@herbertgao/pi-extensions 2026.10.1 → 2026.10.3

package/node_modules/pi-lens/dist/clients/memory-sampler.js

@@ -1,208 +0,0 @@
-/**
- * Periodic memory-attribution sample (#1123 item 2, expanded on top of item 1's
- * loop_block windowing — the #1126 sizing study's "instrumentation the next
- * report should add" list is this module's requirements).
- *
- * The #1126 sizing study diagnosed a 1.37 GB instance from code + serialized
- * artifacts alone, because nothing recorded a per-subsystem trajectory over
- * time — the same detection-without-attribution gap loop_block had before
- * #1122/#1125. This module answers "what is resident right now, broken down
- * by subsystem" as a single ndjson `memory_sample` `latency.log` line, emitted
- * every `MEMORY_SAMPLE_TURN_INTERVAL` turns (cheap enough not to need finer
- * throttling).
- *
- * HARD CONSTRAINT: every field here is an O(1) `Map`/array `.size`/`.length`
- * read, or a `process.memoryUsage()` call — nothing here iterates a large
- * structure's contents, and nothing takes a heap snapshot. `PI_LENS_DEBUG_HEAP`
- * (item 4's memory sibling) is a SEPARATE, explicitly opt-in mechanism, out of
- * scope here.
- *
- * WASM linear-memory byte length gap (documented, not silently dropped): the
- * #1126 spec asked for `Module.wasmMemory.buffer.byteLength` off the
- * web-tree-sitter parser runtime. Inspecting the installed web-tree-sitter
- * 0.25.10 package (see `clients/tree-sitter-client.ts#getRuntimeStats`'s
- * docstring) confirmed that value is not reachable through any public export
- * — only through package-internal reflection or by overriding Emscripten's
- * `wasmMemory` module option with a hand-built `WebAssembly.Memory` (a
- * stability risk for an observability-only feature, given a memory-import
- * mismatch would break structural analysis entirely). `process.memoryUsage()`
- * `arrayBuffers` is used as the process-wide proxy instead — WASM linear
- * memory backs an ArrayBuffer, so it is already included there.
- */
-import { countPostingEntries, estimateWordIndexStoreBytes, } from "./word-index-store.js";
-import { getSharedTreeSitterClient } from "./tree-sitter-shared.js";
-import { getReviewGraphWorkspaceCacheSnapshot } from "./review-graph/builder.js";
-import { getDispatchCascadeCacheStats } from "./dispatch/integration.js";
-import { getLspDocumentTextRetentionSnapshot } from "./lsp/client.js";
-/** Every N turns, emit one `memory_sample` latency.log line (#1123 item 2). */
-export const MEMORY_SAMPLE_TURN_INTERVAL = 10;
-/** True on turn 10, 20, 30, ... — never on turn 0 (nothing meaningful is
- *  resident yet at session start). Pure so the cadence is unit-testable
- *  without driving a real turn loop. */
-export function shouldEmitMemorySample(turnIndex) {
-    return turnIndex > 0 && turnIndex % MEMORY_SAMPLE_TURN_INTERVAL === 0;
-}
-/**
- * Rising-edge cadence (#1999): when heapUsed grows more than
- * {@link HEAP_GROWTH_TIGHTEN_RATIO} between two sampled turns, sampling
- * tightens from every {@link MEMORY_SAMPLE_TURN_INTERVAL} turns to every turn
- * until growth stabilizes. The state below is module-scoped SESSION state —
- * reset it at every primary `session_start` via
- * {@link resetMemorySamplerCadence} (defect shape 17: a process-lifetime latch
- * holding a session-scoped signal).
- */
-export const HEAP_GROWTH_TIGHTEN_RATIO = 1.2;
-let _lastSampledHeapUsedBytes = 0;
-let _tightenThroughTurn = 0;
-/** Clear the rising-edge cadence state. Called on primary session_start. */
-export function resetMemorySamplerCadence() {
-    _lastSampledHeapUsedBytes = 0;
-    _tightenThroughTurn = 0;
-}
-/** PURE: >20% heap growth between two sampled readings warrants tightening. */
-export function isRapidHeapGrowth(previousHeapUsedBytes, currentHeapUsedBytes) {
-    return (previousHeapUsedBytes > 0 &&
-        currentHeapUsedBytes > previousHeapUsedBytes * HEAP_GROWTH_TIGHTEN_RATIO);
-}
-/** Record the heap reading of a sample just emitted at `turnIndex`. A rapid
- *  growth edge extends the tightened window through the NEXT turn; each
- *  subsequent still-growing sample (including one taken inside an already
- *  tightened window) extends it again, so the window naturally expires once
- *  growth stabilizes. Monotonic max so an out-of-order turn can never shrink
- *  the window. O(1). */
-export function recordMemorySampleOutcome(heapUsedBytes, turnIndex) {
-    if (isRapidHeapGrowth(_lastSampledHeapUsedBytes, heapUsedBytes)) {
-        _tightenThroughTurn = Math.max(_tightenThroughTurn, turnIndex + 1);
-    }
-    _lastSampledHeapUsedBytes = heapUsedBytes;
-}
-/** Adaptive gate used by turn_end: base every-10 cadence OR an open tightened
- *  window. Pure w.r.t. its argument; the window itself is session state owned
- *  by {@link recordMemorySampleOutcome}. */
-export function shouldEmitMemorySampleAdaptive(turnIndex) {
-    if (turnIndex <= 0)
-        return false;
-    return (turnIndex % MEMORY_SAMPLE_TURN_INTERVAL === 0 ||
-        turnIndex <= _tightenThroughTurn);
-}
-/** PURE: reshape Node's `process.memoryUsage()` (+ optional
- *  `process.resourceUsage()`) into this module's field names — testable
- *  without touching the real process. */
-export function toMemoryProcessUsage(mem, resourceUsage) {
-    const maxKb = resourceUsage?.maxRSS;
-    return {
-        rssBytes: mem.rss,
-        heapUsedBytes: mem.heapUsed,
-        heapTotalBytes: mem.heapTotal,
-        externalBytes: mem.external,
-        arrayBuffersBytes: mem.arrayBuffers,
-        peakWorkingSetBytes: typeof maxKb === "number" && Number.isFinite(maxKb) && maxKb > 0
-            ? maxKb * 1024
-            : null,
-    };
-}
-/**
- * Live O(1)/O(bounded-cache-size) subsystem counters. Impure (reads
- * process-global singletons) but every individual read is a `.size`/`.length`
- * access — see the module docstring's hard constraint.
- */
-/** Byte attribution for `dispatchCaches`, from measured per-entry costs: three
- *  isolated-store runs put a recently-clean neighbor entry at 320 bytes, and
- *  #2282 measured a 500-file batch's 1,000 session-fact entries at 439,560
- *  bytes (~440 each). O(1) — the cache key and Map bookkeeping are included. */
-export function estimateDispatchCacheBytes(stats) {
-    return (stats.recentlyCleanNeighborCacheSize * 320 + stats.sessionFactEntries * 440);
-}
-export function collectMemorySampleSubsystems(wordIndex) {
-    const reviewGraph = getReviewGraphWorkspaceCacheSnapshot();
-    const treeSitterClient = getSharedTreeSitterClient();
-    const treeSitter = treeSitterClient
-        ? (() => {
-            const runtimeStats = treeSitterClient.getRuntimeStats();
-            const cacheStats = treeSitterClient.getParseCacheStats();
-            return {
-                ...runtimeStats,
-                treeCacheSize: cacheStats.size,
-                treeCacheMaxSize: cacheStats.maxSize,
-                treeCacheTotalBytes: cacheStats.totalBytes,
-            };
-        })()
-        : null;
-    const dispatchCaches = getDispatchCascadeCacheStats();
-    return {
-        lsp: (() => {
-            const retention = getLspDocumentTextRetentionSnapshot();
-            return {
-                clients: retention.clients,
-                clientRoots: retention.roots,
-                incrementalTextEntries: retention.entries,
-                incrementalTextBytes: retention.bytes,
-            };
-        })(),
-        reviewGraph,
-        wordIndex: wordIndex
-            ? {
-                docs: wordIndex.docLengths.size,
-                fileTable: wordIndex.fileTable.size,
-                postings: wordIndex.postings.size,
-                // O(distinct tokens), reading only `.length`/`.byteLength` per
-                // list — no posting ELEMENT is touched, so this stays inside the
-                // module docstring’s bounded-read constraint.
-                postingEntries: countPostingEntries(wordIndex),
-                residentBytes: estimateWordIndexStoreBytes(wordIndex),
-                forwardEntries: wordIndex.forward?.size ?? 0,
-            }
-            : null,
-        treeSitter,
-        dispatchCaches: {
-            ...dispatchCaches,
-            estimatedBytes: estimateDispatchCacheBytes(dispatchCaches),
-        },
-    };
-}
-/** Assemble one full sample. `mem` is injectable for tests; defaults to a
- *  live `process.memoryUsage()` read. `resourceUsage` (peak working set) and
- *  `session` are optional ridealongs (#1999); when `resourceUsage` is omitted
- *  a live `process.resourceUsage()` read supplies the peak. */
-export function buildMemorySample(wordIndex, mem = process.memoryUsage(), resourceUsage, session) {
-    let resolvedResourceUsage = resourceUsage;
-    if (!resolvedResourceUsage) {
-        try {
-            resolvedResourceUsage = process.resourceUsage();
-        }
-        catch {
-            resolvedResourceUsage = undefined;
-        }
-    }
-    return {
-        process: toMemoryProcessUsage(mem, resolvedResourceUsage),
-        subsystems: collectMemorySampleSubsystems(wordIndex),
-        session,
-    };
-}
-const toMb = (bytes) => Math.round(bytes / (1024 * 1024));
-/**
- * PURE: one compact `/lens-health` line reusing the same sample the periodic
- * latency.log emitter builds — RSS + heap/external, plus the two subsystem
- * numbers most useful for spotting an attribution outlier at a glance: the
- * tree-sitter tree-cache byte total (the only subsystem counter here that is
- * ALREADY in bytes, so it's directly comparable to RSS) and the review-graph
- * node/edge counts (the multiple-graph-copies question #1126 called out).
- * Follows #1125's health-line style (a single summary line, no per-subsystem
- * breakdown table — that's what latency.log's `memory_sample` is for).
- */
-export function formatMemoryHealthLine(sample) {
-    const { process: proc, subsystems } = sample;
-    const treeCache = subsystems.treeSitter
-        ? `${toMb(subsystems.treeSitter.treeCacheTotalBytes)}MB (${subsystems.treeSitter.treeCacheSize} trees)`
-        : "n/a";
-    const graph = `${subsystems.reviewGraph.totalNodes}n/${subsystems.reviewGraph.totalEdges}e (${subsystems.reviewGraph.cacheEntries} cwd)`;
-    // #1999: peak WS rides along when known — rss far below peak means the
-    // periodic samples are catching idle valleys, not the true high-water mark.
-    const peak = proc.peakWorkingSetBytes !== null
-        ? ` · peak WS ${toMb(proc.peakWorkingSetBytes)}MB`
-        : "";
-    return (`Memory: RSS ${toMb(proc.rssBytes)}MB · heap ${toMb(proc.heapUsedBytes)}/${toMb(proc.heapTotalBytes)}MB` +
-        ` · external ${toMb(proc.externalBytes)}MB${peak}` +
-        ` · tree-sitter cache ${treeCache} · review-graph ${graph}`);
-}

package/node_modules/pi-lens/dist/clients/message-end-attribution.js

@@ -1,30 +0,0 @@
-/** Session-local attribution captured before a stale message_end can drain. */
-let lastStableSessionId;
-let previousSessionId;
-/** Remember the stable id used by a live message_end's own cache row. */
-export function noteLiveMessageEndSessionId(sessionId) {
-    lastStableSessionId = sessionId;
-}
-/** Return the newest usable id for a stale message_end attribution. */
-export function getLastLiveMessageEndSessionId() {
-    return lastStableSessionId ?? previousSessionId;
-}
-/**
- * Rotate the attribution anchor at the real session boundary. A queued stale
- * message_end from the session being replaced may drain after this boundary,
- * so retain exactly one prior anchor while making room for the replacement.
- */
-export function rotateMessageEndAttribution() {
-    // Keep the prior anchor when no live message_end arrived this session:
-    // two back-to-back boundaries (reload/resume re-announcing) must not
-    // erase the only id a still-queued stale drain can use (#1956 R10).
-    if (lastStableSessionId !== undefined) {
-        previousSessionId = lastStableSessionId;
-    }
-    lastStableSessionId = undefined;
-}
-/** Full reset seam used by the session-state registry and test isolation. */
-export function resetMessageEndAttribution() {
-    lastStableSessionId = undefined;
-    previousSessionId = undefined;
-}

package/node_modules/pi-lens/dist/clients/metrics-client.js

@@ -1,107 +0,0 @@
-/**
- * Silent Metrics Client for pi-lens
- *
- * Tracks code quality metrics silently during the session.
- * Metrics are aggregated and shown in session summary only.
- *
- * Tracks:
- * - Code Entropy: Shannon entropy delta per file
- *
- * These are observational metrics — they inform the human in session summary,
- * they don't gate or interrupt the agent mid-task.
- */
-import { createSubsystemLogger } from "./extension-log.js";
-import * as fs from "node:fs";
-import * as path from "node:path";
-// --- Client ---
-export class MetricsClient {
-    log;
-    fileBaselines = new Map();
-    constructor(verbose = false) {
-        this.log = verbose ? createSubsystemLogger("metrics") : () => { };
-    }
-    /**
-     * Record initial state of a file when first touched this session
-     */
-    recordBaseline(filePath) {
-        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 });
-        this.log(`Baseline recorded: ${path.basename(filePath)} (entropy: ${entropy.toFixed(2)})`);
-    }
-    /**
-     * Get metrics for a specific file
-     */
-    getFileMetrics(filePath) {
-        const absolutePath = path.resolve(filePath);
-        const baseline = this.fileBaselines.get(absolutePath);
-        if (!baseline)
-            return null;
-        if (!fs.existsSync(absolutePath))
-            return null;
-        const currentContent = fs.readFileSync(absolutePath, "utf-8");
-        const totalLines = currentContent.split("\n").length;
-        const entropyCurrent = this.calculateEntropy(currentContent);
-        const entropyDelta = entropyCurrent - baseline.entropy;
-        return {
-            filePath: path.relative(process.cwd(), absolutePath),
-            totalLines,
-            entropyStart: baseline.entropy,
-            entropyCurrent,
-            entropyDelta,
-        };
-    }
-    /**
-     * Get entropy delta for all touched files
-     */
-    getEntropyDeltas() {
-        const results = [];
-        for (const [filePath, baseline] of this.fileBaselines) {
-            if (!fs.existsSync(filePath))
-                continue;
-            const content = fs.readFileSync(filePath, "utf-8");
-            const current = this.calculateEntropy(content);
-            const delta = current - baseline.entropy;
-            results.push({
-                file: path.relative(process.cwd(), filePath),
-                start: baseline.entropy,
-                current,
-                delta,
-            });
-        }
-        return results.sort((a, b) => Math.abs(b.delta) - Math.abs(a.delta));
-    }
-    /**
-     * Calculate Shannon entropy of a string
-     * Returns bits per character
-     */
-    calculateEntropy(text) {
-        if (text.length === 0)
-            return 0;
-        const freq = new Map();
-        for (const char of text) {
-            freq.set(char, (freq.get(char) || 0) + 1);
-        }
-        let entropy = 0;
-        const len = text.length;
-        for (const count of freq.values()) {
-            const p = count / len;
-            if (p > 0) {
-                entropy -= p * Math.log2(p);
-            }
-        }
-        return entropy;
-    }
-    /**
-     * Reset session state (for new session)
-     */
-    reset() {
-        this.fileBaselines.clear();
-        this.log("Session metrics reset");
-    }
-}

package/node_modules/pi-lens/dist/clients/metrics-history.js

@@ -1,327 +0,0 @@
-/**
- * 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: <project-data>/metrics-history.json
- */
-import { execSync } from "node:child_process";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { getProjectDataDir } from "./file-utils.js";
-import { writeFileAtomic } from "./atomic-write.js";
-// --- Constants ---
-const HISTORY_FILE = "metrics-history.json";
-const MAX_HISTORY_PER_FILE = 20;
-// --- Git Helpers ---
-/**
- * Check whether cwd is inside a Git worktree.
- */
-function isInsideGitRepo(startDir) {
-    let dir = path.resolve(startDir);
-    while (true) {
-        if (fs.existsSync(path.join(dir, ".git"))) {
-            return true;
-        }
-        const parent = path.dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return false;
-}
-/**
- * Get current git commit hash (short)
- */
-function getCurrentCommit(startDir) {
-    const repoStartDir = path.resolve(startDir);
-    if (!isInsideGitRepo(repoStartDir)) {
-        return "unknown";
-    }
-    let spawnDir = repoStartDir;
-    while (!fs.existsSync(spawnDir)) {
-        const parent = path.dirname(spawnDir);
-        if (parent === spawnDir)
-            return "unknown";
-        spawnDir = parent;
-    }
-    try {
-        // #2095: execSync inherits the child's stderr to THIS process by
-        // default (only stdout is captured for the return value), so a
-        // failing `git rev-parse` prints its raw "fatal: ..." line straight
-        // into the pi TUI — the catch below only ever sees the thrown
-        // non-zero-exit error, never the already-inherited stream. The
-        // explicit stdio array pipes stderr instead, so a failure is fully
-        // contained: silent here, same as the "unknown" fallback it feeds.
-        return execSync("git rev-parse --short HEAD", {
-            encoding: "utf-8",
-            timeout: 5000,
-            stdio: ["ignore", "pipe", "ignore"],
-            cwd: spawnDir,
-        }).trim();
-    }
-    catch {
-        return "unknown";
-    }
-}
-// --- History Management ---
-/**
- * Load history from disk (or return empty)
- */
-export function loadHistory() {
-    const historyPath = path.join(getProjectDataDir(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
- */
-function saveHistory(history) {
-    const historyDir = getProjectDataDir(process.cwd());
-    if (!fs.existsSync(historyDir)) {
-        fs.mkdirSync(historyDir, { recursive: true });
-    }
-    history.capturedAt = new Date().toISOString();
-    const historyPath = path.join(historyDir, "metrics-history.json");
-    writeFileAtomic(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(path.dirname(filePath));
-    const snapshot = {
-        commit,
-        timestamp: new Date().toISOString(),
-        mi: Math.round(metrics.maintainabilityIndex * 10) / 10,
-        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) {
-        // 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);
-    saveTimer.unref?.();
-}
-// --- Trend Analysis ---
-/**
- * Compute trend direction from history snapshots
- * Uses last 3 snapshots for stability (or 2 if only 2 available)
- */
-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";
-}
-// --- Technical Debt Index (TDI) ---
-// Test-reached through a child-process `require` string
-/** @public — reached through a child-process `require` string in tests/clients/metrics-history-stderr.test.ts; knip cannot see it. */
-export function captureSnapshots(files) {
-    const history = loadHistory();
-    for (const file of files) {
-        const relativePath = path.relative(process.cwd(), file.filePath);
-        const commit = getCurrentCommit(path.dirname(file.filePath));
-        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,
-            maxCyclomatic: file.metrics.maxCyclomatic,
-            entropy: Math.round(file.metrics.entropy * 100) / 100,
-        };
-        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;
-}
-/**
- * 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: {
-                maintainability: 0,
-                cognitive: 0,
-                nesting: 0,
-                maxCyclomatic: 0,
-                entropy: 0,
-            },
-        };
-    }
-    let totalMI = 0;
-    let totalCognitive = 0;
-    let _totalNesting = 0;
-    let filesWithDebt = 0;
-    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;
-        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;
-        // 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
-    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;
-    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: {
-            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),
-        },
-    };
-}