{"slug": "show-hn-archsentry-deterministic-architectural-enforcement-for-ci", "title": "Show HN: ArchSentry – Deterministic architectural enforcement for CI", "summary": "ArchSentry, a new open-source tool launched on Hacker News, enforces architectural contracts in CI pipelines deterministically at zero scan token cost, using sub-millisecond regex or AST/Semgrep patterns to detect violations and optionally generating AI remediation hints via an LLM. The tool, which runs via `npx archsentry scan`, targets AI coding assistants like Cursor, Copilot, and Claude Code, and integrates with GitHub Actions and a Probot-powered GitHub App.", "body_md": "Enforce your team's architectural contracts on every pull request — deterministically, at zero scan token cost, with instant AI remediation.\n\n``` bash\n$ npx archsentry scan --config archsentry.yml --path src --explain\n\n❌ ArchSentry found 1 violation(s) (1 error, 0 warnings):\n\n  • [error] no-direct-sql  src/controllers/user.controller.ts:7\n    All database writes must go through the repository layer.\n    > await db.query(\"INSERT INTO users (email, name) VALUES ($1, $2)\", [payload.email, payload.name]);\n    💡 Remediation: All database writes must go through the repository layer. Move this call\n       behind the appropriate service or repository layer so the access path is centralized\n       and reviewable, rather than issued directly from `src/controllers/user.controller.ts`.\n\n$ echo $?\n1\n```\n\nAI 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**.\n\nLLM review bots burn hundreds of dollars per repo summarizing diffs without guaranteeing architectural compliance.\n\n**ArchSentry solves this with a two-phase architecture:**\n\n**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.**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.\n\n| Feature | Legacy SAST (SonarQube, Snyk) | Linters (ESLint, Biome) | AI Review Bots (Codium, Copilot PR) | 🛡️ ArchSentry |\n|---|---|---|---|---|\nPrimary Focus |\nKnown CVEs & security vulnerabilities | Code style, syntax, and formatting | Generic natural language commentary | Custom architectural boundaries & contracts |\nScan Cost |\nHeavy license fees | Free | $0.05–$0.50+ per PR diff in LLM tokens | $0 (Deterministic AST & Pattern Engine) |\nScan Latency |\n20s – 5 mins | < 1s | 15s – 60s (LLM API queue) | < 100ms |\nDeterministic Guarantee |\n✅ Yes | ✅ Yes | ❌ No (LLM hallucinations & flakiness) | ✅ 100% Deterministic |\nArchitectural Scope |\n❌ None (generic rules) | ✅ Declarative YAML Contracts |\n||\nActionable AI Fix Hints |\n❌ Generic docs link | ❌ Static message | ✅ Targeted, contextual fix explanations |\n\nNo installation required. Run directly in any repository:\n\n```\n# Scan a path against your contract\nnpx archsentry scan --config archsentry.yml --path .\n\n# With optional AI remediation hints:\nnpx archsentry scan --config archsentry.yml --path . --explain\n\n# Filter findings to modified lines in a git diff:\ngit diff main...HEAD | npx archsentry scan --config archsentry.yml --diff -\n```\n\n`0`\n\n: Clean scan. All architectural invariants satisfied.`1`\n\n: Architectural violations detected (severity:`error`\n\n).`2`\n\n: Runtime error (missing configuration file, malformed YAML, or invalid path).\n\nAdd `.github/workflows/archsentry.yml`\n\nto your repository:\n\n```\nname: ArchSentry Architectural Gate\n\non:\n  pull_request:\n    branches: [main, master, develop]\n  push:\n    branches: [main, master]\n\njobs:\n  archsentry-scan:\n    name: Architectural Integrity Gate\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout Code\n        uses: actions/checkout@v4\n\n      - name: Setup Node.js\n        uses: actions/setup-node@v4\n        with:\n          node-version: 20\n\n      - name: Run ArchSentry Gate\n        run: npx --yes archsentry scan --config archsentry.yml --path .\n        env:\n          # Optional: provides instant AI remediation hints on violations\n          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}\n```\n\nArchSentry 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.\n\n```\n# Clone & install dependencies\npnpm install\n\n# Configure credentials\ncp .env.example .env\n# Set APP_ID, WEBHOOK_SECRET, PRIVATE_KEY_PATH, and OPENROUTER_API_KEY\n\n# Start Probot webhook listener\npnpm start\n```\n\nArchitectural contracts are declared in `archsentry.yml`\n\nat the root of your project:\n\n```\nversion: 1\n\nrules:\n  # 1. Zero-dependency Pattern Matcher\n  - id: no-direct-db-in-controllers\n    type: pattern\n    severity: error\n    description: \"Controllers must route data queries through the repository layer.\"\n    match:\n      patterns:\n        - \"db.query(\"\n        - \"connection.query(\"\n        - \"INSERT INTO\"\n        - \"UPDATE \"\n        - \"DELETE FROM\"\n      paths:\n        - \"src/controllers/**\"\n        - \"apps/api/controllers/**\"\n      exclude:\n        - \"src/repositories/**\"\n        - \"**/tests/**\"\n\n  # 2. AST-Aware Semgrep Matcher (Auto-upgrades when semgrep CLI is available)\n  - id: no-raw-eval\n    type: semgrep\n    severity: error\n    description: \"Do not call eval() or new Function() in application code.\"\n    semgrep:\n      languages: [\"typescript\", \"javascript\"]\n      pattern-either:\n        - pattern: eval(...)\n        - pattern: new Function(...)\n      paths:\n        include:\n          - \"src/**\"\n        exclude:\n          - \"**/*.spec.ts\"\n\n  # 3. Warning Severity Rule\n  - id: avoid-console-log-in-production\n    type: pattern\n    severity: warn\n    description: \"Use structured logger (logger.info / logger.error) instead of console.log.\"\n    match:\n      patterns:\n        - \"console.log(\"\n      paths:\n        - \"src/**\"\n      exclude:\n        - \"src/scripts/**\"\n```\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n`version` |\n`number` |\nYes |\nContract schema version (must be `1` ). |\n`rules[].id` |\n`string` |\nYes |\nUnique identifier (`[a-zA-Z0-9_-]` ). |\n`rules[].type` |\n`\"pattern\"` | `\"semgrep\"` |\nYes |\nRule engine backend. `pattern` requires 0 external tools; `semgrep` runs AST queries. |\n`rules[].description` |\n`string` |\nYes |\nPlain-English rationale for the rule. |\n`rules[].severity` |\n`\"error\"` | `\"warn\"` |\nNo | Default `error` . `error` exits `1` ; `warn` informs without breaking the build. |\n`rules[].match.patterns` |\n`string[]` |\nYes (pattern) |\nSubstrings / tokens that trigger violations. |\n`rules[].match.paths` |\n`string[]` |\nNo | Globs specifying which file paths are subject to enforcement. |\n`rules[].match.exclude` |\n`string[]` |\nNo | Globs specifying paths exempt from this rule. |\n`rules[].semgrep` |\n`object` |\nYes (semgrep) |\nNative Semgrep rule definition object (`pattern` , `pattern-either` , `languages` ). |\n\nWhen `--explain`\n\nis enabled (or running via PR comment bot), ArchSentry derives remediation hints using whichever provider key is detected in the environment:\n\n| Provider | Environment Variable | Default Model | Notes |\n|---|---|---|---|\nOpenRouter |\n`OPENROUTER_API_KEY` |\n`nvidia/nemotron-3-ultra-550b-a55b:free` |\n100% Free Tiers Available (no card required) |\nOpenAI |\n`OPENAI_API_KEY` |\n`gpt-4o-mini` |\nHigh-speed, commercial grade |\nOllama |\n`OLLAMA_MODEL` |\nSet by env (e.g. `llama3` ) |\n100% Local & Air-gapped (`localhost:11434` ) |\nOffline Fallback |\n(None) |\nBuilt-in Template Engine | Zero-cost, zero-network deterministic hints |\n\n```\n# Clone the repository\ngit clone https://github.com/comerade2134/archsentry.git\ncd archsentry\n\n# Install dependencies\npnpm install\n\n# Run unit & integration test suites\npnpm test\n\n# Typecheck and build standalone binary\npnpm typecheck\npnpm run build\n```\n\nMIT © [comerade2134](https://github.com/comerade2134)", "url": "https://wpnews.pro/news/show-hn-archsentry-deterministic-architectural-enforcement-for-ci", "canonical_source": "https://github.com/comerade2134/archsentry", "published_at": "2026-08-23 09:53:53+00:00", "updated_at": "2026-08-23 10:14:00.442785+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "artificial-intelligence"], "entities": ["ArchSentry", "Cursor", "Copilot", "Claude Code", "GitHub Actions", "Probot", "OpenRouter"], "alternates": {"html": "https://wpnews.pro/news/show-hn-archsentry-deterministic-architectural-enforcement-for-ci", "markdown": "https://wpnews.pro/news/show-hn-archsentry-deterministic-architectural-enforcement-for-ci.md", "text": "https://wpnews.pro/news/show-hn-archsentry-deterministic-architectural-enforcement-for-ci.txt", "jsonld": "https://wpnews.pro/news/show-hn-archsentry-deterministic-architectural-enforcement-for-ci.jsonld"}}