@herbertgao/pi-extensions 2026.10.1 → 2026.10.3

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

@@ -1,798 +0,0 @@
-/**
- * The ONE config resolution path (#2426).
- *
- * Every pi-lens config file — canonical or legacy, project or global — is read,
- * validated and layered here, through `config-core`'s `resolveConfig` over the
- * canonical schema in `config-schema.ts`. The three exported loaders
- * (`loadLSPConfig`, `loadPiLensGlobalConfig`, `loadPiLensProjectConfig`) keep
- * their names and return types and become PROJECTIONS of what this module
- * resolves, so their ~20 call sites are untouched.
- *
- * THE DOCUMENTED LOOKUP ORDER, lowest precedence first:
- *
- *   builtin -> global -> project root -> nested-project -> env -> cli -> host
- *
- * It is `config-core`'s own `SOURCE_TIERS`, not a second ordering: this
- * module places files into tiers and the core sorts them. `docs/configuration.md`
- * documents the same order once, and `tests/clients/config-resolve.test.ts`
- * walks it.
- *
- * Only THREE of those tiers are populated here — `global`, `project` and
- * `nested-project` — because those are the tiers config FILES live in.
- * `builtin`, `env`, `cli` and `host` are reserved (#2427 wires env/CLI, #2416
- * the host tier); today's env vars and CLI flags reach a setting through their
- * own accessors, and `docs/configuration.md` states that precedence rather than
- * implying this resolution already carries it.
- *
- * WITHIN a tier, the canonical file is added LAST and therefore wins, because
- * `merge` keeps caller order on a precedence tie. That is the whole deprecation
- * story in one line: a legacy file is still read, and it loses to the file the
- * user is being told to move to.
- *
- * LEGACY ROOT LSP KEYS ARE NORMALIZED INTO THE `lsp` NAMESPACE HERE, at source
- * injection, and nowhere else (#2427 review round 2, F1). Every LSP setting has
- * two spellings during the deprecation window — `disabledServers` at a
- * document's root and `lsp.disabledServers` inside it — and leaving both in
- * place gave the schema TWO nodes for one setting. `merge()` then resolved each
- * node independently: two deny unions that never saw each other's tiers, and
- * two object merges that never saw each other's entries. A projection could
- * only pick one, and picking the canonical one meant a global denial written in
- * the legacy spelling disappeared the moment any project file mentioned the
- * canonical one — the operator-denial-lifted-by-repository-content defect
- * #2415 AC 3 forbids, arriving through the migration instead of through the
- * merge strategy.
- *
- * An earlier draft rejected this rewrite because it would inject an `lsp` key
- * into `PiLensProjectConfig.raw` that was never in the user's file. That
- * objection is why the normalization lives HERE and not in
- * `resolveOnePiLensConfigDocument`: `.raw` comes from the single-document path,
- * which still merges a document exactly as written. Only this multi-document
- * resolution — whose two consumers are `loadLSPConfig` and `effectiveConfig`,
- * both of which read the `lsp` section and nothing else — normalizes.
- *
- * The mapping is `canonicalKeyFor`'s, the one the deprecation records already
- * publish, so "where does this key move to" is answered once. Within a single
- * document the canonical spelling still wins a collision, which is the rule
- * `lspSectionOf` used to apply at projection time; across documents `merge()`
- * now applies the ordinary tier precedence and the deny union to ONE node.
- */
-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 { CANONICAL_GLOBAL_CONFIG_FILE, CANONICAL_PROJECT_CONFIG_FILE, GLOBAL_CONFIG_LOCATIONS, isResolvedGlobalConfigPath, LEGACY_ROOT_LSP_KEYS, LSP_NAMESPACE_KEY, PROJECT_CONFIG_LOCATIONS, configSearchDirs, } from "./config-locations.js";
-// The core's halves are imported directly rather than through
-// `config-core/index.js` (#2426). The barrel re-exports the whole vocabulary
-// including `process-spec.js`, which reaches `project-trust.js` and the
-// degradation ledger; a module that only resolves a config has no use for that
-// and, sitting downstream of `file-utils.ts` as every config loader does, would
-// close three import cycles by importing it. `resolveConfig` is still the one
-// supported way into the pipeline — `merge()` is deliberately not imported here.
-import { resolveConfig } from "./config-core/resolve.js";
-import { finalizeRecords, migrationSubject, } from "./config-core/records.js";
-import { SOURCE_TIERS, } from "./config-core/provenance.js";
-import { PI_LENS_CONFIG_SCHEMA } from "./config-schema.js";
-import { normalizeParseErrorReason, warnIgnoredConfigOnce, } from "./config-warn.js";
-import { homeRelativePath } from "./path-utils.js";
-/**
- * Read and JSON-parse one config file.
- *
- * Deliberately does NOT warn: the three loaders each render their own prose
- * (`ignoring invalid LSP config …` / `… global config …` / `… project config …`)
- * and their tests assert on it, so the decision of what to say about a bad file
- * stays with the loader while the reading itself is shared.
- */
-export function readConfigDocument(file) {
-    let text;
-    try {
-        text = fs.readFileSync(file, "utf-8");
-    }
-    catch (error) {
-        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-            return { status: "missing" };
-        }
-        return { status: "error", error };
-    }
-    try {
-        return { status: "ok", value: JSON.parse(text) };
-    }
-    catch (error) {
-        return { status: "error", error, sourceText: text };
-    }
-}
-/**
- * The canonical GLOBAL config path this resolution uses — for READING it and
- * for naming it in a migration notice, from one expression (#2426 review round
- * 2, F1).
- *
- * The two used to be computed separately: the read came from
- * `options.globalConfigPath` (`getPiLensGlobalConfigPath()`, `$HOME`-derived
- * unless `PI_LENS_CONFIG_PATH` overrides it) while the notice was recomputed as
- * `dirname(<legacy file>) + config.json` — and the legacy file lives under
- * `getGlobalPiLensDir()`, which `PI_LENS_HOME` relocates. Set `PI_LENS_HOME`
- * without `PI_LENS_CONFIG_PATH` and the two diverge, so the notice named a file
- * the resolver never reads: a user who followed it moved their settings into a
- * file that does nothing. Deriving both from here makes "the path we name" and
- * "the path we read" the same value by construction rather than by agreement.
- */
-function canonicalGlobalFile(options) {
-    if (options.globalConfigPath !== undefined)
-        return options.globalConfigPath;
-    return options.globalDir === undefined
-        ? undefined
-        : path.join(options.globalDir, CANONICAL_GLOBAL_CONFIG_FILE);
-}
-function collectDocuments(dir, locations, tier, onReadError) {
-    const documents = [];
-    for (const location of locations) {
-        const file = path.join(dir, location.relativePath);
-        // The global tier reads its file by absolute path; a candidate that IS
-        // that file is refused rather than adopted as a project/nested-project
-        // document, which would double-read and double-validate it
-        // (global-config-location PR, refs #2457).
-        if (tier !== "global" && isResolvedGlobalConfigPath(file))
-            continue;
-        const outcome = readConfigDocument(file);
-        if (outcome.status === "missing")
-            continue;
-        if (outcome.status === "error") {
-            onReadError?.({
-                file,
-                location,
-                tier,
-                error: outcome.error,
-                sourceText: outcome.sourceText,
-            });
-            continue;
-        }
-        documents.push({ tier, file, location, value: outcome.value });
-    }
-    return documents;
-}
-/**
- * Assemble every config document for a resolution, lowest precedence first.
- *
- * The project walk is ceiling-bounded by `configSearchDirs`. The OUTERMOST
- * config-bearing directory is the `project` tier and everything nearer the cwd
- * is `nested-project`, which is what makes "nearest wins, per field" fall out
- * of the core's tier precedence instead of being re-implemented here.
- */
-function collectPiLensConfigDocuments(options) {
-    const documents = [];
-    const { globalDir, onReadError } = options;
-    const globalConfigPath = canonicalGlobalFile(options);
-    if (globalDir !== undefined || globalConfigPath !== undefined) {
-        for (const location of GLOBAL_CONFIG_LOCATIONS) {
-            const file = location.relativePath === CANONICAL_GLOBAL_CONFIG_FILE
-                ? globalConfigPath
-                : globalDir === undefined
-                    ? undefined
-                    : path.join(globalDir, location.relativePath);
-            if (file === undefined)
-                continue;
-            const outcome = readConfigDocument(file);
-            if (outcome.status === "missing")
-                continue;
-            if (outcome.status === "error") {
-                onReadError?.({
-                    file,
-                    location,
-                    tier: "global",
-                    error: outcome.error,
-                    sourceText: outcome.sourceText,
-                });
-                continue;
-            }
-            documents.push({ tier: "global", file, location, value: outcome.value });
-        }
-    }
-    if (options.cwd !== undefined) {
-        // Innermost first from the walk; reversed so the OUTERMOST directory is
-        // emitted first and lands in the lower-precedence `project` tier.
-        const dirs = configSearchDirs(options.cwd, options.homeDir ?? os.homedir()).reverse();
-        const bearing = dirs
-            .map((dir) => ({
-            dir,
-            found: collectDocuments(dir, PROJECT_CONFIG_LOCATIONS, "project", onReadError),
-        }))
-            .filter((entry) => entry.found.length > 0);
-        bearing.forEach((entry, index) => {
-            const tier = index === 0 ? "project" : "nested-project";
-            for (const document of entry.found)
-                documents.push({ ...document, tier });
-        });
-    }
-    return documents;
-}
-/** A zero for every tier, so a consumer never has to test for an absent key. */
-function emptyTierCounts() {
-    return Object.fromEntries(SOURCE_TIERS.map((tier) => [tier, 0]));
-}
-/**
- * Project a resolution onto its redacted summary.
- *
- * Values never appear: a document contributes its PATH (home-relative), its
- * tier and its legacy flag, and nothing else — the same structural redaction
- * `pilens_effective_config` applies, spelled once rather than twice (rule 3 of
- * `clients/effective-config.ts`: the redacted view is the only view).
- *
- * Pure and synchronous: it reads a resolution the caller already performed and
- * resolves nothing itself, so no caller can turn "report what we resolved"
- * into a second walk of the config tree (#2513's facade rule).
- */
-export function summarizeConfigResolution(resolution, homeDir) {
-    const countsByTier = emptyTierCounts();
-    for (const entry of resolution.provenance.values()) {
-        countsByTier[entry.tier] += 1;
-    }
-    return {
-        documents: resolution.documents.map((document) => ({
-            tier: document.tier,
-            file: homeRelativePath(document.file, homeDir),
-            legacy: document.location.legacy,
-        })),
-        countsByTier,
-        recordCount: resolution.records.length,
-    };
-}
-/** Resolve every discovered document into one configuration. */
-export function resolvePiLensConfig(options) {
-    const documents = collectPiLensConfigDocuments(options);
-    const sources = configSources(documents);
-    const resolution = resolveConfig({
-        sources,
-        schema: PI_LENS_CONFIG_SCHEMA,
-    });
-    return {
-        value: resolution.resolved.value ?? {},
-        provenance: resolution.resolved.provenance,
-        records: finalizeRecords([
-            ...resolution.records,
-            ...deprecationRecords(documents, options.homeDir ?? os.homedir(), canonicalGlobalFile(options)),
-        ], documentAnchor(documents), 
-        // The core ALREADY truncated (#2426 review round 6, F1). Its drop count
-        // is seeded here so the one `PILENS_CFG_0007` a user reads names the
-        // whole truncation rather than the part this bound performed.
-        resolution.droppedRecordCount),
-        documents,
-    };
-}
-/**
- * Resolve ONE document — the shape both single-file loaders need.
- *
- * Still the core's pipeline, not a shortcut around it: the value is validated
- * against the canonical schema (depth bound, prototype-key policy, the declared
- * `lsp.*` types) and merged from one source, so a single-file loader and the
- * multi-file one cannot disagree about what a value means.
- *
- * It deliberately does NOT normalize legacy root LSP keys into the `lsp`
- * namespace the way `resolvePiLensConfig` does (#2427 review round 2, F1).
- * This path's two callers project the pi-lens sections of ONE file and hand
- * the resolved value out as `PiLensProjectConfig.raw`, which is documented and
- * tested as the parsed document; relocating a key inside it would put an `lsp`
- * section in `raw` that the user's file never contained. The relocation exists
- * so that ONE key seen at SEVERAL tiers reaches one schema node, and a
- * single-document resolution has no tiers to reconcile.
- *
- * The visible consequence is small and worth naming: a wrong-TYPED legacy root
- * LSP key (`warmFiles: true`) is validated against the typed `lsp.*` node only
- * in the multi-document path, so the LSP loader reports it and the two
- * single-file loaders do not. A session runs both, and the warn-once latch
- * unions their notices, so a user loses nothing — they gain one accurate
- * notice.
- */
-export function resolveOnePiLensConfigDocument(document, homeDir = os.homedir()) {
-    const resolution = resolveConfig({
-        sources: [
-            { tier: document.tier, file: document.file, value: document.value },
-        ],
-        schema: PI_LENS_CONFIG_SCHEMA,
-    });
-    return {
-        value: resolution.resolved.value ?? {},
-        records: finalizeRecords([...resolution.records, ...deprecationRecords([document], homeDir)], documentAnchor([document]), 
-        // Same double bound as the multi-document path above (round 6, F1).
-        resolution.droppedRecordCount),
-    };
-}
-/**
- * The anchor for a record list produced from these documents: the
- * highest-precedence one — the file whose values would have won, and the one a
- * user reading a config notice is looking at.
- *
- * The list's BOUND, its overflow record, and the reserved slot that record
- * occupies all live in `config-core/records.ts` (#2426 review round 5,
- * F-A/F-B/S-A). This module used to carry its own copy of them, the project
- * loader carried a second, and the project loader's legacy path carried none
- * at all — the shape the single-source rule exists to catch. What is left here
- * is the one thing `config-core` cannot know: which of the caller's documents
- * is the anchor.
- */
-function documentAnchor(documents) {
-    const last = documents[documents.length - 1];
-    return last === undefined ? undefined : { file: last.file, tier: last.tier };
-}
-/**
- * The `ConfigLocation` for a project-relative basename, for a caller that
- * discovered the file through its own (cached) walk rather than through
- * `collectPiLensConfigDocuments`. Falls back to the canonical location so an
- * unrecognized basename is never reported as deprecated.
- */
-export function projectLocationFor(file) {
-    const base = path.basename(file);
-    return (PROJECT_CONFIG_LOCATIONS.find((candidate) => path.posix.basename(candidate.relativePath) === base) ?? PROJECT_CONFIG_LOCATIONS[PROJECT_CONFIG_LOCATIONS.length - 1]);
-}
-// --- deprecation records (#2418 codes 0002 / 0003, #2426 is their producer) ---
-const WINDOW_BY_SURFACE = new Map(DEPRECATED_CONFIG_SURFACES.map((row) => [row.surface, row]));
-function windowSuffix(surface) {
-    const row = surface === undefined ? undefined : WINDOW_BY_SURFACE.get(surface);
-    return row
-        ? ` (deprecated since ${row.deprecatedSince}; read for the last time before ${row.removeNotBefore})`
-        : "";
-}
-/**
- * The canonical file a legacy document's keys belong in.
- *
- * `globalFile` is THREADED from the resolution that read the legacy document,
- * never recomputed from that document's own directory (#2426 review round 2,
- * F1) — see `canonicalGlobalFile`. The sibling fallback survives only for a
- * caller that resolves ONE document in isolation and names no canonical global
- * (no production caller does; `resolveOnePiLensConfigDocument`'s two callers
- * pass a project document and a canonical global one respectively), and it is
- * the only path this module can name at all in that case.
- */
-function canonicalDestination(document, homeDir, globalFile) {
-    if (document.tier === "global") {
-        return homeRelativePath(globalFile ??
-            path.join(path.dirname(document.file), CANONICAL_GLOBAL_CONFIG_FILE), homeDir);
-    }
-    return CANONICAL_PROJECT_CONFIG_FILE;
-}
-/**
- * The `lsp`-namespace key a document ROOT key normalizes to, or `undefined`
- * when the key stays where it is.
- *
- * THE mapping, shared with `canonicalKeyFor` below so the key a deprecation
- * record tells the user to move to and the key the resolution actually merges
- * under are the same key by construction. An LSP-SCOPED legacy file
- * (`pi-lsp.json`, `.pi-lens/lsp.json`) is wholly what a canonical file now
- * carries under `lsp`, so every RECOGNIZED root key of one moves; a canonical
- * or non-LSP legacy file moves only the four registry-derived legacy root keys.
- * An unrecognized key is left alone in both cases — it is not a pi-lens
- * setting, and relocating it would invent a meaning for it.
- */
-function lspNamespaceKeyFor(document, key) {
-    if (key === LSP_NAMESPACE_KEY)
-        return undefined;
-    if (document.location.lspScoped) {
-        return recognizedKeysFor(document.location).has(key) ? key : undefined;
-    }
-    return LEGACY_ROOT_LSP_KEYS.includes(key) ? key : undefined;
-}
-/**
- * Assign one raw, not-yet-validated value under a user-chosen key.
- *
- * `defineProperty` rather than `=` for the reason `config-core/safe-object.ts`
- * spells out: `out["__proto__"] = x` runs an inherited SETTER instead of
- * creating a property. This split runs BEFORE `validate()`, so it is the one
- * place in this module that touches user-chosen key names, and it hands every
- * such key through untouched for the core to reject and record.
- */
-function assignRaw(target, key, value) {
-    Object.defineProperty(target, key, {
-        value,
-        writable: true,
-        enumerable: true,
-        configurable: true,
-    });
-}
-/**
- * The sources a resolution merges, with every document's legacy root LSP keys
- * moved into the `lsp` namespace (#2427 review round 2, F1).
- *
- * A document that carries none is passed through UNCHANGED — the overwhelming
- * majority, and the case that must cost nothing. One that does becomes TWO
- * sources at the same tier and file: the relocated keys first, the rest of the
- * document (its own `lsp` namespace included) second. Two sources rather than
- * one merged object because the second still carries whatever the document
- * spelled at `lsp`, so a malformed `lsp` keeps producing its `PILENS_CFG_0004`
- * while the relocated keys survive beside it; and because caller order at an
- * equal tier is what `merge()` uses to break a tie, putting the canonical
- * spelling second is exactly the canonical-wins-per-key rule `lspSectionOf`
- * used to apply at projection time.
- *
- * The relocated keys are STRIPPED from the second source rather than left in
- * place. Leaving them would keep the legacy schema node populated, and a
- * malformed legacy key would then record the same `PILENS_CFG_0004` twice —
- * once per spelling — for one mistake in one file.
- *
- * A deny key is the one place the intra-document tie is not "canonical wins":
- * `merge()` sends `lsp.disabledServers` to `config-core/deny.ts`, which unions
- * every contribution. A file spelling BOTH `disabledServers` and
- * `lsp.disabledServers` therefore denies both lists. That is the monotonic
- * answer and the only safe one — a denial silently dropped because the user
- * half-migrated the file it was written in is the defect this whole change
- * exists to remove.
- */
-function configSources(documents) {
-    const sources = [];
-    for (const document of documents) {
-        const value = document.value;
-        const namespaced = {};
-        const rest = {};
-        for (const key of topLevelKeys(value)) {
-            const entry = value[key];
-            const target = lspNamespaceKeyFor(document, key);
-            if (target === undefined)
-                assignRaw(rest, key, entry);
-            else
-                assignRaw(namespaced, target, entry);
-        }
-        const base = { tier: document.tier, file: document.file };
-        if (Object.keys(namespaced).length === 0) {
-            sources.push({ ...base, value });
-            continue;
-        }
-        sources.push({ ...base, value: { [LSP_NAMESPACE_KEY]: namespaced } });
-        sources.push({ ...base, value: rest });
-    }
-    return sources;
-}
-/**
- * The canonical KEY a legacy key moves to.
- *
- * Carried on the record (`canonicalKey`) rather than only rendered into the
- * message, so the auto-migrator #2426 explicitly defers can be a pure function
- * over these records instead of re-parsing prose.
- */
-function canonicalKeyFor(document, key) {
-    const namespaced = lspNamespaceKeyFor(document, key);
-    return namespaced === undefined ? key : `${LSP_NAMESPACE_KEY}.${namespaced}`;
-}
-function topLevelKeys(value) {
-    return value && typeof value === "object" && !Array.isArray(value)
-        ? Object.keys(value)
-        : [];
-}
-/** The `properties` key names of a JSON-Schema-shaped node. */
-function schemaPropertyKeys(node) {
-    const properties = node?.properties;
-    return properties !== null &&
-        typeof properties === "object" &&
-        !Array.isArray(properties)
-        ? Object.keys(properties)
-        : [];
-}
-/**
- * The top-level keys a pi-lens config document may legitimately carry — READ
- * OFF the canonical schema rather than restated, so a section added to a
- * registry is recognized here for free (`config-schema.ts` derives its property
- * list from those registries).
- */
-const CANONICAL_TOP_LEVEL_KEYS = new Set(schemaPropertyKeys(PI_LENS_CONFIG_SCHEMA));
-/**
- * The same, for an LSP-SCOPED legacy file (`pi-lsp.json`, `.pi-lens/lsp.json`,
- * `~/.pi-lens/lsp.json`): that whole file is what a canonical file now holds
- * under `lsp`, so its recognized ROOT keys are the `lsp` namespace's own.
- */
-const LSP_DOCUMENT_KEYS = new Set(schemaPropertyKeys(PI_LENS_CONFIG_SCHEMA
-    .properties?.[LSP_NAMESPACE_KEY]));
-function recognizedKeysFor(location) {
-    return location.lspScoped ? LSP_DOCUMENT_KEYS : CANONICAL_TOP_LEVEL_KEYS;
-}
-/**
- * One record per `(file, key)` — never one per nested leaf, and only for a key
- * pi-lens actually RECOGNIZES (#2426 review round 4, F2/F5).
- *
- * A per-leaf record would re-nag once per custom server. A record for every
- * top-level key, which is what this emitted before, was worse in both
- * directions: the count was user input, so a 100-key legacy file produced 100
- * "move it" notices on top of the 98 typo notices the project loader already
- * emits for the same keys; and each one told the user to MOVE a key that is
- * not a pi-lens setting at all, which is advice that cannot be followed. A key
- * no schema property claims gets the loaders' typo diagnostic and nothing
- * else.
- *
- * The unrecognized keys are still accounted for, in ONE whole-file record
- * naming their count — the file is at a deprecated location whatever its keys
- * spell, and a user who moves only the keys named here has to know the rest
- * were left behind deliberately.
- */
-export function deprecationRecords(documents, homeDir, globalFile) {
-    const records = [];
-    for (const document of documents) {
-        if (document.location.legacy) {
-            const destination = canonicalDestination(document, homeDir, globalFile);
-            const recognized = recognizedKeysFor(document.location);
-            let unrecognized = 0;
-            for (const key of topLevelKeys(document.value)) {
-                if (!recognized.has(key)) {
-                    unrecognized += 1;
-                    continue;
-                }
-                const canonicalKey = canonicalKeyFor(document, key);
-                records.push(record({
-                    code: "PILENS_CFG_0003",
-                    file: document.file,
-                    key,
-                    canonicalKey,
-                    tier: document.tier,
-                    reason: `move "${key}" to ${destination}` +
-                        (canonicalKey === key ? "" : ` under "${canonicalKey}"`) +
-                        windowSuffix(document.location.surface),
-                }));
-            }
-            if (unrecognized > 0) {
-                const plural = unrecognized === 1 ? "it was" : "they were";
-                records.push({
-                    code: "PILENS_CFG_0003",
-                    file: document.file,
-                    key: "",
-                    // An LSP-scoped legacy file moves WHOLESALE into the `lsp`
-                    // namespace, so naming that namespace is literally true here — and
-                    // it is what routes this record to the LSP loader's subsystem, the
-                    // same key-derived ownership every other record uses.
-                    ...(document.location.lspScoped
-                        ? { canonicalKey: LSP_NAMESPACE_KEY }
-                        : {}),
-                    subject: migrationSubject(document.file, ""),
-                    tier: document.tier,
-                    reason: `this file is at a deprecated location; move it to ${destination}. ` +
-                        (unrecognized === 1
-                            ? "1 of its top-level keys is not a recognized pi-lens setting"
-                            : `${unrecognized} of its top-level keys are not recognized pi-lens settings`) +
-                        `, and ${plural} not migrated${windowSuffix(document.location.surface)}`,
-                });
-            }
-            continue;
-        }
-        // A CANONICAL file carrying legacy ROOT LSP keys: the file stays, the keys
-        // move into the `lsp` namespace inside it.
-        for (const key of topLevelKeys(document.value)) {
-            if (!LEGACY_ROOT_LSP_KEYS.includes(key))
-                continue;
-            const canonicalKey = `${LSP_NAMESPACE_KEY}.${key}`;
-            records.push(record({
-                code: "PILENS_CFG_0002",
-                file: document.file,
-                key,
-                canonicalKey,
-                tier: document.tier,
-                reason: `move "${key}" to "${canonicalKey}" in the same file${windowSuffix(key)}`,
-            }));
-        }
-    }
-    return records;
-}
-function record(input) {
-    return {
-        code: input.code,
-        file: input.file,
-        key: input.key,
-        canonicalKey: input.canonicalKey,
-        subject: migrationSubject(input.file, input.key),
-        reason: input.reason,
-        tier: input.tier,
-    };
-}
-/**
- * `undefined` for a record no key can attribute — the whole-file/whole-document
- * failure records (`key: ""`) that both halves of the core emit when a resolution
- * fails internally. Those are reported by EVERY loader rather than by none: a
- * duplicate notice about a config that failed to load is noise, while silence
- * about it is the failure mode this module exists to prevent.
- */
-function configRecordOwner(record) {
-    const key = record.canonicalKey ?? record.key;
-    if (key.length === 0)
-        return undefined;
-    const head = (key.startsWith("/") ? key.slice(1) : key).split(/[./]/)[0] ?? "";
-    if (head.length === 0)
-        return undefined;
-    return head === LSP_NAMESPACE_KEY || LEGACY_ROOT_LSP_KEYS.includes(head)
-        ? "lsp"
-        : "pi-lens";
-}
-/** The pi-lens-config subsystem a GLOBAL vs. PROJECT tier reports under. */
-function piLensSubsystemFor(tier) {
-    if (tier === "global")
-        return "lens-config";
-    if (tier === "project" || tier === "nested-project") {
-        return "project-lens-config";
-    }
-    // `builtin` / `env` / `cli` / `host` never produce a document today, and a
-    // merge-level bound refusal (see `MigrationRecord.tier`'s doc comment) names
-    // no single source at all — `undefined` in either case.
-    return undefined;
-}
-/**
- * The subsystem(s) one record must be reported under (#2426 review round 3,
- * F1).
- *
- * DERIVED from the record itself — owner (`configRecordOwner`) plus, for a
- * pi-lens-owned record, the TIER it was read at — rather than from which
- * loader is calling. Before this, a caller filtered to the records it "owned"
- * with `recordsOwnedBy` before reporting, which meant a pi-lens-owned record
- * from a document only the LSP loader's multi-file resolution actually
- * discovered (a legacy sibling file `loadPiLensProjectConfig`'s single-nearest-
- * file walk never opens) was filtered OUT by the LSP loader and never produced
- * by the project loader either: dropped by construction, never reported by
- * anyone.
- *
- * Deriving the subsystem from the record instead of the caller fixes that:
- * EVERY loader that sees the record now reports it, always to the SAME
- * subsystem set, so the warn-once latch (keyed on `subsystem\0file\0key\0
- * reason`) naturally collapses duplicate reports from different callers into
- * one notice — the F2 behavior — while a record no caller happened to "own"
- * before is reported by whichever loader actually resolved it.
- *
- * An `lsp` owner always reports under `lsp-config`, regardless of tier — the
- * LSP loader is the one home for every LSP setting. A `pi-lens` owner reports
- * under the tier-appropriate pi-lens loader.
- *
- * An unattributable record (owner `undefined` — the whole-file failures both
- * halves of the core emit with `key: ""`) reports under the ONE subsystem its
- * TIER names, when a tier is known (#2426 review round 4, S1). Round 3 sent it
- * to every subsystem that could plausibly have produced it, which turned one
- * internal failure into three notices, one of them announcing an "LSP config"
- * problem in a file with no LSP settings in it. `config-core`'s own
- * `resolveConfig` anchors that record to the resolution's highest-precedence
- * source precisely so the tier is known; the report-by-all fallback survives only for
- * a record that names no source at all.
- */
-function configRecordSubsystems(record) {
-    const owner = configRecordOwner(record);
-    const piLens = piLensSubsystemFor(record.tier);
-    const piLensSubsystems = piLens
-        ? [piLens]
-        : ["lens-config", "project-lens-config"];
-    if (owner === "lsp")
-        return ["lsp-config"];
-    if (owner === "pi-lens")
-        return piLensSubsystems;
-    if (piLens)
-        return [piLens];
-    return ["lsp-config", ...piLensSubsystems];
-}
-/**
- * WHICH subsystem owns a config file that could not be read or parsed (#2445).
- *
- * Derived from the DOCUMENT — its location and its tier — for the same reason
- * `configRecordSubsystems` derives ownership from the record: `loadLSPConfig`
- * opens the pi-lens global and project configs too, and labelling their parse
- * failures "ignoring invalid LSP config" told a user to look at an LSP setting
- * when what they had broken was `~/.pi-lens/config.json`. An LSP-SCOPED file
- * (`pi-lsp.json`, `lsp.json`) is the LSP loader's whatever tier it sits at.
- */
-function configFileSubsystem(location, tier) {
-    if (location.lspScoped)
-        return "lsp-config";
-    return tier === "global" ? "lens-config" : "project-lens-config";
-}
-/**
- * Report an unreadable/unparsable config document under its OWNING subsystem.
- *
- * `{ parseError }`, never a pre-stringified message: `warnIgnoredConfigOnce` is
- * the one seam that decides how much of a `JSON.parse` `SyntaxError#message`
- * (which embeds a snippet of the file being parsed, #2431) survives into the
- * log line, the ledger row and the notification.
- */
-export function reportConfigReadFailure(failure) {
-    warnIgnoredConfigOnce({
-        subsystem: configFileSubsystem(failure.location, failure.tier),
-        file: failure.file,
-        reason: { parseError: failure.error, sourceText: failure.sourceText },
-    });
-}
-/**
- * Thread a resolution's records to the ONE config warning seam (#2418).
- *
- * Every caller passes every record its OWN resolution produced — no filtering
- * (#2426 review round 3, F1; see `subsystemsFor`). Calling this more than once
- * with overlapping records (the LSP loader and a pi-lens loader resolving the
- * same document) is by design: the warn-once latch dedupes across callers, so
- * the user still sees exactly one notice per `(subsystem, file, key, reason)`.
- *
- * It lives here rather than in `config-core/records.ts`, where #2425 first put
- * it (#2426). Putting the sink call inside the library contradicted the
- * library's own stated purity — `config-core` is documented as "no state, no
- * I/O, no ledger writes" — and the import it needed
- * (`records.ts` -> `config-warn.js` -> `degradation-ledger.js`) closed seven
- * cycles the moment a loader resolved through the core, because every config
- * loader sits downstream of `file-utils.ts`. Reporting is a loader decision;
- * this is the loaders' shared module.
- */
-export function reportPiLensConfigRecords(records) {
-    for (const record of records) {
-        for (const subsystem of configRecordSubsystems(record)) {
-            warnIgnoredConfigOnce({
-                subsystem,
-                file: record.file,
-                key: record.key.length > 0 ? record.key : undefined,
-                reason: record.reason,
-                code: record.code,
-            });
-        }
-    }
-}
-/**
- * Buffer a loader's own ignored-config notices for one document, then bound
- * them once.
- *
- * A `NoteIgnored` COLLECTS rather than reports (#2426 review round 4, F3/F5).
- * Two things follow. The notice survives into a loader's cache entry, so a warm
- * cache HIT replays it instead of losing the whole `config-ignored` class from
- * session 2 onwards. And the count is bounded: the number of these a file can
- * produce is the number of keys the user typed — a 100-key file emitted 98
- * unknown-key notifications — so the buffered list goes through the same
- * `finalizeRecords` bound every other config record obeys, with one slot held
- * back to say how many were suppressed.
- *
- * ONE COPY, in the module both loaders already import (#2426 review round 7,
- * F2). Round 6 gave the global loader the bound the project loader already had
- * — by copying it — leaving two spellings of one record literal
- * (`PILENS_CFG_0001`, no key, `migrationSubject(configPath, "")`) and one flush,
- * differing only in a tier literal. Two copies of one policy is the shape round
- * 5 collapsed three copies of this same bound to avoid, so the tier is an
- * argument and the copy is gone. `tests/clients/config-notice-bounds.test.ts`
- * asserts on the SOURCE that no third copy grows back, because duplication is
- * invisible to a behavioral probe until one copy is edited.
- *
- * The buffer is a plain array (round 6, S2). It used to be a pre-subtracted
- * `finalizableCollector`, a second exported shape for the one policy round 5
- * had just collapsed; the notes a single parse can accumulate are bounded by
- * the document already in memory, which is a smaller cost than a second public
- * entry point onto the same arithmetic.
- */
-export function ignoredRecordCollector(configPath, tier) {
-    const noted = [];
-    const note = (reason, code = "PILENS_CFG_0001") => {
-        let notedRecord = {
-            code: "PILENS_CFG_0001",
-            file: configPath,
-            key: "",
-            subject: migrationSubject(configPath, ""),
-            reason: typeof reason === "string"
-                ? reason
-                : normalizeParseErrorReason(reason.parseError, {
-                    sourceText: reason.sourceText,
-                }),
-            tier,
-        };
-        if (code !== "PILENS_CFG_0001")
-            notedRecord.code = code;
-        noted.push(notedRecord);
-    };
-    return {
-        note,
-        records: () => finalizeRecords(noted, { file: configPath, tier }),
-    };
-}
-/**
- * The effective `lsp` section of a resolved configuration.
- *
- * One lookup, because the combination it used to perform now happens at source
- * injection (`configSources`): by the time a value reaches here, every legacy
- * root LSP key a document carried is already inside the namespace and has been
- * resolved against every tier through the SAME schema node as its canonical
- * spelling. Canonical still wins a collision inside one document — that is
- * caller order in `configSources` — but the winner is now chosen by `merge()`,
- * which is the only place that can see all the tiers at once.
- *
- * "Wins" is PER LEAF, not per key. A document that spells both root `servers`
- * and `lsp.servers` no longer has one object replace the other: the two are
- * merged by server id, and canonical wins only the ids they both define. A
- * server defined only in the legacy root spelling therefore survives beside
- * the canonical ones instead of disappearing — which is the same fix, one
- * level down, as the vanishing legacy denial below (#2427 review round 3).
- *
- * The projection-time combination this used to do could only ever see two
- * independently resolved nodes, and picking one of them is how a global denial
- * written in the legacy spelling used to vanish (#2427 review round 2, F1).
- */
-export function lspSectionOf(value) {
-    const namespace = value[LSP_NAMESPACE_KEY];
-    return namespace && typeof namespace === "object" && !Array.isArray(namespace)
-        ? namespace
-        : {};
-}