@telorun/analyzer 0.56.1 → 0.58.0

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"}

package/dist/migrations/provenance.js

@@ -0,0 +1,118 @@
+/** 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. */
+function identityKey(kind, name) {
+    return `${kind}\0${name}`;
+}
+function push(index, key, record) {
+    const bucket = index.get(key);
+    if (bucket)
+        bucket.push(record);
+    else
+        index.set(key, [record]);
+}
+function buildIndex(graph) {
+    const byFile = new Map();
+    const byIdentity = new Map();
+    let size = 0;
+    for (const mod of graph.modules.values()) {
+        for (const file of [mod.owner, ...mod.partials]) {
+            for (const rewrite of file.migrations.rewrites) {
+                const manifest = file.manifests[rewrite.documentIndex];
+                const kind = typeof manifest?.kind === "string" ? manifest.kind : undefined;
+                const name = typeof manifest?.metadata?.name === "string" ? manifest.metadata.name : undefined;
+                const record = { source: file.source, kind, name, rewrite };
+                push(byFile, file.source, record);
+                if (kind !== undefined && name !== undefined) {
+                    push(byIdentity, identityKey(kind, name), record);
+                }
+                size++;
+            }
+        }
+    }
+    return { byFile, byIdentity, size };
+}
+/** The records a diagnostic may be remapped against, narrowed by whichever
+ *  routing facts it carries. `undefined` means "cannot be narrowed to one
+ *  file", the one case where no answer is better than a guess. */
+function candidatesFor(index, filePath, kind, name) {
+    if (kind !== undefined && name !== undefined) {
+        const records = index.byIdentity.get(identityKey(kind, name));
+        if (!records)
+            return undefined;
+        if (filePath !== undefined)
+            return records.filter((r) => r.source === filePath);
+        // Several files declare this identity and the diagnostic names none of
+        // them. Guessing would move a squiggle onto an unrelated node, which is
+        // worse than the parent-squiggle fallback leaving it where it is.
+        return new Set(records.map((r) => r.source)).size > 1 ? undefined : records;
+    }
+    if (filePath !== undefined)
+        return index.byFile.get(filePath);
+    return undefined;
+}
+/** `path` with the longest matching migrated prefix swapped back to the legacy
+ *  spelling, or `undefined` when no rewrite touched it. Longest-prefix wins so
+ *  a rewrite nested inside another resolves against the innermost one.
+ *
+ *  Two records covering the same path with DIFFERENT legacy spellings are
+ *  ambiguous — a file-scoped candidate set spans every document in the file,
+ *  and two documents can share a path. Refusing beats picking one. */
+function remapPath(path, records) {
+    let best;
+    let ambiguous = false;
+    for (const { rewrite } of records) {
+        const migrated = rewrite.migratedPath;
+        if (migrated === rewrite.legacyPath)
+            continue;
+        const covers = path === migrated || path.startsWith(`${migrated}.`) || path.startsWith(`${migrated}[`);
+        if (!covers)
+            continue;
+        if (!best || migrated.length > best.migratedPath.length) {
+            best = rewrite;
+            ambiguous = false;
+        }
+        else if (migrated.length === best.migratedPath.length &&
+            rewrite.legacyPath !== best.legacyPath) {
+            ambiguous = true;
+        }
+    }
+    if (!best || ambiguous)
+        return undefined;
+    return best.legacyPath + path.slice(best.migratedPath.length);
+}
+/**
+ * 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 function remapMigratedPaths(graph, diagnostics) {
+    const index = buildIndex(graph);
+    if (index.size === 0)
+        return [...diagnostics];
+    return diagnostics.map((d) => {
+        const data = d.data;
+        if (typeof data?.path !== "string")
+            return d;
+        const records = candidatesFor(index, typeof data.filePath === "string" ? data.filePath : undefined, typeof data.resource?.kind === "string" ? data.resource.kind : undefined, typeof data.resource?.name === "string" ? data.resource.name : undefined);
+        if (!records || records.length === 0)
+            return d;
+        const remapped = remapPath(data.path, records);
+        if (remapped === undefined || remapped === data.path)
+            return d;
+        return { ...d, data: { ...data, path: remapped } };
+    });
+}

package/dist/migrations/registry.d.ts

@@ -0,0 +1,35 @@
+/** The core migration set — entries that ship with the analyzer and may match
+ *  any node.
+ *
+ *  **The set is data, not code.** One JSON file per entry, canonical at
+ *  `analyzer/migrations/`, read as one lexically ordered list: adding a
+ *  migration is one file, and retiring one is deleting it. Nothing here lists
+ *  the entries — TypeScript has no glob import, so the barrel beside the copies
+ *  is emitted from the same directory listing that produced them. A
+ *  hand-maintained list was the one place this mechanism could fail silently:
+ *  add a file, forget the import, and the migration never fires, which looks
+ *  exactly like one that ran.
+ *
+ *  The files live beside the language implementations rather than inside any
+ *  one of them because every kernel must apply the IDENTICAL rewrite — a
+ *  rewrite added to one side would mean one artifact means two things on two
+ *  kernels, invisibly, since a migration that succeeds is silent. Only
+ *  `analyzer/nodejs` reads them today — the Rust reader is planned, and until
+ *  it lands the Rust kernel applies NO migration, so a legacy spelling it
+ *  cannot otherwise interpret fails there rather than being rewritten. When it
+ *  lands it will embed these files with `include_str!`; a Go half would use
+ *  `//go:embed`. JSON rather than YAML for one reason: it is the only format
+ *  all three embed with no generation step, because TypeScript's only native
+ *  embed is `resolveJsonModule`. The copy under `./entries/` is made by the
+ *  analyzer's `prepare` (`scripts/copy-migration-entries.mjs`) — identical
+ *  bytes, so no entry's MEANING is ever derived from anything.
+ *
+ *  **Entries carry no version stamp.** "Can this be deleted?" turns on whether
+ *  any published artifact still carries the legacy spelling, which the
+ *  artifact's own release version cannot answer — the hub can, since it caches
+ *  every tracked module version's `telo.yaml`. A stamp would record when an
+ *  entry was written, which git already does, while looking like an answer to a
+ *  question it does not address. */
+import type { MigrationEntry } from "./types.js";
+export declare const CORE_MIGRATIONS: readonly MigrationEntry[];
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/migrations/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oCA+BoC;AAIpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,eAAO,MAAM,eAAe,EAAE,SAAS,cAAc,EAEpD,CAAC"}

package/dist/migrations/registry.js

@@ -0,0 +1,35 @@
+/** The core migration set — entries that ship with the analyzer and may match
+ *  any node.
+ *
+ *  **The set is data, not code.** One JSON file per entry, canonical at
+ *  `analyzer/migrations/`, read as one lexically ordered list: adding a
+ *  migration is one file, and retiring one is deleting it. Nothing here lists
+ *  the entries — TypeScript has no glob import, so the barrel beside the copies
+ *  is emitted from the same directory listing that produced them. A
+ *  hand-maintained list was the one place this mechanism could fail silently:
+ *  add a file, forget the import, and the migration never fires, which looks
+ *  exactly like one that ran.
+ *
+ *  The files live beside the language implementations rather than inside any
+ *  one of them because every kernel must apply the IDENTICAL rewrite — a
+ *  rewrite added to one side would mean one artifact means two things on two
+ *  kernels, invisibly, since a migration that succeeds is silent. Only
+ *  `analyzer/nodejs` reads them today — the Rust reader is planned, and until
+ *  it lands the Rust kernel applies NO migration, so a legacy spelling it
+ *  cannot otherwise interpret fails there rather than being rewritten. When it
+ *  lands it will embed these files with `include_str!`; a Go half would use
+ *  `//go:embed`. JSON rather than YAML for one reason: it is the only format
+ *  all three embed with no generation step, because TypeScript's only native
+ *  embed is `resolveJsonModule`. The copy under `./entries/` is made by the
+ *  analyzer's `prepare` (`scripts/copy-migration-entries.mjs`) — identical
+ *  bytes, so no entry's MEANING is ever derived from anything.
+ *
+ *  **Entries carry no version stamp.** "Can this be deleted?" turns on whether
+ *  any published artifact still carries the legacy spelling, which the
+ *  artifact's own release version cannot answer — the hub can, since it caches
+ *  every tracked module version's `telo.yaml`. A stamp would record when an
+ *  entry was written, which git already does, while looking like an answer to a
+ *  question it does not address. */
+import { parseMigrationEntry } from "./entry-data.js";
+import { MIGRATION_ENTRY_FILES } from "./entries/index.js";
+export const CORE_MIGRATIONS = MIGRATION_ENTRY_FILES.map(([file, data]) => parseMigrationEntry(file, data));

package/dist/migrations/report.d.ts

@@ -0,0 +1,28 @@
+/** How a rewrite is REPORTED — the provenance record and the diagnostic.
+ *
+ *  Split from the driver because the two answer different questions: the driver
+ *  owns the guarantees (one pass, a frozen match set, all-or-nothing patches,
+ *  refusal rather than a guess), while everything here is about telling an
+ *  author what happened. Nothing in this file can change what a migration does.
+ *
+ *  **A diagnostic composes in three parts and the entry writes only one.** What
+ *  changed and how to apply it are generated identically for every entry, from
+ *  the matched key and value, the replacement, and the operation verbs. What
+ *  the driver cannot know is *why*, which is the part that makes a deprecation
+ *  actionable rather than mysterious — so an entry supplies `reason`, and never
+ *  a clause of the generated sentence. */
+import type { ResourceManifest } from "@telorun/sdk";
+import { type PatchPlan } from "./patch.js";
+import type { MigrationEntry, MigrationOperation, MigrationPath, MigrationRewrite } from "./types.js";
+import type { AnalysisDiagnostic } from "../types.js";
+/** One patch that applied, as the reporting side needs to see it. */
+export interface AppliedPatch {
+    readonly entry: MigrationEntry;
+    readonly documentIndex: number;
+    readonly matched: MigrationPath;
+    readonly plan: PatchPlan;
+    readonly ops: readonly MigrationOperation[];
+}
+export declare function toRewrite(applied: AppliedPatch): MigrationRewrite;
+export declare function toDiagnostic(applied: AppliedPatch, rewrite: MigrationRewrite, source: string, manifests: ReadonlyArray<ResourceManifest | null>): AnalysisDiagnostic;
+//# sourceMappingURL=report.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/migrations/report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;0CAY0C;AAE1C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,EAA6C,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AACvF,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,gBAAgB,EACjB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,kBAAkB,EAAiB,MAAM,aAAa,CAAC;AAErE,qEAAqE;AACrE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAC7C;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,YAAY,GAAG,gBAAgB,CAUjE;AAED,wBAAgB,YAAY,CAC1B,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,aAAa,CAAC,gBAAgB,GAAG,IAAI,CAAC,GAChD,kBAAkB,CA+BpB"}

package/dist/migrations/report.js

@@ -0,0 +1,144 @@
+/** How a rewrite is REPORTED — the provenance record and the diagnostic.
+ *
+ *  Split from the driver because the two answer different questions: the driver
+ *  owns the guarantees (one pass, a frozen match set, all-or-nothing patches,
+ *  refusal rather than a guess), while everything here is about telling an
+ *  author what happened. Nothing in this file can change what a migration does.
+ *
+ *  **A diagnostic composes in three parts and the entry writes only one.** What
+ *  changed and how to apply it are generated identically for every entry, from
+ *  the matched key and value, the replacement, and the operation verbs. What
+ *  the driver cannot know is *why*, which is the part that makes a deprecation
+ *  actionable rather than mysterious — so an entry supplies `reason`, and never
+ *  a clause of the generated sentence. */
+import { isTaggedSentinel } from "@telorun/templating";
+import { formatMigrationPath } from "./patch.js";
+export function toRewrite(applied) {
+    return {
+        entryId: applied.entry.id,
+        code: applied.entry.code,
+        severity: applied.entry.severity,
+        documentIndex: applied.documentIndex,
+        legacyPath: formatMigrationPath(applied.matched),
+        migratedPath: formatMigrationPath(applied.plan.finalPath),
+        summary: describeChange(applied),
+    };
+}
+export function toDiagnostic(applied, rewrite, source, manifests) {
+    const fix = deriveFix(applied);
+    const closing = fix
+        ? "Run `telo migrate` to apply it."
+        : `no quick fix (${refusalPhrase(applied.ops)}) — run \`telo migrate\``;
+    const manifest = manifests[applied.documentIndex];
+    const kind = manifest?.kind;
+    const name = manifest?.metadata?.name;
+    return {
+        severity: applied.entry.severity,
+        code: applied.entry.code,
+        source: "telo-analyzer",
+        message: `${rewrite.summary}\n${applied.entry.reason}\n${closing}`,
+        data: {
+            filePath: source,
+            // The AUTHOR's path, not the post-rewrite one: the position index is
+            // built from the raw file and knows only the spelling that is in it.
+            path: rewrite.legacyPath,
+            ...(typeof kind === "string" && typeof name === "string"
+                ? { resource: { kind, name } }
+                : {}),
+            ...(fix ? { fix } : {}),
+            migration: {
+                id: applied.entry.id,
+                legacyPath: rewrite.legacyPath,
+                migratedPath: rewrite.migratedPath,
+            },
+        },
+    };
+}
+/**
+ * Whether a quick fix exists is DERIVED from the operations, never declared.
+ *
+ * `DiagnosticFix` is a whole-value `replacement` written over a value node's
+ * span, and it promises a repair applicable without review. A lone `set-value`
+ * producing a scalar is exactly that. Anything else — a key rename, a tag, a
+ * collection edit, a structured value — has no honest whole-value form, and the
+ * diagnostic says so rather than offering a repair that would corrupt the file.
+ * The derivation is total, so a migration never silently lacks one.
+ */
+function deriveFix(applied) {
+    if (applied.ops.length !== 1)
+        return undefined;
+    const only = applied.ops[0];
+    if (only.op !== "set-value")
+        return undefined;
+    const value = applied.plan.after;
+    if (typeof value === "string")
+        return { replacement: value };
+    if (typeof value === "number" || typeof value === "boolean" || value === null) {
+        return { replacement: String(value) };
+    }
+    return undefined;
+}
+function refusalPhrase(ops) {
+    for (const op of ops) {
+        switch (op.op) {
+            case "rename-key":
+                return "renames a key";
+            case "set-tag":
+                return "adds a tag";
+            case "insert-item":
+                return "inserts an item";
+            case "remove-entry":
+                return "removes an entry";
+            default:
+                break;
+        }
+    }
+    return "writes a structured value";
+}
+/** Only the items an `insert-item` added, narrowed by the effect's own kind so
+ *  the value is read off a typed field rather than cast out of a union. */
+function insertedValues(effects) {
+    const values = [];
+    for (const effect of effects) {
+        if (effect.kind !== "insert-item")
+            return undefined;
+        values.push(effect.value);
+    }
+    return values.length > 0 ? values : undefined;
+}
+/** The generated "what changed" sentence — the half no entry writes. */
+function describeChange(applied) {
+    const legacyKey = lastSegment(applied.matched);
+    const migratedKey = lastSegment(applied.plan.finalPath);
+    const { before, after, effects } = applied.plan;
+    if (after === undefined && effects.some((e) => e.kind === "remove-entry")) {
+        return `\`${legacyKey}\` is no longer used.`;
+    }
+    const inserted = insertedValues(effects);
+    if (inserted) {
+        return `\`${formatMigrationPath(applied.matched)}\` gains \`${inserted
+            .map(renderValue)
+            .join("`, `")}\`.`;
+    }
+    return `\`${legacyKey}: ${renderValue(before)}\` is now written \`${migratedKey}: ${renderValue(after)}\`.`;
+}
+function lastSegment(path) {
+    const last = path[path.length - 1];
+    return typeof last === "number" ? `[${last}]` : String(last ?? "");
+}
+function renderValue(value) {
+    if (typeof value === "string")
+        return value;
+    if (value === null || value === undefined)
+        return "null";
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (isTaggedSentinel(value))
+        return `!${value.engine} ${value.source}`;
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}