Skip to content

feat(check): add --max-warnings flag to fail on warnings #374

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rhuanbarreto merged 5 commits into from
May 28, 2026
Merged

feat(check): add --max-warnings flag to fail on warnings #374

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
43c8b1b
feat(check): add --max-warnings flag to fail on warnings
rhuanbarreto May 28, 2026
925a41d
docs: regenerate llms-full.txt
rhuanbarreto May 28, 2026
8a458e2
Merge remote-tracking branch 'origin/main' into claude/hardcore-licht…
rhuanbarreto May 28, 2026
5c670db
fix(check): mirror --max-warnings docs to nb locale, resolve merge
rhuanbarreto May 28, 2026
602da0b
Merge remote-tracking branch 'origin/claude/hardcore-lichterman-88dcb…
rhuanbarreto May 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 23 additions & 13 deletions docs/public/llms-full.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3649,14 +3649,15 @@ Loads every ADR with `rules: true` in its frontmatter, executes the companion `.

## Options

| Option | Description |
| -------------- | -------------------------------------------------------------------- |
| `--staged` | Only check git-staged files (useful for pre-commit hooks) |
| `--base [ref]` | Compare changed files against a base ref (auto-detects when omitted) |
| `--json` | Machine-readable JSON output |
| `--ci` | GitHub Actions annotation format |
| `--adr <id>` | Only check rules from a specific ADR |
| `--verbose` | Show passing rules and timing info |
| Option | Description |
| -------------------- | --------------------------------------------------------------------------------- |
| `--staged` | Only check git-staged files (useful for pre-commit hooks) |
| `--base [ref]` | Compare changed files against a base ref (auto-detects when omitted) |
| `--json` | Machine-readable JSON output |
| `--ci` | GitHub Actions annotation format |
| `--adr <id>` | Only check rules from a specific ADR |
| `--verbose` | Show passing rules and timing info |
| `--max-warnings <n>` | Fail (exit 1) when the warning count exceeds `n`. Use `0` to fail on any warning. |

## Arguments

Expand All @@ -3666,11 +3667,11 @@ Loads every ADR with `rules: true` in its frontmatter, executes the companion `.

## Exit codes

| Code | Meaning |
| ---- | -------------------------------------------------------------------- |
| 0 | All rules pass. No violations found. |
| 1 | One or more violations detected. |
| 2 | Rule execution error (e.g., malformed rule, security scanner block). |
| Code | Meaning |
| ---- | ----------------------------------------------------------------------- |
| 0 | All rules pass. No violations found. |
| 1 | One or more violations detected, or warnings exceeded `--max-warnings`. |
| 2 | Rule execution error (e.g., malformed rule, security scanner block). |

## Examples

Expand Down Expand Up @@ -3698,6 +3699,12 @@ Check a single ADR:
archgate check --adr ARCH-001
```

Treat any warning as a failure (useful in CI):

```bash
archgate check --max-warnings 0
```

Check specific files (only matching ADRs run):

```bash
Expand Down Expand Up @@ -3754,6 +3761,8 @@ During execution, `archgate check` emits warnings for common misconfigurations t

These warnings appear in the standard output and do not affect the exit code. They also appear in JSON output when `--json` is used (as violations with `"severity": "warning"`).

By default, warnings (both diagnostics and rule-reported `"severity": "warning"` violations) never change the exit code. Pass `--max-warnings <n>` to make `archgate check` exit 1 when the total warning count exceeds `n`. `--max-warnings 0` fails on any warning. When the threshold is exceeded the JSON output's `warningsExceeded` field is `true` and `pass` is `false`.

## JSON output format

When `--json` is used, the output is a single JSON object:
Expand All @@ -3768,6 +3777,7 @@ When `--json` is used, the output is a single JSON object:
"errors": 1,
"infos": 0,
"ruleErrors": 0,
"warningsExceeded": false,
"truncated": false,
"results": [
{
Expand Down
28 changes: 19 additions & 9 deletions docs/src/content/docs/nb/reference/cli/check.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,14 +13,15 @@ Laster inn hver ADR med `rules: true` i frontmatteren, kjører den tilhørende `

## Valg

| Valg | Beskrivelse |
| -------------- | ---------------------------------------------------------------------------- |
| `--staged` | Sjekk kun git-stagede filer (nyttig for pre-commit-hooks) |
| `--base [ref]` | Sammenlign endrede filer mot en basisreferanse (autodetekteres hvis utelatt) |
| `--json` | Maskinlesbar JSON-utdata |
| `--ci` | GitHub Actions-annotasjonsformat |
| `--adr <id>` | Sjekk kun regler fra en bestemt ADR |
| `--verbose` | Vis beståtte regler og tidsinformasjon |
| Valg | Beskrivelse |
| -------------------- | -------------------------------------------------------------------------------------------------------- |
| `--staged` | Sjekk kun git-stagede filer (nyttig for pre-commit-hooks) |
| `--base [ref]` | Sammenlign endrede filer mot en basisreferanse (autodetekteres hvis utelatt) |
| `--json` | Maskinlesbar JSON-utdata |
| `--ci` | GitHub Actions-annotasjonsformat |
| `--adr <id>` | Sjekk kun regler fra en bestemt ADR |
| `--verbose` | Vis beståtte regler og tidsinformasjon |
| `--max-warnings <n>` | Mislykkes (kode 1) når antallet advarsler overskrider `n`. Bruk `0` for å mislykkes ved enhver advarsel. |

## Argumenter

Expand All @@ -33,7 +34,7 @@ Laster inn hver ADR med `rules: true` i frontmatteren, kjører den tilhørende `
| Kode | Betydning |
| ---- | -------------------------------------------------------------------------------- |
| 0 | Alle regler bestått. Ingen brudd funnet. |
| 1 | Ett eller flere brudd oppdaget. |
| 1 | Ett eller flere brudd oppdaget, eller advarsler overskred `--max-warnings`. |
| 2 | Feil ved regelkjøring (f.eks. feilformatert regel, sikkerhetsskannerblokkering). |

## Eksempler
Expand Down Expand Up @@ -62,6 +63,12 @@ Sjekk en enkelt ADR:
archgate check --adr ARCH-001
```

Behandle enhver advarsel som en feil (nyttig i CI):

```bash
archgate check --max-warnings 0
```

Sjekk bestemte filer (bare matchende ADR-er kjøres):

```bash
Expand Down Expand Up @@ -118,6 +125,8 @@ Under kjøring sender `archgate check` advarsler for vanlige feilkonfigurasjoner

Disse advarslene vises i standardutdataene og påvirker ikke avslutningskoden. De vises også i JSON-utdata når `--json` brukes (som brudd med `"severity": "warning"`).

Som standard endrer advarsler (både diagnostikk og regelrapporterte brudd med `"severity": "warning"`) aldri avslutningskoden. Send `--max-warnings <n>` for å få `archgate check` til å avslutte med kode 1 når det totale antallet advarsler overskrider `n`. `--max-warnings 0` mislykkes ved enhver advarsel. Når terskelen overskrides, er feltet `warningsExceeded` i JSON-utdataene `true` og `pass` er `false`.

## JSON-utdataformat

Når `--json` brukes, er utdataene et enkelt JSON-objekt:
Expand All @@ -132,6 +141,7 @@ Når `--json` brukes, er utdataene et enkelt JSON-objekt:
"errors": 1,
"infos": 0,
"ruleErrors": 0,
"warningsExceeded": false,
"truncated": false,
"results": [
{
Expand Down
28 changes: 19 additions & 9 deletions docs/src/content/docs/pt-br/reference/cli/check.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,14 +13,15 @@ Carrega cada ADR com `rules: true` no frontmatter, executa o arquivo `.rules.ts`

## 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 |
| 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

Expand All @@ -33,7 +34,7 @@ Carrega cada ADR com `rules: true` no frontmatter, executa o arquivo `.rules.ts`
| Código | Significado |
| ------ | ------------------------------------------------------------------------------------ |
| 0 | Todas as regras passaram. Nenhuma violação encontrada. |
| 1 | Uma ou mais violações detectadas. |
| 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
Expand Down Expand Up @@ -62,6 +63,12 @@ Verificar um único ADR:
archgate check --adr ARCH-001
```

Tratar qualquer aviso como falha (útil em CI):

```bash
archgate check --max-warnings 0
```

Verificar arquivos específicos (apenas ADRs correspondentes são executados):

```bash
Expand Down Expand Up @@ -98,6 +105,8 @@ Durante a execução, `archgate check` emite avisos para configurações incorre

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:
Expand All @@ -112,6 +121,7 @@ Quando `--json` é usado, a saída é um único objeto JSON:
"errors": 1,
"infos": 0,
"ruleErrors": 0,
"warningsExceeded": false,
"truncated": false,
"results": [
{
Expand Down
36 changes: 23 additions & 13 deletions docs/src/content/docs/reference/cli/check.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,14 +13,15 @@ Loads every ADR with `rules: true` in its frontmatter, executes the companion `.

## Options

| Option | Description |
| -------------- | -------------------------------------------------------------------- |
| `--staged` | Only check git-staged files (useful for pre-commit hooks) |
| `--base [ref]` | Compare changed files against a base ref (auto-detects when omitted) |
| `--json` | Machine-readable JSON output |
| `--ci` | GitHub Actions annotation format |
| `--adr <id>` | Only check rules from a specific ADR |
| `--verbose` | Show passing rules and timing info |
| Option | Description |
| -------------------- | --------------------------------------------------------------------------------- |
| `--staged` | Only check git-staged files (useful for pre-commit hooks) |
| `--base [ref]` | Compare changed files against a base ref (auto-detects when omitted) |
| `--json` | Machine-readable JSON output |
| `--ci` | GitHub Actions annotation format |
| `--adr <id>` | Only check rules from a specific ADR |
| `--verbose` | Show passing rules and timing info |
| `--max-warnings <n>` | Fail (exit 1) when the warning count exceeds `n`. Use `0` to fail on any warning. |

## Arguments

Expand All @@ -30,11 +31,11 @@ Loads every ADR with `rules: true` in its frontmatter, executes the companion `.

## Exit codes

| Code | Meaning |
| ---- | -------------------------------------------------------------------- |
| 0 | All rules pass. No violations found. |
| 1 | One or more violations detected. |
| 2 | Rule execution error (e.g., malformed rule, security scanner block). |
| Code | Meaning |
| ---- | ----------------------------------------------------------------------- |
| 0 | All rules pass. No violations found. |
| 1 | One or more violations detected, or warnings exceeded `--max-warnings`. |
| 2 | Rule execution error (e.g., malformed rule, security scanner block). |

## Examples

Expand Down Expand Up @@ -62,6 +63,12 @@ Check a single ADR:
archgate check --adr ARCH-001
```

Treat any warning as a failure (useful in CI):

```bash
archgate check --max-warnings 0
```

Check specific files (only matching ADRs run):

```bash
Expand Down Expand Up @@ -118,6 +125,8 @@ During execution, `archgate check` emits warnings for common misconfigurations t

These warnings appear in the standard output and do not affect the exit code. They also appear in JSON output when `--json` is used (as violations with `"severity": "warning"`).

By default, warnings (both diagnostics and rule-reported `"severity": "warning"` violations) never change the exit code. Pass `--max-warnings <n>` to make `archgate check` exit 1 when the total warning count exceeds `n`. `--max-warnings 0` fails on any warning. When the threshold is exceeded the JSON output's `warningsExceeded` field is `true` and `pass` is `false`.

## JSON output format

When `--json` is used, the output is a single JSON object:
Expand All @@ -132,6 +141,7 @@ When `--json` is used, the output is a single JSON object:
"errors": 1,
"infos": 0,
"ruleErrors": 0,
"warningsExceeded": false,
"truncated": false,
"results": [
{
Expand Down
21 changes: 20 additions & 1 deletion src/commands/check.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Archgate
import type { Command } from "@commander-js/extra-typings";
import { Option } from "@commander-js/extra-typings";

import { resolveBaseRef } from "../engine/git-files";
import { loadRuleAdrs } from "../engine/loader";
Expand All @@ -19,6 +20,11 @@ import { findProjectRoot } from "../helpers/paths";
import { getConfiguredBaseBranch } from "../helpers/project-config";
import { trackCheckResult } from "../helpers/telemetry";

const maxWarningsOption = new Option(
"--max-warnings <n>",
"Fail (exit 1) when the number of warnings exceeds this threshold (0 = fail on any warning)"
).argParser((val) => parseInt(val, 10));

export function registerCheckCommand(program: Command) {
program
.command("check")
Expand All @@ -32,6 +38,7 @@ export function registerCheckCommand(program: Command) {
)
.option("--adr <id>", "Only check rules from a specific ADR")
.option("--verbose", "Show passing rules and timing info")
.addOption(maxWarningsOption)
.argument("[files...]", "Only check rules relevant to these files")
.action(async (files, opts) => {
const projectRoot = findProjectRoot();
Expand All @@ -43,6 +50,16 @@ export function registerCheckCommand(program: Command) {
return;
}

const maxWarnings = opts.maxWarnings;
if (
maxWarnings !== undefined &&
(Number.isNaN(maxWarnings) || maxWarnings < 0)
) {
logError("--max-warnings must be a non-negative integer");
await exitWith(1);
return;
}

let loadResults;
const loadStart = performance.now();
try {
Expand Down Expand Up @@ -72,6 +89,7 @@ export function registerCheckCommand(program: Command) {
errors: 0,
infos: 0,
ruleErrors: 0,
warningsExceeded: false,
results: [],
durationMs: 0,
},
Expand Down Expand Up @@ -122,7 +140,7 @@ export function registerCheckCommand(program: Command) {
// Build the summary once and share it with the reporters, telemetry,
// and exit-code resolver. Previously each of those built its own
// summary — 3 walks over the same result set.
const summary = buildSummary(result);
const summary = buildSummary(result, { maxWarnings });

if (opts.ci) {
reportCI(result, summary);
Expand All @@ -146,6 +164,7 @@ export function registerCheckCommand(program: Command) {
used_base: Boolean(resolvedBase),
used_file_filter: filterFiles.length > 0,
used_adr_filter: Boolean(opts.adr),
used_max_warnings: maxWarnings !== undefined,
files_scanned: filterFiles.length,
load_duration_ms: loadDurationMs,
check_duration_ms: Math.round(result.totalDurationMs),
Expand Down
1 change: 1 addition & 0 deletions src/engine/context.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,6 +191,7 @@ const EMPTY_SUMMARY: ReportSummary = {
errors: 0,
infos: 0,
ruleErrors: 0,
warningsExceeded: false,
truncated: false,
results: [],
durationMs: 0,
Expand Down
Loading
Loading