archgate check

Executa todas as verificações automatizadas de conformidade com ADRs no codebase.

archgate check [options] [files...]

Carrega cada ADR com rules: true no frontmatter, executa o arquivo .rules.ts complementar e reporta violações com caminhos de arquivo e números de linha. Quando caminhos de arquivo são fornecidos como argumentos posicionais, apenas ADRs cujos padrões files correspondem a esses arquivos são executados.

Opções

Opção	Descrição
--staged	Verificar apenas arquivos no git stage (útil para hooks de pre-commit)
--base [ref]	Comparar arquivos alterados contra uma ref base (auto-detecta quando omitido)
--json	Saída JSON legível por máquina
--ci	Formato de anotação do GitHub Actions
--adr <id>	Verificar apenas regras de um ADR específico
--verbose	Mostrar regras aprovadas e informações de tempo
--max-warnings <n>	Falhar (código 1) quando a contagem de avisos exceder n. Use 0 para falhar com qualquer aviso.

Argumentos

Argumento	Descrição
[files...]	Caminhos de arquivo opcionais para limitar as verificações. Apenas ADRs cujos padrões files correspondem serão executados. Suporta pipe via stdin.

Códigos de saída

Código	Significado
0	Todas as regras passaram. Nenhuma violação encontrada.
1	Uma ou mais violações detectadas, ou avisos excederam --max-warnings.
2	Erro na execução de regra (ex.: regra malformada, bloqueio do scanner de segurança).

Exemplos

Verificar o projeto inteiro:

archgate check

Verificar apenas arquivos no stage antes de commitar:

archgate check --staged

Verificar todos os arquivos alterados na branch atual vs main:

archgate check --base main

Verificar um único ADR:

archgate check --adr ARCH-001

Tratar qualquer aviso como falha (útil em CI):

archgate check --max-warnings 0

Verificar arquivos específicos (apenas ADRs correspondentes são executados):

archgate check src/foo.ts src/bar.ts

Pipe do git (verificar apenas arquivos alterados):

git diff --name-only | archgate check --json

Obter saída JSON para integração com CI:

archgate check --json

Obter anotações do GitHub Actions:

archgate check --ci

Detecção de arquivos alterados

Por padrão, archgate check autodetecta a branch base e preenche ctx.changedFiles com o diff da branch (git diff <base>...HEAD) mais quaisquer alterações não commitadas da árvore de trabalho (arquivos staged, não staged e não rastreados que não sejam ignorados). Isso permite que regras de dependência entre arquivos funcionem localmente — não apenas no CI — e garante que edições ainda não commitadas também sejam verificadas.

A referência base é resolvida nesta ordem de prioridade:

Prioridade	Fonte	changedFiles preenchido com
1	--staged	Apenas a área de staging do git
2	--base <ref>	git diff <ref>...HEAD + alterações da árvore de trabalho
3	.archgate/config.json baseBranch	git diff <resolved-ref>...HEAD + alterações da árvore de trabalho
4	Autodetecção do git	git diff <detected-ref>...HEAD + alterações da árvore de trabalho
5	Detecção falha	Vazio (modo de varredura completa)

A autodetecção tenta origin/HEAD, depois origin/main, origin/master, main local e master local. Para definir um padrão do projeto, adicione baseBranch ao .archgate/config.json:

{ "baseBranch": "main" }

Diagnósticos

Durante a execução, archgate check emite avisos para configurações incorretas comuns que podem causar resultados lentos ou inesperados:

Aviso	Condição	Recomendação
Escopo de arquivos amplo	Os padrões files de um ADR resolvem mais de 1.000 arquivos ou a varredura de glob leva mais de 2 segundos	Estreite os padrões files no frontmatter do ADR para atingir apenas os diretórios de código relevantes
Opt-out de gitignore sem escopo	respectGitignore: false está definido sem um escopo files	Adicione padrões files para evitar a varredura de todos os arquivos incluindo node_modules/, .git/, etc.
Todos os arquivos excluídos pelo gitignore	Padrões files explícitos correspondem a arquivos, mas todas as correspondências são excluídas pelo .gitignore	Defina respectGitignore: false no frontmatter do ADR para incluir arquivos ignorados pelo git

Esses avisos aparecem na saída padrão e não afetam o código de saída. Eles também aparecem na saída JSON quando --json é usado (como violações com "severity": "warning").

Por padrão, avisos (tanto diagnósticos quanto violações de regra com "severity": "warning") nunca alteram o código de saída. Passe --max-warnings <n> para fazer archgate check sair com código 1 quando a contagem total de avisos exceder n. --max-warnings 0 falha com qualquer aviso. Quando o limite é excedido, o campo warningsExceeded da saída JSON é true e pass é false.

Formato da saída JSON

Quando --json é usado, a saída é um único objeto JSON:

{
  "pass": false,
  "total": 4,
  "passed": 3,
  "failed": 1,
  "warnings": 0,
  "errors": 1,
  "infos": 0,
  "ruleErrors": 0,
  "warningsExceeded": false,
  "truncated": false,
  "results": [
    {
      "adrId": "ARCH-001",
      "ruleId": "register-function-export",
      "description": "Command file must export a register*Command function",
      "status": "fail",
      "totalViolations": 1,
      "shownViolations": 1,
      "violations": [
        {
          "message": "Command file must export a register*Command function",
          "file": "src/commands/broken.ts",
          "line": 1,
          "endLine": 1,
          "endColumn": 42,
          "severity": "error"
        }
      ],
      "durationMs": 12
    }
  ],
  "durationMs": 42
}

Campos de violação

Campo	Tipo	Descrição
message	string	Descrição da violação
file	string?	Caminho relativo do arquivo
line	number?	Linha inicial (base 1)
endLine	number?	Linha final (base 1) — para destaque preciso no editor
endColumn	number?	Coluna final (base 0) — para destaque preciso no editor
fix	string?	Correção sugerida (apenas orientação)
severity	string	"error", "warning" ou "info"

Arquivos de regra bloqueados

Quando um arquivo de regra é bloqueado pelo scanner de segurança (ex.: usa Bun.spawn()) ou um arquivo .rules.ts complementar está ausente, o resultado aparece na saída JSON com status: "error" e ruleId: "security-scan". As violações incluem o arquivo e a linha exata do código bloqueado (ou a linha rules: true no ADR para arquivos complementares ausentes).