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ção | Mostra |
|---|---|
| Explorar | Componentes (as partes do sistema) e as conexões entre eles, agrupados em camadas |
| Jornadas do cliente | Cada jornada que um usuário pode realizar, animada sobre a arquitetura: requisições, respostas e entregas (hand-offs) rotuladas |
| Mapa de estados | Toda dimensão de estado declarada no escopo mapeado, seus estados e as transições que as jornadas realmente realizam |
| Código | Cada 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)
- 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 comoUNVERIFIEDou 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. - 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_gape verifique-o no código antes de adicioná-lo, com evidência. - 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. - 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.
- Somente leitura. Nunca edite o repositório alvo. Escreva tudo em
.xylem/(ou uma pasta que o usuário nomear). - 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 eprocessType; - conexões: cada
{from, to, label, kind}, ondekindé 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)
- 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:
summarylegí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 otestde código exato, umkind(branch, calculation, loop ou unconditional) e sucessores corretos. Umreturnouraiseencerra o caminho. As continuações normal e de erro de um bloco try são separadas, e uma exceção pendente executafinallye depois propaga. Quando estiver em dúvida, marque o sucessor comounresolved; nuncaverified; - tags
riskapenas em decisões que implementam diretamente um defeito conhecido.
- 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 depoisx==='b'sim, ou um valor excluído e depois exigido porincludes(). Corrija o rastreamento ou retire-o paraunavailable, 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
atSecpor etapa emmanifest.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>.mdcom 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
unavailablehonestos 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
| Script | Propósito |
|---|---|
census.py | Censo de definições em várias linguagens (o denominador de cobertura) |
scaffold_deep.py | Mapa preliminar em nível de função a partir do censo e da arquitetura |
merge_deep.py | Mesclar mapas de partes; reconciliar IDs por arquivo e linha |
validate.py | Cada porta: esquema, referências, cobertura, saltos silenciosos, sucessores, consistência do seletor |
build_site.py | Exportar os dados compactos da visualização Código e construir o site de página única |
record_journey.example.mjs | Iniciador 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.