eslint-plugin-ai-guard 1.2.8 → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.md +510 -260
  2. package/dist/cli/index.js +4358 -3762
  3. package/dist/cli/index.js.map +1 -1
  4. package/dist/index.d.mts +23 -5
  5. package/dist/index.d.ts +23 -5
  6. package/dist/index.js +260 -77
  7. package/dist/index.js.map +1 -1
  8. package/dist/index.mjs +259 -77
  9. package/dist/index.mjs.map +1 -1
  10. package/package.json +101 -97
package/README.md CHANGED
@@ -1,393 +1,643 @@
1
1
  <p align="center">
2
- <img src="./assets/logo.png" alt="AI Guard Logo" width="80" />
3
- <h1 align="center">eslint-plugin-ai-guard</h1>
4
- <p align="center">
5
- <strong>🛡️ GitHub-native guardrails for AI-generated code.</strong>
6
- </p>
7
- <p align="center">
8
- <a href="https://www.npmjs.com/package/eslint-plugin-ai-guard"><img src="https://img.shields.io/npm/v/eslint-plugin-ai-guard.svg?style=flat-square&color=7c3aed" alt="npm version"></a>
9
- <a href="https://github.com/YashJadhav21/eslint-plugin-ai-guard/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/YashJadhav21/eslint-plugin-ai-guard/ci.yml?style=flat-square&label=CI&color=10b981" alt="CI"></a>
10
- <a href="https://www.npmjs.com/package/eslint-plugin-ai-guard"><img src="https://img.shields.io/npm/dm/eslint-plugin-ai-guard.svg?style=flat-square&color=3b82f6" alt="downloads"></a>
11
- <a href="https://github.com/YashJadhav21/eslint-plugin-ai-guard/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/eslint-plugin-ai-guard.svg?style=flat-square&color=64748b" alt="MIT License"></a>
12
- <a href="https://github.com/YashJadhav21/eslint-plugin-ai-guard/blob/main/SECURITY.md"><img src="https://img.shields.io/badge/security-policy-orange?style=flat-square" alt="Security Policy"></a>
13
- </p>
2
+ <a href="https://getaiguard.dev">
3
+ <img src="./assets/logo/ai-guard-logo.png" alt="AI Guard Logo" width="260" />
4
+ </a>
5
+ </p>
6
+
7
+ <h1 align="center">AI Guard</h1>
8
+
9
+ <p align="center">
10
+ <strong>Deterministic AST safety layer and CI guardrails for AI-assisted JavaScript and TypeScript code.</strong>
11
+ </p>
12
+
13
+ <p align="center">
14
+ <a href="https://getaiguard.dev"><strong>Website</strong></a> &nbsp;•&nbsp;
15
+ <a href="https://www.npmjs.com/package/eslint-plugin-ai-guard"><strong>npm Package</strong></a> &nbsp;•&nbsp;
16
+ <a href="https://github.com/ai-guard-dev/eslint-plugin-ai-guard"><strong>GitHub Repository</strong></a> &nbsp;•&nbsp;
17
+ <a href="./docs/rules/"><strong>Rules Catalog</strong></a> &nbsp;•&nbsp;
18
+ <a href="./docs/benchmarks.md"><strong>Benchmarks</strong></a> &nbsp;•&nbsp;
19
+ <a href="./docs/integrations/claude-code.md"><strong>Claude Code</strong></a> &nbsp;•&nbsp;
20
+ <a href="./docs/getting-started.md"><strong>Documentation</strong></a>
21
+ </p>
22
+
23
+ <p align="center">
24
+ <a href="https://www.npmjs.com/package/eslint-plugin-ai-guard"><img src="https://img.shields.io/npm/v/eslint-plugin-ai-guard.svg?style=flat-square&color=0284c7" alt="npm version"></a>
25
+ <a href="https://github.com/ai-guard-dev/eslint-plugin-ai-guard/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/ai-guard-dev/eslint-plugin-ai-guard/ci.yml?style=flat-square&label=CI&color=10b981" alt="CI Status"></a>
26
+ <a href="https://www.npmjs.com/package/eslint-plugin-ai-guard"><img src="https://img.shields.io/npm/dm/eslint-plugin-ai-guard.svg?style=flat-square&color=3b82f6" alt="npm downloads"></a>
27
+ <a href="https://github.com/ai-guard-dev/eslint-plugin-ai-guard/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-64748b?style=flat-square" alt="MIT License"></a>
28
+ <a href="https://github.com/ai-guard-dev/eslint-plugin-ai-guard/blob/main/SECURITY.md"><img src="https://img.shields.io/badge/security-policy-orange?style=flat-square" alt="Security Policy"></a>
29
+ <a href="https://getaiguard.dev"><img src="https://img.shields.io/badge/website-getaiguard.dev-0ea5e9?style=flat-square" alt="Website"></a>
14
30
  </p>
15
31
 
16
32
  ---
17
33
 
18
- ## What is ai-guard?
34
+ ## What is AI Guard?
19
35
 
20
- **ai-guard** is an ESLint plugin and GitHub Action that catches reliability and security bugs
21
- specific to AI-generated code — the patterns Copilot, Claude, Cursor, and Gemini consistently get wrong.
36
+ **AI Guard** (`eslint-plugin-ai-guard`) is a deterministic ESLint plugin, CLI, and GitHub Action engineered to detect reliability bugs, async hazards, security vulnerabilities, and code-scaffolding defects frequently introduced during AI-assisted development (GitHub Copilot, Cursor, Claude Code, Gemini Code Assist, etc.).
22
37
 
23
- It integrates directly into GitHub pull request workflows: blocking dangerous merges, generating
24
- SARIF reports for GitHub Code Scanning, and posting inline PR annotations at the exact line where
25
- the bug lives.
38
+ AI Guard analyzes Abstract Syntax Trees (AST) using ESLint's native engine. It runs locally in your editor, in your terminal via the zero-config CLI, and in your CI/CD pipelines via native SARIF 2.1.0 integration with GitHub Code Scanning.
26
39
 
27
- ```bash
28
- # Scan immediately — no config needed
29
- npx ai-guard run
40
+ ### What AI Guard is NOT
30
41
 
31
- # PR-aware changed-only scan with GitHub Advanced Security
32
- npx ai-guard changed --sarif --sarif-output results.sarif
33
- ```
42
+ > [!IMPORTANT]
43
+ > - **AI Guard is NOT an AI detector.** It does not attempt to predict whether code was authored by an LLM or a human.
44
+ > - **AI Guard detects dangerous or fragile code patterns** that LLMs repeatedly introduce due to incomplete context, hallucinated patterns, or probabilistic generation.
45
+ > - **AI Guard does NOT replace ESLint.** It extends ESLint with 18 specialized, high-impact rules that core ESLint and standard configurations omit.
46
+
47
+ ---
34
48
 
35
- > [SCREENSHOT PLACEHOLDER — GitHub PR annotation showing ai-guard finding on a floating promise]
49
+ ## Why AI Guard?
50
+
51
+ AI coding assistants write code at remarkable velocity, but generated code repeatedly suffers from predictable reliability and security anti-patterns that conventional linters miss:
52
+
53
+ | Pattern | Why AI Assistants Generate It | Real-World Impact |
54
+ | :--- | :--- | :--- |
55
+ | **Floating Promises** | Omits `await`, `return`, or `.catch()` on async calls | Unhandled promise rejections, silent failures in background jobs |
56
+ | **Async Array Iteration** | Passes async callbacks into `array.map()` or `.filter()` | Returns unawaited `Promise[]` instead of resolved values |
57
+ | **Sequential Awaits in Loops** | Loops over items with sequential `await` | Significant latency bottlenecks; blocks event loop execution |
58
+ | **Empty Catch Blocks** | Inserts generic `try { ... } catch (e) {}` blocks | Swallows production exceptions silently without telemetry |
59
+ | **Hardcoded Secrets** | Injects placeholder or real API keys/tokens | Credential leakage in version control and deployment bundles |
60
+ | **Dynamic `eval()`** | Generates dynamic function compilation | Arbitrary code execution and code injection |
61
+ | **Raw SQL Concatenation** | Concatenates query strings with variables | Severe SQL injection vulnerabilities |
62
+ | **Unsafe Deserialization** | Calls `JSON.parse(req.body)` directly without schema checks | Denial of service and unhandled runtime crashes |
63
+ | **Missing Route Auth & Authz** | Emits boilerplate endpoints without auth middleware | Unprotected API endpoints and IDOR privilege escalations |
64
+ | **Dead Branches & Scaffolding** | Leaves `if (true)` or conflicting conditions from prompt iterations | Bloated bundles and dead code paths |
65
+
66
+ AI Guard provides an instantaneous, deterministic feedback loop that catches these issues before they reach pull requests or production.
36
67
 
37
68
  ---
38
69
 
39
- ## The Problem
70
+ ## Architecture & Workflow
71
+
72
+ ```mermaid
73
+ flowchart TD
74
+ subgraph Dev["1. Development & Prompt Phase"]
75
+ A["Developer + AI Coding Assistant\n(Copilot, Cursor, Claude Code)"] --> B["JavaScript / TypeScript Code"]
76
+ end
77
+
78
+ subgraph ShiftLeft["Shift Left — Context Injection"]
79
+ SL["npx ai-guard init-context"] -.-> CTX["CLAUDE.md\n.cursorrules\ncopilot-instructions.md"]
80
+ CTX -.-> A
81
+ end
82
+
83
+ subgraph Analysis["2. Deterministic AST Analysis"]
84
+ B --> C["ESLint Parser\n(espree / @typescript-eslint/parser)"]
85
+ C --> D["AST Representation"]
86
+ D --> E["AI Guard Rules Engine\n(18 Deterministic Rules)"]
87
+ end
88
+
89
+ subgraph Tiers["3. Classification & Presets"]
90
+ E --> F{"Active Preset\n(recommended | strict | security)"}
91
+ F --> G["Confidence Tiering & AST Filtering"]
92
+ end
93
+
94
+ subgraph Outputs["4. Output & Remediation"]
95
+ G --> H["Local CLI Scanning\n(ai-guard run / changed)"]
96
+ G --> I["Autofix Remediation\n(eslint --fix)"]
97
+ G --> J["HTML Dashboard\n(ai-guard report)"]
98
+ G --> K["SARIF 2.1.0 Artifact\n(ai-guard --sarif)"]
99
+ end
100
+
101
+ subgraph CI["5. GitHub Pull Request & CI/CD"]
102
+ K --> L["GitHub Action\nai-guard-dev/eslint-plugin-ai-guard@v1"]
103
+ L --> M["GitHub Code Scanning Alerts"]
104
+ L --> N["Inline PR Code Annotations"]
105
+ L --> O["PR Status Check (Blocks Merge)"]
106
+ end
107
+ ```
40
108
 
41
- AI coding assistants generate code that **looks correct but isn't.** The patterns they get wrong
42
- are consistent, predictable, and existing linters don't catch them:
109
+ ---
43
110
 
44
- | Pattern | Why AI Gets It Wrong |
45
- |---------|---------------------|
46
- | `try {} catch (e) {}` | AI adds catch blocks without handling the error |
47
- | `array.map(async ...)` | AI generates async callbacks returning `Promise[]`, not values |
48
- | `fetch(url)` without await | AI forgets to await or handle promise rejection |
49
- | `const apiKey = 'sk-...'` | AI uses placeholder credentials that get committed |
50
- | `eval(userInput)` | AI generates dynamic evaluation without security context |
51
- | `if (true) { ... }` | AI leaves dead scaffolding branches in generated code |
111
+ ## Rules Catalog
52
112
 
53
- ai-guard is purpose-built to catch what AI tools consistently get wrong — before those bugs reach production.
113
+ AI Guard includes **18 deterministic rules** divided into four specialized categories. Every rule is engineered with low false-positive heuristics and validated against real-world production codebases:
114
+
115
+ ### 🔴 Security (6 Rules)
116
+
117
+ | Rule | Recommended | What It Catches | Fixable? |
118
+ | :--- | :---: | :--- | :---: |
119
+ | [`no-hardcoded-secret`](./docs/rules/no-hardcoded-secret.md) | **`error`** | API keys, bearer tokens, passwords, and private keys committed directly in source code. | **Yes** (`process.env.*`) |
120
+ | [`no-eval-dynamic`](./docs/rules/no-eval-dynamic.md) | **`error`** | `eval()`, `new Function()`, and `setTimeout`/`setInterval` with dynamic/non-literal string expressions. | No |
121
+ | [`no-sql-string-concat`](./docs/rules/no-sql-string-concat.md) | `warn` | SQL queries constructed by string concatenation or raw template literals — SQL injection risks. | No |
122
+ | [`no-unsafe-deserialize`](./docs/rules/no-unsafe-deserialize.md) | `warn` | Unchecked `JSON.parse()` called directly on HTTP request inputs (`req.body`, `req.query`, `req.params`). | No |
123
+ | [`require-auth-middleware`](./docs/rules/require-auth-middleware.md) | `warn` | Express and Fastify route definitions exposed without authentication middleware. | No |
124
+ | [`require-authz-check`](./docs/rules/require-authz-check.md) | `warn` | Endpoints accessing sensitive resources or user IDs without tenant/ownership authorization checks. | No |
125
+
126
+ ### 🟠 Reliability (4 Rules)
127
+
128
+ | Rule | Recommended | What It Catches | Fixable? |
129
+ | :--- | :---: | :--- | :---: |
130
+ | [`no-empty-catch`](./docs/rules/no-empty-catch.md) | **`error`** | Empty `catch (e) {}` blocks that silently swallow exceptions without logging or rethrowing. | **Yes** (inserts `/* TODO: handle error */`) |
131
+ | [`no-broad-exception`](./docs/rules/no-broad-exception.md) | `warn` | Catching broad exception types like `catch (e: any)` that mask system faults and typing. | No |
132
+ | [`no-catch-log-rethrow`](./docs/rules/no-catch-log-rethrow.md) | `off`* | Catch blocks that only log to `console` and rethrow without adding context or diagnostic info. | No |
133
+ | [`no-catch-without-use`](./docs/rules/no-catch-without-use.md) | `off`* | Caught error variables that are declared in catch parameters but never referenced. | No |
134
+
135
+ ### 🟡 Async Stability (5 Rules)
136
+
137
+ | Rule | Recommended | What It Catches | Fixable? |
138
+ | :--- | :---: | :--- | :---: |
139
+ | [`no-floating-promise`](./docs/rules/no-floating-promise.md) | **`error`** | Async function invocations without `await`, `.catch()`, or `return` — leading to silent dropped errors. | **Yes** (marks with `void`) |
140
+ | [`no-async-array-callback`](./docs/rules/no-async-array-callback.md) | `warn` | Async callbacks passed to `map()`, `filter()`, `forEach()`, or `reduce()` returning `Promise[]`. | No |
141
+ | [`no-await-in-loop`](./docs/rules/no-await-in-loop.md) | `warn` | Sequential `await` in loops where iterations can be safely executed concurrently with `Promise.all`. | **Yes** (rewrites to `Promise.all`) |
142
+ | [`no-async-without-await`](./docs/rules/no-async-without-await.md) | `warn` | Functions declared `async` that never execute an `await` expression, adding unnecessary Promise overhead. | No |
143
+ | [`no-redundant-await`](./docs/rules/no-redundant-await.md) | `off`* | Redundant `return await` statements outside of `try...catch` blocks. | No |
144
+
145
+ ### 🔵 AI Patterns (3 Rules)
146
+
147
+ | Rule | Recommended | What It Catches | Fixable? |
148
+ | :--- | :---: | :--- | :---: |
149
+ | [`no-dead-branch`](./docs/rules/no-dead-branch.md) | `warn` | Unreachable or tautological branches (`if (true)`, `if (false)`, `x && !x`) left behind from LLM code synthesis. | No |
150
+ | [`no-duplicate-logic-block`](./docs/rules/no-duplicate-logic-block.md) | `off`* | Consecutive duplicate code blocks or repeated conditional branches duplicated during AI edits. | No |
151
+ | [`no-console-in-handler`](./docs/rules/no-console-in-handler.md) | `off`* | Unstructured `console.log` statements left in HTTP route handlers instead of production loggers. | No |
152
+
153
+ *\* Enabled at `error` level in the `strict` preset.*
54
154
 
55
155
  ---
56
156
 
57
- ## Install
157
+ ## Presets
58
158
 
59
- ```bash
60
- npm install --save-dev eslint-plugin-ai-guard
61
- ```
159
+ AI Guard exports four official configurations ready for flat config or legacy setups:
62
160
 
63
- **Requirements:** Node.js ≥ 18 · ESLint ≥ 8
161
+ | Preset | Description | Configuration Focus |
162
+ | :--- | :--- | :--- |
163
+ | **`recommended`** | **Default.** Balanced adoption preset. Enables 4 high-confidence critical rules at `error`, 9 context-sensitive rules at `warn`, and disables 5 noisy rules. Zero noise on day one. | Production codebases, new teams |
164
+ | **`strict`** | Enforces **all 18 rules at `error`**. Designed for zero-tolerance CI gates, high-assurance software, and mature teams. | Strict CI/CD quality gates |
165
+ | **`security`** | Focuses exclusively on the **6 security rules** (`no-hardcoded-secret`, `no-eval-dynamic`, `no-sql-string-concat` at `error`; remainder at `warn`). | AppSec auditing & security scans |
166
+ | **`agent`** | **5 high-signal rules at `error`**. Optimized for AI-agent editing workflows where lint feedback runs immediately after each file edit (e.g., PostToolUse hooks). | Claude Code, Cursor, real-time agent loops |
64
167
 
65
168
  ---
66
169
 
67
- ## Quick Start
170
+ ## Quick Start & Installation
171
+
172
+ Install the package as a development dependency using your package manager:
68
173
 
69
174
  ```bash
70
- # Zero-config project scan
71
- npx ai-guard run
175
+ # npm
176
+ npm install --save-dev eslint-plugin-ai-guard
72
177
 
73
- # Security-focused scan
74
- npx ai-guard run --security
178
+ # pnpm
179
+ pnpm add -D eslint-plugin-ai-guard
75
180
 
76
- # Strict mode — all 18 rules at error
77
- npx ai-guard run --strict
181
+ # yarn
182
+ yarn add -D eslint-plugin-ai-guard
78
183
 
79
- # Scan only changed files (PR-aware)
80
- npx ai-guard changed --pr
184
+ # bun
185
+ bun add -d eslint-plugin-ai-guard
81
186
  ```
82
187
 
83
- **No configuration required.** ai-guard ships with a production-tuned `recommended` preset.
188
+ ### Requirements
189
+
190
+ - **Node.js:** `>= 20.0.0`
191
+ - **ESLint:** `>= 8.0.0` (Supports both Flat Config and legacy configs)
192
+ - **TypeScript (optional):** `@typescript-eslint/parser >= 6.0.0` for TypeScript AST parsing
84
193
 
85
194
  ---
86
195
 
87
- ## GitHub Actions Integration
196
+ ## ESLint Configuration
88
197
 
89
- Drop this into any repository to get PR validation, SARIF-based Code Scanning, and
90
- GitHub Advanced Security integration in under 5 minutes:
198
+ ### 1. Modern Flat Config (`eslint.config.mjs` / `eslint.config.js`)
91
199
 
92
- ```yaml
93
- # .github/workflows/ai-guard.yml
94
- name: AI Guard
200
+ AI Guard exports full native support for modern ESLint Flat Config:
95
201
 
96
- on: [pull_request]
202
+ ```javascript
203
+ // eslint.config.mjs
204
+ import aiGuard from 'eslint-plugin-ai-guard';
97
205
 
98
- permissions:
99
- security-events: write
100
- contents: read
206
+ export default [
207
+ {
208
+ plugins: {
209
+ 'ai-guard': aiGuard,
210
+ },
211
+ rules: {
212
+ ...aiGuard.configs.recommended.rules,
213
+ // Custom overrides if desired:
214
+ 'ai-guard/no-floating-promise': 'error',
215
+ },
216
+ },
217
+ ];
218
+ ```
101
219
 
102
- jobs:
103
- scan:
104
- runs-on: ubuntu-latest
105
- steps:
106
- - uses: actions/checkout@v4
107
- with:
108
- fetch-depth: 0 # Required for changed-file detection
220
+ To use the `strict` or `security` preset in flat config:
109
221
 
110
- - uses: actions/setup-node@v4
111
- with:
112
- node-version: 20
113
- cache: 'npm'
222
+ ```javascript
223
+ // Strict preset — all 18 rules at error
224
+ rules: {
225
+ ...aiGuard.configs.strict.rules,
226
+ }
114
227
 
115
- - run: npm ci
228
+ // Security preset — security rules only
229
+ rules: {
230
+ ...aiGuard.configs.security.rules,
231
+ }
232
+ ```
116
233
 
117
- - name: Scan changed files
118
- run: |
119
- npx ai-guard changed \
120
- --pr \
121
- --strict \
122
- --sarif \
123
- --sarif-output ai-guard-results.sarif \
124
- --fail-on high
234
+ ### 2. Legacy Config (`.eslintrc.js` / `.eslintrc.json`)
125
235
 
126
- - name: Upload to GitHub Code Scanning
127
- uses: github/codeql-action/upload-sarif@v3
128
- if: always()
129
- with:
130
- sarif_file: ai-guard-results.sarif
131
- category: ai-guard
236
+ ```javascript
237
+ // .eslintrc.js
238
+ module.exports = {
239
+ plugins: ['ai-guard'],
240
+ extends: ['plugin:ai-guard/recommended'],
241
+ };
132
242
  ```
133
243
 
134
- This produces:
135
- - ✅ Inline PR annotations at the exact line of each finding
136
- - ✅ GitHub Advanced Security summary ("4 new alerts including 1 high severity")
137
- - ✅ Persistent alerts in `Security → Code scanning`
138
- - ✅ PR status check that blocks merges on high-severity findings
244
+ ---
139
245
 
140
- > [SCREENSHOT PLACEHOLDER — GitHub Advanced Security summary showing ai-guard findings]
246
+ ## CLI Reference
141
247
 
142
- > [SCREENSHOT PLACEHOLDER — GitHub Code Scanning view with persistent ai-guard alerts]
248
+ AI Guard includes a full-featured CLI binary (`ai-guard`) that runs out of the box with zero ESLint configuration files required:
143
249
 
144
- > [SCREENSHOT PLACEHOLDER — PR check failing due to high-severity ai-guard finding]
250
+ ```bash
251
+ npx ai-guard <command> [options]
252
+ ```
145
253
 
146
- See [`docs/github-actions.md`](./docs/github-actions.md) for the complete workflow reference
147
- including full-scan mode, baseline mode, and SARIF debugging.
254
+ ### Core Commands
148
255
 
149
- ---
256
+ | Command | Purpose | Common Options |
257
+ | :--- | :--- | :--- |
258
+ | `run` | Scan your workspace using AI Guard AST rules | `--path <dir>`, `--strict`, `--security`, `--json`, `--sarif`, `--fail-on <level>`, `--max-warnings <n>` |
259
+ | `changed` | Fast CI scan — only scans modified files in git | `--pr`, `--staged`, `--base <branch>`, `--strict`, `--sarif`, `--sarif-output <file>`, `--fail-on <level>` |
260
+ | `init` | Automatically detect environment & configure ESLint | `--preset <name>`, `--flat`, `--dry-run`, `-y, --yes` |
261
+ | `init-context` | Generate prompt instruction files for AI coding agents | `-a, --all`, `--force`, `--dry-run`, `--rules <categories>` |
262
+ | `doctor` | Diagnose your ESLint, parser, and plugin environment | (No options needed — prints actionable diagnostic report) |
263
+ | `baseline` | Snapshot current issues to track only new regressions | `--save`, `--check`, `--mode <strict\|stable>`, `--preset <name>` |
264
+ | `report` | Generate an interactive standalone HTML audit report | `--path <dir>`, `--preset <name>`, `--output <file>`, `--no-open`, `--json` |
265
+ | `preset` | Interactively select and switch active preset in config | (Interactive prompt with automatic config patch & backup) |
266
+ | `ignore` | Add standard ignore paths (`.next`, `dist`, `build`) to config | (Patches flat config or legacy ignores safely) |
150
267
 
151
- ## CLI Commands
152
-
153
- | Command | Description |
154
- |---------|-------------|
155
- | `ai-guard run` | Scan your project with the recommended preset |
156
- | `ai-guard run --strict` | All 18 rules at error — for CI enforcement |
157
- | `ai-guard run --security` | Security rules only |
158
- | `ai-guard run --sarif` | Output SARIF for GitHub Code Scanning |
159
- | `ai-guard run --json` | Output results as JSON (CI-friendly) |
160
- | `ai-guard changed --pr` | Scan only files changed in this PR |
161
- | `ai-guard changed --staged` | Scan only staged files (pre-commit hook) |
162
- | `ai-guard init` | Auto-configure ESLint for your project |
163
- | `ai-guard init-context` | Generate AI agent rules (CLAUDE.md, .cursorrules, etc.) |
164
- | `ai-guard baseline` | Save current issues, track only new ones going forward |
165
- | `ai-guard report` | Generate a shareable HTML report |
166
- | `ai-guard doctor` | Diagnose your ESLint and ai-guard setup |
167
-
168
- ### Fail Strategies
268
+ ### CLI Usage Examples
169
269
 
170
270
  ```bash
171
- --fail-on errors # Fail on any error-level finding (default)
172
- --fail-on high # Fail only on high-severity findings
173
- --fail-on none # Never fail — always continue
174
- --max-warnings 0 # Fail on any warning
175
- ```
271
+ # 1. Immediate scan of current directory
272
+ npx ai-guard run
273
+
274
+ # 2. Strict CI scan failing only on high-confidence issues
275
+ npx ai-guard run --strict --fail-on high
176
276
 
177
- ### Example Output
277
+ # 3. Pull Request scan (diffs against PR target branch)
278
+ npx ai-guard changed --pr --sarif --sarif-output results.sarif
178
279
 
280
+ # 4. Generate AI agent guardrails for Cursor, Claude Code, and Copilot
281
+ npx ai-guard init-context --all
282
+
283
+ # 5. Generate interactive HTML diagnostic report
284
+ npx ai-guard report --output ai-guard-report.html
285
+
286
+ # 6. Save existing issues as baseline and only fail on new regressions
287
+ npx ai-guard baseline --save
288
+ npx ai-guard baseline --check
179
289
  ```
180
- AI GUARD
181
290
 
182
- Files scanned: 142 · Issues in: 7 files · Duration: 312ms · Preset: strict
291
+ ---
183
292
 
184
- ── Summary by Category ──
293
+ ## AI Agent Integration (`init-context`)
185
294
 
186
- 🔴 Security 3 errors
187
- 🟠 Reliability 2 errors
188
- 🟡 Async Stability 2 warnings
295
+ Standard linters only run **after** code has already been written. The `init-context` command shifts your guardrails left by embedding AI Guard's rules directly into the instruction files loaded by your AI coding tools:
189
296
 
190
- Total: 5 errors · 2 warnings
297
+ ```bash
298
+ npx ai-guard init-context --all
299
+ ```
191
300
 
192
- ── By Rule ──
193
- • no-hardcoded-secret: 3
194
- • no-empty-catch: 2
195
- • no-floating-promise: 2
301
+ This generates three targeted context files:
302
+ 1. **`CLAUDE.md`** — Automatically loaded by **Claude Code**
303
+ 2. **`.cursorrules`** — Automatically loaded by **Cursor**
304
+ 3. **`.github/copilot-instructions.md`** — Automatically loaded by **GitHub Copilot**
196
305
 
197
- ── Next Steps ──
198
- ℹ Run ai-guard baseline to save these issues and track only new ones
199
- ℹ Run ai-guard report to generate a shareable HTML report
306
+ ### How Shift-Left Works
307
+
308
+ ```
309
+ AI Guard (init-context)
310
+ ↓
311
+ Generates project guardrail files (CLAUDE.md, .cursorrules, copilot-instructions.md)
312
+ ↓
313
+ AI coding assistant reads safety rules before generating code
314
+ ↓
315
+ Model avoids floating promises, empty catches, and hardcoded secrets at prompt time
316
+ ↓
317
+ AI Guard CLI & GitHub Action deterministically verifies the output in CI
200
318
  ```
201
319
 
320
+ This dual-layer defense minimizes review friction and ensures generated code meets your security standard on the first pass.
321
+
202
322
  ---
203
323
 
204
- ## Rules
324
+ ## Claude Code Integration
325
+
326
+ AI Guard integrates directly with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) as a **PostToolUse validation hook**. Every time Claude Code edits or writes a JS/TS file, AI Guard automatically scans it for common issues.
205
327
 
206
- ### 🔴 Security
328
+ ```bash
329
+ # One-command setup
330
+ npx ai-guard init-claude
331
+ ```
207
332
 
208
- | Rule | Recommended | What it catches |
209
- |------|------------|------------------|
210
- | [`no-hardcoded-secret`](./docs/rules/no-hardcoded-secret.md) | **error** | API keys, passwords, tokens in source. Autofix: `process.env.*` |
211
- | [`no-eval-dynamic`](./docs/rules/no-eval-dynamic.md) | **error** | `eval()` / `new Function()` with non-literal args |
212
- | [`no-sql-string-concat`](./docs/rules/no-sql-string-concat.md) | warn | SQL built by string concatenation — SQL injection risk |
213
- | [`no-unsafe-deserialize`](./docs/rules/no-unsafe-deserialize.md) | warn | `JSON.parse(req.body)` without validation |
214
- | [`require-auth-middleware`](./docs/rules/require-auth-middleware.md) | warn | Express/Fastify routes without authentication middleware |
215
- | [`require-authz-check`](./docs/rules/require-authz-check.md) | warn | Resource access without ownership checks |
333
+ This configures a PostToolUse hook in `.claude/settings.json` that runs AI Guard's fast `agent` preset (5 high-confidence rules, ~50-200ms per file) after every file edit. Claude Code reads the diagnostics and can fix issues automatically.
216
334
 
217
- ### 🟠 Reliability
335
+ ```bash
336
+ # Preview before applying
337
+ npx ai-guard init-claude --dry-run
218
338
 
219
- | Rule | Recommended | What it catches |
220
- |------|------------|------------------|
221
- | [`no-empty-catch`](./docs/rules/no-empty-catch.md) | **error** | `catch (e) {}` — errors silently vanish. Autofix: inserts TODO |
222
- | [`no-broad-exception`](./docs/rules/no-broad-exception.md) | warn | `catch (e: any)` that hides the real error type |
223
- | [`no-catch-log-rethrow`](./docs/rules/no-catch-log-rethrow.md) | off* | Catch blocks that only `console.log` + rethrow |
224
- | [`no-catch-without-use`](./docs/rules/no-catch-without-use.md) | off* | Caught error variable never used |
339
+ # Use per-machine settings (gitignored)
340
+ npx ai-guard init-claude --local
341
+ ```
225
342
 
226
- ### 🟡 Async Stability
343
+ **Agent preset rules:** `no-hardcoded-secret`, `no-eval-dynamic`, `no-empty-catch`, `no-sql-string-concat`, `no-floating-promise`
227
344
 
228
- | Rule | Recommended | What it catches |
229
- |------|------------|------------------|
230
- | [`no-floating-promise`](./docs/rules/no-floating-promise.md) | **error** | Async calls with no `await`, return, or `.catch()`. Autofix: adds `void` |
231
- | [`no-async-array-callback`](./docs/rules/no-async-array-callback.md) | warn | `array.map(async ...)` — returns `Promise[]` not values |
232
- | [`no-await-in-loop`](./docs/rules/no-await-in-loop.md) | warn | Sequential `await` in loops — use `Promise.all` |
233
- | [`no-async-without-await`](./docs/rules/no-async-without-await.md) | warn | `async` function that never uses `await` |
234
- | [`no-redundant-await`](./docs/rules/no-redundant-await.md) | off* | `return await` outside try/catch |
345
+ → [Full documentation](./docs/integrations/claude-code.md)
235
346
 
236
- ### 🔵 AI Patterns
347
+ ---
237
348
 
238
- | Rule | Recommended | What it catches |
239
- |------|------------|------------------|
240
- | [`no-dead-branch`](./docs/rules/no-dead-branch.md) | warn | `if (true)`, `if (false)`, `x && !x` — scaffolding leftovers |
241
- | [`no-duplicate-logic-block`](./docs/rules/no-duplicate-logic-block.md) | off* | Consecutive duplicate code blocks |
242
- | [`no-console-in-handler`](./docs/rules/no-console-in-handler.md) | off* | `console.log` in route handlers — use a logger |
349
+ ## GitHub Action
243
350
 
244
- *Enabled at `error` in the `strict` preset.
351
+ The official AI Guard GitHub Action runs on PRs, detects changed files, provides step summaries, outputs SARIF 2.1.0, and posts inline PR annotations directly on GitHub:
245
352
 
246
- Full rule documentation: [`docs/rules/`](./docs/rules/)
353
+ ```yaml
354
+ # .github/workflows/ai-guard.yml
355
+ name: AI Guard
247
356
 
248
- ---
357
+ on:
358
+ pull_request:
359
+ branches: [main, develop]
360
+ push:
361
+ branches: [main]
249
362
 
250
- ## Presets
363
+ jobs:
364
+ ai-guard-scan:
365
+ name: AI Guard Code Review
366
+ runs-on: ubuntu-latest
251
367
 
252
- | Preset | Purpose | Best For |
253
- |--------|---------|----------|
254
- | `recommended` | Critical issues at `error`, context-sensitive at `warn` | All projects on day one |
255
- | `strict` | All 18 rules at `error` | CI enforcement in mature codebases |
256
- | `security` | Security rules only | Security-focused scanning |
368
+ permissions:
369
+ contents: read
370
+ security-events: write
371
+ actions: read
257
372
 
258
- ### ESLint Flat Config
373
+ steps:
374
+ - name: Checkout Code
375
+ uses: actions/checkout@v4
376
+ with:
377
+ fetch-depth: 0 # Required for git diff comparison
259
378
 
260
- ```javascript
261
- // eslint.config.mjs
262
- import aiGuard from 'eslint-plugin-ai-guard';
379
+ - name: Setup Node.js
380
+ uses: actions/setup-node@v4
381
+ with:
382
+ node-version: 20
383
+ cache: 'npm'
263
384
 
264
- export default [
265
- {
266
- plugins: { 'ai-guard': aiGuard },
267
- rules: { ...aiGuard.configs.recommended.rules },
268
- },
269
- ];
385
+ - name: Run AI Guard
386
+ uses: ai-guard-dev/eslint-plugin-ai-guard@v1
387
+ with:
388
+ preset: 'recommended'
389
+ fail-on: 'high'
390
+ changed-only: 'true'
391
+ upload-sarif: 'true'
270
392
  ```
271
393
 
394
+ ### Action Inputs (`action.yml`)
395
+
396
+ | Input | Description | Default |
397
+ | :--- | :--- | :---: |
398
+ | `preset` | Rule preset: `recommended` \| `strict` \| `security` | `'recommended'` |
399
+ | `fail-on` | Severity threshold to fail CI: `high` \| `medium` \| `any` \| `none` | `'high'` |
400
+ | `changed-only` | Scan only files changed in this PR / commit | `'true'` |
401
+ | `path` | Target file or directory to scan | `'.'` |
402
+ | `upload-sarif` | Upload results to GitHub Code Scanning | `'true'` |
403
+ | `github-summary` | Write an execution breakdown to the GitHub Actions Job Summary | `'true'` |
404
+ | `working-directory`| Working directory for scanning (ideal for monorepos) | `'.'` |
405
+ | `package-manager` | Package manager: `auto` \| `npm` \| `pnpm` \| `yarn` | `'auto'` |
406
+ | `sarif-output` | Output filepath for generated SARIF report | `'ai-guard-results.sarif'` |
407
+ | `install-deps` | Install project dependencies prior to scanning | `'true'` |
408
+
409
+ ### Action Outputs
410
+
411
+ | Output | Description |
412
+ | :--- | :--- |
413
+ | `issues-found` | Total number of issues found across scanned files |
414
+ | `high-confidence-count` | Number of high-confidence issues flagged |
415
+ | `medium-confidence-count` | Number of medium-confidence issues flagged |
416
+ | `files-scanned` | Count of files analyzed during the execution |
417
+ | `sarif-file` | Absolute path to the generated SARIF 2.1.0 artifact |
418
+ | `duration-ms` | Total scan execution duration in milliseconds |
419
+
272
420
  ---
273
421
 
274
- ## AI Agent Integration
422
+ ## SARIF & GitHub Code Scanning
275
423
 
276
- Generate instruction files so **Claude Code, Cursor, and GitHub Copilot** automatically avoid
277
- the 18 most common AI-generated anti-patterns at generation time:
424
+ AI Guard natively outputs **SARIF 2.1.0** (`Static Analysis Results Interchange Format`). When uploaded via the GitHub Action or `github/codeql-action/upload-sarif@v3`, findings integrate directly with GitHub Advanced Security:
278
425
 
279
- ```bash
280
- npx ai-guard init-context
281
- ```
426
+ - **Inline PR Annotations:** Direct comments on the exact source lines where flaws exist.
427
+ - **Security Dashboard:** Persistent alerts under your repository's `Security → Code scanning` tab.
428
+ - **Merge Protection:** Block merges automatically when high-confidence security or async bugs are detected.
282
429
 
283
- This writes:
284
- - `CLAUDE.md` — loaded automatically by Claude Code
285
- - `.cursorrules` — loaded automatically by Cursor
286
- - `.github/copilot-instructions.md` — loaded automatically by GitHub Copilot
430
+ ### Visual Previews
287
431
 
288
- Your AI tools will avoid these patterns **before you even run the linter.**
432
+ #### Inline Pull Request Annotations
433
+ <img src="./assets/ss9.jpg" alt="AI Guard PR Inline Annotations" width="1000" />
289
434
 
290
- See [`docs/ai-agents.md`](./docs/ai-agents.md) for the complete integration guide.
435
+ #### GitHub Advanced Security Summary
436
+ <img src="./assets/ss10.jpg" alt="GitHub Advanced Security Summary for AI Guard" width="1000" />
437
+
438
+ #### Persistent Code Scanning Dashboard
439
+ <img src="./assets/ss11.jpg" alt="GitHub Code Scanning Alerts List" width="1000" />
291
440
 
292
441
  ---
293
442
 
294
- ## Real-World Example
443
+ ## Rule Examples (Before & After)
444
+
445
+ ### 1. `no-floating-promise` (Unhandled Promises)
295
446
 
296
447
  ```typescript
297
- // ❌ Typical AI-generated code — 4 issues in one function
298
- async function processUserOrders(userId: string) {
299
- const apiKey = 'sk-prod-1234567890abcdef'; // no-hardcoded-secret
448
+ // ❌ BAD: Floating promise. Errors are dropped silently.
449
+ async function syncUserProfile(user: User) {
450
+ sendTelemetryEvent('user_sync', user.id);
451
+ database.save(user);
452
+ }
300
453
 
301
- const orders = await db.query(
302
- 'SELECT * FROM orders WHERE id = ' + userId // no-sql-string-concat
303
- );
454
+ // ✅ GOOD: Awaited, explicitly handled, or marked with void
455
+ async function syncUserProfile(user: User) {
456
+ await database.save(user);
457
+ void sendTelemetryEvent('user_sync', user.id); // Explicitly unhandled
458
+ }
459
+ ```
304
460
 
305
- for (const order of orders) {
306
- await sendEmail(order.email); // no-await-in-loop
461
+ ### 2. `no-hardcoded-secret` (Committed Credentials)
462
+
463
+ ```typescript
464
+ // ❌ BAD: Secret committed inline
465
+ const client = new PaymentGateway({
466
+ apiKey: 'sk-prod-983427598273498273948273',
467
+ });
468
+
469
+ // ✅ GOOD: Read from environment variable (Autofixable!)
470
+ const client = new PaymentGateway({
471
+ apiKey: process.env.API_KEY,
472
+ });
473
+ ```
474
+
475
+ ### 3. `no-await-in-loop` (Sequential Latency Trap)
476
+
477
+ ```typescript
478
+ // ❌ BAD: Consecutive awaits block each iteration sequentially
479
+ async function fetchAllUsers(ids: string[]) {
480
+ const users = [];
481
+ for (const id of ids) {
482
+ users.push(await fetchUser(id));
307
483
  }
484
+ return users;
485
+ }
308
486
 
309
- updateAnalytics(userId); // no-floating-promise
487
+ // ✅ GOOD: Concurrently fetched with Promise.all (Autofixable!)
488
+ async function fetchAllUsers(ids: string[]) {
489
+ return await Promise.all(ids.map((id) => fetchUser(id)));
310
490
  }
491
+ ```
492
+
493
+ ### 4. `no-empty-catch` (Swallowed Errors)
311
494
 
312
- // ✅ After ai-guard fixes
313
- async function processUserOrders(userId: string) {
314
- const apiKey = process.env.API_KEY;
495
+ ```typescript
496
+ // ❌ BAD: Exception swallowed without trace
497
+ try {
498
+ parseConfiguration(rawConfig);
499
+ } catch (e) {}
500
+
501
+ // ✅ GOOD: Logged, rethrown, or documented (Autofixable!)
502
+ try {
503
+ parseConfiguration(rawConfig);
504
+ } catch (e) {
505
+ logger.error('Configuration parsing failed', { error: e });
506
+ throw e;
507
+ }
508
+ ```
315
509
 
316
- const orders = await db.query(
317
- 'SELECT * FROM orders WHERE id = $1', [userId]
318
- );
510
+ ### 5. `no-sql-string-concat` (SQL Injection)
319
511
 
320
- await Promise.all(orders.map(async (order) => sendEmail(order.email)));
512
+ ```typescript
513
+ // ❌ BAD: Dynamic string interpolation in SQL
514
+ const query = `SELECT * FROM users WHERE organization_id = '${orgId}' AND role = '${role}'`;
515
+ await db.query(query);
321
516
 
322
- void updateAnalytics(userId);
323
- }
517
+ // ✅ GOOD: Parameterized query binding
518
+ const query = 'SELECT * FROM users WHERE organization_id = $1 AND role = $2';
519
+ await db.query(query, [orgId, role]);
324
520
  ```
325
521
 
326
522
  ---
327
523
 
328
- ## Autofix Support
524
+ ## Automatic Remediation (Autofix)
525
+
526
+ Rules that have deterministic solutions provide automatic autofix handlers. Run ESLint's native `--fix` flag to automatically resolve them:
329
527
 
330
528
  ```bash
331
- npx eslint src --fix
529
+ npx eslint . --fix
332
530
  ```
333
531
 
334
- | Rule | What Gets Fixed |
335
- |------|-----------------|
336
- | `no-hardcoded-secret` | Literal → `process.env.VAR_NAME` |
337
- | `no-empty-catch` | Inserts `/* TODO: handle error */` |
338
- | `no-floating-promise` | Marks with `void` |
339
- | `no-await-in-loop` | Rewrites simple loops to `Promise.all(...)` |
340
- | `no-async-without-await` | Removes unnecessary `async` keyword |
532
+ | Rule | Automatic Fix Behavior |
533
+ | :--- | :--- |
534
+ | `no-hardcoded-secret` | Replaces hardcoded string literal with `process.env.VARIABLE_NAME` |
535
+ | `no-empty-catch` | Inserts `/* TODO: handle error */` comment to prevent silent swallowing |
536
+ | `no-floating-promise` | Prepends `void ` expression to intentionally unawaited calls |
537
+ | `no-await-in-loop` | Rewrites straightforward sequential loops to `await Promise.all(...)` |
341
538
 
342
539
  ---
343
540
 
344
- ## Philosophy
541
+ ## Benchmarks & Empirical Evaluation
542
+
543
+ AI Guard has been empirically evaluated across multiple benchmarks comparing runtime scan performance, coverage gaps vs. standard tooling, and detection accuracy across real-world codebases.
345
544
 
346
- - **Precision over recall** — we'd rather miss a bug than create noise
347
- - **Low false positives** — a rule that fires on valid code goes to `warn` or gets disabled
348
- - **Gradual adoption** — `recommended` is safe for day-one; `strict` is opt-in
349
- - **Self-validating** — ai-guard scans its own source in CI with the strict preset
350
- - **GitHub-native** — SARIF output, Code Scanning, PR annotations are first-class features
545
+ ### 1. What AI Guard Catches vs. Conventional Linters
546
+
547
+ Conventional linters either omit AI-specific hazards entirely or require heavyweight TypeScript type-checking (`parserOptions.project`) that significantly slows down CI:
548
+
549
+ | Pattern | AI Guard Rule | ESLint Core | `@typescript-eslint` |
550
+ | :--- | :--- | :---: | :--- |
551
+ | **Floating Promises** (unawaited async call) | [`no-floating-promise`](./docs/rules/no-floating-promise.md) | ❌ None | `@typescript-eslint/no-floating-promises` *(requires type info)* |
552
+ | **Async Array Callbacks** (`.map(async ...)`) | [`no-async-array-callback`](./docs/rules/no-async-array-callback.md) | ❌ None | Partial: `no-misused-promises` *(requires type info)* |
553
+ | **Empty Catch Blocks** (swallowed errors) | [`no-empty-catch`](./docs/rules/no-empty-catch.md) | `no-empty` *(weaker)* | ❌ None |
554
+ | **Hardcoded Secrets / API Tokens** | [`no-hardcoded-secret`](./docs/rules/no-hardcoded-secret.md) | ❌ None | ❌ None |
555
+ | **Raw SQL String Concatenation** | [`no-sql-string-concat`](./docs/rules/no-sql-string-concat.md) | ❌ None | ❌ None |
556
+ | **Missing Route Auth Middleware** | [`require-auth-middleware`](./docs/rules/require-auth-middleware.md) | ❌ None | ❌ None |
557
+ | **Missing Route Authorization Checks** | [`require-authz-check`](./docs/rules/require-authz-check.md) | ❌ None | ❌ None |
558
+ | **Dynamic `eval()` / `new Function()`** | [`no-eval-dynamic`](./docs/rules/no-eval-dynamic.md) | `no-eval` *(blanket ban)* | ❌ None |
559
+ | **Unsafe `JSON.parse(req.body)`** | [`no-unsafe-deserialize`](./docs/rules/no-unsafe-deserialize.md) | ❌ None | ❌ None |
560
+ | **Async Without Await** | [`no-async-without-await`](./docs/rules/no-async-without-await.md) | ❌ None | `require-await` |
561
+ | **Sequential Await in Loop** | [`no-await-in-loop`](./docs/rules/no-await-in-loop.md) | `no-await-in-loop` *(no fix)* | ❌ None |
562
+ | **Dead Code Branches (`if (true)`)** | [`no-dead-branch`](./docs/rules/no-dead-branch.md) | ❌ None | ❌ None |
563
+
564
+ > [!TIP]
565
+ > **Minimal Type-Information Dependency:** 17 of 18 AI Guard rules operate in pure syntax/scope-analysis mode without `projectService` or `tsconfig.json`. The `no-floating-promise` rule optionally uses TypeScript parser services for higher recall on cross-module Promise calls, with syntax/scope-based heuristics as a zero-config fallback.
351
566
 
352
567
  ---
353
568
 
354
- ## Development
569
+ ### 2. Runtime Performance
355
570
 
356
- ```bash
357
- git clone https://github.com/YashJadhav21/eslint-plugin-ai-guard.git
358
- cd eslint-plugin-ai-guard
359
- npm install
360
- npm run test # 667 tests across 39 test files
361
- npm run build # Build CJS + ESM bundles
362
- npm run typecheck # TypeScript strict check
363
- npm run lint:self # Scan own source with ai-guard
364
- ```
571
+ Benchmark: scanning 196 TypeScript / JavaScript files (`algorithm-automata-simulator`, Windows 11, Node.js 20, median of 3 runs):
572
+
573
+ | Tool / Mode | Scan Time | Configuration Overhead |
574
+ | :--- | :---: | :--- |
575
+ | **`ai-guard run --strict`** | **~1.8s** | **Zero config** (18 AST heuristic rules, no `tsconfig.json` needed) |
576
+ | `eslint .` (recommended) | ~2.5s | Core syntax rules only (misses floating promises & secrets) |
577
+ | `eslint .` (type-aware `@typescript-eslint`) | **~8–12s** | Requires full TS compiler graph binding (**4x–6x slower**) |
578
+
579
+ AI Guard executes **4x–6x faster** than type-aware linting suites because it leverages deterministic AST heuristics rather than reconstructing the full TypeScript symbol graph.
580
+
581
+ ---
365
582
 
366
- See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development guide.
583
+ ### 3. Empirical Bug Detection & Precision Study
584
+
585
+ Two comprehensive empirical benchmark evaluations were conducted to measure real-world precision and detection yields:
586
+
587
+ #### A. Accuracy & False Positive Audit (4 Real-World Repositories, 378 Files)
588
+
589
+ | Category | Findings | True Positives | False Positive Rate |
590
+ | :--- | :---: | :---: | :---: |
591
+ | **Security** (`no-hardcoded-secret`, `no-eval-dynamic`, etc.) | 15 | 15 | **0%** |
592
+ | **Reliability** (`no-empty-catch`, broad exceptions) | 53 | 53 | **0%** |
593
+ | **Async Stability** (`no-floating-promise`, async callbacks) | 43 | ~40 | **~7%** |
594
+ | **AI Patterns** (duplicate logic, dead branches) | 58 | 43 | **26%** *(reduced in v1.2.8+)* |
595
+
596
+ #### B. Dual-Mode Detection Study (48 Call Sites & Real Production Target)
597
+
598
+ Audited across a controlled multi-file test corpus (13 files, 48 call sites) and a real-world Express + MongoDB production application (`Truvita New`):
599
+
600
+ - **High Precision:** **100% precision** on type-aware exclusive findings (26 of 26 verified True Positives; 0 false alarms on synchronous controls).
601
+ - **Critical Detection:** Detected **1 critical database startup race condition** in production (`server/index.ts connectDB()`) where an unawaited connection call allowed requests to hit the database before initialization.
602
+ - **Single-File Actionability:** **100%** of findings were resolvable locally at the call site (`await`, `.catch()`, or `void`).
603
+
604
+ For the complete methodology, raw findings, and benchmark harness, see [**`docs/benchmarks.md`**](./docs/benchmarks.md).
367
605
 
368
606
  ---
369
607
 
370
- ## Documentation
608
+ ## Performance & Philosophy
371
609
 
372
- | Doc | Purpose |
373
- |-----|---------|
374
- | [`docs/github-actions.md`](./docs/github-actions.md) | GitHub Actions workflow reference |
375
- | [`docs/ai-agents.md`](./docs/ai-agents.md) | AI agent integration guide |
376
- | [`docs/architecture.md`](./docs/architecture.md) | Architecture and internals |
377
- | [`docs/rules/`](./docs/rules/) | Per-rule documentation |
378
- | [`CONTRIBUTING.md`](./CONTRIBUTING.md) | Contribution guide |
379
- | [`SECURITY.md`](./SECURITY.md) | Security policy |
380
- | [`CHANGELOG.md`](./CHANGELOG.md) | Release history |
381
- | [`ROADMAP.md`](./ROADMAP.md) | Planned features |
610
+ - **Zero LLM Overhead:** AI Guard does not call external APIs, does not incur token costs, and does not add LLM latency. A scan of 100+ files executes in milliseconds.
611
+ - **100% Deterministic:** Every finding is derived strictly from Abstract Syntax Tree analysis. No probabilistic drift, no non-deterministic hallucinated findings.
612
+ - **Low False Positives:** Built with precision-first design. Context-sensitive rules are configured at `warn` or `off` in the recommended preset so developers are never blocked by noise.
613
+ - **Self-Scanning:** AI Guard enforces its own rules on its own codebase in CI using the `strict` preset.
382
614
 
383
615
  ---
384
616
 
385
- ## License
617
+ ## Learn More & Ecosystem
618
+
619
+ Visit [getaiguard.dev](https://getaiguard.dev) to explore interactive documentation, rule catalogs, benchmarks, and deep-dive engineering articles.
620
+
621
+ ### Official Links
386
622
 
387
- [MIT](LICENSE) — free forever. No rules behind a paywall.
623
+ - **Website:** [https://getaiguard.dev](https://getaiguard.dev)
624
+ - **GitHub Organization:** [https://github.com/ai-guard-dev](https://github.com/ai-guard-dev)
625
+ - **Repository:** [https://github.com/ai-guard-dev/eslint-plugin-ai-guard](https://github.com/ai-guard-dev/eslint-plugin-ai-guard)
626
+ - **npm Registry:** [https://www.npmjs.com/package/eslint-plugin-ai-guard](https://www.npmjs.com/package/eslint-plugin-ai-guard)
627
+ - **GitHub Action:** [ai-guard-dev/eslint-plugin-ai-guard@v1](https://github.com/ai-guard-dev/eslint-plugin-ai-guard)
388
628
 
389
629
  ---
390
630
 
391
- <p align="center">
392
- Built to make AI-assisted development reliable and trustworthy. ⚡
393
- </p>
631
+ ## Contributing
632
+
633
+ We welcome contributions, new rule ideas, bug reports, and false-positive reports!
634
+
635
+ 1. Check out our [Contributing Guide](CONTRIBUTING.md) for local setup and testing standards.
636
+ 2. Review our [Security Policy](SECURITY.md) to report vulnerabilities responsibly.
637
+ 3. Check open issues or submit new ones on our [Issue Tracker](https://github.com/ai-guard-dev/eslint-plugin-ai-guard/issues).
638
+
639
+ ---
640
+
641
+ ## License
642
+
643
+ [MIT](LICENSE) © AI Guard Authors. Free and open source forever.