Referência de CLI e configuração do ADR Guard

Disponibilidade: init, .adrguard.yml e a saída estruturada de check foram publicados no ADR Guard v1.2.0. A seleção do formato MADR 4.0 foi publicada na v1.3.0. Consulte as Releases do GitHub para os artefatos exatos.

A análise de impacto arquitetural está preparada para a v1.5.0, mas ainda não foi publicada. O pacote público permanece na v1.3.0 enquanto a distribuição incompleta da v1.4.0 é resolvida.

Inicializar um repositório

adr-guard init [repositório] [--adr-directory <caminho>]
  [--template minimal|extended | --template-file <caminho>]
  [--github-actions] [--dry-run] [--overwrite]

repositório usa o diretório de invocação por padrão. Caminhos gerenciados devem ser relativos, permanecer dentro do repositório e não podem atravessar links simbólicos/reparse points. --dry-run relata exatamente os arquivos planejados sem gravar. Repetir o mesmo comando não regrava arquivos inalterados. Arquivos existentes causam erro operacional, salvo quando --overwrite autoriza explicitamente a substituição.

--github-actions grava .github/workflows/adr-guard.yml com contents: read, sem credenciais de provider e sem permissão de escrita.

Configuração

O ADR Guard procura .adrguard.yml no diretório de invocação. O schema v1 é intencionalmente limitado a escalares top-level inertes:

schema-version: 1
adr-directory: "docs/adr"
template: minimal
# template-file: "docs/templates/team.md" # exclusivo com template
# adr-format: canonical                   # canonical ou madr-4
# lifecycle-statuses: Rejected=rejected,Under Review=proposed
# conventional-supersession: true          # habilita relações no texto de status
# filename-policy: canonical               # canonical, unnumbered, adr-prefix, numeric:1..9
# placeholder-policy: warn                 # off (padrão), warn ou error
# metadata-policy: validate                # validação opcional e limitada de metadados
# validation-profile: legacy              # legacy, advisory, standard, strict

Propriedades desconhecidas/duplicadas, versões incompatíveis, YAML aninhado, coleções, tags, anchors, aliases, block scalars, UTF-8 inválido, arquivos grandes demais, caminhos inseguros e uso simultâneo de template/template-file são rejeitados. Caminhos relativos partem do diretório da configuração. A configuração nunca é interpretada como comando e não expande variáveis de ambiente.

A precedência é:

1. Argumento explícito da CLI.
2. Valor de .adrguard.yml.
3. Default legado do comando.

O diretório configurado é aplicado quando o argumento posicional é omitido em check, index, new e draft. O template configurado é aplicado somente quando new/draft não recebem opção explícita. review continua exigindo target explícito.

Saída do check

adr-guard check [diretório] [--format text|json|sarif]

text permanece como default. JSON usa schema 1.0; SARIF usa 2.1.0. Ambos são gravados no stdout em sucesso e falha de validação; diagnósticos operacionais usam stderr. Os exit codes continuam 0 para válido, 1 para diagnósticos ADR, 2 para uso/configuração inválida e 3 para falha operacional.

Impacto arquitetural

adr-guard impact [repositório] --base-ref <ref> --map <arquivo> [--format text|json]

impact é explícito, consultivo e somente leitura. repositório usa o diretório atual por padrão; --map é relativo ao repositório. Texto é o formato padrão, e JSON usa o schema independente de relatório 1.0. Achados afetados/não mapeados retornam 0, uso inválido retorna 2, e falhas de Git/histórico/manifesto/limites retornam 3. Consulte o guia completo.

Solução de problemas

• Configuração ignorada: invoque o ADR Guard no diretório de .adrguard.yml ou informe diretório/template explicitamente.
• Recusa de sobrescrita: inspecione o arquivo existente e use init --overwrite somente quando a substituição for desejada.
• Caminho inseguro: remova paths absolutos, escapes com .. ou componentes de link simbólico/reparse point.
• Relatório estruturado vazio: JSON/SARIF usa stdout; não redirecione stderr para o mesmo arquivo.
• CI precisa de Code Scanning: gere SARIF e use uma etapa separada com security-events: write; a Action padrão permanece intencionalmente somente leitura.

Migração

Nenhuma migração é necessária. Repositórios sem .adrguard.yml preservam os padrões legados. Adicione configuração quando ela ajudar a centralizar argumentos repetidos de diretório, template ou formato.