@herbertgao/pi-extensions 2026.10.0 → 2026.10.2

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

@@ -1,388 +0,0 @@
-/**
- * WHERE pi-lens config lives, and in what order (#2426).
- *
- * Before this module the answer was spread across three loaders with three
- * different walks: `lsp/config.ts` had its own `CONFIG_PATHS` and an UNBOUNDED
- * upward walk to the filesystem root, `project-lens-config.ts` had its own
- * `PROJECT_CONFIG_BASENAMES` and a second unbounded walk, and `lens-config.ts`
- * read one fixed path. Three walks meant three places for the #622/#625
- * ceiling rule to be forgotten, and it was: a `pi-lsp.json` sitting in `$HOME`
- * — or in `C:\` — was read for every project on the machine.
- *
- * There are exactly TWO canonical locations:
- *
- *   `.pi-lens.json`            — project, nearest-package-wins per field
- *   `~/.pi-lens/config.json`   — machine-global
- *
- * Everything else in `PROJECT_CONFIG_LOCATIONS` / `GLOBAL_CONFIG_LOCATIONS` is
- * legacy, read for the deprecation window declared in
- * `DEPRECATED_CONFIG_SURFACES` and then removed. This module does not restate
- * that membership: it DERIVES the legacy set from the registry and orders it,
- * and `tests/clients/config-locations.test.ts` pins that the derived set is
- * exactly the registry's `kind: "file"` rows. Registry owns WHICH surfaces are
- * deprecated; this module owns only their precedence.
- *
- * Pure data, one walk, and — as of the global-config-location PR (refs #2457,
- * #2426) — the ONE existence probe and memoized resolution that decide which
- * file supplies the global tier. The probe is a single `statSync` under the
- * resolution memo; no other file reads, no state beyond that one memo.
- */
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { DEPRECATED_CONFIG_SURFACES } from "./config-diagnostic-codes.js";
-import { errorClassName } from "./error-class.js";
-import { isAtOrAboveHomeDir, isWindowsPath, normalizeFilePath, realpathOrResolve, walkUpDirs, } from "./path-utils.js";
-/** The one canonical PROJECT config file. Never deprecated. */
-export const CANONICAL_PROJECT_CONFIG_FILE = ".pi-lens.json";
-/** Basename of the one canonical GLOBAL config file inside `~/.pi-lens/`. */
-export const CANONICAL_GLOBAL_CONFIG_FILE = "config.json";
-/** The key the LSP namespace lives under in BOTH canonical files. */
-export const LSP_NAMESPACE_KEY = "lsp";
-/** The `~/` prefix a global row in the registry carries. */
-const GLOBAL_SURFACE_PREFIX = "~/.pi-lens/";
-const LEGACY_FILE_SURFACES = DEPRECATED_CONFIG_SURFACES.filter((row) => row.kind === "file").map((row) => row.surface);
-/**
- * The legacy LSP ROOT keys still accepted inside a canonical file. Derived from
- * the registry's `kind: "key"` rows so the accepted set and the deprecation
- * schedule cannot drift apart.
- */
-export const LEGACY_ROOT_LSP_KEYS = DEPRECATED_CONFIG_SURFACES.filter((row) => row.kind === "key").map((row) => row.surface);
-function isLspScoped(relativePath) {
-    const base = path.posix.basename(relativePath.replace(/\\/g, "/"));
-    return base === "lsp.json" || base === "pi-lsp.json";
-}
-function legacyLocation(relativePath, surface) {
-    return {
-        relativePath,
-        surface,
-        legacy: true,
-        lspScoped: isLspScoped(relativePath),
-    };
-}
-/**
- * Project locations in ASCENDING precedence: the canonical file is LAST, so it
- * wins every collision with a legacy file in the same directory.
- *
- * This inverts one pre-#2426 rule deliberately. `lsp/config.ts` searched
- * `.pi-lens/lsp.json`, `.pi-lens.json`, `pi-lsp.json` and took the FIRST hit,
- * so a leftover `.pi-lens/lsp.json` silently beat the file the user was being
- * told to migrate to. A deprecated location that outranks the canonical one is
- * a migration that can never be completed.
- */
-export const PROJECT_CONFIG_LOCATIONS = [
-    legacyLocation("pi-lens.json", "pi-lens.json"),
-    legacyLocation("pi-lsp.json", "pi-lsp.json"),
-    legacyLocation(path.posix.join(".pi-lens", "lsp.json"), ".pi-lens/lsp.json"),
-    {
-        relativePath: CANONICAL_PROJECT_CONFIG_FILE,
-        legacy: false,
-        lspScoped: false,
-    },
-];
-/**
- * The project config BASENAMES a first-match-wins probe uses, in DESCENDING
- * precedence — canonical first. The inverse view of the table above, for the
- * two callers that look for one file in one directory rather than layering all
- * of them: `project-lens-config.ts`'s upward walk and `workspace-topology.ts`'s
- * directory-marker index.
- *
- * Derived here rather than restated there. Both of those modules carried their
- * OWN literal pair before (#2426 folded the first one in; the marker index's
- * copy outlived it), and two hand-maintained lists of the same filenames is the
- * mirror the single-source-of-truth rule forbids — the failure mode being a
- * table change that flips one probe's collision winner and not the other's.
- *
- * The LSP-scoped legacy locations are filtered out: their ROOT keys are LSP
- * settings, not the pi-lens config sections these two probes project.
- */
-export const PROJECT_CONFIG_BASENAMES = PROJECT_CONFIG_LOCATIONS.filter((location) => !location.lspScoped)
-    .map((location) => location.relativePath)
-    .reverse();
-/** Global locations in ASCENDING precedence; canonical last, same rule. */
-export const GLOBAL_CONFIG_LOCATIONS = [
-    legacyLocation("lsp.json", `${GLOBAL_SURFACE_PREFIX}lsp.json`),
-    {
-        relativePath: CANONICAL_GLOBAL_CONFIG_FILE,
-        legacy: false,
-        lspScoped: false,
-    },
-];
-/**
- * Every legacy surface this module claims to read, for the registry-agreement
- * test. Exported rather than re-derived in the test, so the test compares the
- * SHIPPED set against the registry instead of comparing the registry to itself.
- */
-export const DECLARED_LEGACY_FILE_SURFACES = [
-    ...PROJECT_CONFIG_LOCATIONS,
-    ...GLOBAL_CONFIG_LOCATIONS,
-]
-    .filter((location) => location.legacy)
-    .map((location) => location.surface);
-/** The registry's own `kind: "file"` surfaces, for the same test. */
-export const REGISTERED_LEGACY_FILE_SURFACES = LEGACY_FILE_SURFACES;
-/**
- * Directories to look for a project config in, INNERMOST FIRST, stopping at the
- * `$HOME` ceiling.
- *
- * The ceiling is the whole point (#622/#625, #2426 scope item 1). `$HOME` and
- * every ancestor of it is refused, so a stray `pi-lsp.json` in the user's home
- * directory — or at the filesystem root — is not silently adopted by every
- * project on the machine. `isAtOrAboveHomeDir` is the shared primitive; a
- * private `dir === homedir()` check is the exact bug #625 catalogued, because
- * it stops at HOME but still reads everything above it.
- *
- * The MACHINE-GLOBAL config is not affected: it is read by absolute path from
- * `~/.pi-lens/`, never by walking into `$HOME` and finding it.
- */
-export function configSearchDirs(startDir, homeDir = os.homedir()) {
-    const dirs = [];
-    for (const dir of walkUpDirs(startDir)) {
-        if (isAtOrAboveHomeDir(dir, homeDir))
-            break;
-        dirs.push(dir);
-    }
-    return dirs;
-}
-function defaultGlobalConfigExists(file) {
-    try {
-        return fs.statSync(file).isFile();
-    }
-    catch (error) {
-        // ENOENT is the ordinary ABSENT answer the tier walk consumes. Any other
-        // stat failure (ENOTDIR when a file sits where a directory belongs,
-        // EACCES, ELOOP) propagates: the discriminated probe in
-        // `resolveGlobalConfigLocation` retains the errored tier instead of
-        // silently switching config sources (#3251 review H2, defect shape 48),
-        // and the load's read of the retained path is reported by the existing
-        // `PILENS_CFG_0001` seam.
-        if (error.code === "ENOENT")
-            return false;
-        throw error;
-    }
-}
-/**
- * The agent-dir config path for one `PI_CODING_AGENT_DIR` value, shared by the
- * resolution and the recognized-location set so the two can never spell the
- * same location differently.
- *
- * Shape-aware joining (defect shape 2): a Windows-shaped agent dir is joined
- * with `path.win32` regardless of host — the host-default `path.resolve` on
- * POSIX treats a drive-letter path as RELATIVE and mangles it, which made a
- * case-folded Windows spelling unmatchable (#3251 review M1).
- */
-function agentConfigPathFor(agentDir) {
-    return isWindowsPath(agentDir)
-        ? path.win32.join(path.win32.resolve(agentDir), "extensions", "pi-lens.json")
-        : path.join(path.resolve(agentDir), "extensions", "pi-lens.json");
-}
-/**
- * Resolve which file supplies the global config tier (see
- * `GlobalConfigLocationSource` for the order).
- *
- * Lives here rather than in `lens-config.ts` (#2426 review round 3, S1):
- * this module is the one that already states "WHERE pi-lens config lives",
- * and BOTH discovery seams that must refuse the resolved global path
- * (`project-lens-config.ts`, `workspace-topology.ts`) already import from
- * here — importing the resolver from `lens-config.ts` would close a cycle
- * (`lens-config.ts` itself imports from `project-lens-config.ts`).
- * `lens-config.ts` re-exports the accessors so its own, pre-existing import
- * sites are unaffected.
- */
-export function resolveGlobalConfigLocation(options) {
-    // An options object means the caller OWNS the resolution context (a test
-    // or explicitly-scoped caller): the ambient host env must not leak into it,
-    // or a test that resolves-then-writes "under its own home" lands in the
-    // maintainer's real config (dogfooded live: ambient PI_CODING_AGENT_DIR
-    // redirected a suite's writeConfig into ~/.config/pi/agent/extensions/
-    // pi-lens.json). Owned contexts therefore ignore PI_CODING_AGENT_DIR
-    // entirely; only the production resolution (no options) walks the
-    // host-relative tier. PI_LENS_HOME does not participate in this resolution
-    // at all — the canonical default keeps its released homedir spelling, and
-    // the #2457 split-brain (which concerns the machine root, not the config
-    // file) stays a separate issue.
-    const owned = options !== undefined;
-    const homeDir = options?.homeDir ?? os.homedir();
-    const legacyDefault = path.join(homeDir, ".pi-lens", CANONICAL_GLOBAL_CONFIG_FILE);
-    // Byte-compatible with the released override: any non-empty value wins,
-    // untrimmed, exactly as before.
-    const override = process.env.PI_LENS_CONFIG_PATH;
-    if (override) {
-        return { path: path.resolve(override), source: "pi-lens-config-path" };
-    }
-    // The probe is DISCRIMINATED (#3251 review H2, defect shape 48): "error"
-    // (ENOTDIR when a file sits where a directory belongs, EACCES, ELOOP) is
-    // NOT absent — the errored tier is RETAINED, so the load's read of that
-    // same path fails and the existing `reportConfigReadFailure` seam
-    // (`PILENS_CFG_0001`) reports it. Absorbing the error as ABSENT would
-    // silently select a lower tier: different user settings applying with no
-    // diagnostic, and the read seam would only ever see the finally-read path,
-    // never the probe that failed.
-    let probeError;
-    const probe = (file) => {
-        try {
-            return (options?.exists ?? defaultGlobalConfigExists)(file)
-                ? "present"
-                : "absent";
-        }
-        catch (error) {
-            // The caught error is carried to the retained tier's resolution so
-            // the loader's retention record can name the error CLASS (never
-            // the message, per the #2431/#2451 rule).
-            probeError = error;
-            return "error";
-        }
-    };
-    const agentDir = owned ? undefined : process.env.PI_CODING_AGENT_DIR?.trim();
-    const agentPath = agentDir ? agentConfigPathFor(agentDir) : undefined;
-    const legacyProbe = probe(legacyDefault);
-    if (legacyProbe === "present") {
-        if (agentPath !== undefined && probe(agentPath) === "present") {
-            return {
-                path: legacyDefault,
-                source: "legacy-default-existing",
-                shadowedPath: agentPath,
-            };
-        }
-        return { path: legacyDefault, source: "legacy-default-existing" };
-    }
-    if (legacyProbe === "error") {
-        // Fail closed at the location the probe could not evaluate: the file
-        // might exist, and switching sources would silently swap the user's
-        // settings. The subsequent read reports the failure (`PILENS_CFG_0001`),
-        // and the loader emits the probe-failed retention record.
-        return {
-            path: legacyDefault,
-            source: "legacy-default-unprobed",
-            existsProbeFailed: {
-                path: legacyDefault,
-                errorClassName: errorClassName(probeError),
-            },
-        };
-    }
-    if (agentPath !== undefined) {
-        const agentProbe = probe(agentPath);
-        if (agentProbe === "present") {
-            return { path: agentPath, source: "pi-coding-agent-dir" };
-        }
-        if (agentProbe === "error") {
-            // Same rule one tier down: the agent-dir identity is retained, and
-            // the read of it reports the failure rather than the resolution
-            // silently falling to the canonical default.
-            return {
-                path: agentPath,
-                source: "pi-coding-agent-dir-unprobed",
-                existsProbeFailed: {
-                    path: agentPath,
-                    errorClassName: errorClassName(probeError),
-                },
-            };
-        }
-    }
-    return { path: legacyDefault, source: "canonical-default" };
-}
-let memoizedGlobalConfigResolution;
-function globalConfigEnvFingerprint() {
-    return JSON.stringify([
-        process.env.PI_LENS_CONFIG_PATH,
-        process.env.PI_CODING_AGENT_DIR,
-    ]);
-}
-export function getProductionGlobalConfigResolution() {
-    const fingerprint = globalConfigEnvFingerprint();
-    if (memoizedGlobalConfigResolution?.fingerprint !== fingerprint) {
-        memoizedGlobalConfigResolution = {
-            fingerprint,
-            resolution: resolveGlobalConfigLocation(),
-        };
-    }
-    return memoizedGlobalConfigResolution.resolution;
-}
-/** Test-only: drop the memoized production resolution so the next call re-probes. */
-export function resetGlobalConfigLocationCache() {
-    memoizedGlobalConfigResolution = undefined;
-}
-/**
- * The absolute path of the canonical GLOBAL config (see
- * `GlobalConfigLocationSource` for the full resolution order).
- *
- * Lives here rather than in `lens-config.ts` (#2426 review round 3, S1),
- * which is where it originated: this module is the one that already states
- * "WHERE pi-lens config lives", and `project-lens-config.ts` needs this exact
- * function — not a re-derivation of `PI_LENS_CONFIG_PATH` — to name the file a
- * global-only setting belongs in. Importing it from `lens-config.ts` would
- * close a cycle, since `lens-config.ts` itself imports from
- * `project-lens-config.ts`. `lens-config.ts` re-exports this so its own,
- * pre-existing import sites are unaffected.
- */
-export function getPiLensGlobalConfigPath(homeDir) {
-    return homeDir === undefined
-        ? getProductionGlobalConfigResolution().path
-        : resolveGlobalConfigLocation({ homeDir }).path;
-}
-/**
- * Whether `candidate` matches ANY location the global config tier recognizes —
- * the resolved file, the legacy default, and the agent-dir target.
- *
- * The one predicate every project-config discovery seam consults before it
- * adopts a candidate (#783's nested layering, the upward walk, and the
- * workspace marker index): a file the global tier recognizes must not be
- * discovered a second time as a project config — the discovery loader would
- * full-validate it, ignore every global-only key in it, and advise the user
- * to set those keys in the very file it is ignoring. The check covers the
- * POTENTIAL set, not just whichever file currently won the read: a second
- * recognized file that exists but lost the tier walk (the grandfathered
- * legacy file beside an adopted agent-dir file, say) is equally not a project
- * config.
- *
- * Comparison is alias-anchored on BOTH sides (#3251 review M1 round 2):
- * each path is canonicalized through `realpathOrResolve` (resolving existing
- * symlink aliases; a nonexistent path falls back to its resolved spelling —
- * the documented fallback) and then `normalizeFilePath` (separator-agnostic,
- * case-insensitive on Windows, casing-adoption). A symlinked-home alias of a
- * recognized location is therefore the same identity as its real spelling,
- * and a case-folded or separator-differing Windows spelling cannot dodge the
- * refusal either.
- */
-export function isResolvedGlobalConfigPath(candidate) {
-    return recognizedGlobalConfigPaths().has(canonicalPathIdentity(candidate));
-}
-/**
- * Canonical path identity for one candidate: realpath-anchored so an
- * existing symlink alias resolves to the same identity as its real spelling
- * (#3251 review M1 round 2), with `realpathOrResolve`'s documented
- * nonexistent-path fallback (the resolved spelling, dot-folded and
- * case-normalized by `normalizeFilePath` — which pays its own `realpath`
- * only when the path exists). The discovery seams consult this predicate
- * per config candidate, and the env-derived recognized set is canonicalized
- * with the SAME helper once per env fingerprint, so both sides of the
- * comparison share one identity function.
- */
-export function canonicalPathIdentity(candidate) {
-    // Shape-aware (defect shape 2): a Windows-shaped path is resolved with
-    // `path.win32` — the host resolver on POSIX treats a drive-letter path as
-    // RELATIVE and mangles it before any comparison could run. On a real
-    // Windows host this arm is the native one, and `normalizeFilePath`'s
-    // Windows branch does the alias resolution itself (realpathSync.native
-    // plus canonical-casing adoption).
-    if (isWindowsPath(candidate)) {
-        return normalizeFilePath(path.win32.resolve(candidate));
-    }
-    return normalizeFilePath(realpathOrResolve(candidate));
-}
-let recognizedCache;
-function recognizedGlobalConfigPaths() {
-    const fingerprint = globalConfigEnvFingerprint();
-    if (recognizedCache?.fingerprint !== fingerprint) {
-        const paths = new Set();
-        const override = process.env.PI_LENS_CONFIG_PATH;
-        if (override)
-            paths.add(canonicalPathIdentity(path.resolve(override)));
-        paths.add(canonicalPathIdentity(path.join(os.homedir(), ".pi-lens", CANONICAL_GLOBAL_CONFIG_FILE)));
-        const agentDir = process.env.PI_CODING_AGENT_DIR?.trim();
-        if (agentDir)
-            paths.add(canonicalPathIdentity(agentConfigPathFor(agentDir)));
-        recognizedCache = { fingerprint, paths };
-    }
-    return recognizedCache.paths;
-}