@herbertgao/pi-extensions 2026.8.6 → 2026.8.7

package/node_modules/pi-lens/dist/clients/dependency-checker.js

@@ -15,7 +15,7 @@ import { findNodeToolBinary } from "./package-manager.js";
 import { isFullyQualified } from "./path-utils.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
 import { createAvailabilityChecker, discoverManagedTool, getManagedToolEnvironment, resolveAvailableOrInstall, } from "./dispatch/runners/utils/runner-helpers.js";
-import { createAvailabilityLatch } from "./dispatch/runners/utils/availability-policy.js";
+import { createAvailabilityLatch, } from "./dispatch/runners/utils/availability-policy.js";
 /**
  * Build madge's argv for a circular-dependency scan.
  *
@@ -136,8 +136,15 @@ async function resolvedCommandIsStale(resolved, spawnableCache) {
     spawnableCache.set(resolved.cmd, spawnable);
     return !spawnable;
 }
-/** Run `mapper` over `items` with at most `concurrency` in flight at once. */
-async function mapWithConcurrency(items, concurrency, mapper) {
+/**
+ * Run `mapper` over `items` with at most `concurrency` in flight at once.
+ * Exported (#1810 review F6) so `clients/dispatch/runners/biome-check.ts`'s
+ * `resolveBiomeFixKinds` can reuse this exact worker-pool shape for its
+ * `biome explain` fan-out instead of carrying a second copy — this file
+ * predates that need but is otherwise unrelated to it; a shared home for
+ * this one helper wasn't worth a whole new module for two call sites.
+ */
+export async function mapWithConcurrency(items, concurrency, mapper) {
     if (items.length === 0)
         return;
     let nextIndex = 0;
@@ -353,6 +360,21 @@ export class DependencyChecker {
         this.availabilityLatch.noteUnavailable(verdict.outcome ?? "missing", verdict.cause ?? "not-found");
         return false;
     }
+    /**
+     * #1623: public availability verdict for callers outside the dispatch
+     * graph (mode=full's fresh-fetch) that need to say WHY `ensureAvailable()`
+     * most recently returned false, using the SAME outcome/cause this class
+     * already latched above — not a re-guessed "madge binary unavailable"
+     * that can't tell a transient retry-cooldown probe from a durable
+     * absence.
+     */
+    getAvailabilityVerdict() {
+        return {
+            outcome: this.availabilityLatch.getOutcome(),
+            cause: this.availabilityLatch.getCause(),
+            retryAtMs: this.availabilityLatch.getRetryAtMs(),
+        };
+    }
     /**
      * Check if a file is part of a circular dependency (from cache)
      */

package/node_modules/pi-lens/dist/clients/diagnostic-dispositions.js

@@ -53,26 +53,40 @@
  * assumption proves wrong in practice, a surrounding-window hash can be
  * layered on later without changing the store shape.
  */
-import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { commitDurableStore } from "./durable-store.js";
 import { logDispositionEvent } from "./disposition-logger.js";
 import { publishDisposition } from "./disposition-publish.js";
 import { getProjectDataDir } from "./file-utils.js";
+import { normalizeMessage as sharedNormalizeMessage, relativeFile as sharedRelativeFile, stableFindingId, } from "./finding-identity.js";
 import { normalizeMapKey } from "./path-utils.js";
 import { lineContentHash } from "./read-guard.js";
 // "defer" is session-ephemeral by design (#690) — held only in memory so it
 // resurfaces for free on the next process run, with no expiry/pruning logic
 // needed. Stores WEAK anchors (see module doc) so a deferred finding stays
 // hidden all session even if the flagged line itself is edited.
+//
+// Review-round F3 (#1625): this Set is process-GLOBAL, but a weak anchor
+// itself only encodes a RELATIVE path (`relativeFile` derives it from
+// `path.relative(cwd, filePath)`, never the cwd's own identity) plus
+// tool/rule/normalizedMessage — two unrelated projects sharing the same
+// relative path/tool/rule/message (e.g. "src/auth.ts" flagged by the same
+// eslint rule in project A and project B) collapse onto the IDENTICAL weak
+// anchor string. A defer in project A therefore silently suppressed the same
+// finding in project B for the rest of the process's life. Every read/write
+// below goes through `deferredKey`, which folds the resolved cwd into the Set
+// key, so the two projects can no longer collide.
 const deferredThisSession = new Set();
+function deferredKey(cwd, anchor) {
+    return `${normalizeMapKey(cwd)}::${anchor}`;
+}
 /** Exported (#802) so lens-diagnostic-mark's cross-check against live widget
  * diagnostics matches a message the same way anchor derivation does — a
- * second, slightly different normalizer would make a real match invisible. */
-export function normalizeMessage(message) {
-    return message.replace(/\s+/g, " ").trim().toLowerCase();
-}
+ * second, slightly different normalizer would make a real match invisible.
+ * Re-exports the shared `finding-identity.js` normalizer (#1816) so this
+ * module keeps its existing public surface. */
+export const normalizeMessage = sharedNormalizeMessage;
 // Anchor derivation chokepoint (#1024, #210 class): the `dd:`/`ddw:` id builders
 // (computeStrictAnchor/computeWeakAnchor) both derive their path component here,
 // so a mark and its later lookup diverge whenever the two callers pass different
@@ -91,34 +105,35 @@ export function normalizeMessage(message) {
 // widget hot path, and the read side already pays exactly this cost. Semantics
 // are unchanged: the `..`-escape fallback still returns the canonical filePath,
 // only now in the same canonical form the non-escape branch uses.
-function relativeFile(filePath, cwd) {
-    const canonicalCwd = normalizeMapKey(cwd);
-    const canonicalFile = normalizeMapKey(filePath);
-    const rel = path.relative(canonicalCwd, canonicalFile).replace(/\\/g, "/");
-    return rel && !rel.startsWith("..") ? rel : canonicalFile;
-}
+//
+// #1816: this used to be a local copy; it is now `finding-identity.js`'s
+// `relativeFile` (identical body — canonicalize both inputs through
+// `normalizeMapKey` before relativizing), re-exported so the rest of this
+// file, and the module doc/comments above referencing `relativeFile`, keep
+// working unchanged.
+const relativeFile = sharedRelativeFile;
 /** Site-specific anchor — see module doc. Used only for false-positive. */
 export function computeStrictAnchor(args) {
     const lines = args.content?.split(/\r?\n/);
     const lineText = args.line !== undefined && lines ? (lines[args.line - 1] ?? "") : "";
-    const parts = [
-        relativeFile(args.filePath, args.cwd),
-        args.tool ?? "",
-        args.rule ?? "",
-        normalizeMessage(args.message),
-        lineContentHash(lineText),
-    ];
-    return `dd:${createHash("sha256").update(parts.join("|")).digest("hex").slice(0, 12)}`;
+    return stableFindingId("dd:", {
+        cwd: args.cwd,
+        filePath: args.filePath,
+        parts: [
+            args.tool ?? "",
+            args.rule ?? "",
+            normalizeMessage(args.message),
+            lineContentHash(lineText),
+        ],
+    });
 }
 /** Intent-level anchor — see module doc. Used for defer/flagged/suppress. */
 export function computeWeakAnchor(args) {
-    const parts = [
-        relativeFile(args.filePath, args.cwd),
-        args.tool ?? "",
-        args.rule ?? "",
-        normalizeMessage(args.message),
-    ];
-    return `ddw:${createHash("sha256").update(parts.join("|")).digest("hex").slice(0, 12)}`;
+    return stableFindingId("ddw:", {
+        cwd: args.cwd,
+        filePath: args.filePath,
+        parts: [args.tool ?? "", args.rule ?? "", normalizeMessage(args.message)],
+    });
 }
 /** Both anchors a stored/filtered diagnostic would compute — the one shared
  * derivation both the dispatch-pipeline filter and lens-diagnostics' flagged
@@ -156,6 +171,15 @@ export function _setBeforeDispositionCacheRefreshForTests(hook) {
 export function _setDispositionStatForTests(statSync) {
     dispositionStatSync = statSync ?? fs.statSync;
 }
+// Test seam for `applyDispositionsMultiFile`'s per-group content read (#1625
+// F2) — Vitest can't `vi.spyOn` a bare ESM `node:fs` named export directly
+// ("Module namespace is not configurable in ESM"), so the F2 regression test
+// (proving the empty-store hoist means zero reads, not just fast ones)
+// swaps this indirection instead, mirroring `dispositionStatSync` above.
+let multiFileReadFileSync = fs.readFileSync;
+export function _setMultiFileReadForTests(readFileSync) {
+    multiFileReadFileSync = readFileSync ?? fs.readFileSync;
+}
 function readState(cwd) {
     const p = statePath(cwd);
     let stat;
@@ -328,7 +352,7 @@ export function markDisposition(cwd, target, disposition, reason, identity) {
     // mark) — the log should record what this mark shadowed either way.
     const existing = readState(cwd).dispositions?.[anchor];
     if (disposition === "defer") {
-        deferredThisSession.add(anchor);
+        deferredThisSession.add(deferredKey(cwd, anchor));
         emitMarkTelemetry(cwd, target, disposition, anchor, reason, existing, identity);
         return anchor;
     }
@@ -352,8 +376,12 @@ export function markDisposition(cwd, target, disposition, reason, identity) {
 export function getDisposition(cwd, anchor) {
     return readState(cwd).dispositions?.[anchor];
 }
-export function isDeferredThisSession(anchor) {
-    return deferredThisSession.has(anchor);
+/** #1625 F3: `anchor` alone is ambiguous across projects — a weak anchor
+ * encodes only a RELATIVE path plus tool/rule/message, never the project's
+ * own identity, so `cwd` must be supplied to disambiguate which project's
+ * defer is being checked. */
+export function isDeferredThisSession(cwd, anchor) {
+    return deferredThisSession.has(deferredKey(cwd, anchor));
 }
 /** Test-only escape hatch — defer state is module-level (one process = one
  * session), so tests need to reset it between cases. */
@@ -369,6 +397,14 @@ export function _resetDeferredForTests() {
  * Computes both anchors per diagnostic (cheap — same hash primitive, twice)
  * since false-positive is keyed strict while defer/suppress are keyed weak;
  * see module doc for why each disposition binds the way it does.
+ *
+ * Review-round F1 (#1625): a `d.semantic === "blocking"` diagnostic can be
+ * dropped ONLY by the STRICT (false-positive) branch — never by a WEAK-
+ * anchored suppress or defer. Two distinct secrets sharing the same
+ * rule/message (e.g. two different AWS keys on different lines) collapse
+ * onto the SAME weak anchor, so a weak suppress/defer on one would silently
+ * silence the other too; unacceptable for a STOP-tier finding. `flagged` is
+ * unaffected either way — it never drops anything, blocking or not.
  */
 export function applyDispositions(diagnostics, cwd, filePath, content) {
     if (!diagnostics.length)
@@ -378,16 +414,21 @@ export function applyDispositions(diagnostics, cwd, filePath, content) {
         return diagnostics;
     return diagnostics.filter((d) => {
         const { strict, weak } = anchorsForDiagnostic(cwd, filePath, d, content);
-        if (deferredThisSession.has(weak))
+        const isBlocking = d.semantic === "blocking";
+        if (!isBlocking && deferredThisSession.has(deferredKey(cwd, weak))) {
             return false;
+        }
         if (dispositions?.[strict]?.disposition === "false-positive")
             return false;
         // Belt-and-braces: the inline `pi-lens-ignore` comment is the real
         // suppress enforcement (see suppress-writer.ts) and normally already
         // dropped this finding upstream via applyInlineSuppressions. This is a
-        // harmless second cover for the store-only audit trail case.
-        if (dispositions?.[weak]?.disposition === "suppress")
+        // harmless second cover for the store-only audit trail case — gated
+        // off blocking findings per F1 above (the inline comment, unaffected
+        // by this gate, remains the real suppress mechanism for those too).
+        if (!isBlocking && dispositions?.[weak]?.disposition === "suppress") {
             return false;
+        }
         return true;
     });
 }
@@ -407,6 +448,13 @@ export function applyDispositions(diagnostics, cwd, filePath, content) {
  * content-based filter). suppress/defer, being intent-level and weak-anchored,
  * are the marks that must apply the instant a query re-serves cached findings,
  * and they do so here without any read.
+ *
+ * Review-round F1 (#1625): this filter is ENTIRELY weak-anchored — it has no
+ * strict-anchor branch to fall back to — so a `d.semantic === "blocking"`
+ * diagnostic is never dropped here at all, regardless of any suppress/defer
+ * mark. The full `applyDispositions` (content in hand, at the next per-edit
+ * dispatch or mode=full merge) is the only place a blocking finding can ever
+ * be suppressed, and only via its STRICT branch.
  */
 export function applyWeakDispositions(diagnostics, cwd, filePath) {
     if (!diagnostics.length)
@@ -415,6 +463,8 @@ export function applyWeakDispositions(diagnostics, cwd, filePath) {
     if (!dispositions && deferredThisSession.size === 0)
         return diagnostics;
     return diagnostics.filter((d) => {
+        if (d.semantic === "blocking")
+            return true;
         const weak = computeWeakAnchor({
             cwd,
             filePath,
@@ -423,10 +473,74 @@ export function applyWeakDispositions(diagnostics, cwd, filePath) {
             message: d.message,
             line: d.line,
         });
-        if (deferredThisSession.has(weak))
+        if (deferredThisSession.has(deferredKey(cwd, weak)))
             return false;
         if (dispositions?.[weak]?.disposition === "suppress")
             return false;
         return true;
     });
 }
+/**
+ * Multi-file variant of {@link applyDispositions} for lanes whose findings
+ * span many files in ONE report — gitleaks/trivy/govulncheck/opengrep
+ * project-wide scans (#1617), unlike the dispatch path's one-`ctx.filePath`-
+ * at-a-time shape. Groups by `filePathOf(diagnostic)`, reads each file's
+ * CURRENT content once, then delegates to `applyDispositions` per group —
+ * same anchor derivation, same strict/weak split, no cloned logic (#1617's
+ * single-source-of-truth requirement).
+ *
+ * Content read is best-effort: a file that no longer exists, or that this
+ * process can't read, degrades to `content: ""` for that group rather than
+ * dropping its diagnostics outright. `applyDispositions` already treats a
+ * missing/empty content argument safely — the STRICT (false-positive) anchor
+ * hashes the diagnostic's own line, so an empty content can't collide with a
+ * mark made against the file's real content and the finding simply isn't
+ * matched (fails OPEN — still reported); the WEAK anchor (suppress/defer)
+ * never looks at content at all, so those marks keep applying regardless.
+ * This is a deliberate choice, not an oversight: a security finding must
+ * never silently vanish just because its file went unreadable at filter
+ * time (a security finding staying VISIBLE on a read failure is the safe
+ * default; a stale mark quietly reappearing is recoverable, a leaked secret
+ * quietly disappearing is not).
+ *
+ * Review-round F2 (#1625): the empty-store early return is checked HERE,
+ * before any per-group file read — not left to `applyDispositions` to notice
+ * once already inside the per-group loop. Every mode=full analyzer call
+ * (9 lanes) runs through this on every scan, and the overwhelmingly common
+ * case is zero marks in the project; measured ~270ms of synchronous
+ * `fs.readFileSync` per analyzer per run for that common case before this
+ * hoist (reading every finding's file just to discover there was nothing to
+ * filter), ~0-1ms after.
+ */
+export function applyDispositionsMultiFile(diagnostics, cwd, filePathOf) {
+    if (!diagnostics.length)
+        return diagnostics;
+    const dispositions = readState(cwd).dispositions;
+    if (!dispositions && deferredThisSession.size === 0)
+        return diagnostics;
+    const groups = new Map();
+    for (const d of diagnostics) {
+        const filePath = filePathOf(d);
+        const group = groups.get(filePath);
+        if (group)
+            group.push(d);
+        else
+            groups.set(filePath, [d]);
+    }
+    const kept = new Set();
+    for (const [filePath, group] of groups) {
+        let content = "";
+        try {
+            content = multiFileReadFileSync(filePath, "utf-8");
+        }
+        catch {
+            // Unreadable/missing — fail open, see doc above.
+        }
+        for (const d of applyDispositions(group, cwd, filePath, content)) {
+            kept.add(d);
+        }
+    }
+    // Preserve the caller's original order/dedup by reference rather than the
+    // per-group insertion order above.
+    return diagnostics.filter((d) => kept.has(d));
+}

package/node_modules/pi-lens/dist/clients/diagnostic-line-freshness.js

@@ -0,0 +1,298 @@
+/**
+ * Past-EOF validity gate for cited diagnostic line numbers (#1641).
+ *
+ * A live session served diagnostics at lines 407-410 of a file that was 402
+ * lines on disk and UNMODIFIED — the LSP's in-memory document had drifted
+ * longer than disk without any file write happening (no didChange lost, just
+ * an in-memory buffer that grew past what the file actually contains). That
+ * makes this a DIFFERENT invariant than #1622/#1627's freshness gate: those
+ * compare a cited file's MTIME against a scan timestamp, which says nothing
+ * when the file was never touched on disk at all. The cheap, orthogonal check
+ * available here is structural: a diagnostic whose start line exceeds the
+ * file's CURRENT line count cannot possibly be describing current content,
+ * regardless of what any timestamp says.
+ *
+ * CONTRACT:
+ *   - A diagnostic citing a line beyond the file's current line count is
+ *     DEMOTED (`stale: true`), never dropped — the underlying issue may well
+ *     still be real, just at a coordinate this gate can no longer vouch for.
+ *   - RE-ARMS, never latches: the verdict is recomputed from the gate's own
+ *     inputs (current mtime, current line count) on every call, so a
+ *     TRANSIENT shrink (truncate-then-write, a formatter pass, a checkout)
+ *     that later restores the line un-demotes on its own next read. A
+ *     persisted `stale: true` a caller stores between calls is a cache of the
+ *     last-derived verdict, never an independent source of truth that
+ *     overrides the next derivation — the #1633-V1 lesson: derive, don't latch.
+ *   - Fail open: a file that cannot be stat'ed/read, or exceeds the size gate,
+ *     yields no verdict at all (every diagnostic passes through unchanged).
+ *     An unreadable/oversized file is not evidence of anything; demoting on
+ *     it would manufacture false staleness.
+ *   - The line count matches the LSP's own addressing, not `wc -l`: a
+ *     document with N newline characters has N+1 ADDRESSABLE lines (the
+ *     line after the final `\n`, or the single line of an empty document,
+ *     is a real position a server can anchor a diagnostic to — e.g. TS1005
+ *     "'}' expected" at EOF). `WidgetDiagnostic.line` is always
+ *     `range.start.line + 1` from that same addressing, so the gate must
+ *     use it too or every trailing-newline file demotes its own valid EOF
+ *     diagnostics.
+ *   - Cost discipline: one `statSync` per served file; the file's newlines
+ *     are counted in bounded chunks via a raw fd read (never a full
+ *     `readFileSync` — no whole-file string materialization, no per-render
+ *     re-read of unchanged content), gated by a byte-size cap matching
+ *     `captureReadContentBinding`'s precedent (`read-guard.ts`). The count is
+ *     memoized in a small SHARED cache (module-scoped, bounded, evicted FIFO
+ *     past a cap), keyed on BOTH mtime AND size (review round V1) — mtime
+ *     ALONE is not a reliable cache key on hosts where its resolution is
+ *     coarser than back-to-back writes: a truncate-then-write, a formatter
+ *     write-back, or pi-lens's own auto-format immediately followed by the
+ *     agent's write can land two DIFFERENT contents on the identical
+ *     `mtimeMs`, and a mtime-only cache serves the first content's count for
+ *     the second — measured live at 207/300 shrink/restore cycles. Requiring
+ *     both to match narrows a same-tick collision to same-mtime-AND-same-size
+ *     (which a shrink/restore cycle never produces, since the whole point is
+ *     the size changed). A changed file is always recounted. Tests can still
+ *     inject an isolated {@link LineCountCache} via {@link createLineCountCache}
+ *     to avoid cross-test bleed.
+ *   - On a demotion EDGE (a diagnostic that was not already flagged past-EOF
+ *     and now is), best-effort trigger a document resync (didClose/didOpen or
+ *     a full-sync didChange) so the desync HEALS instead of re-serving the
+ *     same stale verdict next time (#1631's resync-before-revalidate rule).
+ *     Resync is fire-and-forget: a failure here must never block or fail the
+ *     render path that discovered the drift. Already-demoted entries and the
+ *     healing direction never re-trigger a resync — only the rising edge does.
+ */
+import * as fs from "node:fs";
+import { logLatency } from "./latency-logger.js";
+import { toProjectRelativePath } from "./path-utils.js";
+import { STALE_LINE_MARKER } from "./stale-marker.js";
+/** Marker rendered in place of a demoted diagnostic's now-untrustworthy line.
+ * Shares the base `STALE_LINE_MARKER` vocabulary with sibling freshness
+ * gates (#1622/#1633) and adds this gate's own specific reason as a suffix. */
+export const PAST_EOF_STALE_MARKER = `${STALE_LINE_MARKER} — line past EOF`;
+/** How many demoted cited lines a single record names before it stops. */
+const MAX_LOGGED_PAST_EOF_LINES = 3;
+/** Byte-size gate matching `captureReadContentBinding`'s precedent
+ * (`clients/read-guard.ts`'s `READ_BINDING_MAX_BYTES`) — a hot render/serve
+ * path must never pay to scan an unbounded file. */
+const MAX_GATE_BYTES = 4 * 1024 * 1024;
+/** Chunk size for the bounded newline scan — small enough to keep one read's
+ * memory footprint negligible, large enough that a multi-MB file finishes in
+ * single-digit reads rather than thousands. */
+const NEWLINE_SCAN_CHUNK_BYTES = 64 * 1024;
+const NEWLINE_BYTE = 0x0a;
+/** Test-only isolation seam. Production code uses the shared default cache. */
+export function createLineCountCache() {
+    return new Map();
+}
+// Shared across calls/render passes so N files touched once per session cost
+// N recounts total, not N per render — the actual fix for the cost this gate
+// exists to control. Still cannot go stale: every read re-stats first and a
+// mismatched mtime always recomputes (see the module doc comment). Bounded
+// via FIFO eviction (mirrors `READ_GUARD_MAX_FILES`'s precedent) so a long
+// session's file count cannot grow this without limit.
+const MAX_SHARED_CACHE_ENTRIES = 512;
+const sharedLineCountCache = new Map();
+function rememberInSharedCache(cache, filePath, entry) {
+    if (cache === sharedLineCountCache &&
+        cache.size >= MAX_SHARED_CACHE_ENTRIES &&
+        !cache.has(filePath)) {
+        const oldest = cache.keys().next().value;
+        if (oldest !== undefined)
+            cache.delete(oldest);
+    }
+    cache.set(filePath, entry);
+}
+/** Test-only: drop the shared memo between test files/cases. */
+export function _resetSharedLineCountCacheForTests() {
+    sharedLineCountCache.clear();
+}
+/**
+ * Test-only: seed the shared memo with a fabricated entry, deterministically
+ * proving a cache HIT (and that the default cache used by callers with no
+ * explicit `lineCountCache` is genuinely shared across calls) without relying
+ * on a real write's mtime round-tripping through `fs.utimesSync` at full
+ * precision — a platform-specific hazard on its own, unrelated to what such a
+ * test is actually verifying.
+ */
+export function _seedSharedLineCountCacheForTests(filePath, entry) {
+    sharedLineCountCache.set(filePath, entry);
+}
+/**
+ * Count newline bytes in `filePath` via bounded raw reads — never a full
+ * `readFileSync`/UTF-8 decode of the whole file. `0x0A` (LF) never appears as
+ * a continuation byte in UTF-8, so counting it at the byte level is exact
+ * regardless of encoding, and multi-byte characters spanning a chunk boundary
+ * cannot produce a false match (a continuation byte's high bits can never
+ * equal `0x0A`).
+ */
+function countNewlinesChunked(filePath, sizeBytes) {
+    const fd = fs.openSync(filePath, "r");
+    try {
+        const buffer = Buffer.allocUnsafe(Math.min(NEWLINE_SCAN_CHUNK_BYTES, sizeBytes) || 1);
+        let newlineCount = 0;
+        let position = 0;
+        while (position < sizeBytes) {
+            const bytesRead = fs.readSync(fd, buffer, 0, buffer.length, position);
+            if (bytesRead <= 0)
+                break;
+            for (let i = 0; i < bytesRead; i++) {
+                if (buffer[i] === NEWLINE_BYTE)
+                    newlineCount++;
+            }
+            position += bytesRead;
+        }
+        return newlineCount;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/**
+ * LSP-addressable line count for `filePath`: newline count + 1, matching
+ * `range.start.line + 1` (a document with zero newlines still has one
+ * addressable line — position 0,0 — and a trailing `\n` adds one more,
+ * empty, addressable line after it). Memoized in `cache` (the shared default
+ * unless a caller injects its own) and invalidated by mtime AND size (V1 —
+ * mtime alone is not a reliable cache key on hosts where its resolution is
+ * coarser than back-to-back writes). Returns `undefined` when the file
+ * cannot be stat'ed, is zero bytes, exceeds the byte-size gate, or
+ * cannot be read (deleted, unreadable, permissions, oversized) — callers MUST
+ * treat `undefined` as "no verdict", not as "zero lines" (the empty-result-
+ * must-distinguish-clean-from-errored screen).
+ */
+export function getCachedLineCount(filePath, cache = sharedLineCountCache) {
+    let stat;
+    try {
+        stat = fs.statSync(filePath);
+    }
+    catch {
+        return undefined;
+    }
+    // A zero-byte stat can be a truncate-then-write window. It is not evidence
+    // that the file has one addressable line, so fail open like an unreadable
+    // file rather than manufacturing a verdict from the empty read.
+    if (stat.size === 0)
+        return undefined;
+    const cached = cache.get(filePath);
+    if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+        return cached.lineCount;
+    }
+    if (stat.size > MAX_GATE_BYTES)
+        return undefined;
+    let newlineCount;
+    try {
+        newlineCount = countNewlinesChunked(filePath, stat.size);
+    }
+    catch {
+        return undefined;
+    }
+    const lineCount = newlineCount + 1;
+    rememberInSharedCache(cache, filePath, {
+        mtimeMs: stat.mtimeMs,
+        size: stat.size,
+        lineCount,
+    });
+    return lineCount;
+}
+/**
+ * Recompute the past-EOF verdict for every diagnostic in `diagnostics`
+ * against `filePath`'s CURRENT line count. Sets `stale: true` on a match and
+ * `stale: false` when a previously-past-EOF line is back in bounds (a
+ * transient shrink healed) — the verdict is always derived fresh, never
+ * latched. Pure apart from the cached stat/read in {@link getCachedLineCount}
+ * and the bounded `logLatency`/`resync` calls, which fire only on a RISING
+ * edge (a diagnostic that was not already flagged and now is) so an
+ * unchanged persistent demotion doesn't re-log or re-resync on every render.
+ * Never throws, never mutates the input array.
+ */
+export function demotePastEofDiagnostics(args) {
+    const { diagnostics } = args;
+    if (diagnostics.length === 0) {
+        return { diagnostics: [], demotedCount: 0 };
+    }
+    const lineCount = getCachedLineCount(args.filePath, args.lineCountCache ?? sharedLineCountCache);
+    if (lineCount === undefined) {
+        // Fail open: no verdict available for this file right now. Leave
+        // whatever `stale` value each entry already carries untouched — this
+        // gate has nothing to say either direction.
+        return { diagnostics: [...diagnostics], demotedCount: 0 };
+    }
+    const risingEdgeLines = [];
+    const out = diagnostics.map((d) => {
+        // Another gate's demotion is not this gate's to heal (#1631 drift
+        // entries have in-bounds lines; re-deriving here would clear them).
+        if (d.stale && d.staleReason !== undefined && d.staleReason !== "past-eof")
+            return d;
+        const isPastEof = typeof d.line === "number" && d.line > lineCount;
+        if (isPastEof === !!d.stale)
+            return d; // no transition either direction
+        if (isPastEof)
+            risingEdgeLines.push(d.line);
+        return { ...d, stale: isPastEof, staleReason: isPastEof ? "past-eof" : undefined };
+    });
+    if (risingEdgeLines.length === 0) {
+        return { diagnostics: out, demotedCount: 0 };
+    }
+    let sizeBytes;
+    try {
+        sizeBytes = fs.statSync(args.filePath).size;
+    }
+    catch {
+        sizeBytes = 0;
+    }
+    logLatency({
+        type: "phase",
+        phase: "diagnostic_past_eof",
+        filePath: args.cwd,
+        durationMs: 0,
+        metadata: {
+            store: args.store,
+            file: toProjectRelativePath(args.filePath, args.cwd),
+            sizeBytes,
+            actualLineCount: lineCount,
+            demotedCount: risingEdgeLines.length,
+            sampleCitedLines: risingEdgeLines.slice(0, MAX_LOGGED_PAST_EOF_LINES),
+        },
+    });
+    if (args.resync) {
+        try {
+            args.resync(args.filePath);
+        }
+        catch {
+            // Best-effort — a resync failure must never fail the render path.
+        }
+    }
+    return { diagnostics: out, demotedCount: risingEdgeLines.length };
+}
+/**
+ * Default resync trigger (#1641 criterion 2): re-open the file with its
+ * CURRENT disk content so the LSP's in-memory document is replaced rather
+ * than left to re-publish the same divergent diagnostics next time
+ * (`LSPService.openFile` sends a full-sync didChange, or a didClose/didOpen
+ * pair for servers that only re-scan on a fresh open — see
+ * `handleNotifyOpen`'s `reopenOnResync` branch). Dynamic import (mirrors
+ * `clients/module-report-lsp.ts`) so this module — used from widget-state.ts
+ * and tools/lens-diagnostics.ts — never statically depends on `clients/lsp`,
+ * which itself imports widget-state.ts.
+ *
+ * Fire-and-forget by design: the caller is a synchronous render path and must
+ * not block on (or fail because of) a resync. No LSP service, no client for
+ * this file's language, or a transient read/spawn failure all degrade to a
+ * silent no-op — the next successful touch/dispatch resyncs anyway.
+ */
+export function resyncDocumentOnPastEof(filePath) {
+    void (async () => {
+        try {
+            const [{ getLSPService }, content] = await Promise.all([
+                import("./lsp/index.js"),
+                fs.promises.readFile(filePath, "utf-8"),
+            ]);
+            await getLSPService().openFile(filePath, content, {
+                preserveDiagnostics: false,
+            });
+        }
+        catch {
+            // Best-effort heal only.
+        }
+    })();
+}