migrate-to-shoehorn

Visão geral da skill migrate-to-shoehorn

A skill migrate-to-shoehorn ajuda você a refatorar código de teste em TypeScript, saindo de assertions frágeis com as e migrando para @total-typescript/shoehorn. Ela é mais indicada para quem já tem testes cheios de as Type ou as unknown as Type, especialmente quando objetos grandes deixam o setup barulhento e enganoso.

Para que serve migrate-to-shoehorn

Use migrate-to-shoehorn quando sua necessidade real não for “aprender uma biblioteca”, mas sim limpar fixtures de teste inseguras sem reescrever a suíte inteira. A skill é centrada em uma tarefa de refatoração bem específica:

• trocar as Type por fromPartial()
• trocar as unknown as Type por fromAny()
• reduzir boilerplate fake em objetos de entrada grandes nos testes

Quem deve instalar esta skill

Esta migrate-to-shoehorn skill é uma ótima escolha se você:

• mantém testes TypeScript com muito casting
• quer fixtures parciais mais seguras
• precisa de ajuda para decidir qual padrão de assertion corresponde a qual helper do shoehorn
• quer que um agente execute ou conduza uma refatoração direcionada, em vez de dar conselhos genéricos de TypeScript

O que mais importa antes de adotar

O principal ponto de decisão é o escopo: esta skill é explicitamente voltada para testes, não para código de produção. Isso importa porque shoehorn é útil quando você quer, de propósito, usar dados incompletos ou até inválidos para dirigir casos de teste, mas ainda assim quer uma tipagem mais clara e intencional do que assertions cruas.

Por que usar migrate-to-shoehorn em vez de um prompt genérico de refatoração

Um prompt genérico pode remover as de forma mecânica e perder a intenção do teste. migrate-to-shoehorn é mais útil porque foi ajustada para os padrões de migração que desenvolvedores realmente encontram na prática:

• entradas parciais de teste para tipos de objeto grandes
• dados propositalmente inválidos em testes negativos
• redução de propriedades fake que não são relevantes para o teste

Esse foco mais estreito normalmente significa menos adivinhação e menos substituições inseguras.

Como usar a skill migrate-to-shoehorn

Contexto de instalação da skill migrate-to-shoehorn

Para usar a biblioteca base no seu projeto, instale:

npm i @total-typescript/shoehorn

Se você estiver instalando a skill em um ambiente com suporte a skills, use o fluxo normal de instalação da sua plataforma e depois invoque migrate-to-shoehorn ao trabalhar em refatorações de testes.

Leia este arquivo primeiro

Comece por SKILL.md na pasta migrate-to-shoehorn. Neste repositório, essa é a principal fonte de verdade e contém os padrões de migração que orientam a skill.

Ordem de leitura sugerida:

1. migrate-to-shoehorn/SKILL.md
2. os arquivos de teste que você quer alterar
3. seus usos locais de as Type e as unknown as Type

Que entrada a skill precisa

A skill funciona melhor quando você fornece:

• o trecho atual do teste
• a função ou o componente de destino que está sendo chamado
• o nome do tipo relevante, se souber
• se os dados do teste devem ser válidos ou intencionalmente inválidos
• se você quer uma correção pontual ou um padrão de migração reaplicável

Sem esse contexto, um agente ainda pode sugerir fromPartial() ou fromAny(), mas pode escolher o helper errado.

Padrões principais de migração para pedir

Os padrões práticos de migrate-to-shoehorn usage são simples:

• as Type → normalmente fromPartial()
• as unknown as Type → normalmente fromAny()
• objeto fake enorme em que só alguns campos importam → fromPartial()

Esse é o valor central da skill: ela transforma pedidos vagos como “limpe estes casts de teste” em uma abordagem de refatoração consistente.

Como escrever um bom prompt para migrate-to-shoehorn

Um prompt fraco:

Replace as with shoehorn.

Um prompt mais forte:

Use the migrate-to-shoehorn skill to refactor this test file. Replace plain as Request casts with fromPartial() where the object is just a partial fixture. Replace as unknown as Request with fromAny() only where the test intentionally passes invalid data. Keep the test behavior unchanged and add imports if needed.

Essa versão dá ao agente intenção, limites e uma regra de decisão.

Exemplo: migração de fixture parcial

Antes:

getUser({ body: { id: "123" } } as Request);

Depois:

import { fromPartial } from "@total-typescript/shoehorn";

getUser(fromPartial({ body: { id: "123" } }));

Use isso quando a fixture estiver estruturalmente incompleta, mas ainda fizer sentido conceitualmente para o teste.

Exemplo: migração de dados intencionalmente errados

Antes:

getUser({ body: { id: 123 } } as unknown as Request);

Depois:

import { fromAny } from "@total-typescript/shoehorn";

getUser(fromAny({ body: { id: 123 } }));

Use isso quando o teste estiver deliberadamente passando dados inválidos para exercitar validação ou caminhos de falha.

Melhor fluxo de trabalho para refatorações maiores

Para um migrate-to-shoehorn guide aplicado ao repositório inteiro, não reescreva tudo em lote às cegas. Um fluxo mais seguro é:

1. procurar nos arquivos de teste por as e as unknown as
2. classificar os casts entre parcial-válido e intencionalmente-inválido
3. migrar primeiro uma pasta de testes
4. rodar testes e typecheck
5. padronizar estilo de import e escolha de helper
6. só então escalar para o restante da suíte

Isso evita misturar casts legítimos de testes negativos com limpeza comum de fixtures.

Dicas práticas que melhoram a qualidade da saída

Peça ao agente para preservar estes detalhes:

• nomes de teste e assertions já existentes
• intenção semântica dos testes com entrada inválida
• shape mínimo da fixture, em vez de objetos fake totalmente expandidos
• deduplicação de imports quando vários helpers forem usados

Também deixe claro se você quer que a skill prefira a menor fixture possível. Isso normalmente produz a refatoração com shoehorn mais limpa.

Quando migrate-to-shoehorn é a ferramenta errada

Não use migrate-to-shoehorn for Refactoring se seu problema real for segurança de tipos em produção, modelagem de domínio ou correção de contratos de API. Esta skill não foi feita para “consertar” tipos em todo lugar. Ela é um auxílio focado em refatoração de testes.

FAQ da skill migrate-to-shoehorn

migrate-to-shoehorn é só para testes?

Sim. Esse é o limite mais importante. A skill foi desenhada em torno de ergonomia de testes e intenção de teste, não de padrões de tipagem em produção.

Preciso de shoehorn se meus testes já passam?

Não necessariamente. Instale migrate-to-shoehorn se seus testes atuais são difíceis de ler, estão cheios de objetos fake barulhentos ou dependem de casts inseguros que escondem a intenção. Se o setup de testes já estiver limpo, talvez a migração não valha a pena.

Qual é a diferença entre fromPartial e fromAny?

fromPartial() serve para dados de fixture incompletos, mas ainda coerentes para o contexto.
fromAny() serve para dados intencionalmente inválidos, quando o teste precisa contornar uma tipagem mais rígida para simular uma entrada ruim em runtime.

Essa distinção é um dos principais motivos para usar a skill em vez de um prompt amplo de “remover assertions”.

migrate-to-shoehorn é amigável para iniciantes?

Sim, desde que você já entenda o básico de testes em TypeScript. O escopo da skill é pequeno, e as regras de migração são fáceis de seguir. O principal risco para iniciantes é exagerar no uso de shoehorn fora dos testes.

Posso usar esta skill para migrar um repositório inteiro?

Sim, mas apenas se você revisar categoria por categoria. O maior modo de falha em migrações grandes é tratar todos os casts como se fossem equivalentes. Alguns são fixtures parciais; alguns são payloads propositalmente quebrados; alguns podem pertencer ao código de produção e não devem ser migrados com esse padrão.

Isso é melhor do que prompting comum?

Na maioria dos casos, sim, quando a tarefa é especificamente “migrar assertions de teste para shoehorn”. Prompts comuns podem conhecer a biblioteca, mas migrate-to-shoehorn usage funciona melhor quando você quer um mapeamento consistente do estilo antigo de cast para o helper correto.

Como melhorar a skill migrate-to-shoehorn

Dê ao agente a intenção do teste, não só o código

A forma mais rápida de melhorar os resultados de migrate-to-shoehorn é dizer se cada teste está verificando:

• comportamento de happy path com setup parcial
• falha de validação com entrada intencionalmente errada
• edge cases que precisam de apenas alguns campos

Esse único contexto muitas vezes define fromPartial() versus fromAny().

Marque os arquivos como somente teste logo de início

Se um arquivo mistura código helper e código de produção, diga isso explicitamente. A skill é muito mais segura quando você informa ao agente:

Only apply migrate-to-shoehorn changes inside test files and test fixtures.

Isso evita que a mudança se espalhe por engano para caminhos que não são de teste.

Peça um inventário dos casts antes de mudar anything

Para suítes bagunçadas, comece com:

Using the migrate-to-shoehorn skill, classify each cast in this file as fromPartial, fromAny, or leave unchanged, then explain why.

Esse passo de revisar antes de reescrever ajuda a capturar edge cases antes da mudança real.

Forneça os tipos próximos quando a inferência não estiver clara

Se o trecho isolado não mostrar qual é o tipo esperado, inclua a assinatura da função ou a definição de tipo relevante. Um contexto de tipos mais forte leva a escolhas melhores de import e a menos reescritas esquisitas.

Fique atento a estes modos de falha comuns

Problemas comuns durante migrate-to-shoehorn install e adoção incluem:

• usar shoehorn em código de produção
• converter dados intencionalmente inválidos para fromPartial()
• expandir objetos de fixture em vez de simplificá-los
• alterar o significado do teste ao “limpar” os tipos

Esses não são problemas da biblioteca; são problemas de prompt e revisão.

Itere sobre a primeira saída

Depois da primeira passada, peça um segundo refinamento, por exemplo:

• minimizar cada fixture para conter apenas os campos exigidos pelo teste
• consolidar imports
• explicar quaisquer casts restantes que devam permanecer
• separar dados parciais válidos de dados de teste inválidos

Isso transforma uma migração básica em um padrão de testes mais limpo e sustentável no longo prazo.