@herbertgao/pi-extensions 2026.9.0 → 2026.9.2

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

@@ -0,0 +1,234 @@
+/**
+ * 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";
+/** 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");
+    }
+    // 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/node_modules/pi-lens/dist/clients/config-warn.js

@@ -0,0 +1,407 @@
+/**
+ * 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, } 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,
+        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);
+        }
+    }
+}