@herbertgao/pi-extensions 2026.8.3 → 2026.8.5

package/node_modules/pi-lens/dist/clients/lsp-mutation.js

@@ -0,0 +1,248 @@
+import * as path from "node:path";
+import { createReadGuardEditBatchSummary, getReadGuardCorrelationId, logReadGuardEvent, } from "./read-guard-logger.js";
+import { appendProjectChange, } from "./project-changes.js";
+import { normalizeMapKey } from "./path-utils.js";
+const MAX_SAMPLES = 100;
+const MAX_SUMMARIES_PER_CONTEXT = 100;
+export function newLspMutationCorrelationId(toolCallId) {
+    return getReadGuardCorrelationId(toolCallId ? { toolCallId } : {});
+}
+function allResults(options) {
+    return options.results ?? [];
+}
+function combineResults(results) {
+    const files = new Set();
+    const fileDetails = [];
+    const appliedIndexes = [];
+    const paths = [];
+    let requestedTotal = 0;
+    let appliedTotal = 0;
+    let textEdits = 0;
+    let create = 0;
+    let rename = 0;
+    let deleteCount = 0;
+    for (const result of results) {
+        requestedTotal += result.operationTotal;
+        appliedTotal += result.appliedOperationTotal;
+        textEdits += result.operationCounts.textEdits;
+        create += result.operationCounts.create;
+        rename += result.operationCounts.rename;
+        deleteCount += result.operationCounts.delete;
+        for (const index of result.appliedOperationIndexes)
+            appliedIndexes.push(index);
+        for (const file of result.files) {
+            if (!files.has(file)) {
+                files.add(file);
+                paths.push(file);
+            }
+        }
+        fileDetails.push(...result.fileDetails);
+    }
+    return {
+        requestedTotal,
+        appliedTotal,
+        appliedIndexes,
+        files: [...files],
+        fileDetails,
+        textEdits,
+        create,
+        rename,
+        delete: deleteCount,
+        paths,
+    };
+}
+function uniqueDetails(files, fileDetails) {
+    const byPath = new Map();
+    for (const detail of fileDetails) {
+        const key = normalizeMapKey(path.resolve(detail.filePath));
+        const previous = byPath.get(key);
+        if (!previous) {
+            byPath.set(key, detail);
+            continue;
+        }
+        byPath.set(key, {
+            filePath: previous.filePath,
+            range: previous.range && detail.range
+                ? {
+                    start: Math.min(previous.range.start, detail.range.start),
+                    end: Math.max(previous.range.end, detail.range.end),
+                }
+                : previous.range ?? detail.range,
+            importsChanged: previous.importsChanged || detail.importsChanged,
+        });
+    }
+    return files.map((filePath) => byPath.get(normalizeMapKey(path.resolve(filePath))) ?? {
+        filePath,
+        // Resource operations have no already-computed text range. A small
+        // range is still enough to invalidate the touched-file turn state;
+        // never synchronously re-read the whole file here.
+        range: { start: 1, end: 1 },
+        importsChanged: true,
+    });
+}
+function bookkeepLspMutation(context, files, fileDetails) {
+    const details = uniqueDetails(files, fileDetails);
+    for (const detail of details) {
+        const filePath = path.resolve(detail.filePath);
+        if (context.readGuard) {
+            try {
+                context.readGuard.recordWritten(filePath);
+            }
+            catch (err) {
+                context.dbg?.(`lsp mutation read-guard stamp failed for ${filePath}: ${err}`);
+            }
+        }
+        const runtime = context.runtime;
+        if (runtime?.bumpFileSeq) {
+            const { projectSeq, fileSeq } = runtime.bumpFileSeq(filePath);
+            try {
+                appendProjectChange(context.cwd, {
+                    seq: projectSeq,
+                    timestamp: new Date().toISOString(),
+                    sessionId: runtime.telemetrySessionId ?? "unknown",
+                    turnIndex: runtime.turnIndex ?? 0,
+                    source: context.source,
+                    filePath,
+                    fileSeq,
+                    changedRange: detail.range,
+                });
+            }
+            catch (err) {
+                context.dbg?.(`lsp mutation project change append failed for ${filePath}: ${err}`);
+            }
+        }
+        if (context.cacheManager) {
+            try {
+                context.cacheManager.addModifiedRange(filePath, detail.range ?? { start: 1, end: 1 }, detail.importsChanged ?? true, context.cwd, runtime?.telemetrySessionId);
+            }
+            catch (err) {
+                context.dbg?.(`lsp mutation modified-range tracking failed for ${filePath}: ${err}`);
+            }
+        }
+        if (context.recordAutofix && context.source === "autofix") {
+            const key = normalizeMapKey(filePath);
+            const seen = context.autofixRecordedPaths ?? new Set();
+            context.autofixRecordedPaths = seen;
+            if (!seen.has(key)) {
+                if (seen.size >= MAX_SAMPLES) {
+                    const oldest = seen.values().next().value;
+                    if (oldest)
+                        seen.delete(oldest);
+                }
+                seen.add(key);
+                context.recordAutofix(filePath);
+            }
+        }
+    }
+    if (context.publishFilesTouched && files.length > 0) {
+        context.publishFilesTouched(files);
+    }
+}
+function telemetryFor(context, options) {
+    const combined = combineResults(allResults(options));
+    const requestedTotal = options.requestedTotal ?? combined.requestedTotal;
+    const appliedTotal = combined.appliedTotal;
+    const requestedIndexes = Array.from({ length: Math.min(requestedTotal, MAX_SAMPLES) }, (_, index) => index);
+    const rejectedTotal = Math.max(0, requestedTotal - appliedTotal);
+    const rejectedReasons = Array.from({ length: Math.min(rejectedTotal, MAX_SAMPLES) }, (_, index) => ({ index, code: "write_failed" }));
+    const status = options.status ?? (appliedTotal > 0 ? "success" : "skipped");
+    const editBatchSummary = createReadGuardEditBatchSummary({
+        requestedIndexes,
+        requestedTotal,
+        resolvedIndexes: requestedIndexes,
+        resolvedTotal: requestedTotal,
+        rejectedReasons,
+        rejectedTotal,
+        appliedIndexes: combined.appliedIndexes,
+        appliedTotal,
+        participantIds: [context.correlationId],
+        participantTotal: 1,
+        commitStatus: status === "failed"
+            ? "failed"
+            : appliedTotal > 0
+                ? "committed"
+                : "no_changes",
+        terminalStatus: status,
+    });
+    return {
+        editBatchSummary,
+        operationCounts: {
+            requested: requestedTotal,
+            applied: appliedTotal,
+            textEdits: combined.textEdits,
+            create: combined.create,
+            rename: combined.rename,
+            delete: combined.delete,
+        },
+        sampledPaths: combined.paths.slice(0, MAX_SAMPLES),
+        sampledPathsTotal: combined.paths.length,
+        sampledPathsTruncated: combined.paths.length > MAX_SAMPLES,
+        considered: options.considered,
+        completed: options.completed,
+        failedCount: options.failedCount,
+    };
+}
+export function recordLspMutation(context, options = {}) {
+    const results = allResults(options);
+    const combined = combineResults(results);
+    if (options.bookkeep !== false && combined.files.length > 0) {
+        bookkeepLspMutation(context, combined.files, combined.fileDetails);
+    }
+    const telemetry = telemetryFor(context, options);
+    if (context.emitSummary !== false) {
+        const summaryCount = context.summaryCount ?? 0;
+        context.summaryEmitted = true;
+        if (summaryCount < MAX_SUMMARIES_PER_CONTEXT) {
+            context.summaryCount = summaryCount + 1;
+            logReadGuardEvent({
+                event: "edit_batch_summary",
+                correlationId: context.correlationId,
+                filePath: combined.files[0] ?? context.cwd,
+                metadata: {
+                    tool: context.tool,
+                    source: context.source,
+                    outcome: telemetry.editBatchSummary.terminalStatus,
+                    // The outer correlation identifies the soliciting tool call; the
+                    // bounded sequence distinguishes multiple applyEdit requests within it.
+                    summaryIndex: summaryCount,
+                    editBatchSummary: telemetry.editBatchSummary,
+                    operationCounts: telemetry.operationCounts,
+                    sampledPaths: telemetry.sampledPaths,
+                    sampledPathsTotal: telemetry.sampledPathsTotal,
+                    sampledPathsTruncated: telemetry.sampledPathsTruncated,
+                    considered: telemetry.considered,
+                    completed: telemetry.completed,
+                    failedCount: telemetry.failedCount,
+                },
+            });
+        }
+        else if (!context.summaryOverflowed) {
+            context.summaryOverflowed = true;
+            logReadGuardEvent({
+                event: "edit_batch_summary_overflow",
+                correlationId: context.correlationId,
+                filePath: combined.files[0] ?? context.cwd,
+                metadata: {
+                    tool: context.tool,
+                    source: context.source,
+                    summaryLimit: MAX_SUMMARIES_PER_CONTEXT,
+                    suppressedSummaries: "one or more",
+                },
+            });
+        }
+    }
+    return telemetry;
+}
+export function recordLspMutationBatch(context, options) {
+    const previous = context.emitSummary;
+    context.emitSummary = true;
+    try {
+        return recordLspMutation(context, options);
+    }
+    finally {
+        context.emitSummary = previous;
+    }
+}
+export function recordLspMutationOutcome(context, status) {
+    return recordLspMutation(context, { status, requestedTotal: 0 });
+}

package/node_modules/pi-lens/dist/clients/mcp/analyze.js

@@ -13,16 +13,19 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { CacheManager } from "../cache-manager.js";
+import { CacheManager, MCP_TURN_STATE_OWNER_ID } from "../cache-manager.js";
 import { CASCADE_GRAPH_KINDS, dispatchLintWithResult, getLatencyReports, } from "../dispatch/integration.js";
 import { FactStore } from "../dispatch/fact-store.js";
 import { detectFileKind } from "../file-kinds.js";
 import { getDiagnosticTracker } from "../diagnostic-tracker.js";
 import { getLSPService } from "../lsp/index.js";
+import { PathKeyedMap } from "../path-keyed-map.js";
+import { normalizeMapKey } from "../path-utils.js";
 import { loadProjectSnapshot } from "../project-snapshot.js";
 import { buildOrUpdateGraph } from "../review-graph/service.js";
 import { recordDiagnostics } from "../widget-state.js";
 import { deserializeWordIndex, removeWordIndexDocument, scheduleWordIndexPersist, updateWordIndexDocument, WORD_INDEX_MAX_BYTES, } from "../word-index.js";
+import { logWordIndex } from "../word-index-logger.js";
 import { createMcpHost } from "./host-shim.js";
 // #536: module-scoped FactStore for the warm-analyze graph seam, mirroring the
 // per-edit cascade path's own module-level `sessionFacts` singleton
@@ -43,7 +46,59 @@ const warmGraphFacts = new FactStore();
 // nothing usable" (index missing or pre-phase-2/no-forward-map), distinct from
 // "never checked" (key absent) — avoids re-attempting a snapshot load with no
 // forward index on every single analyze call.
-const warmWordIndexes = new Map();
+const DEFAULT_WORD_INDEX_IDLE_EVICT_MS = 20 * 60_000;
+const DEFAULT_WORD_INDEX_MAX_WARM_ROOTS = 8;
+const warmWordIndexes = new PathKeyedMap(normalizeMapKey);
+function positiveEnv(name, fallback) {
+    const parsed = Number.parseInt(process.env[name] ?? "", 10);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+function idleEvictMs() {
+    return positiveEnv("PI_LENS_WORD_INDEX_IDLE_EVICT_MS", DEFAULT_WORD_INDEX_IDLE_EVICT_MS);
+}
+function maxWarmRoots() {
+    return positiveEnv("PI_LENS_WORD_INDEX_MAX_WARM_ROOTS", DEFAULT_WORD_INDEX_MAX_WARM_ROOTS);
+}
+function clearWarmWordIndexTimer(entry) {
+    if (entry.timer)
+        clearTimeout(entry.timer);
+    entry.timer = undefined;
+}
+function evictWarmWordIndex(key, entry, reason) {
+    if (entry.leases > 0 || warmWordIndexes.get(key) !== entry)
+        return false;
+    clearWarmWordIndexTimer(entry);
+    warmWordIndexes.delete(key);
+    logWordIndex({
+        phase: "warm_cache_evicted",
+        cwd: key,
+        trigger: "mcp",
+        reason,
+    });
+    return true;
+}
+function scheduleWarmWordIndexIdleEviction(key, entry) {
+    clearWarmWordIndexTimer(entry);
+    const generation = ++entry.generation;
+    const timer = setTimeout(() => {
+        entry.timer = undefined;
+        if (warmWordIndexes.get(key) !== entry || entry.generation !== generation)
+            return;
+        if (!evictWarmWordIndex(key, entry, "idle"))
+            scheduleWarmWordIndexIdleEviction(key, entry);
+    }, idleEvictMs());
+    timer.unref?.();
+    entry.timer = timer;
+}
+function enforceWarmWordIndexLruCap() {
+    while (warmWordIndexes.size > maxWarmRoots()) {
+        const victim = [...warmWordIndexes.entries()]
+            .filter(([, entry]) => entry.leases === 0)
+            .sort(([, a], [, b]) => a.lastUsedAt - b.lastUsedAt)[0];
+        if (!victim || !evictWarmWordIndex(victim[0], victim[1], "lru"))
+            return;
+    }
+}
 /**
  * Look up (loading from the persisted snapshot on first use per cwd) the warm
  * in-memory word index this analyze facade keeps mutated in place. Exported so
@@ -52,26 +107,57 @@ const warmWordIndexes = new Map();
  * following a warm `pilens_analyze` call in the SAME process would read a
  * stale on-disk snapshot until the debounced persist (default 1500ms) flushes.
  */
-export function getOrLoadWarmWordIndex(cwd) {
+export function acquireWarmWordIndex(cwd) {
     const key = path.resolve(cwd);
-    if (warmWordIndexes.has(key))
-        return warmWordIndexes.get(key);
-    const snapshot = loadProjectSnapshot(key);
-    const index = deserializeWordIndex(snapshot?.wordIndex) ?? undefined;
-    // Same phase-2 rule as updateWordIndexForCascade: no forward index ⇒ no
-    // incremental primitive available, so don't cache it as "usable" — this
-    // call site's whole point is the incremental single-doc update.
-    const usable = index?.forward ? index : undefined;
-    warmWordIndexes.set(key, usable);
-    return usable;
+    let entry = warmWordIndexes.get(key);
+    if (!entry) {
+        const snapshot = loadProjectSnapshot(key);
+        const index = deserializeWordIndex(snapshot?.wordIndex) ?? undefined;
+        entry = {
+            index: index?.forward ? index : undefined,
+            timer: undefined,
+            leases: 0,
+            lastUsedAt: Date.now(),
+            generation: 0,
+        };
+        warmWordIndexes.set(key, entry);
+    }
+    entry.leases++;
+    entry.lastUsedAt = Date.now();
+    scheduleWarmWordIndexIdleEviction(key, entry);
+    enforceWarmWordIndexLruCap();
+    let released = false;
+    return {
+        index: entry.index,
+        release() {
+            if (released)
+                return;
+            released = true;
+            entry.leases = Math.max(0, entry.leases - 1);
+            entry.lastUsedAt = Date.now();
+            if (warmWordIndexes.get(key) === entry) {
+                scheduleWarmWordIndexIdleEviction(key, entry);
+                enforceWarmWordIndexLruCap();
+            }
+        },
+    };
 }
 /**
  * Test-only reset — the module-level warm cache otherwise survives across
  * unrelated test cases in the same vitest worker.
  */
 export function _resetWarmWordIndexCacheForTests() {
+    for (const entry of warmWordIndexes.values())
+        clearWarmWordIndexTimer(entry);
     warmWordIndexes.clear();
 }
+export function _getWarmWordIndexCacheStateForTests() {
+    return {
+        size: warmWordIndexes.size,
+        keys: [...warmWordIndexes.keys()],
+        timers: [...warmWordIndexes.values()].flatMap((entry) => entry.timer ? [entry.timer] : []),
+    };
+}
 // Generous warm-up budgets: a cold language server needs to spawn AND publish
 // diagnostics. The per-edit dispatch runner caps these tightly (spawn budget +
 // 2500ms) for latency; a review tool prioritises completeness, so we pre-warm
@@ -167,11 +253,11 @@ export async function analyzeFile(filePath, cwd, options = {}) {
     }
     if (options.registerTurnState) {
         // Full-file range, importsChanged=true (conservative → dep/knip re-check
-        // broadly). No sessionId — leaving it unset avoids turn_end's stale-session
-        // eviction. Best-effort.
+        // broadly). Clear any stale pi session ID because the MCP Stop route owns
+        // this workspace-scoped worklist independently. Best-effort.
         try {
             const lineCount = fs.readFileSync(absPath, "utf8").split("\n").length;
-            new CacheManager().addModifiedRange(absPath, { start: 1, end: lineCount }, true, cwd);
+            new CacheManager().addModifiedRange(absPath, { start: 1, end: lineCount }, true, cwd, options.ownerId ?? MCP_TURN_STATE_OWNER_ID, "mcp");
         }
         catch {
             // unreadable — skip turn-state registration
@@ -215,24 +301,30 @@ export async function analyzeFile(filePath, cwd, options = {}) {
         // INTERNALLY (PathKeyedMap), so this edit-form key and the build path's
         // walk-derived key converge on the same entry regardless of casing/
         // separator — the old duplicate-orphan hazard is gone at the map layer.
-        const warmIndex = getOrLoadWarmWordIndex(cwd);
-        if (warmIndex) {
-            try {
-                const content = fs.readFileSync(absPath, "utf8");
-                const byteLength = Buffer.byteLength(content, "utf-8");
-                if (byteLength > WORD_INDEX_MAX_BYTES) {
-                    removeWordIndexDocument(warmIndex, absPath);
+        const warmLease = acquireWarmWordIndex(cwd);
+        const warmIndex = warmLease.index;
+        try {
+            if (warmIndex) {
+                try {
+                    const content = fs.readFileSync(absPath, "utf8");
+                    const byteLength = Buffer.byteLength(content, "utf-8");
+                    if (byteLength > WORD_INDEX_MAX_BYTES) {
+                        removeWordIndexDocument(warmIndex, absPath);
+                    }
+                    else {
+                        updateWordIndexDocument(warmIndex, { path: absPath, content });
+                    }
+                    scheduleWordIndexPersist(cwd, warmIndex);
                 }
-                else {
-                    updateWordIndexDocument(warmIndex, { path: absPath, content });
+                catch {
+                    // unreadable/deleted, or an update failure — best-effort, same as the
+                    // graph update above.
                 }
-                scheduleWordIndexPersist(cwd, warmIndex);
-            }
-            catch {
-                // unreadable/deleted, or an update failure — best-effort, same as the
-                // graph update above.
             }
         }
+        finally {
+            warmLease.release();
+        }
     }
     // dispatchForFile appended a latency report during the call above. Match the
     // newly-added report for this exact path; fall back to the most recent new
@@ -243,8 +335,7 @@ export async function analyzeFile(filePath, cwd, options = {}) {
     const lspRunner = latencyReport?.runners.find((runner) => runner.runnerId === "lsp");
     const lsp = lspRunner
         ? {
-            ran: lspRunner.status !== "skipped" &&
-                lspRunner.status !== "when_skipped",
+            ran: lspRunner.status !== "skipped" && lspRunner.status !== "when_skipped",
             status: lspRunner.status,
             diagnosticCount: lspRunner.diagnosticCount,
             durationMs: lspRunner.durationMs,