pi-lens 4.3.0 → 4.4.0

package/dist/clients/config-schema.js

@@ -1,251 +0,0 @@
-/**
- * THE canonical pi-lens config schema (#2426).
- *
- * A plain JSON-Schema-shaped object, per `config-core/schema.ts`: the same
- * value the validator runs on is the value #2416 publishes as
- * `docs/schema/pi-lens-config-v1.json`, so there is no compiler between the two
- * for drift to hide in. It is the FIRST real schema through the #2418 harness —
- * `tests/config/pi-lens-config-schema.test.ts` runs `assertSchemaStabilityTiers`
- * and `assertSchemaIdentityAnchor` over this object rather than over the
- * placeholder fixture, which is what makes those two assertions load-bearing
- * instead of self-referential.
- *
- * Three deliberate shapes:
- *
- * 1. THE ROOT IS OPEN (`additionalProperties: true`). pi-lens's default is
- *    closed (`docs/public-api-stability.md`), and this is the one place that
- *    default is overridden on purpose. Both loaders already have their OWN,
- *    richer unknown-key diagnostics — the global loader names the typo, and the
- *    project loader distinguishes "typo" from "that is a global-only setting"
- *    (#533/#883). Letting `validate()` drop an unknown root key first would
- *    replace both messages with a generic `PILENS_CFG_0004`, which is strictly
- *    less information for the user. Closing the root belongs to the slice that
- *    moves those diagnostics into the schema, not to this one.
- *
- * 2. THE NAMESPACE LIST IS DERIVED, NEVER RESTATED. Every top-level section
- *    comes from `lens-flag-registry.ts`'s registries; adding a flag or a
- *    section needs no edit here. A hand-copied mirror of a registry is the
- *    defect AGENTS.md's single-source-of-truth rule names, and it is the exact
- *    thing #883 already removed from the two loaders' unknown-key scans.
- *
- * 3. ONLY `lsp` DECLARES A TYPE, and only one level deep. #2416 owns the
- *    `lsp.servers.<id>` shape; this slice RESERVES the namespace and moves the
- *    loader. Everything else stays schema-opaque, which `config-core` walks
- *    open — the node is still depth-bounded, prototype-key-checked and
- *    recorded, but no field's accepted values change in a slice whose
- *    acceptance criterion is that they do not.
- */
-import { CONFIG_SCHEMA_ANCHOR_KEY, CONFIG_SCHEMA_ID, STABILITY_TIER_KEY, } from "./config-diagnostic-codes.js";
-import { LEGACY_ROOT_LSP_KEYS, LSP_NAMESPACE_KEY } from "./config-locations.js";
-// From the owning module, not the barrel — same reason as `config-resolve.ts`:
-// the barrel's width would drag `process-spec.js` -> `project-trust.js` into
-// every config loader's import graph for one type alias.
-import { DENY_KEY, } from "./config-core/schema.js";
-import { flagConfigSectionKeys, GLOBAL_NON_FLAG_CONFIG_SECTIONS, LENS_FLAGS, PROJECT_FOREIGN_CONFIG_NAMESPACES, PROJECT_NON_FLAG_CONFIG_SECTIONS, } from "./lens-flag-registry.js";
-import { LENS_TOOL_NAMES } from "./tool-config.js";
-/** The JSON Schema dialect the published artifact declares. */
-const CONFIG_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
-/**
- * A node the schema says nothing else about. `config-core` treats a node with
- * no `type` as opaque and walks its children OPEN, so an undeclared section
- * keeps exactly the values it kept before this schema existed.
- */
-function opaque(tier) {
-    return { [STABILITY_TIER_KEY]: tier };
-}
-/**
- * The `lsp` namespace: reserved here, shaped by #2416.
- *
- * `enabled` is the pre-existing `--no-lsp` toggle and keeps living here, which
- * is why `lsp` is a NAMESPACE rather than a new sibling of the toggle: a config
- * key that already means "is the LSP on" and a key that means "which servers"
- * belong under one heading, and splitting them would have been a second name
- * for the same subsystem.
- *
- * The four catalog keys are `experimental` on purpose. They are the canonical
- * home of the four legacy ROOT keys deprecated by this PR, and #2416 replaces
- * the bare-command server form with the trust-gated `ProcessSpec` — promising
- * stability on a shape that is already scheduled to change would be a promise
- * made only to be broken.
- */
-/**
- * The JSON type each canonical `lsp.*` key carries. Spelled out rather than
- * inferred from the key's name: this is the ONE piece of validation the slice
- * adds, and it earns its place — pre-#2426 a `disabledServers` that was a
- * STRING reached `new Set(config.disabledServers)` and disabled one server per
- * CHARACTER. `tests/config/pi-lens-config-schema.test.ts` asserts every
- * `LEGACY_ROOT_LSP_KEYS` member has an entry here, so a new registry row cannot
- * land untyped.
- */
-const LSP_KEY_TYPES = {
-    servers: "object",
-    serverOverrides: "object",
-    disabledServers: "array",
-    warmFiles: "array",
-};
-export { LSP_KEY_TYPES };
-/**
- * The canonical `lsp.*` keys that carry a DENIAL rather than an ordinary value
- * (#2427).
- *
- * `config-core/deny.ts` has shipped monotonic deny precedence since #2440 and
- * `merge()` has consulted it since — but it only fires for a node the SCHEMA
- * annotates, and no production node did. The consequence was live and
- * measurable: with `~/.pi-lens/config.json` saying
- * `lsp.disabledServers: ["typos"]` and a repository's `.pi-lens.json` saying
- * `lsp.disabledServers: []`, the resolution returned `[]` attributed to the
- * `project` tier and `loadLSPConfig` handed `initLSPConfig` an empty disable
- * set — repository content silently re-enabling a server the operator turned
- * off, which is the exact scenario `deny.ts`'s module doc says it exists to
- * prevent and #2415 AC 3 forbids. One annotation is the whole fix: the union
- * of every tier's members, attributed to the tier that first denied.
- *
- * `enabled` is deliberately NOT annotated here. `boolean-false` pins an
- * operator denial against every higher tier including `cli`, and `env`/`cli`
- * are still unpopulated (`docs/configuration.md`), so annotating it now would
- * decide what `--lsp` means against a global `lsp.enabled: false` in a slice
- * that cannot test the tiers involved. That belongs to the slice that
- * populates them.
- */
-const LSP_KEY_DENY = {
-    disabledServers: "array-union",
-};
-/** The `x-deny` annotation for a key, or nothing when it carries no denial. */
-function denyAnnotation(key) {
-    const policy = LSP_KEY_DENY[key];
-    return policy === undefined ? {} : { [DENY_KEY]: policy };
-}
-function lspNamespace() {
-    const properties = {
-        // Reserved but deliberately UNTYPED. `lens-config.ts` already rejects a
-        // non-boolean here with `lsp.enabled must be a boolean` — a message that
-        // names the key and the expected type — and it is the one every flag in
-        // the registry shares. Declaring `type: "boolean"` would make `validate()`
-        // drop the value first and replace that message with the core's generic
-        // `expected boolean, got string`, which is strictly less useful. The flag
-        // sections move into the schema when their diagnostics do, not before.
-        enabled: { [STABILITY_TIER_KEY]: "stable" },
-    };
-    for (const key of LEGACY_ROOT_LSP_KEYS) {
-        const declared = LSP_KEY_TYPES[key];
-        properties[key] = {
-            ...(declared ? { type: declared } : {}),
-            [STABILITY_TIER_KEY]: "experimental",
-            ...(declared === "object" ? { additionalProperties: true } : {}),
-            ...denyAnnotation(key),
-        };
-    }
-    return {
-        type: "object",
-        additionalProperties: true,
-        [STABILITY_TIER_KEY]: "stable",
-        properties,
-    };
-}
-function buildConfigSchema() {
-    const properties = {};
-    // Every top-level section pi-lens recognizes today, derived from the
-    // registries rather than listed. These have shipped and are documented, so
-    // they are `stable`; declaring long-published fields experimental would
-    // understate a guarantee users already rely on.
-    for (const key of [
-        ...flagConfigSectionKeys(LENS_FLAGS),
-        ...GLOBAL_NON_FLAG_CONFIG_SECTIONS,
-        ...PROJECT_NON_FLAG_CONFIG_SECTIONS,
-    ]) {
-        properties[key] = opaque("stable");
-    }
-    properties.tools = {
-        type: "object",
-        additionalProperties: true,
-        properties: Object.fromEntries(LENS_TOOL_NAMES.map((name) => [
-            name,
-            {
-                type: "object",
-                additionalProperties: true,
-                properties: {
-                    enabled: { type: "boolean", [STABILITY_TIER_KEY]: "experimental" },
-                },
-                [STABILITY_TIER_KEY]: "experimental",
-            },
-        ])),
-        [STABILITY_TIER_KEY]: "stable",
-    };
-    // Namespaces owned by another tool that ride in the same file (`trivy`,
-    // `helm`). Reserved so they survive validation, `experimental` because their
-    // shape belongs to those runners, not to this schema.
-    for (const key of PROJECT_FOREIGN_CONFIG_NAMESPACES) {
-        properties[key] ??= opaque("experimental");
-    }
-    for (const key of [
-        "knip",
-        "jscpd",
-        "madge",
-        "gitleaks",
-        "govulncheck",
-        "deadCode",
-        "complexity",
-    ]) {
-        properties[key] = {
-            type: "object",
-            additionalProperties: true,
-            properties: {
-                enabled: { type: "boolean", [STABILITY_TIER_KEY]: "experimental" },
-            },
-            [STABILITY_TIER_KEY]: "stable",
-        };
-    }
-    properties.startup = {
-        type: "object",
-        additionalProperties: true,
-        properties: {
-            mode: {
-                type: "string",
-                enum: ["quick", "full", "minimal"],
-                [STABILITY_TIER_KEY]: "experimental",
-            },
-            scans: {
-                type: "object",
-                additionalProperties: true,
-                properties: {
-                    enabled: { type: "boolean", [STABILITY_TIER_KEY]: "experimental" },
-                },
-                [STABILITY_TIER_KEY]: "experimental",
-            },
-        },
-        [STABILITY_TIER_KEY]: "stable",
-    };
-    // The four legacy ROOT LSP keys. Still accepted for their deprecation window
-    // (#2418 registry), and `experimental` because they are scheduled for
-    // removal — a `stable` tier on a key with a `removeNotBefore` would be two
-    // registries contradicting each other.
-    //
-    // NO deny annotation, unlike round 1 of #2427 (review round 2, F1). Round 1
-    // annotated BOTH spellings and got two independent deny unions for one
-    // setting, neither seeing the other tiers. Both resolution entry points now
-    // normalize a document legacy root LSP keys into the `lsp` namespace before
-    // merging, so this node never receives a contribution at all and a policy on
-    // it could not fire. The denial is resolved once, at the canonical node,
-    // over every tier and every spelling — which is what the second annotation
-    // was trying to achieve and structurally could not.
-    for (const key of LEGACY_ROOT_LSP_KEYS) {
-        properties[key] = opaque("experimental");
-    }
-    properties[LSP_NAMESPACE_KEY] = lspNamespace();
-    properties[CONFIG_SCHEMA_ANCHOR_KEY] = {
-        type: "string",
-        description: "Identity anchor naming the schema version this config was written against.",
-        [STABILITY_TIER_KEY]: "stable",
-    };
-    return {
-        $schema: CONFIG_SCHEMA_DIALECT,
-        $id: CONFIG_SCHEMA_ID,
-        type: "object",
-        // See shape 1 in the module doc: deliberately open, so the loaders keep
-        // their own richer unknown-key diagnostics.
-        additionalProperties: true,
-        properties,
-    };
-}
-/** The canonical schema both canonical files are validated against. */
-export const PI_LENS_CONFIG_SCHEMA = buildConfigSchema();

package/dist/clients/config-warn.js

@@ -1,407 +0,0 @@
-/**
- * The ONE seam for "a config the user wrote is being ignored" (#2418).
- *
- * Three loaders — `clients/lsp/config.ts`, `clients/lens-config.ts`,
- * `clients/project-lens-config.ts` — each degraded a malformed config to
- * defaults and warned about it, with three near-identical bodies: a warn-once
- * latch, a `logExtension` line, and a `notifyUserDegradation` call. Three
- * copies meant three places to forget the stable diagnostic code, and three
- * places for the message shape to drift. They now share this helper, which
- * owns all four obligations:
- *
- * 1. the warn-once latch, keyed on (subsystem, file, key, reason) so a repeat
- *    load of the same broken file does not re-nag the user;
- * 2. the MACHINE-audience `extension.log` line;
- * 3. the durable degradation-ledger row, through the repo's existing
- *    `recordDegradationOnce` choke point rather than a parallel tally;
- * 4. the HUMAN-audience notification, carrying the stable `PILENS_CFG_*` code
- *    that `docs/public-api-stability.md` makes the user's match key.
- *
- * The message prose is assembled here from a per-subsystem label so every
- * caller's rendered string is byte-identical to what it emitted before the
- * extraction — the prose is not API (the code is), but silently rewording a
- * warning inside a refactor is still not a thing this PR does.
- */
-import { DEPRECATED_CONFIG_SURFACES, withConfigDiagnosticCode, } from "./config-diagnostic-codes.js";
-import { recordDegradationOnce } from "./degradation-ledger.js";
-import { errorClassName } from "./error-class.js";
-import { logExtension } from "./extension-log.js";
-import { redactSecrets } from "./redact/secrets.js";
-import { notifyUserDegradation } from "./user-notify.js";
-/**
- * The noun each subsystem uses for the config it is ignoring. These strings
- * are load-bearing for byte-identical prose: `ignoring invalid LSP config …`,
- * `… global config …`, `… project config …` are what shipped before #2418
- * extracted this helper, and `tests/clients/lsp/config.test.ts` +
- * `tests/clients/project-lens-config.test.ts` still assert on them.
- */
-const SUBSYSTEM_CONFIG_LABEL = {
-    "lsp-config": "LSP config",
-    "lens-config": "global config",
-    "project-lens-config": "project config",
-};
-/**
- * The code every ignored-config warning carries: PILENS_CFG_0001, "config file
- * unreadable or unparsable; ignored". Named here rather than repeated at three
- * call sites so the registry entry has exactly one referent in production code.
- */
-const IGNORED_CONFIG_CODE = "PILENS_CFG_0001";
-/**
- * The degradation kind this helper records under. One kind for all three
- * loaders: the subject discriminates WHICH file, and `metadata.subsystem`
- * discriminates which loader, so aggregation answers both without a kind
- * explosion.
- */
-const IGNORED_CONFIG_KIND = "config-ignored";
-/**
- * The degradation kind a DEPRECATION notice records under (#2426).
- *
- * Kept apart from `config-ignored` because the two are opposite facts about a
- * session: an ignored config means pi-lens ran on defaults instead of what the
- * user asked for, while a deprecated one means it ran on exactly what the user
- * asked for and the location will stop working. Folding them together would
- * have made "how many sessions ran degraded" un-answerable from the ledger.
- */
-const DEPRECATED_CONFIG_KIND = "config-deprecated";
-/**
- * The code that says a notice LIST was truncated (#2426 review round 6, F2).
- *
- * It is the one code on this seam that describes the OUTPUT rather than the
- * config, so it is the one that must not inherit either default below.
- */
-const SUPPRESSED_NOTICE_CODE = "PILENS_CFG_0007";
-/**
- * The degradation kind a SUPPRESSED-NOTICE summary records under (#2426 review
- * round 6, F2).
- *
- * Neither of the other two: nothing was ignored and nothing is deprecated —
- * a legacy file whose 28 settings ALL applied still overflows the bound, and
- * before this it produced a `config-ignored` row and an `ignoring invalid
- * project config` notice for a file with nothing invalid in it. That is the
- * same inversion `DEPRECATED_CONFIG_KIND` exists to prevent, arriving through
- * the default branch instead of through a wrong one.
- */
-const SUPPRESSED_NOTICE_KIND = "config-notice-suppressed";
-/**
- * The codes that mean "accepted, but deprecated". DERIVED from the deprecation
- * registry rather than listed, so a future `kind` of deprecated surface with a
- * new code cannot render as `ignoring invalid …` by omission.
- */
-const DEPRECATION_NOUN_BY_CODE = new Map(DEPRECATED_CONFIG_SURFACES.map((row) => [
-    row.code,
-    row.kind === "file" ? "location" : "key",
-]));
-/** Warn-once latch, keyed on (subsystem, file, key, reason). */
-const warnedIgnoredConfigs = new Set();
-/**
- * The one shape `JSON.parse`'s own `SyntaxError#message` states a position
- * in, on every supported Node (CI pins Node 22; V8 has emitted `at position N
- * (line L column C)` for this shape since ~Node 20). Captures the absolute
- * offset too (group 1), not just V8's own stated line/col (groups 2, 3):
- * with source text in hand, line/col is recomputed by scanning the source
- * ourselves rather than trusted from the message (#2451) — the offset is
- * still just a digit, kept only as the pre-#2451 fallback for a caller that
- * has no source text to scan.
- *
- * V8 also emits a position-free shape for a token error — `Unexpected token
- * 'x', "<snippet>"... is not valid JSON` — which carries no position at all,
- * only a slice of the source text being parsed. That is the exact shape
- * #2431's evidence hit (`ghp_SECRET` sitting in the snippet on Node 24), and
- * `locateSyntaxErrorOffset` below locates it in the source instead.
- */
-const JSON_PARSE_POSITION = /at position (\d+) \(line (\d+) column (\d+)\)/;
-/**
- * True for `JSON.parse`'s own `SyntaxError`, including one thrown across a
- * realm boundary (e.g. `vm.runInContext`), where BOTH `instanceof SyntaxError`
- * and `instanceof Error` fail — a realm-bound object's prototype chain
- * resolves through that OTHER realm's `Error.prototype`/`Object.prototype`,
- * never this one's. Duck-typed on `name` and `message` instead, which are
- * plain string own/inherited properties readable regardless of which realm's
- * prototype chain the object carries.
- */
-function isSyntaxError(error) {
-    return (typeof error === "object" &&
-        error !== null &&
-        error.name === "SyntaxError" &&
-        typeof error.message === "string");
-}
-/**
- * Line (1-based) and column (1-based, V8's own convention) of a character
- * offset, scanned directly from the source — never trusted from anything the
- * message states (#2451). `offset` is always in `[0, sourceText.length]`: it
- * comes from either V8's own `at position N` digit (bounded by construction —
- * V8 cannot state a position past the text it just parsed) or a snippet
- * `indexOf` match inside `sourceText` itself, so there is no out-of-range
- * case for this function to guard against.
- */
-function lineColAt(sourceText, offset) {
-    let line = 1;
-    let lastNewline = -1;
-    for (let i = 0; i < offset; i++) {
-        if (sourceText[i] === "\n") {
-            line++;
-            lastNewline = i;
-        }
-    }
-    return { line, col: offset - lastNewline };
-}
-/**
- * Split V8's position-free `Unexpected token` message into the offending
- * token and the (possibly truncated) source snippet around it.
- *
- * NOT regex-quote-matched: the snippet is a raw slice of the user's source
- * text and can itself contain `"`, which a `/"([\s\S]*?)"/`-shaped pattern
- * would stop at prematurely (`{"a": ghp_SECRET` has one right after the
- * opening `{`). Fixed prefix/suffix stripping instead, which is exact
- * regardless of what the snippet contains.
- */
-function parseUnexpectedTokenMessage(message) {
-    const prefix = "Unexpected token '";
-    if (!message.startsWith(prefix))
-        return undefined;
-    const closeIdx = message.indexOf("', ", prefix.length);
-    // No explicit `closeIdx === -1` branch: when the marker is missing,
-    // `closeIdx` is `-1`, so `rest` below starts at `message[2]` — always
-    // still inside the fixed `prefix` text the `startsWith` check just
-    // confirmed, never `"`. The `rest.startsWith('"')` check a few lines down
-    // already rejects that case; a second explicit check here could never be
-    // exercised by any input that passes the first, so it stayed untestable
-    // dead code rather than a guard (#2451 mutation pass).
-    const token = message.slice(prefix.length, closeIdx);
-    let rest = message.slice(closeIdx + 3);
-    if (rest.startsWith("..."))
-        rest = rest.slice(3);
-    if (!rest.startsWith('"'))
-        return undefined;
-    rest = rest.slice(1);
-    const truncatedSuffix = '"... is not valid JSON';
-    const plainSuffix = '" is not valid JSON';
-    const snippet = rest.endsWith(truncatedSuffix)
-        ? rest.slice(0, -truncatedSuffix.length)
-        : rest.endsWith(plainSuffix)
-            ? rest.slice(0, -plainSuffix.length)
-            : undefined;
-    // No explicit `snippet.length === 0` branch: `String#indexOf("")` matches
-    // at EVERY position, so an empty snippet always fails the caller's
-    // uniqueness check (`sourceText.indexOf(snippet, snippetAt + 1) !== -1`
-    // is true at every offset, including on an empty `sourceText`) — a second
-    // explicit check here could never be exercised by any input the first
-    // does not already catch (#2451 mutation pass).
-    return snippet === undefined ? undefined : { token, snippet };
-}
-/**
- * Locate a `JSON.parse` `SyntaxError`'s offset in ITS OWN source text
- * (#2451). Two shapes, both anchored to the source rather than to anything
- * V8 states about it:
- *
- * - `at position N`: N is already an exact offset.
- * - `Unexpected token 'x', "<snippet>"...`: no offset in the message at all,
- *   only a slice of the source. `snippet` is searched for in `sourceText`
- *   with `indexOf`; a match that is not unique is not trusted (the wrong
- *   occurrence would report a false location, and a `config-ignored` reason
- *   is not worth that risk). Inside a unique match, the offending token's
- *   own OFFSET is used when it too occurs exactly once in the snippet — the
- *   common case (JSON punctuation, a typo'd letter) — otherwise the snippet's
- *   own start stands in: still the correct line far more often than not
- *   (the snippet is a ~20-char window around the real offset), never a
- *   snippet the user did not already put in their own file.
- *
- * Returns `undefined` when neither shape locates unambiguously — the honest,
- * safe answer, which the caller degrades to the bare class name for.
- */
-function locateSyntaxErrorOffset(message, sourceText) {
-    const stated = JSON_PARSE_POSITION.exec(message);
-    if (stated)
-        return Number(stated[1]);
-    const parsed = parseUnexpectedTokenMessage(message);
-    if (!parsed)
-        return undefined;
-    const { token, snippet } = parsed;
-    const snippetAt = sourceText.indexOf(snippet);
-    if (snippetAt === -1 || sourceText.indexOf(snippet, snippetAt + 1) !== -1) {
-        return undefined;
-    }
-    const tokenAt = snippet.indexOf(token);
-    const onlyTokenOccurrence = tokenAt !== -1 && snippet.indexOf(token, tokenAt + 1) === -1;
-    return snippetAt + (onlyTokenOccurrence ? tokenAt : 0);
-}
-/**
- * Normalize a caught parse/validation error into a bounded, snippet-free
- * reason: the error's own class plus a position, when one can be derived —
- * NEVER the raw message (#2431), and never anything but the class name at
- * all for a `classOnly` caller (#2451).
- *
- * `JSON.parse`'s `SyntaxError#message` is DOCUMENTED (V8) to embed a slice of
- * the source text being parsed. A user's malformed config that happens to
- * carry a credential next to the syntax error would otherwise leak it into
- * `extension.log`, the user-facing notification, and the durable
- * degradation-ledger row through this one seam — so a `SyntaxError` NEVER
- * keeps its message, position-derived or not.
- *
- * Every other caught error reaching this helper (a loader's own hand-thrown
- * validation error, an `fs` error) is not documented to embed file content,
- * and is additionally routed through the repo's own secret scanner
- * (`redactSecrets`) — but that scanner is a floor, not a guarantee: it only
- * recognizes secrets shaped like its registered patterns and long enough to
- * clear each pattern's `minSuffixLength` (16-40 chars), so a short truncated
- * fragment of a real credential can still pass through untouched. It is
- * still worth calling on this branch because most non-`SyntaxError` messages
- * are hand-authored by this codebase, not engine dumps of file content — but
- * `normalizeParseErrorReason`'s own guarantee (no message survives at all)
- * applies only to the `SyntaxError` branch (and, unconditionally, to a
- * `classOnly` caller). `warnIgnoredConfigOnce` (the one `{ parseError }`
- * caller) additionally redacts EVERY reason, including hand-authored ones,
- * so a caller-composed string that happens to interpolate file content (a
- * user-authored config KEY, a rule id) is still covered.
- */
-export function normalizeParseErrorReason(error, options = {}) {
-    if (options.classOnly) {
-        return errorClassName(error);
-    }
-    if (isSyntaxError(error)) {
-        if (options.sourceText !== undefined) {
-            const offset = locateSyntaxErrorOffset(error.message, options.sourceText);
-            if (offset !== undefined) {
-                const { line, col } = lineColAt(options.sourceText, offset);
-                return `${error.name} at line ${line} col ${col}`;
-            }
-            return error.name;
-        }
-        const match = JSON_PARSE_POSITION.exec(error.message);
-        return match
-            ? `${error.name} at line ${match[2]} col ${match[3]}`
-            : error.name;
-    }
-    const message = error instanceof Error ? error.message : String(error);
-    return redactSecrets(message);
-}
-/**
- * Which durable kind a notice records under. Three facts, three kinds, decided
- * in ONE place so a fourth code cannot inherit "ignored" by falling through.
- */
-function degradationKindFor(suppressedNotice, deprecationNoun) {
-    if (suppressedNotice)
-        return SUPPRESSED_NOTICE_KIND;
-    return deprecationNoun ? DEPRECATED_CONFIG_KIND : IGNORED_CONFIG_KIND;
-}
-/**
- * The rendered prose for one notice.
- *
- * The two pre-existing shapes are BYTE-IDENTICAL to what shipped — several
- * suites assert on them — and the third is deliberately built from neither
- * vocabulary: a truncation summary describes the notice list, never the
- * config, so it says nothing about the file being invalid or ignored.
- */
-function noticeMessage(options) {
-    const label = SUBSYSTEM_CONFIG_LABEL[options.subsystem];
-    if (options.suppressedNotice) {
-        return `${label} notices for ${options.file} were summarised: ${options.reason}`;
-    }
-    return options.deprecationNoun
-        ? `deprecated ${label} ${options.deprecationNoun} in ${options.file}: ${options.reason}`
-        : `ignoring invalid ${label} ${options.file}: ${options.reason}`;
-}
-/**
- * Warn once that a config file (or one key in it) is being ignored.
- *
- * Fires the durable ledger row, the machine log, and the user-facing
- * notification. Every one of the three is bounded, but on two DIFFERENT
- * lifetimes: the latch here bounds the log line and the notification for the
- * life of the PROCESS, while `recordDegradationOnce` bounds the ledger row on
- * (kind, subject) for the life of the SESSION. That is why the ledger call sits
- * in front of the latch's early return — see the comment on it. The ledger
- * bound is also coarser, so a file failing for two different reasons warns
- * twice but is counted as one degraded config.
- */
-export function warnIgnoredConfigOnce(options) {
-    const { subsystem, file, key } = options;
-    const code = options.code ?? IGNORED_CONFIG_CODE;
-    // The ONLY place a caught parse/read error becomes a string (#2431). A
-    // `{ parseError }` is normalized to error class + position, never the raw
-    // message. A hand-authored reason is still `redactSecrets`-scrubbed here —
-    // review round 2, F1: several callers interpolate a user-authored KEY or
-    // rule id straight from the parsed config (`unknown key "${key}" is not a
-    // recognized pi-lens setting`), so "hand-authored" does not mean
-    // "content-free"; the ONE seam every caller shares is where that gets
-    // caught, not each of the ~8 call sites that format one of these strings.
-    const reason = redactSecrets(typeof options.reason === "string"
-        ? options.reason
-        : normalizeParseErrorReason(options.reason.parseError, {
-            sourceText: options.reason.sourceText,
-        }));
-    // The durable half (#2418 F6), and it runs BEFORE the latch on purpose
-    // (#2418 review round 3, F1). The latch is a PROCESS-lifetime Set; the
-    // ledger is per SESSION, reset by `resetDegradationLedger()` at the top of
-    // `handleSessionStart`. With the early return in front of this call, every
-    // session after the first recorded nothing while the config on disk was
-    // still ignored — the exact catalog-shape-17 defect
-    // `refreshGrammarSessionLatches` exists to prevent in tree-sitter-client.
-    //
-    // No second, generation-compared latch is needed to re-arm it, unlike that
-    // precedent: `recordDegradationOnce` already dedupes on (kind, subject)
-    // through its own once-key set, and that set IS cleared by the ledger
-    // reset. Calling it unconditionally makes the ledger the single source of
-    // truth for "once per session", instead of a parallel Set here that mirrors
-    // it and has to be kept in step. (tree-sitter needs its own gates because
-    // they guard `incrementDegradationCount`, which counts EVERY call, plus
-    // non-ledger state.)
-    //
-    // Subject is `<file>\0<key>` when a single key is rejected, and plain
-    // `<file>` otherwise, so a per-key rejection and a whole-file rejection are
-    // distinct rows for the same file without a trailing separator on every row.
-    const suppressedNotice = code === SUPPRESSED_NOTICE_CODE;
-    const deprecationNoun = suppressedNotice
-        ? undefined
-        : DEPRECATION_NOUN_BY_CODE.get(code);
-    recordDegradationOnce({
-        kind: degradationKindFor(suppressedNotice, deprecationNoun),
-        subject: key ? `${file}\0${key}` : file,
-        reason,
-        metadata: { subsystem, configPath: file },
-        code,
-    });
-    const latchKey = `${subsystem}\0${file}\0${key ?? ""}\0${reason}`;
-    if (warnedIgnoredConfigs.has(latchKey))
-        return;
-    warnedIgnoredConfigs.add(latchKey);
-    // Three prose shapes for three different facts. A deprecation notice — or a
-    // truncation summary — that said "ignoring invalid …" would tell the user
-    // their setting is not being applied when it IS: the one thing #2426's
-    // "no user is broken silently" rule cannot afford to get backwards.
-    const message = noticeMessage({
-        subsystem,
-        file,
-        reason,
-        suppressedNotice,
-        deprecationNoun,
-    });
-    logExtension({
-        subsystem,
-        level: "warn",
-        message: withConfigDiagnosticCode(message, code),
-        metadata: { configPath: file, reason, code, ...(key ? { key } : {}) },
-    });
-    // HUMAN-audience too: a config the user wrote is being ignored. Routed
-    // through the host's own render path (#1333), never a raw write. The stable
-    // code (#2418) is what a user matches or suppresses on; the prose may still
-    // change. Once per PROCESS, deliberately: re-nagging about the same broken
-    // file at every session boundary is noise, while the ledger row above is
-    // the per-session record.
-    notifyUserDegradation(`pi-lens: ${message}`, "warning", { code });
-}
-/**
- * Clear the warn-once latch. Test-only seam, and the one the loaders' own
- * reset helpers delegate to — a subsystem argument clears just that loader's
- * entries so one loader's test cannot silently un-latch another's.
- */
-export function resetIgnoredConfigWarnCache(subsystem) {
-    if (!subsystem) {
-        warnedIgnoredConfigs.clear();
-        return;
-    }
-    for (const latchKey of warnedIgnoredConfigs) {
-        if (latchKey.startsWith(`${subsystem}\0`)) {
-            warnedIgnoredConfigs.delete(latchKey);
-        }
-    }
-}