@herbertgao/pi-extensions 2026.9.0 → 2026.9.1

package/node_modules/pi-lens/dist/clients/dispatch/dispatcher.js

@@ -17,15 +17,16 @@ import { logExtension } from "../extension-log.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { recordRunner } from "../widget-state.js";
-import { incrementDegradationCount } from "../degradation-ledger.js";
+import { incrementDegradationCount, recordDegradationOnce, } from "../degradation-ledger.js";
 import { detectFileKind } from "../file-kinds.js";
 import { detectFileRole } from "../file-role.js";
+import { classifyGeneratedOrArtifactDetailed, } from "../generated-artifacts.js";
 import { isTestFile } from "../file-utils.js";
 import { getPrimaryDispatchGroup } from "../language-policy.js";
 import { resolveLanguageRootForFile } from "../language-profile.js";
 import { logLatency, phaseFinished, phaseStarted } from "../latency-logger.js";
 import { isSpawnableCommand } from "../installer/index.js";
-import { normalizeEphemeralMapKey, normalizeMapKey } from "../path-utils.js";
+import { isAbsoluteFilePath, normalizeEphemeralMapKey, normalizeMapKey, } from "../path-utils.js";
 import { loadPiLensProjectConfig } from "../project-lens-config.js";
 import { RUNTIME_CONFIG, getRunnerTimeoutFloorMs } from "../runtime-config.js";
 import { safeSpawnAsync } from "../safe-spawn.js";
@@ -61,7 +62,7 @@ export class RunnerRegistry {
         for (const runner of this.runners.values()) {
             if (isTest && runner.skipTestFiles)
                 continue;
-            if (runner.appliesTo.includes(kind) || runner.appliesTo.length === 0) {
+            if (runnerAppliesToKind(runner, kind)) {
                 matching.push(runner);
             }
         }
@@ -74,6 +75,10 @@ export class RunnerRegistry {
         this.runners.clear();
     }
 }
+function runnerAppliesToKind(runner, kind) {
+    return (runner.appliesTo.length === 0 ||
+        (kind !== undefined && runner.appliesTo.includes(kind)));
+}
 // --- Tool Availability Cache ---
 /**
  * Normalize a command name to a FactStore session key.
@@ -245,7 +250,19 @@ telemetryModel, telemetryProvider) {
     const normalizedCwd = normalizeMapKey(resolveLanguageRootForFile(absoluteFilePath, cwd));
     const normalizedFilePath = normalizeMapKey(absoluteFilePath);
     const kind = detectFileKind(normalizedFilePath);
-    const fileRole = detectFileRole(normalizedFilePath, readFilePrefix(normalizedFilePath));
+    const contentPrefix = readFilePrefix(normalizedFilePath);
+    const fileRole = detectFileRole(normalizedFilePath, contentPrefix);
+    // Captured once here so the generated short-circuit below can emit a
+    // `dispatch_skipped_generated` record carrying the deciding evidence tier
+    // and the measured line-shape statistic — without re-reading the file
+    // (refs #2346). The content passed is the same 4096-byte prefix already
+    // read for role detection, so this classification costs no extra I/O.
+    const generatedDetail = fileRole === "generated"
+        ? classifyGeneratedOrArtifactDetailed(normalizedFilePath, {
+            content: contentPrefix,
+            includeDeclarations: false,
+        })
+        : undefined;
     const projectConfig = loadPiLensProjectConfig(normalizedCwd);
     return {
         filePath: normalizedFilePath,
@@ -253,6 +270,8 @@ telemetryModel, telemetryProvider) {
         cwd: normalizedCwd,
         kind,
         fileRole,
+        generatedEvidence: generatedDetail?.evidence,
+        generatedLineShapeMean: generatedDetail?.lineShapeMean,
         pi,
         autofix: false,
         deltaMode: !pi.getFlag("no-delta"),
@@ -462,7 +481,9 @@ function buildCoverageNotice(ctx, runnerLatencies) {
     const primaryHasCoverage = relevant.some((r) => r.status === "succeeded" || r.status === "failed");
     if (primaryHasCoverage)
         return undefined;
-    const allPrimarySkipped = relevant.every((r) => r.status === "skipped" || r.status === "when_skipped");
+    const allPrimarySkipped = relevant.every((r) => r.status === "skipped" ||
+        r.status === "when_skipped" ||
+        r.status === "test_file_skipped");
     if (!allPrimarySkipped)
         return undefined;
     const plan = getToolPlan(ctx.kind);
@@ -499,6 +520,11 @@ function buildCoverageNotice(ctx, runnerLatencies) {
 }
 const latencyReports = [];
 const coverageNoticeSeen = new Set();
+// One `dispatch_skipped_generated` phase record per file per process (refs
+// #2346): a generated file dispatched repeatedly must not spam latency.log,
+// so only the first skip of each file emits the row; the degradation ledger
+// below still tallies every repetition with a bounded per-subject count.
+const generatedSkipRecorded = new Set();
 export function getLatencyReports() {
     return [...latencyReports];
 }
@@ -507,6 +533,7 @@ export function clearLatencyReports() {
 }
 export function clearCoverageNoticeState() {
     coverageNoticeSeen.clear();
+    generatedSkipRecorded.clear();
 }
 export function formatLatencyReport(report) {
     const lines = [];
@@ -588,6 +615,59 @@ async function runGroup(ctx, group, registry, onRunnerResult) {
             });
             continue;
         }
+        // Same skipTestFiles gate RunnerRegistry.getForKind applies for the
+        // per-edit path (#2337): the plan/group path resolves runners by id via
+        // registry.get() instead, which bypasses getForKind entirely, so a
+        // runner declaring skipTestFiles never had it enforced here.
+        if (runner.skipTestFiles && isTestFile(ctx.filePath)) {
+            latencies.push({
+                runnerId,
+                startTime: runnerStart,
+                endTime: Date.now(),
+                durationMs: Date.now() - runnerStart,
+                status: "test_file_skipped",
+                diagnosticCount: 0,
+                semantic: "none",
+            });
+            logLatency({
+                type: "runner",
+                filePath: ctx.filePath,
+                runnerId,
+                durationMs: 0,
+                status: "test_file_skipped",
+                diagnosticCount: 0,
+                semantic: "none",
+            });
+            continue;
+        }
+        // Keep explicit groups aligned with RunnerRegistry.getForKind(): an empty
+        // appliesTo list means every kind, while a populated list must contain the
+        // current kind. A filtered runner remains visible as skipped telemetry so
+        // language mismatches cannot be mistaken for runner failures.
+        const appliesToCurrentKind = runnerAppliesToKind(runner, ctx.kind);
+        if (!appliesToCurrentKind) {
+            const runnerEnd = Date.now();
+            latencies.push({
+                runnerId,
+                startTime: runnerStart,
+                endTime: runnerEnd,
+                durationMs: 0,
+                status: "skipped",
+                diagnosticCount: 0,
+                semantic: "unknown",
+            });
+            logLatency({
+                type: "runner",
+                filePath: ctx.filePath,
+                runnerId,
+                durationMs: 0,
+                status: "skipped",
+                diagnosticCount: 0,
+                semantic: "unknown",
+                metadata: { reason: "applies_to", kind: ctx.kind },
+            });
+            continue;
+        }
         // Check preconditions
         let shouldRun = true;
         if (runner.when) {
@@ -802,6 +882,31 @@ async function runGroup(ctx, group, registry, onRunnerResult) {
 export async function dispatchForFile(ctx, groups, registry, onRunnerResult) {
     const _overallStart = Date.now();
     if (ctx.fileRole === "generated") {
+        // The generated short-circuit (refs #2346): never ran before this fix
+        // for name-less machine-emitted files (a scraped/minified page has no
+        // `.min.js` pattern to catch it), so the classification now also has a
+        // content-shape tier. The skip is observable — one `dispatch_skipped_generated`
+        // phase record per file per process carrying the deciding evidence tier
+        // and the measured line-shape statistic. Deliberately NOT a degradation
+        // ledger entry: skipping a generated file is healthy behavior working
+        // as designed, and the ledger's bounded kind slots are reserved for
+        // genuine degradations (#2348 review F3 — the ledger precedent at the
+        // collect-later tier flip below records an actual capability loss).
+        const evidence = ctx.generatedEvidence;
+        const lineShapeMean = ctx.generatedLineShapeMean;
+        if (!generatedSkipRecorded.has(ctx.filePath)) {
+            generatedSkipRecorded.add(ctx.filePath);
+            logLatency({
+                type: "phase",
+                filePath: ctx.filePath,
+                phase: "dispatch_skipped_generated",
+                durationMs: 0,
+                metadata: {
+                    evidence: evidence ?? "unknown",
+                    ...(lineShapeMean !== undefined && { lineShapeMean }),
+                },
+            });
+        }
         return {
             diagnostics: [],
             blockers: [],
@@ -836,17 +941,46 @@ export async function dispatchForFile(ctx, groups, registry, onRunnerResult) {
     // group order so output is deterministic.
     const groupResults = await Promise.all(groups.map((group) => runGroup(ctx, group, registry, onRunnerResult)));
     // Count baseline warnings before filtering (for delta count display)
-    const relativeKey = path.relative(ctx.cwd, ctx.filePath).replace(/\\/g, "/");
+    //
+    // #2489: `ctx.filePath` is `createDispatchContext`'s `normalizedFilePath`
+    // (`resolveRunnerPath` -> `path.resolve` -> `normalizeMapKey`), which is
+    // ALWAYS absolute — the #2016 invariant this seam already relies on. A
+    // prior relative-path fallback key (`session.baseline.<path relative to
+    // ctx.cwd>`) existed here for self-consistency across the abs/rel read
+    // and write, but on `ctx.facts` singletons that outlive one project root
+    // (`dispatch/integration.ts`'s module-scope `sessionFacts`, reached by
+    // the warm `pilens_analyze` MCP route across any number of cwds) two
+    // different projects dispatching files that share a relative path (e.g.
+    // both have `src/index.ts`) collided on that fallback key, so project
+    // B's first-ever delta baseline read could silently return project A's
+    // stored diagnostics. Since the absolute key can never collide across
+    // projects (an absolute path is unique on the filesystem) and both
+    // writes always land together, the relative fallback is both unneeded
+    // and the sole source of the collision — removed rather than cwd-scoped
+    // (`cwd` is not a stable identity across this seam's callers, #2494).
+    //
+    // #2489 round 2: the #2016 invariant above is enforced by
+    // `createDispatchContext`, the sole real constructor, but nothing enforced
+    // it AT THIS SEAM — a hand-built `DispatchContext` (test scaffolding, a
+    // future caller) carrying a relative `filePath` would silently key the
+    // baseline under a value the constructor could never produce, and every
+    // subsequent same-session dispatch of the real (absolute-keyed) file would
+    // read back `undefined`, never the collision itself. Mirrors the sibling
+    // guard `recordEntitySnapshotDiff` already enforces for the entity-snapshot
+    // seam (`clients/review-graph/service.ts`, #2477): reject visibly and skip
+    // the baseline read/write for this dispatch rather than compute one under
+    // an unreachable key.
+    const baselinePathSafe = isAbsoluteFilePath(ctx.filePath);
+    if (ctx.deltaMode && !baselinePathSafe) {
+        recordDegradationOnce({
+            kind: "dispatch-non-absolute-baseline-path",
+            subject: ctx.filePath,
+            reason: "dispatchForFile requires an absolute ctx.filePath to key the delta baseline (refs #2489)",
+        });
+    }
     const baselineAbsKey = `session.baseline.${ctx.filePath}`;
-    // #2016: `relativeKey` is relative to `ctx.cwd`. `normalizeMapKey` resolved
-    // it against the process cwd instead, so on Windows this "relative" key
-    // became an absolute path anchored on the wrong root while POSIX left it
-    // relative. Both the read here and the write below use this const, so the
-    // key stays self-consistent within a session.
-    const baselineRelKey = `session.baseline.${normalizeEphemeralMapKey(relativeKey)}`;
-    const previousBaseline = ctx.deltaMode
-        ? (ctx.facts.getSessionFact(baselineAbsKey) ??
-            ctx.facts.getSessionFact(baselineRelKey))
+    const previousBaseline = ctx.deltaMode && baselinePathSafe
+        ? ctx.facts.getBoundedSessionFact(baselineAbsKey)
         : undefined;
     const baselineWarnings = previousBaseline?.filter((d) => d.semantic === "warning" || d.semantic === "none");
     const baselineWarningCount = baselineWarnings?.length ?? 0;
@@ -913,9 +1047,12 @@ export async function dispatchForFile(ctx, groups, registry, onRunnerResult) {
         resolvedCount = filtered.fixed.length;
     }
     // Persist full current snapshot for next run (not delta-filtered subset).
-    if (ctx.deltaMode) {
-        ctx.facts.setSessionFact(baselineAbsKey, [...dedupedDiagnostics]);
-        ctx.facts.setSessionFact(baselineRelKey, [...dedupedDiagnostics]);
+    // Gated on `baselinePathSafe` too: a non-absolute `ctx.filePath` already
+    // skipped the read above (the degradation record fired there), and writing
+    // under that same unreachable key here would just seed a baseline no real
+    // reader (always absolute) could ever read back.
+    if (ctx.deltaMode && baselinePathSafe) {
+        ctx.facts.setBoundedSessionFact(baselineAbsKey, [...dedupedDiagnostics]);
     }
     // Categorize results
     const blockers = visibleDiagnostics.filter((d) => d.semantic === "blocking");
@@ -1003,6 +1140,13 @@ export async function dispatchForFile(ctx, groups, registry, onRunnerResult) {
             })),
             totalDiagnostics: visibleDiagnostics.length,
             blockers: blockers.length,
+            // #2489 round 2: distinguishes a delta baseline HIT (a prior snapshot
+            // was read for this file this session) from a MISS (first dispatch, or
+            // the non-absolute-path guard above skipped the read) — `dispatch_start`
+            // (above, `metadata: { groupCount, kind, runners }`) fires before the
+            // baseline read ever runs and cannot carry either value.
+            baselineHit: previousBaseline !== undefined,
+            baselineWarningCount,
         },
     });
     return {

package/node_modules/pi-lens/dist/clients/dispatch/fact-store.js

@@ -1,3 +1,4 @@
+import { BoundedLruCache } from "../bounded-cache.js";
 import { normalizeMapKey } from "../path-utils.js";
 let capacityEvictionReporter;
 export function setFactStoreEvictionReporter(reporter) {
@@ -17,11 +18,60 @@ const MAX_FILE_FACT_RECORDS = 1024;
 // preventing a small number of generated or vendored files from retaining
 // hundreds of MiB for the process lifetime (#2247).
 const MAX_FILE_FACT_CONTENT_BYTES = 64 * 1024 * 1024;
+// Pinned records are exempt from capacity eviction. A dispatch reads its
+// file's facts back after the runner groups settle (`file.content` misses read as
+// empty content, not as "re-derive"), and the fire-and-forget blast-radius
+// build runs a whole-project walk against the SAME store meanwhile — plain LRU
+// recency would let that walk evict the file being dispatched. Every other holder
+// re-derives an evicted fact from disk.
+//
+// #2243 item 2: a dispatch pins its file at start (`clearFileFactsFor`) and
+// releases it at completion (`endDispatchFor`, in the dispatch's finally). The
+// pin set therefore tracks dispatches actually IN FLIGHT, not the last N files
+// touched.
+// #2282: `sessionFacts` below is a flat `Map<factId, value>` shared by two
+// unrelated fact shapes — a small FIXED vocabulary (tool availability keyed by
+// command, the singleton "session.reviewGraph") and PER-FILE families that
+// mint one key per file touched (session baseline, cascade baseline, review-
+// graph entity snapshots) and never shrink. Only the second shape grows with
+// batch size, so only it gets a bound; the fixed vocabulary stays on the plain
+// map, unbounded, because its cardinality is small and stable. Per-file
+// session facts opt into `boundedSessionFacts` instead, reusing fileFacts'
+// LRU-count-cap-and-report discipline rather than adding a third mechanism.
+// No pin exemption here (unlike fileFacts): every current per-file session
+// fact is read once near dispatch start and written once at dispatch end, so
+// nothing re-reads its OWN key later in the same dispatch the way a runner
+// re-reads `file.content` — an eviction mid-batch only means the next dispatch
+// of that path sees no previous baseline, the same safe state as its first
+// ever dispatch this session.
+//
+// That equivalence holds only where an absent baseline means "report
+// everything", which is true for the diagnostic baselines and false for the
+// review-graph entity snapshot: there, an absent snapshot read as an empty one
+// puts every symbol in `added` and drives a blast-radius run for a file that
+// did not change. So an eviction leaves a tombstone, and a reader that needs
+// the distinction asks `wasBoundedSessionFactEvicted`. Tombstones are keys
+// only, and carry the same cap, so the coldest of them fall off in turn and
+// that key reverts to first-dispatch semantics.
+//
+// Four per-file keys are minted per dispatched file today (diagnostic
+// baseline, cascade baseline, entity snapshot, changed symbols), so 4096
+// records covers roughly 1024 distinct files before the coldest file's
+// baseline starts degrading.
+const MAX_SESSION_FACT_RECORDS = 4096;
 export class FactStore {
     subject;
     // Insertion order is eviction order: the oldest-used record is evicted first.
     fileFacts = new Map();
     sessionFacts = new Map();
+    // Bounded sibling of `sessionFacts` for per-file-keyed session facts (#2282).
+    // True LRU: every fetch (get or create, see getBoundedSessionFact) refreshes
+    // recency, so the oldest-UNUSED record is evicted first, not merely the
+    // oldest-inserted.
+    boundedSessionFacts = new BoundedLruCache(MAX_SESSION_FACT_RECORDS);
+    // Keys evicted from `boundedSessionFacts` and not written since, so a reader
+    // can tell "evicted" from "never seen" (#2282). Same cap, same FIFO order.
+    evictedSessionFactKeys = new Set();
     // Pin refcount per file. A file is exempt from capacity eviction while its
     // count is > 0. Refcounted, not a Set, so two overlapping dispatches of the
     // same file both hold the pin until BOTH settle (#2243 item 2).
@@ -269,10 +319,57 @@ export class FactStore {
     hasSessionFact(factId) {
         return this.sessionFacts.has(factId);
     }
+    /** Bounded counterpart to {@link getSessionFact} for per-file-keyed session
+     *  facts (#2282) — session baselines, cascade baselines, review-graph entity
+     *  snapshots. LRU touch: a read moves the record off the eviction end. */
+    getBoundedSessionFact(factId) {
+        if (!this.boundedSessionFacts.has(factId))
+            return undefined;
+        return this.boundedSessionFacts.get(factId);
+    }
+    /** Bounded counterpart to {@link setSessionFact}. Callers use this instead
+     *  of `setSessionFact` for any family that mints one key per file/entity
+     *  touched, so the store's count stays bounded across a large batch instead
+     *  of retaining one entry per distinct path for the process lifetime. */
+    setBoundedSessionFact(factId, value) {
+        this.evictedSessionFactKeys.delete(factId);
+        const evicted = this.boundedSessionFacts.set(factId, value);
+        for (const [oldestKey] of evicted) {
+            this.evictedSessionFactKeys.add(oldestKey);
+            while (this.evictedSessionFactKeys.size > MAX_SESSION_FACT_RECORDS) {
+                const oldestTombstone = this.evictedSessionFactKeys
+                    .values()
+                    .next().value;
+                if (oldestTombstone === undefined)
+                    break;
+                this.evictedSessionFactKeys.delete(oldestTombstone);
+            }
+            capacityEvictionReporter?.(this.subject, "session-count", `session-fact store axis=count exceeded ${MAX_SESSION_FACT_RECORDS} records; evicted least-recently-used fact for ${oldestKey}`);
+        }
+    }
+    hasBoundedSessionFact(factId) {
+        return this.boundedSessionFacts.has(factId);
+    }
+    /** True when this key held a bounded session fact that capacity eviction
+     *  dropped and nothing has rewritten since (#2282). Readers whose "absent"
+     *  branch is not a safe default — the review-graph entity snapshot, where
+     *  absent would read as "every symbol is new" — use this to tell an evicted
+     *  key from one this session has never seen. */
+    wasBoundedSessionFactEvicted(factId) {
+        return this.evictedSessionFactKeys.has(factId);
+    }
+    /** O(1) entry count for memory-attribution sampling (#2282 Observability):
+     *  the fixed-vocabulary map plus the bounded per-file map, so a caller gets
+     *  this store's whole `sessionFacts` footprint in one number. */
+    getSessionFactEntryCount() {
+        return this.sessionFacts.size + this.boundedSessionFacts.size;
+    }
     /** Call on session reset only. Clears everything including tool cache and baselines. */
     clearAll() {
         this.fileFacts.clear();
         this.sessionFacts.clear();
+        this.boundedSessionFacts.clear();
+        this.evictedSessionFactKeys.clear();
         this.pinnedFiles.clear();
         this.retainedContentBytes = 0;
         this.pinnedContentBytesTotal = 0;

package/node_modules/pi-lens/dist/clients/dispatch/integration.js

@@ -139,7 +139,6 @@ setFactStoreEvictionReporter((subject, axis, reason) => {
         reason,
     });
 });
-const cascadeDiagnosticBaselines = new Map();
 const sessionRunnerRegistry = new RunnerRegistry();
 registerDefaultRunners(sessionRunnerRegistry);
 const LSP_CAPABLE_KINDS = new Set(getLspCapableKinds());
@@ -385,7 +384,6 @@ export function resetDispatchBaselines(cwd) {
     clearModuleGraphCache();
     recentlyCleanNeighborCache.clear();
     primaryFilesThisTurn.clear();
-    cascadeDiagnosticBaselines.clear();
     cascadeSessionStats = {
         runs: 0,
         diagnosticsSurfaced: 0,
@@ -405,10 +403,16 @@ export function getCascadeSessionStats() {
 }
 const recentlyCleanNeighborCache = new Map();
 /** O(1) entry count of this module's turn-bounded cache (#1123 item 2
- *  memory attribution) — a `Map.size` read, never iterated. */
+ *  memory attribution) — a `Map.size` read, never iterated.
+ *  `sessionFactEntries` (#2282) is the dispatch `FactStore`'s own
+ *  `sessionFacts` footprint: the fixed-vocabulary map (small, unbounded by
+ *  design) plus the bounded per-file map (capped at `MAX_SESSION_FACT_RECORDS`
+ *  — see `fact-store.ts`), so this number is now itself bounded rather than
+ *  invisible growth. */
 export function getDispatchCascadeCacheStats() {
     return {
         recentlyCleanNeighborCacheSize: recentlyCleanNeighborCache.size,
+        sessionFactEntries: sessionFacts.getSessionFactEntryCount(),
     };
 }
 const RECENTLY_CLEAN_TTL_TURNS = 5;
@@ -1940,10 +1944,8 @@ function diagnosticDeltaKey(diagnostic) {
 function applyCascadeDeltaBaselines(neighbors) {
     return neighbors.map((neighbor) => {
         const baselineKey = `session.baseline.cascade.${normalizeMapKey(neighbor.filePath)}`;
-        const previous = cascadeDiagnosticBaselines.get(baselineKey) ??
-            sessionFacts.getSessionFact(baselineKey);
-        cascadeDiagnosticBaselines.set(baselineKey, [...neighbor.diagnostics]);
-        sessionFacts.setSessionFact(baselineKey, [...neighbor.diagnostics]);
+        const previous = sessionFacts.getBoundedSessionFact(baselineKey);
+        sessionFacts.setBoundedSessionFact(baselineKey, [...neighbor.diagnostics]);
         if (!previous)
             return neighbor;
         const before = new Set(previous.map(diagnosticDeltaKey));

package/node_modules/pi-lens/dist/clients/dispatch/runners/actionlint.js

@@ -61,7 +61,6 @@ const actionlintRunner = {
     id: "actionlint",
     appliesTo: ["yaml"],
     priority: PRIORITY.YAML_LINT + 1,
-    enabledByDefault: true,
     skipTestFiles: false,
     when(ctx) {
         return isGitHubWorkflowFile(ctx.filePath);