@telorun/analyzer 0.57.0 → 0.58.0

package/src/migrations/driver.ts

@@ -0,0 +1,262 @@
+/** The migration driver — one pass, one set of guarantees.
+ *
+ *  **Composition is the driver's guarantee, not each entry's proof
+ *  obligation.** The match set is frozen against the pre-migration tree, so no
+ *  rule can match a node another rule produced; rules within an entry apply in
+ *  order at each match; entries never see one another's output. That matters
+ *  once core and module entries are aggregated from different parties, where
+ *  "it happens to work" is not determinism. Idempotency then follows from the
+ *  driver rather than from every author getting it right: a rule matches only
+ *  the legacy spelling, and re-running finds nothing.
+ *
+ *  How a rewrite is REPORTED — the provenance record and the diagnostic — is
+ *  `report.ts`. Nothing there can change what a migration does, and nothing
+ *  here decides how it reads. */
+
+import type { ResourceManifest } from "@telorun/sdk";
+import type { Document } from "yaml";
+import {
+  applyEffectsToTree,
+  formatMigrationPath,
+  planPatch,
+  type MigrationEffect,
+} from "./patch.js";
+import { applyTextEdits, planTextEdits, type TextEdit } from "./yaml-edit.js";
+import { applicableRules, buildMatchIndex, selectMatches } from "./match.js";
+import { CORE_MIGRATIONS } from "./registry.js";
+import { toDiagnostic, toRewrite, type AppliedPatch } from "./report.js";
+import type {
+  MigrationEntry,
+  MigrationOperation,
+  MigrationPath,
+  MigrationRewrite,
+} from "./types.js";
+import type { AnalysisDiagnostic } from "../types.js";
+
+/** What one file's migration produced. */
+export interface FileMigrations {
+  /** One record per applied rewrite, in application order. Empty when the file
+   *  carried no legacy spelling — the overwhelmingly common case. */
+  readonly rewrites: readonly MigrationRewrite[];
+  /** One diagnostic per rewrite. Whether they are SURFACED is the graph's
+   *  decision: a migration rewrites always, because the runtime must read
+   *  artifacts published years ago, but reports only for the entry's own
+   *  modules, because a published dependency is not the consumer's to fix. */
+  readonly diagnostics: readonly AnalysisDiagnostic[];
+}
+
+export const NO_MIGRATIONS: FileMigrations = { rewrites: [], diagnostics: [] };
+
+/**
+ * Run `entries` over one file's parsed documents, mutating `manifests` in
+ * place. Returns the provenance records and their diagnostics.
+ *
+ * The manifests are the loader's own projection of the file, never the
+ * author's text — nothing here can reach disk.
+ */
+export function migrateManifests(args: {
+  source: string;
+  manifests: Array<ResourceManifest | null>;
+  entries?: readonly MigrationEntry[];
+}): FileMigrations {
+  const entries = args.entries ?? CORE_MIGRATIONS;
+  if (entries.length === 0) return NO_MIGRATIONS;
+
+  const applied = applyAll(args.manifests, entries);
+  if (applied.length === 0) return NO_MIGRATIONS;
+
+  const rewrites = applied.map((a) => toRewrite(a));
+  const diagnostics = applied.map((a, i) =>
+    toDiagnostic(a, rewrites[i]!, args.source, args.manifests),
+  );
+  return { rewrites, diagnostics };
+}
+
+/**
+ * Migrate the author's YAML instead of the loader's tree — the operation
+ * `telo migrate` is the reference application of.
+ *
+ * `manifests` must be the RAW (un-migrated) projection of `documents`, since
+ * the matchers select legacy spellings. Returns `null` when nothing matched, so
+ * a caller can leave an untouched file untouched rather than rewriting
+ * identical bytes.
+ *
+ * `unwritable` names every rewrite the tree accepted but the TEXT could not
+ * express. The two appliers can disagree only in this direction, and the
+ * disagreement has to be reported: the diagnostic that sent the author here
+ * says "run `telo migrate`", so a location this silently skipped would keep
+ * warning with no way to act on it.
+ */
+export function migrateFileText(args: {
+  source: string;
+  text: string;
+  documents: readonly Document[];
+  manifests: ReadonlyArray<ResourceManifest | null>;
+  entries?: readonly MigrationEntry[];
+}): {
+  text: string;
+  rewrites: MigrationRewrite[];
+  unwritable: MigrationRewrite[];
+} | null {
+  const entries = args.entries ?? CORE_MIGRATIONS;
+  if (entries.length === 0) return null;
+
+  // Planned against a copy: the tree walk is what decides which patches apply
+  // (and in what order they refuse), so the YAML side must ask exactly the same
+  // question of exactly the same state rather than re-deriving it.
+  const scratch = args.manifests.map((m) => (m ? (structuredClone(m) as ResourceManifest) : null));
+  const applied = applyAll(scratch, entries);
+  if (applied.length === 0) return null;
+
+  const edits: TextEdit[] = [];
+  const kept: AppliedPatch[] = [];
+  const skipped: AppliedPatch[] = [];
+  for (const patch of applied) {
+    const doc = args.documents[patch.documentIndex];
+    if (!doc) {
+      skipped.push(patch);
+      continue;
+    }
+    const planned = planTextEdits(doc, args.text, patch.plan.effects);
+    // A patch the tree accepted but the text cannot express (a block scalar
+    // span, a flow-style entry) leaves that node alone rather than half-written.
+    if (!planned) {
+      skipped.push(patch);
+      continue;
+    }
+    // Two patches whose spans overlap cannot both be spliced — the second would
+    // write into bytes the first replaced. The tree side has no equivalent,
+    // because an object write is idempotent where a splice is positional, so
+    // this is the one place the file applier is stricter: the later patch is
+    // dropped and its node stays as the author wrote it.
+    if (planned.some((edit) => edits.some((existing) => overlaps(edit, existing)))) {
+      skipped.push(patch);
+      continue;
+    }
+    edits.push(...planned);
+    kept.push(patch);
+  }
+  if (edits.length === 0 && skipped.length === 0) return null;
+
+  return {
+    text: edits.length > 0 ? applyTextEdits(args.text, edits) : args.text,
+    rewrites: kept.map(toRewrite),
+    unwritable: skipped.map(toRewrite),
+  };
+}
+
+/** Whether two splices contend for the same bytes. A pure insertion (an empty
+ *  span) collides only with a span that strictly contains its point. */
+function overlaps(a: TextEdit, b: TextEdit): boolean {
+  if (a.start === a.end) return b.start < a.start && a.start < b.end;
+  if (b.start === b.end) return a.start < b.start && b.start < a.end;
+  return a.start < b.end && b.start < a.end;
+}
+
+/** One pass: every match collected against the frozen pre-migration tree, then
+ *  applied in entry order. */
+function applyAll(
+  manifests: Array<ResourceManifest | null>,
+  entries: readonly MigrationEntry[],
+): AppliedPatch[] {
+  const candidates: Array<{
+    entry: MigrationEntry;
+    ops: readonly MigrationOperation[];
+    documentIndex: number;
+    path: MigrationPath;
+  }> = [];
+
+  // One index per DOCUMENT, shared by every rule that can reach it — the walk
+  // is the expensive part and does not depend on the rule. This runs on the
+  // kernel's boot path for every file in the graph, so a walk per rule would
+  // scale the cost of loading any manifest with the size of the migration set.
+  //
+  // The `inKind` gate and the `under` regions are both known BEFORE the walk,
+  // so they bound it rather than filtering its output: a document no rule
+  // targets is never walked, and a region no rule names is never descended
+  // into. `type:` alone occurs a couple of hundred times in a standard-library
+  // manifest, so indexing sites that cannot be selected is the whole cost.
+  const flatRules = entries.flatMap((entry) =>
+    entry.rules.map((rule) => ({ entry, ops: rule.patch, match: rule.match })),
+  );
+  for (let documentIndex = 0; documentIndex < manifests.length; documentIndex++) {
+    const manifest = manifests[documentIndex];
+    if (!manifest) continue;
+    const { rules, keys, roots } = applicableRules(flatRules, manifest.kind);
+    if (rules.length === 0) continue;
+    const index = buildMatchIndex(manifest, keys, roots);
+    for (const { entry, ops, match } of rules) {
+      for (const path of selectMatches(index, manifest, match)) {
+        candidates.push({ entry, ops, documentIndex, path });
+      }
+    }
+  }
+
+  // Arrays whose LENGTH an already-applied patch changed, as
+  // `<documentIndex>:<dotted path>`. A frozen match names a sequence element by
+  // INDEX, and an index is not an identity: once a sibling patch inserted or
+  // removed an item, the same index names a different element — including one
+  // another rule just produced, which is exactly what the frozen match set
+  // exists to prevent. A key-based path needs no such record, because a rename
+  // or removal makes the stale path resolve to nothing and `planPatch` refuses
+  // it on its own.
+  const shiftedArrays = new Set<string>();
+
+  const applied: AppliedPatch[] = [];
+  for (const candidate of candidates) {
+    const manifest = manifests[candidate.documentIndex];
+    if (!manifest) continue;
+    if (indexIsStale(candidate.documentIndex, candidate.path, shiftedArrays)) continue;
+    const result = planPatch(manifest, candidate.path, candidate.ops);
+    // Refusal is not an error: the node stays as the author wrote it and the
+    // ordinary validator reports it with an accurate message.
+    if (!result.ok) continue;
+    applyEffectsToTree(manifest, result.plan.effects);
+    for (const array of resizedArrays(candidate.documentIndex, result.plan.effects)) {
+      shiftedArrays.add(array);
+    }
+    applied.push({
+      entry: candidate.entry,
+      documentIndex: candidate.documentIndex,
+      matched: candidate.path,
+      plan: result.plan,
+      ops: candidate.ops,
+    });
+  }
+  return applied;
+}
+
+/** Arrays this patch resized, keyed for `shiftedArrays`. */
+function resizedArrays(
+  documentIndex: number,
+  effects: readonly MigrationEffect[],
+): string[] {
+  const out: string[] = [];
+  for (const effect of effects) {
+    if (effect.kind === "insert-item") {
+      out.push(`${documentIndex}:${formatMigrationPath(effect.path)}`);
+    } else if (
+      effect.kind === "remove-entry" &&
+      typeof effect.path[effect.path.length - 1] === "number"
+    ) {
+      out.push(`${documentIndex}:${formatMigrationPath(effect.path.slice(0, -1))}`);
+    }
+  }
+  return out;
+}
+
+/** Whether any index along `path` steps into an array a prior patch resized. */
+function indexIsStale(
+  documentIndex: number,
+  path: MigrationPath,
+  shiftedArrays: ReadonlySet<string>,
+): boolean {
+  if (shiftedArrays.size === 0) return false;
+  for (let i = 0; i < path.length; i++) {
+    if (typeof path[i] !== "number") continue;
+    if (shiftedArrays.has(`${documentIndex}:${formatMigrationPath(path.slice(0, i))}`)) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/migrations/entries/index.ts

@@ -0,0 +1,10 @@
+// GENERATED by scripts/copy-migration-entries.mjs — do not edit, and do not commit.
+// Source: analyzer/migrations/*.json (lexically ordered).
+import e0 from "./normalize-value-types.json" with { type: "json" };
+import e1 from "./ref-slot-scalar-type.json" with { type: "json" };
+
+/** Every entry file, in the order the driver applies them. */
+export const MIGRATION_ENTRY_FILES: ReadonlyArray<readonly [file: string, data: unknown]> = [
+  ["normalize-value-types.json", e0],
+  ["ref-slot-scalar-type.json", e1],
+];

package/src/migrations/entries/normalize-value-types.json

@@ -0,0 +1,48 @@
+{
+  "$comment": "Three keywords answered one question — what is the value at this slot, beyond what JSON Schema's `type` can say — and each answered it differently. `inSchema` with the wildcard `inKind` / `under` is what makes this reachable at all: these annotations occur in author-written schema fragments inside ORDINARY resource documents (an inline `inputType:` on any kind that declares one, a route's `request.schema.body`), and that set of kinds is open, so enumerating it would be both incomplete and a violation of the topology-driven constraint. The wildcards are earned by the pairing the reader enforces: a schema region bounds where the walk may go, and an `x-telo-*` key — Telo vocabulary wherever it appears — bounds what it may touch. Each rule sets the value BEFORE renaming the key, so both match the frozen pre-migration tree; a rename first would leave the second rule looking for a node that no longer exists. `notUnder` keeps all three out of the data-bearing keywords, where a value may merely look like a schema.",
+  "id": "normalize-value-types",
+  "code": "X_TELO_TYPE_DEPRECATED",
+  "severity": "warning",
+  "reason": "The three value-type annotations were unified into one `x-telo-type`, whose names are `Telo.`-qualified like every other kernel-owned name. `x-telo-binary` and `x-telo-stream` said what a value IS just as `x-telo-type` did, differing only in posture toward the JSON Schema layer — so a fourth kind of value meant a fourth keyword and edits across four packages.",
+  "rules": [
+    {
+      "match": {
+        "key": "x-telo-stream",
+        "inKind": ["*"],
+        "under": ["*"],
+        "inSchema": true,
+        "value": true,
+        "notUnder": ["const", "default", "enum", "examples"]
+      },
+      "patch": [
+        { "op": "set-value", "value": "Telo.Stream" },
+        { "op": "rename-key", "to": "x-telo-type" }
+      ]
+    },
+    {
+      "match": {
+        "key": "x-telo-binary",
+        "inKind": ["*"],
+        "under": ["*"],
+        "inSchema": true,
+        "value": true,
+        "notUnder": ["const", "default", "enum", "examples"]
+      },
+      "patch": [
+        { "op": "set-value", "value": "Telo.Bytes" },
+        { "op": "rename-key", "to": "x-telo-type" }
+      ]
+    },
+    {
+      "match": {
+        "key": "x-telo-type",
+        "inKind": ["*"],
+        "under": ["*"],
+        "inSchema": true,
+        "valueOneOf": ["TcpPort", "UdpPort"],
+        "notUnder": ["const", "default", "enum", "examples"]
+      },
+      "patch": [{ "op": "set-value", "qualify": "Telo." }]
+    }
+  ]
+}

package/src/migrations/entries/ref-slot-scalar-type.json

@@ -0,0 +1,20 @@
+{
+  "$comment": "See README.md in this directory. `inKind` + `under` are the positive containment: `under` names TOP-LEVEL keys, so this rule can reach nothing but the schema blocks of a kind document — never the `resources:` template body, whose nested config may hold a key spelled `schema` over data. `withSibling` is what makes it precise — a scalar `type:` is stale only because an `x-telo-ref` sits beside it. `notUnder` then narrows within that region, keeping the rule out of the data-bearing keywords where a value may merely look like a schema.",
+  "id": "ref-slot-scalar-type",
+  "code": "X_TELO_REF_SCALAR_TYPE",
+  "severity": "warning",
+  "reason": "A reference is written with the `!ref` tag and resolves to an object, so a reference slot no longer carries the scalar `type:` that plain-string references were pinned to. Leaving it in place makes the slot reject the very value it is declared to accept, and every schema reader has had to know to ignore it.",
+  "rules": [
+    {
+      "match": {
+        "key": "type",
+        "inKind": ["Telo.Definition", "Telo.Abstract"],
+        "under": ["schema", "status", "inputType", "outputType"],
+        "valueOneOf": ["string", "number", "integer", "boolean"],
+        "withSibling": "x-telo-ref",
+        "notUnder": ["const", "default", "enum", "examples"]
+      },
+      "patch": [{ "op": "remove-entry" }]
+    }
+  ]
+}

package/src/migrations/entry-data.ts

@@ -0,0 +1,207 @@
+/** The on-disk shape of a migration entry, and its reader.
+ *
+ *  An entry is DATA: one file per entry under `analyzer/migrations/`, consumed
+ *  as one lexically ordered set. That is what makes adding a migration one file
+ *  and retiring one deleting it, what ships the set in the published package,
+ *  and what lets the Rust crate embed the identical files at build time rather
+ *  than reimplementing each rewrite.
+ *
+ *  **An entry contains no code.** Both halves — what a rule matches and what it
+ *  patches — are data, so one file is read identically 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.
+ *
+ *  Reading is STRICT. A malformed entry is an authoring mistake, and the
+ *  alternative to throwing is a migration that silently does not run — the one
+ *  failure mode a rewrite-on-load design cannot afford, because a migration
+ *  that succeeds and one that never fires look identical. */
+
+import { DiagnosticSeverity } from "../types.js";
+import { readMigrationMatch } from "./match.js";
+import type {
+  MigrationEntry,
+  MigrationOperation,
+  MigrationRule,
+} from "./types.js";
+import { MIGRATION_OPS } from "./types.js";
+
+/** How an entry file names a severity. The LSP integers are a transport detail
+ *  of one editor; an entry is read by a Rust crate too. */
+const SEVERITIES: Record<string, DiagnosticSeverity> = {
+  error: DiagnosticSeverity.Error,
+  warning: DiagnosticSeverity.Warning,
+  info: DiagnosticSeverity.Information,
+  hint: DiagnosticSeverity.Hint,
+};
+
+class MigrationEntryError extends Error {
+  constructor(file: string, detail: string) {
+    super(`Invalid migration entry '${file}': ${detail}`);
+    this.name = "MigrationEntryError";
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function requireString(file: string, node: Record<string, unknown>, key: string): string {
+  const value = node[key];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new MigrationEntryError(file, `'${key}' must be a non-empty string`);
+  }
+  return value;
+}
+
+const OPERATION_KEYS: Record<(typeof MIGRATION_OPS)[number], readonly string[]> = {
+  "rename-key": ["to"],
+  "set-value": ["value", "qualify"],
+  "set-tag": ["tag"],
+  "insert-item": ["value", "at"],
+  "remove-entry": [],
+};
+
+/** Top-level entry keys. `$comment` is the sanctioned place for author notes —
+ *  the reader ignores it, but it has to be DECLARED, or "unknown keys are
+ *  refused" would be true of every level but this one. */
+const ENTRY_KEYS = ["id", "code", "severity", "reason", "rules", "$comment"] as const;
+
+/**
+ * A value a patch may write.
+ *
+ * Scalars only, because "every operation has a known YAML edit form" is what
+ * makes a migration applicable to a FILE, and the file applier renders a value
+ * by re-quoting it in the author's own style at the node's own span — which has
+ * no meaning for a mapping or a sequence. Without this check the limitation is
+ * invisible until a user runs `telo migrate` and is told, permanently, to fix
+ * it by hand; with it, the entry's author learns at authoring time. Structured
+ * values are a vocabulary extension (a block renderer), not a silent gap.
+ */
+function requireScalarValue(file: string, index: number, op: string, value: unknown): void {
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  ) {
+    return;
+  }
+  throw new MigrationEntryError(
+    file,
+    `patch[${index}] ('${op}') value must be a scalar (string, number, boolean or null) — ` +
+      `a mapping or sequence has no in-place YAML edit form, so \`telo migrate\` could never apply it`,
+  );
+}
+
+function readOperation(file: string, raw: unknown, index: number): MigrationOperation {
+  if (!isPlainObject(raw)) {
+    throw new MigrationEntryError(file, `patch[${index}] must be a mapping`);
+  }
+  const op = raw.op;
+  if (typeof op !== "string" || !(MIGRATION_OPS as readonly string[]).includes(op)) {
+    throw new MigrationEntryError(
+      file,
+      `patch[${index}].op '${String(op)}' is not one of ${MIGRATION_OPS.join(", ")}`,
+    );
+  }
+  // The vocabulary is closed, so an unknown parameter is a typo — and a typo in
+  // a patch is a rewrite that quietly does something other than what it reads
+  // as. `set-value`'s two parameters are alternatives, checked below.
+  const allowed = new Set<string>([...OPERATION_KEYS[op as (typeof MIGRATION_OPS)[number]], "op"]);
+  for (const key of Object.keys(raw)) {
+    if (!allowed.has(key)) {
+      throw new MigrationEntryError(file, `patch[${index}] ('${op}') has no parameter '${key}'`);
+    }
+  }
+
+  switch (op) {
+    case "rename-key":
+      return { op, to: requireString(file, raw, "to") };
+    case "set-value": {
+      const hasValue = Object.hasOwn(raw, "value");
+      const hasQualify = Object.hasOwn(raw, "qualify");
+      if (hasValue === hasQualify) {
+        throw new MigrationEntryError(
+          file,
+          `patch[${index}] ('set-value') takes exactly one of 'value' or 'qualify'`,
+        );
+      }
+      if (hasQualify) return { op, qualify: requireString(file, raw, "qualify") };
+      requireScalarValue(file, index, op, raw.value);
+      return { op, value: raw.value };
+    }
+    case "set-tag":
+      return { op, tag: requireString(file, raw, "tag") };
+    case "insert-item": {
+      if (!Object.hasOwn(raw, "value")) {
+        throw new MigrationEntryError(file, `patch[${index}] ('insert-item') requires 'value'`);
+      }
+      requireScalarValue(file, index, op, raw.value);
+      const at = raw.at;
+      if (at !== undefined && (typeof at !== "number" || !Number.isInteger(at) || at < 0)) {
+        throw new MigrationEntryError(
+          file,
+          `patch[${index}].at must be a non-negative integer when present`,
+        );
+      }
+      return at === undefined ? { op, value: raw.value } : { op, value: raw.value, at };
+    }
+    case "remove-entry":
+      return { op };
+    default:
+      throw new MigrationEntryError(file, `patch[${index}].op '${op}' is unhandled`);
+  }
+}
+
+function readRule(file: string, raw: unknown, index: number): MigrationRule {
+  if (!isPlainObject(raw)) {
+    throw new MigrationEntryError(file, `rules[${index}] must be a mapping`);
+  }
+  if (!Array.isArray(raw.patch) || raw.patch.length === 0) {
+    throw new MigrationEntryError(file, `rules[${index}].patch must be a non-empty sequence`);
+  }
+  return {
+    match: readMigrationMatch(`Invalid migration entry '${file}': rules[${index}]`, raw.match),
+    patch: raw.patch.map((op, i) => readOperation(file, op, i)),
+  };
+}
+
+/**
+ * Read one entry file's parsed data into a `MigrationEntry`.
+ *
+ * `file` names the entry file, so a failure says which one.
+ */
+export function parseMigrationEntry(file: string, data: unknown): MigrationEntry {
+  if (!isPlainObject(data)) {
+    throw new MigrationEntryError(file, "an entry must be a mapping");
+  }
+  // Closed at every level, this one included: a typo'd top-level key would
+  // otherwise be silently ignored, which is the one failure a rewrite-on-load
+  // design cannot afford once module-shipped entries make this a trust boundary.
+  for (const key of Object.keys(data)) {
+    if (!(ENTRY_KEYS as readonly string[]).includes(key)) {
+      throw new MigrationEntryError(
+        file,
+        `an entry has no key '${key}'. Known keys: ${ENTRY_KEYS.join(", ")}.`,
+      );
+    }
+  }
+  const severityName = requireString(file, data, "severity");
+  const severity = SEVERITIES[severityName];
+  if (severity === undefined) {
+    throw new MigrationEntryError(
+      file,
+      `severity '${severityName}' must be one of ${Object.keys(SEVERITIES).join(", ")}`,
+    );
+  }
+  if (!Array.isArray(data.rules) || data.rules.length === 0) {
+    throw new MigrationEntryError(file, "'rules' must be a non-empty sequence");
+  }
+  return {
+    id: requireString(file, data, "id"),
+    code: requireString(file, data, "code"),
+    severity,
+    reason: requireString(file, data, "reason").trim(),
+    rules: data.rules.map((rule, i) => readRule(file, rule, i)),
+  };
+}

package/src/migrations/index.ts

@@ -0,0 +1,22 @@
+/** The migration mechanism's surface — what a consumer OUTSIDE this directory
+ *  may hold.
+ *
+ *  Deliberately narrow. The matcher, the patch planner and the two appliers are
+ *  one mechanism with one entry point per job (`migrateManifests` for the
+ *  loader, `migrateFileText` for `telo migrate`, `remapMigratedPaths` for a
+ *  diagnostic consumer); re-exporting their internals would make the plan/apply
+ *  split, the effect vocabulary and the text-edit shape semver-bound API with
+ *  no caller, and freeze the one part most likely to change as the operation
+ *  vocabulary grows.
+ *
+ *  The entry-set trio (`CORE_MIGRATIONS`, `parseMigrationEntry`,
+ *  `MigrationEntry`) is here because `LoaderInitOptions.migrations` is a
+ *  composition-root seam: a host aggregating module-shipped entries beside the
+ *  core ones needs to read one and to name the set it is extending. */
+
+export { migrateFileText, migrateManifests, NO_MIGRATIONS } from "./driver.js";
+export type { FileMigrations } from "./driver.js";
+export { parseMigrationEntry } from "./entry-data.js";
+export { remapMigratedPaths } from "./provenance.js";
+export { CORE_MIGRATIONS } from "./registry.js";
+export type { MigrationEntry, MigrationRewrite } from "./types.js";