archgate check

Run all automated ADR compliance checks against the codebase.

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. When file paths are provided as positional arguments, only ADRs whose files patterns match those files are executed.

Options

Option	Description
--staged	Only check git-staged files (useful for pre-commit hooks)
--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

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	Rule execution error (e.g., malformed rule, security scanner block).

Examples

Check the entire project:

archgate check

Check only staged files before committing:

archgate check --staged

Check a single ADR:

archgate check --adr ARCH-001

Check specific files (only matching ADRs run):

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

Pipe from git (check only changed files):

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

Get JSON output for CI integration:

archgate check --json

Get GitHub Actions annotations:

archgate check --ci

JSON output format

When --json is used, the output is a single JSON object:

{
  "pass": false,
  "total": 4,
  "passed": 3,
  "failed": 1,
  "warnings": 0,
  "errors": 1,
  "infos": 0,
  "ruleErrors": 0,
  "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
}

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