@telorun/analyzer 0.57.0 → 0.58.0

package/dist/migrations/match.js

@@ -0,0 +1,295 @@
+/** The selector half of a migration: what a rule MATCHES, as data.
+ *
+ *  A patch addresses a known location; a migration has to find *every*
+ *  occurrence of a legacy spelling, so selection is the half a plain patch
+ *  format has none of. It is declarative for the same reason the operations
+ *  are: an entry travels to a Rust and a Go kernel, and a predicate expressed
+ *  in one language would mean one artifact is read two ways — invisibly, since
+ *  a migration that succeeds is silent.
+ *
+ *  **Containment is POSITIVE and required.** A rule states which document kinds
+ *  it may touch (`inKind`) and which region of those documents it may reach
+ *  into (`under`); nothing outside is reachable. The alternative — walk
+ *  everything and subtract — cannot be made sound, because the set to subtract
+ *  is unbounded: a `Run.Value` value, an `Assert.Equals` expected, any kind
+ *  whose config carries a user JSON blob can hold something shaped like the
+ *  node a rule looks for, and forgetting one corrupts a manifest with no
+ *  diagnostic. A denylist also cannot express the guarantee the module surface
+ *  is promised to carry — *a dependency can rename its own field and provably
+ *  nothing else* — which is a statement about what a rule may reach, so it has
+ *  to be said positively. `notUnder` remains for subtracting inside a region a
+ *  rule legitimately reaches, which is a narrowing, not the containment itself.
+ *
+ *  **`under` is ANCHORED at the document root**, not a set of key names to look
+ *  for anywhere on the path. Anchoring is what makes the containment claim
+ *  true: a `Telo.Definition`'s `resources:` template body carries other kinds'
+ *  configuration, and any of it may hold a key spelled `schema` over data that
+ *  merely looks like a schema — so "some segment of the path is `schema`" would
+ *  reach the very user JSON blob the positive form exists to keep out, and
+ *  would delete from it silently. Anchored, `under` names top-level document
+ *  keys and a region is a genuine subtree.
+ *
+ *  **`inSchema` is the one region a kind list cannot name.** An annotation
+ *  keyword occurs in author-written JSON Schema, and schema fragments are not
+ *  confined to kind documents: an inline `inputType:` / `outputType:` on ANY kind
+ *  that declares one, an API route's `request.schema.body`, a `Telo.JsonSchema`'s
+ *  `schema`. That set of kinds is open — any kind may declare a schema-valued
+ *  field — and enumerating the standard library's would put resource-kind
+ *  knowledge into the analyzer, against the topology-driven constraint. So a rule
+ *  may instead state that it reaches only inside a SCHEMA REGION, named by the
+ *  KERNEL's own schema-valued keys, which no kind owns.
+ *
+ *  With `inSchema`, and only with it, `inKind` / `under` may be `["*"]` — and
+ *  only for a rule keyed on a reserved `x-telo-*` annotation. That pairing IS the
+ *  containment: the region gate bounds where the walk may go, and the reserved-key
+ *  rule bounds what it may touch, since an `x-telo-*` key is Telo vocabulary
+ *  wherever it appears and cannot mean something else in someone's config. Both
+ *  halves are refused at entry-read time, so a module-shipped entry can no more
+ *  spell `"*"` than it can name another module's kind.
+ *
+ *  The residue is stated rather than claimed away: a manifest that asserts ABOUT
+ *  a schema — a schema literal under a key spelled `schema` inside an assertion's
+ *  expected value — is reachable, and would be rewritten into its own synonym.
+ *  That cannot be closed in a data-only matcher without naming kinds. It is
+ *  accepted because the sites the wildcards reach are exactly the ones no
+ *  enumeration covers, and the alternative leaves an author reading a deprecation
+ *  `telo migrate` refuses to act on.
+ *
+ *  The vocabulary is closed, which is what makes it a trust boundary once
+ *  module-shipped entries are aggregated beside core ones. An unrecognized key
+ *  is refused rather than ignored — a selector that silently matches wider than
+ *  it reads is the one failure this cannot tolerate. */
+import { isInSchemaRegion } from "../schema-region.js";
+/** The wildcard `inKind` / `under` value. Legal only alongside `inSchema`, and
+ *  only for a rule keyed on an `x-telo-*` annotation. */
+export const MATCH_ANY = "*";
+export const MATCH_KEYS = [
+    "key",
+    "inKind",
+    "under",
+    "value",
+    "valueOneOf",
+    "withSibling",
+    "notUnder",
+    "inSchema",
+];
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Structural equality over JSON values — what `value` / `valueOneOf` compare
+ *  with, so a match on `true` never also matches `"true"`.
+ *
+ *  Exported because the PATCHER asks the same question in the other direction:
+ *  "is the value already what this would write". Both answers have to come from
+ *  one rule, or a rule could match a spelling the patch then declares current. */
+export function deepEquals(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((item, i) => deepEquals(item, b[i]));
+    }
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const aKeys = Object.keys(a);
+        if (aKeys.length !== Object.keys(b).length)
+            return false;
+        return aKeys.every((k) => Object.hasOwn(b, k) && deepEquals(a[k], b[k]));
+    }
+    return false;
+}
+function requireStringList(describe, raw, key) {
+    const value = raw[key];
+    if (!Array.isArray(value) || value.length === 0 || value.some((v) => typeof v !== "string")) {
+        throw new Error(`${describe}: 'match.${key}' must be a non-empty sequence of strings`);
+    }
+    return value;
+}
+/** Read a rule's `match` block, refusing anything the vocabulary does not
+ *  define. `describe` names the entry and rule so a failure says which. */
+export function readMigrationMatch(describe, raw) {
+    if (!isPlainObject(raw))
+        throw new Error(`${describe}: 'match' must be a mapping`);
+    for (const key of Object.keys(raw)) {
+        if (!MATCH_KEYS.includes(key)) {
+            throw new Error(`${describe}: 'match' has no key '${key}'. Known keys: ${MATCH_KEYS.join(", ")}.`);
+        }
+    }
+    if (typeof raw.key !== "string" || raw.key.length === 0) {
+        throw new Error(`${describe}: 'match.key' must be a non-empty string`);
+    }
+    if (Object.hasOwn(raw, "value") && Object.hasOwn(raw, "valueOneOf")) {
+        throw new Error(`${describe}: 'match' takes at most one of 'value' or 'valueOneOf'`);
+    }
+    if (Object.hasOwn(raw, "valueOneOf") && !Array.isArray(raw.valueOneOf)) {
+        throw new Error(`${describe}: 'match.valueOneOf' must be a sequence`);
+    }
+    if (Object.hasOwn(raw, "withSibling") && typeof raw.withSibling !== "string") {
+        throw new Error(`${describe}: 'match.withSibling' must be a string`);
+    }
+    if (Object.hasOwn(raw, "notUnder") &&
+        (!Array.isArray(raw.notUnder) || raw.notUnder.some((k) => typeof k !== "string"))) {
+        throw new Error(`${describe}: 'match.notUnder' must be a sequence of strings`);
+    }
+    if (Object.hasOwn(raw, "inSchema") && typeof raw.inSchema !== "boolean") {
+        throw new Error(`${describe}: 'match.inSchema' must be a boolean`);
+    }
+    // The two conditions that make a wildcard safe, refused here rather than
+    // narrowed later: a rule the reader accepts is a rule the driver will run, and
+    // a selector that matches wider than it reads is exactly what this vocabulary
+    // exists to prevent. A module-shipped entry therefore cannot spell `"*"` at
+    // all, because it cannot satisfy both halves for a keyword it does not own.
+    const wildcards = [
+        ...(Array.isArray(raw.inKind) ? raw.inKind : []),
+        ...(Array.isArray(raw.under) ? raw.under : []),
+    ].filter((value) => value === MATCH_ANY);
+    if (wildcards.length > 0) {
+        if (raw.inSchema !== true) {
+            throw new Error(`${describe}: 'match.inKind' / 'match.under' may only be '${MATCH_ANY}' together with ` +
+                `'inSchema: true' — the schema region is what bounds a walk the wildcard unbounds`);
+        }
+        if (!raw.key.startsWith("x-telo-")) {
+            throw new Error(`${describe}: '${MATCH_ANY}' is legal only for a rule keyed on an 'x-telo-*' annotation, ` +
+                `which is Telo vocabulary wherever it appears — '${raw.key}' could mean something else ` +
+                `inside a resource's own configuration`);
+        }
+    }
+    const match = {
+        key: raw.key,
+        inKind: requireStringList(describe, raw, "inKind"),
+        under: requireStringList(describe, raw, "under"),
+    };
+    if (Object.hasOwn(raw, "value"))
+        match.value = raw.value;
+    if (Object.hasOwn(raw, "valueOneOf"))
+        match.valueOneOf = raw.valueOneOf;
+    if (Object.hasOwn(raw, "withSibling"))
+        match.withSibling = raw.withSibling;
+    if (Object.hasOwn(raw, "notUnder"))
+        match.notUnder = raw.notUnder;
+    if (raw.inSchema === true)
+        match.inSchema = true;
+    return match;
+}
+/**
+ * Index `document`'s candidate sites for `keys`, descending only into the
+ * top-level regions named by `roots`.
+ *
+ * The caller has already gated on `inKind` — see `selectMatches`, which repeats
+ * the check because it holds the individual rule.
+ */
+export function buildMatchIndex(document, keys, roots) {
+    const index = new Map();
+    if (keys.size === 0 || roots.size === 0 || !isPlainObject(document))
+        return index;
+    // A mutable stack, materialized into an array only when a site is recorded.
+    const stack = [];
+    const record = (key, value, parent) => {
+        const bucket = index.get(key) ?? [];
+        bucket.push({ path: [...stack], value, parent });
+        index.set(key, bucket);
+    };
+    const walk = (node) => {
+        if (Array.isArray(node)) {
+            for (let i = 0; i < node.length; i++) {
+                stack.push(i);
+                walk(node[i]);
+                stack.pop();
+            }
+            return;
+        }
+        if (!isPlainObject(node))
+            return;
+        for (const [key, value] of Object.entries(node)) {
+            stack.push(key);
+            if (keys.has(key))
+                record(key, value, node);
+            walk(value);
+            stack.pop();
+        }
+    };
+    // Anchored containment, enforced by where the walk STARTS: everything the
+    // index holds is at or below a top-level key some rule named. A wildcard root
+    // starts everywhere instead — bounded not by where the walk begins but by the
+    // schema region and the reserved key its rule had to declare to earn it.
+    const everywhere = roots.has(MATCH_ANY);
+    for (const [key, value] of Object.entries(document)) {
+        if (!everywhere && !roots.has(key))
+            continue;
+        stack.push(key);
+        if (keys.has(key))
+            record(key, value, document);
+        walk(value);
+        stack.pop();
+    }
+    return index;
+}
+/** The rules in `entries` that may match a document of `kind`, with the key and
+ *  root sets their shared index needs. Empty rules mean the document is not
+ *  walked at all. */
+export function applicableRules(rules, kind) {
+    const applicable = [];
+    const keys = new Set();
+    const roots = new Set();
+    if (typeof kind !== "string")
+        return { rules: applicable, keys, roots };
+    for (const rule of rules) {
+        if (!rule.match.inKind.includes(kind) && !rule.match.inKind.includes(MATCH_ANY))
+            continue;
+        applicable.push(rule);
+        keys.add(rule.match.key);
+        for (const root of rule.match.under)
+            roots.add(root);
+    }
+    return { rules: applicable, keys, roots };
+}
+function valueMatches(match, value) {
+    if (Object.hasOwn(match, "value"))
+        return deepEquals(match.value, value);
+    if (match.valueOneOf)
+        return match.valueOneOf.some((candidate) => deepEquals(candidate, value));
+    return true;
+}
+/** The sites in `index` this match selects, in document order. */
+export function selectMatches(index, document, match) {
+    const kind = isPlainObject(document) ? document.kind : undefined;
+    if (typeof kind !== "string")
+        return [];
+    if (!match.inKind.includes(kind) && !match.inKind.includes(MATCH_ANY))
+        return [];
+    const sites = index.get(match.key);
+    if (!sites)
+        return [];
+    const anyRoot = match.under.includes(MATCH_ANY);
+    const out = [];
+    for (const site of sites) {
+        // The index may be shared with rules naming other regions, so the anchor is
+        // re-checked per rule. A numeric first segment cannot occur — a document is
+        // a mapping — but the guard keeps the containment claim independent of that.
+        const anchor = site.path[0];
+        if (!anyRoot && (typeof anchor !== "string" || !match.under.includes(anchor)))
+            continue;
+        // The schema region — the same ancestry rule every schema-bounded surface
+        // reads, so the migration and the validators cannot disagree about where a
+        // schema is.
+        if (match.inSchema && !isInSchemaRegion(site.path))
+            continue;
+        // `notUnder` subtracts within the region, so it reads the whole path. A
+        // numeric segment never equals a key name, so the raw path is enough.
+        if (match.notUnder?.some((segment) => site.path.includes(segment)))
+            continue;
+        if (!valueMatches(match, site.value))
+            continue;
+        if (match.withSibling !== undefined && !Object.hasOwn(site.parent, match.withSibling))
+            continue;
+        out.push(site.path);
+    }
+    return out;
+}
+/** Convenience for a single match against a document — builds a one-rule index.
+ *  The driver uses `applicableRules` + `buildMatchIndex` + `selectMatches` so
+ *  one walk serves every rule that can reach the document. */
+export function findMatches(document, match) {
+    const index = buildMatchIndex(document, new Set([match.key]), new Set(match.under));
+    return selectMatches(index, document, match);
+}

package/dist/migrations/patch.d.ts

@@ -0,0 +1,68 @@
+/** Planning and applying a migration patch.
+ *
+ *  Planning is separate from applying because a patch is ALL-OR-NOTHING at each
+ *  match: a rule whose second operation cannot apply must not leave the first
+ *  one's edit behind. `planPatch` resolves every operation against the tree
+ *  first and returns either a concrete effect list or one refusal; only then
+ *  does an applier run. The same plan drives both appliers — the JSON tree the
+ *  loader hands the analyzer, and the YAML document `telo migrate` writes — so
+ *  the in-memory rewrite and the on-disk repair cannot disagree about what an
+ *  operation means. */
+import type { MigrationOperation, MigrationPath, MigrationRefusal } from "./types.js";
+/** A resolved, unconditionally applicable edit. */
+export type MigrationEffect = {
+    readonly kind: "rename-key";
+    readonly parent: MigrationPath;
+    readonly from: string;
+    readonly to: string;
+} | {
+    readonly kind: "set-value";
+    readonly path: MigrationPath;
+    readonly value: unknown;
+} | {
+    readonly kind: "set-tag";
+    readonly path: MigrationPath;
+    readonly tag: string;
+    readonly source: string;
+} | {
+    readonly kind: "insert-item";
+    readonly path: MigrationPath;
+    readonly index: number;
+    readonly value: unknown;
+} | {
+    readonly kind: "remove-entry";
+    readonly path: MigrationPath;
+};
+export interface PatchPlan {
+    readonly effects: readonly MigrationEffect[];
+    /** Where the matched node lives after the patch. Differs from the matched
+     *  path only when a `rename-key` moved it. */
+    readonly finalPath: MigrationPath;
+    /** The value at the match before anything was applied — the "before" half of
+     *  the generated diagnostic sentence. */
+    readonly before: unknown;
+    /** The value at the match after the patch, or `undefined` for a removal. */
+    readonly after: unknown;
+}
+export type PatchPlanResult = {
+    readonly ok: true;
+    readonly plan: PatchPlan;
+} | {
+    readonly ok: false;
+    readonly refusal: MigrationRefusal;
+};
+/**
+ * Resolve `ops` at `path` against `root`, or refuse.
+ *
+ * Refusing is the design's safety valve: the node is left exactly as the author
+ * wrote it and the ordinary validator reports it with an accurate message,
+ * rather than the migration guessing or dropping a value.
+ */
+export declare function planPatch(root: unknown, path: MigrationPath, ops: readonly MigrationOperation[]): PatchPlanResult;
+/** Apply a plan to the in-memory manifest tree. Mutates in place — the tree is
+ *  the loader's own projection of the document, never the author's file. */
+export declare function applyEffectsToTree(root: unknown, effects: readonly MigrationEffect[]): void;
+/** Dotted rendering of a path, in the form the position index and every
+ *  diagnostic's `data.path` use: `routes[0].handler`. */
+export declare function formatMigrationPath(path: MigrationPath): string;
+//# sourceMappingURL=patch.d.ts.map

package/dist/migrations/patch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patch.d.ts","sourceRoot":"","sources":["../../src/migrations/patch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;uBASuB;AAIvB,OAAO,KAAK,EACV,kBAAkB,EAClB,aAAa,EACb,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,mDAAmD;AACnD,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC3G;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACrF;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACzG;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC/G;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAEpE,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C;kDAC8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC;6CACyC;IACzC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAoD/D;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,aAAa,EACnB,GAAG,EAAE,SAAS,kBAAkB,EAAE,GACjC,eAAe,CA4FjB;AAED;4EAC4E;AAC5E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,IAAI,CA6C3F;AAUD;yDACyD;AACzD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAO/D"}

package/dist/migrations/patch.js

@@ -0,0 +1,236 @@
+/** Planning and applying a migration patch.
+ *
+ *  Planning is separate from applying because a patch is ALL-OR-NOTHING at each
+ *  match: a rule whose second operation cannot apply must not leave the first
+ *  one's edit behind. `planPatch` resolves every operation against the tree
+ *  first and returns either a concrete effect list or one refusal; only then
+ *  does an applier run. The same plan drives both appliers — the JSON tree the
+ *  loader hands the analyzer, and the YAML document `telo migrate` writes — so
+ *  the in-memory rewrite and the on-disk repair cannot disagree about what an
+ *  operation means. */
+import { makeTaggedSentinel } from "@telorun/templating";
+import { deepEquals } from "./match.js";
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The container a path's last segment indexes into, or `undefined` when any
+ *  hop is missing. An empty path has no container — the document root is not a
+ *  mapping entry and no operation targets it. */
+function containerOf(root, path) {
+    if (path.length === 0)
+        return undefined;
+    let current = root;
+    for (let i = 0; i < path.length - 1; i++) {
+        const segment = path[i];
+        if (typeof segment === "number") {
+            if (!Array.isArray(current))
+                return undefined;
+            current = current[segment];
+        }
+        else {
+            if (!isPlainObject(current))
+                return undefined;
+            current = current[segment];
+        }
+    }
+    return { container: current, key: path[path.length - 1] };
+}
+function readAt(root, path) {
+    const located = containerOf(root, path);
+    if (!located)
+        return { found: false, value: undefined };
+    const { container, key } = located;
+    if (typeof key === "number") {
+        if (!Array.isArray(container) || key < 0 || key >= container.length) {
+            return { found: false, value: undefined };
+        }
+        return { found: true, value: container[key] };
+    }
+    if (!isPlainObject(container) || !Object.hasOwn(container, key)) {
+        return { found: false, value: undefined };
+    }
+    return { found: true, value: container[key] };
+}
+/** A scalar YAML can carry behind a tag, and the only thing `set-tag` and
+ *  `qualify` can operate on. */
+function scalarSource(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    return undefined;
+}
+/**
+ * Resolve `ops` at `path` against `root`, or refuse.
+ *
+ * Refusing is the design's safety valve: the node is left exactly as the author
+ * wrote it and the ordinary validator reports it with an accurate message,
+ * rather than the migration guessing or dropping a value.
+ */
+export function planPatch(root, path, ops) {
+    const initial = readAt(root, path);
+    if (!initial.found)
+        return { ok: false, refusal: "path-not-found" };
+    const effects = [];
+    let currentPath = path;
+    let currentValue = initial.value;
+    let removed = false;
+    for (const op of ops) {
+        if (removed)
+            return { ok: false, refusal: "path-not-found" };
+        switch (op.op) {
+            case "rename-key": {
+                const located = containerOf(root, currentPath);
+                const key = located?.key;
+                if (!located || typeof key !== "string" || !isPlainObject(located.container)) {
+                    return { ok: false, refusal: "not-a-mapping-entry" };
+                }
+                if (op.to !== key && Object.hasOwn(located.container, op.to)) {
+                    // Refuse rather than replace: the occupied destination holds a value
+                    // the author wrote.
+                    return { ok: false, refusal: "destination-occupied" };
+                }
+                const parent = currentPath.slice(0, -1);
+                effects.push({ kind: "rename-key", parent, from: key, to: op.to });
+                currentPath = [...parent, op.to];
+                break;
+            }
+            case "set-value": {
+                let next;
+                if (op.qualify !== undefined) {
+                    if (typeof currentValue !== "string") {
+                        return { ok: false, refusal: "malformed-value" };
+                    }
+                    if (currentValue.startsWith(op.qualify)) {
+                        return { ok: false, refusal: "nothing-to-rewrite" };
+                    }
+                    next = `${op.qualify}${currentValue}`;
+                }
+                else {
+                    // Same refusal as `qualify`'s, and for the same reason: a rule should
+                    // match only the legacy spelling, so a write of the value already
+                    // there means the matcher was too wide. Reporting it would be a
+                    // deprecation reading `type: string is now written type: string`.
+                    if (deepEquals(op.value, currentValue)) {
+                        return { ok: false, refusal: "nothing-to-rewrite" };
+                    }
+                    next = op.value;
+                }
+                effects.push({ kind: "set-value", path: currentPath, value: next });
+                currentValue = next;
+                break;
+            }
+            case "set-tag": {
+                const source = scalarSource(currentValue);
+                if (source === undefined)
+                    return { ok: false, refusal: "not-a-scalar" };
+                effects.push({ kind: "set-tag", path: currentPath, tag: op.tag, source });
+                currentValue = makeTaggedSentinel(op.tag, source);
+                break;
+            }
+            case "insert-item": {
+                if (!Array.isArray(currentValue))
+                    return { ok: false, refusal: "not-a-sequence" };
+                const index = op.at === undefined
+                    ? currentValue.length
+                    : Math.max(0, Math.min(op.at, currentValue.length));
+                effects.push({ kind: "insert-item", path: currentPath, index, value: op.value });
+                currentValue = [
+                    ...currentValue.slice(0, index),
+                    op.value,
+                    ...currentValue.slice(index),
+                ];
+                break;
+            }
+            case "remove-entry": {
+                effects.push({ kind: "remove-entry", path: currentPath });
+                currentValue = undefined;
+                removed = true;
+                break;
+            }
+        }
+    }
+    return {
+        ok: true,
+        plan: {
+            effects,
+            finalPath: currentPath,
+            before: initial.value,
+            after: removed ? undefined : currentValue,
+        },
+    };
+}
+/** Apply a plan to the in-memory manifest tree. Mutates in place — the tree is
+ *  the loader's own projection of the document, never the author's file. */
+export function applyEffectsToTree(root, effects) {
+    for (const effect of effects) {
+        switch (effect.kind) {
+            case "rename-key": {
+                const parent = effect.parent.length === 0 ? root : readAt(root, effect.parent).value;
+                if (!isPlainObject(parent))
+                    continue;
+                // Rebuilt in place so the renamed key keeps its position. Key order is
+                // what a round-trip consumer and a rendered diff both read.
+                const entries = Object.entries(parent);
+                for (const [key] of entries)
+                    delete parent[key];
+                for (const [key, value] of entries) {
+                    parent[key === effect.from ? effect.to : key] = value;
+                }
+                break;
+            }
+            case "set-value":
+            case "set-tag": {
+                const located = containerOf(root, effect.path);
+                if (!located)
+                    continue;
+                const next = effect.kind === "set-value"
+                    ? effect.value
+                    : makeTaggedSentinel(effect.tag, effect.source);
+                writeAt(located.container, located.key, next);
+                break;
+            }
+            case "insert-item": {
+                const target = readAt(root, effect.path).value;
+                if (!Array.isArray(target))
+                    continue;
+                target.splice(effect.index, 0, effect.value);
+                break;
+            }
+            case "remove-entry": {
+                const located = containerOf(root, effect.path);
+                if (!located)
+                    continue;
+                if (typeof located.key === "number") {
+                    if (Array.isArray(located.container))
+                        located.container.splice(located.key, 1);
+                }
+                else if (isPlainObject(located.container)) {
+                    delete located.container[located.key];
+                }
+                break;
+            }
+        }
+    }
+}
+function writeAt(container, key, value) {
+    if (typeof key === "number") {
+        if (Array.isArray(container))
+            container[key] = value;
+        return;
+    }
+    if (isPlainObject(container))
+        container[key] = value;
+}
+/** Dotted rendering of a path, in the form the position index and every
+ *  diagnostic's `data.path` use: `routes[0].handler`. */
+export function formatMigrationPath(path) {
+    let out = "";
+    for (const segment of path) {
+        if (typeof segment === "number")
+            out += `[${segment}]`;
+        else
+            out += out.length === 0 ? segment : `.${segment}`;
+    }
+    return out;
+}

package/dist/migrations/provenance.d.ts

@@ -0,0 +1,25 @@
+/** Path provenance — part of the driver's contract, not an optional extra.
+ *
+ *  `resolveRange` looks a diagnostic's dotted path up in a position index built
+ *  from the RAW file, then falls back to the parent's key or value range. Every
+ *  rewrite that existed before migrations preserved paths; a `rename-key` is
+ *  the first that does not, and without a remap every downstream diagnostic on
+ *  that node degrades to a parent squiggle — with a `DiagnosticFix` over a
+ *  single-line parent value writing a whole value across it.
+ *
+ *  So each rewrite records the legacy path it matched alongside the migrated
+ *  one, and diagnostics are remapped through that record before position
+ *  resolution. This is the generalization of `rewriteSyntheticOrigins`, which
+ *  already rewrites `data.path` so lookups resolve after
+ *  `normalizeInlineResources` has moved a resource. */
+import type { AnalysisDiagnostic } from "../types.js";
+import type { LoadedGraph } from "../loaded-types.js";
+/**
+ * Rewrite every diagnostic's `data.path` from the migrated spelling back to
+ * what the author wrote, so position lookups against the raw file resolve.
+ *
+ * A no-op — and returns the input array — when nothing in the graph was
+ * migrated, which is the overwhelmingly common case.
+ */
+export declare function remapMigratedPaths(graph: LoadedGraph, diagnostics: readonly AnalysisDiagnostic[]): AnalysisDiagnostic[];
+//# sourceMappingURL=provenance.d.ts.map

package/dist/migrations/provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../../src/migrations/provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;uDAauD;AAEvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAsHtD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,WAAW,EAClB,WAAW,EAAE,SAAS,kBAAkB,EAAE,GACzC,kBAAkB,EAAE,CAsBtB"}