Project Class Architect

O que Project Class Architect faz?

Transforma um repositório em um diagrama de classes UML interativo que um desenvolvedor pode explorar em vez de ler centenas de arquivos. A análise é baseada em evidências: cada classe, atributo, método e relacionamento no diagrama aponta para o arquivo e a linha de onde veio. Nada é inventado; descobertas heurísticas são marcadas como inferido.

Todos os caminhos neste arquivo são relativos ao diretório da skill (a pasta que contém este SKILL.md).

Requisitos

• Node.js 18+ (node --version). Os scripts não têm dependências: nunca execute npm install para esta skill.
• Acesso de leitura ao repositório. A análise nunca modifica arquivos de código-fonte; ela apenas grava sua pasta de saída.
• Se o Node.js não estiver disponível, use o método alternativo descrito no final.

Fluxo de trabalho

1. Identificar o repositório

Use o caminho absoluto do projeto sobre o qual o usuário está falando (geralmente o workspace atual). Os comandos abaixo são executados a partir do diretório da skill, portanto um caminho relativo como . apontaria para a própria skill.

2. Gerar o diagrama

node scripts/class-architect.js generate "/caminho/absoluto/para/o/repositorio"

Opções úteis (veja a referência da CLI para todas):

Necessidade	Opção
Autor no rodapé	--author "Nome" --author-role "Engenheiro de Software"
Título do diagrama	--title "Serviço de Faturamento"
Apenas parte de um repositório grande	--include "src/main/java/com/acme/billing/**" (repetível)
Pular pastas	--exclude "legacy/**" (repetível)
Restringir linguagens	--languages java,sql
Analisar testes também	--include-tests
Visualização / layout inicial	--view classes|er|overview|packages --layout grouped|layered|hierarchical|grid
Pasta de saída personalizada	--out "/caminho/para/saida" (padrão <repo>/.class-architect)
Manter caminhos locais fora do HTML	--hide-root (desabilita links "abrir no editor")

O comando imprime um resumo JSON na saída padrão (o progresso vai para o erro padrão). Códigos de saída: 0 sucesso, 1 erro de uso, 2 nenhum arquivo de código-fonte analisável, 3 falha na validação do modelo (nada foi gravado), 4 erro interno.

3. Verificar o resultado

Leia o resumo JSON (status, outputs, summary.counts, summary.insights, summary.edits, validation). Saídas gravadas na pasta de saída:

• diagram.html - o diagrama interativo (abra em um navegador; funciona offline).
• report.md / report.json - arquivos escaneados, classes, interfaces, enums, relacionamentos, relacionamentos inferidos, referências não resolvidas, arquivos excluídos com motivos, avisos, insights.
• model.json - o modelo UML (fonte única da verdade); overlay.json - edições do usuário, quando houver.

Se o código de saída for 2, ajuste --include / --languages e informe quais pastas foram excluídas e por quê (a partir do JSON details). Se o código de saída for 3, relate os erros de validação; não edite manualmente o modelo para ocultá-los.

Para repositórios com centenas de classes, o diagrama abre na visão Visão Geral (módulos) e permite que o usuário aprofunde em módulos e pacotes; você também pode gerar diagramas focados com --include para um contexto limitado.

4. Apresentar o diagrama ao usuário

• Forneça o caminho de diagram.html (e sua URL file:// de outputs.diagramUrl). Não tente abrir um navegador, a menos que o usuário peça e seu ambiente permita.
• Resuma apenas o que o relatório diz: números de classes / interfaces / enums / relacionamentos, frameworks detectados, ciclos de dependência, descobertas de arquitetura, referências não resolvidas e avisos. Cite os nomes das classes exatamente.
• Mencione que relacionamentos marcados como inferido (convenções de nomenclatura, tipagem estrutural de Go) devem ser verificados e que nomes de tabelas/colunas derivados são marcados como derivados.
• Aponte as principais interações: clique em uma classe ou linha para inspecioná-la (com arquivo e linha de origem), pesquisa (/), filtros, visualizações (Visão Geral, Pacotes, Classes, ER do Banco de Dados), a lupa (L), modo de edição (E), Insights, Exportar. Detalhes: o guia do diagrama interativo.

5. Atualizar após alterações no código

Execute o mesmo comando novamente. Ele:

• reanalisa apenas os arquivos alterados (cache incremental),
• mantém todas as edições do usuário (de overlay.json e de edições que o usuário salvou em diagram.html com o botão Salvar),
• relata edições cujo alvo desapareceu do código como órfãs (mantidas, nunca descartadas silenciosamente) e edições que entram em conflito com uma alteração no código-fonte,
• destaca classes adicionadas / removidas / modificadas em comparação com a execução anterior,
• mantém um backup do diagrama anterior (diagram.prev.html).

Se o usuário baixou uma cópia do diagrama em outro local, passe-a com --edits "/caminho/para/o/diagrama-salvo.html".

6. Opcional: seções de documentação

O diagrama pode mostrar documentação extra abaixo dele (tabelas, fluxos, etapas, grades de enum, notas de banner) usando os componentes do modelo original. Adicione apenas fatos que você verificou no código e cite o arquivo de origem. Escreva um arquivo JSON seguindo o guia de configuração e passe --notes notes.json.

Regras

• Nunca modifique, formate ou "corrija" o código-fonte analisado como parte desta skill.
• Nunca invente classes, membros ou relacionamentos, e nunca apresente um relacionamento inferido como certo.
• Nunca exclua ou sobrescreva overlay.json ou um diagram.html salvo pelo usuário: a CLI os mescla para você.
• A pasta de saída .class-architect/ é gerada; sugira adicioná-la ao .gitignore a menos que o usuário queira versionar o diagrama.
• Não faça upload do diagrama ou do modelo para lugar nenhum: eles podem conter estrutura de código proprietária.

Método alternativo quando os scripts não podem ser executados

Se o Node.js 18+ não estiver disponível ou a execução de comandos não for permitida:

1. Leia os arquivos de código-fonte relevantes e escreva um modelo JSON manualmente seguindo a referência do modelo UML. Inclua apenas elementos que você viu no código, com source.file e source.line; defina confidence: "inferred" para qualquer coisa não explícita.
2. Copie templates/viewer.html para o local onde o usuário deseja o diagrama (por exemplo, class-diagram.html).
3. Na cópia, substitua o texto null dentro de <script type="application/json" id="pca-data">null</script> por {"model": <seu modelo>, "overlay": null, "meta": {"title": "<nome do projeto>"}}, escrevendo < como < dentro do JSON.
4. Alternativamente, diga ao usuário para abrir templates/viewer.html e arrastar o model.json para a página.

O layout, as interações e as exportações funcionarão no navegador exatamente como em um diagrama gerado; apenas a extração automática, a detecção de alterações e o relatório de validação estarão ausentes. Diga claramente que o modelo foi escrito manualmente.

Outros comandos

node scripts/class-architect.js analyze "/abs/repo"                       # modelo + relatório, sem HTML
node scripts/class-architect.js render --model model.json --out diagram.html
node scripts/class-architect.js validate --model model.json --html diagram.html
node scripts/class-architect.js diff --base old-model.json --head model.json
node scripts/class-architect.js edits --from saved-diagram.html --out overlay.json
node scripts/class-architect.js viewer --out viewer.html
node scripts/class-architect.js doctor

Arquivos de referência (leia apenas quando necessário)

• references/CLI.md - todos os comandos, opções, saídas e códigos de saída.
• references/INTERACTIVE-DIAGRAM.md - o que o usuário pode fazer no diagrama, atalhos de teclado.
• references/RELATIONSHIPS.md - como cada tipo de relacionamento e multiplicidade é decidido, evidência e confiança.
• references/LANGUAGES.md - linguagens suportadas, frameworks e ORMs, e o que é extraído.
• references/CONFIGURATION.md - class-architect.config.json, entidades externas, limites, notas de documentação.
• references/UML-MODEL.md - o formato do modelo (para o método alternativo ou para outras ferramentas).
• references/LIMITATIONS.md - limitações conhecidas para mencionar quando relevante.