ramp

Que fait ramp ?

Transformez un sujet dans un dépôt inconnu en une carte interactive : nœuds groupés, arêtes étiquetées, panneau de détail cliquable et parcours numéroté qui trace la séquence d'exécution réelle.

Le pipeline est délibérément divisé. Une passe statique trouve quel code importe, vous décidez ce qu'il signifie, et un moteur de rendu le dessine. Sauter la passe statique et lire librement le dépôt est plus lent et manque des fichiers ; sauter votre passe produit un graphe d'appel dont personne n'apprend rien.

Flux de travail

1. Scanner

node ~/.claude/skills/ramp/scripts/scan.js <repo> --topic "<sujet>" --max 30 --out /tmp/scan.json

Les chemins sont absolus car vous exécuterez depuis le dépôt cible, pas depuis ici.

Exécutez-le d'abord sans --topic si vous ne connaissez pas encore la forme du dépôt — cela affiche un aperçu avec le mélange de langages, les plus grands répertoires et les fichiers les plus importés (hubs), ce qui suffit généralement pour choisir un bon sujet.

Le scan du sujet retourne des nodes classés (fichiers, avec score, termes matched et defs extraits) ainsi que les edges entre eux. seed: true marque une correspondance directe avec le sujet ; les autres sont arrivés par expansion du graphe et sont les appelants et appelés qui complètent le tableau.

S'il ne retourne rien, les termes du sujet n'apparaissent pas dans le code. Essayez le vocabulaire utilisé par le codebase plutôt que le vocabulaire utilisé par l'utilisateur.

2. Lire

Lisez les fichiers seeds et tout nœud étendu dont le nom est suggestif. Lisez-les correctement — toute la valeur de la carte réside dans l'explication, et vous ne pouvez pas écrire un detail utile à partir d'une simple liste de fichiers.

Pendant la lecture, cherchez spécifiquement :

• le point d'entrée — où ce flux commence-t-il à l'exécution ?
• le non évident — la garde qui empêche un bug, le flag de configuration qui fait le vrai travail, ce qui surprendrait un nouveau venu
• la séquence réelle — ce qui appelle quoi, dans quel ordre, à l'exécution

3. Modéliser

Écrivez un modèle JSON (schéma ci-dessous). C'est la partie qui nécessite du jugement.

4. Rendre

node ~/.claude/skills/ramp/scripts/render.js /tmp/model.json -o /tmp/<repo>-<sujet>.html

Il valide strictement et refuse de rendre un modèle cassé — identifiants de nœuds inconnus dans les arêtes, identifiants en double, références de parcours pendantes. Les avertissements concernant les nœuds inexpliqués ou orphelins valent la peine d'être corrigés plutôt qu'ignorés.

5. Publier

Publiez le fichier rendu avec l'outil Artifact et donnez le lien à l'utilisateur. Ne chargez pas artifact-design d'abord — le modèle est déjà conçu ; publiez-le tel quel.

Schéma du modèle

{
  "title": "Flux de connexion",
  "repo": "mon-app",
  "summary": "Une ou deux phrases : la forme de la chose, et le seul fait le plus utile à son sujet.",
  "groups": [{ "id": "boot", "label": "Démarrage de l'app", "hint": "infobulle optionnelle" }],
  "nodes": [{
    "id": "provider",
    "label": "AuthProvider",
    "group": "provider",
    "role": "Possède l'état de session",
    "detail": "Le paragraphe dont un nouveau venu a vraiment besoin.",
    "files": ["src/context/AuthContext.jsx:12"],
    "symbols": ["AuthProvider", "signInWithGoogle"]
  }],
  "edges": [{ "from": "provider", "to": "supabase", "label": "getSession, OAuth" }],
  "walkthrough": [{ "node": "provider", "text": "Ce qui se passe à cette étape." }]
}

Les groups sont des colonnes, de gauche à droite, dans l'ordre des dépendances — les points d'entrée à gauche, les primitives à droite. Les arêtes sont dessinées de l'importateur vers l'importé, donc un modèle dont les groupes suivent cet ordre se dispose proprement. Jusqu'à six groupes obtiennent des couleurs distinctes.

walkthrough est optionnel mais c'est la fonctionnalité qui enseigne. Ordonnez-le par séquence d'exécution, pas par structure de fichiers. Un nœud peut apparaître plusieurs fois — les flux bouclent, et le montrer est le but.

Ce qui distingue une bonne carte d'une carte inutile

Les nœuds sont des concepts, pas des fichiers. Deux fichiers qui sont une seule idée (AuthContext.jsx + AuthContextValue.js) peuvent être un seul nœud ; un fichier contenant deux responsabilités non liées peut en être deux. Mettez chaque vrai fichier dans files quoi qu'il arrive.

6–14 nœuds. Une carte avec 40 nœuds est la pelote de poils que l'utilisateur regardait déjà. Coupez pour ne garder que ce qui porte le flux — l'ordre de score du scan vous dit quoi garder. Dites ce que vous avez laissé de côté dans le summary.

role est un travail, pas une reformulation. "Possède l'état de session" — pas "Composant fournisseur d'authentification".

detail mérite le clic. Mettez ce qui n'est pas évident d'après le nom : pourquoi c'est divisé ainsi, le flag qui compte, l'échec que cela évite, l'hypothèse que cela fait. Si un detail ne fait que paraphraser le label, supprimez le nœud ou découvrez ce qu'il fait vraiment.

Étiquetez chaque arête avec la relation réelle — "gates on user", "getSession, OAuth" — pas "utilise" ou "importe".

Citez des lignes. path/to/file.ts:42 dans files pointe le lecteur à l'endroit exact.

Dites ce qui est critique et ce qui ne l'est pas. Un nouveau venu a surtout besoin de savoir quelles parties il peut ignorer.

Remarques

• Le scan est Node sans dépendances et ne nécessite aucune installation. Il respecte .gitignore lorsque la cible est un dépôt git.
• Swift et Java/C# dans le même package n'ont pas d'imports au niveau fichier ; pour ceux-ci, le scan infère les arêtes à partir de références de types uniques à la place. Considérez ces arêtes comme de fortes indications plutôt que des certitudes.
• La résolution des imports est basée sur des expressions régulières, pas sur un vérificateur de types. Elle résout les chemins relatifs, les alias du bundler (@/), et les spécificateurs de style package par suffixe de chemin. Les imports dynamiques et générés sont manqués — si un fichier que vous attendez est absent, ajoutez-le vous-même au modèle.