Skip to content

fix: report blocked rules and range info in JSON output #152

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 2 commits into from
Mar 23, 2026
Merged

fix: report blocked rules and range info in JSON output #152

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d1e4795
fix: include blocked rules in JSON output with range info
rhuanbarreto Mar 23, 2026
c64bea3
docs: regenerate llms-full.txt
rhuanbarreto Mar 23, 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
91 changes: 69 additions & 22 deletions docs/public/llms-full.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3143,10 +3143,10 @@ archgate plugin install --editor cursor
Run all automated ADR compliance checks against the codebase.

```bash
archgate check [options]
archgate check [options] [files...]
```

Loads every ADR with `rules: true` in its frontmatter, executes the companion `.rules.ts` file, and reports violations with file paths and line numbers.
Loads every ADR with `rules: true` in its frontmatter, executes the companion `.rules.ts` file, and reports violations with file paths and line numbers. When file paths are provided as positional arguments, only ADRs whose `files` patterns match those files are executed.

### Options

Expand All @@ -3158,13 +3158,19 @@ Loads every ADR with `rules: true` in its frontmatter, executes the companion `.
| `--adr <id>` | Only check rules from a specific ADR |
| `--verbose` | Show passing rules and timing info |

### Arguments

| Argument | Description |
| ------------ | --------------------------------------------------------------------------------------------------------------- |
| `[files...]` | Optional file paths to scope checks to. Only ADRs whose `files` patterns match will run. Supports stdin piping. |

### Exit codes

| Code | Meaning |
| ---- | --------------------------------------------- |
| 0 | All rules pass. No violations found. |
| 1 | One or more violations detected. |
| 2 | Internal error (e.g., malformed ADR or rule). |
| 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). |

### Examples

Expand All @@ -3186,6 +3192,18 @@ Check a single ADR:
archgate check --adr ARCH-001
```

Check specific files (only matching ADRs run):

```bash
archgate check src/foo.ts src/bar.ts
```

Pipe from git (check only changed files):

```bash
git diff --name-only | archgate check --json
```

Get JSON output for CI integration:

```bash
Expand Down Expand Up @@ -3225,6 +3243,9 @@ When `--json` is used, the output is a single JSON object:
{
"message": "Command file must export a register*Command function",
"file": "src/commands/broken.ts",
"line": 1,
"endLine": 1,
"endColumn": 42,
"severity": "error"
}
],
Expand All @@ -3235,6 +3256,22 @@ When `--json` is used, the output is a single JSON object:
}
```

#### Violation fields

| Field | Type | Description |
| ----------- | ------- | ------------------------------------------------------ |
| `message` | string | What the violation is |
| `file` | string? | Relative file path |
| `line` | number? | Start line (1-based) |
| `endLine` | number? | End line (1-based) — for precise editor highlighting |
| `endColumn` | number? | End column (0-based) — for precise editor highlighting |
| `fix` | string? | Suggested fix (guidance only) |
| `severity` | string | `"error"`, `"warning"`, or `"info"` |

#### Blocked rule files

When a rule file is blocked by the security scanner (e.g., uses `Bun.spawn()`) or a companion `.rules.ts` file is missing, the result appears in the JSON output with `status: "error"` and `ruleId: "security-scan"`. Violations include the exact file and line of the blocked code (or the `rules: true` line in the ADR for missing companions).

---

## archgate adr create
Expand Down Expand Up @@ -3718,16 +3755,22 @@ interface ReportDetail {
message: string;
file?: string;
line?: number;
endLine?: number;
endColumn?: number;
fix?: string;
}
```

| Field | Type | Required | Description |
| --------- | -------- | -------- | --------------------------------------- |
| `message` | `string` | Yes | Human-readable description of the issue |
| `file` | `string` | No | File path where the issue was found |
| `line` | `number` | No | Line number in the file |
| `fix` | `string` | No | Suggested fix or remediation action |
| Field | Type | Required | Description |
| ----------- | -------- | -------- | ------------------------------------------------------------------- |
| `message` | `string` | Yes | Human-readable description of the issue |
| `file` | `string` | No | File path where the issue was found |
| `line` | `number` | No | Start line number (1-based) |
| `endLine` | `number` | No | End line number (1-based) — for precise editor range highlighting |
| `endColumn` | `number` | No | End column number (0-based) — for precise editor range highlighting |
| `fix` | `string` | No | Suggested fix or remediation action |

When `endLine` and `endColumn` are provided, editors (VS Code, Cursor) can highlight the exact expression that violates the rule, rather than the entire line. If omitted, the full line at `line` is highlighted.

---

Expand Down Expand Up @@ -3778,20 +3821,24 @@ interface ViolationDetail {
message: string;
file?: string;
line?: number;
endLine?: number;
endColumn?: number;
fix?: string;
severity: Severity;
}
```

| Field | Type | Description |
| ---------- | ---------- | ------------------------------------ |
| `ruleId` | `string` | Rule ID from the `rules` object key |
| `adrId` | `string` | ADR ID from the frontmatter |
| `message` | `string` | Human-readable description |
| `file` | `string?` | File path where the issue was found |
| `line` | `number?` | Line number in the file |
| `fix` | `string?` | Suggested fix |
| `severity` | `Severity` | Effective severity of this violation |
| Field | Type | Description |
| ----------- | ---------- | ------------------------------------------------------ |
| `ruleId` | `string` | Rule ID from the `rules` object key |
| `adrId` | `string` | ADR ID from the frontmatter |
| `message` | `string` | Human-readable description |
| `file` | `string?` | File path where the issue was found |
| `line` | `number?` | Start line number (1-based) |
| `endLine` | `number?` | End line (1-based) — for precise editor highlighting |
| `endColumn` | `number?` | End column (0-based) — for precise editor highlighting |
| `fix` | `string?` | Suggested fix |
| `severity` | `Severity` | Effective severity of this violation |

---

Expand Down
51 changes: 44 additions & 7 deletions docs/src/content/docs/pt-br/reference/cli-commands.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -275,10 +275,10 @@ archgate plugin install --editor cursor
Executa todas as verificações automatizadas de conformidade com ADRs no codebase.

```bash
archgate check [options]
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.
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

Expand All @@ -290,13 +290,19 @@ Carrega cada ADR com `rules: true` no frontmatter, executa o arquivo `.rules.ts`
| `--adr <id>` | Verificar apenas regras de um ADR específico |
| `--verbose` | Mostrar regras aprovadas e informações de tempo |

### 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. |
| 2 | Erro interno (ex.: ADR ou regra malformada). |
| Código | Significado |
| ------ | ------------------------------------------------------------------------------------ |
| 0 | Todas as regras passaram. Nenhuma violação encontrada. |
| 1 | Uma ou mais violações detectadas. |
| 2 | Erro na execução de regra (ex.: regra malformada, bloqueio do scanner de segurança). |

### Exemplos

Expand All @@ -318,6 +324,18 @@ Verificar um único ADR:
archgate check --adr ARCH-001
```

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

```bash
archgate check src/foo.ts src/bar.ts
```

Pipe do git (verificar apenas arquivos alterados):

```bash
git diff --name-only | archgate check --json
```

Obter saída JSON para integração com CI:

```bash
Expand Down Expand Up @@ -357,6 +375,9 @@ Quando `--json` é usado, a saída é um único objeto JSON:
{
"message": "Command file must export a register*Command function",
"file": "src/commands/broken.ts",
"line": 1,
"endLine": 1,
"endColumn": 42,
"severity": "error"
}
],
Expand All @@ -367,6 +388,22 @@ Quando `--json` é usado, a saída é um único objeto JSON:
}
```

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

---

## archgate adr create
Expand Down
40 changes: 25 additions & 15 deletions docs/src/content/docs/pt-br/reference/rule-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -214,16 +214,22 @@ interface ReportDetail {
message: string;
file?: string;
line?: number;
endLine?: number;
endColumn?: number;
fix?: string;
}
```

| Campo | Tipo | Obrigatório | Descrição |
| --------- | -------- | ----------- | ------------------------------------------------- |
| `message` | `string` | Sim | Descrição legível do problema |
| `file` | `string` | Não | Caminho do arquivo onde o problema foi encontrado |
| `line` | `number` | Não | Número da linha no arquivo |
| `fix` | `string` | Não | Sugestão de correção ou ação de remediação |
| Campo | Tipo | Obrigatório | Descrição |
| ----------- | -------- | ----------- | ----------------------------------------------------------------- |
| `message` | `string` | Sim | Descrição legível do problema |
| `file` | `string` | Não | Caminho do arquivo onde o problema foi encontrado |
| `line` | `number` | Não | Número da linha inicial (base 1) |
| `endLine` | `number` | Não | Número da linha final (base 1) — para destaque preciso no editor |
| `endColumn` | `number` | Não | Número da coluna final (base 0) — para destaque preciso no editor |
| `fix` | `string` | Não | Sugestão de correção ou ação de remediação |

Quando `endLine` e `endColumn` são fornecidos, editores (VS Code, Cursor) podem destacar a expressão exata que viola a regra, em vez da linha inteira. Se omitidos, a linha completa em `line` é destacada.

---

Expand Down Expand Up @@ -274,20 +280,24 @@ interface ViolationDetail {
message: string;
file?: string;
line?: number;
endLine?: number;
endColumn?: number;
fix?: string;
severity: Severity;
}
```

| Campo | Tipo | Descrição |
| ---------- | ---------- | ------------------------------------------------- |
| `ruleId` | `string` | ID da regra da chave do objeto `rules` |
| `adrId` | `string` | ID do ADR do frontmatter |
| `message` | `string` | Descrição legível |
| `file` | `string?` | Caminho do arquivo onde o problema foi encontrado |
| `line` | `number?` | Número da linha no arquivo |
| `fix` | `string?` | Sugestão de correção |
| `severity` | `Severity` | Severidade efetiva desta violação |
| Campo | Tipo | Descrição |
| ----------- | ---------- | ------------------------------------------------------- |
| `ruleId` | `string` | ID da regra da chave do objeto `rules` |
| `adrId` | `string` | ID do ADR do frontmatter |
| `message` | `string` | Descrição legível |
| `file` | `string?` | Caminho do arquivo onde o problema foi encontrado |
| `line` | `number?` | Número da 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?` | Sugestão de correção |
| `severity` | `Severity` | Severidade efetiva desta violação |

---

Expand Down
51 changes: 44 additions & 7 deletions docs/src/content/docs/reference/cli-commands.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -277,10 +277,10 @@ archgate plugin install --editor cursor
Run all automated ADR compliance checks against the codebase.

```bash
archgate check [options]
archgate check [options] [files...]
```

Loads every ADR with `rules: true` in its frontmatter, executes the companion `.rules.ts` file, and reports violations with file paths and line numbers.
Loads every ADR with `rules: true` in its frontmatter, executes the companion `.rules.ts` file, and reports violations with file paths and line numbers. When file paths are provided as positional arguments, only ADRs whose `files` patterns match those files are executed.

### Options

Expand All @@ -292,13 +292,19 @@ Loads every ADR with `rules: true` in its frontmatter, executes the companion `.
| `--adr <id>` | Only check rules from a specific ADR |
| `--verbose` | Show passing rules and timing info |

### Arguments

| Argument | Description |
| ------------ | --------------------------------------------------------------------------------------------------------------- |
| `[files...]` | Optional file paths to scope checks to. Only ADRs whose `files` patterns match will run. Supports stdin piping. |

### Exit codes

| Code | Meaning |
| ---- | --------------------------------------------- |
| 0 | All rules pass. No violations found. |
| 1 | One or more violations detected. |
| 2 | Internal error (e.g., malformed ADR or rule). |
| 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). |

### Examples

Expand All @@ -320,6 +326,18 @@ Check a single ADR:
archgate check --adr ARCH-001
```

Check specific files (only matching ADRs run):

```bash
archgate check src/foo.ts src/bar.ts
```

Pipe from git (check only changed files):

```bash
git diff --name-only | archgate check --json
```

Get JSON output for CI integration:

```bash
Expand Down Expand Up @@ -359,6 +377,9 @@ When `--json` is used, the output is a single JSON object:
{
"message": "Command file must export a register*Command function",
"file": "src/commands/broken.ts",
"line": 1,
"endLine": 1,
"endColumn": 42,
"severity": "error"
}
],
Expand All @@ -369,6 +390,22 @@ When `--json` is used, the output is a single JSON object:
}
```

#### Violation fields

| Field | Type | Description |
| ----------- | ------- | ------------------------------------------------------ |
| `message` | string | What the violation is |
| `file` | string? | Relative file path |
| `line` | number? | Start line (1-based) |
| `endLine` | number? | End line (1-based) — for precise editor highlighting |
| `endColumn` | number? | End column (0-based) — for precise editor highlighting |
| `fix` | string? | Suggested fix (guidance only) |
| `severity` | string | `"error"`, `"warning"`, or `"info"` |

#### Blocked rule files

When a rule file is blocked by the security scanner (e.g., uses `Bun.spawn()`) or a companion `.rules.ts` file is missing, the result appears in the JSON output with `status: "error"` and `ruleId: "security-scan"`. Violations include the exact file and line of the blocked code (or the `rules: true` line in the ADR for missing companions).

---

## archgate adr create
Expand Down
Loading
Loading