@herbertgao/pi-extensions 2026.9.0 → 2026.9.2

package/node_modules/pi-lens/dist/clients/config-core/schema.js

@@ -0,0 +1,165 @@
+/**
+ * The schema representation the config core reads (#2425).
+ *
+ * A schema here is a PLAIN JSON-Schema-shaped object, not a compiled validator
+ * object and not a TypeBox/Zod value. That is a deliberate constraint, not
+ * laziness: #2416 publishes the same object as `docs/schema/pi-lens-config-v1.json`
+ * and its drift test compares the published artifact against the object the
+ * runtime validates with. Two representations would need a compiler between
+ * them, and a compiler is exactly the place drift hides.
+ *
+ * Three pi-lens annotations extend the vocabulary, all `x-`-prefixed so a
+ * standard JSON Schema validator ignores them:
+ *
+ * - `x-stability` — the #2418 tier every published property carries. Owned by
+ *   `clients/config-diagnostic-codes.ts`; re-exported here only as the key, so
+ *   a schema author has one import.
+ * - `x-merge-strategy` — how an ARRAY node combines across tiers. Objects are
+ *   always merged field-wise, so the annotation is meaningless on them.
+ * - `x-deny` — the node carries a denial, and `deny.ts` gives it monotonic
+ *   precedence instead of last-tier-wins.
+ *
+ * Pure accessors only. Nothing here reads a file, and nothing holds state.
+ */
+/** Narrows to the recursive domain type, not to `unknown`. */
+export function isConfigObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// --- x-merge-strategy ---
+/** The annotation key selecting how an array node combines across tiers. */
+export const MERGE_STRATEGY_KEY = "x-merge-strategy";
+const DEFAULT_MERGE_STRATEGY = "replace";
+const KEYED_PREFIX = "keyed:";
+export function isMergeStrategy(value) {
+    if (typeof value !== "string")
+        return false;
+    if (value === "replace" || value === "append")
+        return true;
+    return value.startsWith(KEYED_PREFIX) && value.length > KEYED_PREFIX.length;
+}
+/**
+ * The declared strategy for a node, or the default.
+ *
+ * An UNRECOGNIZED annotation value falls back to `replace` rather than throwing.
+ * The default is the conservative one: replace never silently unions entries a
+ * nearer tier meant to supersede, so a typo in a schema degrades to the safe
+ * shape. Schema typos are caught by the #2416 drift test, not at resolve time.
+ */
+export function mergeStrategyOf(node) {
+    const declared = node?.[MERGE_STRATEGY_KEY];
+    return isMergeStrategy(declared) ? declared : DEFAULT_MERGE_STRATEGY;
+}
+/** The field name a `keyed:<field>` strategy matches on, else `undefined`. */
+export function keyedField(strategy) {
+    return strategy.startsWith(KEYED_PREFIX)
+        ? strategy.slice(KEYED_PREFIX.length)
+        : undefined;
+}
+// --- x-deny ---
+/** The annotation key marking a node as carrying a denial. */
+export const DENY_KEY = "x-deny";
+/**
+ * How a node expresses a denial.
+ *
+ * - `boolean-false` — a boolean whose `false` denies. `enabled: false`.
+ * - `array-union` — a list whose MEMBERS are denials. `disabledServers`.
+ *
+ * Annotation-driven rather than name-driven on purpose. A heuristic over field
+ * names ("anything called `disabled*`") is defect shape 8: it silently misses
+ * the field someone spelled differently, and silently claims one that merely
+ * looks the part. A schema says what it means.
+ */
+const DENY_POLICIES = ["boolean-false", "array-union"];
+export function isDenyPolicy(value) {
+    return (typeof value === "string" &&
+        DENY_POLICIES.includes(value));
+}
+/** The declared deny policy for a node, or `undefined` when it carries none. */
+export function denyPolicyOf(node) {
+    const declared = node?.[DENY_KEY];
+    return isDenyPolicy(declared) ? declared : undefined;
+}
+// --- structural accessors ---
+export function isSchemaNode(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The declared `type` keyword, when it is a single string. */
+export function schemaType(node) {
+    const declared = node?.type;
+    return typeof declared === "string" ? declared : undefined;
+}
+/**
+ * The `type` keywords the core knows how to act on.
+ *
+ * An unrecognized keyword is the SCHEMA's problem, not the user's, and both
+ * halves of the pipeline treat it identically: the node is opaque, so the walk
+ * dispatches on the value's own shape instead of on a word it cannot read
+ * (#2440 review). Asking `schemaType(node) !== undefined` was the older,
+ * asymmetric test — it let the validator walk a `type: "widget"` node field by
+ * field while the merger replaced it whole, so the same schema typo produced
+ * two different merge semantics.
+ */
+const SCHEMA_TYPES = [
+    "object",
+    "array",
+    "string",
+    "number",
+    "integer",
+    "boolean",
+    "null",
+];
+const SCHEMA_TYPE_SET = new Set(SCHEMA_TYPES);
+/** True when the node declares a `type` keyword the core acts on. */
+export function isKnownSchemaType(declared) {
+    return declared !== undefined && SCHEMA_TYPE_SET.has(declared);
+}
+/**
+ * The subschema governing property `name`: its `properties` entry, else the
+ * first `patternProperties` entry whose regex matches.
+ *
+ * A malformed pattern is skipped rather than thrown: a schema is data, and one
+ * bad regex must not take down every config load that touches the file.
+ */
+export function propertySchema(node, name) {
+    if (!node)
+        return undefined;
+    const properties = node.properties;
+    if (isSchemaNode(properties) && Object.hasOwn(properties, name)) {
+        const child = properties[name];
+        if (isSchemaNode(child))
+            return child;
+    }
+    const patterns = node.patternProperties;
+    if (isSchemaNode(patterns)) {
+        for (const [pattern, child] of Object.entries(patterns)) {
+            if (!isSchemaNode(child))
+                continue;
+            let matcher;
+            try {
+                matcher = new RegExp(pattern);
+            }
+            catch {
+                continue;
+            }
+            if (matcher.test(name))
+                return child;
+        }
+    }
+    return undefined;
+}
+export function additionalPropertyPolicy(node) {
+    const declared = node?.additionalProperties;
+    if (declared === true)
+        return { kind: "keep" };
+    if (isSchemaNode(declared))
+        return { kind: "validate", schema: declared };
+    return { kind: "drop" };
+}
+/** The `items` subschema of an array node, when it is a single schema. */
+export function itemsSchema(node) {
+    const declared = node?.items;
+    return isSchemaNode(declared) ? declared : undefined;
+}

package/node_modules/pi-lens/dist/clients/config-diagnostic-codes.js

@@ -0,0 +1,281 @@
+/**
+ * The stability registry for pi-lens's PUBLIC config surfaces (#2418).
+ *
+ * At ~28k downloads/month a config field or a warning string becomes a
+ * compatibility obligation the moment it ships. This module is the one place
+ * that obligation is written down as DATA, so the policy in
+ * `docs/public-api-stability.md` is enforceable by test rather than by
+ * convention:
+ *
+ * - `STABILITY_TIERS` / `STABILITY_TIER_KEY` — the `x-stability` annotation
+ *   every published schema property must carry. New fields default to
+ *   `experimental`; only `stable` fields are covered by the compatibility
+ *   guarantee. Promotion is a deliberate, changelogged act.
+ * - `CONFIG_SCHEMA_ID` / `CONFIG_SCHEMA_ANCHOR_KEY` — the reserved schema
+ *   identity anchor the unified config envelope carries from its first
+ *   published version (#2416 populates it; nothing here emits config).
+ * - `CONFIG_DIAGNOSTIC_CODES` — a closed, APPEND-ONLY namespace of stable
+ *   codes for user-facing config validation and migration warnings, so a user
+ *   can match or suppress on `PILENS_CFG_0001` instead of on prose. Message
+ *   text may change freely; codes may never be renumbered or removed.
+ * - `DEPRECATED_CONFIG_SURFACES` — the deprecation window (`deprecatedSince` /
+ *   `removeNotBefore`) for every legacy config key and file location that is
+ *   still read. Removal happens only in a major, through the documented
+ *   breaking-change checklist.
+ *
+ * Deliberately DEPENDENCY-FREE: this is a data leaf imported by the config
+ * loaders, the degradation ledger seam, and the governance tests. It must
+ * never grow an import on a module that itself reports config diagnostics.
+ */
+// --- Field stability tiers (policy point 1) ---
+/** The JSON Schema annotation key carrying a field's stability tier. */
+export const STABILITY_TIER_KEY = "x-stability";
+/**
+ * The closed tier vocabulary. `experimental` fields may change or be removed
+ * in a minor; `stable` fields are covered by the compatibility guarantee.
+ */
+const STABILITY_TIERS = ["experimental", "stable"];
+export function isStabilityTier(value) {
+    return (typeof value === "string" &&
+        STABILITY_TIERS.includes(value));
+}
+// --- Config envelope identity (policy point 3) ---
+/**
+ * The reserved `$schema` URL for the unified pi-lens config envelope. Pinned
+ * here from the first published version so the identity anchor cannot drift
+ * between the schema, the validator, and the docs. #2416 is the first consumer.
+ */
+export const CONFIG_SCHEMA_ID = "https://raw.githubusercontent.com/apmantza/pi-lens/master/docs/schema/pi-lens-config-v1.json";
+/** The envelope key carrying `CONFIG_SCHEMA_ID` in a user's config file. */
+export const CONFIG_SCHEMA_ANCHOR_KEY = "$schema";
+// --- Stable config diagnostic codes (policy point 2) ---
+/**
+ * APPEND-ONLY. Add new codes at the end with the next number; never renumber,
+ * never delete, never reuse a retired number. A retired code keeps its entry
+ * with its description amended — `tests/clients/config-diagnostic-codes.test.ts`
+ * pins the full list and goes red on any renumber or removal.
+ */
+export const CONFIG_DIAGNOSTIC_CODES = {
+    /**
+     * A config file exists but could not be read or parsed, so it is ignored.
+     *
+     * EMITTED, by `warnIgnoredConfigOnce` (`clients/config-warn.ts`) — the one
+     * seam behind all three config loaders. It rides the user-facing message as
+     * a ` [PILENS_CFG_0001]` suffix AND the durable `config-ignored`
+     * degradation row, so the code a user greps for in the terminal is the same
+     * one in `latency.log`.
+     */
+    PILENS_CFG_0001: "config file unreadable or unparsable; ignored",
+    /**
+     * A deprecated config KEY was accepted inside its deprecation window.
+     *
+     * EMITTED since #2426, by `deprecationRecords` (`clients/config-resolve.ts`)
+     * for every `kind: "key"` row below that appears at the ROOT of a canonical
+     * file — one record per `(file, key)` — and delivered through
+     * `reportPiLensConfigRecords` -> `warnIgnoredConfigOnce`, which renders it as
+     * `deprecated <label> key in <file>: …` and records a `config-deprecated`
+     * ledger row rather than a `config-ignored` one. The setting still APPLIES;
+     * the code says only that the spelling is on a removal schedule.
+     *
+     * The record carries `canonicalKey`, so the auto-migrator #2426 defers can
+     * be a pure function over these records rather than a prose parser.
+     */
+    PILENS_CFG_0002: "deprecated config key accepted",
+    /**
+     * A deprecated config FILE LOCATION was read inside its window.
+     *
+     * EMITTED since #2426 — same producer, same delivery path, and the same
+     * one-record-per-`(file, key)` granularity as `PILENS_CFG_0002`; this is the
+     * code for the `kind: "file"` rows below. Per-key rather than per-file so the
+     * warning can name the destination of each setting the user has to move.
+     */
+    PILENS_CFG_0003: "deprecated config file location accepted",
+    /**
+     * A config field no schema property claims was dropped.
+     *
+     * PRODUCED by `validate()` (`clients/config-core/normalize.ts`), which is
+     * the one place the unknown-field policy in `docs/public-api-stability.md`
+     * is implemented: warn and drop, never throw. It reaches a user through
+     * `reportPiLensConfigRecords` -> `warnIgnoredConfigOnce`, which #2426 wires
+     * when the loaders adopt the core. Registered now because the resolution
+     * pipeline already stamps records with it, and a record carrying an
+     * unregistered code is exactly what the #2418 drift test forbids.
+     */
+    PILENS_CFG_0004: "unknown config field ignored",
+    /**
+     * A config field's value did not match its schema and was dropped.
+     *
+     * Wrong type, a value outside a declared `enum`, or a nesting depth past the
+     * validator's bound. Same producer and same delivery path as
+     * `PILENS_CFG_0004`. Kept distinct from it because the two need different
+     * user actions: an unknown field is usually a typo or a removed key, while a
+     * rejected value is a field the user meant and spelled wrongly.
+     */
+    PILENS_CFG_0005: "config field value rejected by schema; ignored",
+    /**
+     * A config KEY that would have modified an object's prototype was refused.
+     *
+     * `__proto__`, `constructor`, `prototype`. PRODUCED by both halves of the
+     * config core (`normalize.ts` when validating, `merge.ts` when combining
+     * tiers), through the shared policy in `config-core/safe-object.ts`.
+     *
+     * Kept distinct from `PILENS_CFG_0004` even though both describe a dropped
+     * key, because the two mean different things to whoever reads the warning: an
+     * unknown field is a typo the user should fix, while this one is a key no
+     * pi-lens config can ever legitimately carry. A user who sees it in their own
+     * hand-written file has a mistake; a user who sees it naming a file they did
+     * not write has something worth looking at.
+     */
+    PILENS_CFG_0006: "config key would modify the object prototype; ignored",
+    /**
+     * Further config notices were suppressed by a per-resolution bound.
+     *
+     * The record count a config file can produce is USER INPUT — one key, one
+     * record — so every producer collects into a bounded
+     * `MigrationRecordCollector` through `finalizeRecords`, which holds one slot
+     * back for this code. It is the difference between a bound that is honest
+     * and one that drops notices silently: a user who sees it knows the list
+     * they were shown is partial, and how much of it is missing. The count is
+     * the WHOLE truncation, including anything an earlier bound in the same
+     * pipeline already discarded (#2426 review round 6, F1).
+     *
+     * Registered as its own code rather than folded into `PILENS_CFG_0001`
+     * because the user action differs — nothing about the config is wrong, the
+     * OUTPUT was truncated, and the fix is to read the file rather than to
+     * change it. For the same reason it is the ONE code `warnIgnoredConfigOnce`
+     * renders with neither the `ignoring invalid …` prose nor the
+     * `config-ignored` ledger kind: it records under `config-notice-suppressed`,
+     * because a file whose every setting applied can still overflow the bound.
+     */
+    PILENS_CFG_0007: "further config notices suppressed by the per-resolution bound",
+    /**
+     * A WHOLE configuration was dropped because resolving it failed internally.
+     *
+     * PRODUCED by the two guards that stand under the config pipeline —
+     * `resolveConfig` (`clients/config-core/resolve.ts`) and the global loader's
+     * post-parse catch (`clients/lens-config.ts`) — each of which degrades a
+     * failed resolution to "no config" rather than taking the session with it.
+     * The record carries the error CLASS only, never its message.
+     *
+     * Distinct from `PILENS_CFG_0005`, which both guards borrowed until #2426
+     * review round 6 (S1). 0005 is registered as a per-FIELD rejection: a user
+     * who matches on it expects one setting to have been dropped and the rest to
+     * be in effect. Here NOTHING in the file is in effect, so the two need
+     * different codes to be worth matching on at all.
+     *
+     * The ONE code the per-resolution bound never suppresses (#2426 review round
+     * 7, F1). Every other record is one more per-key notice, and past 20 of
+     * those a count is worth more than the list; this record is the statement
+     * that those notices are no longer the whole story, so letting a
+     * `PILENS_CFG_0007` stand in for it told the user "19 keys rejected, N more
+     * suppressed" about a configuration that applied nothing at all.
+     */
+    PILENS_CFG_0008: "config resolution failed; whole configuration ignored",
+};
+/** The shape every code in the namespace must match. */
+export const CONFIG_DIAGNOSTIC_CODE_PATTERN = /^PILENS_CFG_\d{4}$/;
+export function isConfigDiagnosticCode(value) {
+    return (typeof value === "string" && Object.hasOwn(CONFIG_DIAGNOSTIC_CODES, value));
+}
+/** The registered description for a code, or `undefined` when unregistered. */
+export function getConfigDiagnosticCode(code) {
+    return isConfigDiagnosticCode(code)
+        ? CONFIG_DIAGNOSTIC_CODES[code]
+        : undefined;
+}
+/**
+ * The user-visible marker appended to a coded message: ` [PILENS_CFG_0001]`.
+ * Kept as a bracketed suffix so it is greppable and suppressible without
+ * depending on any prose before it.
+ */
+export function configDiagnosticMarker(code) {
+    return `[${code}]`;
+}
+/** Append a code marker to a message, unless the message already carries it. */
+export function withConfigDiagnosticCode(message, code) {
+    const marker = configDiagnosticMarker(code);
+    return message.includes(marker) ? message : `${message} ${marker}`;
+}
+/** Matches the marker suffix in rendered messages (capture group 1 = code). */
+export const CONFIG_DIAGNOSTIC_MARKER_PATTERN = /\[(PILENS_CFG_\d{4})\]/;
+/**
+ * The legacy config surfaces pi-lens still reads. Each row commits to being
+ * read for one deprecation window and then ACTUALLY removed at
+ * `removeNotBefore` — legacy sources are not carried forever. Removal routes
+ * through the #2372 slice-5 breaking-change plan, which instantiates the
+ * checklist in `docs/public-api-stability.md`.
+ *
+ * The consolidation slice (#2426) blesses exactly two canonical locations:
+ * `.pi-lens.json` (project) and `~/.pi-lens/config.json` (global). Neither
+ * appears here, and that is the point: a CANONICAL FILE IS NOT DEPRECATED
+ * BECAUSE SOME OF ITS KEYS ARE. `.pi-lens.json` keeps being read forever; what
+ * is deprecated is the legacy top-level LSP keys inside it (`servers`,
+ * `serverOverrides`, `disabledServers`, `warmFiles`), which are the
+ * `kind: "key"` rows below. Listing the file itself would have promised users
+ * that the file they were just told to migrate TO is going away.
+ */
+/**
+ * The window every surface below shares. One window, not eight copies: the
+ * whole point of policy point 4 is that a deprecation is announced ONCE and
+ * removed at ONE major, so a per-row date is an invitation to drift. Spelling
+ * it once also means the S3 rule — `deprecatedSince` is the release that
+ * announces, never one that already shipped — has a single place to be wrong.
+ */
+const LSP_DEPRECATION_WINDOW = {
+    deprecatedSince: "4.1.4",
+    removeNotBefore: "5.0.0",
+};
+/** A legacy top-level LSP KEY inside a config file that is itself canonical. */
+const LEGACY_KEY = {
+    kind: "key",
+    code: "PILENS_CFG_0002",
+    ...LSP_DEPRECATION_WINDOW,
+};
+/** A legacy config FILE LOCATION that a loader still reads. */
+const LEGACY_FILE = {
+    kind: "file",
+    code: "PILENS_CFG_0003",
+    ...LSP_DEPRECATION_WINDOW,
+};
+export const DEPRECATED_CONFIG_SURFACES = [
+    {
+        ...LEGACY_KEY,
+        surface: "servers",
+        reason: "custom-server definitions move to the unified catalog schema; the bare string command + args form is replaced by the trust-gated ProcessSpec (#2416).",
+    },
+    {
+        ...LEGACY_KEY,
+        surface: "serverOverrides",
+        reason: "per-server initializationOptions overrides fold into the catalog's field-wise merge, keyed by the same public server IDs (#2416).",
+    },
+    {
+        ...LEGACY_KEY,
+        surface: "disabledServers",
+        reason: "replaced by the catalog's per-entry `enabled: false`, which carries monotonic deny precedence (#1416/#2415).",
+    },
+    {
+        ...LEGACY_KEY,
+        surface: "warmFiles",
+        reason: "session warm-up seeds become a per-server catalog field rather than a config-root list (#2416).",
+    },
+    {
+        ...LEGACY_FILE,
+        surface: ".pi-lens/lsp.json",
+        reason: "project LSP settings consolidate into `.pi-lens.json` under the unified envelope (#2426).",
+    },
+    {
+        ...LEGACY_FILE,
+        surface: "pi-lsp.json",
+        reason: "pre-rename project location; superseded by `.pi-lens.json` (#2426).",
+    },
+    {
+        ...LEGACY_FILE,
+        surface: "pi-lens.json",
+        reason: "undotted project-config basename; superseded by `.pi-lens.json` (#2426).",
+    },
+    {
+        ...LEGACY_FILE,
+        surface: "~/.pi-lens/lsp.json",
+        reason: "global LSP settings consolidate into `~/.pi-lens/config.json` (#2426).",
+    },
+];

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

@@ -0,0 +1,160 @@
+/**
+ * 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 plus one walk. No file reads, no caching, no state.
+ */
+import * as os from "node:os";
+import * as path from "node:path";
+import { DEPRECATED_CONFIG_SURFACES } from "./config-diagnostic-codes.js";
+import { isAtOrAboveHomeDir, 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;
+}
+/**
+ * The absolute path of the canonical GLOBAL config — `~/.pi-lens/config.json`,
+ * or `PI_LENS_CONFIG_PATH` when it overrides that.
+ *
+ * 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 = os.homedir()) {
+    const override = process.env.PI_LENS_CONFIG_PATH;
+    if (override)
+        return path.resolve(override);
+    return path.join(homeDir, ".pi-lens", CANONICAL_GLOBAL_CONFIG_FILE);
+}