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)
--output <format>	Formato de saída: console (padrão), json, github ou sarif. Veja Saída SARIF.
--adr <id>	Verificar apenas regras de um ADR específico
--verbose	Mostrar regras aprovadas e informações de tempo
--strict	Trata qualquer aviso de severidade de regra, e achados consultivos (orçamento do resumo, supressão, ADRs não analisados), como falhas. Veja Modo estrito.

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 --strict escalou avisos ou achados consultivos para falhas.
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 de severidade de regra e qualquer achado consultivo (orçamento do resumo, supressão, ADRs não analisados) como falha (útil em CI):

archgate check --strict

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 --output json

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

archgate check --output json

Obter anotações do GitHub Actions:

archgate check --output github

Obter saída SARIF para o GitHub Code Scanning:

archgate check --output sarif > results.sarif

Saída SARIF

archgate check --output sarif emite SARIF 2.1.0, o formato padrão que os recursos Code Scanning e Code Quality do GitHub consomem em CI. Cada violação de regra vira um resultado SARIF; as severidades error/warning/info mapeiam para error/warning/note do SARIF. Os achados consultivos (orçamento do resumo, supressão e ADRs não analisados) também são incluídos, como resultados sintéticos sob IDs de regra dedicados (archgate/briefing-budget, archgate/suppression-warning, archgate/unparsed-adr), sempre no nível warning — assim como nunca são tratados como bloqueantes fora do --strict.

--output sarif é somente opt-in: diferente do json em contexto de agente, ele nunca é auto-detectado.

Envie os resultados para a aba Security do GitHub em CI:

- name: Run archgate check
  run: archgate check --output sarif > results.sarif

- name: Upload SARIF to GitHub Security tab
  if: success() || failure()
  uses: github/codeql-action/upload-sarif@7188fc363630916deb702c7fdcf4e481b751f97a # v4.37.1
  with:
    sarif_file: results.sarif

A condição if: success() || failure() é obrigatória: archgate check sai com código 1 quando encontra violações, o que pularia a etapa de upload exatamente quando há achados a reportar. Prefira-a em vez de always(), que executaria o upload até em jobs cancelados. O job também precisa da permissão security-events: write para o upload funcionar.

Veja o guia de integração com CI para o fluxo completo.

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 --output json é usado (como violações com "severity": "warning").

Orçamento do resumo

archgate review-context --verbose incorpora as seções Decision e Do’s and Don’ts de cada ADR aplicável e trunca cada uma delas em um limite fixo de caracteres. O texto além desse ponto nunca chega ao agente que o ADR governa, e nenhuma regra companheira consegue detectá-lo — regras medem código, não o texto do próprio ADR.

Portanto, archgate check relata toda seção de ADR que excede o limite, em todos os ADRs, inclusive os com rules: false:

[briefing] ARCH-024 "Decision" is 3574 chars; review-context truncates at 2000, hiding 1574 from agent briefings

As mesmas entradas aparecem na saída JSON em briefingWarnings, com adrId, file, section, length e cap.

Um ADR que não pode ser lido ou analisado não é medido por nada, então é relatado separadamente em vez de contar como conforme:

[adr] could not be parsed, so it was excluded from every check above  .archgate/adrs/BROKEN.md

A saída JSON lista esses arquivos em unparsedAdrs. Um briefingWarnings vazio significa “nada acima do limite” apenas quando unparsedAdrs também estiver vazio — caso contrário, parte do corpus nunca foi inspecionada.

Elas são consultivas e nunca afetam pass, a menos que --strict esteja definido — veja Modo estrito.

Para eliminar um excesso, aplique primeiro os remédios que não podem custar uma regra: mova justificativas para Context ou Consequences, que nunca entram no resumo e portanto nunca têm limite; remova narrativa histórica; e mescle itens que enunciam a mesma regra duas vezes.

Se o próximo corte removeria uma cláusula normativa — uma lista enumerada de identificadores, uma barreira de proteção ordenada, uma isenção — pare. Espera-se mesmo que essa seção exceda o limite, e ela NÃO DEVE ser encurtada além disso. Registre o motivo na seção Compliance do próprio ADR e organize a seção para que o conteúdo mais normativo venha antes do corte, já que o truncamento sempre remove o final.

Por padrão, avisos (tanto diagnósticos quanto violações de regra com "severity": "warning") nunca alteram o código de saída. Passe --strict para escalá-los para falhas — veja Modo estrito.

Modo estrito

--strict combina duas escaladas em uma única flag: qualquer violação de regra com "severity": "warning" falha a build (o campo warningsExceeded da saída JSON é true e pass é false), e separadamente falha a build quando briefingWarnings, suppressionWarnings ou unparsedAdrs não estiver vazio — os diagnósticos consultivos acima que, por padrão, nunca afetam pass. O campo strictAdvisoryExceeded da saída JSON é true quando essa última condição causou a falha.

Os diagnósticos de orçamento do resumo e de ADRs não analisados abrangem todo o corpus, não apenas as regras: eles são coletados e aplicados mesmo quando nenhum ADR com rules: true existe, então um corpus de ADRs só de prosa ainda falha com --strict diante de um estouro de orçamento do resumo ou de um arquivo de ADR não analisável. Já os avisos de supressão derivam de violações de regras e só surgem quando regras são executadas.

--strict também se aplica a archgate review-context e archgate adr sync. Veja a referência de configuração para o schema completo.

Para evitar passar --strict em toda invocação, defina um padrão do projeto em .archgate/config.json:

{ "strict": true }

Não existe uma flag --no-strict: --strict na linha de comando só pode ativar o modo estrito sobre um padrão de config ausente ou false — não pode desativar um strict: true já configurado.

Formato da saída JSON

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

results contém apenas as regras que têm algo a relatar: falhas, erros de regra e qualquer regra com violações (incluindo regras que geram apenas avisos ou informações). Regras aprovadas sem violações são omitidas — sua entrada apenas repetiria o texto estático do ADR e, em projetos grandes, essas entradas dominam o payload. Os contadores total e passed continuam informando exatamente quantas regras foram executadas e quantas foram aprovadas. Use --verbose para incluir todas as regras em results.

{
  "pass": false,
  "total": 4,
  "passed": 3,
  "failed": 1,
  "warnings": 0,
  "errors": 1,
  "infos": 0,
  "ruleErrors": 0,
  "warningsExceeded": false,
  "strictAdvisoryExceeded": 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).