pi-lens 2.2.6 → 2.2.8

package/clients/metrics-history.js

@@ -261,3 +261,81 @@ export function formatTrendCell(filePath, history) {
     const miColor = delta.mi > 0 ? "🟢" : delta.mi < 0 ? "🔴" : "⚪";
     return `${emoji} ${miColor}${miSign}${delta.mi}`;
 }
+/**
+ * Calculate Technical Debt Index for the project.
+ * Score: 0 = perfect, 100 = maximum debt.
+ */
+export function computeTDI(history) {
+    const files = Object.values(history.files);
+    if (files.length === 0) {
+        return {
+            score: 0,
+            grade: "N/A",
+            avgMI: 100,
+            totalCognitive: 0,
+            filesAnalyzed: 0,
+            filesWithDebt: 0,
+            byCategory: { complexity: 0, maintainability: 0, nesting: 0 },
+        };
+    }
+    let totalMI = 0;
+    let totalCognitive = 0;
+    let totalNesting = 0;
+    let filesWithDebt = 0;
+    let debtFromMI = 0;
+    let debtFromCognitive = 0;
+    let debtFromNesting = 0;
+    for (const file of files) {
+        const snap = file.latest;
+        totalMI += snap.mi;
+        totalCognitive += snap.cognitive;
+        totalNesting += snap.nesting;
+        // Accumulate debt points
+        let fileDebt = 0;
+        // MI debt: 0 at MI=100, max at MI=0
+        const miDebt = Math.max(0, (100 - snap.mi) / 100);
+        debtFromMI += miDebt;
+        // Cognitive debt: 0 at 0, max at 500+
+        const cogDebt = Math.min(1, snap.cognitive / 200);
+        debtFromCognitive += cogDebt;
+        // Nesting debt: 0 at 1-3, max at 10+
+        const nestDebt = Math.min(1, Math.max(0, snap.nesting - 3) / 7);
+        debtFromNesting += nestDebt;
+        fileDebt = miDebt + cogDebt + nestDebt;
+        if (fileDebt > 1)
+            filesWithDebt++; // File has at least some debt
+    }
+    const avgMI = totalMI / files.length;
+    // Normalize to 0-100 scale
+    const avgMIDebt = debtFromMI / files.length; // 0-1
+    const avgCogDebt = debtFromCognitive / files.length; // 0-1
+    const avgNestDebt = debtFromNesting / files.length; // 0-1
+    // Weighted: MI matters most (50%), cognitive (35%), nesting (15%)
+    const rawScore = avgMIDebt * 50 + avgCogDebt * 35 + avgNestDebt * 15;
+    const score = Math.round(rawScore * 100) / 100;
+    // Grade
+    let grade;
+    if (score <= 15)
+        grade = "A";
+    else if (score <= 30)
+        grade = "B";
+    else if (score <= 50)
+        grade = "C";
+    else if (score <= 70)
+        grade = "D";
+    else
+        grade = "F";
+    return {
+        score,
+        grade,
+        avgMI: Math.round(avgMI * 10) / 10,
+        totalCognitive,
+        filesAnalyzed: files.length,
+        filesWithDebt,
+        byCategory: {
+            complexity: Math.round(avgCogDebt * 100),
+            maintainability: Math.round(avgMIDebt * 100),
+            nesting: Math.round(avgNestDebt * 100),
+        },
+    };
+}

package/clients/metrics-history.ts

@@ -348,3 +348,104 @@ export function formatTrendCell(
 
 	return `${emoji} ${miColor}${miSign}${delta.mi}`;
 }
+
+// --- Technical Debt Index (TDI) ---
+
+export interface ProjectTDI {
+	score: number; // 0-100, higher = more debt
+	grade: string; // A-F
+	avgMI: number;
+	totalCognitive: number;
+	filesAnalyzed: number;
+	filesWithDebt: number;
+	byCategory: {
+		complexity: number;
+		maintainability: number;
+		nesting: number;
+	};
+}
+
+/**
+ * Calculate Technical Debt Index for the project.
+ * Score: 0 = perfect, 100 = maximum debt.
+ */
+export function computeTDI(history: MetricsHistory): ProjectTDI {
+	const files = Object.values(history.files);
+	if (files.length === 0) {
+		return {
+			score: 0,
+			grade: "N/A",
+			avgMI: 100,
+			totalCognitive: 0,
+			filesAnalyzed: 0,
+			filesWithDebt: 0,
+			byCategory: { complexity: 0, maintainability: 0, nesting: 0 },
+		};
+	}
+
+	let totalMI = 0;
+	let totalCognitive = 0;
+	let totalNesting = 0;
+	let filesWithDebt = 0;
+	let debtFromMI = 0;
+	let debtFromCognitive = 0;
+	let debtFromNesting = 0;
+
+	for (const file of files) {
+		const snap = file.latest;
+		totalMI += snap.mi;
+		totalCognitive += snap.cognitive;
+		totalNesting += snap.nesting;
+
+		// Accumulate debt points
+		let fileDebt = 0;
+
+		// MI debt: 0 at MI=100, max at MI=0
+		const miDebt = Math.max(0, (100 - snap.mi) / 100);
+		debtFromMI += miDebt;
+
+		// Cognitive debt: 0 at 0, max at 500+
+		const cogDebt = Math.min(1, snap.cognitive / 200);
+		debtFromCognitive += cogDebt;
+
+		// Nesting debt: 0 at 1-3, max at 10+
+		const nestDebt = Math.min(1, Math.max(0, snap.nesting - 3) / 7);
+		debtFromNesting += nestDebt;
+
+		fileDebt = miDebt + cogDebt + nestDebt;
+		if (fileDebt > 1) filesWithDebt++; // File has at least some debt
+	}
+
+	const avgMI = totalMI / files.length;
+
+	// Normalize to 0-100 scale
+	const avgMIDebt = debtFromMI / files.length; // 0-1
+	const avgCogDebt = debtFromCognitive / files.length; // 0-1
+	const avgNestDebt = debtFromNesting / files.length; // 0-1
+
+	// Weighted: MI matters most (50%), cognitive (35%), nesting (15%)
+	const rawScore = avgMIDebt * 50 + avgCogDebt * 35 + avgNestDebt * 15;
+	const score = Math.round(rawScore * 100) / 100;
+
+	// Grade
+	let grade: string;
+	if (score <= 15) grade = "A";
+	else if (score <= 30) grade = "B";
+	else if (score <= 50) grade = "C";
+	else if (score <= 70) grade = "D";
+	else grade = "F";
+
+	return {
+		score,
+		grade,
+		avgMI: Math.round(avgMI * 10) / 10,
+		totalCognitive,
+		filesAnalyzed: files.length,
+		filesWithDebt,
+		byCategory: {
+			complexity: Math.round(avgCogDebt * 100),
+			maintainability: Math.round(avgMIDebt * 100),
+			nesting: Math.round(avgNestDebt * 100),
+		},
+	};
+}

package/commands/fix.js

@@ -112,41 +112,57 @@ function generatePlan(results, session, _isTsProject, prevCounts) {
         }
     }
     nodeFs.writeFileSync(reportPath, tsvRows.join("\n"), "utf-8");
-    // --- Build compact summary for terminal ---
+    // --- Build actionable list for terminal (no TSV reading needed) ---
     const lines = [];
-    lines.push(`📋 FIX PLAN — Iteration ${session.iteration}/${MAX_ITERATIONS} — ${totalFixable} issues`);
-    lines.push(`📄 Full plan: .pi-lens/reports/fix-plan.tsv\n`);
-    // Summary by category with counts
+    lines.push(`📋 FIX PLAN — Iteration ${session.iteration}/${MAX_ITERATIONS} — ${totalFixable} issues:\n`);
+    // Duplicates
     if (filteredDups.length > 0) {
-        lines.push(`🔁 Duplicates: ${filteredDups.length} block(s) — extract to shared utils`);
+        for (const clone of filteredDups.slice(0, 10)) {
+            lines.push(`🔁 ${clone.fileA}:${clone.startA} — ${clone.lines} dup from ${clone.fileB}:${clone.startB}`);
+        }
+        if (filteredDups.length > 10)
+            lines.push(`   ... +${filteredDups.length - 10} more`);
+        lines.push("");
     }
+    // Dead code
     if (filteredDeadCode.length > 0) {
-        lines.push(`🗑️ Dead code: ${filteredDeadCode.length} item(s) — remove unused exports`);
+        for (const issue of filteredDeadCode.slice(0, 10)) {
+            lines.push(`🗑️ ${issue.file || issue.name} — ${issue.name} unused`);
+        }
+        if (filteredDeadCode.length > 10)
+            lines.push(`   ... +${filteredDeadCode.length - 10} more`);
+        lines.push("");
     }
+    // AST lint
     if (agentTasks.length > 0) {
-        // Group by rule, show top 5 rules
-        const grouped = new Map();
-        for (const t of agentTasks) {
-            grouped.set(t.rule, (grouped.get(t.rule) ?? 0) + 1);
+        for (const issue of agentTasks.slice(0, 15)) {
+            lines.push(`🔨 ${issue.file}:${issue.line} — ${issue.rule}`);
         }
-        const sorted = [...grouped.entries()].sort((a, b) => b[1] - a[1]);
-        lines.push(`🔨 Lint: ${agentTasks.length} item(s)`);
-        for (const [rule, count] of sorted.slice(0, 5)) {
-            lines.push(`   ${rule}: ${count}`);
-        }
-        if (sorted.length > 5)
-            lines.push(`   ... and ${sorted.length - 5} more rules`);
+        if (agentTasks.length > 15)
+            lines.push(`   ... +${agentTasks.length - 15} more`);
+        lines.push("");
     }
+    // Biome
     if (filteredBiome.length > 0) {
-        lines.push(`🟠 Biome: ${filteredBiome.length} item(s) — auto-fixable`);
+        for (const issue of filteredBiome.slice(0, 10)) {
+            lines.push(`🟠 ${issue.file}:${issue.line} — ${issue.rule}`);
+        }
+        if (filteredBiome.length > 10)
+            lines.push(`   ... +${filteredBiome.length - 10} more`);
+        lines.push("");
     }
+    // AI Slop
     if (filteredSlop.length > 0) {
-        lines.push(`🤖 AI Slop: ${filteredSlop.length} file(s) — review complexity`);
+        for (const { file, warnings } of filteredSlop.slice(0, 5)) {
+            lines.push(`🤖 ${file} — ${warnings[0]}`);
+        }
+        if (filteredSlop.length > 5)
+            lines.push(`   ... +${filteredSlop.length - 5} more`);
+        lines.push("");
     }
-    lines.push("\n---");
-    lines.push("📖 **Read plan**: `read .pi-lens/reports/fix-plan.tsv` for full details");
-    lines.push("🚀 **Fix & loop**: Fix items, then run `/lens-booboo-fix --loop`");
-    lines.push('🚫 **False positive**: `/lens-booboo-fix --false-positive "type:file:line"`');
+    lines.push("---");
+    lines.push("🚀 Fix items above, then run `/lens-booboo-fix --loop`");
+    lines.push('🚫 False positive: `/lens-booboo-fix --false-positive "type:file:line"`');
     return lines.join("\n");
 }
 // --- Main handler ---

package/commands/fix.ts

@@ -183,56 +183,68 @@ function generatePlan(
 
 	nodeFs.writeFileSync(reportPath, tsvRows.join("\n"), "utf-8");
 
-	// --- Build compact summary for terminal ---
+	// --- Build actionable list for terminal (no TSV reading needed) ---
 	const lines: string[] = [];
 	lines.push(
-		`📋 FIX PLAN — Iteration ${session.iteration}/${MAX_ITERATIONS} — ${totalFixable} issues`,
+		`📋 FIX PLAN — Iteration ${session.iteration}/${MAX_ITERATIONS} — ${totalFixable} issues:\n`,
 	);
-	lines.push(`📄 Full plan: .pi-lens/reports/fix-plan.tsv\n`);
 
-	// Summary by category with counts
+	// Duplicates
 	if (filteredDups.length > 0) {
-		lines.push(
-			`🔁 Duplicates: ${filteredDups.length} block(s) — extract to shared utils`,
-		);
+		for (const clone of filteredDups.slice(0, 10)) {
+			lines.push(
+				`🔁 ${clone.fileA}:${clone.startA} — ${clone.lines} dup from ${clone.fileB}:${clone.startB}`,
+			);
+		}
+		if (filteredDups.length > 10)
+			lines.push(`   ... +${filteredDups.length - 10} more`);
+		lines.push("");
 	}
+
+	// Dead code
 	if (filteredDeadCode.length > 0) {
-		lines.push(
-			`🗑️ Dead code: ${filteredDeadCode.length} item(s) — remove unused exports`,
-		);
+		for (const issue of filteredDeadCode.slice(0, 10)) {
+			lines.push(`🗑️ ${issue.file || issue.name} — ${issue.name} unused`);
+		}
+		if (filteredDeadCode.length > 10)
+			lines.push(`   ... +${filteredDeadCode.length - 10} more`);
+		lines.push("");
 	}
+
+	// AST lint
 	if (agentTasks.length > 0) {
-		// Group by rule, show top 5 rules
-		const grouped = new Map<string, number>();
-		for (const t of agentTasks) {
-			grouped.set(t.rule, (grouped.get(t.rule) ?? 0) + 1);
-		}
-		const sorted = [...grouped.entries()].sort((a, b) => b[1] - a[1]);
-		lines.push(`🔨 Lint: ${agentTasks.length} item(s)`);
-		for (const [rule, count] of sorted.slice(0, 5)) {
-			lines.push(`   ${rule}: ${count}`);
+		for (const issue of agentTasks.slice(0, 15)) {
+			lines.push(`🔨 ${issue.file}:${issue.line} — ${issue.rule}`);
 		}
-		if (sorted.length > 5)
-			lines.push(`   ... and ${sorted.length - 5} more rules`);
+		if (agentTasks.length > 15)
+			lines.push(`   ... +${agentTasks.length - 15} more`);
+		lines.push("");
 	}
+
+	// Biome
 	if (filteredBiome.length > 0) {
-		lines.push(`🟠 Biome: ${filteredBiome.length} item(s) — auto-fixable`);
+		for (const issue of filteredBiome.slice(0, 10)) {
+			lines.push(`🟠 ${issue.file}:${issue.line} — ${issue.rule}`);
+		}
+		if (filteredBiome.length > 10)
+			lines.push(`   ... +${filteredBiome.length - 10} more`);
+		lines.push("");
 	}
+
+	// AI Slop
 	if (filteredSlop.length > 0) {
-		lines.push(
-			`🤖 AI Slop: ${filteredSlop.length} file(s) — review complexity`,
-		);
+		for (const { file, warnings } of filteredSlop.slice(0, 5)) {
+			lines.push(`🤖 ${file} — ${warnings[0]}`);
+		}
+		if (filteredSlop.length > 5)
+			lines.push(`   ... +${filteredSlop.length - 5} more`);
+		lines.push("");
 	}
 
-	lines.push("\n---");
-	lines.push(
-		"📖 **Read plan**: `read .pi-lens/reports/fix-plan.tsv` for full details",
-	);
-	lines.push(
-		"🚀 **Fix & loop**: Fix items, then run `/lens-booboo-fix --loop`",
-	);
+	lines.push("---");
+	lines.push("🚀 Fix items above, then run `/lens-booboo-fix --loop`");
 	lines.push(
-		'🚫 **False positive**: `/lens-booboo-fix --false-positive "type:file:line"`',
+		'🚫 False positive: `/lens-booboo-fix --false-positive "type:file:line"`',
 	);
 
 	return lines.join("\n");

package/commands/refactor.js

@@ -83,16 +83,18 @@ export async function handleRefactor(args, ctx, clients, pi, skipRules, ruleActi
         : "";
     // First violation line for quick reference
     const firstViolationLine = issues.length > 0 ? issues[0].line : null;
-    // --- Compact terminal summary ---
+    // --- Full ranked list in terminal (agent won't read TSV) ---
     const topFiles = scored
-        .slice(0, 5)
+        .slice(0, 15)
         .map((f, i) => {
         const name = path.relative(targetPath, f.file).replace(/\\/g, "/");
-        return `  ${i + 1}. ${name} (score: ${f.score})`;
+        const m = metricsByFile.get(f.file);
+        const mi = m ? `MI:${m.mi.toFixed(0)}` : "";
+        return `  ${i + 1}. ${name} (${f.score} pts${mi ? `, ${mi}` : ""})`;
     })
         .join("\n");
     ctx.ui.notify(`🏗️ Worst: ${relFile} (score: ${score}) — ${scored.length} files with debt`, "info");
-    console.log(`\n📊 Top ${Math.min(scored.length, 5)} worst offenders:\n${topFiles}\n📄 Full ranked list: .pi-lens/reports/refactor-ranked.tsv\n`);
+    console.log(`\n📊 Ranked by debt score:\n${topFiles}${scored.length > 15 ? `\n  ... and ${scored.length - 15} more` : ""}\n`);
     // --- Steer message for agent ---
     const steer = [
         `🏗️ BOOBOO REFACTOR — worst offender identified`,
@@ -107,7 +109,7 @@ export async function handleRefactor(args, ctx, clients, pi, skipRules, ruleActi
             : "",
         firstViolationLine ? `First violation at line ${firstViolationLine}` : "",
         "",
-        `📄 Full details: .pi-lens/reports/refactor-ranked.tsv — read \`${relFile}\` when ready`,
+        `📄 Read \`${relFile}\` when ready to implement`,
         "",
         "**Your job**:",
         "1. Analyze this code — what's the most impactful refactoring for this file?",

package/commands/refactor.ts

@@ -148,12 +148,14 @@ export async function handleRefactor(
 	// First violation line for quick reference
 	const firstViolationLine = issues.length > 0 ? issues[0].line : null;
 
-	// --- Compact terminal summary ---
+	// --- Full ranked list in terminal (agent won't read TSV) ---
 	const topFiles = scored
-		.slice(0, 5)
+		.slice(0, 15)
 		.map((f, i) => {
 			const name = path.relative(targetPath, f.file).replace(/\\/g, "/");
-			return `  ${i + 1}. ${name} (score: ${f.score})`;
+			const m = metricsByFile.get(f.file);
+			const mi = m ? `MI:${m.mi.toFixed(0)}` : "";
+			return `  ${i + 1}. ${name} (${f.score} pts${mi ? `, ${mi}` : ""})`;
 		})
 		.join("\n");
 
@@ -162,7 +164,7 @@ export async function handleRefactor(
 		"info",
 	);
 	console.log(
-		`\n📊 Top ${Math.min(scored.length, 5)} worst offenders:\n${topFiles}\n📄 Full ranked list: .pi-lens/reports/refactor-ranked.tsv\n`,
+		`\n📊 Ranked by debt score:\n${topFiles}${scored.length > 15 ? `\n  ... and ${scored.length - 15} more` : ""}\n`,
 	);
 
 	// --- Steer message for agent ---
@@ -179,7 +181,7 @@ export async function handleRefactor(
 			: "",
 		firstViolationLine ? `First violation at line ${firstViolationLine}` : "",
 		"",
-		`📄 Full details: .pi-lens/reports/refactor-ranked.tsv — read \`${relFile}\` when ready`,
+		`📄 Read \`${relFile}\` when ready to implement`,
 		"",
 		"**Your job**:",
 		"1. Analyze this code — what's the most impactful refactoring for this file?",

package/index.ts

@@ -634,6 +634,40 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	pi.registerCommand("lens-tdi", {
+		description:
+			"Show Technical Debt Index (TDI) and project health trend. Usage: /lens-tdi",
+		handler: async (_args, ctx) => {
+			const { loadHistory, computeTDI } = await import(
+				"./clients/metrics-history.js"
+			);
+			const history = loadHistory();
+			const tdi = computeTDI(history);
+
+			const lines = [
+				`📊 TECHNICAL DEBT INDEX: ${tdi.score}/100 (${tdi.grade})`,
+				``,
+				`Files analyzed: ${tdi.filesAnalyzed}`,
+				`Files with debt: ${tdi.filesWithDebt}`,
+				`Avg MI: ${tdi.avgMI}`,
+				`Total cognitive complexity: ${tdi.totalCognitive}`,
+				``,
+				`Debt breakdown:`,
+				`  Maintainability: ${tdi.byCategory.maintainability}%`,
+				`  Complexity: ${tdi.byCategory.complexity}%`,
+				`  Nesting: ${tdi.byCategory.nesting}%`,
+				``,
+				tdi.score <= 30
+					? "✅ Codebase is healthy!"
+					: tdi.score <= 60
+						? "⚠️ Moderate debt — consider refactoring"
+						: "🔴 High debt — run /lens-booboo-refactor",
+			];
+
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+
 	pi.registerCommand("lens-format", {
 		description:
 			"Apply Biome formatting to files. Usage: /lens-format [file-path] or /lens-format --all",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-lens",
-	"version": "2.2.6",
+	"version": "2.2.8",
 	"type": "module",
 	"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": {