pi-lens 3.3.0 → 3.6.0

package/clients/metrics-client.ts

@@ -5,8 +5,6 @@
  * Metrics are aggregated and shown in session summary only.
  *
  * Tracks:
- * - TDR (Technical Debt Ratio): composite score from existing signals
- * - AI Code Ratio: % of file written by agent this session vs pre-existing
  * - Code Entropy: Shannon entropy delta per file
  *
  * These are observational metrics — they inform the human in session summary,
@@ -21,30 +19,14 @@ import * as path from "node:path";
 export interface FileMetrics {
 	filePath: string;
 	totalLines: number;
-	agentLines: number; // lines written by agent this session
-	preExistingLines: number; // lines that existed before session
 	entropyStart: number; // Shannon entropy at first touch
 	entropyCurrent: number; // Current Shannon entropy
 	entropyDelta: number; // Change in entropy
-	tdrStart: number; // New field
-	tdrCurrent: number; // New field
-	tdrContributors: TDREntry[];
-}
-
-export interface TDREntry {
-	category: string;
-	count: number;
-	severity: "error" | "warning" | "info";
 }
 
 export interface SessionMetrics {
 	filesModified: number;
-	totalAgentLines: number;
-	totalPreExistingLines: number;
-	aiCodeRatio: number; // 0-1, agent lines / total lines
 	avgEntropyDelta: number; // average across files
-	tdrScore: number; // 0-100, lower is better
-	tdrByCategory: Map<string, number>;
 	fileDetails: Map<string, FileMetrics>;
 }
 
@@ -52,12 +34,8 @@ export interface SessionMetrics {
 
 export class MetricsClient {
 	private log: (msg: string) => void;
-	private fileBaselines: Map<
-		string,
-		{ content: string; entropy: number; tdr: number }
-	> = new Map();
-	private fileSessionWrites: Map<string, number> = new Map(); // agent-written lines
-	private tdrFindings: Map<string, TDREntry[]> = new Map();
+	private fileBaselines: Map<string, { content: string; entropy: number }> =
+		new Map();
 
 	constructor(verbose = false) {
 		this.log = verbose
@@ -68,65 +46,17 @@ export class MetricsClient {
 	/**
 	 * Record initial state of a file when first touched this session
 	 */
-	recordBaseline(filePath: string, initialTdr = 0): void {
+	recordBaseline(filePath: string): void {
 		const absolutePath = path.resolve(filePath);
 		if (!fs.existsSync(absolutePath)) return;
 		if (this.fileBaselines.has(absolutePath)) return; // Already recorded
 
 		const content = fs.readFileSync(absolutePath, "utf-8");
 		const entropy = this.calculateEntropy(content);
-		this.fileBaselines.set(absolutePath, { content, entropy, tdr: initialTdr });
-		this.fileSessionWrites.set(absolutePath, 0);
-
-		this.log(
-			`Baseline recorded: ${path.basename(filePath)} (entropy: ${entropy.toFixed(2)}, tdr: ${initialTdr})`,
-		);
-	}
-
-	/**
-	 * Update TDR findings for a file
-	 */
-	updateTDR(filePath: string, entries: TDREntry[]): void {
-		const absolutePath = path.resolve(filePath);
-		this.tdrFindings.set(absolutePath, entries);
-	}
-
-	/**
-	 * Get overall TDR score for the session
-	 * 0-100, where 100 is high debt.
-	 */
-	getTDRScore(): number {
-		let totalScore = 0;
-		for (const entries of this.tdrFindings.values()) {
-			for (const entry of entries) {
-				// Each entry adds to the debt index based on its Grade (count as the Grade value)
-				totalScore += entry.count;
-			}
-		}
-		// Normalize to 0-100? Or just return the raw Index.
-		// SCA.md says "Technical Debt Index"
-		return totalScore;
-	}
-
-	/**
-	 * Record that the agent wrote/replaced content in a file
-	 * @param newContent The new content after the write
-	 */
-	recordWrite(filePath: string, newContent: string): void {
-		const absolutePath = path.resolve(filePath);
-		this.recordBaseline(absolutePath);
-
-		const baseline = this.fileBaselines.get(absolutePath)!;
-		const _baselineLines = baseline.content.split("\n").length;
-		const _newLines = newContent.split("\n").length;
-
-		// Estimate agent-written lines: count the diff
-		const diffLines = this.estimateDiffLines(baseline.content, newContent);
-		const currentAgentLines = this.fileSessionWrites.get(absolutePath) || 0;
-		this.fileSessionWrites.set(absolutePath, currentAgentLines + diffLines);
+		this.fileBaselines.set(absolutePath, { content, entropy });
 
 		this.log(
-			`Write recorded: ${path.basename(filePath)} (+~${diffLines} agent lines)`,
+			`Baseline recorded: ${path.basename(filePath)} (entropy: ${entropy.toFixed(2)})`,
 		);
 	}
 
@@ -142,66 +72,16 @@ export class MetricsClient {
 
 		const currentContent = fs.readFileSync(absolutePath, "utf-8");
 		const totalLines = currentContent.split("\n").length;
-		const agentLines = this.fileSessionWrites.get(absolutePath) || 0;
 
 		const entropyCurrent = this.calculateEntropy(currentContent);
 		const entropyDelta = entropyCurrent - baseline.entropy;
 
-		const currentTdrFindings = this.tdrFindings.get(absolutePath) || [];
-		const tdrCurrent = currentTdrFindings.reduce((a, b) => a + b.count, 0);
-
 		return {
 			filePath: path.relative(process.cwd(), absolutePath),
 			totalLines,
-			agentLines: Math.min(agentLines, totalLines),
-			preExistingLines: Math.max(0, totalLines - agentLines),
 			entropyStart: baseline.entropy,
 			entropyCurrent,
 			entropyDelta,
-			tdrStart: baseline.tdr,
-			tdrCurrent,
-			tdrContributors: currentTdrFindings,
-		};
-	}
-
-	/**
-	 * Calculate AI Code Ratio for the session
-	 * Returns 0-1 where 1 = all code written by agent
-	 */
-	getAICodeRatio(): {
-		ratio: number;
-		agentLines: number;
-		preExistingLines: number;
-		fileCount: number;
-	} {
-		let totalAgentLines = 0;
-		let totalPreExistingLines = 0;
-		let fileCount = 0;
-
-		for (const [filePath, agentLines] of this.fileSessionWrites) {
-			if (!fs.existsSync(filePath)) continue;
-
-			const content = fs.readFileSync(filePath, "utf-8");
-			const totalLines = content.split("\n").length;
-			const baseline = this.fileBaselines.get(filePath);
-			const _baselineLines = baseline
-				? baseline.content.split("\n").length
-				: totalLines;
-
-			// Pre-existing = lines that existed before this session and weren't replaced
-			const preExisting = Math.max(0, totalLines - agentLines);
-
-			totalAgentLines += agentLines;
-			totalPreExistingLines += preExisting;
-			fileCount++;
-		}
-
-		const total = totalAgentLines + totalPreExistingLines;
-		return {
-			ratio: total > 0 ? totalAgentLines / total : 0, // fixed
-			agentLines: totalAgentLines,
-			preExistingLines: totalPreExistingLines,
-			fileCount,
 		};
 	}
 
@@ -223,7 +103,6 @@ export class MetricsClient {
 
 		for (const [filePath, baseline] of this.fileBaselines) {
 			if (!fs.existsSync(filePath)) continue;
-			if (!this.fileSessionWrites.has(filePath)) continue;
 
 			const content = fs.readFileSync(filePath, "utf-8");
 			const current = this.calculateEntropy(content);
@@ -264,104 +143,11 @@ export class MetricsClient {
 		return entropy;
 	}
 
-	/**
-	 * Format metrics for session summary
-	 */
-	formatSessionSummary(): string {
-		const aiRatio = this.getAICodeRatio();
-		const entropyDeltas = this.getEntropyDeltas();
-		const fileCount = this.fileSessionWrites.size;
-
-		if (fileCount === 0) return ""; // No files touched
-
-		const parts: string[] = [];
-
-		// Aggregate TDR from details
-		let totalTdrCurrent = 0;
-		let totalTdrStart = 0;
-		for (const path of this.fileSessionWrites.keys()) {
-			const m = this.getFileMetrics(path);
-			if (m) {
-				totalTdrCurrent += m.tdrCurrent;
-				totalTdrStart += m.tdrStart;
-			}
-		}
-
-		// Technical Debt Index
-		if (totalTdrCurrent > 0 || totalTdrStart > 0) {
-			const delta = totalTdrCurrent - totalTdrStart;
-			const deltaStr =
-				delta !== 0
-					? ` (${delta > 0 ? "+" : ""}${delta.toFixed(1)} this session)`
-					: "";
-			parts.push(
-				`[TDR Index] Total Debt: ${totalTdrCurrent.toFixed(1)}${deltaStr}`,
-			);
-		}
-
-		// AI Code Ratio
-		const pct = (aiRatio.ratio * 100).toFixed(1);
-		parts.push(
-			`[AI Code] ${pct}% of ${fileCount} file(s) written by agent this session (${aiRatio.agentLines} lines, ${aiRatio.preExistingLines} pre-existing)`,
-		);
-
-		// Entropy deltas (only show files with significant changes)
-		const significant = entropyDeltas.filter((e) => Math.abs(e.delta) > 0.1);
-		if (significant.length > 0) {
-			const topChanges = significant.slice(0, 5);
-			parts.push(
-				`[Entropy] ${significant.length} file(s) with complexity changes:`,
-			);
-			for (const e of topChanges) {
-				const arrow = e.delta > 0 ? "↑" : "↓";
-				const sign = e.delta > 0 ? "+" : "";
-				parts.push(
-					`  ${arrow} ${e.file}: ${e.start.toFixed(2)} → ${e.current.toFixed(2)} (${sign}${e.delta.toFixed(2)} bits)`,
-				);
-			}
-			if (significant.length > 5) {
-				parts.push(`  ... and ${significant.length - 5} more`);
-			}
-		}
-
-		return parts.join("\n");
-	}
-
 	/**
 	 * Reset session state (for new session)
 	 */
 	reset(): void {
 		this.fileBaselines.clear();
-		this.fileSessionWrites.clear();
 		this.log("Session metrics reset");
 	}
-
-	// --- Internal ---
-
-	/**
-	 * Estimate number of lines that changed between two texts
-	 * Simple line-based diff (not Myers, but good enough for metrics)
-	 */
-	private estimateDiffLines(oldText: string, newText: string): number {
-		const oldLines = new Set(oldText.split("\n"));
-		const newLines = newText.split("\n");
-
-		let changed = 0;
-		for (const line of newLines) {
-			if (!oldLines.has(line)) {
-				changed++;
-			}
-		}
-
-		// Also count deleted lines
-		const newLinesSet = new Set(newLines);
-		for (const line of oldLines) {
-			if (!newLinesSet.has(line)) {
-				changed++;
-			}
-		}
-
-		// Return roughly half (additions + deletions / 2)
-		return Math.max(1, Math.ceil(changed / 2));
-	}
 }

package/clients/metrics-history.js

@@ -86,6 +86,8 @@ export function captureSnapshot(filePath, metrics) {
         cognitive: metrics.cognitiveComplexity,
         nesting: metrics.maxNestingDepth,
         lines: metrics.linesOfCode,
+        maxCyclomatic: metrics.maxCyclomatic,
+        entropy: Math.round(metrics.entropy * 100) / 100,
     };
     const existing = pendingHistory.files[relativePath];
     if (existing) {
@@ -136,6 +138,8 @@ export function captureSnapshots(files) {
             cognitive: file.metrics.cognitiveComplexity,
             nesting: file.metrics.maxNestingDepth,
             lines: file.metrics.linesOfCode,
+            maxCyclomatic: file.metrics.maxCyclomatic,
+            entropy: Math.round(file.metrics.entropy * 100) / 100,
         };
         const existing = history.files[relativePath];
         if (existing) {
@@ -275,7 +279,13 @@ export function computeTDI(history) {
             totalCognitive: 0,
             filesAnalyzed: 0,
             filesWithDebt: 0,
-            byCategory: { complexity: 0, maintainability: 0, nesting: 0 },
+            byCategory: {
+                maintainability: 0,
+                cognitive: 0,
+                nesting: 0,
+                maxCyclomatic: 0,
+                entropy: 0,
+            },
         };
     }
     let totalMI = 0;
@@ -285,6 +295,8 @@ export function computeTDI(history) {
     let debtFromMI = 0;
     let debtFromCognitive = 0;
     let debtFromNesting = 0;
+    let debtFromMaxCyclomatic = 0; // NEW
+    let debtFromEntropy = 0; // NEW
     for (const file of files) {
         const snap = file.latest;
         totalMI += snap.mi;
@@ -301,17 +313,29 @@ export function computeTDI(history) {
         // 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
+        // Max Cyclomatic debt: 0 at max<=10, 1 at max>=30
+        const maxCycDebt = Math.min(1, Math.max(0, snap.maxCyclomatic - 10) / 20);
+        debtFromMaxCyclomatic += maxCycDebt;
+        // Entropy debt: 0 at entropy<=4.0, 1 at entropy>=7.0
+        const entropyDebt = Math.min(1, Math.max(0, snap.entropy - 4.0) / 3.0);
+        debtFromEntropy += entropyDebt;
+        fileDebt = miDebt + cogDebt + nestDebt + maxCycDebt + entropyDebt;
+        if (fileDebt > 0.5)
+            filesWithDebt++; // Lowered threshold since we have more factors
     }
     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 avgMaxCycDebt = debtFromMaxCyclomatic / files.length; // NEW
+    const avgEntropyDebt = debtFromEntropy / files.length; // NEW
+    // Weighted: MI (45%), cognitive (30%), nesting (10%), maxCyc (10%), entropy (5%)
+    const rawScore = avgMIDebt * 45 +
+        avgCogDebt * 30 +
+        avgNestDebt * 10 +
+        avgMaxCycDebt * 10 +
+        avgEntropyDebt * 5;
     const score = Math.round(rawScore * 100) / 100;
     // Grade
     let grade;
@@ -333,9 +357,11 @@ export function computeTDI(history) {
         filesAnalyzed: files.length,
         filesWithDebt,
         byCategory: {
-            complexity: Math.round(avgCogDebt * 100),
             maintainability: Math.round(avgMIDebt * 100),
+            cognitive: Math.round(avgCogDebt * 100),
             nesting: Math.round(avgNestDebt * 100),
+            maxCyclomatic: Math.round(avgMaxCycDebt * 100),
+            entropy: Math.round(avgEntropyDebt * 100),
         },
     };
 }

package/clients/metrics-history.ts

@@ -19,6 +19,8 @@ export interface MetricSnapshot {
 	cognitive: number;
 	nesting: number;
 	lines: number;
+	maxCyclomatic: number; // NEW: worst function complexity
+	entropy: number; // NEW: code unpredictability in bits
 }
 
 export interface FileHistory {
@@ -115,6 +117,8 @@ export function captureSnapshot(
 		cognitiveComplexity: number;
 		maxNestingDepth: number;
 		linesOfCode: number;
+		maxCyclomatic: number;
+		entropy: number;
 	},
 ): void {
 	// Use in-memory cache if available, otherwise load from disk
@@ -132,6 +136,8 @@ export function captureSnapshot(
 		cognitive: metrics.cognitiveComplexity,
 		nesting: metrics.maxNestingDepth,
 		lines: metrics.linesOfCode,
+		maxCyclomatic: metrics.maxCyclomatic,
+		entropy: Math.round(metrics.entropy * 100) / 100,
 	};
 
 	const existing = pendingHistory.files[relativePath];
@@ -180,6 +186,8 @@ export function captureSnapshots(
 			cognitiveComplexity: number;
 			maxNestingDepth: number;
 			linesOfCode: number;
+			maxCyclomatic: number;
+			entropy: number;
 		};
 	}>,
 ): MetricsHistory {
@@ -196,6 +204,8 @@ export function captureSnapshots(
 			cognitive: file.metrics.cognitiveComplexity,
 			nesting: file.metrics.maxNestingDepth,
 			lines: file.metrics.linesOfCode,
+			maxCyclomatic: file.metrics.maxCyclomatic,
+			entropy: Math.round(file.metrics.entropy * 100) / 100,
 		};
 
 		const existing = history.files[relativePath];
@@ -359,9 +369,11 @@ export interface ProjectTDI {
 	filesAnalyzed: number;
 	filesWithDebt: number;
 	byCategory: {
-		complexity: number;
-		maintainability: number;
-		nesting: number;
+		maintainability: number; // 45% - MI-based
+		cognitive: number; // 30%
+		nesting: number; // 10%
+		maxCyclomatic: number; // 10% - NEW
+		entropy: number; // 5% - NEW
 	};
 }
 
@@ -379,7 +391,13 @@ export function computeTDI(history: MetricsHistory): ProjectTDI {
 			totalCognitive: 0,
 			filesAnalyzed: 0,
 			filesWithDebt: 0,
-			byCategory: { complexity: 0, maintainability: 0, nesting: 0 },
+			byCategory: {
+				maintainability: 0,
+				cognitive: 0,
+				nesting: 0,
+				maxCyclomatic: 0,
+				entropy: 0,
+			},
 		};
 	}
 
@@ -390,6 +408,8 @@ export function computeTDI(history: MetricsHistory): ProjectTDI {
 	let debtFromMI = 0;
 	let debtFromCognitive = 0;
 	let debtFromNesting = 0;
+	let debtFromMaxCyclomatic = 0; // NEW
+	let debtFromEntropy = 0; // NEW
 
 	for (const file of files) {
 		const snap = file.latest;
@@ -412,8 +432,16 @@ export function computeTDI(history: MetricsHistory): ProjectTDI {
 		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
+		// Max Cyclomatic debt: 0 at max<=10, 1 at max>=30
+		const maxCycDebt = Math.min(1, Math.max(0, snap.maxCyclomatic - 10) / 20);
+		debtFromMaxCyclomatic += maxCycDebt;
+
+		// Entropy debt: 0 at entropy<=4.0, 1 at entropy>=7.0
+		const entropyDebt = Math.min(1, Math.max(0, snap.entropy - 4.0) / 3.0);
+		debtFromEntropy += entropyDebt;
+
+		fileDebt = miDebt + cogDebt + nestDebt + maxCycDebt + entropyDebt;
+		if (fileDebt > 0.5) filesWithDebt++; // Lowered threshold since we have more factors
 	}
 
 	const avgMI = totalMI / files.length;
@@ -422,9 +450,16 @@ export function computeTDI(history: MetricsHistory): ProjectTDI {
 	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 avgMaxCycDebt = debtFromMaxCyclomatic / files.length; // NEW
+	const avgEntropyDebt = debtFromEntropy / files.length; // NEW
+
+	// Weighted: MI (45%), cognitive (30%), nesting (10%), maxCyc (10%), entropy (5%)
+	const rawScore =
+		avgMIDebt * 45 +
+		avgCogDebt * 30 +
+		avgNestDebt * 10 +
+		avgMaxCycDebt * 10 +
+		avgEntropyDebt * 5;
 	const score = Math.round(rawScore * 100) / 100;
 
 	// Grade
@@ -443,9 +478,11 @@ export function computeTDI(history: MetricsHistory): ProjectTDI {
 		filesAnalyzed: files.length,
 		filesWithDebt,
 		byCategory: {
-			complexity: Math.round(avgCogDebt * 100),
 			maintainability: Math.round(avgMIDebt * 100),
+			cognitive: Math.round(avgCogDebt * 100),
 			nesting: Math.round(avgNestDebt * 100),
+			maxCyclomatic: Math.round(avgMaxCycDebt * 100),
+			entropy: Math.round(avgEntropyDebt * 100),
 		},
 	};
 }