Hooks de Pre-commit

Visão geral

O comando archgate check --staged verifica apenas os arquivos staged no git em relação às suas regras de ADR. Como ele ignora arquivos não-staged e não-rastreados, ele executa rápido o suficiente para ser usado como hook de pre-commit sem desacelerar seu fluxo de trabalho.

Quando uma verificação falha, o commit é bloqueado. As violações são impressas em stderr com caminhos de arquivo e números de linha para que você possa localizá-las e corrigi-las imediatamente.

Lefthook

Lefthook é um gerenciador de hooks git rápido e multiplataforma. Adicione o seguinte ao seu lefthook.yml:

lefthook.yml

pre-commit:
  commands:
    adr-check:
      run: archgate check --staged

Instale o hook com:

lefthook install

Husky

Husky é uma ferramenta popular de hooks git para projetos Node.js. Adicione a verificação ao seu hook de pre-commit:

.husky/pre-commit

archgate check --staged

Certifique-se de que o arquivo do hook é executável:

chmod +x .husky/pre-commit

O que acontece quando as verificações falham

Quando archgate check --staged encontra violações, ele termina com código 1. Isso bloqueia o commit. A saída inclui:

• O ID do ADR e o nome da regra que foi violada
• O caminho do arquivo onde a violação foi encontrada
• O número da linha (quando disponível)
• Uma descrição do que a regra espera

Corrija as violações, re-stage os arquivos com git add e faça o commit novamente.

Performance

A flag --staged restringe as verificações apenas aos arquivos na área de staging do git. Isso significa:

• Um projeto com centenas de arquivos fonte mas apenas três arquivos staged verificará apenas esses três arquivos.
• Regras que não correspondem a nenhum arquivo staged são ignoradas completamente.
• Verificações típicas de pre-commit completam em menos de um segundo.

Sem --staged, archgate check escaneia todos os arquivos correspondentes ao padrão glob files de cada ADR, o que é útil para CI mas mais lento para uso interativo.

Flags úteis

Flag	Finalidade
--staged	Verifica apenas arquivos staged no git (obrigatório para pre-commit)
--verbose	Mostra regras aprovadas e informações de tempo — útil para debugar por que uma verificação está lenta ou quais regras estão sendo avaliadas
--json	Exibe resultados como JSON — útil para encaminhar a outras ferramentas ou scripts de relatório personalizados
--adr <id>	Verifica apenas regras de um ADR específico — útil para isolar uma única regra durante o debug
--ci	Exibe anotações do GitHub Actions — use em workflows de CI ao invés de hooks de pre-commit

Combinando com outros hooks

Hooks de pre-commit podem executar múltiplos comandos. Por exemplo, com Lefthook:

lefthook.yml

pre-commit:
  commands:
    lint:
      run: npm run lint
    typecheck:
      run: npm run typecheck
    adr-check:
      run: archgate check --staged

Cada comando executa independentemente. Se qualquer comando terminar com código diferente de zero, o commit é bloqueado.