@herbertgao/pi-extensions 2026.9.0 → 2026.9.1

package/node_modules/pi-lens/dist/clients/project-snapshot.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from "node:url";
 import { Worker } from "node:worker_threads";
 import { gunzipSync, gzipSync } from "node:zlib";
 import { writeFileAtomic } from "./atomic-write.js";
+import { BoundedFifoMap } from "./bounded-cache.js";
 import { getProjectDataDir } from "./file-utils.js";
 import { incrementDegradationCount } from "./degradation-ledger.js";
 import { readJsonCache } from "./json-cache-read.js";
@@ -130,14 +131,14 @@ export function readProjectSnapshotMeta(cwd) {
 export function isProjectSnapshotMetaStale(meta, currentProjectSeq) {
     return (meta.version !== PROJECT_SNAPSHOT_VERSION || meta.seq !== currentProjectSeq);
 }
-const SNAPSHOT_PARSE_CACHE_MAX = 4;
+export const SNAPSHOT_PARSE_CACHE_MAX = 4;
 // #957 review: the cache exists to avoid re-parsing NORMAL snapshots within a
 // session. A 112MB-class body parses to hundreds of MB of heap — pinning that
 // for process lifetime inverts the win, so oversized bodies are simply never
 // cached (they re-parse per read, exactly the pre-#947 behavior). Measured
 // against the UNCOMPRESSED body size, never the (much smaller) gz file size.
 const SNAPSHOT_PARSE_CACHE_MAX_BYTES = 24 * 1024 * 1024;
-const snapshotParseCache = new Map();
+const snapshotParseCache = new BoundedFifoMap(SNAPSHOT_PARSE_CACHE_MAX);
 function withoutWordIndex(snapshot) {
     if (!snapshot?.wordIndex)
         return snapshot;
@@ -145,18 +146,13 @@ function withoutWordIndex(snapshot) {
     return stripped;
 }
 function cacheParsedSnapshot(snapshotPath, entry) {
-    // Refresh recency (Map preserves insertion order).
+    // Refresh recency (delete then set moves the key to the newest position;
+    // BoundedFifoMap itself never reorders an already-present key on set()).
     snapshotParseCache.delete(snapshotPath);
     snapshotParseCache.set(snapshotPath, entry);
-    while (snapshotParseCache.size > SNAPSHOT_PARSE_CACHE_MAX) {
-        const oldest = snapshotParseCache.keys().next().value;
-        if (oldest === undefined)
-            break;
-        snapshotParseCache.delete(oldest);
-    }
 }
 const authoritativeSnapshots = new Map();
-const PROJECT_SNAPSHOT_MAX_WARM_ROOTS = 8;
+export const PROJECT_SNAPSHOT_MAX_WARM_ROOTS = 8;
 const PROJECT_SNAPSHOT_IDLE_EVICT_MS_DEFAULT = 20 * 60_000;
 function projectSnapshotIdleEvictMs() {
     const value = Number.parseInt(process.env.PI_LENS_PROJECT_SNAPSHOT_IDLE_EVICT_MS ?? "", 10);
@@ -620,8 +616,8 @@ export function loadProjectSnapshotWithoutWordIndex(cwd) {
     return loadProjectSnapshotInternal(cwd, false);
 }
 const _snapshotGenerationStates = new Map();
-const _successfulSnapshotPersists = new Map();
-const _failedSnapshotPersists = new Map();
+const _successfulSnapshotPersists = new BoundedFifoMap(PROJECT_SNAPSHOT_MAX_WARM_ROOTS);
+const _failedSnapshotPersists = new BoundedFifoMap(PROJECT_SNAPSHOT_MAX_WARM_ROOTS);
 const _activeSnapshotPersists = new Map();
 const _queuedSnapshotPersists = new Map();
 const _snapshotWorkerRequests = new Map();
@@ -648,12 +644,6 @@ function pendingSnapshotIsCurrent(pending) {
 function rememberSuccessfulSnapshotPersist(key, record) {
     _successfulSnapshotPersists.delete(key);
     _successfulSnapshotPersists.set(key, record);
-    while (_successfulSnapshotPersists.size > PROJECT_SNAPSHOT_MAX_WARM_ROOTS) {
-        const oldest = _successfulSnapshotPersists.keys().next().value;
-        if (oldest === undefined)
-            break;
-        _successfulSnapshotPersists.delete(oldest);
-    }
 }
 function assessSnapshotBodyIntegrity(meta, body) {
     if (meta.gzBytes === undefined) {
@@ -808,12 +798,6 @@ function recordSnapshotPersistFailure(pending, error, bodyPersisted = false) {
         seq: pending.snapshot.seq,
         generation: pending.generation,
     });
-    while (_failedSnapshotPersists.size > PROJECT_SNAPSHOT_MAX_WARM_ROOTS) {
-        const oldest = _failedSnapshotPersists.keys().next().value;
-        if (oldest === undefined)
-            break;
-        _failedSnapshotPersists.delete(oldest);
-    }
     deleteAuthoritativeSnapshot(pending.key);
     logLatency({
         type: "phase",
@@ -1492,6 +1476,50 @@ export function setProjectSnapshotPromotionSeamForTests(seam) {
 export function getProjectSnapshotPersistErrorForTests() {
     return _lastSnapshotPersistErrorForTests;
 }
+// ── #2442 test-only seams: exercise the three BoundedFifoMap-backed caches ──
+// through the exact same write path production uses (cacheParsedSnapshot /
+// rememberSuccessfulSnapshotPersist's delete+set refresh, and a direct write
+// mirroring recordSnapshotPersistFailure's), without the real gzip/worker
+// persistence pipeline or a full ProjectSnapshot fixture.
+/** Test-only: seed the parse cache exactly as `cacheParsedSnapshot` would. */
+export function _seedSnapshotParseCacheForTests(key, entry) {
+    cacheParsedSnapshot(key, entry);
+}
+export function _snapshotParseCacheKeysForTests() {
+    return [...snapshotParseCache.keys()];
+}
+/**
+ * #2442 test-only: the exact `snapshotParseCache.get(key)` the production
+ * read at {@link loadProjectSnapshot}'s parse-cache hit performs. A `.has()`
+ * would not do — `.has()` reorders nothing on either bounded class, so a
+ * has-based test cannot tell FIFO from LRU, which is the axis these bounded
+ * tests exist to pin (#2442 review F4).
+ */
+export function _snapshotParseCacheGetForTests(key) {
+    return snapshotParseCache.get(key) !== undefined;
+}
+/** Test-only: seed the successful-persist cache exactly as production would. */
+export function _seedSuccessfulSnapshotPersistForTests(key, record) {
+    rememberSuccessfulSnapshotPersist(key, record);
+}
+export function _successfulSnapshotPersistKeysForTests() {
+    return [..._successfulSnapshotPersists.keys()];
+}
+/** #2442 test-only: the same `_successfulSnapshotPersists.get(key)` the
+ *  persist-dedupe read and `getProjectSnapshotPersistStateForTests` perform.
+ *  See {@link _snapshotParseCacheGetForTests} for why `.has()` will not do. */
+export function _successfulSnapshotPersistGetForTests(key) {
+    return _successfulSnapshotPersists.get(key) !== undefined;
+}
+/** Test-only: seed the failed-persist cache with the same write
+ *  `recordSnapshotPersistFailure` performs, without its side effects
+ *  (deleteAuthoritativeSnapshot / logLatency) or a full PendingSnapshotBody. */
+export function _seedFailedSnapshotPersistForTests(key, record) {
+    _failedSnapshotPersists.set(key, record);
+}
+export function _failedSnapshotPersistKeysForTests() {
+    return [..._failedSnapshotPersists.keys()];
+}
 export function buildProjectSnapshotFromRuntime(args) {
     return {
         version: PROJECT_SNAPSHOT_VERSION,

package/node_modules/pi-lens/dist/clients/python-environment.js

@@ -0,0 +1,217 @@
+import { access, readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { extractTomlTableSection, hasTomlTable, parseTomlStringArray, } from "./cargo-manifest.js";
+import { isAtOrAboveHomeDir, matchesWorkspaceMemberPattern, toPosix, UV_WORKSPACE_EXCLUDE_DIALECT, UV_WORKSPACE_MEMBERS_DIALECT, walkUpDirs, } from "./path-utils.js";
+const UV_WORKSPACE_TABLE = "tool\\.uv\\.workspace";
+/**
+ * Resolve the uv workspace root using the same discovery shape as uv:
+ * start at the nearest pyproject, then continue upward for an explicit
+ * `[tool.uv.workspace]` declaration. A nearest pyproject without that table
+ * is an implicit single-project workspace.
+ *
+ * The walk stops AT `homeDir` (`isAtOrAboveHomeDir`, the shared ceiling
+ * primitive from #625) so a `pyproject.toml` sitting in `/tmp`, `/home`, or
+ * `$HOME` itself cannot supply the environment for every project beneath it.
+ * `homeDir` is injected rather than read from `os.homedir()` inside the walk
+ * for the same reason every sibling walker takes it (#2536, #2544 F2): the
+ * ceiling is otherwise untestable.
+ */
+async function findUvWorkspace(startDir, homeDir) {
+    const resolvedStart = path.resolve(startDir);
+    let nearestProject;
+    for (const dir of walkUpDirs(startDir)) {
+        if (isAtOrAboveHomeDir(dir, homeDir))
+            break;
+        let content;
+        try {
+            content = await readFile(path.join(dir, "pyproject.toml"), "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (!nearestProject)
+            nearestProject = dir;
+        if (hasTomlTable(content, UV_WORKSPACE_TABLE)) {
+            const workspaceTable = extractTomlTableSection(content, UV_WORKSPACE_TABLE);
+            return {
+                root: dir,
+                explicit: true,
+                projectRoot: nearestProject,
+                isStartDir: nearestProject === resolvedStart,
+                members: parseTomlStringArray(workspaceTable, "members"),
+                exclude: parseTomlStringArray(workspaceTable, "exclude"),
+            };
+        }
+    }
+    return nearestProject
+        ? {
+            root: nearestProject,
+            explicit: false,
+            projectRoot: nearestProject,
+            isStartDir: nearestProject === resolvedStart,
+            members: [],
+            exclude: [],
+        }
+        : undefined;
+}
+/**
+ * Apply uv's explicit-workspace membership rules before inheriting its root
+ * environment. The workspace root is always a member; descendants must match
+ * a declared member glob and must not match an exclusion glob.
+ *
+ * The glob dialects are pinned to uv 3c979abda4530fe9bf3d92e9bcf5c5575e3b3126,
+ * `crates/uv-workspace/src/workspace.rs`, and live beside the ONE shared
+ * workspace-member matcher (#2591) instead of as a minimatch options block
+ * here: `UV_WORKSPACE_MEMBERS_DIALECT` for `members`
+ * (`is_included_in_workspace` — `MatchOptions { require_literal_separator:
+ * true, ..MatchOptions::new() }`) and `UV_WORKSPACE_EXCLUDE_DIALECT` for
+ * `exclude` (`WorkspaceExclusions::matches` — `Pattern::matches_path`, i.e.
+ * `MatchOptions::new()` defaults, where `require_literal_separator` is FALSE
+ * and a `*` therefore crosses `/`). Both normalize the pattern first
+ * (`normalize_path`, so a leading `./` is not part of the pattern) and are
+ * case-SENSITIVE on every platform with no literal-leading-dot requirement.
+ *
+ * That `exclude` option set used to be a documented limitation rather than
+ * behavior: minimatch cannot express a separator-crossing `*`, so
+ * `exclude = ['packages/a*c']` did not exclude `packages/a/b/c`. A dialect
+ * object can, so #2591 implements it — the one intentional answer change in
+ * that fold.
+ */
+function isUvWorkspaceMember(workspace, projectRoot) {
+    // No `projectRoot === workspace.root` shortcut. uv treats the workspace
+    // root as a member of its own workspace, but only in its capacity as a
+    // PROJECT — and a project already gets uv's settings through `isStartDir`,
+    // with its own `<root>/.venv` reached by the ordinary project candidate at
+    // the very same path. Answering "member" on directory equality made every
+    // non-project subdirectory of the workspace root inherit the workspace
+    // `.venv`, `exclude` included, because equality was tested before the
+    // walk result was consulted (review round 3, S2). The relative-path guard
+    // below returns false for the root itself, which is the intended answer.
+    const relative = toPosix(path.relative(workspace.root, projectRoot));
+    if (relative.length === 0 ||
+        relative === ".." ||
+        relative.startsWith("../") ||
+        path.isAbsolute(relative)) {
+        return false;
+    }
+    const matches = (dialect) => (pattern) => matchesWorkspaceMemberPattern(pattern, relative, dialect);
+    return (!workspace.exclude.some(matches(UV_WORKSPACE_EXCLUDE_DIALECT)) &&
+        workspace.members.some(matches(UV_WORKSPACE_MEMBERS_DIALECT)));
+}
+/**
+ * Resolve the interpreter and executable directory for the project's Python
+ * environment without activating it or invoking a package manager.
+ */
+export async function detectPythonEnvironment(projectRoot, homeDir = os.homedir()) {
+    // `path.resolve` once at the seam entry so `isStartDir` below compares like
+    // with like: `walkUpDirs` resolves its input, a caller's argument need not
+    // be normalized.
+    const root = path.resolve(projectRoot);
+    const uvWorkspace = await findUvWorkspace(root, homeDir);
+    // `UV_PROJECT_ENVIRONMENT` and the workspace `.venv` are uv PROJECT
+    // settings. uv applies them to a directory only when that directory IS the
+    // project — a `pyproject.toml` merely sitting somewhere ABOVE it makes it a
+    // subdirectory of a project, not a project, and nothing below a project
+    // root inherits from it (the F3 decision, applied consistently). Exporting
+    // `UV_PROJECT_ENVIRONMENT` process-wide is uv's own documented CI/Docker
+    // recipe, so a gate on "a pyproject exists at or above root" lets one
+    // image-level variable capture every subdirectory on the box that happens
+    // to sit under some Python project.
+    const isProjectRoot = uvWorkspace?.isStartDir === true;
+    // A declared, non-excluded member of an EXPLICIT workspace is itself a
+    // project root, so this is a strict refinement of `isProjectRoot`: it adds
+    // the workspace `.venv` candidate and re-anchors a relative
+    // `UV_PROJECT_ENVIRONMENT` at the workspace root.
+    const memberWorkspaceRoot = isProjectRoot &&
+        uvWorkspace.explicit &&
+        isUvWorkspaceMember(uvWorkspace, root)
+        ? uvWorkspace.root
+        : undefined;
+    const uvEnvironmentRoot = isProjectRoot
+        ? (memberWorkspaceRoot ?? uvWorkspace.projectRoot)
+        : undefined;
+    const uvProjectEnvironment = process.env.UV_PROJECT_ENVIRONMENT;
+    // PEP 723 `uv run --script` environments are cache-keyed by script content;
+    // without a stable project marker or explicit path, they remain undiscoverable.
+    const candidates = [
+        ...(uvEnvironmentRoot !== undefined && uvProjectEnvironment
+            ? [
+                {
+                    // `path.resolve` leaves an absolute value untouched and
+                    // anchors a relative one at the project's workspace root.
+                    root: path.resolve(uvEnvironmentRoot, uvProjectEnvironment),
+                    source: "uv-project-environment",
+                },
+            ]
+            : []),
+        ...(memberWorkspaceRoot !== undefined
+            ? [
+                {
+                    root: path.join(memberWorkspaceRoot, ".venv"),
+                    source: "uv-workspace",
+                },
+            ]
+            : []),
+        { root: process.env.VIRTUAL_ENV, source: "virtual-env" },
+        { root: process.env.CONDA_PREFIX, source: "conda" },
+        { root: path.join(root, ".venv"), source: "project-dot-venv" },
+        { root: path.join(root, "venv"), source: "project-venv" },
+    ];
+    for (const candidate of candidates) {
+        if (!candidate.root)
+            continue;
+        const binDir = path.join(candidate.root, process.platform === "win32" ? "Scripts" : "bin");
+        const pythonPath = path.join(binDir, process.platform === "win32" ? "python.exe" : "python");
+        try {
+            await access(pythonPath);
+            return {
+                root: candidate.root,
+                binDir,
+                pythonPath,
+                source: candidate.source,
+            };
+        }
+        catch {
+            // The marker can outlive its environment. Continue to the next candidate.
+        }
+    }
+    return undefined;
+}
+/** Preserve the existing interpreter-only API used by LSP initialization. */
+export async function detectPythonVenv(projectRoot) {
+    return (await detectPythonEnvironment(projectRoot))?.pythonPath;
+}
+/**
+ * Build a child-only environment for Python tools. The host process remains
+ * unchanged, so another project can resolve a different environment.
+ */
+export function augmentPythonEnvironment(baseEnvironment, environment) {
+    if (!environment)
+        return baseEnvironment;
+    const inheritedPath = baseEnvironment.PATH ?? baseEnvironment.Path ?? baseEnvironment.path ?? "";
+    const augmentedPath = inheritedPath
+        ? `${environment.binDir}${path.delimiter}${inheritedPath}`
+        : environment.binDir;
+    const childEnvironment = {
+        ...baseEnvironment,
+        PATH: augmentedPath,
+        VIRTUAL_ENV: environment.root,
+    };
+    if (process.platform === "win32")
+        childEnvironment.Path = augmentedPath;
+    return childEnvironment;
+}
+/** Return explicit project-environment candidates before a bare PATH fallback. */
+export function pythonEnvironmentToolCandidates(environment, command) {
+    if (!environment)
+        return [];
+    if (process.platform !== "win32") {
+        return [path.join(environment.binDir, command)];
+    }
+    return [
+        path.join(environment.binDir, `${command}.exe`),
+        path.join(environment.binDir, `${command}.cmd`),
+        path.join(environment.binDir, command),
+    ];
+}