@telorun/analyzer 0.59.0 → 0.61.0

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

package/dist/release/workspace-config.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `telo-workspace.yaml` — the release anchor.
+ *
+ * Every path the release system names — a module key, a ledger entry, a
+ * fragment's `modules:` — is relative to this file's directory. That is the
+ * whole of its job: **its location is the anchor**, and its one field names the
+ * subtrees that may hold modules, which is not derivable (a whole-tree scan
+ * would read every example and every cached `.telo/manifests` copy as a released
+ * module).
+ *
+ * The file is **optional and read only by `telo release`**. Nothing else — not
+ * `run`, `check`, `publish`, `install`, `upgrade`, `migrate`, `module`, and not
+ * the kernel — looks for it, so a single-manifest repo, a bare `examples/`
+ * directory and a third-party module checkout keep working with nothing added.
+ * Any field added later must be true of the whole tree, not derivable from it,
+ * and harmless by its absence.
+ *
+ * Parsing lives here, in the browser-safe half, because the editor answers
+ * "what does changing this library bump?" from the same model. Finding the file
+ * on disk is the CLI's half — this side takes text.
+ */
+export declare const WORKSPACE_FILENAME = "telo-workspace.yaml";
+export interface WorkspaceConfig {
+    /**
+     * Gitignore-style patterns, workspace-relative, naming the subtrees that may
+     * hold modules (`modules/*`, `apps/*`). A pattern names a place to look, never
+     * a module: what makes a directory a module is its `telo.yaml`.
+     */
+    readonly modules: readonly string[];
+}
+export declare class WorkspaceConfigError extends Error {
+}
+/**
+ * Parse the marker file's text.
+ *
+ * Strict about its one field, because there is nothing here to be lenient with:
+ * an empty or absent `modules:` names no subtree, so discovery would find no
+ * module and every gate would silently pass over a whole repo.
+ */
+export declare function parseWorkspaceConfig(text: string, where: string): WorkspaceConfig;
+//# sourceMappingURL=workspace-config.d.ts.map

package/dist/release/workspace-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-config.d.ts","sourceRoot":"","sources":["../../src/release/workspace-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,eAAO,MAAM,kBAAkB,wBAAwB,CAAC;AAExD,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,qBAAa,oBAAqB,SAAQ,KAAK;CAAG;AAElD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,eAAe,CAoCjF"}

package/dist/release/workspace-config.js

@@ -0,0 +1,60 @@
+/**
+ * `telo-workspace.yaml` — the release anchor.
+ *
+ * Every path the release system names — a module key, a ledger entry, a
+ * fragment's `modules:` — is relative to this file's directory. That is the
+ * whole of its job: **its location is the anchor**, and its one field names the
+ * subtrees that may hold modules, which is not derivable (a whole-tree scan
+ * would read every example and every cached `.telo/manifests` copy as a released
+ * module).
+ *
+ * The file is **optional and read only by `telo release`**. Nothing else — not
+ * `run`, `check`, `publish`, `install`, `upgrade`, `migrate`, `module`, and not
+ * the kernel — looks for it, so a single-manifest repo, a bare `examples/`
+ * directory and a third-party module checkout keep working with nothing added.
+ * Any field added later must be true of the whole tree, not derivable from it,
+ * and harmless by its absence.
+ *
+ * Parsing lives here, in the browser-safe half, because the editor answers
+ * "what does changing this library bump?" from the same model. Finding the file
+ * on disk is the CLI's half — this side takes text.
+ */
+import { parseDocument } from "yaml";
+export const WORKSPACE_FILENAME = "telo-workspace.yaml";
+export class WorkspaceConfigError extends Error {
+}
+/**
+ * Parse the marker file's text.
+ *
+ * Strict about its one field, because there is nothing here to be lenient with:
+ * an empty or absent `modules:` names no subtree, so discovery would find no
+ * module and every gate would silently pass over a whole repo.
+ */
+export function parseWorkspaceConfig(text, where) {
+    let value;
+    try {
+        value = parseDocument(text).toJSON();
+    }
+    catch (err) {
+        throw new WorkspaceConfigError(`${where} is not valid YAML: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new WorkspaceConfigError(`${where} must be a YAML mapping.`);
+    }
+    const record = value;
+    for (const key of Object.keys(record)) {
+        if (key !== "modules") {
+            throw new WorkspaceConfigError(`${where}: unknown field '${key}'. The workspace marker carries only 'modules:' — ` +
+                `the subtrees that may hold modules.`);
+        }
+    }
+    const modules = record.modules;
+    if (!Array.isArray(modules) || modules.some((entry) => typeof entry !== "string")) {
+        throw new WorkspaceConfigError(`${where}: 'modules' must be a list of path patterns, e.g. [modules/*, apps/*].`);
+    }
+    if (modules.length === 0) {
+        throw new WorkspaceConfigError(`${where}: 'modules' is empty, so no directory can ever be discovered as a module. ` +
+            `List the subtrees that hold them, e.g. [modules/*, apps/*].`);
+    }
+    return { modules: modules };
+}

package/dist/schema-compat.js

@@ -1,7 +1,8 @@
 import AjvModule from "ajv";
 import addFormats from "ajv-formats";
-import { isRefSentinel, isTaggedSentinel, ManifestRootSchema, producedTypeOf, } from "@telorun/templating";
+import { isRefSentinel, isTaggedSentinel, producedTypeOf, } from "@telorun/templating";
 import { celBaseOfValueType, celTypeOfValueType, readValueTypeSlot, valueBrandBases, valueTypeOf, valueTypePlaceholder, } from "@telorun/sdk";
+import { ManifestRootSchema } from "./manifest-schemas.js";
 import { registerTeloKeywords } from "./value-type-keyword.js";
 const Ajv = AjvModule.default ?? AjvModule;
 /** Creates a configured AJV instance (allErrors, strict: false, with formats).

package/dist/validate-module-artifact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-module-artifact.d.ts","sourceRoot":"","sources":["../src/validate-module-artifact.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAQrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,gBAAgB,EAAE,GAAG,kBAAkB,EAAE,CAO1F"}
+{"version":3,"file":"validate-module-artifact.d.ts","sourceRoot":"","sources":["../src/validate-module-artifact.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAUrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,gBAAgB,EAAE,GAAG,kBAAkB,EAAE,CAQ1F"}

package/dist/validate-module-artifact.js

@@ -1,5 +1,6 @@
 import { parseLayerIndex, LayerIndexError } from "./artifact-layer-index.js";
-import { ArtifactSelectorError, PLATFORM_AXES, selectorFromQualifiers, } from "./artifact-selector.js";
+import { ArtifactSelectorError, PLATFORM_AXES, selectorFromQualifiers, selectorKey, } from "./artifact-selector.js";
+import { readLibraryCandidates } from "./module-library.js";
 import { DiagnosticSeverity } from "./types.js";
 const SOURCE = "telo-analyzer";
 /**
@@ -30,9 +31,60 @@ export function validateModuleArtifact(manifests) {
     for (const manifest of manifests) {
         validateLayerIndex(manifest, out);
         validateControllerSelectors(manifest, out);
+        validateLibraryCandidates(manifest, out);
     }
     return out;
 }
+/**
+ * The `exports.code:` block on a `Telo.Library` doc.
+ *
+ * Reported here rather than left to the loader for the same reason a controller
+ * selector is: an entry that cannot be read names no entry point, so a
+ * consumer's bundle falls back to *inlining* the library — the module scope
+ * duplication this whole mechanism exists to remove — and it does so silently, on
+ * someone else's machine.
+ */
+function validateLibraryCandidates(manifest, out) {
+    // `Telo.Library` only. An application is a root with no importer, so it has no
+    // `exports:` block at all — and its schema is `additionalProperties: false`,
+    // so AJV already rejects the key by name in this same pass. A second
+    // diagnostic on that node would be two squiggles saying one thing.
+    if (manifest.kind !== "Telo.Library")
+        return;
+    const metadata = manifest.metadata;
+    const { candidates, problems } = readLibraryCandidates(manifest);
+    const resource = { kind: manifest.kind, name: metadata?.name };
+    for (const problem of problems) {
+        out.push({
+            severity: DiagnosticSeverity.Error,
+            code: "LIBRARY_CANDIDATE_INVALID",
+            source: SOURCE,
+            message: `Telo.Library/${metadata?.name ?? "(unnamed)"}: ${problem.origin}: ${problem.detail}`,
+            data: { resource, filePath: metadata?.source, path: "exports/code" },
+        });
+    }
+    // One specifier per selector: two candidates of one format claiming the same
+    // specifier leave the resolution ambiguous, and two specifiers for one format
+    // mean a consumer's import resolves by whichever candidate is read first.
+    const seen = new Map();
+    for (const candidate of candidates) {
+        const key = selectorKey(candidate.selector);
+        const first = seen.get(key);
+        if (first) {
+            out.push({
+                severity: DiagnosticSeverity.Error,
+                code: "LIBRARY_CANDIDATE_DUPLICATE",
+                source: SOURCE,
+                message: `Telo.Library/${metadata?.name ?? "(unnamed)"}: two 'exports.code' entries declare the ` +
+                    `selector ${key} ('${first.specifier}' and '${candidate.specifier}'). A module has one ` +
+                    `entry point per format — which is what makes "one specifier, one module scope" true.`,
+                data: { resource, filePath: metadata?.source, path: "exports/code" },
+            });
+            continue;
+        }
+        seen.set(key, candidate);
+    }
+}
 /** `local_path` names the source `path=` was built from, so a working copy runs
  *  with no build step. It is inert in a published artifact — which ships no
  *  `src/` — and contributes nothing to the selector, so it never affects which

package/dist/validate-step-inputs.d.ts

@@ -6,7 +6,7 @@ export interface StepInputIssue {
     message: string;
     /** Set when the issue is a type-argument disagreement rather than a contract
      *  shape violation — the two read differently and deserve their own code. */
-    code?: "CEL_TYPE_ARGUMENT_MISMATCH";
+    code?: "CEL_TYPE_ARGUMENT_MISMATCH" | "LIVE_VALUE_RETRIED";
 }
 /**
  * Validate every step's `inputs:` against the invoked target's declared input

package/dist/validate-step-inputs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-step-inputs.d.ts","sourceRoot":"","sources":["../src/validate-step-inputs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAoBnE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB;iFAC6E;IAC7E,IAAI,CAAC,EAAE,4BAA4B,CAAC;CACrC;AAGD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC7B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC9B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EACnC,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,YAAY;AACpB;;mEAEmE;AACnE,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAChC,cAAc,EAAE,CAiHlB"}
+{"version":3,"file":"validate-step-inputs.d.ts","sourceRoot":"","sources":["../src/validate-step-inputs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAqBnE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB;iFAC6E;IAC7E,IAAI,CAAC,EAAE,4BAA4B,GAAG,oBAAoB,CAAC;CAC5D;AAGD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC7B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC9B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EACnC,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,YAAY;AACpB;;mEAEmE;AACnE,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAChC,cAAc,EAAE,CAsJlB"}