# ArchSentry

> Enforce your team's architectural contracts on every pull request using deterministic pattern, AST, and import boundary rules — with optional AI remediation hints at zero scan token cost.

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.

## Features
- Deterministic architectural contract enforcement via YAML rules
- Zero scan token cost — LLM only invoked on violations with --explain flag
- Pattern matching engine (substring/token, glob path filtering, multiline support)
- AST-aware Semgrep engine integration (auto-upgrades when Semgrep CLI available)
- Import boundary enforcement with relative import resolution
- GitHub Actions integration with CI-standardized exit codes
- GitHub App (Probot) for automated PR inline comments
- AI remediation hints via OpenRouter, OpenAI, Ollama, or offline template fallback
- Fail-closed mode for unverified rule sets
- Sub-100ms scan latency
- npx zero-install execution
- Git diff filtering to scope findings to modified lines only

## Integrations
GitHub Actions, GitHub App (Probot), OpenRouter, OpenAI, Ollama, Semgrep, npm/npx, pnpm

## Platforms
CLI, API

## Pricing
Open Source

## Version
v0.4.0

## Links
- Website: https://github.com/comerade2134/archsentry
- Documentation: https://github.com/comerade2134/archsentry#readme
- Repository: https://github.com/comerade2134/archsentry
- EveryDev.ai: https://www.everydev.ai/tools/archsentry