pi-lens 2.0.38 → 2.0.40

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to pi-lens will be documented in this file.
 
+## [2.0.40] - 2026-03-27
+
+### Changed
+- **Passive capture on every file edit**: `captureSnapshot()` now called from `tool_call` hook with 5s debounce. Zero latency — reuses complexity metrics already computed for real-time feedback.
+- **Skip duplicate snapshots**: Same commit + same MI = no write (reduces noise).
+
+## [2.0.39] - 2026-03-27
+
+### Added
+- **Historical metrics tracking**: New `clients/metrics-history.ts` module captures complexity snapshots per commit. Tracks MI, cognitive complexity, and nesting depth across sessions.
+- **Trend analysis in `/lens-metrics`**: New "Trend" column shows 📈/📉/➡️ with MI delta. "Trend Summary" section aggregates improving/stable/regressing counts with worst regressions.
+- **Passive capture**: Snapshots captured on every file edit (tool_call hook) + `/lens-metrics` run. Max 20 snapshots per file (sliding window).
+
+## [2.0.38] - 2026-03-27
+
+### Changed
+- **Refactored 4 client files** via `/lens-booboo-refactor` loop:
+  - `biome-client.ts`: Extracted `withValidatedPath()` guard pattern (4 methods consolidated)
+  - `complexity-client.ts`: Extracted `analyzeFile()` pipeline into `readAndParse()`, `computeMetrics()`, `aggregateFunctionStats()`
+  - `dependency-checker.ts`: Simplified `importsChanged()` — replaced 3 for-loops with `setsEqual()` helper
+  - `ast-grep-client.ts`: Simplified `groupSimilarFunctions()` with `filter().map()` pattern + `extractFunctionName()` helper
+
 ## [2.0.29] - 2026-03-26
 
 ### Added

package/README.md

@@ -77,7 +77,7 @@ On every new session, scans run silently in the background. Data is cached for r
 | `/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-metrics [path]` | Measure complexity metrics for all files. Exports `report.md` with grades (A-F), summary stats, and top 10 worst files |
+| `/lens-metrics [path]` | Measure complexity metrics for all files. Exports `report.md` with grades (A-F), summary stats, top 10 worst files, and **historical trends** (📈📉 per file) |
 
 ### On-demand tools
 

package/clients/ast-grep-client.js

@@ -101,30 +101,26 @@ message: found
         return this.groupSimilarFunctions(matches);
     }
     groupSimilarFunctions(matches) {
-        const normalized = new Map();
+        const grouped = new Map();
         for (const item of matches) {
-            const text = item.text || "";
-            const nameMatch = text.match(/function\s+(\w+)/);
-            if (!nameMatch?.[1])
+            const name = this.extractFunctionName(item.text);
+            if (!name)
                 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 signature = this.normalizeFunction(item.text);
+            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);
         }
-        const result_groups = [];
-        for (const [pattern, functions] of normalized) {
-            if (functions.length > 1) {
-                result_groups.push({ pattern, functions });
-            }
-        }
-        return result_groups;
+        return Array.from(grouped.entries())
+            .filter(([_, functions]) => functions.length > 1)
+            .map(([pattern, functions]) => ({ pattern, functions }));
+    }
+    /**
+     * Extract function name from match text
+     */
+    extractFunctionName(text) {
+        return text.match(/function\s+(\w+)/)?.[1] ?? null;
     }
     normalizeFunction(text) {
         const normalizedText = text

package/clients/biome-client.js

@@ -56,14 +56,24 @@ export class BiomeClient {
             ".cjs",
         ].includes(ext);
     }
+    // --- Internal helpers ---
     /**
-     * Run biome check (format + lint) without fixing — returns diagnostics
+     * Validate path and availability — returns path or null on failure
      */
-    checkFile(filePath) {
+    withValidatedPath(filePath) {
         if (!this.isAvailable())
-            return [];
+            return null;
         const absolutePath = path.resolve(filePath);
         if (!fs.existsSync(absolutePath))
+            return null;
+        return absolutePath;
+    }
+    /**
+     * Run biome check (format + lint) without fixing — returns diagnostics
+     */
+    checkFile(filePath) {
+        const absolutePath = this.withValidatedPath(filePath);
+        if (!absolutePath)
             return [];
         try {
             const result = spawnSync("npx", [
@@ -92,11 +102,13 @@ export class BiomeClient {
      * Format a file (writes to disk)
      */
     formatFile(filePath) {
-        if (!this.isAvailable())
-            return { success: false, changed: false, error: "Biome not available" };
-        const absolutePath = path.resolve(filePath);
-        if (!fs.existsSync(absolutePath))
-            return { success: false, changed: false, error: "File not found" };
+        const absolutePath = this.withValidatedPath(filePath);
+        if (!absolutePath)
+            return {
+                success: false,
+                changed: false,
+                error: this.isAvailable() ? "File not found" : "Biome not available",
+            };
         const content = fs.readFileSync(absolutePath, "utf-8");
         try {
             const result = spawnSync("npx", ["@biomejs/biome", "format", "--write", absolutePath], {
@@ -123,20 +135,13 @@ export class BiomeClient {
      * Fix both formatting and linting issues (writes to disk)
      */
     fixFile(filePath) {
-        if (!this.isAvailable())
+        const absolutePath = this.withValidatedPath(filePath);
+        if (!absolutePath)
             return {
                 success: false,
                 changed: false,
                 fixed: 0,
-                error: "Biome not available",
-            };
-        const absolutePath = path.resolve(filePath);
-        if (!fs.existsSync(absolutePath))
-            return {
-                success: false,
-                changed: false,
-                fixed: 0,
-                error: "File not found",
+                error: this.isAvailable() ? "File not found" : "Biome not available",
             };
         const content = fs.readFileSync(absolutePath, "utf-8");
         try {
@@ -211,10 +216,8 @@ export class BiomeClient {
      * Generate a diff-like summary of formatting changes
      */
     getFormatDiff(filePath) {
-        if (!this.isAvailable())
-            return "";
-        const absolutePath = path.resolve(filePath);
-        if (!fs.existsSync(absolutePath))
+        const absolutePath = this.withValidatedPath(filePath);
+        if (!absolutePath)
             return "";
         const content = fs.readFileSync(absolutePath, "utf-8");
         try {

package/clients/complexity-client.js

@@ -126,70 +126,88 @@ export class ComplexityClient {
      * Analyze complexity metrics for a file
      */
     analyzeFile(filePath) {
-        const absolutePath = path.resolve(filePath);
-        if (!fs.existsSync(absolutePath))
+        const parsed = this.readAndParse(filePath);
+        if (!parsed)
             return null;
         try {
-            const content = fs.readFileSync(absolutePath, "utf-8");
-            const lines = content.split("\n");
-            const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true);
-            // Count lines of code (non-empty, non-comment)
-            const { codeLines, commentLines } = this.countLines(sourceFile, lines);
-            // Collect function metrics
-            const functions = [];
-            this.collectFunctionMetrics(sourceFile, sourceFile, functions, 0);
-            // Calculate file-level metrics
-            const maxNestingDepth = this.calculateMaxNesting(sourceFile, 0);
-            const _cyclomatic = this.calculateCyclomaticComplexity(sourceFile);
-            const cognitive = this.calculateCognitiveComplexity(sourceFile);
-            const halstead = this.calculateHalsteadVolume(sourceFile);
-            // Function length stats
-            const funcLengths = functions.map((f) => f.length);
-            const avgFunctionLength = funcLengths.length > 0
-                ? Math.round(funcLengths.reduce((a, b) => a + b, 0) / funcLengths.length)
-                : 0;
-            const maxFunctionLength = funcLengths.length > 0 ? Math.max(...funcLengths) : 0;
-            // Function cyclomatic stats
-            const cyclomatics = functions.map((f) => f.cyclomatic);
-            const avgCyclomatic = cyclomatics.length > 0
-                ? Math.round(cyclomatics.reduce((a, b) => a + b, 0) / cyclomatics.length)
-                : 1;
-            const maxCyclomatic = cyclomatics.length > 0 ? Math.max(...cyclomatics) : 1;
-            // Maintainability Index (simplified Microsoft formula)
-            // MI = max(0, (171 - 5.2 * ln(Halstead) - 0.23 * Cyclomatic - 16.2 * ln(LOC)) * 100 / 171)
-            const maintainabilityIndex = this.calculateMaintainabilityIndex(halstead, avgCyclomatic, codeLines, commentLines);
-            // Code Entropy (Shannon entropy of code tokens)
-            const codeEntropy = this.calculateCodeEntropy(content);
-            // AI slop indicators
-            const maxParamsInFunction = this.calculateMaxParams(functions);
-            const aiCommentPatterns = this.countAICommentPatterns(sourceFile);
-            const singleUseFunctions = this.countSingleUseFunctions(functions);
-            const tryCatchCount = this.countTryCatch(sourceFile);
-            return {
-                filePath: path.relative(process.cwd(), absolutePath),
-                maxNestingDepth,
-                avgFunctionLength,
-                maxFunctionLength,
-                functionCount: functions.length,
-                cyclomaticComplexity: avgCyclomatic,
-                maxCyclomaticComplexity: maxCyclomatic,
-                cognitiveComplexity: cognitive,
-                halsteadVolume: Math.round(halstead * 10) / 10,
-                maintainabilityIndex: Math.round(maintainabilityIndex * 10) / 10,
-                linesOfCode: codeLines,
-                commentLines,
-                codeEntropy: Math.round(codeEntropy * 100) / 100,
-                maxParamsInFunction,
-                aiCommentPatterns,
-                singleUseFunctions,
-                tryCatchCount,
-            };
+            return this.computeMetrics(parsed);
         }
         catch (err) {
             this.log(`Analysis error for ${filePath}: ${err.message}`);
             return null;
         }
     }
+    /**
+     * Read file and parse to TypeScript AST
+     */
+    readAndParse(filePath) {
+        const absolutePath = path.resolve(filePath);
+        if (!fs.existsSync(absolutePath))
+            return null;
+        const content = fs.readFileSync(absolutePath, "utf-8");
+        const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true);
+        return { absolutePath, content, sourceFile };
+    }
+    /**
+     * Compute all metrics from parsed source
+     */
+    computeMetrics(parsed) {
+        const { absolutePath, content, sourceFile } = parsed;
+        const lines = content.split("\n");
+        // Line counts and function collection
+        const { codeLines, commentLines } = this.countLines(sourceFile, lines);
+        const functions = this.collectFunctionMetrics(sourceFile);
+        // File-level complexity metrics
+        const maxNestingDepth = this.calculateMaxNesting(sourceFile, 0);
+        const cognitive = this.calculateCognitiveComplexity(sourceFile);
+        const halstead = this.calculateHalsteadVolume(sourceFile);
+        // Aggregate function statistics
+        const funcStats = this.aggregateFunctionStats(functions);
+        // Derived metrics
+        const maintainabilityIndex = this.calculateMaintainabilityIndex(halstead, funcStats.avgCyclomatic, codeLines, commentLines);
+        const codeEntropy = this.calculateCodeEntropy(content);
+        // AI slop indicators
+        const maxParamsInFunction = this.calculateMaxParams(functions);
+        const aiCommentPatterns = this.countAICommentPatterns(sourceFile);
+        const singleUseFunctions = this.countSingleUseFunctions(functions);
+        const tryCatchCount = this.countTryCatch(sourceFile);
+        return {
+            filePath: path.relative(process.cwd(), absolutePath),
+            maxNestingDepth,
+            avgFunctionLength: funcStats.avgLength,
+            maxFunctionLength: funcStats.maxLength,
+            functionCount: functions.length,
+            cyclomaticComplexity: funcStats.avgCyclomatic,
+            maxCyclomaticComplexity: funcStats.maxCyclomatic,
+            cognitiveComplexity: cognitive,
+            halsteadVolume: Math.round(halstead * 10) / 10,
+            maintainabilityIndex: Math.round(maintainabilityIndex * 10) / 10,
+            linesOfCode: codeLines,
+            commentLines,
+            codeEntropy: Math.round(codeEntropy * 100) / 100,
+            maxParamsInFunction,
+            aiCommentPatterns,
+            singleUseFunctions,
+            tryCatchCount,
+        };
+    }
+    /**
+     * Aggregate function metrics into summary statistics
+     */
+    aggregateFunctionStats(functions) {
+        if (functions.length === 0) {
+            return { avgLength: 0, maxLength: 0, avgCyclomatic: 1, maxCyclomatic: 1 };
+        }
+        const lengths = functions.map((f) => f.length);
+        const cyclomatics = functions.map((f) => f.cyclomatic);
+        const sum = (arr) => arr.reduce((a, b) => a + b, 0);
+        return {
+            avgLength: Math.round(sum(lengths) / lengths.length),
+            maxLength: Math.max(...lengths),
+            avgCyclomatic: Math.max(1, Math.round(sum(cyclomatics) / cyclomatics.length)),
+            maxCyclomatic: Math.max(1, Math.max(...cyclomatics)),
+        };
+    }
     /**
      * Format metrics for display
      */
@@ -401,7 +419,15 @@ export class ComplexityClient {
         return { codeLines, commentLines };
     }
     // --- Private: Function Metrics Collection ---
-    collectFunctionMetrics(node, sourceFile, functions, nestingLevel) {
+    /**
+     * Collect metrics for all functions in the source file
+     */
+    collectFunctionMetrics(sourceFile) {
+        const functions = [];
+        this.visitFunctionMetrics(sourceFile, sourceFile, functions, 0);
+        return functions;
+    }
+    visitFunctionMetrics(node, sourceFile, functions, nestingLevel) {
         if (FUNCTION_LIKE_NODES.has(node.kind)) {
             const funcNode = node;
             const startLine = sourceFile.getLineAndCharacterOfPosition(node.getStart()).line;
@@ -427,7 +453,7 @@ export class ComplexityClient {
             ? nestingLevel + 1
             : nestingLevel;
         ts.forEachChild(node, (child) => {
-            this.collectFunctionMetrics(child, sourceFile, functions, newNesting);
+            this.visitFunctionMetrics(child, sourceFile, functions, newNesting);
         });
     }
     // --- Private: Max Nesting Depth ---

package/clients/dependency-checker.js

@@ -95,46 +95,32 @@ export class DependencyChecker {
     importsChanged(filePath) {
         const normalized = path.resolve(filePath);
         if (!fs.existsSync(normalized)) {
-            // File deleted, remove from cache
             this.importCache.delete(normalized);
             return true;
         }
         const stat = fs.statSync(normalized);
-        const mtime = stat.mtimeMs;
         const cached = this.importCache.get(normalized);
-        // If timestamp hasn't changed, imports haven't changed
-        if (cached && cached.timestamp >= mtime) {
+        // Fast path: timestamp hasn't changed
+        if (cached && cached.timestamp >= stat.mtimeMs) {
             return false;
         }
-        // Parse new imports
+        // Compare actual imports
         const newImports = this.extractImports(normalized);
-        const newEntry = {
-            imports: newImports,
-            timestamp: mtime,
-        };
-        // Check if imports actually changed
-        if (cached) {
-            if (cached.imports.size !== newImports.size) {
-                this.importCache.set(normalized, newEntry);
-                return true;
-            }
-            for (const imp of newImports) {
-                if (!cached.imports.has(imp)) {
-                    this.importCache.set(normalized, newEntry);
-                    return true;
-                }
-            }
-            for (const imp of cached.imports) {
-                if (!newImports.has(imp)) {
-                    this.importCache.set(normalized, newEntry);
-                    return true;
-                }
-            }
-            // Imports are the same, just update timestamp
-            this.importCache.set(normalized, newEntry);
+        const hasChanged = !cached || !this.setsEqual(cached.imports, newImports);
+        // Update cache
+        this.importCache.set(normalized, { imports: newImports, timestamp: stat.mtimeMs });
+        return hasChanged;
+    }
+    /**
+     * Check if two sets have the same elements
+     */
+    setsEqual(a, b) {
+        if (a.size !== b.size)
             return false;
+        for (const item of a) {
+            if (!b.has(item))
+                return false;
         }
-        this.importCache.set(normalized, newEntry);
         return true;
     }
     /**

package/clients/metrics-history.js

@@ -0,0 +1,262 @@
+/**
+ * Metrics History Tracker for pi-lens
+ *
+ * Persists complexity metrics per commit to track trends over time.
+ * Captures snapshots passively (session start) and explicitly (/lens-metrics).
+ *
+ * Storage: .pi-lens/metrics-history.json
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+// --- Constants ---
+const HISTORY_FILE = ".pi-lens/metrics-history.json";
+const MAX_HISTORY_PER_FILE = 20;
+// --- Git Helpers ---
+/**
+ * Get current git commit hash (short)
+ */
+function getCurrentCommit() {
+    try {
+        const { execSync } = require("node:child_process");
+        return execSync("git rev-parse --short HEAD", {
+            encoding: "utf-8",
+            timeout: 5000,
+        }).trim();
+    }
+    catch {
+        return "unknown";
+    }
+}
+// --- History Management ---
+/**
+ * Load history from disk (or return empty)
+ */
+export function loadHistory() {
+    const historyPath = path.join(process.cwd(), HISTORY_FILE);
+    if (!fs.existsSync(historyPath)) {
+        return {
+            version: 1,
+            files: {},
+            capturedAt: new Date().toISOString(),
+        };
+    }
+    try {
+        const content = fs.readFileSync(historyPath, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return {
+            version: 1,
+            files: {},
+            capturedAt: new Date().toISOString(),
+        };
+    }
+}
+/**
+ * Save history to disk
+ */
+export function saveHistory(history) {
+    const historyDir = path.join(process.cwd(), ".pi-lens");
+    if (!fs.existsSync(historyDir)) {
+        fs.mkdirSync(historyDir, { recursive: true });
+    }
+    history.capturedAt = new Date().toISOString();
+    const historyPath = path.join(historyDir, "metrics-history.json");
+    fs.writeFileSync(historyPath, JSON.stringify(history, null, 2));
+}
+// In-memory cache to avoid loading/saving on every capture
+let pendingHistory = null;
+let saveTimer = null;
+const SAVE_DEBOUNCE_MS = 5000; // Save at most every 5 seconds
+/**
+ * Capture a snapshot for a file's current metrics
+ * Auto-saves to disk (debounced) for passive tracking
+ */
+export function captureSnapshot(filePath, metrics) {
+    // Use in-memory cache if available, otherwise load from disk
+    if (!pendingHistory) {
+        pendingHistory = loadHistory();
+    }
+    const relativePath = path.relative(process.cwd(), filePath);
+    const commit = getCurrentCommit();
+    const snapshot = {
+        commit,
+        timestamp: new Date().toISOString(),
+        mi: Math.round(metrics.maintainabilityIndex * 10) / 10,
+        cognitive: metrics.cognitiveComplexity,
+        nesting: metrics.maxNestingDepth,
+        lines: metrics.linesOfCode,
+    };
+    const existing = pendingHistory.files[relativePath];
+    if (existing) {
+        // Skip if same commit + same MI (no change worth recording)
+        const latest = existing.latest;
+        if (latest.commit === commit && latest.mi === snapshot.mi) {
+            return;
+        }
+        // Append to history (cap at MAX_HISTORY_PER_FILE)
+        existing.history.push(snapshot);
+        if (existing.history.length > MAX_HISTORY_PER_FILE) {
+            existing.history = existing.history.slice(-MAX_HISTORY_PER_FILE);
+        }
+        existing.latest = snapshot;
+        existing.trend = computeTrend(existing.history);
+    }
+    else {
+        // New file
+        pendingHistory.files[relativePath] = {
+            latest: snapshot,
+            history: [snapshot],
+            trend: "stable",
+        };
+    }
+    // Debounced save to disk
+    if (saveTimer)
+        clearTimeout(saveTimer);
+    saveTimer = setTimeout(() => {
+        if (pendingHistory) {
+            saveHistory(pendingHistory);
+            pendingHistory = null;
+        }
+    }, SAVE_DEBOUNCE_MS);
+}
+/**
+ * Capture snapshots for multiple files (explicit, immediate save)
+ * Used by /lens-metrics for batch capture
+ */
+export function captureSnapshots(files) {
+    let history = loadHistory();
+    for (const file of files) {
+        const relativePath = path.relative(process.cwd(), file.filePath);
+        const commit = getCurrentCommit();
+        const snapshot = {
+            commit,
+            timestamp: new Date().toISOString(),
+            mi: Math.round(file.metrics.maintainabilityIndex * 10) / 10,
+            cognitive: file.metrics.cognitiveComplexity,
+            nesting: file.metrics.maxNestingDepth,
+            lines: file.metrics.linesOfCode,
+        };
+        const existing = history.files[relativePath];
+        if (existing) {
+            existing.history.push(snapshot);
+            if (existing.history.length > MAX_HISTORY_PER_FILE) {
+                existing.history = existing.history.slice(-MAX_HISTORY_PER_FILE);
+            }
+            existing.latest = snapshot;
+            existing.trend = computeTrend(existing.history);
+        }
+        else {
+            history.files[relativePath] = {
+                latest: snapshot,
+                history: [snapshot],
+                trend: "stable",
+            };
+        }
+    }
+    saveHistory(history);
+    return history;
+}
+// --- Trend Analysis ---
+/**
+ * Compute trend direction from history snapshots
+ * Uses last 3 snapshots for stability (or 2 if only 2 available)
+ */
+export function computeTrend(history) {
+    if (history.length < 2)
+        return "stable";
+    const recent = history.slice(-3);
+    const first = recent[0];
+    const last = recent[recent.length - 1];
+    // Use MI as primary indicator, cognitive as secondary
+    const miDelta = last.mi - first.mi;
+    const cogDelta = last.cognitive - first.cognitive;
+    // Thresholds (MI changes < 2 are noise)
+    if (miDelta > 2)
+        return "improving";
+    if (miDelta < -2)
+        return "regressing";
+    // If MI is stable, check cognitive
+    if (cogDelta < -10)
+        return "improving";
+    if (cogDelta > 10)
+        return "regressing";
+    return "stable";
+}
+/**
+ * Get delta between current snapshot and previous
+ */
+export function getDelta(history) {
+    if (!history || history.history.length < 2)
+        return null;
+    const current = history.history[history.history.length - 1];
+    const previous = history.history[history.history.length - 2];
+    return {
+        mi: Math.round((current.mi - previous.mi) * 10) / 10,
+        cognitive: current.cognitive - previous.cognitive,
+        trend: history.trend,
+    };
+}
+/**
+ * Get trend emoji for display
+ */
+export function getTrendEmoji(trend) {
+    switch (trend) {
+        case "improving":
+            return "📈";
+        case "regressing":
+            return "📉";
+        default:
+            return "➡️";
+    }
+}
+/**
+ * Get trend summary across all files
+ */
+export function getTrendSummary(history) {
+    let improving = 0;
+    let regressing = 0;
+    let stable = 0;
+    const regressions = [];
+    for (const [file, fileHistory] of Object.entries(history.files)) {
+        switch (fileHistory.trend) {
+            case "improving":
+                improving++;
+                break;
+            case "regressing":
+                regressing++;
+                const delta = getDelta(fileHistory);
+                if (delta) {
+                    regressions.push({ file, miDelta: delta.mi });
+                }
+                break;
+            default:
+                stable++;
+        }
+    }
+    // Sort regressions by MI delta (worst first)
+    regressions.sort((a, b) => a.miDelta - b.miDelta);
+    return {
+        improving,
+        regressing,
+        stable,
+        worstRegressions: regressions.slice(0, 5),
+    };
+}
+/**
+ * Format trend for metrics table
+ */
+export function formatTrendCell(filePath, history) {
+    const relativePath = path.relative(process.cwd(), filePath);
+    const fileHistory = history.files[relativePath];
+    if (!fileHistory || fileHistory.history.length < 2) {
+        return "—"; // No history
+    }
+    const delta = getDelta(fileHistory);
+    if (!delta)
+        return "—";
+    const emoji = getTrendEmoji(delta.trend);
+    const miSign = delta.mi > 0 ? "+" : "";
+    const miColor = delta.mi > 0 ? "🟢" : delta.mi < 0 ? "🔴" : "⚪";
+    return `${emoji} ${miColor}${miSign}${delta.mi}`;
+}

package/clients/metrics-history.ts

@@ -0,0 +1,349 @@
+/**
+ * Metrics History Tracker for pi-lens
+ *
+ * Persists complexity metrics per commit to track trends over time.
+ * Captures snapshots passively (session start) and explicitly (/lens-metrics).
+ *
+ * Storage: .pi-lens/metrics-history.json
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+// --- Types ---
+
+export interface MetricSnapshot {
+	commit: string;
+	timestamp: string;
+	mi: number;
+	cognitive: number;
+	nesting: number;
+	lines: number;
+}
+
+export interface FileHistory {
+	latest: MetricSnapshot;
+	history: MetricSnapshot[];
+	trend: "improving" | "stable" | "regressing";
+}
+
+export interface MetricsHistory {
+	version: number;
+	files: Record<string, FileHistory>;
+	capturedAt: string;
+}
+
+export type TrendDirection = "improving" | "stable" | "regressing";
+
+// --- Constants ---
+
+const HISTORY_FILE = ".pi-lens/metrics-history.json";
+const MAX_HISTORY_PER_FILE = 20;
+
+// --- Git Helpers ---
+
+/**
+ * Get current git commit hash (short)
+ */
+function getCurrentCommit(): string {
+	try {
+		const { execSync } = require("node:child_process");
+		return execSync("git rev-parse --short HEAD", {
+			encoding: "utf-8",
+			timeout: 5000,
+		}).trim();
+	} catch {
+		return "unknown";
+	}
+}
+
+// --- History Management ---
+
+/**
+ * Load history from disk (or return empty)
+ */
+export function loadHistory(): MetricsHistory {
+	const historyPath = path.join(process.cwd(), HISTORY_FILE);
+
+	if (!fs.existsSync(historyPath)) {
+		return {
+			version: 1,
+			files: {},
+			capturedAt: new Date().toISOString(),
+		};
+	}
+
+	try {
+		const content = fs.readFileSync(historyPath, "utf-8");
+		return JSON.parse(content);
+	} catch {
+		return {
+			version: 1,
+			files: {},
+			capturedAt: new Date().toISOString(),
+		};
+	}
+}
+
+/**
+ * Save history to disk
+ */
+export function saveHistory(history: MetricsHistory): void {
+	const historyDir = path.join(process.cwd(), ".pi-lens");
+	if (!fs.existsSync(historyDir)) {
+		fs.mkdirSync(historyDir, { recursive: true });
+	}
+
+	history.capturedAt = new Date().toISOString();
+	const historyPath = path.join(historyDir, "metrics-history.json");
+	fs.writeFileSync(historyPath, JSON.stringify(history, null, 2));
+}
+
+// In-memory cache to avoid loading/saving on every capture
+let pendingHistory: MetricsHistory | null = null;
+let saveTimer: ReturnType<typeof setTimeout> | null = null;
+const SAVE_DEBOUNCE_MS = 5000; // Save at most every 5 seconds
+
+/**
+ * Capture a snapshot for a file's current metrics
+ * Auto-saves to disk (debounced) for passive tracking
+ */
+export function captureSnapshot(
+	filePath: string,
+	metrics: {
+		maintainabilityIndex: number;
+		cognitiveComplexity: number;
+		maxNestingDepth: number;
+		linesOfCode: number;
+	},
+): void {
+	// Use in-memory cache if available, otherwise load from disk
+	if (!pendingHistory) {
+		pendingHistory = loadHistory();
+	}
+
+	const relativePath = path.relative(process.cwd(), filePath);
+	const commit = getCurrentCommit();
+
+	const snapshot: MetricSnapshot = {
+		commit,
+		timestamp: new Date().toISOString(),
+		mi: Math.round(metrics.maintainabilityIndex * 10) / 10,
+		cognitive: metrics.cognitiveComplexity,
+		nesting: metrics.maxNestingDepth,
+		lines: metrics.linesOfCode,
+	};
+
+	const existing = pendingHistory.files[relativePath];
+
+	if (existing) {
+		// Skip if same commit + same MI (no change worth recording)
+		const latest = existing.latest;
+		if (latest.commit === commit && latest.mi === snapshot.mi) {
+			return;
+		}
+		// Append to history (cap at MAX_HISTORY_PER_FILE)
+		existing.history.push(snapshot);
+		if (existing.history.length > MAX_HISTORY_PER_FILE) {
+			existing.history = existing.history.slice(-MAX_HISTORY_PER_FILE);
+		}
+		existing.latest = snapshot;
+		existing.trend = computeTrend(existing.history);
+	} else {
+		// New file
+		pendingHistory.files[relativePath] = {
+			latest: snapshot,
+			history: [snapshot],
+			trend: "stable",
+		};
+	}
+
+	// Debounced save to disk
+	if (saveTimer) clearTimeout(saveTimer);
+	saveTimer = setTimeout(() => {
+		if (pendingHistory) {
+			saveHistory(pendingHistory);
+			pendingHistory = null;
+		}
+	}, SAVE_DEBOUNCE_MS);
+}
+
+/**
+ * Capture snapshots for multiple files (explicit, immediate save)
+ * Used by /lens-metrics for batch capture
+ */
+export function captureSnapshots(
+	files: Array<{
+		filePath: string;
+		metrics: {
+			maintainabilityIndex: number;
+			cognitiveComplexity: number;
+			maxNestingDepth: number;
+			linesOfCode: number;
+		};
+	}>,
+): MetricsHistory {
+	let history = loadHistory();
+
+	for (const file of files) {
+		const relativePath = path.relative(process.cwd(), file.filePath);
+		const commit = getCurrentCommit();
+
+		const snapshot: MetricSnapshot = {
+			commit,
+			timestamp: new Date().toISOString(),
+			mi: Math.round(file.metrics.maintainabilityIndex * 10) / 10,
+			cognitive: file.metrics.cognitiveComplexity,
+			nesting: file.metrics.maxNestingDepth,
+			lines: file.metrics.linesOfCode,
+		};
+
+		const existing = history.files[relativePath];
+
+		if (existing) {
+			existing.history.push(snapshot);
+			if (existing.history.length > MAX_HISTORY_PER_FILE) {
+				existing.history = existing.history.slice(-MAX_HISTORY_PER_FILE);
+			}
+			existing.latest = snapshot;
+			existing.trend = computeTrend(existing.history);
+		} else {
+			history.files[relativePath] = {
+				latest: snapshot,
+				history: [snapshot],
+				trend: "stable",
+			};
+		}
+	}
+
+	saveHistory(history);
+	return history;
+}
+
+// --- Trend Analysis ---
+
+/**
+ * Compute trend direction from history snapshots
+ * Uses last 3 snapshots for stability (or 2 if only 2 available)
+ */
+export function computeTrend(history: MetricSnapshot[]): TrendDirection {
+	if (history.length < 2) return "stable";
+
+	const recent = history.slice(-3);
+	const first = recent[0];
+	const last = recent[recent.length - 1];
+
+	// Use MI as primary indicator, cognitive as secondary
+	const miDelta = last.mi - first.mi;
+	const cogDelta = last.cognitive - first.cognitive;
+
+	// Thresholds (MI changes < 2 are noise)
+	if (miDelta > 2) return "improving";
+	if (miDelta < -2) return "regressing";
+
+	// If MI is stable, check cognitive
+	if (cogDelta < -10) return "improving";
+	if (cogDelta > 10) return "regressing";
+
+	return "stable";
+}
+
+/**
+ * Get delta between current snapshot and previous
+ */
+export function getDelta(history: FileHistory | null): {
+	mi: number;
+	cognitive: number;
+	trend: TrendDirection;
+} | null {
+	if (!history || history.history.length < 2) return null;
+
+	const current = history.history[history.history.length - 1];
+	const previous = history.history[history.history.length - 2];
+
+	return {
+		mi: Math.round((current.mi - previous.mi) * 10) / 10,
+		cognitive: current.cognitive - previous.cognitive,
+		trend: history.trend,
+	};
+}
+
+/**
+ * Get trend emoji for display
+ */
+export function getTrendEmoji(trend: TrendDirection): string {
+	switch (trend) {
+		case "improving":
+			return "📈";
+		case "regressing":
+			return "📉";
+		default:
+			return "➡️";
+	}
+}
+
+/**
+ * Get trend summary across all files
+ */
+export function getTrendSummary(history: MetricsHistory): {
+	improving: number;
+	regressing: number;
+	stable: number;
+	worstRegressions: Array<{ file: string; miDelta: number }>;
+} {
+	let improving = 0;
+	let regressing = 0;
+	let stable = 0;
+	const regressions: Array<{ file: string; miDelta: number }> = [];
+
+	for (const [file, fileHistory] of Object.entries(history.files)) {
+		switch (fileHistory.trend) {
+			case "improving":
+				improving++;
+				break;
+			case "regressing":
+				regressing++;
+				const delta = getDelta(fileHistory);
+				if (delta) {
+					regressions.push({ file, miDelta: delta.mi });
+				}
+				break;
+			default:
+				stable++;
+		}
+	}
+
+	// Sort regressions by MI delta (worst first)
+	regressions.sort((a, b) => a.miDelta - b.miDelta);
+
+	return {
+		improving,
+		regressing,
+		stable,
+		worstRegressions: regressions.slice(0, 5),
+	};
+}
+
+/**
+ * Format trend for metrics table
+ */
+export function formatTrendCell(
+	filePath: string,
+	history: MetricsHistory,
+): string {
+	const relativePath = path.relative(process.cwd(), filePath);
+	const fileHistory = history.files[relativePath];
+
+	if (!fileHistory || fileHistory.history.length < 2) {
+		return "—"; // No history
+	}
+
+	const delta = getDelta(fileHistory);
+	if (!delta) return "—";
+
+	const emoji = getTrendEmoji(delta.trend);
+	const miSign = delta.mi > 0 ? "+" : "";
+	const miColor = delta.mi > 0 ? "🟢" : delta.mi < 0 ? "🔴" : "⚪";
+
+	return `${emoji} ${miColor}${miSign}${delta.mi}`;
+}

package/index.ts

@@ -14,6 +14,7 @@ import { buildInterviewer } from "./clients/interviewer.js";
 import { JscpdClient } from "./clients/jscpd-client.js";
 import { KnipClient } from "./clients/knip-client.js";
 import { MetricsClient } from "./clients/metrics-client.js";
+import { captureSnapshot, captureSnapshots, getTrendSummary, formatTrendCell } from "./clients/metrics-history.js";
 import { RuffClient } from "./clients/ruff-client.js";
 import { RustClient } from "./clients/rust-client.js";
 import { getSourceFiles } from "./clients/scan-utils.js";
@@ -366,6 +367,19 @@ export default function (pi: ExtensionAPI) {
 				gradeCount[g.letter as keyof typeof gradeCount]++;
 			}
 
+			// Capture snapshots for history tracking
+			const history = captureSnapshots(
+				results.map((r) => ({
+					filePath: r.filePath,
+					metrics: {
+						maintainabilityIndex: r.maintainabilityIndex,
+						cognitiveComplexity: r.cognitiveComplexity,
+						maxNestingDepth: r.maxNestingDepth,
+						linesOfCode: r.linesOfCode,
+					},
+				})),
+			);
+
 			// Build report
 			let report = `# Code Metrics Report: ${projectName}\n\n`;
 			report += `**Generated:** ${new Date().toISOString()}\n\n`;
@@ -438,8 +452,8 @@ export default function (pi: ExtensionAPI) {
 
 			// All files table (sorted by MI ascending)
 			report += `## All Files\n\n`;
-			report += `| Grade | File | MI | Cognitive | Cyclomatic | Nesting | Functions | LOC | Entropy |\n`;
-			report += `|-------|------|-----|-----------|------------|---------|-----------|-----|--------|\n`;
+			report += `| Grade | File | MI | Cognitive | Nesting | LOC | Trend |\n`;
+			report += `|-------|------|-----|-----------|---------|-----|-------|\n`;
 
 			const sorted = [...results].sort(
 				(a, b) => a.maintainabilityIndex - b.maintainabilityIndex,
@@ -455,11 +469,30 @@ export default function (pi: ExtensionAPI) {
 
 				// Make path relative for readability
 				const relPath = path.relative(targetPath, f.filePath);
+				const trendCell = formatTrendCell(f.filePath, history);
 
-				report += `| ${grade} | ${relPath} | ${mi.toFixed(1)} | ${f.cognitiveComplexity} | ${f.cyclomaticComplexity.toFixed(1)} | ${f.maxNestingDepth} | ${f.functionCount} | ${f.linesOfCode} | ${f.codeEntropy.toFixed(2)} |\n`;
+				report += `| ${grade} | ${relPath} | ${mi.toFixed(1)} | ${f.cognitiveComplexity} | ${f.maxNestingDepth} | ${f.linesOfCode} | ${trendCell} |\n`;
 			}
 			report += `\n`;
 
+			// Trend Summary
+			const trendSummary = getTrendSummary(history);
+			report += `## Trend Summary\n\n`;
+			report += `| Trend | Count |\n`;
+			report += `|-------|-------|\n`;
+			report += `| 📈 Improving | ${trendSummary.improving} |\n`;
+			report += `| ➡️ Stable | ${trendSummary.stable} |\n`;
+			report += `| 📉 Regressing | ${trendSummary.regressing} |\n\n`;
+
+			if (trendSummary.worstRegressions.length > 0) {
+				report += `### Top Regressions\n\n`;
+				report += `Files with largest MI decline since last scan:\n\n`;
+				for (const r of trendSummary.worstRegressions) {
+					report += `- **${r.file}**: MI ${r.miDelta > 0 ? "+" : ""}${r.miDelta}\n`;
+				}
+				report += `\n`;
+			}
+
 			// Top 10 worst files (actionable)
 			report += `## Top 10 Files Needing Attention\n\n`;
 			report += `These files have the lowest maintainability scores:\n\n`;
@@ -869,7 +902,7 @@ export default function (pi: ExtensionAPI) {
 		);
 		if (!nodeFs.existsSync(filePath)) return;
 
-		// Record complexity baseline for TS/JS files
+		// Record complexity baseline for TS/JS files + capture history snapshot
 		if (
 			complexityClient.isSupportedFile(filePath) &&
 			!complexityBaselines.has(filePath)
@@ -877,6 +910,13 @@ export default function (pi: ExtensionAPI) {
 			const baseline = complexityClient.analyzeFile(filePath);
 			if (baseline) {
 				complexityBaselines.set(filePath, baseline);
+				// Capture snapshot for historical tracking (async, non-blocking)
+				captureSnapshot(filePath, {
+					maintainabilityIndex: baseline.maintainabilityIndex,
+					cognitiveComplexity: baseline.cognitiveComplexity,
+					maxNestingDepth: baseline.maxNestingDepth,
+					linesOfCode: baseline.linesOfCode,
+				});
 			}
 		}
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-lens",
-	"version": "2.0.38",
+	"version": "2.0.40",
 	"description": "Real-time code quality feedback for pi — TypeScript LSP, Biome, ast-grep, Ruff, complexity metrics, duplicate detection. Includes automated fix loop (/lens-booboo-fix) and interactive architectural refactoring (/lens-booboo-refactor) with browser-based interviews.",
 	"repository": {
 		"type": "git",