@telorun/analyzer 0.59.0 → 0.60.0

package/dist/release/payload-digest.js

@@ -0,0 +1,65 @@
+/**
+ * A module's payload, reduced to one digest per layer — the exact answer to
+ * "did this module's artifact change?".
+ *
+ * It is exact because it is taken from the bytes: it fires for an inlined
+ * sibling's edit, for a shared-library fix, and for a transitive bump the
+ * lockfile alone moved, none of which touch a file under the module's own
+ * directory. No path-scoped rule and no declared-dependency graph can see any of
+ * them.
+ *
+ * The digest itself is `computeFilesIntegrity`, the same framing-independent
+ * content digest the published `layers:` index carries — which is what makes the
+ * ledger's recorded number and the registry's the same number, comparable
+ * without fetching a blob.
+ */
+import { PLATFORM_AXES } from "../artifact-selector.js";
+/** The ledger key for the module's `telo.yaml` layer. */
+export const MANIFEST_LAYER = "manifest";
+/**
+ * Ledger keys the registry cannot answer for, and so the ones `telo release
+ * verify` reconciles nothing about and must preserve.
+ *
+ * Exactly one today, and for a structural reason rather than an omission: the
+ * published `layers:` index lives *inside* `telo.yaml`, so it cannot carry that
+ * file's own digest — the entry would have to be computed over bytes containing
+ * it. Nor can the digest be recovered by hashing what the registry serves, since
+ * the transport injects the index at push time and the published text is
+ * therefore not the text the payload builder produced.
+ *
+ * It stays in the ledger regardless, because it is the only thing that sees a
+ * **manifest-only change**: a schema edit, a new kind, a description, a
+ * dependency's version moving into a pin. None of those touch a controller byte,
+ * so without this key such a module would report no drift and its fix would ship
+ * to nobody — the exact failure the digest exists to prevent.
+ */
+export const LOCALLY_DERIVED_LAYERS = new Set([MANIFEST_LAYER]);
+/**
+ * A layer's identity within an artifact, as a stable, readable, YAML-plain key.
+ *
+ * A role alone is not the identity — there is one controller layer per selector
+ * — so a selector's axes join the key. Rendered as `controller/js` and
+ * `controller/napi+linux+amd64+gnu` rather than through `selectorKey`'s
+ * `axis=value;…` form, because this string is read by a human in a ledger diff
+ * and written into a plain YAML key; the axis order is `PLATFORM_AXES`, so the
+ * rendering is deterministic rather than dependent on how the selector was
+ * built.
+ */
+export function layerDigestKey(role, selector) {
+    if (!selector)
+        return role;
+    const parts = [selector.format, ...PLATFORM_AXES.map((axis) => selector[axis])].filter((value) => value !== undefined);
+    return `${role}/${parts.join("+")}`;
+}
+/** Every layer on which two readings disagree, in key order. Empty means the
+ *  payloads are byte-identical. */
+export function diffLayerDigests(before, after) {
+    const changes = [];
+    for (const layer of [...new Set([...Object.keys(before), ...Object.keys(after)])].sort()) {
+        const a = before[layer];
+        const b = after[layer];
+        if (a !== b)
+            changes.push({ layer, ...(a ? { before: a } : {}), ...(b ? { after: b } : {}) });
+    }
+    return changes;
+}

package/dist/release/release-plan.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Turning evidence into a release plan: which modules bump, to what, and why.
+ *
+ * Three questions, three mechanisms, and keeping them apart is the whole design:
+ *
+ * - **Whether** a module bumps is decided by the **payload digest** — exact,
+ *   from the bytes, so it sees an inlined sibling and a lockfile-only transitive
+ *   bump that no path-scoped rule can.
+ * - **At what level** is decided by the **edge graph** — a declared fragment is a
+ *   root, and a dependent mirrors its dependency's level, joined as the maximum
+ *   over paths, because a module that inlines a breaking change is breaking for
+ *   its own consumers.
+ * - **Whether a changelog line is requested** is decided by the path-scoped
+ *   changed-files rule, which used to decide the version. Demoted, its guesswork
+ *   costs one sentence rather than a spurious republish.
+ *
+ * The seam between digest and graph is *reported*, never papered over: a payload
+ * that moved with nothing to attribute it to — a third-party dependency, a
+ * changesets-owned package inlined into a module, a toolchain bump — resolves to
+ * `patch` and says so.
+ *
+ * Pure data in, plan out. Everything Node-shaped — building payloads, running
+ * the controller builder, reading git — is the CLI's half, so the editor can
+ * answer "what does changing this library bump?" from the same model.
+ */
+import { type BumpLevel, type FragmentKind } from "./bump-level.js";
+import type { ModuleKey, ReleaseFragment } from "./fragment.js";
+import type { Ledger } from "./ledger.js";
+import { type LayerChange, type LayerDigests } from "./payload-digest.js";
+/** What a module ships. A `Dockerfile` beside the manifest makes it an image
+ *  module; its absence, a registry artifact module. Derived rather than
+ *  declared, so discovery stays configuration-free. */
+export type ArtifactKind = "registry" | "image";
+export interface ModuleEvidence {
+    /** Workspace-relative directory path — the module's key everywhere. */
+    readonly key: ModuleKey;
+    /** `metadata.name`, for display only. */
+    readonly name: string;
+    /** `metadata.version` as it stands in the working copy. */
+    readonly version: string;
+    readonly artifactKind: ArtifactKind;
+    /** Per-layer integrity of the payload built from the working copy. */
+    readonly layers: LayerDigests;
+    /**
+     * Files this module's build inlined that belong to ANOTHER workspace module,
+     * grouped by owner. From the build's own metafile: a declared-dependency graph
+     * cannot see `--external`, so `@telorun/sdk` — declared by 54 modules, inlined
+     * by none — would otherwise bump the whole standard library on every SDK
+     * change.
+     */
+    readonly inlines: ReadonlyMap<ModuleKey, readonly string[]>;
+    /**
+     * Modules reached by an in-repo **relative** `imports:` source. A pinned
+     * registry ref is deliberately not an edge: pinning is the statement "I am not
+     * affected until I choose to be", and moving it is `telo upgrade`'s job.
+     */
+    readonly imports: readonly ModuleKey[];
+    /** Whether a file under this module's own directory that reaches the artifact
+     *  changed. Decides only whether a changelog line is requested. */
+    readonly ownFilesChanged: boolean;
+}
+export interface ReleaseEvidence {
+    readonly modules: readonly ModuleEvidence[];
+    readonly ledger: Ledger;
+    readonly fragments: readonly ReleaseFragment[];
+    /** The publish destination base the digests above were built against. */
+    readonly registry?: string;
+}
+/** Why a module is in the plan. A module usually carries several. */
+export type BumpReason = {
+    readonly kind: "declared";
+    readonly fragment: string;
+    readonly as: FragmentKind;
+} | {
+    readonly kind: "inlines";
+    readonly module: ModuleKey;
+    readonly files: readonly string[];
+} | {
+    readonly kind: "imports";
+    readonly module: ModuleKey;
+} | {
+    readonly kind: "unattributed";
+};
+export interface ChangelogEntry {
+    readonly kind: FragmentKind;
+    readonly body: string;
+    /** The fragment this line came from, so `apply` can report what it consumed. */
+    readonly fragment: string;
+}
+export interface PlannedModule {
+    readonly key: ModuleKey;
+    readonly name: string;
+    readonly from: string;
+    readonly to: string;
+    readonly level: BumpLevel;
+    readonly reasons: readonly BumpReason[];
+    /** Layers whose digest differs from the ledger's reading. Empty for a module
+     *  bumping purely because a dependency's version moves into its manifest. */
+    readonly changed: readonly LayerChange[];
+    readonly entries: readonly ChangelogEntry[];
+}
+export interface ReleaseDiagnostic {
+    readonly severity: "error" | "warning";
+    readonly code: string;
+    readonly message: string;
+}
+export interface ReleasePlan {
+    /** Bumping modules in dependency order — a dependency precedes its
+     *  dependents, which is also the order `telo publish` must push them. */
+    readonly modules: readonly PlannedModule[];
+    /** Fragments this plan consumes, for `apply` to delete. */
+    readonly fragments: readonly string[];
+    readonly diagnostics: readonly ReleaseDiagnostic[];
+}
+export declare function planRelease(evidence: ReleaseEvidence): ReleasePlan;
+/**
+ * Dependency order over in-repo imports — a dependency before its dependents.
+ *
+ * This is also the publish order, and it is not optional there: publishing
+ * canonicalizes a relative import and then hard-fails when the derived ref does
+ * not already resolve, so a sibling has to be pushed first.
+ *
+ * A cycle keeps its members in key order rather than throwing. A module graph
+ * should not have one, but a release is the wrong moment to discover it, and the
+ * ordering degrades to "arbitrary among the cycle" rather than to nothing.
+ */
+export declare function orderByImports(modules: readonly ModuleEvidence[]): ModuleEvidence[];
+//# sourceMappingURL=release-plan.d.ts.map

package/dist/release/release-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-plan.d.ts","sourceRoot":"","sources":["../../src/release/release-plan.ts"],"names":[],"mappings":"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"}

package/dist/release/release-plan.js

@@ -0,0 +1,277 @@
+/**
+ * Turning evidence into a release plan: which modules bump, to what, and why.
+ *
+ * Three questions, three mechanisms, and keeping them apart is the whole design:
+ *
+ * - **Whether** a module bumps is decided by the **payload digest** — exact,
+ *   from the bytes, so it sees an inlined sibling and a lockfile-only transitive
+ *   bump that no path-scoped rule can.
+ * - **At what level** is decided by the **edge graph** — a declared fragment is a
+ *   root, and a dependent mirrors its dependency's level, joined as the maximum
+ *   over paths, because a module that inlines a breaking change is breaking for
+ *   its own consumers.
+ * - **Whether a changelog line is requested** is decided by the path-scoped
+ *   changed-files rule, which used to decide the version. Demoted, its guesswork
+ *   costs one sentence rather than a spurious republish.
+ *
+ * The seam between digest and graph is *reported*, never papered over: a payload
+ * that moved with nothing to attribute it to — a third-party dependency, a
+ * changesets-owned package inlined into a module, a toolchain bump — resolves to
+ * `patch` and says so.
+ *
+ * Pure data in, plan out. Everything Node-shaped — building payloads, running
+ * the controller builder, reading git — is the CLI's half, so the editor can
+ * answer "what does changing this library bump?" from the same model.
+ */
+import { applyBump, maxLevel, levelOfKind, } from "./bump-level.js";
+import { diffLayerDigests } from "./payload-digest.js";
+export function planRelease(evidence) {
+    const diagnostics = [];
+    const byKey = new Map(evidence.modules.map((module) => [module.key, module]));
+    checkRegistryAgreement(evidence, diagnostics);
+    // What the digest says, per module. A module with no ledger entry has never
+    // been published, which is not drift — there is nothing to differ from.
+    const drift = new Map();
+    for (const module of evidence.modules) {
+        const recorded = evidence.ledger.modules.get(module.key);
+        if (!recorded)
+            continue;
+        if (recorded.version !== module.version) {
+            diagnostics.push({
+                severity: "error",
+                code: "LEDGER_VERSION_MISMATCH",
+                message: `${module.key} declares version ${module.version} but the ledger records ` +
+                    `${recorded.version} as published. The digests beside it were taken at that version, ` +
+                    `so nothing here can be compared. Reconcile with \`telo release verify\` — or, if the ` +
+                    `version was moved by hand, restore it and let \`telo release apply\` move it.`,
+            });
+            continue;
+        }
+        const changes = diffLayerDigests(recorded.layers, module.layers);
+        if (changes.length > 0)
+            drift.set(module.key, changes);
+    }
+    const levels = new Map();
+    const reasons = new Map();
+    const addReason = (key, reason) => {
+        const list = reasons.get(key);
+        if (list)
+            list.push(reason);
+        else
+            reasons.set(key, [reason]);
+    };
+    // Declared roots.
+    const consumed = new Set();
+    for (const fragment of evidence.fragments) {
+        for (const [key, kind] of fragment.modules) {
+            if (!byKey.has(key)) {
+                diagnostics.push({
+                    severity: "error",
+                    code: "FRAGMENT_UNKNOWN_MODULE",
+                    message: `${fragment.source} names '${key}', which is not a module in this workspace. ` +
+                        `A fragment names a module by its workspace-relative directory path.`,
+                });
+                continue;
+            }
+            const level = levelOfKind(kind);
+            if (level === "major") {
+                diagnostics.push({
+                    severity: "error",
+                    code: "MAJOR_BUMP_REJECTED",
+                    message: `${fragment.source} declares '${key}: ${kind}', which induces a major bump. ` +
+                        `Modules are intentionally pre-1.0 — a breaking change ships as a minor. ` +
+                        `Use Added and describe the break in the body.`,
+                });
+                continue;
+            }
+            consumed.add(fragment.source);
+            levels.set(key, maxLevel(levels.get(key) ?? level, level));
+            addReason(key, { kind: "declared", fragment: fragment.source, as: kind });
+        }
+    }
+    // Edges already credited, so a second propagation pass does not repeat an
+    // explanation the author has already been given.
+    const credited = new Set();
+    propagateToFixedPoint(evidence.modules, drift, levels, credited, addReason);
+    // The seam. A payload that moved with nothing to attribute it to still has to
+    // ship — the fix would otherwise reach nobody — so it takes a patch and is
+    // named. Seeded after propagation and then propagated again, because an
+    // unattributed bump is itself a dependency move for anything importing it.
+    for (;;) {
+        let seeded = false;
+        for (const module of evidence.modules) {
+            if (levels.has(module.key) || !drift.has(module.key))
+                continue;
+            levels.set(module.key, "patch");
+            addReason(module.key, { kind: "unattributed" });
+            seeded = true;
+        }
+        if (!seeded)
+            break;
+        propagateToFixedPoint(evidence.modules, drift, levels, credited, addReason);
+    }
+    const entriesByModule = collectChangelogEntries(evidence.fragments, byKey);
+    requestMissingChangelogEntries(evidence.modules, entriesByModule, diagnostics);
+    const planned = [];
+    for (const module of orderByImports(evidence.modules)) {
+        const level = levels.get(module.key);
+        if (!level)
+            continue;
+        planned.push({
+            key: module.key,
+            name: module.name,
+            from: module.version,
+            to: applyBump(module.version, level),
+            level,
+            reasons: reasons.get(module.key) ?? [],
+            changed: drift.get(module.key) ?? [],
+            entries: entriesByModule.get(module.key) ?? [],
+        });
+    }
+    return { modules: planned, fragments: [...consumed].sort(), diagnostics };
+}
+/**
+ * Raise levels along release edges until nothing moves.
+ *
+ * The two edge kinds answer different questions and so are gated differently:
+ *
+ * - An **import** edge bumps unconditionally. Publishing rewrites a relative
+ *   `imports:` source to `<base>/<sibling>@<version>`, so when the sibling's
+ *   version moves this module's manifest layer provably changes — a fact about
+ *   the plan, which the current digest cannot yet show because it was taken
+ *   against the sibling's *current* version.
+ * - An **inline** edge only explains drift that already showed up. The inlined
+ *   bytes are in this payload, so if they had changed the digest would say so;
+ *   attributing without that check would bump every dependent of a module whose
+ *   fragment covers a docs-only change.
+ */
+function propagateToFixedPoint(modules, drift, levels, credited, addReason) {
+    for (let moved = true; moved;) {
+        moved = false;
+        for (const module of modules) {
+            for (const dependency of module.imports) {
+                moved = raise(module, dependency, { kind: "imports", module: dependency }) || moved;
+            }
+            if (!drift.has(module.key))
+                continue;
+            for (const [dependency, files] of module.inlines) {
+                moved =
+                    raise(module, dependency, { kind: "inlines", module: dependency, files }) || moved;
+            }
+        }
+    }
+    function raise(module, dependency, reason) {
+        const from = levels.get(dependency);
+        if (!from)
+            return false;
+        const current = levels.get(module.key);
+        const next = current ? maxLevel(current, from) : from;
+        // The reason is recorded the first time this edge carries anything, even
+        // when it does not raise the level: it is the explanation the author reads,
+        // and an edge that merely agrees with another still says why this module is
+        // in the plan.
+        const edge = `${module.key}\0${dependency}\0${reason.kind}`;
+        if (!credited.has(edge)) {
+            credited.add(edge);
+            addReason(module.key, reason);
+        }
+        if (current === next)
+            return false;
+        levels.set(module.key, next);
+        return true;
+    }
+}
+function collectChangelogEntries(fragments, byKey) {
+    const entries = new Map();
+    for (const fragment of fragments) {
+        for (const [key, kind] of fragment.modules) {
+            if (!byKey.has(key))
+                continue;
+            const list = entries.get(key);
+            const entry = { kind, body: fragment.body, fragment: fragment.source };
+            if (list)
+                list.push(entry);
+            else
+                entries.set(key, [entry]);
+        }
+    }
+    return entries;
+}
+/**
+ * Ask for prose where a human made a semantic change.
+ *
+ * A warning, not an error: `check`'s job is "can a complete, consistent plan be
+ * formed", and a module that drifted through propagation or a toolchain bump is
+ * planned and released without anyone writing a word. This fires only for a
+ * module whose OWN files moved, which is the case where the changelog would
+ * otherwise be silent about a real change.
+ */
+function requestMissingChangelogEntries(modules, entries, diagnostics) {
+    const missing = modules
+        .filter((module) => module.ownFilesChanged && !entries.has(module.key))
+        .map((module) => module.key);
+    if (missing.length === 0)
+        return;
+    // ONE diagnostic listing the modules, not one per module. A change that
+    // touches every module's build script or a shared config asks the same
+    // question about forty of them at once, and forty copies of one sentence bury
+    // the plan they are printed beside — the more so because they go to stderr
+    // while the plan goes to stdout, so a piped run interleaves them.
+    //
+    // The fix for all of them is also one fragment, since a fragment names as many
+    // modules as it likes.
+    diagnostics.push({
+        severity: "warning",
+        code: "CHANGELOG_ENTRY_REQUESTED",
+        message: `${missing.length} module(s) have their own changes but no fragment describes them, so ` +
+            `their changelogs will not mention this release: ${missing.join(", ")}. ` +
+            `One \`telo release add\` can name them all.`,
+    });
+}
+/**
+ * The base the digests were built against has to be the base they were recorded
+ * against, or the manifest layers are not comparable: canonicalization writes
+ * the destination into them.
+ */
+function checkRegistryAgreement(evidence, diagnostics) {
+    const recorded = evidence.ledger.registry;
+    if (!recorded || !evidence.registry || recorded === evidence.registry)
+        return;
+    diagnostics.push({
+        severity: "error",
+        code: "LEDGER_REGISTRY_MISMATCH",
+        message: `The ledger's digests were taken against '${recorded}', but this run built against ` +
+            `'${evidence.registry}'. Publishing rewrites each relative import to ` +
+            `'<base>/<sibling>@<version>', so the manifest layers of the two are different bytes ` +
+            `and comparing them would report every module as changed.`,
+    });
+}
+/**
+ * Dependency order over in-repo imports — a dependency before its dependents.
+ *
+ * This is also the publish order, and it is not optional there: publishing
+ * canonicalizes a relative import and then hard-fails when the derived ref does
+ * not already resolve, so a sibling has to be pushed first.
+ *
+ * A cycle keeps its members in key order rather than throwing. A module graph
+ * should not have one, but a release is the wrong moment to discover it, and the
+ * ordering degrades to "arbitrary among the cycle" rather than to nothing.
+ */
+export function orderByImports(modules) {
+    const byKey = new Map(modules.map((module) => [module.key, module]));
+    const ordered = [];
+    const state = new Map();
+    const visit = (key) => {
+        const module = byKey.get(key);
+        if (!module || state.get(key))
+            return;
+        state.set(key, "visiting");
+        for (const dependency of [...module.imports].sort())
+            visit(dependency);
+        state.set(key, "done");
+        ordered.push(module);
+    };
+    for (const key of [...byKey.keys()].sort())
+        visit(key);
+    return ordered;
+}

package/dist/release/version-stamp.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Writing a module's one version into every manifest it owns.
+ *
+ * A module has a single version across `telo.yaml`, `nodejs/package.json` and
+ * `rust/Cargo.toml`. Three formats, one rule: find the scalar, splice over its
+ * span, touch nothing else. That is `yaml-source-edit.ts`'s primitive — the same
+ * one the quick fix, `telo migrate` and `telo upgrade`'s pin rewrite use — so a
+ * bump lands as a one-line diff instead of a re-serialized file that re-folds
+ * every block scalar in a 900-line manifest.
+ *
+ * Each stamp returns `undefined` when the file carries no version to write,
+ * which is not an error: a module may own only a `telo.yaml`, and 42 of the
+ * standard library's packages have no Rust crate. A file that *has* a version in
+ * a shape this cannot address is a hard error instead, because silently skipping
+ * it would publish an artifact whose manifests disagree about what it is.
+ */
+export declare class VersionStampError extends Error {
+}
+/**
+ * `metadata.version` on the **module doc** — the first document, the one whose
+ * kind is `Telo.Application` or `Telo.Library`. Deliberately not "any
+ * `metadata.version` in the file": a `Telo.Definition` further down may carry
+ * one, and the regex-replacement changie was configured with matched by line
+ * shape rather than by position, which is why it needed a hand-maintained count
+ * of how many lines it was allowed to hit.
+ */
+export declare function stampManifestVersion(text: string, version: string, where: string): string | undefined;
+/** Read the module doc's `metadata.version` without rewriting it. */
+export declare function readManifestVersion(text: string): string | undefined;
+/**
+ * The top-level `"version"` of a `package.json`.
+ *
+ * Parsed with the YAML reader rather than `JSON.parse`, because JSON is a YAML
+ * subset and this one needs the node's *source range* — `JSON.parse` discards it,
+ * and re-serializing with `JSON.stringify` would reformat a file whose
+ * indentation, key order and trailing newline are all conventions someone chose.
+ */
+export declare function stampPackageVersion(text: string, version: string, where: string): string | undefined;
+/**
+ * `version` in a `Cargo.toml`'s `[package]` table.
+ *
+ * Scanned rather than parsed: TOML is not YAML, adding a TOML parser to the
+ * browser-safe analyzer for one scalar is not a trade worth making, and the
+ * shape being addressed is the canonical one cargo itself writes. The scan is
+ * bounded to the `[package]` table so a `version` under `[dependencies.x]`
+ * cannot be hit, and a `[package]` whose version is not a simple quoted scalar
+ * is refused rather than guessed at.
+ */
+export declare function stampCrateVersion(text: string, version: string, where: string): string | undefined;
+//# sourceMappingURL=version-stamp.d.ts.map

package/dist/release/version-stamp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-stamp.d.ts","sourceRoot":"","sources":["../../src/release/version-stamp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,qBAAa,iBAAkB,SAAQ,KAAK;CAAG;AAqB/C;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,SAAS,CAYpB;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMpE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,SAAS,CAKpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,SAAS,CA+BpB"}

package/dist/release/version-stamp.js

@@ -0,0 +1,119 @@
+/**
+ * Writing a module's one version into every manifest it owns.
+ *
+ * A module has a single version across `telo.yaml`, `nodejs/package.json` and
+ * `rust/Cargo.toml`. Three formats, one rule: find the scalar, splice over its
+ * span, touch nothing else. That is `yaml-source-edit.ts`'s primitive — the same
+ * one the quick fix, `telo migrate` and `telo upgrade`'s pin rewrite use — so a
+ * bump lands as a one-line diff instead of a re-serialized file that re-folds
+ * every block scalar in a 900-line manifest.
+ *
+ * Each stamp returns `undefined` when the file carries no version to write,
+ * which is not an error: a module may own only a `telo.yaml`, and 42 of the
+ * standard library's packages have no Rust crate. A file that *has* a version in
+ * a shape this cannot address is a hard error instead, because silently skipping
+ * it would publish an artifact whose manifests disagree about what it is.
+ */
+import { defaultCustomTags } from "@telorun/templating";
+import { isScalar, parseAllDocuments, parseDocument } from "yaml";
+import { applyTextEdits, renderFixReplacement } from "../yaml-source-edit.js";
+export class VersionStampError extends Error {
+}
+/** Replace the scalar at `[start, end)` with `version`, re-quoted in the
+ *  author's own style. */
+function spliceScalar(text, node, version, where) {
+    const range = node.range;
+    if (!range) {
+        throw new VersionStampError(`${where}: the version scalar carries no source range.`);
+    }
+    const [start, end] = range;
+    const source = text.slice(start, end);
+    const replacement = renderFixReplacement(source, version);
+    if (replacement === undefined) {
+        throw new VersionStampError(`${where}: the version is written as '${source}', which cannot be rewritten in place. ` +
+            `Write it as a plain or quoted scalar on one line.`);
+    }
+    return applyTextEdits(text, [{ start, end, newText: replacement }]);
+}
+/**
+ * `metadata.version` on the **module doc** — the first document, the one whose
+ * kind is `Telo.Application` or `Telo.Library`. Deliberately not "any
+ * `metadata.version` in the file": a `Telo.Definition` further down may carry
+ * one, and the regex-replacement changie was configured with matched by line
+ * shape rather than by position, which is why it needed a hand-maintained count
+ * of how many lines it was allowed to hit.
+ */
+export function stampManifestVersion(text, version, where) {
+    const docs = parseAllDocuments(text, { customTags: defaultCustomTags() });
+    const doc = docs[0];
+    if (!doc)
+        return undefined;
+    const metadata = doc.get("metadata", true);
+    if (!metadata || typeof metadata.get !== "function")
+        return undefined;
+    const node = metadata.get("version", true);
+    if (!isScalar(node))
+        return undefined;
+    return spliceScalar(text, node, version, where);
+}
+/** Read the module doc's `metadata.version` without rewriting it. */
+export function readManifestVersion(text) {
+    const docs = parseAllDocuments(text, { customTags: defaultCustomTags() });
+    const first = docs[0]?.toJSON();
+    if (first?.kind !== "Telo.Application" && first?.kind !== "Telo.Library")
+        return undefined;
+    const version = first.metadata?.version;
+    return typeof version === "string" ? version : undefined;
+}
+/**
+ * The top-level `"version"` of a `package.json`.
+ *
+ * Parsed with the YAML reader rather than `JSON.parse`, because JSON is a YAML
+ * subset and this one needs the node's *source range* — `JSON.parse` discards it,
+ * and re-serializing with `JSON.stringify` would reformat a file whose
+ * indentation, key order and trailing newline are all conventions someone chose.
+ */
+export function stampPackageVersion(text, version, where) {
+    const doc = parseDocument(text);
+    const node = doc.get("version", true);
+    if (!isScalar(node))
+        return undefined;
+    return spliceScalar(text, node, version, where);
+}
+/**
+ * `version` in a `Cargo.toml`'s `[package]` table.
+ *
+ * Scanned rather than parsed: TOML is not YAML, adding a TOML parser to the
+ * browser-safe analyzer for one scalar is not a trade worth making, and the
+ * shape being addressed is the canonical one cargo itself writes. The scan is
+ * bounded to the `[package]` table so a `version` under `[dependencies.x]`
+ * cannot be hit, and a `[package]` whose version is not a simple quoted scalar
+ * is refused rather than guessed at.
+ */
+export function stampCrateVersion(text, version, where) {
+    const table = /^[ \t]*\[package\][ \t]*$/m.exec(text);
+    if (!table)
+        return undefined;
+    const bodyStart = table.index + table[0].length;
+    const next = /^[ \t]*\[/m.exec(text.slice(bodyStart));
+    const bodyEnd = next ? bodyStart + next.index : text.length;
+    const entry = /^([ \t]*version[ \t]*=[ \t]*)(".*?"|'.*?')[ \t]*$/m.exec(text.slice(bodyStart, bodyEnd));
+    if (!entry) {
+        // A `[package]` with `version.workspace = true` inherits from the workspace
+        // and genuinely has nothing here to stamp; anything else is a shape this
+        // cannot address, and writing nothing would leave the crate behind.
+        if (/^[ \t]*version[ \t]*\.[ \t]*workspace[ \t]*=/m.test(text.slice(bodyStart, bodyEnd))) {
+            return undefined;
+        }
+        if (/^[ \t]*version[ \t]*=/m.test(text.slice(bodyStart, bodyEnd))) {
+            throw new VersionStampError(`${where}: [package].version is not a quoted scalar on one line, so it cannot be ` +
+                `rewritten in place.`);
+        }
+        return undefined;
+    }
+    const start = bodyStart + entry.index + entry[1].length;
+    const quote = entry[2][0];
+    return applyTextEdits(text, [
+        { start, end: start + entry[2].length, newText: `${quote}${version}${quote}` },
+    ]);
+}