pi-lens 2.0.37 → 2.0.39

package/clients/metrics-history.js

@@ -0,0 +1,215 @@
+/**
+ * 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));
+}
+/**
+ * Capture a snapshot for a file's current metrics
+ */
+export function captureSnapshot(filePath, metrics, history) {
+    const hist = history ?? 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 = hist.files[relativePath];
+    if (existing) {
+        // 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
+        hist.files[relativePath] = {
+            latest: snapshot,
+            history: [snapshot],
+            trend: "stable",
+        };
+    }
+    return hist;
+}
+/**
+ * Capture snapshots for multiple files
+ */
+export function captureSnapshots(files) {
+    let history = loadHistory();
+    for (const file of files) {
+        history = captureSnapshot(file.filePath, file.metrics, history);
+    }
+    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,300 @@
+/**
+ * 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));
+}
+
+/**
+ * Capture a snapshot for a file's current metrics
+ */
+export function captureSnapshot(
+	filePath: string,
+	metrics: {
+		maintainabilityIndex: number;
+		cognitiveComplexity: number;
+		maxNestingDepth: number;
+		linesOfCode: number;
+	},
+	history?: MetricsHistory,
+): MetricsHistory {
+	const hist = history ?? 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 = hist.files[relativePath];
+
+	if (existing) {
+		// 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
+		hist.files[relativePath] = {
+			latest: snapshot,
+			history: [snapshot],
+			trend: "stable",
+		};
+	}
+
+	return hist;
+}
+
+/**
+ * Capture snapshots for multiple files
+ */
+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) {
+		history = captureSnapshot(file.filePath, file.metrics, history);
+	}
+
+	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/clients/scan-architectural-debt.js

@@ -2,8 +2,10 @@
  * Shared architectural debt scanning — used by booboo-fix and booboo-refactor.
  * Scans ast-grep skip rules + complexity metrics + architect.yaml rules.
  */
+import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { getSourceFiles, parseAstGrepJson } from "./scan-utils.js";
 /**
  * Scan for skip-category ast-grep violations grouped by absolute file path.
  */
@@ -11,34 +13,35 @@ export function scanSkipViolations(astGrepClient, configPath, targetPath, isTsPr
     const skipByFile = new Map();
     if (!astGrepClient.isAvailable())
         return skipByFile;
-    const { spawnSync } = require("node:child_process");
     const sgResult = spawnSync("npx", [
-        "sg", "scan", "--config", configPath, "--json",
-        "--globs", "!**/*.test.ts", "--globs", "!**/*.spec.ts",
-        "--globs", "!**/test-utils.ts", "--globs", "!**/.pi-lens/**",
+        "sg",
+        "scan",
+        "--config",
+        configPath,
+        "--json",
+        "--globs",
+        "!**/*.test.ts",
+        "--globs",
+        "!**/*.spec.ts",
+        "--globs",
+        "!**/test-utils.ts",
+        "--globs",
+        "!**/.pi-lens/**",
         ...(isTsProject ? ["--globs", "!**/*.js"] : []),
         targetPath,
-    ], { encoding: "utf-8", timeout: 30000, shell: true, maxBuffer: 32 * 1024 * 1024 });
-    const raw = sgResult.stdout?.trim() ?? "";
-    // biome-ignore lint/suspicious/noExplicitAny: ast-grep JSON output is untyped
-    const items = raw.startsWith("[")
-        ? (() => { try {
-            return JSON.parse(raw);
-        }
-        catch {
-            return [];
-        } })()
-        : raw.split("\n").flatMap((l) => { try {
-            return [JSON.parse(l)];
-        }
-        catch {
-            return [];
-        } });
+    ], {
+        encoding: "utf-8",
+        timeout: 30000,
+        shell: true,
+        maxBuffer: 32 * 1024 * 1024,
+    });
+    const items = parseAstGrepJson(sgResult.stdout?.trim() ?? "");
     for (const item of items) {
         const rule = item.ruleId || item.rule?.title || item.name || "unknown";
         if (!skipRules.has(rule))
             continue;
-        const line = (item.labels?.[0]?.range?.start?.line ?? item.range?.start?.line ?? 0) + 1;
+        const line = (item.labels?.[0]?.range?.start?.line ?? item.range?.start?.line ?? 0) +
+            1;
         const absFile = path.resolve(item.file ?? "");
         const list = skipByFile.get(absFile) ?? [];
         list.push({ rule, line, note: ruleActions[rule]?.note ?? "" });
@@ -51,26 +54,19 @@ export function scanSkipViolations(astGrepClient, configPath, targetPath, isTsPr
  */
 export function scanComplexityMetrics(complexityClient, targetPath, isTsProject) {
     const metricsByFile = new Map();
-    const scanDir = (dir) => {
-        if (!fs.existsSync(dir))
-            return;
-        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-            const full = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
-                if (["node_modules", ".git", "dist", "build", ".next", ".pi-lens"].includes(entry.name))
-                    continue;
-                scanDir(full);
-            }
-            else if (complexityClient.isSupportedFile(full) &&
-                !/\.(test|spec)\.[jt]sx?$/.test(entry.name) &&
-                !(isTsProject && /\.js$/.test(entry.name))) {
-                const m = complexityClient.analyzeFile(full);
-                if (m)
-                    metricsByFile.set(full, { mi: m.maintainabilityIndex, cognitive: m.cognitiveComplexity, nesting: m.maxNestingDepth });
-            }
+    const files = getSourceFiles(targetPath, isTsProject);
+    for (const full of files) {
+        if (complexityClient.isSupportedFile(full) &&
+            !/\.(test|spec)\.[jt]sx?$/.test(path.basename(full))) {
+            const m = complexityClient.analyzeFile(full);
+            if (m)
+                metricsByFile.set(full, {
+                    mi: m.maintainabilityIndex,
+                    cognitive: m.cognitiveComplexity,
+                    nesting: m.maxNestingDepth,
+                });
         }
-    };
-    scanDir(targetPath);
+    }
     return metricsByFile;
 }
 /**
@@ -81,37 +77,27 @@ export function scanArchitectViolations(architectClient, targetPath) {
     const violationsByFile = new Map();
     if (!architectClient.hasConfig())
         return violationsByFile;
-    const scanDir = (dir) => {
-        if (!fs.existsSync(dir))
-            return;
-        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-            const full = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
-                if (["node_modules", ".git", "dist", "build", ".next", ".pi-lens"].includes(entry.name))
-                    continue;
-                scanDir(full);
-            }
-            else if (/\.(ts|tsx|js|jsx|py|go|rs)$/.test(entry.name)) {
-                const relPath = path.relative(targetPath, full).replace(/\\/g, "/");
-                const content = fs.readFileSync(full, "utf-8");
-                const lineCount = content.split("\n").length;
-                const msgs = [];
-                // Check pattern violations
-                for (const v of architectClient.checkFile(relPath, content)) {
-                    msgs.push(v.message);
-                }
-                // Check file size
-                const sizeV = architectClient.checkFileSize(relPath, lineCount);
-                if (sizeV) {
-                    msgs.push(sizeV.message);
-                }
-                if (msgs.length > 0) {
-                    violationsByFile.set(full, msgs);
-                }
-            }
+    const isTsProject = fs.existsSync(path.join(targetPath, "tsconfig.json"));
+    const files = getSourceFiles(targetPath, isTsProject);
+    for (const full of files) {
+        const relPath = path.relative(targetPath, full).replace(/\\/g, "/");
+        const content = fs.readFileSync(full, "utf-8");
+        const lineCount = content.split("\n").length;
+        const msgs = [];
+        // Check pattern violations
+        for (const v of architectClient.checkFile(relPath, content)) {
+            const lineStr = v.line ? `L${v.line}: ` : "";
+            msgs.push(`${lineStr}${v.message}`);
         }
-    };
-    scanDir(targetPath);
+        // Check file size
+        const sizeV = architectClient.checkFileSize(relPath, lineCount);
+        if (sizeV) {
+            msgs.push(sizeV.message);
+        }
+        if (msgs.length > 0) {
+            violationsByFile.set(full, msgs);
+        }
+    }
     return violationsByFile;
 }
 /**
@@ -170,9 +156,13 @@ export function scoreFiles(skipByFile, metricsByFile, architectViolations) {
 export function extractCodeSnippet(filePath, firstLine, contextLines = 2, maxLines = 45) {
     try {
         const fileLines = fs.readFileSync(filePath, "utf-8").split("\n");
-        const start = Math.max(0, (firstLine - 1) - contextLines);
+        const start = Math.max(0, firstLine - 1 - contextLines);
         const end = Math.min(fileLines.length, start + maxLines);
-        return { snippet: fileLines.slice(start, end).join("\n"), start: start + 1, end };
+        return {
+            snippet: fileLines.slice(start, end).join("\n"),
+            start: start + 1,
+            end,
+        };
     }
     catch {
         return null;