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

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