pi-lens 2.0.44 → 2.1.0

package/README.md

@@ -16,6 +16,76 @@ pi install git:github.com/apmantza/pi-lens
 
 ---
 
+## What's New (v2.0)
+
+### Declarative Dispatch System
+
+The core linting engine has been redesigned from ~400 lines of nested `if/else` blocks into a clean, extensible dispatch architecture:
+
+```
+file → detectFileKind() → getRunnersForKind() → run all runners → aggregate output
+```
+
+**Key improvements:**
+- **Extensible**: Add new linters by dropping a runner file in `clients/dispatch/runners/` — no need to touch the core
+- **Unified output**: All tools report through the same format (🔴 blocking, 🟡 warning, ✅ fixed)
+- **Delta mode built-in**: Each runner supports baseline tracking to show only *new* violations
+- **Conditional execution**: Runners can have `when` conditions (e.g., only run when `--autofix` is enabled)
+
+**Runners:** `ts-lsp`, `biome`, `ruff`, `ast-grep`, `type-safety`, `architect`, `go-vet`, `rust-clippy`
+
+### Asynchronous Session Start
+
+Session initialization now runs all scans concurrently with caching:
+
+```
+session_start
+  ├─ TODO/FIXME scan (fast, uncached)
+  ├─ Knip dead code (cached 30 min)
+  ├─ jscpd duplicates (cached 30 min)
+  ├─ Type coverage (cached 30 min)
+  └─ Export scanning (async, for duplicate export detection)
+```
+
+Each scan runs independently — expensive scans (jscpd, knip) are cached in `.pi-lens/cache/` with 30-minute TTL. The agent sees results immediately without waiting for slow tools.
+
+### Inline Messaging
+
+Every `write` or `edit` operation returns structured feedback directly in the tool result:
+
+```typescript
+// tool_result handler runs dispatchLint() → formats output → appends to result
+return {
+  content: [...event.content, { type: "text", text: lspOutput }],
+};
+```
+
+**Message types:**
+| Prefix | Meaning |
+|--------|---------|
+| 🔴 | Blocking error — must fix before continuing |
+| 🟡 | Warning — should fix, but not blocking |
+| ✅ | Auto-fixed issue — no action needed |
+| 📊 | Silent metric — tracked but not shown |
+| 📐 | Architectural rule — reference only |
+
+### File Type Detection
+
+Centralized file-kind detection (`clients/file-kinds.ts`) replaces scattered regex checks:
+
+```typescript
+const kind = detectFileKind(filePath); // "jsts" | "python" | "go" | "rust" | ...
+const runners = getRunnersForKind(kind); // All applicable runners
+```
+
+### Project Rules Integration
+
+pi-lens now scans for project-specific rule files (`.claude/rules/`, `.agents/rules/`, `CLAUDE.md`, `AGENTS.md`) at session start. These are surfaced in the system prompt so the agent knows to read them when relevant.
+
+This works **alongside** pi-lens architect rules — your project's markdown rules provide general guidance, while pi-lens handles automated regex-based checks on every write.
+
+---
+
 ## Features
 
 ### On every write / edit
@@ -80,6 +150,25 @@ On every new session, scans run silently in the background. Data is cached for r
 | **jscpd** | Duplicate detection on write; `/lens-booboo` reports |
 | **type-coverage** | `/lens-booboo` reports |
 | **Complexity baselines** | Regressed/improved delta tracking via `/lens-metrics` |
+| **Project rules** | Scans for `.claude/rules/`, `.agents/rules/`, `CLAUDE.md`, `AGENTS.md` |
+
+### Project Rules Integration
+
+pi-lens scans for project-specific rule files at session start. If found, they're listed in the system prompt so the agent knows to read them when relevant:
+
+```
+📋 Project rules found: 2 file(s) in .claude/rules, root. These apply alongside pi-lens defaults.
+```
+
+**Scanned locations:**
+| Location | Description |
+|----------|-------------|
+| `.claude/rules/` | Claude Code rule files (recursive) |
+| `.agents/rules/` | Generic agent rule files (recursive) |
+| `CLAUDE.md` | Claude Code project context |
+| `AGENTS.md` | Generic agent context |
+
+These files provide **general project guidance** (coding conventions, workflow rules, architecture notes). They coexist with pi-lens architect rules — your rules inform the agent's behavior, while pi-lens provides automated regex-based checks on every write.
 
 ### On-demand commands
 

package/clients/agent-behavior-client.js

@@ -0,0 +1,110 @@
+/**
+ * AgentBehaviorClient for pi-lens
+ *
+ * Tracks tool call sequences and flags anti-patterns in real-time:
+ * - Blind writes: editing or writing without reading first
+ * - Thrashing: repeated identical tool calls with no progress
+ *
+ * No external dependencies — purely tracks tool call history.
+ */
+// --- Constants ---
+const WRITE_OPS = new Set(["edit", "write", "multiedit"]);
+const READ_OPS = new Set(["read", "bash", "grep", "glob", "find", "rg"]);
+const BLIND_WRITE_WINDOW = 5; // Check last N tool calls for a read
+const THRASH_THRESHOLD = 3; // Flag after N consecutive identical tools
+const THRASH_TIMEOUT_MS = 30000; // Reset thrash counter if gap > 30s
+// --- Client ---
+export class AgentBehaviorClient {
+    constructor() {
+        this.toolHistory = [];
+        this.consecutiveCount = 0;
+        this.lastToolName = null;
+        this.lastToolTimestamp = 0;
+        // Per-file tracking
+        this.fileEditCount = new Map();
+    }
+    /**
+     * Record a tool call and return any warnings triggered.
+     * Called from tool_result handler.
+     */
+    recordToolCall(toolName, filePath) {
+        const warnings = [];
+        const now = Date.now();
+        // Track consecutive identical tools (thrashing)
+        if (toolName === this.lastToolName &&
+            now - this.lastToolTimestamp < THRASH_TIMEOUT_MS) {
+            this.consecutiveCount++;
+        }
+        else {
+            this.consecutiveCount = 1;
+        }
+        this.lastToolName = toolName;
+        this.lastToolTimestamp = now;
+        // Check for thrashing
+        if (this.consecutiveCount === THRASH_THRESHOLD) {
+            warnings.push({
+                type: "thrashing",
+                message: `🔴 THRASHING — ${THRASH_THRESHOLD} consecutive \`${toolName}\` calls with no other action. Consider fixing the root cause instead of re-running.`,
+                severity: "error",
+                details: {
+                    toolName,
+                    callCount: this.consecutiveCount,
+                },
+            });
+        }
+        // Check for blind writes
+        if (WRITE_OPS.has(toolName)) {
+            const recentWindow = this.toolHistory.slice(-BLIND_WRITE_WINDOW);
+            const hasRecentRead = recentWindow.some((r) => READ_OPS.has(r.toolName));
+            if (!hasRecentRead && recentWindow.length > 0) {
+                // Count how many writes in the window without reads
+                const writesWithoutRead = recentWindow.filter((r) => WRITE_OPS.has(r.toolName)).length;
+                if (writesWithoutRead >= 2) {
+                    warnings.push({
+                        type: "blind-write",
+                        message: `⚠ BLIND WRITE — editing \`${filePath ?? "file"}\` without reading in the last ${BLIND_WRITE_WINDOW} tool calls. Read the file first to avoid assumptions.`,
+                        severity: "warning",
+                        details: {
+                            filePath,
+                            windowSize: recentWindow.length,
+                        },
+                    });
+                }
+            }
+            // Track edits per file
+            if (filePath) {
+                this.fileEditCount.set(filePath, (this.fileEditCount.get(filePath) ?? 0) + 1);
+            }
+        }
+        // Add to history (keep last 50 entries)
+        this.toolHistory.push({ toolName, filePath, timestamp: now });
+        if (this.toolHistory.length > 50) {
+            this.toolHistory = this.toolHistory.slice(-50);
+        }
+        return warnings;
+    }
+    /**
+     * Format warnings for LLM consumption.
+     */
+    formatWarnings(warnings) {
+        if (warnings.length === 0)
+            return "";
+        return warnings.map((w) => w.message).join("\n");
+    }
+    /**
+     * Get edit count for a file in this session.
+     */
+    getEditCount(filePath) {
+        return this.fileEditCount.get(filePath) ?? 0;
+    }
+    /**
+     * Reset state (e.g., on session start).
+     */
+    reset() {
+        this.toolHistory = [];
+        this.consecutiveCount = 0;
+        this.lastToolName = null;
+        this.lastToolTimestamp = 0;
+        this.fileEditCount.clear();
+    }
+}

package/clients/agent-behavior-client.test.js

@@ -0,0 +1,94 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { AgentBehaviorClient } from "./agent-behavior-client.js";
+describe("AgentBehaviorClient", () => {
+    let client;
+    beforeEach(() => {
+        client = new AgentBehaviorClient();
+        client.reset();
+    });
+    describe("blind write detection", () => {
+        it("should NOT warn when read precedes write", () => {
+            client.recordToolCall("read", "src/file.ts");
+            client.recordToolCall("edit", "src/file.ts");
+            const warnings = client.recordToolCall("write", "src/file.ts");
+            expect(warnings).toHaveLength(0);
+        });
+        it("should warn when multiple writes happen without reads", () => {
+            // First write is OK (no history)
+            client.recordToolCall("write", "src/file1.ts");
+            // Second write - still in window, accumulates
+            client.recordToolCall("edit", "src/file2.ts");
+            // Third write without any read - now we have a pattern
+            const warnings = client.recordToolCall("edit", "src/file3.ts");
+            expect(warnings).toHaveLength(1);
+            expect(warnings[0].type).toBe("blind-write");
+        });
+        it("should not warn for single write with no history", () => {
+            const warnings = client.recordToolCall("write", "src/file.ts");
+            expect(warnings).toHaveLength(0);
+        });
+    });
+    describe("thrashing detection", () => {
+        it("should warn after 3 consecutive identical tool calls", () => {
+            client.recordToolCall("bash", undefined);
+            // Second call - no warning yet
+            let warnings = client.recordToolCall("bash", undefined);
+            expect(warnings).toHaveLength(0);
+            // Third consecutive - should warn
+            warnings = client.recordToolCall("bash", undefined);
+            expect(warnings).toHaveLength(1);
+            expect(warnings[0].type).toBe("thrashing");
+            expect(warnings[0].details.callCount).toBe(3);
+        });
+        it("should NOT warn for different tool calls", () => {
+            client.recordToolCall("read", "src/file.ts");
+            client.recordToolCall("bash", "npm test");
+            const warnings = client.recordToolCall("edit", "src/file.ts");
+            expect(warnings).toHaveLength(0);
+        });
+        it("should reset count when tool changes", () => {
+            client.recordToolCall("bash", undefined);
+            client.recordToolCall("bash", undefined);
+            // Different tool resets the count
+            client.recordToolCall("read", "src/file.ts");
+            // Now start new consecutive sequence
+            client.recordToolCall("bash", undefined);
+            const warnings = client.recordToolCall("bash", undefined);
+            expect(warnings).toHaveLength(0); // Only 2 consecutive, not 3
+        });
+    });
+    describe("edit counting", () => {
+        it("should track edit count per file", () => {
+            client.recordToolCall("edit", "src/a.ts");
+            client.recordToolCall("edit", "src/a.ts");
+            client.recordToolCall("edit", "src/b.ts");
+            expect(client.getEditCount("src/a.ts")).toBe(2);
+            expect(client.getEditCount("src/b.ts")).toBe(1);
+            expect(client.getEditCount("src/c.ts")).toBe(0);
+        });
+    });
+    describe("formatWarnings", () => {
+        it("should format multiple warnings", () => {
+            const warnings = [
+                {
+                    type: "blind-write",
+                    message: "⚠ BLIND WRITE — editing file",
+                    severity: "warning",
+                    details: {},
+                },
+                {
+                    type: "thrashing",
+                    message: "🔴 THRASHING — 3 consecutive calls",
+                    severity: "error",
+                    details: {},
+                },
+            ];
+            const formatted = client.formatWarnings(warnings);
+            expect(formatted).toContain("BLIND WRITE");
+            expect(formatted).toContain("THRASHING");
+        });
+        it("should return empty string for no warnings", () => {
+            expect(client.formatWarnings([])).toBe("");
+        });
+    });
+});

package/clients/agent-behavior-client.test.ts

@@ -0,0 +1,116 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { AgentBehaviorClient } from "./agent-behavior-client.js";
+
+describe("AgentBehaviorClient", () => {
+	let client: AgentBehaviorClient;
+
+	beforeEach(() => {
+		client = new AgentBehaviorClient();
+		client.reset();
+	});
+
+	describe("blind write detection", () => {
+		it("should NOT warn when read precedes write", () => {
+			client.recordToolCall("read", "src/file.ts");
+			client.recordToolCall("edit", "src/file.ts");
+
+			const warnings = client.recordToolCall("write", "src/file.ts");
+			expect(warnings).toHaveLength(0);
+		});
+
+		it("should warn when multiple writes happen without reads", () => {
+			// First write is OK (no history)
+			client.recordToolCall("write", "src/file1.ts");
+
+			// Second write - still in window, accumulates
+			client.recordToolCall("edit", "src/file2.ts");
+
+			// Third write without any read - now we have a pattern
+			const warnings = client.recordToolCall("edit", "src/file3.ts");
+			expect(warnings).toHaveLength(1);
+			expect(warnings[0].type).toBe("blind-write");
+		});
+
+		it("should not warn for single write with no history", () => {
+			const warnings = client.recordToolCall("write", "src/file.ts");
+			expect(warnings).toHaveLength(0);
+		});
+	});
+
+	describe("thrashing detection", () => {
+		it("should warn after 3 consecutive identical tool calls", () => {
+			client.recordToolCall("bash", undefined);
+
+			// Second call - no warning yet
+			let warnings = client.recordToolCall("bash", undefined);
+			expect(warnings).toHaveLength(0);
+
+			// Third consecutive - should warn
+			warnings = client.recordToolCall("bash", undefined);
+			expect(warnings).toHaveLength(1);
+			expect(warnings[0].type).toBe("thrashing");
+			expect(warnings[0].details.callCount).toBe(3);
+		});
+
+		it("should NOT warn for different tool calls", () => {
+			client.recordToolCall("read", "src/file.ts");
+			client.recordToolCall("bash", "npm test");
+
+			const warnings = client.recordToolCall("edit", "src/file.ts");
+			expect(warnings).toHaveLength(0);
+		});
+
+		it("should reset count when tool changes", () => {
+			client.recordToolCall("bash", undefined);
+			client.recordToolCall("bash", undefined);
+
+			// Different tool resets the count
+			client.recordToolCall("read", "src/file.ts");
+
+			// Now start new consecutive sequence
+			client.recordToolCall("bash", undefined);
+
+			const warnings = client.recordToolCall("bash", undefined);
+			expect(warnings).toHaveLength(0); // Only 2 consecutive, not 3
+		});
+	});
+
+	describe("edit counting", () => {
+		it("should track edit count per file", () => {
+			client.recordToolCall("edit", "src/a.ts");
+			client.recordToolCall("edit", "src/a.ts");
+			client.recordToolCall("edit", "src/b.ts");
+
+			expect(client.getEditCount("src/a.ts")).toBe(2);
+			expect(client.getEditCount("src/b.ts")).toBe(1);
+			expect(client.getEditCount("src/c.ts")).toBe(0);
+		});
+	});
+
+	describe("formatWarnings", () => {
+		it("should format multiple warnings", () => {
+			const warnings = [
+				{
+					type: "blind-write" as const,
+					message: "⚠ BLIND WRITE — editing file",
+					severity: "warning" as const,
+					details: {},
+				},
+				{
+					type: "thrashing" as const,
+					message: "🔴 THRASHING — 3 consecutive calls",
+					severity: "error" as const,
+					details: {},
+				},
+			];
+
+			const formatted = client.formatWarnings(warnings);
+			expect(formatted).toContain("BLIND WRITE");
+			expect(formatted).toContain("THRASHING");
+		});
+
+		it("should return empty string for no warnings", () => {
+			expect(client.formatWarnings([])).toBe("");
+		});
+	});
+});

package/clients/agent-behavior-client.ts

@@ -0,0 +1,152 @@
+/**
+ * AgentBehaviorClient for pi-lens
+ *
+ * Tracks tool call sequences and flags anti-patterns in real-time:
+ * - Blind writes: editing or writing without reading first
+ * - Thrashing: repeated identical tool calls with no progress
+ *
+ * No external dependencies — purely tracks tool call history.
+ */
+
+// --- Types ---
+
+export type BehaviorWarning = {
+	type: "blind-write" | "thrashing";
+	message: string;
+	severity: "warning" | "error";
+	details: {
+		filePath?: string;
+		callCount?: number;
+		toolName?: string;
+		windowSize?: number;
+	};
+};
+
+interface ToolCallRecord {
+	toolName: string;
+	filePath?: string;
+	timestamp: number;
+}
+
+// --- Constants ---
+
+const WRITE_OPS = new Set(["edit", "write", "multiedit"]);
+const READ_OPS = new Set(["read", "bash", "grep", "glob", "find", "rg"]);
+
+const BLIND_WRITE_WINDOW = 5; // Check last N tool calls for a read
+const THRASH_THRESHOLD = 3; // Flag after N consecutive identical tools
+const THRASH_TIMEOUT_MS = 30_000; // Reset thrash counter if gap > 30s
+
+// --- Client ---
+
+export class AgentBehaviorClient {
+	private toolHistory: ToolCallRecord[] = [];
+	private consecutiveCount = 0;
+	private lastToolName: string | null = null;
+	private lastToolTimestamp = 0;
+
+	// Per-file tracking
+	private fileEditCount = new Map<string, number>();
+
+	/**
+	 * Record a tool call and return any warnings triggered.
+	 * Called from tool_result handler.
+	 */
+	recordToolCall(toolName: string, filePath?: string): BehaviorWarning[] {
+		const warnings: BehaviorWarning[] = [];
+		const now = Date.now();
+
+		// Track consecutive identical tools (thrashing)
+		if (
+			toolName === this.lastToolName &&
+			now - this.lastToolTimestamp < THRASH_TIMEOUT_MS
+		) {
+			this.consecutiveCount++;
+		} else {
+			this.consecutiveCount = 1;
+		}
+		this.lastToolName = toolName;
+		this.lastToolTimestamp = now;
+
+		// Check for thrashing
+		if (this.consecutiveCount === THRASH_THRESHOLD) {
+			warnings.push({
+				type: "thrashing",
+				message: `🔴 THRASHING — ${THRASH_THRESHOLD} consecutive \`${toolName}\` calls with no other action. Consider fixing the root cause instead of re-running.`,
+				severity: "error",
+				details: {
+					toolName,
+					callCount: this.consecutiveCount,
+				},
+			});
+		}
+
+		// Check for blind writes
+		if (WRITE_OPS.has(toolName)) {
+			const recentWindow = this.toolHistory.slice(-BLIND_WRITE_WINDOW);
+			const hasRecentRead = recentWindow.some((r) => READ_OPS.has(r.toolName));
+
+			if (!hasRecentRead && recentWindow.length > 0) {
+				// Count how many writes in the window without reads
+				const writesWithoutRead = recentWindow.filter((r) =>
+					WRITE_OPS.has(r.toolName),
+				).length;
+
+				if (writesWithoutRead >= 2) {
+					warnings.push({
+						type: "blind-write",
+						message: `⚠ BLIND WRITE — editing \`${filePath ?? "file"}\` without reading in the last ${BLIND_WRITE_WINDOW} tool calls. Read the file first to avoid assumptions.`,
+						severity: "warning",
+						details: {
+							filePath,
+							windowSize: recentWindow.length,
+						},
+					});
+				}
+			}
+
+			// Track edits per file
+			if (filePath) {
+				this.fileEditCount.set(
+					filePath,
+					(this.fileEditCount.get(filePath) ?? 0) + 1,
+				);
+			}
+		}
+
+		// Add to history (keep last 50 entries)
+		this.toolHistory.push({ toolName, filePath, timestamp: now });
+		if (this.toolHistory.length > 50) {
+			this.toolHistory = this.toolHistory.slice(-50);
+		}
+
+		return warnings;
+	}
+
+	/**
+	 * Format warnings for LLM consumption.
+	 */
+	formatWarnings(warnings: BehaviorWarning[]): string {
+		if (warnings.length === 0) return "";
+
+		return warnings.map((w) => w.message).join("\n");
+	}
+
+	/**
+	 * Get edit count for a file in this session.
+	 */
+	getEditCount(filePath: string): number {
+		return this.fileEditCount.get(filePath) ?? 0;
+	}
+
+	/**
+	 * Reset state (e.g., on session start).
+	 */
+	reset(): void {
+		this.toolHistory = [];
+		this.consecutiveCount = 0;
+		this.lastToolName = null;
+		this.lastToolTimestamp = 0;
+		this.fileEditCount.clear();
+	}
+}

package/clients/architect-client.js

@@ -15,6 +15,7 @@ import { minimatch } from "minimatch";
 export class ArchitectClient {
     constructor(verbose = false) {
         this.config = null;
+        this.configPath = null;
         this.isUserConfig = false;
         this.log = verbose
             ? (msg) => console.error(`[architect] ${msg}`)

package/clients/architect-client.ts

@@ -44,6 +44,7 @@ export interface FileArchitectResult {
 
 export class ArchitectClient {
 	private config: ArchitectConfig | null = null;
+	private configPath: string | null = null;
 	private isUserConfig: boolean = false;
 	private log: (msg: string) => void;
 

package/clients/ast-grep-client.js

@@ -13,7 +13,7 @@ import * as path from "node:path";
 import { AstGrepParser } from "./ast-grep-parser.js";
 import { AstGrepRuleManager } from "./ast-grep-rule-manager.js";
 import { SgRunner } from "./sg-runner.js";
-const getExtensionDir = () => {
+const _getExtensionDir = () => {
     if (typeof __dirname !== "undefined") {
         return __dirname;
     }
@@ -107,7 +107,8 @@ message: found
             if (!name)
                 continue;
             const signature = this.normalizeFunction(item.text);
-            const line = (item.range?.start?.line || item.labels?.[0]?.range?.start?.line || 0) + 1;
+            const line = (item.range?.start?.line || item.labels?.[0]?.range?.start?.line || 0) +
+                1;
             const group = grouped.get(signature) ?? [];
             group.push({ name, file: item.file, line });
             grouped.set(signature, group);

package/clients/ast-grep-client.ts

@@ -13,9 +13,9 @@ 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";
-import { SgRunner, type SgMatch } from "./sg-runner.js";
+import { type SgMatch, SgRunner } from "./sg-runner.js";
 
-const getExtensionDir = () => {
+const _getExtensionDir = () => {
 	if (typeof __dirname !== "undefined") {
 		return __dirname;
 	}
@@ -174,14 +174,19 @@ message: found
 		pattern: string;
 		functions: Array<{ name: string; file: string; line: number }>;
 	}> {
-		const grouped = new Map<string, Array<{ name: string; file: string; line: number }>>();
+		const grouped = new Map<
+			string,
+			Array<{ name: string; file: string; line: number }>
+		>();
 
 		for (const item of matches) {
 			const name = this.extractFunctionName(item.text);
 			if (!name) continue;
 
 			const signature = this.normalizeFunction(item.text);
-			const line = (item.range?.start?.line || item.labels?.[0]?.range?.start?.line || 0) + 1;
+			const line =
+				(item.range?.start?.line || item.labels?.[0]?.range?.start?.line || 0) +
+				1;
 
 			const group = grouped.get(signature) ?? [];
 			group.push({ name, file: item.file, line });

package/clients/auto-loop.js

@@ -25,7 +25,11 @@ export function createAutoLoop(pi, config) {
     };
     const stop = (ctx, reason) => {
         const wasActive = state.active;
-        state = { active: false, iteration: 0, maxIterations: config.maxIterations };
+        state = {
+            active: false,
+            iteration: 0,
+            maxIterations: config.maxIterations,
+        };
         updateStatus(ctx);
         if (wasActive) {
             ctx.ui.notify(`✅ ${config.name} loop ${reason}`, "info");