repoviz

O que repoviz faz?

Transforme uma base de código em URLs de diagrama prontos para renderização. Cada diagrama é uma única URL https://x-cmd.com/draw (parâmetros planos, codificados por porcentagem) que renderiza SVG em navegadores, READMEs do GitHub e qualquer visualizador Markdown. O modo padrão não escreve arquivos locais; a exportação local ocorre apenas mediante solicitação explícita via scripts/.

Renderizar ≠ verdade: cada nó e aresta carrega evidência de origem (verificado / inferido / desconhecido) — a saída é um ativo verificável, não um esboço de IA.

Etapa 1 — Análise de Intenção e Roteamento de Gráfico

Escolha o(s) tipo(s) de diagrama com base na intenção + formato do repositório. Leia apenas o(s) arquivo(s) references/ correspondente(s) antes de construir aquele diagrama.

Intenção do usuário	Diagrama	Referência
Visão geral do sistema, hierarquia de pastas, microsserviços, stack de tecnologia	Mapa de arquitetura (/draw/archmap)	references/architecture.md
Ciclo de vida de requisição, cadeias de chamada de função, handshakes de API	Diagrama de sequência (/draw/seq)	references/flowchart.md
Lógica de ramificação, algoritmos, estágios de autenticação/pipeline	Fluxograma (/draw/mermaid)	references/flowchart.md
Máquinas de estado, status, retry/rollback	Ciclo de vida (/draw/lifecycle)	references/flowchart.md
Pipelines de dados, pesos de dependência/bundle, roteamento de tráfego	Sankey (?type=sankey)	references/sankey.md
Árvores de funcionalidades, taxonomia de módulos	Mapa mental (/draw/mindmap)	references/general-charts.md
Roadmaps, cronogramas, planos de lançamento	Gantt (/draw/gantt)	references/general-charts.md
Métricas quantitativas do repositório (divisão de linguagens, cobertura, crescimento)	Gráficos de dados (`?type=pie	hbar
"Visualize este repositório" (genérico)	Suite multi-diagrama: 1 archmap visão geral + 1 Sankey (fluxo de dados/dependência) ou seq (fluxo de requisição central)	as duas referências correspondentes

Irmãos de mesma gramática do archmap (veja references/architecture.md): arch2 (skin alternativo). Modelagem de dados/comportamento: uc, dataflow, erd, class — gramáticas e exemplos ao vivo em references/technical-diagrams.md. Gráficos de cauda longa (treemap, funnel, graph, ...): /draw/echarts?d=<url-encoded echarts option JSON>.

Modos de varredura — escopo da varredura antes de ler o código (o usuário pode escolher; padrão de acordo com a intenção):

Modo	Escopo	Saída típica
quick	manifestos, árvore até profundidade 2, pontos de entrada	1 diagrama de visão geral
architecture	módulos, serviços, grafo de dependência	archmap (+ Sankey por peso)
deep-dive	cadeias de chamada, fluxo de dados, máquinas de estado	seq / fluxograma / suite Sankey
impact	git diff vs base: arquivos alterados e seus dependentes	diagrama de fluxo de mudança
full	tudo acima	Relatório de Repositório (suite + relatório de qualidade)

O modo impact carrega references/architecture-diff.md (fluxo de delta git-diff); o modo full carrega references/codebase-report.md (estrutura de relatório padrão); varreduras repetidas do mesmo repositório podem carregar references/incremental-scan.md (protocolo de cache opt-in); trabalho multi-diagrama ou sensível a evidências carrega references/repository-ir.md.

Etapa 2 — Varredura de Código com Disciplina de Token

1. Leia os manifestos raiz primeiro: package.json, go.mod, Cargo.toml, pyproject.toml, docker-compose.yml, mais uma árvore de diretório até profundidade 3 e os pontos de entrada declarados.
2. Nunca leia todos os arquivos fonte. Amostre arquivos de ponto de entrada e tabelas de rota; resuma componentes em nós e arestas de alto sinal.
3. Derive pesos Sankey de quantidades reais quando possível: tamanhos de arquivo (du -sh), contagens de import/referência, ou figuras de tráfego/custo fornecidas pelo usuário.
4. Guarda-corpo de comprimento de URL: mantenha um diagrama em ~15–20 nós (~60 links para Sankey) para que as URLs permaneçam legíveis e dentro dos limites da CDN. Para repositórios grandes, emita um diagrama de visão geral de alto nível + um diagrama por subsistema, nunca um único mega-diagrama denso.
5. Detecte linguagem e stack a partir dos manifestos e varra com essa lente: Go → pacotes/interfaces/goroutines; TypeScript → módulos/grafo de import/rotas de API; Rust → crates/traits/features; Python → pacotes/decoradores/pontos de entrada.
6. Registre evidência enquanto varre: cada nó/aresta recebe file[:symbol[:lines]] e um nível — verificado (visto no código), inferido (derivado da estrutura), ou desconhecido (suposição de padrão). Nunca marque verificado sem abrir o arquivo.

Etapa 3 — Construir a URL

• Construa o IR do Repositório leve primeiro para suites (um inventário de nós compartilhado, um documento por diagrama); mapeie IR → URL no momento da codificação. Esquema e protocolo de validação: references/repository-ir.md.
• Toda URL que você construir carrega seus rótulos para o renderizador — aplique a regra de confidencialidade da Etapa 4 antes de construir, validar ou exportá-la.
• Gramática (nós/arestas/limites), tabela de codificação, exemplos trabalhados e limites por tipo estão nos arquivos de referência. Siga-os exatamente; todo exemplo ali é testado ao vivo.
• Essenciais de codificação: espaço %20, + %2B, & %26, # %23, </> %3C/%3E, nova linha %0A; separadores ; = , : / @` permanecem literais. Sem Base64.
• Modificadores comuns: title=, scheme=dark|light, t=<style> (famílias por tipo em referências — arch2/seq ficam melhores com t=shadcn; nós arch2 recebem um campo icon opcional de 6ª posição, ex. n=api;be;API;ECS;r2c0;aws:ecs), w=/h=, v=N para fixar uma versão em cache, num=all|peak|none (gráficos).
• A saída PNG incorpora um subconjunto CJK nível 1 GB2312: caracteres raros (ex. 渲) tornam-se tofu em PNG. SVG não tem tal limite — prefira sinônimos comuns para rótulos chineses em PNG.
• Em um 4xx, o corpo da resposta é texto simples com um exemplo de correção — leia-o, corrija o parâmetro ofensor, tente novamente. Nunca adivinhe duas vezes.

Etapa 4 — Entrega da Saída

Modo padrão — sem escrita de arquivos. Responda com, por diagrama:

### <Título do diagrama>
![<título>](<url-do-desenho>)
*[Visualização interativa](<url-do-desenho>)* · [Abrir no editor](<url-explorar>)

- <ponto: o que o diagrama mostra — camadas, caminho crítico, fluxos mais pesados>
- <ponto: acoplamento notável / pontos únicos de falha / limites de propriedade>

• <url-explorar> reescreve /draw?type=X&q → /draw/explore?type=X&q e /draw/<nome>?q → /draw/explore/<nome>?q — editor interativo nativo do draw; vincule-o, não o reconstrua.
• 2–5 pontos concisos por diagrama. A imagem é a entrega; os pontos adicionam julgamento.
• Confidencialidade: a renderização — e a validação L1, e os downloads do export.sh — envia os rótulos do diagrama (para fluxogramas, todo o texto do programa) para o servidor de renderização x-cmd.com como parâmetros de URL; eles podem aparecer nos logs de acesso do servidor (codificação por centagem não é criptografia), e as incorporações de imagem Markdown podem ser buscadas automaticamente por clientes ou proxies. A exportação local não evita isso — a renderização ainda é solicitada do x-cmd.com. Para repositórios confidenciais, avise o usuário e obtenha aprovação explícita antes de renderizar, validar ou exportar — ou renderize totalmente offline via um CLI draw instalado localmente.

Feche uma suite com o relatório de qualidade (apenas contagens reais — nunca fabrique):

Análise do Repositório — <repo> (<scan_mode>, <commit>)
Arquivos inspecionados: N | Módulos: N | Relacionamentos: N
Evidência: verificado N · inferido N · desconhecido N
Validação: L1 aprovado|pulado (privacidade) · L2 aprovado · L3: N não resolvidos (sinalizados abaixo)

L1 não é automático — ele busca a URL, ou seja, envia o diagrama para x-cmd.com. Para repositórios confidenciais, execute-o apenas com a aprovação explícita do usuário (regra de confidencialidade da Etapa 4); caso contrário, reporte L1 pulado (privacidade). Sinalize cada desconhecido sob seu diagrama. Para solicitações explícitas de "validar" ou verificações pré-exportação: bash scripts/validate.sh <urls...> (renderização L1) e bash scripts/validate.sh --ir <ir.json> (estrutura L2). L3 é sua releitura dos arquivos citados.

Modo de exportação — apenas quando o usuário disser explicitamente "salvar localmente", "baixar SVG/PNG", "exportar imagem", "link curto", "colocar isso no meu README", ou "gerar relatório HTML":

bash scripts/export.sh "<url-do-desenho>" "<out.svg|png>"        # download único
bash scripts/export.sh --batch <manifest.tsv>              # muitos: "<url>\t<out>" por linha, # comentários
bash scripts/shorten.sh <tipo> '<d-schema json>' [título]   # permanente /draw/c/<hash> (apenas gráficos ?type=)
bash scripts/build_html.sh "<título>" "<out.html>" '<json>'       # relatório autônomo (+ ev evidência opcional)
bash scripts/inject_readme.sh "<README.md>" '<json>'       # inserir/atualizar diagramas entre marcadores repoviz

• export.sh baixa via curl (fallback: CLIs já instalados localmente — ele nunca busca ou instala pacotes); destinos .png obtêm automaticamente &format=png (adicione &scale=2|3 para maior resolução; passe scheme=dark — PNG padrão é claro). Modo batch: um url<TAB>saida por linha, comentários # permitidos; sai com código não zero se qualquer item falhar.
• shorten.sh POSTa a definição do gráfico (o esquema JSON ?d=) para x-cmd.com — limite de taxa ~30/min/IP. Apenas a família ?type= aceita POST; diagramas de nó/aresta (/draw/archmap, /draw/seq, ...) retornam 405 — mantenha suas URLs completas. O /draw/c/<hash> retornado renderiza com GET e é permanente. Execute-o apenas sob solicitação explícita do usuário: a definição armazenada é permanente e pública para qualquer pessoa que tenha o link (regra de confidencialidade da Etapa 4).
• build_html.sh recebe um array JSON de objetos {"title","url","note"[,"ev"]} (url restrita a URLs de renderização draw https://x-cmd.com / https://www.x-cmd.com; ev opcional, codificado "node|file|symbol|lines|level;..." — renderiza uma tabela filtável de evidências de origem) e emite um relatório responsivo escuro/claro autônomo: navegação por sidebar, zoom, tela cheia, botões de copiar URL, amigável para impressão em PDF. Todos os valores são escapados para HTML. Exemplo de payload: [{"title":"Arquitetura","url":"https://x-cmd.com/draw/archmap?...","note":"3 camadas; gateway é a única entrada","ev":"api|src/api.ts|createServer|12-40|verificado"}]
• inject_readme.sh é idempotente: anexa um bloco <!-- repoviz:start --> … <!-- repoviz:end --> (imagem Markdown + nota por diagrama) no primeiro uso, substitui-o no lugar em execuções posteriores — os diagramas tornam-se ativos vivos no repositório.
• Após exportar, imprima o(s) caminho(s) salvo(s) e continue a produzir o bloco Markdown para o chat para que o usuário obtenha ambos.

Regras

• Neutro de marca: apresente resultados como diagramas repoviz; nunca renomeie ou envolva as URLs de renderização.
• Uma varredura, muitos diagramas: reutilize o inventário de nós na suite em vez de reler o repositório por diagrama.
• Prefira menos nós bem escolhidos em vez de completude; colapse detalhes em legendas sub e caixas de limite.
• Evidência ou não aconteceu: cada nó/aresta é verificado, inferido ou sinalizado desconhecido — nunca fabricado. Mantenha a divisão IR/renderizador para que suites, relatórios e diffs futuros de arquitetura compartilhem um inventário; a renderização permanece um adaptador substituível.
• Edições incrementais baseadas em URL: um diagrama repoviz existente é totalmente definido por sua URL — nunca use ferramentas de visão ou leitura de imagem para inspecioná-lo. Decodifique a URL do Markdown, diferencie seu conjunto de nós/arestas contra o código atual, e emita a URL atualizada no lugar, preservando ids de nós, rótulos e convenções de layout.