🛡️ ArchSentry

Enforce your team's architectural contracts on every pull request — deterministically, at zero scan token cost, with instant AI remediation.

---

⚡ Terminal Demo

$ npx archsentry scan --config archsentry.yml --path src --explain

❌ ArchSentry found 1 violation(s) (1 error, 0 warnings):

  • [error] no-direct-sql  src/controllers/user.controller.ts:7
    All database writes must go through the repository layer.
    > await db.query("INSERT INTO users (email, name) VALUES ($1, $2)", [payload.email, payload.name]);
    💡 Remediation: All database writes must go through the repository layer. Move this call
       behind the appropriate service or repository layer so the access path is centralized
       and reviewable, rather than issued directly from `src/controllers/user.controller.ts`.

$ echo $?
1

---

💡 Why ArchSentry?

AI coding assistants (Cursor, Copilot, Claude Code) generate thousands of lines of code per day. While standard linters catch syntax errors and SAST tools detect known CVE vulnerabilities, neither understands your system's architecture.

LLM review bots burn hundreds of dollars per repo summarizing diffs without guaranteeing architectural compliance.

ArchSentry solves this with a two-phase architecture:

1. Deterministic Phase (Zero Cost & Blazing Fast): Code is matched against your YAML contracts via sub-millisecond regex or AST/Semgrep patterns. No tokens are spent finding violations.
2. Explanation Phase (Optional & Free-Tier Compatible): When a violation is flagged, an LLM generates a concise, contextual remediation hint directly on the offending code snippet.

---

📊 Comparison Matrix

---

🚀 30-Second Quickstart

1. Local CLI Execution (npx)

No installation required. Run directly in any repository:

# Scan a path against your contract
npx archsentry scan --config archsentry.yml --path .

# With optional AI remediation hints:
npx archsentry scan --config archsentry.yml --path . --explain

# Filter findings to modified lines in a git diff:
git diff main...HEAD | npx archsentry scan --config archsentry.yml --diff -

Exit Codes (CI Standardized)

• 0: Clean scan. All architectural invariants satisfied.
• 1: Architectural violations detected (severity: error).
• 2: Runtime error (missing configuration file, malformed YAML, or invalid path).

---

2. Native GitHub Action Integration (Zero Infra)

Add .github/workflows/archsentry.yml to your repository:

name: ArchSentry Architectural Gate

on:
  pull_request:
    branches: [main, master, develop]
  push:
    branches: [main, master]

jobs:
  archsentry-scan:
    name: Architectural Integrity Gate
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Run ArchSentry Gate
        run: npx --yes archsentry scan --config archsentry.yml --path .
        env:
          # Optional: provides instant AI remediation hints on violations
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}

---

3. GitHub App Deployment (Automated PR Comments)

ArchSentry can also run as a dedicated Probot-powered GitHub App that automatically reviews PRs, posts inline architectural remediation comments, and cleans up stale comments upon push.

# Clone & install dependencies
pnpm install

# Configure credentials
cp .env.example .env
# Set APP_ID, WEBHOOK_SECRET, PRIVATE_KEY_PATH, and OPENROUTER_API_KEY

# Start Probot webhook listener
pnpm start

Fail-closed mode: by default the App logs (but does not surface) a failure to load archsentry.yml from a repo that has one. Set ARCHSENTRY_FAIL_CLOSED=1 to instead post a warning comment stating the rules were not verified — the right choice for teams that treat unverified rules as a blocker.

---

📜 Rule Schema Reference

Architectural contracts are declared in archsentry.yml at the root of your project:

version: 1

rules:
  # 1. Zero-dependency Pattern Matcher
  - id: no-direct-db-in-controllers
    type: pattern
    severity: error
    description: "Controllers must route data queries through the repository layer."
    match:
      patterns:
        - "db.query("
        - "connection.query("
        - "INSERT INTO"
        - "UPDATE "
        - "DELETE FROM"
      paths:
        - "src/controllers/**"
        - "apps/api/controllers/**"
      exclude:
        - "src/repositories/**"
        - "**/tests/**"

  # 2. AST-Aware Semgrep Matcher (Auto-upgrades when semgrep CLI is available)
  - id: no-raw-eval
    type: semgrep
    severity: error
    description: "Do not call eval() or new Function() in application code."
    semgrep:
      languages: ["typescript", "javascript"]
      pattern-either:
        - pattern: eval(...)
        - pattern: new Function(...)
      paths:
        include:
          - "src/**"
        exclude:
          - "**/*.spec.ts"

  # 3. Warning Severity Rule
  - id: avoid-console-log-in-production
    type: pattern
    severity: warn
    description: "Use structured logger (logger.info / logger.error) instead of console.log."
    match:
      patterns:
        - "console.log("
      paths:
        - "src/**"
      exclude:
        - "src/scripts/**"

  # 4. Dependency Boundary Rule (zero-dependency, understands imports)
  #    Files matching `from` may not import targets matching `forbid`.
  #    Relative imports are resolved to project paths first, so this catches
  #    "../repositories/user" from a controller even without file extensions.
  - id: controllers-import-only-domain
    type: import
    severity: error
    description: "Controllers may import only from their own domain and shared code."
    remediation: "Move shared logic into src/shared or the controller's own domain module."
    import:
      from: ["src/controllers/**"]
      forbid:
        - "src/repositories/**"
        - "src/other-domain/**"
      allow:
        - "src/shared/**"

  # 5. Multi-line Pattern Rule (matches across the whole file)
  - id: no-multiline-fetch
    type: pattern
    severity: error
    description: "No direct fetch calls, even when the call spans multiple lines."
    match:
      patterns:
        - "fetch("
      multiline: true
      paths:
        - "src/**"

Schema Attributes

---

🧠 Supported AI Explainer Providers

When --explain is enabled (or running via PR comment bot), ArchSentry derives remediation hints using whichever provider key is detected in the environment:

---

🛠️ Development & Testing

# Clone the repository
git clone https://github.com/comerade2134/archsentry.git
cd archsentry

# Install dependencies
pnpm install

# Run unit & integration test suites
pnpm test

# Typecheck and build standalone binary
pnpm typecheck
pnpm run build

---

📄 License

MIT © comerade2134