ArchSentry

ArchSentry is an open-source CLI tool and GitHub App that enforces custom architectural contracts on every pull request. Built in TypeScript and published on npm, it runs deterministic scans in under 100ms with zero token cost, then optionally calls an LLM to generate targeted remediation hints only when a violation is found. The latest release is v0.4.0, published August 23, 2026, adding an Import Boundary Engine and multi-line matching.

What It Is

ArchSentry is a code architecture enforcement tool that sits between standard linters (ESLint, Biome) and AI review bots (Copilot PR, Codium). Where linters focus on style and syntax and SAST tools target known CVEs, ArchSentry enforces team-defined architectural invariants — rules like "controllers must not write directly to the database" or "module A may not import from module B." Rules are declared in a YAML file (archsentry.yml) at the repo root and evaluated deterministically on every scan.

Two-Phase Architecture

ArchSentry's design separates the expensive from the cheap:

• Deterministic Phase: Every file is matched against YAML contracts using sub-millisecond regex, glob-aware pattern matching, or AST queries via Semgrep. No LLM tokens are consumed here.
• Explanation Phase (optional): When a violation is detected, a short code snippet is sent to a configured LLM provider to generate a concise, contextual fix hint. This phase is opt-in via the --explain flag and supports OpenRouter (with free-tier models), OpenAI, local Ollama, or a built-in offline template engine as a zero-cost fallback.

Rule Types and Schema

Three rule engine backends are supported, each declared under rules[] in archsentry.yml:

• pattern — Zero-dependency substring/token matching across file paths defined by globs. Supports multiline: true for constructs that span multiple lines.
• semgrep — AST-aware queries using native Semgrep rule syntax (pattern, pattern-either, languages). Auto-upgrades when the Semgrep CLI is available on the host.
• import — Dependency boundary enforcement. Resolves relative imports to project paths before matching, so ../repositories/user from a controller is caught even without file extensions. Supports forbid, allow, and optional regex mode.

Each rule carries an id, description, severity (error or warn), and an optional remediation string that serves as ground truth for the AI explainer.

Deployment Models

ArchSentry supports three usage modes:

• Local CLI via npx — No installation required. Run npx archsentry scan --config archsentry.yml --path . in any repository. Exit codes are CI-standardized: 0 for clean, 1 for violations, 2 for runtime errors.
• GitHub Actions — Drop a workflow YAML into .github/workflows/ to gate pull requests. The OPENROUTER_API_KEY secret is optional and only needed for AI hints.
• GitHub App (Probot) — A self-hosted webhook listener that automatically reviews PRs, posts inline architectural remediation comments, and cleans up stale comments on subsequent pushes. Supports a ARCHSENTRY_FAIL_CLOSED=1 mode that posts a warning comment when rules cannot be verified, treating unverified rules as a blocker.

Update: v0.4.0 — Import Boundary Engine & Multi-Line Matching

The v0.4.0 release (August 23, 2026) introduced the Import Boundary Engine (type: import) and multi-line pattern matching (multiline: true). The import engine resolves relative specifiers to project paths before matching, closing a gap where indirect imports from forbidden modules could previously go undetected. Multi-line matching allows pattern rules to catch constructs like multi-line fetch() calls that span across lines in a file. The project is actively maintained with 13 open issues tracked on GitHub.