@herbertgao/pi-extensions 2026.9.0 → 2026.9.1

package/node_modules/pi-lens/dist/clients/opaque-mutation-scan.js

@@ -56,6 +56,73 @@ export const OPAQUE_MTIME_TOLERANCE_MS = 150;
 // answer usefully about, and it is what makes the truncation guard below
 // reachable at all (#2100).
 const MAX_GIT_STATUS_OUTPUT_BYTES = 16 * 1024 * 1024;
+/**
+ * Stat (and optionally hash) an EXPLICIT file list into a snapshot.
+ *
+ * Extracted from `captureFileStats` so the observational net (#2430) reuses
+ * exactly this identity function — same key form, same hash algorithm, same
+ * byte budget — instead of hand-rolling a second scanner whose diff could
+ * disagree with `diffFileStats`. The walk-and-cap half stays in
+ * `captureFileStats`; a caller that already knows its file set skips it.
+ *
+ * `hashBudgetBytes` defaults to {@link OPAQUE_HASH_BUDGET_BYTES}. A file past
+ * the budget simply carries no hash, and its comparison degrades to
+ * mtime+size — the same documented limitation the walking capture has.
+ *
+ * `deadlineMs` (an absolute epoch stamp) and `signal` are both checked
+ * BETWEEN files, so a multi-path capture cannot outrun either bound. The FIRST
+ * entry always runs: the observational net's settle (#2430) guarantees the
+ * target path it took a baseline for is re-captured no matter what the clock
+ * says (#2449 review round 2, F5), and a bound that could cut the one path the
+ * caller actually asked about would drop a mutation already measured.
+ *
+ * There was a synchronous twin of this function until #2449 review round 3
+ * (T4). It existed only so `handleToolResult` could settle an observation
+ * without yielding; the settle is an ordinary async step now, and blocking the
+ * event loop on a directory's worth of `readFileSync` was never worth the
+ * ordering shortcut it bought.
+ */
+export async function captureFileStatsForPaths(files, options = {}) {
+    const hashBudget = options.hashBudgetBytes ?? OPAQUE_HASH_BUDGET_BYTES;
+    const snapshot = new Map();
+    let hashBytesSpent = 0;
+    let stoppedEarly = false;
+    let first = true;
+    for (const file of files) {
+        if (!first) {
+            if (options.signal?.aborted === true) {
+                stoppedEarly = true;
+                break;
+            }
+            if (options.deadlineMs !== undefined &&
+                Date.now() >= options.deadlineMs) {
+                stoppedEarly = true;
+                break;
+            }
+        }
+        first = false;
+        try {
+            const stat = await fs.promises.stat(file);
+            if (!stat.isFile())
+                continue;
+            const entry = {
+                mtimeMs: stat.mtimeMs,
+                size: stat.size,
+            };
+            if (options.withHashes && hashBytesSpent + stat.size <= hashBudget) {
+                entry.hash = createHash("sha256")
+                    .update(await fs.promises.readFile(file))
+                    .digest("hex");
+                hashBytesSpent += stat.size;
+            }
+            snapshot.set(normalizeMapKey(path.resolve(file)), entry);
+        }
+        catch {
+            // Vanished mid-walk: absent from both snapshots = unchanged-by-absence.
+        }
+    }
+    return { snapshot, stoppedEarly };
+}
 export async function captureFileStats(root, options = {}) {
     const budgetMs = options.budgetMs ?? 50;
     try {
@@ -74,28 +141,7 @@ export async function captureFileStats(root, options = {}) {
                 scannedCount: files.length,
             };
         }
-        const snapshot = new Map();
-        let hashBytesSpent = 0;
-        for (const file of files) {
-            try {
-                const stat = await fs.promises.stat(file);
-                const entry = {
-                    mtimeMs: stat.mtimeMs,
-                    size: stat.size,
-                };
-                if (options.withHashes &&
-                    hashBytesSpent + stat.size <= OPAQUE_HASH_BUDGET_BYTES) {
-                    entry.hash = createHash("sha256")
-                        .update(await fs.promises.readFile(file))
-                        .digest("hex");
-                    hashBytesSpent += stat.size;
-                }
-                snapshot.set(normalizeMapKey(path.resolve(file)), entry);
-            }
-            catch {
-                // Vanished mid-walk: absent from both snapshots = unchanged-by-absence.
-            }
-        }
+        const { snapshot } = await captureFileStatsForPaths(files, options);
         return { snapshot, scannedCount: snapshot.size };
     }
     catch {

package/node_modules/pi-lens/dist/clients/opengrep-config.js

@@ -13,6 +13,10 @@ export const LOCAL_OPENGREP_CONFIG_NAMES = [
     "semgrep.yml",
     "semgrep.yaml",
 ];
+// Deliberately UNCEILINGED at $HOME (refs #2472 review round 3, F1):
+// opengrep/semgrep's own resolver reads a rule file wherever it sits, and a
+// user-level `~/.opengrep.yml` is a legitimate global config, not an
+// escaped-workspace accident.
 export function findLocalOpengrepConfig(startDir) {
     return findLocalToolConfig(startDir, LOCAL_OPENGREP_CONFIG_NAMES);
 }

package/node_modules/pi-lens/dist/clients/package-manager.js

@@ -19,6 +19,8 @@ import * as path from "node:path";
 import { classifyProbeFailure, createAvailabilityLatch, isTransientDecision, logAvailabilityDecision, startHostStallSampler, } from "./dispatch/runners/utils/availability-policy.js";
 import { safeSpawnAsync } from "./safe-spawn.js";
 import { createAvailabilityProbeFlight } from "./availability-probe-flight.js";
+import { createGenerationSource, } from "./generation-guard.js";
+import { isAtOrAboveHomeDir, walkUpDirs } from "./path-utils.js";
 /**
  * Fallback preference when nothing is declared (or the declared manager is
  * missing). npm first for maximum compatibility; bun last. A project lockfile
@@ -197,11 +199,16 @@ function isAvailable(pm, onTransient) {
  * day, start a fresh session, pi-lens still reports it missing until a
  * process restart (#1653). Called from `handleSessionStart`'s per-session
  * reset block beside `resetZizmorTokenAvailability()` /
- * `resetPsScriptAnalyzerAvailability()`; also used directly by tests.
+ * `resetPsScriptAnalyzerAvailability()`; also used directly by tests. Also
+ * clears `globalBinDirCache`, whose memo lifetime rides the same reset — it
+ * must not outlive the availability verdicts it was derived from (#1602).
  */
 export function _resetPackageManagerCache() {
+    packageManagerCacheGeneration.bump();
     availabilityLatches.clear();
     packageManagerProbeFlights.clear();
+    globalBinDirCache.clear();
+    globalBinDirProbeFlights.clear();
 }
 // ============================================================================
 // RESOLUTION
@@ -311,12 +318,39 @@ export function execArgs(pm, pkg, args = []) {
 // ============================================================================
 // GLOBAL BIN DISCOVERY
 // ============================================================================
+/**
+ * Per-manager global bin dir, memoized for the process (cleared alongside
+ * `availabilityLatches` in `_resetPackageManagerCache`). Only a SUCCESSFUL
+ * lookup is cached: a spawn failure here is evidence about this call, not
+ * about the manager (the manager already passed `isAvailable`'s own probe),
+ * so it must not latch an empty result the way a genuine absence would. The
+ * generation guard owns post-await cache publication, so a probe crossing
+ * a session reset cannot repopulate the fresh memo. Reset clears the flight
+ * map separately, so later callers cannot share the pre-reset probe.
+ */
+const globalBinDirCache = new Map();
+const packageManagerCacheGeneration = createGenerationSource("package-manager-global-bin");
+const globalBinDirProbeFlights = createAvailabilityProbeFlight();
 /** Directories where a given manager installs global binaries. */
 async function globalBinDirsFor(pm) {
+    const cached = globalBinDirCache.get(pm);
+    if (cached)
+        return cached;
+    const generation = packageManagerCacheGeneration.capture();
+    // Concurrent callers (dispatch runs several tools per edit) must share ONE
+    // probe rather than each spawning their own `npm config get prefix` (#1602).
+    const shared = globalBinDirProbeFlights.run(pm, () => probeGlobalBinDirs(pm, generation));
+    return shared.promise;
+}
+async function probeGlobalBinDirs(pm, generation) {
     if (pm === "bun") {
         // bun has no per-call query cost — the global bin dir is deterministic.
         const base = process.env.BUN_INSTALL || path.join(os.homedir(), ".bun");
-        return [path.join(base, "bin")];
+        const dirs = [path.join(base, "bin")];
+        generation.guardedWrite(pm, () => {
+            globalBinDirCache.set(pm, dirs);
+        });
+        return dirs;
     }
     const query = pm === "npm"
         ? ["config", "get", "prefix"]
@@ -331,10 +365,11 @@ async function globalBinDirsFor(pm) {
         return [];
     // npm reports a prefix; binaries live in `<prefix>/bin` on Unix, `<prefix>`
     // on Windows. pnpm/yarn already print the bin dir directly.
-    if (pm === "npm") {
-        return [onWindows() ? out : path.join(out, "bin")];
-    }
-    return [out];
+    const dirs = pm === "npm" ? [onWindows() ? out : path.join(out, "bin")] : [out];
+    generation.guardedWrite(pm, () => {
+        globalBinDirCache.set(pm, dirs);
+    });
+    return dirs;
 }
 /**
  * Global bin directories for every installed manager, deduped. Used to locate a
@@ -394,31 +429,165 @@ export async function findGlobalBinary(command, windowsExt = ".cmd") {
     return undefined;
 }
 /**
- * Local `node_modules/.bin/<tool>` walking up from `startDir` to the fs root.
+ * The three project-local bin-directory shapes in this repo, most-preferred
+ * first. Exported so every caller passes the SAME constant instead of
+ * re-listing the directory names next to its own copy of the walk — the venv
+ * list alone had three independent spellings before #2544 review F1
+ * (`formatters.ts`, `runner-helpers.ts`'s `createVenvFinder`,
+ * `dead-code-client.ts`'s `venvCandidates`).
+ *
+ * `VENV_BIN_DIRS` lists BOTH the POSIX (`bin`) and Windows (`Scripts`) layouts
+ * unconditionally rather than branching on `process.platform` at module load:
+ * a module-load platform constant cannot be forced per test, so the other
+ * branch is never exercised on the ubuntu lane (defect shape 30). The extra
+ * two `existsSync` calls per directory are the price of a testable list, and
+ * a `.venv/Scripts` on Linux (or `.venv/bin` under msys) resolves correctly
+ * instead of being invisible.
+ */
+export const NODE_MODULES_BIN_DIRS = [
+    path.join("node_modules", ".bin"),
+];
+export const VENDOR_BIN_DIRS = [path.join("vendor", "bin")];
+export const VENV_BIN_DIRS = [
+    path.join(".venv", "bin"),
+    path.join("venv", "bin"),
+    path.join(".venv", "Scripts"),
+    path.join("venv", "Scripts"),
+];
+/**
+ * THE project-local tool-bin walk: yields every `<binDir>/<tool>` that exists
+ * in `startDir` or one of its ancestors, nearest first, stopping at the HOME
+ * ceiling (never the fs root — see below).
+ *
+ * A generator on purpose. {@link findLocalBinUpwards} takes the first match and
+ * the walk suspends there — no ancestor above the hit is ever stat'd, which is
+ * what a per-edit resolver needs — while {@link findLocalBinsUpwards} drains it
+ * for the ast-grep probe sweep, the one caller that legitimately wants every
+ * candidate above `startDir`. One walk body, two arities, no "collect-all"
+ * flag whose disabled half nothing can observe.
+ * `ceiling: false` opts a walk out of the HOME stop entirely (own-install
+ * trees only, see {@link LocalBinWalkOptions.ceiling}); {@link findLocalBinsAt}
+ * / {@link findLocalBinAt} below are the non-walking sibling for callers that
+ * must check exactly one directory and never climb (`createVenvFinder`,
+ * vulture's `venvCandidates`).
+ *
+ * `tools` is a LIST because the sweep callers probe several spellings of the
+ * same tool and the preference order is per-directory: all of a directory's
+ * candidates, in `tools` order, before the parent directory is looked at.
+ *
+ * `binDirs` makes this the ONLY such walker in the repo. Before #2544 there
+ * were SIX copies of this loop — `formatters.ts`'s `findInNodeModules` /
+ * `findInVendorBin` / `findInVenv`, `oxlint.ts`'s `resolveLocalVp`,
+ * `runner-helpers.ts`'s `findNodeBinRoots` and `resolveVendorToolCommand` —
+ * and they had drifted apart: only this one resolved a relative `startDir`,
+ * only this one had the #2514 HOME ceiling, and `vp` was resolved with
+ * OPPOSITE ceiling policies depending on whether `formatters.ts` or `oxlint.ts`
+ * asked (#2544 review F1). They all delegate here now.
+ *
+ * Candidate order is EXT-OUTER, DIR-INNER: on Windows every `binDir` is tried
+ * with `windowsExt` before any is tried with the bare name, matching what the
+ * `.venv/Scripts` walker did before the fold.
+ */
+/**
+ * Expand `tools` into the actual candidate file names for one directory,
+ * EXT-OUTER: on Windows every tool's extended name is tried before any tool's
+ * bare name (`windowsExt === ""` means the caller already spelled every name
+ * it wants — the ast-grep sweep passes `ast-grep.cmd`/`ast-grep.exe`/`ast-grep`
+ * itself in a shell-dependent order this option cannot express).
+ */
+function expandCandidateNames(tools, windowsExt, isWindows) {
+    return isWindows && windowsExt !== ""
+        ? tools.flatMap((tool) => [`${tool}${windowsExt}`, tool])
+        : [...tools];
+}
+/** Every `<dir>/<binDir>/<name>` that exists, for exactly `dir` — no walk. */
+function* matchesInDir(dir, names, binDirs) {
+    for (const name of names) {
+        for (const binDir of binDirs) {
+            const full = path.join(dir, binDir, name);
+            if (fs.existsSync(full))
+                yield full;
+        }
+    }
+}
+function* localBinMatches(tools, startDir, options) {
+    const { windowsExt = ".cmd", homeDir = os.homedir(), binDirs = NODE_MODULES_BIN_DIRS, isWindows = onWindows(), ceiling = true, } = options;
+    const names = expandCandidateNames(tools, windowsExt, isWindows);
+    for (const dir of walkUpDirs(startDir)) {
+        // Tool-resolution walker, not a config lookup (#2514/#2517 policy):
+        // escaping the project upward past HOME means STOP, not keep reading. A
+        // config-file lookup (`findLocalToolConfig`) keeps climbing past HOME
+        // because the underlying tool would find a legitimate global config
+        // there too; a `node_modules/.bin` match found at or above HOME can
+        // never be THIS project's own installed dependency — it is some
+        // unrelated home-level manifest (the pi-extensions bin shim, #2514).
+        // Default-on (not opt-in like `findLocalToolConfig`'s `options.homeDir`)
+        // because there is no legitimate case for this resolver to hand back a
+        // bin from outside the project tree. `ceiling: false` (own-install
+        // walk only, #2544 round 4 F1) skips this check entirely.
+        if (ceiling && isAtOrAboveHomeDir(dir, homeDir))
+            return;
+        yield* matchesInDir(dir, names, binDirs);
+    }
+}
+/**
+ * The nearest project-local `<binDir>/<tool>` at or above `startDir`, or
+ * `undefined`. See {@link localBinMatches} for the walk itself.
  *
  * Exported so callers that must NOT pay for global-bin discovery can reuse this
  * walk instead of copying it. `findNodeToolBinary` below adds `findGlobalBinary`,
  * which spawns a probe per package manager; a caller resolving a command on
  * every run (knip, #1721) needs the filesystem half only.
  */
-export function findLocalBinUpwards(tool, startDir, windowsExt = ".cmd") {
-    const names = onWindows() ? [`${tool}${windowsExt}`, tool] : [tool];
-    let dir = path.resolve(startDir);
-    const root = path.parse(dir).root;
-    while (true) {
-        for (const name of names) {
-            const full = path.join(dir, "node_modules", ".bin", name);
-            if (fs.existsSync(full))
-                return full;
-        }
-        if (dir === root)
-            break;
-        const parent = path.dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return undefined;
+export function findLocalBinUpwards(tool, startDir, options = {}) {
+    // `.next().value`, not a `for…of` that returns on its first iteration: the
+    // latter is a single-iteration loop (SonarCloud S1751, and it reads as one
+    // too). The generator is simply left suspended after the first match — it
+    // holds no resource that needs closing, which is exactly why the walk above
+    // never stats an ancestor beyond the hit.
+    return localBinMatches([tool], startDir, options).next().value;
+}
+/**
+ * EVERY project-local match for `tools` at or above `startDir`, nearest first.
+ *
+ * For the ast-grep availability sweep (`runner-helpers.ts`'s `buildSgLocalBins`,
+ * which spawns `--version` against each candidate until one answers, both for
+ * the project walk and — with `ceiling: false` — pi-lens's own install-tree
+ * walk), which previously hand-rolled its own unceilinged climb precisely
+ * because the singular `findLocalBinUpwards` could not express "all of them"
+ * (#2544 review F1).
+ *
+ * NOT for a "project's own venv/vendor-bin first" resolver: `createVenvFinder`
+ * and vulture's `venvCandidates` looked like this walk's other two callers in
+ * round 3, but that was an unrequested behaviour change (round 3 introduced
+ * ancestor climbing where a single cwd/root lookup existed before, with no
+ * #2514 defect behind it) — reverted in round 4 F2 to {@link findLocalBinsAt}.
+ */
+export function findLocalBinsUpwards(tools, startDir, options = {}) {
+    return [...localBinMatches(tools, startDir, options)];
+}
+/**
+ * EVERY `<dir>/<binDir>/<tool>` that exists for exactly `dir` — no ancestor
+ * walk, so the HOME ceiling is moot (a single directory can never climb past
+ * it).
+ *
+ * For the "project's own venv/vendor-bin first" resolvers that must NOT climb
+ * to a parent project (#2544 round 4 F2): `createVenvFinder` and vulture's
+ * `venvCandidates` were fixed `cwd`/`root` lookups before #2544 review round 3
+ * converted them into ancestor walks with no reported defect behind the
+ * conversion (an unrelated sibling project's interpreter at `~/code/.venv`
+ * could then outrank PATH for `~/code/app`, which has no venv of its own).
+ * Reverted here; `binDirs`/`windowsExt` stay shared with the walking helpers
+ * above so the three directory shapes have exactly one spelling.
+ */
+export function findLocalBinsAt(tools, dir, options = {}) {
+    const { windowsExt = ".cmd", binDirs = NODE_MODULES_BIN_DIRS, isWindows = onWindows(), } = options;
+    const names = expandCandidateNames(tools, windowsExt, isWindows);
+    return [...matchesInDir(path.resolve(dir), names, binDirs)];
+}
+/** The nearest — i.e. first-listed — `<dir>/<binDir>/<tool>` match, or `undefined`. */
+export function findLocalBinAt(tool, dir, options = {}) {
+    return findLocalBinsAt([tool], dir, options)[0];
 }
 /**
  * Locate a Node CLI tool's binary, preferring a local `node_modules/.bin`
@@ -432,6 +601,6 @@ export function findLocalBinUpwards(tool, startDir, windowsExt = ".cmd") {
  * without changing their npx fallback semantics.
  */
 export async function findNodeToolBinary(tool, cwd, windowsExt = ".cmd") {
-    return (findLocalBinUpwards(tool, cwd, windowsExt) ??
+    return (findLocalBinUpwards(tool, cwd, { windowsExt }) ??
         (await findGlobalBinary(tool, windowsExt)));
 }