Avaliação de Base de Código

O que Avaliação de Base de Código faz?

Você é o revisor. Este skill leva você de uma base de código a um relatório pronto para o cliente.

O resultado é um arquivo JSON (assessments/<slug>.assessment.json) que o gerador renderiza em todos os formatos de relatório. Nada mais que você escreva é um entregável.

---

Antes de começar

Leia estes, nesta ordem. Não os pule — eles contêm a disciplina que separa um relatório defensável de uma lista de palpites.

1. METHODOLOGY.md — o processo de quatro etapas candidato→achado, invariantes, níveis de confiança, disciplina de cobertura e o que não fazer. Este é o arquivo mais importante.
2. scoring/dimensions.md, scoring/maturity-model.md, scoring/criticality-priority.md, scoring/effort-estimation.md — como observações se tornam números.
3. rules/README.md — formato de regras e detecção de stack.
4. schema/assessment.schema.json — o contrato exato de saída.
5. examples/industrifinans.assessment.json — um exemplo completo resolvido. Leia-o para forma e profundidade, nunca para conteúdo. Aqueles achados pertencem a um sistema diferente.

---

Procedimento

Passo 1 — Estabeleça o modelo do sistema

Antes de caçar defeitos. Escreva, em systemModel:

• Propósito & domínio. Para que o sistema serve e quais dados ele armazena. Isso define o raio de alcance de tudo que você encontrar — o mesmo defeito é crítico em uma plataforma financeira e menor em uma ferramenta de teste.
• Atores & limites de confiança. Quem pode acessar o quê. Então nomeie o atacante realista — geralmente um usuário autenticado de baixo privilégio, não um atacante anônimo da internet.
• Fluxos de dados principais. O caminho da requisição da entrada ao armazenamento, e o caminho de autenticação.
• 8–15 invariantes — afirmações positivas do que deve ser sempre verdadeiro, misturando genéricas com específicas deste domínio. Marque cada uma como HOLDS, VIOLATED ou CHECK à medida que as verificar.

Pular isso torna toda chamada de severidade posterior arbitrária.

Passo 2 — Detecte a stack e carregue as regras

Use a tabela de marcadores em rules/README.md § Detecção de stack. Carregue todos os arquivos em rules/universal/ mais os pacotes de stack correspondentes. Em um monorepo, detecte por pacote e carregue a união. Consulte rules/INDEX.md para a listagem completa do catálogo.

Passo 3 — Leia o código

Leia em ordem de execução: ponto de entrada → middleware → roteador → manipulador → serviço → acesso a dados. Os defeitos vivem nas lacunas entre camadas, que a leitura arquivo por arquivo ignora.

Além de buscas por categoria, use as técnicas em METHODOLOGY.md § Descoberta — comparação entre pares, rastreamento de identidade, controle-para-consequência em caminhos de erro, inventário de limites. Elas encontram o que buscas não encontram.

Registre o que você lê à medida que avança; você precisará disso para coverage.

Passo 4 — Refute antes de relatar

Cada candidato passa pelas quatro etapas em METHODOLOGY.md. A maioria morre na etapa 2 ou 3.

• Relate os sobreviventes como achados, cada um com confidence.
• Registre as mortes em refutedCandidates, com a etapa que os matou. Isso não é preenchimento — é a evidência de que a revisão foi rigorosa, e vai para o relatório.
• Rebaixe em vez de deletar quando algo é real, mas menos severo do que inicialmente afirmado.

Cada achado precisa de evidence com um file real e, onde você o abriu, uma line. Se você não pode apontar para o código, não é um achado — pode pertencer a suggestions em vez disso.

Consolide instâncias repetidas em um único achado sistêmico com 2–3 referências representativas e uma contagem de instances. Um achado sistêmico supera oito duplicatas.

Passo 5 — Pontue

• Dimensões. As sete padrão estão em scoring/dimensions.md. O conjunto é configurável — troque uma se o engajamento exigir (por exemplo, "Garantia da Qualidade / Teste"), mas mantenha 5–8 e mantenha-as consistentes em um portfólio.
• Maturidade. Comece em 3.0 e aplique os ajustes em scoring/maturity-model.md. Cada dimensão precisa de um keyGap nomeando os achados específicos que reduziram a pontuação.
• Metas. Metas realistas de 6–12 meses. Nunca 5.0. Nunca abaixo do atual.
• Criticalidade / prioridade / fase. Derive-as de scoring/criticality-priority.md — não copie o padrão da regra cegamente. Qualquer desvio vai em rationale.
• Esforço. Dias-homem de scoring/effort-estimation.md. Use null quando genuinamente desconhecido; nunca invente um número para preencher a coluna.

Passo 6 — Registre o que é bom

Preencha positivePosture com pontos fortes verificados, mantidos no mesmo padrão de evidência. Um relatório composto apenas de negativos parece um ataque e é descartado; além disso, falha em dizer à equipe o que proteger durante a remediação. "Nenhuma injeção de SQL encontrada" é uma declaração de cobertura, não um ponto forte.

Passo 7 — Cobertura e veredito

• coverage — método, tamanho (e como você contou), o que você leu profundamente, o que você varreu com grep, o que você não leu, e as ressalvas. Seja específico. Isso é o que torna os achados falseáveis.
• verdict e releaseGates — apenas quando o engajamento implica uma decisão de deploy. Declare o veredito por ambiente; bloquear produção enquanto aprova dev/teste é o resultado normal. Severidade não é o mesmo que gate — justifique cada um.

Omita verdict e releaseGates completamente para avaliações consultivas. O relatório se adapta.

Passo 8 — Escreva, valide, gere

Defina meta.repoPath como o caminho absoluto do repositório que você revisou. Isso é o que envia o relatório para <repoPath>/architecture-review/ em vez de para output/ desta ferramenta — o entregável pertence ao código que descreve. Omita-o apenas quando o código avaliado não estiver em disco.

Escreva assessments/<slug>.assessment.json, então:

npm run validate -- --input assessments/<slug>.assessment.json
npm run report   -- --input assessments/<slug>.assessment.json

npm run report também escreve o escopo do cliente Review-dashboard.html ao lado do relatório, construído a partir de todas as avaliações que compartilham o meta.client desta. Escreva meta.client exatamente como nas outras avaliações desse cliente, ou o painel se dividirá. Nunca execute npm run portfolio --all para um entregável de cliente — ele abrange clientes e é apenas interno.

Resolva todos os erros. Leia cada aviso e ou corrija o problema subjacente ou seja capaz de justificá-lo — os avisos codificam as regras acima (P0 fora da fase 1, inflação de P0, evidência faltante, dominância de esforço na fase 1, metas em 5.0).

---

Arquivos de saída

Toda saída é HTML — arquivos únicos autocontidos com gráficos SVG embutidos, amigáveis para impressão em PDF.

Arquivo	Escrito em	Público-alvo
ARCHITECTURE-REVIEW-<app>.html	<repoPath>/architecture-review/	Todos. Um relatório por aplicação, cobrindo material executivo e evidência técnica completa.
<slug>.assessment.json	<repoPath>/architecture-review/	Uma cópia ao lado do relatório para que o repositório carregue todo o registro. assessments/ permanece canônico.
Review-dashboard.html	<repoPath>/architecture-review/	Agregação apenas das aplicações deste cliente, gerada automaticamente a cada relatório. Não contém nada de outros clientes.

Um relatório por aplicação. A revisão de arquitetura abre com veredito, objetivo, resumo executivo e scorecard para tomadores de decisão, depois continua com modelo do sistema, cobertura, evidência e roadmap para engenheiros.

Existem duas saídas opcionais — um DECISION-BRIEF condensado por trás de --brief e uma versão Word por trás de --docx. Ambos são subconjuntos estritos. Não gere nenhum dos dois a menos que o usuário peça explicitamente.

---

Regras rígidas

• Nunca edite HTML gerado manualmente. Altere o JSON e regenere. Se o relatório precisar dizer algo novo, estenda schema/assessment.schema.json e tools/ primeiro.
• Nunca copie achados de examples/. Ele descreve o sistema de um cliente diferente.
• Nunca invente um caminho de arquivo ou número de linha. Se você não o abriu, não tem evidência.
• Nunca relate uma regra como um achado. "Deveria usar injeção de dependência" não é um achado. "OrderService constrói seu próprio DbContext em order.service.ts:31, então não pode ser testado sem um banco de dados ativo" é.
• Não encharque o roadmap. Cada dia-homem deve estar vinculado a um achado.
• Node apenas — Python não está instalado nesta máquina.

Escala

Uma aplicação pequena normalmente produz 10–20 achados e 30–60 dias-homem. Uma plataforma de médio porte, 25–40 achados e 80–150 dias-homem. Se seus números estiverem muito fora disso para o tamanho do sistema, algo se desviou — geralmente inflação de severidade ou duplicatas não consolidadas.