ramp — Mapa interativo de tópicos em código desconhecido

ramp

Transforme um tópico em um repositório desconhecido em um mapa interativo: nós agrupados, arestas rotuladas, um painel de detalhes clicável e um passo a passo numerado que traça a sequência real de execução.

O pipeline é deliberadamente dividido. Uma passagem estática descobre quais partes do código importam, você decide o que significam e um renderizador desenha o mapa. Pular a varredura e ler o repositório livremente é mais lento e perde arquivos; pular sua interpretação produz um grafo de chamadas do qual ninguém aprende nada.

Fluxo de trabalho

1. Escanear

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

Os caminhos são absolutos porque você executará a partir do repositório alvo, não daqui.

Execute sem --topic primeiro se você ainda não conhece a estrutura do repositório — isso imprime uma visão geral com a mistura de linguagens, os maiores diretórios e os arquivos mais importados (hubs), o que geralmente é suficiente para escolher um bom tópico.

A varredura por tópico retorna nodes ranqueados (arquivos, com score, termos matched e defs extraídos) mais edges entre eles. seed: true marca uma correspondência direta com o tópico; o restante veio por expansão do grafo e são os chamadores e chamados que completam o quadro.

Se não retornar nada, os termos do tópico não aparecem no código. Tente o vocabulário que o repositório usa, em vez do vocabulário que o usuário usou.

2. Ler

Leia os arquivos seed e qualquer nó expandido com um nome sugestivo. Leia-os adequadamente — o valor total do mapa está na explicação, e você não consegue escrever um detail útil a partir de uma listagem de arquivos.

Ao ler, procure especificamente por:

• o ponto de entrada — onde este fluxo começa em tempo de execução?
• o não óbvio — a guarda que previne um bug, a flag de configuração que faz o trabalho real, a coisa que surpreenderia um novato
• a sequência real — o que chama o quê, em que ordem, em tempo de execução

3. Modelar

Escreva um JSON do modelo (esquema abaixo). Esta é a parte que exige julgamento.

4. Renderizar

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

Ele valida estritamente e se recusa a renderizar um modelo quebrado — IDs de nós desconhecidos em arestas, IDs duplicados, referências órfãs no passo a passo. Avisos sobre nós não explicados ou órfãos valem a pena ser corrigidos, não ignorados.

5. Publicar

Publique o arquivo renderizado com a ferramenta de Artefato e dê ao usuário o link. Não carregue artifact-design primeiro — o template já está projetado; publique-o como está.

Esquema do modelo

{
  "title": "Fluxo de Login",
  "repo": "my-app",
  "summary": "Uma ou duas frases: a forma da coisa, e o fato mais útil sobre ela.",
  "groups": [{ "id": "boot", "label": "Inicialização do App", "hint": "dica opcional" }],
  "nodes": [{
    "id": "provider",
    "label": "AuthProvider",
    "group": "provider",
    "role": "Gerencia estado da sessão",
    "detail": "O parágrafo que um novato realmente precisa.",
    "files": ["src/context/AuthContext.jsx:12"],
    "symbols": ["AuthProvider", "signInWithGoogle"]
  }],
  "edges": [{ "from": "provider", "to": "supabase", "label": "getSession, OAuth" }],
  "walkthrough": [{ "node": "provider", "text": "O que acontece neste passo." }]
}

groups são colunas, da esquerda para a direita, em ordem de dependência — pontos de entrada à esquerda, primitivas à direita. As arestas são desenhadas de quem importa para quem é importado, então um modelo cujos grupos sigam essa ordem se organiza de forma limpa. Até seis grupos recebem cores distintas.

walkthrough é opcional, mas é o recurso que ensina. Ordene-o por sequência de execução, não por estrutura de arquivos. Um nó pode aparecer mais de uma vez — fluxos fazem laços de volta, e mostrar isso é o objetivo.

O que separa um mapa bom de um inútil

Nós são conceitos, não arquivos. Dois arquivos que são uma ideia (AuthContext.jsx + AuthContextValue.js) podem ser um nó; um arquivo que contém duas responsabilidades não relacionadas pode ser dois. Coloque todos os arquivos reais em files independentemente.

6–14 nós. Um mapa com 40 nós é a bola de pelos que o usuário já estava encarando. Corte para o que carrega o fluxo — a ordenação por score da varredura diz o que manter. Diga o que você deixou de fora no summary.

role é uma função, não uma reafirmação. "Gerencia estado da sessão" — não "Componente provedor de autenticação".

detail merece o clique. Coloque a coisa que não é óbvia pelo nome: por que está dividido assim, a flag que importa, a falha que previne, a suposição que faz. Se um detail apenas parafraseia o rótulo, delete o nó ou descubra o que ele realmente faz.

Rotule cada aresta com o relacionamento real — "bloqueia em usuário", "getSession, OAuth" — não "usa" ou "importa".

Cite linhas. path/to/file.ts:42 em files aponta o leitor para o local exato.

Diga o que é crítico e o que não é. Um novato precisa principalmente saber quais partes podem ser ignoradas.

Notas

• A varredura é Node sem dependências e não precisa de instalação. Ela respeita .gitignore quando o alvo é um repositório git.
• Swift, e Java/C# do mesmo pacote, não têm imports em nível de arquivo; para esses, a varredura infere arestas a partir de referências únicas de tipos. Trate essas arestas como dicas fortes, não certezas.
• A resolução de imports é baseada em regex, não em um verificador de tipos. Ela resolve caminhos relativos, aliases de bundler (@/) e especificadores estilo pacote por sufixo de caminho. Imports dinâmicos e gerados são perdidos — se um arquivo que você espera estiver ausente, adicione-o você mesmo ao modelo.