@telorun/analyzer 0.56.1 → 0.58.0

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

package/dist/migrations/yaml-edit.js

@@ -0,0 +1,245 @@
+/** 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 { isMap, isPair, isScalar, isSeq } from "yaml";
+import { renderFixReplacement } from "../yaml-source-edit.js";
+export { applyTextEdits } from "../yaml-source-edit.js";
+function nodeAt(doc, path) {
+    if (path.length === 0)
+        return doc.contents;
+    return doc.getIn(path, true);
+}
+function rangeOf(node) {
+    const range = node?.range;
+    if (!Array.isArray(range) || typeof range[0] !== "number" || typeof range[1] !== "number") {
+        return undefined;
+    }
+    return [range[0], range[1]];
+}
+/** The Pair whose key is `key` inside the map at `parent`. */
+function pairAt(doc, parent, key) {
+    const map = nodeAt(doc, parent);
+    if (!isMap(map))
+        return undefined;
+    return map.items.find((item) => isPair(item) && isScalar(item.key) && String(item.key.value) === key);
+}
+/** Re-quote `value` in the style the author used at `original`.
+ *
+ *  A non-string is rendered as its YAML spelling and then handed to the shared
+ *  rule, so a migration and a quick fix quote the same value identically — the
+ *  rule itself is `renderFixReplacement` (`../yaml-source-edit.js`), which both
+ *  this and `@telorun/ide-support` read rather than restate. */
+function renderScalar(original, value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean" || typeof value === "number")
+        return String(value);
+    if (typeof value !== "string")
+        return undefined;
+    return renderFixReplacement(original, value);
+}
+/** Column of `offset` within its line, and the offset of that line's start. */
+function lineGeometry(text, offset) {
+    const lineStart = text.lastIndexOf("\n", Math.max(0, offset - 1)) + 1;
+    return { lineStart, indent: offset - lineStart };
+}
+/** 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 function planTextEdits(doc, text, effects) {
+    if (effects.length === 0)
+        return [];
+    // **The document is never mutated.** A patch's later effects address the node
+    // by its POST-rename path, which the file does not have — so every effect is
+    // resolved at the one location the patch matched, read off the first effect.
+    // The tree applier and this one therefore agree without either replaying the
+    // other's state.
+    const first = effects[0];
+    const docPath = first.kind === "rename-key" ? [...first.parent, first.from] : first.path;
+    // A removal supersedes every other edit at the location: `planPatch` refuses
+    // anything after a `remove-entry`, and the line it deletes contains them.
+    const removal = effects.find((e) => e.kind === "remove-entry");
+    if (removal)
+        return removeEntryEdit(doc, text, docPath);
+    const edits = [];
+    let keyEdit;
+    // Value edits compose into ONE splice: a `set-tag` after a `set-value` must
+    // emit the tag in front of the NEW scalar, not re-read the old one.
+    let valueSpan;
+    let scalarText;
+    let tagText;
+    for (const effect of effects) {
+        switch (effect.kind) {
+            case "rename-key": {
+                const pair = pairAt(doc, docPath.slice(0, -1), String(docPath[docPath.length - 1]));
+                if (!isPair(pair) || !isScalar(pair.key))
+                    return undefined;
+                const range = rangeOf(pair.key);
+                if (!range)
+                    return undefined;
+                const rendered = renderScalar(text.slice(range[0], range[1]), effect.to);
+                if (rendered === undefined)
+                    return undefined;
+                keyEdit = { start: range[0], end: range[1], newText: rendered };
+                break;
+            }
+            case "set-value": {
+                const range = rangeOf(nodeAt(doc, docPath));
+                if (!range)
+                    return undefined;
+                const rendered = renderScalar(text.slice(range[0], range[1]), effect.value);
+                if (rendered === undefined)
+                    return undefined;
+                valueSpan ??= range;
+                scalarText = rendered;
+                break;
+            }
+            case "set-tag": {
+                const node = nodeAt(doc, docPath);
+                if (!isScalar(node))
+                    return undefined;
+                const range = rangeOf(node);
+                if (!range)
+                    return undefined;
+                // The tag sits outside the scalar's own span, so an existing one is
+                // replaced by rewriting from where it starts; a plain scalar just gains
+                // a prefix.
+                const existing = typeof node.tag === "string" ? node.tag : undefined;
+                const tagStart = existing ? text.lastIndexOf(existing, range[0]) : -1;
+                valueSpan = [tagStart >= 0 ? tagStart : range[0], range[1]];
+                scalarText ??= text.slice(range[0], range[1]);
+                tagText = `!${effect.tag}`;
+                break;
+            }
+            case "insert-item": {
+                const edit = insertItemEdit(doc, text, docPath, effect.index, effect.value);
+                if (!edit)
+                    return undefined;
+                edits.push(edit);
+                break;
+            }
+            case "remove-entry":
+                // Handled above.
+                break;
+        }
+    }
+    if (keyEdit)
+        edits.push(keyEdit);
+    if (valueSpan && scalarText !== undefined) {
+        edits.push({
+            start: valueSpan[0],
+            end: valueSpan[1],
+            newText: tagText ? `${tagText} ${scalarText}` : scalarText,
+        });
+    }
+    return edits;
+}
+function insertItemEdit(doc, text, path, index, value) {
+    const seq = nodeAt(doc, path);
+    // An empty sequence is written `[]` in flow style, which has no item line to
+    // extend — the one insert shape this cannot render.
+    if (!isSeq(seq) || seq.items.length === 0)
+        return undefined;
+    const rendered = renderScalar("", value);
+    if (rendered === undefined)
+        return undefined;
+    const anchorIndex = Math.min(index, seq.items.length - 1);
+    const anchor = rangeOf(seq.items[anchorIndex]);
+    if (!anchor)
+        return undefined;
+    const { lineStart, indent } = lineGeometry(text, anchor[0]);
+    // A block sequence's item starts two columns after its `- `; a flow sequence
+    // has no line of its own.
+    if (text.slice(lineStart, anchor[0]).trimStart() !== "- ")
+        return undefined;
+    const line = `${" ".repeat(Math.max(0, indent - 2))}- ${rendered}\n`;
+    if (index >= seq.items.length) {
+        const last = rangeOf(seq.items[seq.items.length - 1]);
+        if (!last)
+            return undefined;
+        const lineEnd = text.indexOf("\n", last[1]);
+        const at = lineEnd < 0 ? text.length : lineEnd + 1;
+        return { start: at, end: at, newText: line };
+    }
+    return { start: lineStart, end: lineStart, newText: line };
+}
+function removeEntryEdit(doc, text, path) {
+    const located = locateEntry(doc, path);
+    if (!located)
+        return undefined;
+    const { lineStart } = lineGeometry(text, located.start);
+    const prefix = text.slice(lineStart, located.start);
+    const opensSequenceItem = /^-\s+$/.test(prefix.trimStart());
+    // The entry OWNS its line — indentation for a mapping entry, indentation plus
+    // `- ` for a sequence item — so removing the line is exact.
+    if (located.item ? opensSequenceItem : prefix.trim() === "") {
+        const lineEnd = text.indexOf("\n", located.end);
+        return [{ start: lineStart, end: lineEnd < 0 ? text.length : lineEnd + 1, newText: "" }];
+    }
+    // A mapping entry that OPENS a sequence item shares its line with the `- `,
+    // and is the overwhelmingly common shape of the one thing a migration removes
+    // today: a legacy ref slot is almost always an `anyOf` branch, written
+    // `- type: string` with the annotation beneath it. Deleting the line would
+    // take the dash with it and fold the item into its predecessor — so the entry
+    // is spliced out up to the FOLLOWING sibling's key instead, which slides onto
+    // the dash at the column it already occupies. Refusing here would have made
+    // the diagnostic's own advice ("run `telo migrate`") dead for the case it is
+    // most often given in.
+    if (!located.item && opensSequenceItem) {
+        const next = nextSiblingKeyStart(doc, path);
+        // Nothing to promote onto the dash: the entry is the item's only one, and
+        // removing it would leave `- ` with no value.
+        if (next === undefined)
+            return undefined;
+        // Only whitespace may be swallowed. A comment or anything else between the
+        // two entries would be destroyed by the splice, so that stays a hand edit.
+        const between = text.slice(located.end, next);
+        if (!/^\s*$/.test(between) || !between.includes("\n"))
+            return undefined;
+        return [{ start: located.start, end: next, newText: "" }];
+    }
+    return undefined;
+}
+/** Offset of the key of the entry FOLLOWING `path` in its own mapping, or
+ *  `undefined` when `path` is the last entry (or anything is not a plain
+ *  key-scalar pair). */
+function nextSiblingKeyStart(doc, path) {
+    const map = nodeAt(doc, path.slice(0, -1));
+    if (!isMap(map))
+        return undefined;
+    const key = String(path[path.length - 1]);
+    const at = map.items.findIndex((item) => isPair(item) && isScalar(item.key) && String(item.key.value) === key);
+    if (at < 0)
+        return undefined;
+    const next = map.items[at + 1];
+    if (!isPair(next) || !isScalar(next.key))
+        return undefined;
+    return rangeOf(next.key)?.[0];
+}
+/** Span of a whole mapping entry (key through value) or sequence item. */
+function locateEntry(doc, path) {
+    const last = path[path.length - 1];
+    if (typeof last === "string") {
+        const pair = pairAt(doc, path.slice(0, -1), last);
+        if (!isPair(pair) || !isScalar(pair.key))
+            return undefined;
+        const keyRange = rangeOf(pair.key);
+        const valueRange = rangeOf(pair.value) ?? keyRange;
+        if (!keyRange || !valueRange)
+            return undefined;
+        return { start: keyRange[0], end: valueRange[1], item: false };
+    }
+    const range = rangeOf(nodeAt(doc, path));
+    if (!range)
+        return undefined;
+    return { start: range[0], end: range[1], item: true };
+}

package/dist/module-file-claims.d.ts

@@ -0,0 +1,65 @@
+import { type TemplatingEngineRegistry } from "@telorun/templating";
+import { type ArtifactSelector } from "./artifact-selector.js";
+/**
+ * One module-relative file a manifest names, and the artifact layer it belongs
+ * to.
+ *
+ * The single answer to "why is this file in the payload", replacing two
+ * derivations that happened to agree: publish used to re-parse the manifest with
+ * PURL knowledge hardcoded into the CLI, and any second vocabulary — a tag that
+ * embeds a file, say — would have had to be added there by hand. Here the
+ * knowledge sits with whoever owns the syntax: a controller candidate is read by
+ * this module, and a tagged value is read by the engine that owns its tag, via
+ * `TemplatingEngine.fileClaims`. Publish maps role to layer and recognises
+ * neither.
+ *
+ * Deliberately NOT hung off `analyze()`. That pass runs over a flattened,
+ * import-inclusive manifest set, so its claims would mix in imported libraries'
+ * files — whose paths are relative to *their* module and must never join this
+ * artifact — and it would make packaging, today derivable offline from manifest
+ * text, a product of resolving the whole import graph. This is per-module by
+ * construction and needs nothing but the text.
+ *
+ * Browser-safe, like the rest of the analyzer: parsing and string work only, no
+ * filesystem. Whether a claimed file EXISTS is a separate question, asked by the
+ * Node-side caller that has a directory to look in.
+ */
+interface ClaimBase {
+    /** Module-root-relative POSIX path — relative to the directory holding
+     *  `telo.yaml`, never to the file the claim was written in. Publish inlines
+     *  every `include:` partial into the published `telo.yaml`, so a
+     *  per-file-relative path would change meaning in the artifact. */
+    readonly path: string;
+    /** Where the claim came from, for diagnostics: the PURL, or `!<tag>` and the
+     *  path of the value that carried it. */
+    readonly origin: string;
+}
+/**
+ * A **discriminated union**, not one shape with optional fields: a controller
+ * layer is one per selector and carries sibling patterns, and an assets layer is
+ * neither. Optional fields on a single shape put the consumer one `!` away from
+ * a crash inside `selectorKey` with no useful message, and let a producer emit a
+ * controller claim with no selector that nothing would reject.
+ */
+export type ModuleFileClaim = (ClaimBase & {
+    readonly role: "controller";
+    readonly selector: ArtifactSelector;
+    /** Extra payload patterns that belong in the same layer as this claim —
+     *  `.gitignore`-style globs over the selected files, matched by the
+     *  caller, which is the side that knows what was selected. */
+    readonly siblings: readonly string[];
+}) | (ClaimBase & {
+    readonly role: "assets";
+});
+/**
+ * Every module-relative file the manifest names, from every syntax that can name
+ * one.
+ *
+ * `manifestText` is one module's `telo.yaml`. Publish passes the text it is
+ * about to ship — i.e. after `include:` partials have been inlined — but the
+ * answer does not depend on that: claims are root-relative, so collecting them
+ * before or after inlining gives the same set.
+ */
+export declare function collectModuleFileClaims(manifestText: string, registry?: TemplatingEngineRegistry): ModuleFileClaim[];
+export {};
+//# sourceMappingURL=module-file-claims.d.ts.map

package/dist/module-file-claims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-file-claims.d.ts","sourceRoot":"","sources":["../src/module-file-claims.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,wBAAwB,EAC9B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAuC,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAEpG;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,UAAU,SAAS;IACjB;;;uEAGmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;6CACyC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GACvB,CAAC,SAAS,GAAG;IACX,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC;;kEAE8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC,CAAC,GACF,CAAC,SAAS,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,CAAC;AAiF9C;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,QAAQ,GAAE,wBAA4C,GACrD,eAAe,EAAE,CAanB"}

package/dist/module-file-claims.js

@@ -0,0 +1,106 @@
+import { defaultCustomTags, defaultRegistry, walkCelExpressions, } from "@telorun/templating";
+import { PackageURL } from "packageurl-js";
+import { parseAllDocuments } from "yaml";
+import { selectorFromQualifiers, selectorKey } from "./artifact-selector.js";
+/** `pkg:telo/local/<format>?path=…` — the bundled-controller delivery mode.
+ *  Anything else (`pkg:npm`, `pkg:cargo`) fetches from its own ecosystem and
+ *  contributes no layer. */
+const BUNDLED_TYPE = "telo";
+const BUNDLED_NAMESPACE = "local";
+/** Qualifier naming extra files that belong in a controller's layer — what an
+ *  entry point loads but the manifest cannot otherwise see (a `.wasm` beside its
+ *  glue, a native library opened at runtime). */
+const SIBLINGS_QUALIFIER = "siblings";
+/** Normalize a `path=` / sibling value to the manifest-relative POSIX form the
+ *  file selector returns, so membership is a string comparison. */
+function normalizeRelative(value) {
+    return value.replace(/^\.\//, "").replace(/\\/g, "/");
+}
+/** Bundled-controller claims from one document's `controllers:` list. */
+function controllerClaims(json) {
+    const candidates = json?.controllers;
+    if (!Array.isArray(candidates))
+        return [];
+    const claims = [];
+    for (const candidate of candidates) {
+        if (typeof candidate !== "string")
+            continue;
+        let parsed;
+        try {
+            parsed = PackageURL.fromString(candidate);
+        }
+        catch {
+            // Not a parseable PURL — claim collection is not the place to reject it;
+            // the analyzer's own validation and the controller loader both report it
+            // with better context.
+            continue;
+        }
+        if (parsed.type !== BUNDLED_TYPE || parsed.namespace !== BUNDLED_NAMESPACE)
+            continue;
+        const entry = parsed.qualifiers?.path;
+        if (typeof entry !== "string" || entry === "")
+            continue;
+        claims.push({
+            role: "controller",
+            path: normalizeRelative(entry),
+            selector: selectorFromQualifiers(parsed.name, parsed.qualifiers, `controller "${candidate}"`),
+            siblings: String(parsed.qualifiers?.[SIBLINGS_QUALIFIER] ?? "")
+                .split(",")
+                .map((p) => p.trim())
+                .filter((p) => p !== ""),
+            origin: candidate,
+        });
+    }
+    return claims;
+}
+/** Claims contributed by tagged values, asked of the engine that owns each tag.
+ *  The walk reaches every tagged scalar in the document, so an engine that
+ *  embeds files is discovered wherever its tag was written.
+ *
+ *  The layer role is assigned HERE, not by the engine: an engine reports what it
+ *  embeds, and which layer that belongs in is this module's vocabulary. A file a
+ *  tag embeds is read only when the resource holding it is created, so `assets`
+ *  — the lazily-fetched layer — is what it is. */
+function taggedClaims(json, registry) {
+    const claims = [];
+    walkCelExpressions(json, "", (source, path, engineName) => {
+        const engine = registry.get(engineName);
+        for (const claim of engine?.fileClaims?.(source) ?? []) {
+            claims.push({ role: "assets", path: claim.path, origin: `!${engineName} at '${path}'` });
+        }
+    });
+    return claims;
+}
+/** Identity of a claim for de-duplication: the same file claimed twice by two
+ *  resources is one file in one layer. Role and selector are part of it because
+ *  a file two controller candidates both claim is genuinely copied into each of
+ *  their layers — dropping one would leave a platform's layer short a file it
+ *  declared it needs. */
+function claimKey(claim) {
+    const selector = claim.role === "controller" ? selectorKey(claim.selector) : "";
+    return `${claim.role}\0${selector}\0${claim.path}`;
+}
+/**
+ * Every module-relative file the manifest names, from every syntax that can name
+ * one.
+ *
+ * `manifestText` is one module's `telo.yaml`. Publish passes the text it is
+ * about to ship — i.e. after `include:` partials have been inlined — but the
+ * answer does not depend on that: claims are root-relative, so collecting them
+ * before or after inlining gives the same set.
+ */
+export function collectModuleFileClaims(manifestText, registry = defaultRegistry()) {
+    const seen = new Set();
+    const claims = [];
+    for (const doc of parseAllDocuments(manifestText, { customTags: defaultCustomTags() })) {
+        const json = doc.toJSON();
+        for (const claim of [...controllerClaims(json), ...taggedClaims(json, registry)]) {
+            const key = claimKey(claim);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            claims.push(claim);
+        }
+    }
+    return claims;
+}

package/dist/parse-loaded-file.d.ts

@@ -1,11 +1,19 @@
 import type { Environment } from "@marcbachmann/cel-js";
 import type { LoadedFile } from "./loaded-types.js";
+import type { MigrationEntry } from "./migrations/types.js";
 export interface ParseOptions {
     /** When true, runs `precompileDoc` per document and stamps compiled CEL
      *  on the manifests — same flag `LoadOptions.compile` carries today. */
     compile?: boolean;
     /** CEL environment for precompile. Defaults to `buildCelEnvironment()`. */
     celEnv?: Environment;
+    /** When true, the migration phase runs over the parsed documents — legacy
+     *  spellings rewritten to the current ones before anything else reads the
+     *  tree. Off by default so a round-trip consumer (the editor) keeps the
+     *  author's vocabulary; see `LoadOptions.migrate`. */
+    migrate?: boolean;
+    /** Migration set. Defaults to the analyzer's own `CORE_MIGRATIONS`. */
+    migrations?: readonly MigrationEntry[];
 }
 /** Pure: text in, structured load result out. No I/O, no caches. */
 export declare function parseLoadedFile(source: string, requestedUrl: string, text: string, options?: ParseOptions): LoadedFile;

package/dist/parse-loaded-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse-loaded-file.d.ts","sourceRoot":"","sources":["../src/parse-loaded-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAKxD,OAAO,KAAK,EAAE,UAAU,EAAc,MAAM,mBAAmB,CAAC;AAKhE,MAAM,WAAW,YAAY;IAC3B;4EACwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AA4BD,oEAAoE;AACpE,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,YAAY,GACrB,UAAU,CAiDZ"}
+{"version":3,"file":"parse-loaded-file.d.ts","sourceRoot":"","sources":["../src/parse-loaded-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAKxD,OAAO,KAAK,EAAE,UAAU,EAAc,MAAM,mBAAmB,CAAC;AAEhE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAK5D,MAAM,WAAW,YAAY;IAC3B;4EACwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;0DAGsD;IACtD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uEAAuE;IACvE,UAAU,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CACxC;AA4BD,oEAAoE;AACpE,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,YAAY,GACrB,UAAU,CA2DZ"}