eslint-plugin-ai-guard 1.4.6 → 1.4.7

package/README.md

@@ -42,8 +42,18 @@
 - **Hooks for Claude Code, Cursor and Codex** (`ai-guard init-hooks`): findings go back to the agent as it works, and it is stopped once before finishing on weakened checks or problems it introduced
 - **A pre-commit gate** (`ai-guard init-git-hook`) that checks every commit, whichever agent or person wrote it
 - **Works with Oxlint** as a JS plugin, with identical results checked in CI (`ai-guard init-oxlint`)
+- **Package checks** (`ai-guard verify-deps`, an opt-in pre-install hook, and the `ai_guard_check_package` MCP tool): names that do not exist on npm, typosquats and npm security placeholders are blocked; install scripts, deprecations and releases from the last day are flagged
 - **MCP server** (`ai-guard-mcp`, 9 tools) for local AI-agent workflows over STDIO
 
+### Results on real projects
+
+Measured on 12 November 2026 with 1.4.6. Methods, raw numbers and the commands to reproduce them: [docs/evidence.md](./docs/evidence.md).
+
+- **0 of 1,361** real dependencies blocked (763 from 15 large open-source projects, 598 from 9 apps)
+- **34 of 36** names from the 2017 crossenv malware campaign blocked
+- **3.0%** of the 5,000 most-downloaded packages had a latest release under a day old, the window the fresh-release check covers
+- **27 of 27** rules give identical results in ESLint and Oxlint, checked in CI
+
 It is 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.).
 
 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.
@@ -142,7 +152,7 @@ AI Guard includes **27 deterministic rules** divided into four specialized categ
 
 | Rule | Recommended | What It Catches | Fixable? |
 | :--- | :---: | :--- | :---: |
-| [`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 */`) |
+| [`no-empty-catch`](./docs/rules/no-empty-catch.md) | **`error`** | Empty `catch (e) {}` blocks that silently swallow exceptions without logging or rethrowing. | No (editor suggestion: rethrow) |
 | [`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 |
 | [`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 |
 | [`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 |
@@ -152,7 +162,7 @@ AI Guard includes **27 deterministic rules** divided into four specialized categ
 
 | Rule | Recommended | What It Catches | Fixable? |
 | :--- | :---: | :--- | :---: |
-| [`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`) |
+| [`no-floating-promise`](./docs/rules/no-floating-promise.md) | **`error`** | Async function invocations without `await`, `.catch()`, or `return` — leading to silent dropped errors. | No (editor suggestions: `await`, or `void` if intended) |
 | [`no-async-array-callback`](./docs/rules/no-async-array-callback.md) | `warn` | Async callbacks passed to `map()`, `filter()`, `forEach()`, or `reduce()` returning `Promise[]`. | No |
 | [`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`) |
 | [`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 |
@@ -455,14 +465,25 @@ jobs:
           cache: 'npm'
 
       - name: Run AI Guard
+        id: aiguard
         uses: ai-guard-dev/eslint-plugin-ai-guard@v1
         with:
           preset: 'recommended'
           fail-on: 'high'
           changed-only: 'true'
-          upload-sarif: 'true'
+
+      # The Action writes SARIF; this step sends it to Code Scanning.
+      # if: always() uploads it even when the scan step fails the job.
+      - name: Upload to GitHub Code Scanning
+        if: always()
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: ${{ steps.aiguard.outputs.sarif-file }}
+          category: ai-guard
 ```
 
+The Action annotates the pull request and writes the job summary by itself. Alerts in **Security → Code scanning** need the upload step.
+
 ### Action Inputs (`action.yml`)
 
 | Input | Description | Default |
@@ -471,7 +492,7 @@ jobs:
 | `fail-on` | Severity threshold to fail CI: `high` \| `medium` \| `any` \| `none` | `'high'` |
 | `changed-only` | Scan only files changed in this PR / commit | `'true'` |
 | `path` | Target file or directory to scan | `'.'` |
-| `upload-sarif` | Upload results to GitHub Code Scanning | `'true'` |
+| `upload-sarif` | Always write the SARIF file (`sarif-file` output) for an `upload-sarif` step, even when the scan produced none. The Action does not upload to Code Scanning by itself | `'true'` |
 | `github-summary` | Write an execution breakdown to the GitHub Actions Job Summary | `'true'` |
 | `working-directory`| Working directory for scanning (ideal for monorepos) | `'.'` |
 | `package-manager` | Package manager: `auto` \| `npm` \| `pnpm` \| `yarn` | `'auto'` |
@@ -610,10 +631,10 @@ npx eslint . --fix
 | Rule | Automatic Fix Behavior |
 | :--- | :--- |
 | `no-hardcoded-secret` | Replaces hardcoded string literal with `process.env.VARIABLE_NAME` |
-| `no-empty-catch` | Inserts `/* TODO: handle error */` comment to prevent silent swallowing |
-| `no-floating-promise` | Prepends `void ` expression to intentionally unawaited calls |
 | `no-await-in-loop` | Rewrites straightforward sequential loops to `await Promise.all(...)` |
 
+`no-empty-catch` and `no-floating-promise` have no automatic fix on purpose. A fix that inserted a comment or `void` would make the finding disappear without handling the error, and an agent running `--fix` would do exactly that. Editors offer them as suggestions instead (rethrow; `await`, or `void` for an intended fire-and-forget call), which a person applies one at a time.
+
 ---
 
 ## Benchmarks & Empirical Evaluation
@@ -712,7 +733,7 @@ npx --yes --package eslint-plugin-ai-guard ai-guard-mcp
 | :--- | :--- |
 | `ai_guard_scan_file` | Scan a single JS/TS file with structured findings |
 | `ai_guard_scan_diff` | Scan changed files in git diff (including newly created untracked JS/TS files) |
-| `ai_guard_scan_project` | Scan a bounded workspace directory (current source; not yet published) |
+| `ai_guard_scan_project` | Scan a bounded workspace directory (at most 500 files; fails instead of truncating) |
 | `ai_guard_rules` | List rules and presets, or look up specific rules (`rules: ["no-floating-promise"]`) with remediation and docs link |
 | `ai_guard_check_integrity` | Report checks weakened by current Git changes (new suppressions, skipped/removed tests, lowered configs, removed CI steps), with `tier` and `hasBlockingFindings` |
 

package/dist/cli/hook.js

@@ -1323,7 +1323,7 @@ var init_security = __esm({
 });
 
 // src/rules/reliability/no-empty-catch.ts
-var import_utils, createRule, noEmptyCatch;
+var import_utils, createRule, PLACEHOLDER_COMMENT, noEmptyCatch;
 var init_no_empty_catch = __esm({
   "src/rules/reliability/no-empty-catch.ts"() {
     "use strict";
@@ -1332,43 +1332,47 @@ var init_no_empty_catch = __esm({
     createRule = import_utils.ESLintUtils.RuleCreator(
       (name) => `https://github.com/ai-guard-dev/eslint-plugin-ai-guard/blob/main/docs/rules/${name}.md`
     );
+    PLACEHOLDER_COMMENT = /^\s*(?:TODO|FIXME|XXX)\b/i;
     noEmptyCatch = createRule({
       name: "no-empty-catch",
       meta: {
         type: "problem",
         docs: {
-          description: "Disallow empty catch blocks. AI tools frequently generate try/catch with empty catch bodies that silently swallow errors, hiding failures in production. Includes a safe autofix that inserts an explicit placeholder comment."
+          description: "Disallow empty catch blocks. AI tools frequently generate try/catch with empty catch bodies that silently swallow errors, hiding failures in production. A comment explaining why the block is empty is accepted; a TODO, FIXME or XXX comment is not. There is no automatic fix, so `--fix` cannot hide the problem; an editor suggestion rethrows the error."
         },
-        fixable: "code",
         hasSuggestions: true,
         schema: [],
         messages: {
           emptyCatch: "Catch block is empty. AI tools frequently generate empty catch blocks that silently swallow errors. Handle the error (log, rethrow, or recover), or add a comment explaining why it is intentionally empty.",
-          addTodoHandler: "Add a minimal placeholder so this catch block is not silently swallowing errors."
+          placeholderCatch: "Catch block only has a TODO comment, so the error is still swallowed. Handle the error (log, rethrow, or recover), or replace the TODO with a comment explaining why ignoring it is safe.",
+          rethrow: "Rethrow the error."
         }
       },
       defaultOptions: [],
       create(context) {
+        const sourceCode = context.sourceCode;
+        function rethrowFix(node) {
+          if (node.param === null) {
+            return (fixer) => fixer.replaceText(node, "catch (error) { throw error; }");
+          }
+          if (node.param.type === "Identifier") {
+            const name = node.param.name;
+            return (fixer) => fixer.replaceText(node.body, `{ throw ${name}; }`);
+          }
+          return null;
+        }
         return {
           CatchClause(node) {
-            if (node.body.body.length === 0) {
-              const sourceCode = context.sourceCode;
-              const comments = sourceCode.getCommentsInside(node.body);
-              if (comments.length > 0) {
-                return;
-              }
-              context.report({
-                node,
-                messageId: "emptyCatch",
-                fix: (fixer) => fixer.replaceText(node.body, "{ /* TODO: handle error */ }"),
-                suggest: [
-                  {
-                    messageId: "addTodoHandler",
-                    fix: (fixer) => fixer.replaceText(node.body, "{ /* TODO: handle error */ }")
-                  }
-                ]
-              });
-            }
+            if (node.body.body.length > 0) return;
+            const comments = sourceCode.getCommentsInside(node.body);
+            const placeholderOnly = comments.length > 0 && comments.every((c) => PLACEHOLDER_COMMENT.test(c.value));
+            if (comments.length > 0 && !placeholderOnly) return;
+            const fix = rethrowFix(node);
+            context.report({
+              node,
+              messageId: placeholderOnly ? "placeholderCatch" : "emptyCatch",
+              suggest: fix ? [{ messageId: "rethrow", fix }] : []
+            });
           }
         };
       }
@@ -2268,28 +2272,32 @@ var init_no_floating_promise = __esm({
       meta: {
         type: "problem",
         docs: {
-          description: "Disallow calling an async function or Promise-returning function without awaiting or handling the result. AI tools frequently generate floating promises where errors disappear silently. Includes a safe autofix that marks intentional fire-and-forget calls with void."
+          description: "Disallow calling an async function or Promise-returning function without awaiting or handling the result. AI tools frequently generate floating promises where errors disappear silently. There is no automatic fix, because marking a call with void would hide the finding without handling the error; editor suggestions offer await (inside an async function) or void for an intentional fire-and-forget call."
         },
-        fixable: "code",
+        hasSuggestions: true,
         schema: [],
         messages: {
-          floatingPromise: "This async call is not awaited, returned, or error-handled (.catch). AI tools frequently generate floating promises, causing errors to be silently lost. Add `await`, `.catch()`, or assign the result."
+          floatingPromise: "This async call is not awaited, returned, or error-handled (.catch). AI tools frequently generate floating promises, causing errors to be silently lost. Add `await`, `.catch()`, or assign the result.",
+          addAwait: "Await it.",
+          markVoid: "Mark it as intentionally not awaited (void). Errors from it will still be lost."
         }
       },
       defaultOptions: [],
       create(context) {
+        function suggestions(statement) {
+          const text = context.sourceCode.getText(statement.expression);
+          const fn = context.sourceCode.getAncestors(statement).reverse().find((n) => n.type === import_utils8.AST_NODE_TYPES.FunctionDeclaration || n.type === import_utils8.AST_NODE_TYPES.FunctionExpression || n.type === import_utils8.AST_NODE_TYPES.ArrowFunctionExpression);
+          const inAsync = !!fn && "async" in fn && fn.async;
+          return [
+            ...inAsync ? [{ messageId: "addAwait", fix: (fixer) => fixer.replaceText(statement.expression, `await ${text}`) }] : [],
+            { messageId: "markVoid", fix: (fixer) => fixer.replaceText(statement.expression, `void ${text}`) }
+          ];
+        }
         return {
           // Check ExpressionStatements — standalone call expressions
           ExpressionStatement(node) {
             if (node.expression.type === import_utils8.AST_NODE_TYPES.NewExpression && node.expression.callee.type === import_utils8.AST_NODE_TYPES.Identifier && node.expression.callee.name === "Promise") {
-              context.report({
-                node,
-                messageId: "floatingPromise",
-                fix: (fixer) => fixer.replaceText(
-                  node.expression,
-                  `void ${context.sourceCode.getText(node.expression)}`
-                )
-              });
+              context.report({ node, messageId: "floatingPromise", suggest: suggestions(node) });
               return;
             }
             if (node.expression.type !== import_utils8.AST_NODE_TYPES.CallExpression) {
@@ -2304,14 +2312,7 @@ var init_no_floating_promise = __esm({
               return;
             }
             if (localAsyncInfo.isAsync || isKnownPromiseFactoryCall(callExpr) || isPromiseLikeByTypeInfo(callExpr, context)) {
-              context.report({
-                node,
-                messageId: "floatingPromise",
-                fix: (fixer) => fixer.replaceText(
-                  node.expression,
-                  `void ${context.sourceCode.getText(node.expression)}`
-                )
-              });
+              context.report({ node, messageId: "floatingPromise", suggest: suggestions(node) });
             }
           }
         };