migrate-to-shoehorn

Vue d’ensemble de la skill migrate-to-shoehorn

La skill migrate-to-shoehorn vous aide à refactorer du code de test TypeScript pour abandonner les assertions as fragiles au profit de @total-typescript/shoehorn. Elle convient particulièrement aux développeurs qui ont déjà des tests remplis de as Type ou de as unknown as Type, surtout lorsque de gros objets rendent la préparation des tests verbeuse et trompeuse.

À quoi sert migrate-to-shoehorn

Utilisez migrate-to-shoehorn si votre vrai besoin n’est pas de « découvrir une librairie », mais de nettoyer des fixtures de test peu sûres sans réécrire toute la suite de tests. La skill est centrée sur une tâche de refactorisation précise :

• remplacer as Type par fromPartial()
• remplacer as unknown as Type par fromAny()
• réduire le boilerplate factice autour de gros objets d’entrée dans les tests

Qui devrait installer cette skill

Cette migrate-to-shoehorn skill est particulièrement adaptée si vous :

• maintenez des tests TypeScript avec beaucoup de cast
• voulez des fixtures partielles plus sûres
• avez besoin d’aide pour déterminer quel pattern d’assertion correspond à quel helper shoehorn
• voulez qu’un agent réalise ou guide une refactorisation ciblée au lieu de fournir des conseils TypeScript génériques

Ce qu’il faut vérifier avant de l’adopter

Le point de décision principal, c’est le périmètre : cette skill vise explicitement les tests, pas le code de production. C’est important, car shoehorn est utile quand vous voulez volontairement injecter des données incomplètes, voire invalides, dans des cas de test, tout en gardant un typage plus clair et plus intentionnel que de simples assertions brutes.

Pourquoi utiliser migrate-to-shoehorn plutôt qu’un prompt de refactor générique

Un prompt générique peut supprimer as de façon mécanique sans comprendre l’intention. migrate-to-shoehorn est plus utile parce qu’il est calibré sur les schémas de migration concrets que les développeurs rencontrent réellement :

• des entrées de test partielles pour de grands types d’objet
• des données volontairement incorrectes dans des tests négatifs
• la suppression de propriétés factices sans intérêt pour le test

Avec ce cadrage plus étroit, on obtient généralement moins d’approximations et moins de remplacements hasardeux.

Comment utiliser la skill migrate-to-shoehorn

Contexte d’installation pour la skill migrate-to-shoehorn

Pour utiliser la librairie sous-jacente dans votre projet, installez :

npm i @total-typescript/shoehorn

Si vous installez la skill dans un environnement compatible avec les skills, suivez le flux d’installation habituel de votre plateforme, puis invoquez migrate-to-shoehorn lorsque vous travaillez sur des refactors de tests.

Commencez par lire ce fichier

Commencez par SKILL.md dans le dossier migrate-to-shoehorn. Dans ce dépôt, c’est la source de vérité principale, et c’est là que se trouvent les patterns de migration qui pilotent la skill.

Ordre de lecture conseillé :

1. migrate-to-shoehorn/SKILL.md
2. les fichiers de test que vous voulez modifier
3. vos usages locaux de as Type et as unknown as Type

Quelles entrées fournir à la skill

La skill fonctionne mieux si vous fournissez :

• le snippet de test actuel
• la fonction ou le composant cible appelé
• le nom du type concerné, si vous le connaissez
• si les données de test sont censées être valides ou volontairement invalides
• si vous voulez un correctif ponctuel ou un pattern de migration réutilisable

Sans ce contexte, un agent peut quand même suggérer fromPartial() ou fromAny(), mais il risque de choisir le mauvais helper.

Les principaux patterns de migration migrate-to-shoehorn à demander

Les patterns pratiques de migrate-to-shoehorn usage sont simples :

• as Type → en général fromPartial()
• as unknown as Type → en général fromAny()
• gros objet factice dont seuls quelques champs comptent → fromPartial()

C’est là la valeur centrale de la skill : elle transforme une demande vague du type « nettoie ces casts de test » en une approche de refactorisation cohérente.

Comment rédiger un bon prompt migrate-to-shoehorn

Un prompt faible :

Replace as with shoehorn.

Un prompt plus solide :

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.

Cette version donne à l’agent l’intention, les limites et une règle de décision.

Exemple : migration d’une fixture partielle

Avant :

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

Après :

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

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

À utiliser lorsque la fixture est structurellement incomplète, mais reste conceptuellement valide pour le test.

Exemple : migration de données volontairement incorrectes

Avant :

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

Après :

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

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

À utiliser lorsque le test passe délibérément des données invalides pour exercer la validation ou les chemins d’échec.

Meilleur workflow pour des refactors migrate-to-shoehorn plus larges

Pour un migrate-to-shoehorn guide à l’échelle du dépôt, n’appliquez pas une réécriture massive à l’aveugle. Un workflow plus sûr consiste à :

1. rechercher as et as unknown as dans les fichiers de test
2. classer les casts entre partiel-valide et intentionnellement-invalide
3. migrer d’abord un seul dossier de tests
4. lancer les tests et le typecheck
5. standardiser le style d’import et le choix des helpers
6. puis étendre au reste de la suite

Cela évite de mélanger les casts légitimes des tests négatifs avec le simple nettoyage de fixtures ordinaires.

Conseils pratiques pour améliorer la qualité du résultat

Demandez à l’agent de préserver les éléments suivants :

• les noms de test et assertions existants
• l’intention sémantique des tests d’entrée invalide
• une fixture minimale plutôt qu’un faux objet entièrement développé
• la déduplication des imports si plusieurs helpers sont utilisés

Indiquez aussi clairement si vous voulez que la skill privilégie la plus petite fixture possible. C’est généralement ce qui produit le refactor shoehorn le plus propre.

Quand migrate-to-shoehorn n’est pas le bon outil

N’utilisez pas migrate-to-shoehorn for Refactoring si votre vrai problème concerne la sûreté des types en production, la modélisation métier ou la justesse du contrat d’API. Cette skill n’a pas vocation à « corriger » les types partout. C’est un outil ciblé de refactorisation de tests.

FAQ sur la skill migrate-to-shoehorn

migrate-to-shoehorn est-il réservé aux tests ?

Oui. C’est sa limite la plus importante. La skill est pensée autour de l’ergonomie des tests et de leur intention, pas autour des patterns de typage en production.

Ai-je besoin de shoehorn si mes tests passent déjà ?

Pas forcément. Installez migrate-to-shoehorn si vos tests actuels sont difficiles à lire, encombrés de faux objets verbeux, ou s’appuient sur des casts peu sûrs qui masquent l’intention. Si votre mise en place de tests est déjà propre, la migration ne vaut peut-être pas l’effort.

Quelle est la différence entre fromPartial et fromAny ?

fromPartial() convient à des données de fixture incomplètes mais globalement cohérentes.
fromAny() convient à des données volontairement invalides, lorsque le test doit contourner un typage plus strict pour simuler une mauvaise entrée à l’exécution.

Cette distinction est l’une des principales raisons d’utiliser la skill plutôt qu’un prompt large du type « supprimer les assertions ».

La skill migrate-to-shoehorn est-elle adaptée aux débutants ?

Oui, à condition de déjà comprendre les bases des tests TypeScript. Le périmètre de la skill est réduit et les règles de migration sont simples à suivre. Le principal risque pour un débutant est de surutiliser shoehorn en dehors des tests.

Puis-je utiliser cette skill pour migrer tout un dépôt ?

Oui, mais seulement si vous passez catégorie par catégorie. Le principal mode d’échec dans les grosses migrations consiste à traiter tous les casts comme s’ils étaient équivalents. Certains correspondent à des fixtures partielles, d’autres à des payloads volontairement cassés, et certains appartiennent peut-être au code de production : ils ne doivent alors pas être migrés selon ce pattern.

Est-ce vraiment mieux qu’un prompt classique ?

En général, oui, quand la tâche est précisément « migrer des assertions de test vers shoehorn ». Les prompts ordinaires peuvent connaître la librairie, mais migrate-to-shoehorn usage est préférable si vous voulez une correspondance cohérente entre l’ancien style de cast et le bon helper.

Comment améliorer la skill migrate-to-shoehorn

Donnez à l’agent l’intention du test, pas seulement le code

Le moyen le plus rapide d’améliorer les résultats de migrate-to-shoehorn est de préciser si chaque test vérifie :

• un happy path avec une mise en place partielle
• un échec de validation avec une entrée volontairement incorrecte
• des cas limites qui ne nécessitent que quelques champs

Ce simple élément de contexte suffit souvent à trancher entre fromPartial() et fromAny().

Signalez dès le départ quels fichiers sont uniquement des tests

Si un fichier mélange code utilitaire et code de production, dites-le. La skill est bien plus sûre si vous indiquez explicitement à l’agent :

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

Cela évite qu’elle se propage par erreur à des chemins non liés aux tests.

Demandez un inventaire des casts avant toute modification

Pour des suites de tests désordonnées, commencez par :

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

Cette étape de revue en amont permet de repérer les cas limites avant la réécriture elle-même.

Fournissez les types voisins quand l’inférence n’est pas claire

Si le snippet seul ne montre pas le type attendu, ajoutez la signature de fonction ou la définition de type pertinente. Un contexte de types plus solide conduit à de meilleurs choix d’import et à moins de réécritures maladroites.

Surveillez ces modes d’échec fréquents

Les problèmes courants lors de migrate-to-shoehorn install et de son adoption sont :

• utiliser shoehorn dans du code de production
• convertir des données volontairement invalides en fromPartial()
• développer les objets de fixture au lieu de les simplifier
• changer le sens du test en « nettoyant » les types

Ce ne sont pas des problèmes de librairie ; ce sont des problèmes de prompt et de revue.

Itérez sur le premier résultat

Après un premier passage, demandez un second raffinement, par exemple :

• réduire chaque fixture aux seuls champs nécessaires au test
• regrouper les imports
• expliquer quels casts restants doivent être conservés
• séparer les données partielles valides des données de test invalides

C’est ainsi qu’une migration basique devient un pattern de test plus propre et plus durable.