Communitygithub.com

Xylem

Mapeie um repositório da arquitetura até funções nomeadas e decisões selecionadas, trace jornadas de usuário com escopo definido, verifique o mapa contra o código-fonte e construa um site estático interativo (Explore, Jornadas, Mapa de Estados, Código). Use quando alguém pedir para visualizar, mapear, explicar ou auditar a arquitetura, fluxos, jornadas de UX ou caminhos de código de um repositório, ou quiser 'o aplicativo inteiro em uma página'.

O que é Xylem?

Xylem transforma um repositório de código em um mapa interativo e fundamentado no código-fonte, composto por quatro visualizações em um site estático de dois arquivos (`index.html` e `deep-view.json`). Ele foi projetado para desenvolvedores, arquitetos de software e engenheiros de IA que precisam visualizar, documentar ou auditar a arquitetura de um sistema, seus fluxos de usuário e caminhos de código. O método é rigoroso: cada componente, conexão, decisão e estado deve ser evidenciado com referência a arquivo e linha (`file:line`), evitando suposições e marcando lacunas com `UNVERIFIED` ou `unavailable`. O processo é dividido em seis fases principais: Censo (inventário determinístico de definições), Arquitetura (camadas, componentes e conexões), Jornadas e Estados (mapeamento de jornadas do usuário e máquinas de estado), Mapa em Nível de Função (decisões, chamadas e rastreamentos), Construção da Página (site estático offline) e Revisão Cruzada (revisão independente para garantir precisão). Xylem é compatível com repositórios em várias linguagens (usando AST Python para Python, token walker JS/TS para JavaScript/TypeScript e regex para outras linguagens), e todos os scripts são executados apenas com a biblioteca padrão do Python 3.9+. A ferramenta é somente leitura (nunca modifica o repositório alvo) e respeita a privacidade (não envia dados para serviços externos).

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Iineman2/xylem/tree/HEAD/skills/xylem

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Xylem faz?

Você transformará um repositório em um mapa fundamentado no código-fonte. Ele possui quatro visualizações, em um site estático de dois arquivos (index.html e deep-view.json):

VisualizaçãoMostra
ExplorarComponentes (as partes do sistema) e as conexões entre eles, agrupados em camadas
Jornadas do clienteCada jornada que um usuário pode realizar, animada sobre a arquitetura: requisições, respostas e entregas (hand-offs) rotuladas
Mapa de estadosToda dimensão de estado declarada no escopo mapeado, seus estados e as transições que as jornadas realmente realizam
CódigoCada função mapeada como um bloco em sua região, com suas decisões, chamadas e chamadores, e caminhos de jornada traçados no nível da função

O método importa mais do que a página. Cada afirmação está vinculada a arquivo:linha. Cada conexão é real. Onde o código não pode resolver algo, o mapa declara isso em vez de adivinhar.

Regras básicas (aplicam-se em todas as fases)

  1. Evidência ou nada. Cada componente, unidade, decisão, aresta, estado e ação deve citar arquivo:linha. Se não puder citá-lo, marque-o como UNVERIFIED ou omita-o. Esta é uma obrigação do autor/revisor: as portas automatizadas garantem evidências de arquitetura e localizações profundas no código-fonte, não cada citação de estado/ação ou significado da explicação.
  2. Atribuir IDs; nunca inventar entidades ou conexões. Use os IDs de posição de arquivo do scaffold; IDs criados manualmente também devem ser únicos e estáveis. Arestas entre regiões devem percorrer uma conexão de arquitetura declarada. Se uma estiver faltando, registre um diagram_gap e verifique-o no código antes de adicioná-lo, com evidência.
  3. Lacunas honestas são melhores que caminhos impossíveis. Se o resultado de uma jornada não puder ser rastreado distintamente a partir da fonte, escreva {"unavailable": "<motivo específico>"}. Nunca copie o caminho de sucesso em um resultado de falha. Nunca encadeie ramificações que não possam ser ambas verdadeiras.
  4. Diga o que é. Os rastreamentos são caminhos estáticos de código-fonte, não gravações de execuções reais. Rotule-os dessa forma na página.
  5. Somente leitura. Nunca edite o repositório alvo. Escreva tudo em .xylem/ (ou uma pasta que o usuário nomear).
  6. Privacidade. Não envie conteúdo do repositório para nenhum serviço externo, a menos que o usuário solicite. O site faz apenas requisições de mesma origem para seus dados e vídeos opcionais. Ele não faz requisições externas; sirva-o em loopback para uso offline.

Estrutura de saída

.xylem/
  census.json        # cada definição encontrada no código (scripts/census.py)
  architecture.json  # fase 1
  journeys.json      # fase 2
  deep.json          # fase 3 (mapa em nível de função)
  validation.json    # saída do scripts/validate.py
  reviews/           # relatórios de revisão cruzada (fase 6)
  site/              # index.html + deep-view.json (+ vídeos/)   (scripts/build_site.py)

Os formatos para cada arquivo estão em references/schemas.md. Leia-o antes de escrever qualquer JSON.

Fases e portas

Execute as fases em ordem. Cada fase termina com uma porta. Não prossiga até que a porta seja aprovada, ou o usuário aceite uma lacuna documentada. Em uma avaliação explicitamente autorizada, retenha artefatos com falha e logs inalterados e continue apenas dentro do escopo dessa avaliação; rotule as saídas subsequentes como provisórias. Uma aprovação estrutural não estabelece cobertura semântica completa.

Fase 0: Censo (determinístico)

python scripts/census.py <repo> --out .xylem/census.json [--exclude dir ...]

Isso inventaria definições nomeadas com AST Python, um token walker JS/TS da biblioteca padrão e regex aproximados para outras linguagens suportadas. scannedFiles inclui arquivos-fonte com zero definições. JS/TS cobre arrows genéricas, métodos concretos multilinha/computados, assinaturas de sobrecarga, proprietários lexicais de função/classe, literais regex e interpolações de template; callbacks anônimos não são unidades de censo. É um inventário medido, não uma prova de toda a sintaxe da linguagem. Qualifique-o com um parser independente ou amostra de fonte antes de reivindicar completude. Percentagens posteriores descrevem apenas este inventário.

Porta: as contagens do censo parecem plausíveis em relação ao tamanho do repositório. Caminhos excluídos são justificados, por exemplo, código gerado ou node_modules.

Fase 1: Arquitetura

Leia os pontos de entrada, arquivos de build, módulos principais e limites de processo. Em seguida, escreva architecture.json:

  • camadas: por exemplo, shell, UI, servidor, domínio, armazenamento, workers, externo;
  • componentes: cada um com id, layer, files[], uma responsabilidade simples e processType;
  • conexões: cada {from, to, label, kind}, onde kind é spawn, ipc, http, file, data ou uses;
  • fluxos: os principais fluxos ponta a ponta como etapas ordenadas de componentes.

Porta: python scripts/validate.py .xylem --only architecture passa. Cada entrada de scannedFiles pertence a um componente, ou tem uma entrada architecture.meta.fileExclusions justificada. Os caminhos e linhas de evidência devem existir sob a raiz de evidência.

Fase 2: Jornadas e estados

Escreva journeys.json. Deduza-os a partir da UI, rotas, comandos CLI, jobs e caminhos de erro:

  • stateDimensions: cada máquina de estado independente;
  • screens: cada tela;
  • actions: cada ação do usuário e transição do sistema, com seus resultados, o texto exato que o usuário vê e desfazer;
  • journeys: estados iniciais mais etapas.

Cada ação carrega um rastreamento de arquitetura ordenado (alternando componente e conexão). As pernas de retorno usam {"connection": [a, b], "direction": "reply"}. Quando a próxima etapa não começa onde a última terminou, a etapa carrega transition.handoff, com um tipo e rótulo: user, timer, queue, continuation, lifecycle ou download. Cubra jornadas felizes, infelizes, de recuperação e de borda.

Porta: validate.py --only journeys passa:

  • cada jornada é reproduzida através de resultados válidos;
  • zero saltos silenciosos (cada acendimento é alcançado por um fio, uma resposta ou uma entrega (hand-off) rotulada);
  • nenhum estado órfão.

Fase 3: Mapa em nível de função (resolução final)

  1. Gere um mapa preliminar a partir do censo:
python scripts/scaffold_deep.py .xylem

Ele escreve deep.json. O rascunho contém unidades de censo atribuídas, decisões Python de AST e pontos heurísticos JS/TS if, while, for, switch e catch entre parênteses. JS/TS não reivindica um inventário completo de ternários, cálculos ou decisões de curto-circuito. Comentários, conteúdos literais e declarações filhas são excluídos de cada corpo. Chamadas genéricas retêm posições de callsite distintas. Arestas de chamada usam source: heuristic e confidence: name-resolved; nomes não resolvidos não são links inventados. Refine contra a fonte; a resolução de nomes não é resolução de tipos. 2. Refine o rascunho lendo o código:

  • summary legível para negócios por unidade, escrito a partir do corpo, não do nome;
  • para cada decisão, uma pergunta plain ("Este arquivo é maior que 16 MiB?") mais o test de código exato, um kind (branch, calculation, loop ou unconditional) e sucessores corretos. Um return ou raise encerra o caminho. As continuações normal e de erro de um bloco try são separadas, e uma exceção pendente executa finally e depois propaga. Quando estiver em dúvida, marque o sucessor como unresolved; nunca verified;
  • tags risk apenas em decisões que implementam diretamente um defeito conhecido.
  1. Escreva actionTraces: para cada ação de jornada e resultado, os eventos de execução ordenados {component, unit, event, decision?, line, note?, callsite?, returnTo?, precondition?, boundary?}.
    • event é um de call, return, branch, async, spawn, ipc, http, file, render, unknown, throw, finally ou resume. Veja os esquemas para frames de ativação, eventos terminais e limites de reprodução suportados.
    • Comece no iniciador real, como um handler de UI, rota ou job.
    • Siga chamadas, retornos e limites de processo. Uma recusa deve seguir o caminho de erro real de volta ao usuário. Nunca deve continuar para "saved" ou "success".
    • Onde o caminho é incognoscível, emita {"event": "unknown", "note": "..."}, ou marque todo o resultado como unavailable.

Repositórios grandes: divida a fase 3 por área de código entre vários agentes, cada um escrevendo deep-<parte>.json no mesmo formato, depois mescle-os com scripts/merge_deep.py. Reconcilie IDs por arquivo e linha de definição, nunca por similaridade de nome.

Porta: validate.py passa o conjunto completo:

  • cada definição do censo emitida ou explicitamente excluída com um motivo; a cobertura emitida e a contabilidade de exclusão são contadores separados;
  • cada endpoint de aresta é resolvido;
  • cada aresta entre regiões percorre uma conexão;
  • sucessores de decisão são resolvidos;
  • referências de rastreamento são válidas;
  • consistência do seletor: nenhuma ativação assume escolhas mutuamente exclusivas para valores inalterados. Escritas na fonte podem alterar um valor; um rótulo de iteração sozinho não pode redefinir restrições. Gramática e limites suportados estão no esquema. Por exemplo, x==='a' sim e depois x==='b' sim, ou um valor excluído e depois exigido por includes(). Corrija o rastreamento ou retire-o para unavailable, nomeando o conflito.

Fase 4: Construir a página

python scripts/build_site.py .xylem

Isso escreve site/index.html e site/deep-view.json. Vídeos são opcionais: coloque videos/<journeyId>.mp4 mais videos/manifest.json em .xylem/ primeiro (veja os esquemas). Sirva site/ via HTTP para visualizá-lo, por exemplo python -m http.server -d .xylem/site. Uma página file:// não pode carregar os dados da visualização Código.

Porta: abra a página e verifique cada modo uma vez:

  • nenhum erro no console;
  • largura de telefone (420 px) sem rolagem horizontal;
  • teclado e modo escuro funcionam.

Fase 5: Gravações opcionais de tela real

Se o aplicativo tiver uma UI que você possa executar localmente, grave jornadas com Playwright. Um iniciador é scripts/record_journey.example.mjs. Regras para gravações:

  • dirija a UI real, sem respostas simuladas;
  • adicione uma legenda por etapa;
  • acelere esperas ociosas e legendas a aceleração;
  • grave atSec por etapa em manifest.json;
  • marque gravações parciais como parciais.

O visualizador sincroniza um vídeo com o mapa, então o vídeo se torna o relógio.

Fase 6: Conselho de revisão cruzada

Use dois revisores independentes quando possível: dois modelos ou agentes diferentes, ou pelo menos um contexto novo sem acesso ao raciocínio do autor. Siga references/protocol.md:

  • o autor nunca avalia seu próprio trabalho;
  • o revisor recebe arquivos e código, nunca as conclusões do autor;
  • o revisor executa o verificador independente e amostra afirmações contra a fonte: a única regra de amostragem em protocol.md (todos os itens disponíveis abaixo de seus mínimos);
  • as descobertas vão para reviews/<revisor>-<rodada>.md com gravidade, evidência e uma correção concreta;
  • porta de aceitação: um ACCEPT, REJECT ou BLOCKED explícito para arquitetura, jornadas, profundo, página/dados e o pacote congelado. Apenas defeitos materiais justificam REJECT: uma conclusão errada, um caminho impossível ou uma tarefa central bloqueada. Limites declarados, marcadores unavailable honestos e a natureza estática dos rastreamentos não são motivos para rejeição;
  • use um orçamento de revisão limitado; pare com REJECT/BLOCKED e evidência retida se não resolvido. Reavalie o artefato construído exato, não uma descrição dele.

Porta: todos os artefatos do pacote congelado são aceitos por revisão independente. Nunca fabrique caminhos para atender a uma cota de amostragem.

Fase 7: Publicar e relatar

Informe ao usuário o que está na página, com contagens reais:

  • funções, decisões, jornadas e resultados rastreados;
  • quantos resultados estão unavailable e por quê;
  • o que foi revisado cruzadamente.

Relate os limites claramente.

Scripts

ScriptPropósito
census.pyCenso de definições em várias linguagens (o denominador de cobertura)
scaffold_deep.pyMapa preliminar em nível de função a partir do censo e da arquitetura
merge_deep.pyMesclar mapas de partes; reconciliar IDs por arquivo e linha
validate.pyCada porta: esquema, referências, cobertura, saltos silenciosos, sucessores, consistência do seletor
build_site.pyExportar os dados compactos da visualização Código e construir o site de página única
record_journey.example.mjsIniciador Playwright para vídeos de jornada em tela real

Os scripts Python requerem Python 3.9+ e apenas a biblioteca padrão. Os helpers .mjs opcionais de navegador/gravação requerem um Playwright disponível separadamente. A página não usa frameworks ou requisições externas.

Habilidades Relacionadas