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" }

Pulando ADRs não afetados

Sempre que o conjunto de alterações não estiver vazio (qualquer uma das prioridades 1—4 acima), um ADR cujos globs em files não correspondam a nenhum dos arquivos alterados é pulado por completo: suas regras nunca executam, e ele não aparece nos resultados nem nas contagens de aprovação/falha — o mesmo comportamento de um filtro [files...] que não corresponde a nada governado pelo ADR. Arquivos excluídos contam como alterações, então remover um arquivo dentro do escopo de um ADR ainda executa esse ADR. ADRs sem escopo files sempre executam.

Isso significa que uma regra não precisa filtrar ctx.scopedFiles contra ctx.changedFiles apenas para evitar trabalho quando seu ADR é irrelevante para a alteração; o framework nunca a invoca nesse caso. Filtrar dentro da regra continua útil quando alguns arquivos no escopo mudaram e a regra quer inspecionar apenas esses.

Quando o conjunto de alterações está vazio — a detecção falha, --staged não encontra nada em stage, ou a árvore de trabalho é igual à base (por exemplo, na própria branch base no CI) — todos os ADRs executam (modo de varredura completa).

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).