pi-lens 2.0.9 → 2.0.25

package/CHANGELOG.md

@@ -2,6 +2,110 @@
 
 All notable changes to pi-lens will be documented in this file.
 
+## [2.0.24] - 2026-03-26
+
+### Changed
+- **Simplified `/lens-booboo-refactor` confirmation flow**: Post-change report instead of pre-change gate. Agent implements first, then shows what was changed (git diff + metrics delta). User reviews and can request refinements via chat. No more temp files or dry-run diffs.
+- **Confirmation screen**: "✅ Looks good — move to next offender" / "💬 Request changes" (chat textarea). Diff display is optional.
+
+## [2.0.23] - 2026-03-26
+
+### Changed
+- **Extracted interviewer and scan modules from `index.ts`**: `index.ts` reduced by 460 lines.
+  - `clients/interviewer.ts` — all browser interview infrastructure (HTML generation, HTTP server, browser launch, option selection, diff confirmation screen)
+  - `clients/scan-architectural-debt.ts` — shared scanning utilities (`scanSkipViolations`, `scanComplexityMetrics`, `scoreFiles`, `extractCodeSnippet`)
+- **`/lens-booboo-refactor`** now uses imported scan functions instead of duplicated inline code.
+
+## [2.0.22] - 2026-03-26
+
+### Added
+- **Impact metrics in interview options**: Each option now supports an `impact` object (`linesReduced`, `miProjection`, `cognitiveProjection`) rendered as colored badges in the browser form. Agent estimates impact when presenting refactoring options.
+- **Iterative confirmation loop**: Confirmation screen now includes "🔄 Describe a different approach" option with free-text textarea. Agent regenerates plan+diff based on feedback, re-opens confirmation. Repeat until user confirms or cancels.
+- **Auto-close on confirm**: Browser tab closes automatically after user submits.
+
+## [2.0.21] - 2026-03-26
+
+### Added
+- **Two-step confirmation for `/lens-booboo-refactor`**: Agent implements changes, then calls `interviewer` with `confirmationMode=true` to show plan (markdown) + unified diff (green/red line coloring) + line counts at the top. User can Confirm, Cancel, or describe a different approach.
+- **Plan + diff confirmation screen**: Plan rendered as styled markdown, diff rendered with syntax-colored `+`/`-` lines. Line counts (`+N / −N`) shown in diff header.
+
+## [2.0.20] - 2026-03-26
+
+### Added
+- **Impact metrics in interview options**: Structured `impact` field per option with `linesReduced`, `miProjection`, `cognitiveProjection`. Rendered as colored badges (green for lines reduced, blue for metric projections) inside each option card.
+
+## [2.0.19] - 2026-03-26
+
+### Changed
+- **`/lens-booboo-fix` jscpd filter**: Only within-file duplicates shown in actionable section. Cross-file duplicates are architectural — shown in skip section only.
+- **AI slop filter tightened**: Require 2+ signals per file (was 1+). Single-issue flags on small files are noise — skip them.
+
+## [2.0.18] - 2026-03-26
+
+### Fixed
+- **`/lens-booboo-fix` max iterations**: Session file auto-deletes when hitting max iterations. Previously blocked with a manual "delete .pi-lens/fix-session.json" message.
+
+## [2.0.17] - 2026-03-26
+
+### Changed
+- **Agent-driven option generation**: `/lens-booboo-refactor` no longer hardcodes refactoring options per violation type. The command scans and presents the problem + code to the agent; the agent analyzes the actual code and generates 3-5 contextual options with rationale and impact estimates. Calls the `interviewer` tool to present them.
+- **`interviewer` tool**: Generic, reusable browser-based interview mechanism. Accepts `question`, `options` (with `value`, `label`, `context`, `recommended`, `impact`), and `confirmationMode`. Zero dependencies — Node's built-in `http` module + platform CLI `open`/`start`/`xdg-open`.
+
+## [2.0.16] - 2026-03-26
+
+### Added
+- **`/lens-booboo-refactor`**: Interactive architectural refactor session. Scans for worst offender by combined debt score (ast-grep skip violations + complexity metrics). Opens a browser interview with the problem, code context, and AI-generated options. Steers the agent to propose a plan and wait for user confirmation before making changes.
+
+### Changed
+- **Inline tool_result suppresses skip-category rules**: `long-method`, `large-class`, `long-parameter-list`, `no-shadow`, `no-as-any`, `no-non-null-assertion`, `no-star-imports` no longer show as hard stops in real-time feedback. They are architectural — handled by `/lens-booboo-refactor` instead.
+
+## [2.0.15] - 2026-03-26
+
+### Removed
+- **Complexity metrics from real-time feedback**: MI, cognitive complexity, nesting depth, try/catch counts, and entropy scores removed from tool_result output. These were always noise — the agent never acted on "MI dropped to 5.6" mid-task. Metrics still available via `/lens-metrics` and `/lens-booboo`.
+- **Session summary injection**: The `[Session Start]` block (TODOs, dead code, jscpd, type-coverage) is no longer injected into the first tool result. Scans still run for caching purposes (exports, clones, baselines). Data surfaced on-demand via explicit commands.
+- **`/lens-todos`**: Removed (covered by `/lens-booboo`).
+- **`/lens-dead-code`**: Removed (covered by `/lens-booboo`).
+- **`/lens-deps`**: Removed — circular dep scan added to `/lens-booboo` as Part 8.
+
+### Changed
+- **Hardened stop signals**: New violations (ast-grep, Biome, jscpd, duplicate exports) now all use `🔴 STOP` framing. The agent is instructed to fix these before continuing.
+- **`/lens-booboo` now includes circular dependencies**: Added as Part 8 (after type coverage) using `depChecker.scanProject`.
+
+## [2.0.14] - 2026-03-26
+
+### Fixed
+- **`/lens-booboo-fix` excludes `.js` compiled output**: Detects `tsconfig.json` and excludes `*.js` from jscpd, ast-grep, and complexity scans. Prevents double-counting of the same code in `.ts` and `.js` forms.
+- **`raw-strings` rule added to skip list**: 230 false positives in CLI/tooling codebases.
+- **`typescript-client.ts` duplication**: Extracted `resolvePosition()`, `resolveTree()`, and `toLocations()` helpers, deduplicating 6+ LSP methods.
+- **All clients**: `console.log` → `console.error` in verbose loggers (stderr for debug, stdout for data).
+
+## [2.0.13] - 2026-03-26
+
+### Removed
+- **`raw-strings` ast-grep rule**: Not an AI-specific pattern. Humans write magic strings too. Biome handles style. Generated 230 false positives on first real run.
+
+## [2.0.12] - 2026-03-26
+
+### Fixed
+- **`/lens-booboo-fix` sequential scan order**: Reordered to Biome/Ruff → jscpd (duplicates) → knip (dead code) → ast-grep → AI slop → remaining Biome. Duplicates should be fixed before violations (fixing one fixes both). Dead code should be deleted before fixing violations in it.
+
+### Changed
+- **Remaining Biome section rephrased**: "These couldn't be auto-fixed even with `--unsafe` — fix each manually."
+
+## [2.0.11] - 2026-03-26
+
+### Added
+- **Circular dependency scan to `/lens-booboo`**: Added as Part 8, using `depChecker.scanProject()` to detect circular chains across the codebase.
+
+### Removed
+- **`/lens-todos`**, **`/lens-dead-code`**, **`/lens-deps`**: Removed standalone commands — all covered by `/lens-booboo`.
+
+## [2.0.10] - 2026-03-26
+
+### Changed
+- **Session summary injection removed**: The `[Session Start]` block is no longer injected into the first tool result. Scans still run silently for caching (exports for duplicate detection, clones for jscpd, complexity baselines for deltas).
+
 ## [2.0.1] - 2026-03-25
 
 ### Fixed

package/README.md

@@ -15,42 +15,35 @@ Real-time code quality feedback for [pi](https://github.com/mariozechner/pi-codi
 | **Biome** | Lint + format for JS/TS/JSX/TSX/CSS/JSON. Auto-fix disabled by default, use `/lens-format` to apply |
 | **Ruff** | Lint + format for Python. Auto-fixes on every write by default |
 | **Test Runner** | Runs corresponding test file when you edit source code (vitest, jest, pytest). Silent if no test file exists. |
-| **Complexity Metrics** | AST-based analysis: Maintainability Index, Cyclomatic/Cognitive Complexity, Halstead Volume, nesting depth, function length, code entropy. AI slop indicators: emoji comments, try/catch density, over-abstraction, long parameter lists. |
 | **jscpd** | Code duplication detection. Warns when editing a file that has duplicates with other files in the project. |
 | **Duplicate Exports** | Detects when you redefine a function that already exists elsewhere in the codebase. |
 
-### Delta-mode feedback (new in 2.0)
+### Delta-mode feedback
 
-ast-grep and Biome run in **delta mode** — only violations *introduced by the current edit* are shown. Pre-existing issues are silent. Fixed violations are acknowledged.
+ast-grep and Biome run in **delta mode** — only violations *introduced by the current edit* are shown. Pre-existing issues are silent. Fixed violations are acknowledged. Skipped rules (`long-method`, `large-class`, etc.) are suppressed — they're architectural and handled by `/lens-booboo-refactor`.
 
 ```
 🔴 Fix 2 TypeScript error(s) — these must be resolved:
   L10: Type 'string' is not assignable to type 'number'
 
-🔴 You introduced 1 new structural violation(s) — fix before moving on:
+🔴 STOP — you introduced 1 new structural violation(s). Fix before continuing:
   no-var: Use 'const' or 'let' instead of 'var' (L23)
     → var has function scope and can lead to unexpected hoisting behavior.
-  (18 total remaining)
+  → Auto-fixable: check the hints above
 
 ✅ ast-grep: fixed no-console-log (-1)
 
-🟠 You introduced 1 new Biome violation(s) — fix before moving on:
+🔴 STOP — you introduced 1 new Biome violation(s). Fix before continuing:
   L23:5 [style/useConst] This let declares a variable that is only assigned once.
   → Auto-fixable: `npx @biomejs/biome check --write utils.ts`
-  (4 total remaining)
 
-🟠 This file has 1 duplicate block(s) — extract to shared utilities:
+🔴 STOP — this file has 1 duplicate block(s). Extract to a shared utility before adding more code:
   15 lines duplicated with helpers.ts:20
 
 🔴 Do not redefine — 1 function(s) already exist elsewhere:
   formatDate (already in helpers.ts)
   → Import the existing function instead
 
-🟡 Complexity issues — refactor when you get a chance:
-  ⚠ Maintainability dropped to 55 — extract logic into helper functions
-  ⚠ AI-style comments (6) — remove hand-holding comments
-  ⚠ Many try/catch blocks (7) — consolidate error handling
-
 [Tests] ✗ 1/3 failed, 2 passed
   ✗ should format date
   → Fix failing tests before proceeding
@@ -64,50 +57,26 @@ Before every write or edit, the agent is warned about blocking TypeScript errors
 ⚠ Pre-write: file already has 5 TypeScript error(s) — fix before adding more
 ```
 
-### Session start summary (injected into first tool result)
+### Session start (silent caching)
 
-On every new session, the following scans run against the whole project and are delivered once into the first tool result:
+On every new session, scans run silently in the background. Data is cached for real-time feedback during the session and surfaced on-demand via explicit commands:
 
-| Tool | What it reports |
+| Scanner | Cached for |
 |---|---|
-| **TODO scanner** | All TODO / FIXME / HACK / BUG / DEPRECATED annotations, sorted by severity |
-| **Knip** | Unused exports, types, and unlisted dependencies |
-| **jscpd** | Duplicate code blocks — file, line, size, percentage of codebase |
-| **type-coverage** | Percentage of identifiers properly typed; lists exact locations of `any` |
-
-Example:
-
-```
-[Session Start]
-[TODOs] 3 annotation(s) found (2 FIXME, 1 TODO):
-  🔴 src/auth.ts:42 — FIXME: token refresh not implemented
-  🟠 src/parser.ts:17 — HACK: bypassing validation
-  📝 src/api.ts:88 — TODO: add rate limiting
-
-[Knip] 2 issue(s) — 2 unused export(s):
-  Unused exports:
-    - legacyFormat (utils.ts)
-    - oldParser (parser.ts)
-
-[jscpd] 2 duplicate block(s) — 1.2% of codebase (47/3920 lines):
-  16 lines — openrouter.ts:183 ↔ openrouter.ts:135
-  11 lines — cline-auth.ts:51 ↔ kilo-auth.ts:9
-
-[type-coverage] ⚠ 94.3% typed (3870/4107 identifiers):
-  auth.ts:138:44 — undefined as any
-  config.ts:52:12 — err
-  ... and 12 more
-```
+| **TODO scanner** | `/lens-booboo` reports |
+| **Knip** | Dead code detection in `/lens-booboo` and `/lens-booboo-fix` |
+| **jscpd** | Duplicate detection on write; `/lens-booboo` reports |
+| **type-coverage** | `/lens-booboo` reports |
+| **Complexity baselines** | Regressed/improved delta tracking via `/lens-metrics` |
 
 ### On-demand commands
 
 | Command | Description |
 |---|---|
-| `/lens-todos [path]` | Scan for TODO/FIXME/HACK annotations |
-| `/lens-dead-code` | Find unused exports/files/dependencies (requires knip) |
-| `/lens-deps` | Circular dependency scan (requires madge) |
+| `/lens-booboo [path]` | Full code review: TODOs, dead code, duplicates, type coverage, circular dependencies. Saves full report to `.pi-lens/reviews/` |
+| `/lens-booboo-fix [path]` | Iterative automated fix loop. Runs Biome/Ruff autofix, then scans for fixable issues (ast-grep agent rules, dead code). Generates a fix plan for the agent to execute. Re-run for up to 3 iterations, then reset. |
+| `/lens-booboo-refactor [path]` | Interactive architectural refactor. Scans for worst offender by combined debt score (ast-grep skip rules + complexity metrics). Opens a browser interview with impact metrics — agent proposes refactoring options with rationale, user picks one, agent implements and shows a post-change report. |
 | `/lens-format [file\|--all]` | Apply Biome formatting |
-| `/lens-booboo [path]` | Full code review: design smells, complexity, AI slop, TODOs, dead code, duplicates, type coverage. Saves full report to `.pi-lens/reviews/` |
 | `/lens-metrics [path]` | Measure complexity metrics for all files. Exports `report.md` with grades (A-F), summary stats, and top 10 worst files |
 
 ### On-demand tools
@@ -157,6 +126,63 @@ pip install ruff
 
 ---
 
+## Fix loop commands
+
+### `/lens-booboo-fix` — automated mechanical fixes
+
+Iterative loop that auto-fixes what it can, then generates a fix plan for the agent. Scan order:
+
+1. **Biome + Ruff** — auto-fix lint/format issues silently
+2. **jscpd** — within-file duplicate blocks (extract to shared utilities)
+3. **Knip** — dead code (delete unused exports/files)
+4. **ast-grep** — structural violations on surviving code (agent fixes)
+5. **AI slop** — files with 2+ complexity signals
+6. **Remaining Biome** — issues that couldn't be auto-fixed even with `--unsafe`
+
+Run up to 3 iterations per session. Session auto-resets after hitting max — just run again.
+
+```
+📋 BOOBOO FIX PLAN — Iteration 1/3 (44 fixable items remaining)
+✅ Fixed 249 issues since last iteration.
+
+⚡ Auto-fixed: Biome --write --unsafe, Ruff --fix + format already ran.
+
+## 🔨 Fix these [12 items]
+
+### no-console-log (14)
+→ Remove or replace with class logger method
+  - `clients/ruff-client.ts:47`
+  - `clients/biome-client.ts:48`
+  ...
+
+## ⏭️ Skip [109 items — architectural]
+  - **long-method** (79): Extraction requires understanding the function's purpose.
+  - **large-class** (16): Splitting a class requires architectural decisions.
+```
+
+### `/lens-booboo-refactor` — interactive architectural refactoring
+
+Surfaces the worst offender in the codebase by combined debt score (ast-grep skip rules + complexity metrics). The agent analyzes the code, generates refactoring options with impact estimates, and presents them in a browser interview.
+
+**Two-step flow:**
+1. **Option selection** — browser opens with numbered radio cards, each showing rationale + impact metrics (`linesReduced`, `miProjection`, `cognitiveProjection`). One option is recommended.
+2. **Post-change report** — after implementing, agent shows what changed (git diff + line counts) and how metrics evolved. User can say "looks good" or request changes via chat.
+
+```
+🏗️ BOOBOO REFACTOR — worst offender identified
+
+File: index.ts (debt score: 35)
+Complexity: MI: 2.7, Cognitive: 1590, Nesting: 10
+
+Violations:
+  - long-method (×18)
+  - long-parameter-list (×6)
+```
+
+The agent then calls the built-in `interviewer` tool, which opens a browser form with the generated options. Zero dependencies — Node's built-in `http` module + platform CLI (`start`/`open`/`xdg-open`).
+
+---
+
 ## ast-grep rules
 
 Rules live in `rules/ast-grep-rules/rules/`. All rules are YAML files you can edit or extend.

package/clients/ast-grep-client.js

@@ -0,0 +1,340 @@
+/**
+ * AstGrep Client for pi-lens
+ *
+ * Structural code analysis using ast-grep CLI.
+ * Scans files against YAML rule definitions.
+ *
+ * Requires: npm install -D @ast-grep/cli
+ * Rules: ./rules/ directory
+ */
+import { spawn, spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { AstGrepParser } from "./ast-grep-parser.js";
+import { AstGrepRuleManager } from "./ast-grep-rule-manager.js";
+// --- Client ---
+export class AstGrepClient {
+    constructor(ruleDir, verbose = false) {
+        this.available = null;
+        this.ruleDir =
+            ruleDir ||
+                path.join(typeof __dirname !== "undefined" ? __dirname : ".", "..", "rules");
+        this.log = verbose
+            ? (msg) => console.error(`[ast-grep] ${msg}`)
+            : () => { };
+        this.ruleManager = new AstGrepRuleManager(this.ruleDir, this.log);
+    }
+    /**
+     * Check if ast-grep CLI is available
+     */
+    isAvailable() {
+        if (this.available !== null)
+            return this.available;
+        const result = spawnSync("npx", ["sg", "--version"], {
+            encoding: "utf-8",
+            timeout: 10000,
+            shell: true,
+        });
+        this.available = !result.error && result.status === 0;
+        if (this.available) {
+            this.log("ast-grep available");
+        }
+        return this.available;
+    }
+    /**
+     * Search for AST patterns in files
+     */
+    async search(pattern, lang, paths) {
+        return this.runSg([
+            "run",
+            "-p",
+            pattern,
+            "--lang",
+            lang,
+            "--json=compact",
+            ...paths,
+        ]);
+    }
+    /**
+     * Search and replace AST patterns
+     */
+    async replace(pattern, rewrite, lang, paths, apply = false) {
+        const args = [
+            "run",
+            "-p",
+            pattern,
+            "-r",
+            rewrite,
+            "--lang",
+            lang,
+            "--json=compact",
+        ];
+        if (apply)
+            args.push("--update-all");
+        args.push(...paths);
+        const result = await this.runSg(args);
+        return { matches: result.matches, applied: apply, error: result.error };
+    }
+    /**
+     * Run a one-off scan with a temporary rule and configuration
+     */
+    runTempScan(dir, ruleId, ruleYaml, timeout = 30000) {
+        if (!this.isAvailable())
+            return [];
+        const tmpDir = require("node:os").tmpdir();
+        const ts = Date.now();
+        const sessionDir = path.join(tmpDir, `pi-lens-temp-${ruleId}-${ts}`);
+        const rulesSubdir = path.join(sessionDir, "rules");
+        const ruleFile = path.join(rulesSubdir, `${ruleId}.yml`);
+        const configFile = path.join(sessionDir, ".sgconfig.yml");
+        try {
+            fs.mkdirSync(rulesSubdir, { recursive: true });
+            fs.writeFileSync(configFile, `ruleDirs:\n  - ./rules\n`);
+            fs.writeFileSync(ruleFile, ruleYaml);
+            const result = spawnSync("npx", ["sg", "scan", "--config", configFile, "--json", dir], {
+                encoding: "utf-8",
+                timeout,
+                shell: true,
+            });
+            const output = result.stdout || result.stderr || "";
+            if (!output.trim())
+                return [];
+            const items = JSON.parse(output);
+            return Array.isArray(items) ? items : [items];
+        }
+        catch (err) {
+            void err;
+            return [];
+        }
+        finally {
+            try {
+                fs.rmSync(sessionDir, { recursive: true, force: true });
+            }
+            catch (err) {
+                void err;
+            }
+        }
+    }
+    /**
+     * Find similar functions by comparing normalized AST structure
+     */
+    async findSimilarFunctions(dir, lang = "typescript") {
+        const ruleYaml = `id: find-functions
+language: ${lang}
+rule:
+  kind: function_declaration
+severity: info
+message: found
+`;
+        const matches = this.runTempScan(dir, "find-functions", ruleYaml);
+        if (matches.length === 0)
+            return [];
+        return this.groupSimilarFunctions(matches);
+    }
+    groupSimilarFunctions(matches) {
+        const normalized = new Map();
+        for (const item of matches) {
+            const text = item.text || "";
+            const nameMatch = text.match(/function\s+(\w+)/);
+            if (!nameMatch?.[1])
+                continue;
+            const signature = this.normalizeFunction(text);
+            if (!normalized.has(signature)) {
+                normalized.set(signature, []);
+            }
+            const line = item.range?.start?.line || item.labels?.[0]?.range?.start?.line || 0;
+            normalized.get(signature)?.push({
+                name: nameMatch[1],
+                file: item.file,
+                line: line + 1,
+            });
+        }
+        const result_groups = [];
+        for (const [pattern, functions] of normalized) {
+            if (functions.length > 1) {
+                result_groups.push({ pattern, functions });
+            }
+        }
+        return result_groups;
+    }
+    normalizeFunction(text) {
+        const normalizedText = text
+            .replace(/function\s+\w+/, "function FN")
+            .replace(/\bconst\b|\blet\b|\bvar\b/g, "VAR")
+            .replace(/["'].*?["']/g, "STR")
+            .replace(/`[^`]*`/g, "TMPL")
+            .replace(/\b\d+\b/g, "NUM")
+            .replace(/\btrue\b|\bfalse\b/g, "BOOL")
+            .replace(/\/\/.*/g, "")
+            .replace(/\/\*[\s\S]*?\*\//g, "")
+            .replace(/\s+/g, " ")
+            .trim();
+        // Extract just the body structure
+        const bodyMatch = normalizedText.match(/\{(.*)\}/);
+        const body = bodyMatch ? bodyMatch[1].trim() : normalizedText;
+        // Use first 200 chars as signature
+        return body.slice(0, 200);
+    }
+    /**
+     * Scan for exported function names in a directory
+     */
+    async scanExports(dir, lang = "typescript") {
+        const exports = new Map();
+        const ruleYaml = `id: find-functions
+language: ${lang}
+rule:
+  kind: function_declaration
+severity: info
+message: found
+`;
+        const matches = this.runTempScan(dir, "find-functions", ruleYaml, 15000);
+        this.log(`scanExports output length: ${matches.length}`);
+        for (const item of matches) {
+            const text = item.text || "";
+            const nameMatch = text.match(/function\s+(\w+)/);
+            if (nameMatch?.[1]) {
+                this.log(`scanExports found: ${nameMatch[1]} in ${item.file}`);
+                exports.set(nameMatch[1], item.file);
+            }
+        }
+        return exports;
+    }
+    runSg(args) {
+        return new Promise((resolve) => {
+            const proc = spawn("npx", ["sg", ...args], {
+                stdio: ["ignore", "pipe", "pipe"],
+                shell: true,
+            });
+            let stdout = "";
+            let stderr = "";
+            proc.stdout.on("data", (data) => (stdout += data.toString()));
+            proc.stderr.on("data", (data) => (stderr += data.toString()));
+            proc.on("error", (err) => {
+                if (err.message.includes("ENOENT")) {
+                    resolve({
+                        matches: [],
+                        error: "ast-grep CLI not found. Install: npm i -D @ast-grep/cli",
+                    });
+                }
+                else {
+                    resolve({ matches: [], error: err.message });
+                }
+            });
+            proc.on("close", (code) => {
+                if (code !== 0 && !stdout.trim()) {
+                    resolve({
+                        matches: [],
+                        error: stderr.includes("No files found")
+                            ? undefined
+                            : stderr.trim() || `Exit code ${code}`,
+                    });
+                    return;
+                }
+                if (!stdout.trim()) {
+                    resolve({ matches: [] });
+                    return;
+                }
+                try {
+                    const parsed = JSON.parse(stdout);
+                    const matches = Array.isArray(parsed) ? parsed : [parsed];
+                    resolve({ matches });
+                }
+                catch (err) {
+                    void err;
+                    resolve({ matches: [], error: "Failed to parse output" });
+                }
+            });
+        });
+    }
+    formatMatches(matches, isDryRun = false) {
+        if (matches.length === 0)
+            return "No matches found";
+        const MAX = 50;
+        const shown = matches.slice(0, MAX);
+        const lines = shown.map((m) => {
+            const loc = `${m.file}:${m.range.start.line + 1}:${m.range.start.column + 1}`;
+            const text = m.text.length > 100 ? `${m.text.slice(0, 100)}...` : m.text;
+            return isDryRun && m.replacement
+                ? `${loc}\n  - ${text}\n  + ${m.replacement}`
+                : `${loc}: ${text}`;
+        });
+        if (matches.length > MAX)
+            lines.unshift(`Found ${matches.length} matches (showing first ${MAX}):`);
+        return lines.join("\n");
+    }
+    /**
+     * Scan a file against all rules
+     */
+    scanFile(filePath) {
+        if (!this.isAvailable())
+            return [];
+        const absolutePath = path.resolve(filePath);
+        if (!fs.existsSync(absolutePath))
+            return [];
+        const configPath = path.join(this.ruleDir, ".sgconfig.yml");
+        try {
+            const result = spawnSync("npx", ["sg", "scan", "--config", configPath, "--json", absolutePath], {
+                encoding: "utf-8",
+                timeout: 15000,
+                shell: true,
+            });
+            // ast-grep exits 1 when it finds issues
+            const output = result.stdout || result.stderr || "";
+            if (!output.trim())
+                return [];
+            const parser = new AstGrepParser((id) => this.getRuleDescription(id), (sev) => this.mapSeverity(sev));
+            return parser.parseOutput(output, absolutePath);
+        }
+        catch (err) {
+            this.log(`Scan error: ${err.message}`);
+            return [];
+        }
+    }
+    /**
+     * Format diagnostics for LLM consumption
+     */
+    formatDiagnostics(diags) {
+        if (diags.length === 0)
+            return "";
+        const errors = diags.filter((d) => d.severity === "error");
+        const warnings = diags.filter((d) => d.severity === "warning");
+        const hints = diags.filter((d) => d.severity === "hint");
+        let output = `[ast-grep] ${diags.length} structural issue(s)`;
+        if (errors.length)
+            output += ` — ${errors.length} error(s)`;
+        if (warnings.length)
+            output += ` — ${warnings.length} warning(s)`;
+        if (hints.length)
+            output += ` — ${hints.length} hint(s)`;
+        output += ":\n";
+        for (const d of diags.slice(0, 10)) {
+            const loc = d.line === d.endLine ? `L${d.line}` : `L${d.line}-${d.endLine}`;
+            const ruleInfo = d.ruleDescription
+                ? `${d.rule}: ${d.ruleDescription.message}`
+                : d.rule;
+            const fix = d.fix || d.ruleDescription?.note ? " [fixable]" : "";
+            output += `  ${ruleInfo} (${loc})${fix}\n`;
+            if (d.ruleDescription?.note) {
+                const shortNote = d.ruleDescription.note.split("\n")[0];
+                output += `    → ${shortNote}\n`;
+            }
+        }
+        if (diags.length > 10) {
+            output += `  ... and ${diags.length - 10} more\n`;
+        }
+        return output;
+    }
+    getRuleDescription(ruleId) {
+        return this.ruleManager.loadRuleDescriptions().get(ruleId);
+    }
+    mapSeverity(severity) {
+        const lower = severity.toLowerCase();
+        if (lower === "error")
+            return "error";
+        if (lower === "warning")
+            return "warning";
+        if (lower === "info")
+            return "info";
+        return "hint";
+    }
+}