eslint-plugin-ai-guard 1.3.1 → 1.4.0

package/README.md

@@ -33,7 +33,14 @@
 
 ## What is AI Guard?
 
-**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.).
+**AI Guard** (`eslint-plugin-ai-guard`) provides:
+- **ESLint plugin** with 18 deterministic rules and 4 presets (`recommended`, `strict`, `security`, `agent`)
+- **CLI** (`ai-guard`) for terminal, changed-file, and CI scanning
+- **GitHub Action** with native SARIF 2.1.0 output for GitHub Code Scanning
+- **Claude Code integration** with a zero-config PostToolUse hook
+- **MCP server** (`ai-guard-mcp`) for local AI-agent workflows (Claude Code, Claude Desktop, Antigravity)
+
+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.
 
@@ -87,7 +94,7 @@ flowchart TD
     end
 
     subgraph Tiers["3. Classification & Presets"]
-        E --> F{"Active Preset\n(recommended | strict | security)"}
+        E --> F{"Active Preset\n(recommended | strict | security | agent)"}
         F --> G["Confidence Tiering & AST Filtering"]
     end
 
@@ -614,6 +621,39 @@ For the complete methodology, raw findings, and benchmark harness, see [**`docs/
 
 ---
 
+## MCP Server (Model Context Protocol)
+
+AI Guard includes a local MCP server that exposes its deterministic analysis engine to MCP-capable AI clients (Claude Code, Claude Desktop, and other MCP-compatible integrations).
+
+```bash
+npx ai-guard-mcp
+```
+
+**Available tools:**
+
+| Tool | Description |
+| :--- | :--- |
+| `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_rules` | List available rules and presets |
+
+**Claude Code configuration** (`.claude/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "ai-guard": {
+      "command": "npx",
+      "args": ["ai-guard-mcp"]
+    }
+  }
+}
+```
+
+For detailed documentation, tool schemas, and security model, see [**`docs/mcp-server.md`**](./docs/mcp-server.md).
+
+---
+
 ## Learn More & Ecosystem
 
 Visit [getaiguard.dev](https://getaiguard.dev) to explore interactive documentation, rule catalogs, benchmarks, and deep-dive engineering articles.

package/dist/cli/index.js

@@ -1247,6 +1247,7 @@ var AGENT_RULES = {
 };
 
 // cli/utils/eslint-runner.ts
+var import_meta = {};
 var ISSUE_CONFIDENCE = {
   // HIGH — near-certain bugs: false positive rate <2% in real-world codebases
   "ai-guard/no-hardcoded-secret": "high",
@@ -1489,6 +1490,24 @@ async function loadPluginModuleFromCwd(cwd) {
       log.debug(`Local src plugin import failed: ${reason}`);
     }
   }
+  try {
+    const selfRequire = createRequire3(import_meta.url);
+    const selfResolved = selfRequire.resolve("eslint-plugin-ai-guard");
+    return import((0, import_url.pathToFileURL)(selfResolved).href);
+  } catch {
+  }
+  try {
+    const pkgRoot = import_path.default.resolve(import_path.default.dirname((0, import_url.fileURLToPath)(import_meta.url)), "..", "..");
+    const selfDist = import_path.default.join(pkgRoot, "dist", "index.js");
+    if (import_fs.default.existsSync(selfDist)) {
+      return import((0, import_url.pathToFileURL)(selfDist).href);
+    }
+    const selfSrc = import_path.default.join(pkgRoot, "src", "index.ts");
+    if (import_fs.default.existsSync(selfSrc)) {
+      return import((0, import_url.pathToFileURL)(selfSrc).href);
+    }
+  } catch {
+  }
   throw new Error(
     "eslint-plugin-ai-guard is not installed. Run: npm install --save-dev eslint-plugin-ai-guard"
   );
@@ -1772,13 +1791,13 @@ var import_path3 = __toESM(require("path"));
 var import_module = require("module");
 var import_url2 = require("url");
 var import_path2 = __toESM(require("path"));
-var import_meta = {};
+var import_meta2 = {};
 var _version;
 function readVersion() {
   try {
-    const require_ = (0, import_module.createRequire)(import_meta.url);
+    const require_ = (0, import_module.createRequire)(import_meta2.url);
     const pkgPath = import_path2.default.resolve(
-      import_path2.default.dirname((0, import_url2.fileURLToPath)(import_meta.url)),
+      import_path2.default.dirname((0, import_url2.fileURLToPath)(import_meta2.url)),
       "../../package.json"
     );
     const pkg = require_(pkgPath);
@@ -2534,7 +2553,7 @@ function tryPrDiff(branch, cwd, debugInfo) {
     const mergeBase = runGit(["merge-base", "HEAD", rawBranch], cwd);
     if (mergeBase) {
       if (!debugInfo.mergeBase) debugInfo.mergeBase = mergeBase;
-      const out = runGit(`diff --name-only --diff-filter=ACMRT ${mergeBase}`, cwd);
+      const out = runGit(["diff", "--name-only", "--diff-filter=ACMRT", mergeBase], cwd);
       if (out !== null) {
         debugInfo.strategySucceeded = strategy;
         return { output: out, strategy, mergeBase };
@@ -2573,6 +2592,7 @@ function tryPrDiff(branch, cwd, debugInfo) {
 }
 function filterFiles(rawFiles, extensions, workingDirectory, cwd, debugInfo) {
   const kept = [];
+  const seen = /* @__PURE__ */ new Set();
   for (const rel of rawFiles) {
     const normalized = rel.replace(/\\/g, "/").trim();
     if (!normalized) continue;
@@ -2597,7 +2617,10 @@ function filterFiles(rawFiles, extensions, workingDirectory, cwd, debugInfo) {
       debugInfo.droppedMissing++;
       continue;
     }
-    kept.push(abs);
+    if (!seen.has(abs)) {
+      seen.add(abs);
+      kept.push(abs);
+    }
   }
   return kept;
 }
@@ -2611,8 +2634,10 @@ function getChangedFiles(options = {}) {
     cwd = process.cwd(),
     extensions = DEFAULT_EXTENSIONS,
     workingDirectory,
-    debug = false
+    debug = false,
+    includeUntracked
   } = options;
+  const shouldIncludeUntracked = includeUntracked ?? !staged;
   const debugInfo = {
     strategiesAttempted: [],
     strategySucceeded: null,
@@ -2656,7 +2681,15 @@ function getChangedFiles(options = {}) {
     usedBase = resolvedBranch;
     const diffResult = tryPrDiff(resolvedBranch, cwd, debugInfo);
     if (diffResult) {
-      rawOutput = diffResult.output;
+      const untracked = shouldIncludeUntracked ? runGit(["ls-files", "--others", "--exclude-standard"], cwd) ?? "" : "";
+      if (shouldIncludeUntracked && untracked) {
+        debugInfo.strategiesAttempted.push("git ls-files --others --exclude-standard");
+      }
+      const combined = /* @__PURE__ */ new Set([
+        ...parseFileList(diffResult.output),
+        ...parseFileList(untracked)
+      ]);
+      rawOutput = [...combined].join("\n");
     } else {
       const shallow = debugInfo.isShallowClone ? " Shallow clone detected \u2014 try fetch-depth: 0 in your workflow." : "";
       const detached = debugInfo.isDetachedHead ? " HEAD is detached \u2014 ensure checkout fetches the branch." : "";
@@ -2666,8 +2699,16 @@ function getChangedFiles(options = {}) {
     mode = "uncommitted";
     const staged_ = runGit(["diff", "--name-only", "--cached", "--diff-filter=ACMRT"], cwd) ?? "";
     const unstaged = runGit(["diff", "--name-only", "--diff-filter=ACMRT"], cwd) ?? "";
+    const untracked = shouldIncludeUntracked ? runGit(["ls-files", "--others", "--exclude-standard"], cwd) ?? "" : "";
     debugInfo.strategiesAttempted.push("git diff --cached", "git diff (unstaged)");
-    const combined = /* @__PURE__ */ new Set([...parseFileList(staged_), ...parseFileList(unstaged)]);
+    if (shouldIncludeUntracked) {
+      debugInfo.strategiesAttempted.push("git ls-files --others --exclude-standard");
+    }
+    const combined = /* @__PURE__ */ new Set([
+      ...parseFileList(staged_),
+      ...parseFileList(unstaged),
+      ...parseFileList(untracked)
+    ]);
     rawOutput = [...combined].join("\n");
     if (rawOutput) debugInfo.strategySucceeded = "uncommitted changes";
     if (!rawOutput) {
@@ -3748,7 +3789,7 @@ async function verifyConfigLoads(configPath, cwd) {
   }
 }
 function registerInitCommand(program2) {
-  program2.command("init").description("Configure eslint-plugin-ai-guard in this project").option("--preset <name>", "Preset to use: recommended | strict | security", "recommended").option("--flat", "Force flat config format (eslint.config.mjs) regardless of ESLint version").option("--dry-run", "Preview what would change without writing any files").option("-y, --yes", "Skip all prompts \u2014 use defaults (recommended preset, generate workflow + agent context)").action(async (opts) => {
+  program2.command("init").description("Configure eslint-plugin-ai-guard in this project").option("--preset <name>", "Preset to use: recommended | strict | security | agent", "recommended").option("--flat", "Force flat config format (eslint.config.mjs) regardless of ESLint version").option("--dry-run", "Preview what would change without writing any files").option("-y, --yes", "Skip all prompts \u2014 use defaults (recommended preset, generate workflow + agent context)").action(async (opts) => {
     const preset = opts.preset ?? "recommended";
     const cwd = process.cwd();
     const isDryRun = opts.dryRun === true;
@@ -4169,7 +4210,7 @@ var import_chalk8 = __toESM(require("chalk"));
 var import_path10 = __toESM(require("path"));
 init_logger();
 init_config_manager();
-var import_meta2 = {};
+var import_meta3 = {};
 async function probeConfigLoad(configPath, cwd) {
   try {
     const { ESLint } = await import("eslint");
@@ -4297,7 +4338,7 @@ ${env.allConfigPaths.map((p) => `       ${import_path10.default.relative(cwd, p)
       if (!utilsOk) {
         try {
           const selfDir = import_path10.default.dirname(
-            new URL(import_meta2.url).pathname.replace(/^\/([A-Za-z]:)/, "$1")
+            new URL(import_meta3.url).pathname.replace(/^\/([A-Za-z]:)/, "$1")
           );
           const pkgPath = import_path10.default.join(selfDir, "../../node_modules/@typescript-eslint/utils/package.json");
           if ((await import("fs")).existsSync(pkgPath)) {
@@ -4664,7 +4705,7 @@ function computeNewIssues(result, baselineSet, mode) {
   };
 }
 function registerBaselineCommand(program2) {
-  program2.command("baseline [action]").description("Save current issues as baseline; future runs show only new issues (save | check)").option("--save", "Save current state as the new baseline").option("--check", "Show only issues introduced since the last baseline").option("--mode <name>", "Baseline match mode: strict | stable", "stable").option("--path <dir>", "Directory to scan", ".").option("--preset <name>", "Preset: recommended | strict | security", "recommended").action(async (action, opts) => {
+  program2.command("baseline [action]").description("Save current issues as baseline; future runs show only new issues (save | check)").option("--save", "Save current state as the new baseline").option("--check", "Show only issues introduced since the last baseline").option("--mode <name>", "Baseline match mode: strict | stable", "stable").option("--path <dir>", "Directory to scan", ".").option("--preset <name>", "Preset: recommended | strict | security | agent", "recommended").action(async (action, opts) => {
     const cwd = process.cwd();
     const preset = opts.preset ?? "recommended";
     const mode = opts.mode ?? "stable";
@@ -5179,7 +5220,7 @@ function escHtml(str) {
 function registerReportCommand(program2) {
   program2.command("report").description(
     "Generate a beautiful HTML report of AI Guard scan results\nPerfect for sharing with your team or in Slack."
-  ).option("--path <dir>", "Directory or file to scan", ".").option("--preset <preset>", "Rule preset: recommended | strict | security", "recommended").option("--html", "Generate HTML report (default behavior)").option("--json", "Output raw JSON to stdout instead of writing HTML").option("--output <filename>", "Output file name", "ai-guard-report.html").option("--no-open", "Do not open the report in the browser after generating").action(async (opts) => {
+  ).option("--path <dir>", "Directory or file to scan", ".").option("--preset <preset>", "Rule preset: recommended | strict | security | agent", "recommended").option("--html", "Generate HTML report (default behavior)").option("--json", "Output raw JSON to stdout instead of writing HTML").option("--output <filename>", "Output file name", "ai-guard-report.html").option("--no-open", "Do not open the report in the browser after generating").action(async (opts) => {
     const preset = ["recommended", "strict", "security"].includes(opts.preset) ? opts.preset : "recommended";
     const spinner = opts.json ? null : (0, import_ora4.default)({ text: "Scanning\u2026", color: "cyan" }).start();
     let result;