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

| 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, or warnings exceeded --max-warnings. | | 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 all files changed on the current branch vs main:

archgate check --base main

Check a single ADR:

archgate check --adr ARCH-001

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

archgate check --max-warnings 0

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

Changed files detection

By default, archgate check auto-detects the base branch and populates ctx.changedFiles with the branch diff (git diff <base>...HEAD). This enables cross-file dependency rules to work locally — not just in CI.

The base ref is resolved in priority order:

| Priority | Source | changedFiles populated with | | -------- | ------------------------------------ | -------------------------------- | | 1 | --staged | Git staging area only | | 2 | --base <ref> | git diff <ref>...HEAD | | 3 | .archgate/config.json baseBranch | git diff <resolved-ref>...HEAD | | 4 | Git auto-detect | git diff <detected-ref>...HEAD | | 5 | Detection fails | Empty (full-scan mode) |

Auto-detection tries origin/HEAD, then origin/main, origin/master, local main, and local master. To set a project default, add baseBranch to .archgate/config.json:

{ "baseBranch": "main" }

Diagnostics

During execution, archgate check emits warnings for common misconfigurations that may cause slow or unexpected results:

| Warning | Condition | Recommendation | | ----------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- | | Broad file scope | An ADR’s files patterns resolve to more than 1,000 files or the glob scan takes over 2 seconds | Narrow the files patterns in the ADR frontmatter to target only the relevant source directories | | Unscoped gitignore opt-out | respectGitignore: false is set without a files scope | Add files patterns to avoid scanning all files including node_modules/, .git/, etc. | | All files excluded by gitignore | Explicit files patterns match files, but every match is excluded by .gitignore | Set respectGitignore: false in the ADR frontmatter to include gitignored files |

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:

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