@telorun/analyzer 0.57.0 → 0.58.0

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);
+    }
+}

package/dist/migrations/types.d.ts

@@ -0,0 +1,115 @@
+/** Manifest migrations — the entry vocabulary.
+ *
+ *  A migration is a MATCHER plus a PATCH. The two halves are at different
+ *  maturities and that is deliberate (`plans/manifest-migrations.md`):
+ *
+ *  - The **patch** names what it targets. Every operation has a known YAML edit
+ *    form, which is what makes a migration applicable to a *file* at all and
+ *    what lets the driver derive whether a quick fix exists — read straight off
+ *    the verb, never declared by the author.
+ *  - The **matcher** selects every occurrence of a legacy spelling, which is
+ *    the half a plain patch format has none of (see `match.ts`).
+ *
+ *  BOTH halves are data, and an entry contains no code at all. That is what
+ *  lets one entry file be read by every kernel: a predicate expressed in one
+ *  language would mean one artifact is read two ways, invisibly, since a
+ *  migration that succeeds is silent. A migration that does not fit is a signal
+ *  to extend the vocabulary, never to hand-write a rewrite. */
+import type { DiagnosticSeverity } from "../types.js";
+import type { MigrationMatch } from "./match.js";
+/** A location inside one manifest document. Segments are mapping keys
+ *  (strings) and sequence indices (numbers) — the same shape `Document.getIn`
+ *  takes, so the tree applier and the YAML applier address a node identically. */
+export type MigrationPath = ReadonlyArray<string | number>;
+/** Rename the matched mapping entry's KEY, within its own mapping. Deliberately
+ *  not JSON Patch's `move`, which relocates a value anywhere in a document
+ *  across parents and replaces an occupied destination. This refuses an
+ *  occupied destination instead — silently discarding a value the author wrote
+ *  is exactly what the leave-it-alone invariant exists to prevent. */
+export interface RenameKeyOperation {
+    readonly op: "rename-key";
+    readonly to: string;
+}
+/** Replace the value at the matched location.
+ *
+ *  Exactly one of `value` / `qualify` is supplied. `qualify` prefixes the
+ *  existing string — the shape a spelling rewrite that alias-qualifies a bare
+ *  name needs, which a literal `value` cannot express because a patch is static
+ *  data and cannot read the match. */
+export interface SetValueOperation {
+    readonly op: "set-value";
+    readonly value?: unknown;
+    readonly qualify?: string;
+}
+/** Put the matched scalar behind a templating tag (`!cel`, `!ref`, …). `tag` is
+ *  the engine name without its `!`. */
+export interface SetTagOperation {
+    readonly op: "set-tag";
+    readonly tag: string;
+}
+/** Insert an item into the matched sequence. `at` defaults to the end. */
+export interface InsertItemOperation {
+    readonly op: "insert-item";
+    readonly value: unknown;
+    readonly at?: number;
+}
+/** Remove the matched mapping entry or sequence item. */
+export interface RemoveEntryOperation {
+    readonly op: "remove-entry";
+}
+/** The closed operation vocabulary. Named for what each TARGETS, so the target
+ *  is never inferred from which parameter happens to be present and the
+ *  quick-fix question reads off the name. */
+export type MigrationOperation = RenameKeyOperation | SetValueOperation | SetTagOperation | InsertItemOperation | RemoveEntryOperation;
+export declare const MIGRATION_OPS: readonly ["rename-key", "set-value", "set-tag", "insert-item", "remove-entry"];
+/** One legacy spelling and the edit that replaces it. */
+export interface MigrationRule {
+    /** Which nodes this rule rewrites, resolved against the frozen pre-migration
+     *  tree. Declarative — see `match.ts`. */
+    readonly match: MigrationMatch;
+    /** Applied in order at each match. A patch that cannot apply in full leaves
+     *  the node untouched. */
+    readonly patch: readonly MigrationOperation[];
+}
+/** One deprecation story. May carry several rules — the value-type unification
+ *  changed three spellings but tells the author one thing, which is why the
+ *  rationale is entry-level and a mechanical description is not. */
+export interface MigrationEntry {
+    /** Stable identifier. Names which migration fired; docs list them. */
+    readonly id: string;
+    /** Diagnostic code reported for every rewrite this entry makes. */
+    readonly code: string;
+    readonly severity: DiagnosticSeverity;
+    /** A sentence or two of rationale — the one part the driver cannot generate,
+     *  and the part that makes a deprecation actionable rather than mysterious.
+     *  Never a clause of the generated sentence. */
+    readonly reason: string;
+    readonly rules: readonly MigrationRule[];
+}
+/** One applied rewrite. Path provenance is part of the driver's contract:
+ *  diagnostics are remapped through `legacyPath` before position resolution,
+ *  and `telo migrate` reads its edit target from the same record — the location
+ *  in the author's file, not the post-rewrite path. */
+export interface MigrationRewrite {
+    readonly entryId: string;
+    readonly code: string;
+    readonly severity: DiagnosticSeverity;
+    readonly documentIndex: number;
+    /** Dotted path (`a.b[0].c`) as the AUTHOR wrote it — the key into a
+     *  position index built from the raw file. */
+    readonly legacyPath: string;
+    /** Dotted path after the rewrite. Equal to `legacyPath` unless a
+     *  `rename-key` moved it. */
+    readonly migratedPath: string;
+    /** Human-readable description of what changed, generated by the driver. */
+    readonly summary: string;
+}
+/** Why a matched patch was refused. A migration that cannot rewrite leaves the
+ *  node untouched for the ordinary validator to reject — never guessing, never
+ *  dropping. */
+export type MigrationRefusal = "path-not-found" | "destination-occupied" | "not-a-mapping-entry" | "not-a-sequence" | "not-a-scalar" | "malformed-value"
+/** The value is already what the patch would write. A rule should match only
+ *  the legacy spelling, so this means its matcher was too wide — refusing
+ *  keeps that from surfacing as a deprecation the author cannot act on. */
+ | "nothing-to-rewrite";
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/migrations/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;+DAgB+D;AAE/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;kFAEkF;AAClF,MAAM,MAAM,aAAa,GAAG,aAAa,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;AAE3D;;;;sEAIsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAC;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;;;;sCAKsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;uCACuC;AACvC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,yDAAyD;AACzD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC;CAC7B;AAED;;6CAE6C;AAC7C,MAAM,MAAM,kBAAkB,GAC1B,kBAAkB,GAClB,iBAAiB,GACjB,eAAe,GACf,mBAAmB,GACnB,oBAAoB,CAAC;AAEzB,eAAO,MAAM,aAAa,gFAMhB,CAAC;AAEX,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B;8CAC0C;IAC1C,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B;8BAC0B;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAC/C;AAED;;oEAEoE;AACpE,MAAM,WAAW,cAAc;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC;;oDAEgD;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;CAC1C;AAED;;;uDAGuD;AACvD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;kDAC8C;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;iCAC6B;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;gBAEgB;AAChB,MAAM,MAAM,gBAAgB,GACxB,gBAAgB,GAChB,sBAAsB,GACtB,qBAAqB,GACrB,gBAAgB,GAChB,cAAc,GACd,iBAAiB;AACnB;;2EAE2E;GACzE,oBAAoB,CAAC"}

package/dist/migrations/types.js

@@ -0,0 +1,24 @@
+/** Manifest migrations — the entry vocabulary.
+ *
+ *  A migration is a MATCHER plus a PATCH. The two halves are at different
+ *  maturities and that is deliberate (`plans/manifest-migrations.md`):
+ *
+ *  - The **patch** names what it targets. Every operation has a known YAML edit
+ *    form, which is what makes a migration applicable to a *file* at all and
+ *    what lets the driver derive whether a quick fix exists — read straight off
+ *    the verb, never declared by the author.
+ *  - The **matcher** selects every occurrence of a legacy spelling, which is
+ *    the half a plain patch format has none of (see `match.ts`).
+ *
+ *  BOTH halves are data, and an entry contains no code at all. That is what
+ *  lets one entry file be read by every kernel: a predicate expressed in one
+ *  language would mean one artifact is read two ways, invisibly, since a
+ *  migration that succeeds is silent. A migration that does not fit is a signal
+ *  to extend the vocabulary, never to hand-write a rewrite. */
+export const MIGRATION_OPS = [
+    "rename-key",
+    "set-value",
+    "set-tag",
+    "insert-item",
+    "remove-entry",
+];

package/dist/migrations/yaml-edit.d.ts

@@ -0,0 +1,21 @@
+/** Rendering a migration plan back into the author's YAML.
+ *
+ *  Edits are BYTE SPLICES computed from the parsed document's node ranges, not
+ *  `Document.toString()`. That is `cli/nodejs/src/commands/upgrade.ts`'s
+ *  precedent and it is load-bearing here for the same reason: re-serializing
+ *  re-folds block scalars, drops quote-style hints and reflows long strings, so
+ *  a one-key repair would arrive as a whole-file diff. Everything outside the
+ *  spliced ranges is byte-identical to the input.
+ *
+ *  The document is parsed with the same `defaultCustomTags()` every other
+ *  parse site uses, so a tagged scalar is a node here exactly as it is in the
+ *  loader's tree. */
+import { type Document } from "yaml";
+import { type TextEdit } from "../yaml-source-edit.js";
+import type { MigrationEffect } from "./patch.js";
+export { applyTextEdits, type TextEdit } from "../yaml-source-edit.js";
+/** One YAML edit per effect, or `undefined` when the effect cannot be written
+ *  into this file — the same all-or-nothing rule the tree side has, so a
+ *  partially applied patch never reaches disk. */
+export declare function planTextEdits(doc: Document, text: string, effects: readonly MigrationEffect[]): TextEdit[] | undefined;
+//# sourceMappingURL=yaml-edit.d.ts.map

package/dist/migrations/yaml-edit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml-edit.d.ts","sourceRoot":"","sources":["../../src/migrations/yaml-edit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;qBAWqB;AAErB,OAAO,EAAkC,KAAK,QAAQ,EAAa,MAAM,MAAM,CAAC;AAChF,OAAO,EAAwB,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGlD,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AA2CvE;;kDAEkD;AAClD,wBAAgB,aAAa,CAC3B,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,SAAS,eAAe,EAAE,GAClC,QAAQ,EAAE,GAAG,SAAS,CAkFxB"}