pi-lens 1.1.2 → 1.2.0

package/README.md

@@ -69,7 +69,16 @@ Example:
 | `/find-todos [path]` | Scan for TODO/FIXME/HACK annotations |
 | `/dead-code` | Find unused exports/files/dependencies (requires knip) |
 | `/check-deps` | Circular dependency scan (requires madge) |
-| `/format [file\|--all]` | Apply Biome formatting |
+| `/format [file|--all]` | Apply Biome formatting |
+
+### On-demand tools
+
+| Tool | Description |
+|---|---|
+| **`ast_grep_search`** | Search code patterns using AST-aware matching. Supports meta-variables: `$VAR` (single node), `$$$` (multiple). Example: `console.log($MSG)` |
+| **`ast_grep_replace`** | Replace code patterns with AST-aware rewriting. Dry-run by default, use `apply=true` to apply changes. Example: `pattern='console.log($MSG)' rewrite='logger.info($MSG)'` |
+
+Supported languages: c, cpp, csharp, css, dart, elixir, go, haskell, html, java, javascript, json, kotlin, lua, php, python, ruby, rust, scala, sql, swift, tsx, typescript, yaml
 
 ---
 
@@ -110,6 +119,8 @@ pip install ruff
 
 Rules live in `rules/ast-grep-rules/rules/`. All rules are YAML files you can edit or extend.
 
+Each rule includes a `message` and `note` that are shown in diagnostics, so the agent understands why something violated a rule and how to fix it.
+
 **Security**
 `no-eval`, `no-implied-eval`, `no-hardcoded-secrets`, `no-insecure-randomness`, `no-open-redirect`, `no-sql-in-code`, `no-inner-html`, `no-dangerously-set-inner-html`, `no-javascript-url`
 

package/clients/ast-grep-client.ts

@@ -8,12 +8,26 @@
  * Rules: ./rules/ directory
  */
 
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import * as path from "node:path";
 import * as fs from "node:fs";
 
 // --- Types ---
 
+export interface RuleDescription {
+  id: string;
+  message: string;
+  note?: string;
+  severity: "error" | "warning" | "info" | "hint";
+}
+
+export interface AstGrepMatch {
+  file: string;
+  range: { start: { line: number; column: number }; end: { line: number; column: number } };
+  text: string;
+  replacement?: string;
+}
+
 export interface AstGrepDiagnostic {
   line: number;
   column: number;
@@ -22,6 +36,7 @@ export interface AstGrepDiagnostic {
   severity: "error" | "warning" | "info" | "hint";
   message: string;
   rule: string;
+  ruleDescription?: RuleDescription;
   file: string;
   fix?: string;
 }
@@ -61,17 +76,89 @@ export class AstGrepClient {
   private available: boolean | null = null;
   private ruleDir: string;
   private log: (msg: string) => void;
+  private ruleDescriptions: Map<string, RuleDescription> | null = null;
 
   constructor(ruleDir?: string, verbose = false) {
     this.ruleDir = ruleDir || path.join(typeof __dirname !== "undefined" ? __dirname : ".", "..", "rules");
     this.log = verbose
       ? (msg: string) => console.log(`[ast-grep] ${msg}`)
       : () => {};
+  }
+
+  /**
+   * Load rule descriptions from YAML files
+   */
+  private loadRuleDescriptions(): Map<string, RuleDescription> {
+    if (this.ruleDescriptions !== null) return this.ruleDescriptions;
+
+    const descriptions = new Map<string, RuleDescription>();
+
+    // Find the rules directory - check more specific paths first
+    const possiblePaths = [
+      path.join(this.ruleDir, "ast-grep-rules", "rules"),
+      path.join(this.ruleDir, "rules"),
+      this.ruleDir,
+    ];
+
+    let rulesPath = possiblePaths.find(p => fs.existsSync(p));
+
+    if (!rulesPath) {
+      this.log(`Rule descriptions: no rules directory found in ${possiblePaths.join(", ")}`);
+      this.ruleDescriptions = descriptions;
+      return descriptions;
+    }
+
     try {
-      const nodeFs2 = require("node:fs") as typeof import("node:fs");
-      nodeFs2.appendFileSync("C:/Users/R3LiC/Desktop/pi-lens-debug.log",
-        `[${new Date().toISOString()}] AstGrepClient constructed, __dirname=${typeof __dirname !== "undefined" ? __dirname : "undefined"}, ruleDir=${this.ruleDir}\n`);
-    } catch {}
+      const files = fs.readdirSync(rulesPath).filter(f => f.endsWith(".yml"));
+      this.log(`Loaded ${files.length} rule descriptions from ${rulesPath}`);
+      for (const file of files) {
+        const filePath = path.join(rulesPath, file);
+        const content = fs.readFileSync(filePath, "utf-8");
+        const rule = this.parseRuleYaml(content);
+        if (rule) {
+          descriptions.set(rule.id, rule);
+        }
+      }
+    } catch (err: any) {
+      this.log(`Failed to load rule descriptions: ${err.message}`);
+    }
+
+    this.ruleDescriptions = descriptions;
+    return descriptions;
+  }
+
+  /**
+   * Simple YAML parser for rule descriptions
+   */
+  private parseRuleYaml(content: string): RuleDescription | null {
+    const result: Partial<RuleDescription> = {};
+
+    // Extract id
+    const idMatch = content.match(/^id:\s*(.+)$/m);
+    if (idMatch) result.id = idMatch[1].trim();
+
+    // Extract message (handle quoted strings)
+    const msgMatch = content.match(/^message:\s*"([^"]+)"/m) || content.match(/^message:\s*'([^']+)'/m) || content.match(/^message:\s*(.+)$/m);
+    if (msgMatch) result.message = (msgMatch[3] || msgMatch[2] || msgMatch[1]).trim();
+
+    // Extract note (multiline, indented lines)
+    const noteMatch = content.match(/^note:\s*\|([\s\S]*?)(?=^\w|\n\n|\nrule:)/m);
+    if (noteMatch) {
+      result.note = noteMatch[1]
+        .split("\n")
+        .map(line => line.trim())
+        .filter(line => line.length > 0)
+        .join(" ");
+    }
+
+    // Extract severity
+    const sevMatch = content.match(/^severity:\s*(.+)$/m);
+    if (sevMatch) result.severity = this.mapSeverity(sevMatch[1].trim());
+
+    if (result.id && result.message) {
+      return result as RuleDescription;
+    }
+    return null;
   }
 
   /**
@@ -94,6 +181,72 @@ export class AstGrepClient {
     return this.available;
   }
 
+  /**
+   * Search for AST patterns in files
+   */
+  async search(pattern: string, lang: string, paths: string[]): Promise<{ matches: AstGrepMatch[]; error?: string }> {
+    return this.runSg(["run", "-p", pattern, "--lang", lang, "--json=compact", ...paths]);
+  }
+
+  /**
+   * Search and replace AST patterns
+   */
+  async replace(pattern: string, rewrite: string, lang: string, paths: string[], apply = false): Promise<{ matches: AstGrepMatch[]; applied: boolean; error?: string }> {
+    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 };
+  }
+
+  private runSg(args: string[]): Promise<{ matches: AstGrepMatch[]; error?: string }> {
+    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: Buffer) => (stdout += data.toString()));
+      proc.stderr.on("data", (data: Buffer) => (stderr += data.toString()));
+
+      proc.on("error", (err: Error) => {
+        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: number | null) => {
+        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 {
+          resolve({ matches: [], error: "Failed to parse output" });
+        }
+      });
+    });
+  }
+
+  formatMatches(matches: AstGrepMatch[], isDryRun = false): string {
+    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
    */
@@ -137,22 +290,33 @@ export class AstGrepClient {
 
     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, 15)) {
+    for (const d of diags.slice(0, 10)) {
       const loc = d.line === d.endLine
         ? `L${d.line}`
         : `L${d.line}-${d.endLine}`;
-      const fix = d.fix ? " [fixable]" : "";
-      output += `  [${d.rule}] ${loc} ${d.message}${fix}\n`;
+      const ruleInfo = d.ruleDescription
+        ? `${d.rule}: ${d.ruleDescription.message}`
+        : d.rule;
+      const fix = d.fix || d.ruleDescription?.note ? " [fixable]" : "";
+      output += `  ${ruleInfo} (${loc})${fix}\n`;
+
+      // Include note for errors to provide fix guidance
+      if (d.severity === "error" && d.ruleDescription?.note) {
+        const shortNote = d.ruleDescription.note.split("\n")[0];
+        output += `    → ${shortNote}\n`;
+      }
     }
 
-    if (diags.length > 15) {
-      output += `  ... and ${diags.length - 15} more\n`;
+    if (diags.length > 10) {
+      output += `  ... and ${diags.length - 10} more\n`;
     }
 
     return output;
@@ -214,6 +378,7 @@ export class AstGrepClient {
         severity: this.mapSeverity(item.severity),
         message: item.message || "Unknown issue",
         rule: item.ruleId || "unknown",
+        ruleDescription: this.getRuleDescription(item.ruleId || "unknown"),
         file: filePath,
       };
     }
@@ -229,6 +394,7 @@ export class AstGrepClient {
       const start = span.range?.start || { line: 0, column: 0 };
       const end = span.range?.end || start;
 
+      const ruleId = item.name || item.ruleId || "unknown";
       return {
         line: start.line + 1,
         column: start.column,
@@ -236,7 +402,8 @@ export class AstGrepClient {
         endColumn: end.column,
         severity: this.mapSeverity(item.severity || item.Severity || "warning"),
         message: item.Message?.text || item.message || "Unknown issue",
-        rule: item.name || item.ruleId || "unknown",
+        rule: ruleId,
+        ruleDescription: this.getRuleDescription(ruleId),
         file: filePath,
       };
     }
@@ -244,6 +411,11 @@ export class AstGrepClient {
     return null;
   }
 
+  private getRuleDescription(ruleId: string): RuleDescription | undefined {
+    const descriptions = this.loadRuleDescriptions();
+    return descriptions.get(ruleId);
+  }
+
   private mapSeverity(severity: string): AstGrepDiagnostic["severity"] {
     const lower = severity.toLowerCase();
     if (lower === "error") return "error";

package/index.ts

@@ -28,6 +28,7 @@
 import * as nodeFs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { Type } from "@sinclair/typebox";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { isToolCallEventType } from "@mariozechner/pi-coding-agent";
 import { AstGrepClient } from "./clients/ast-grep-client.js";
@@ -55,13 +56,12 @@ function dbg(msg: string) {
 let _verbose = false;
 
 function log(msg: string) {
-	console.log(`[pi-lens] ${msg}`);
+	if (_verbose) console.log(`[pi-lens] ${msg}`);
 }
 
 // --- Extension ---
 
 export default function (pi: ExtensionAPI) {
-	log("Extension loaded");
 
 	const tsClient = new TypeScriptClient();
 	const astGrepClient = new AstGrepClient();
@@ -252,6 +252,74 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	// --- Tools ---
+
+	const LANGUAGES = [
+		"c", "cpp", "csharp", "css", "dart", "elixir", "go", "haskell", "html",
+		"java", "javascript", "json", "kotlin", "lua", "php", "python", "ruby",
+		"rust", "scala", "sql", "swift", "tsx", "typescript", "yaml",
+	] as const;
+
+	pi.registerTool({
+		name: "ast_grep_search",
+		label: "AST Search",
+		description: "Search code patterns using AST-aware matching. Use meta-variables: $VAR (single node), $$$ (multiple). Examples: 'console.log($MSG)', 'def $FUNC($$$):'",
+		parameters: Type.Object({
+			pattern: Type.String({ description: "AST pattern with meta-variables" }),
+			lang: Type.Union(LANGUAGES.map((l) => Type.Literal(l)), { description: "Target language" }),
+			paths: Type.Optional(Type.Array(Type.String(), { description: "Paths to search (default: .)" })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			if (!astGrepClient.isAvailable()) {
+				return { content: [{ type: "text", text: "ast-grep CLI not found. Install: npm i -D @ast-grep/cli" }], isError: true, details: {} };
+			}
+
+			const { pattern, lang, paths } = params as { pattern: string; lang: string; paths?: string[] };
+			const searchPaths = paths?.length ? paths : [ctx.cwd || "."];
+			const result = await astGrepClient.search(pattern, lang, searchPaths);
+
+			if (result.error) {
+				return { content: [{ type: "text", text: `Error: ${result.error}` }], isError: true, details: {} };
+			}
+
+			const output = astGrepClient.formatMatches(result.matches);
+			return { content: [{ type: "text", text: output }], details: { matchCount: result.matches.length } };
+		},
+	});
+
+	pi.registerTool({
+		name: "ast_grep_replace",
+		label: "AST Replace",
+		description: "Replace code patterns with AST-aware rewriting. Dry-run by default (preview changes). Use apply=true to apply. Example: pattern='console.log($MSG)' rewrite='logger.info($MSG)'",
+		parameters: Type.Object({
+			pattern: Type.String({ description: "AST pattern to match" }),
+			rewrite: Type.String({ description: "Replacement pattern" }),
+			lang: Type.Union(LANGUAGES.map((l) => Type.Literal(l)), { description: "Target language" }),
+			paths: Type.Optional(Type.Array(Type.String(), { description: "Paths to search (default: .)" })),
+			apply: Type.Optional(Type.Boolean({ description: "Apply changes (default: false)" })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			if (!astGrepClient.isAvailable()) {
+				return { content: [{ type: "text", text: "ast-grep CLI not found. Install: npm i -D @ast-grep/cli" }], isError: true, details: {} };
+			}
+
+			const { pattern, rewrite, lang, paths, apply } = params as { pattern: string; rewrite: string; lang: string; paths?: string[]; apply?: boolean };
+			const searchPaths = paths?.length ? paths : [ctx.cwd || "."];
+			const result = await astGrepClient.replace(pattern, rewrite, lang, searchPaths, apply ?? false);
+
+			if (result.error) {
+				return { content: [{ type: "text", text: `Error: ${result.error}` }], isError: true, details: {} };
+			}
+
+			const isDryRun = !apply;
+			let output = astGrepClient.formatMatches(result.matches, isDryRun);
+			if (isDryRun && result.matches.length > 0) output += "\n\n(Dry run - use apply=true to apply)";
+			if (apply && result.matches.length > 0) output = `Applied ${result.matches.length} replacements:\n${output}`;
+
+			return { content: [{ type: "text", text: output }], details: { matchCount: result.matches.length, applied: apply ?? false } };
+		},
+	});
+
 	// Delivered once into the first tool_result of the session, then cleared
 	let sessionSummary: string | null = null;
 

package/package.json

@@ -1,7 +1,8 @@
 {
 	"name": "pi-lens",
-	"version": "1.1.2",
+	"version": "1.2.0",
 	"description": "Real-time code feedback for pi — TypeScript LSP, Biome, ast-grep, Ruff, TODO scanner, dead code, duplicate detection, type coverage",
+	"repository": "github:apmantza/pi-lens",
 	"main": "index.ts",
 	"scripts": {
 		"build": "tsc",