@telorun/analyzer 0.73.0 → 0.74.0

package/dist/module-named-files.js

@@ -0,0 +1,115 @@
+/**
+ * The rules that relate a module's `native:` entries, its file claims and its
+ * `sources:` block — which files a source may stage, which declarations collide
+ * on one path, and which staged entries nothing names.
+ *
+ * One home, because `telo check` (`validate-native-entries.ts`,
+ * `validate-source-entries.ts`) and `telo publish` apply the same rules to the
+ * same manifest; two copies would each drift toward whatever its own tests pin.
+ * Callers read the three blocks with their own readers and hand the results in.
+ * Browser-safe: no filesystem.
+ */
+import { PLATFORM_AXES, describeSelector } from "./artifact-selector.js";
+const CLAIM_LABEL = {
+    controller: "the controller candidate",
+    library: "the exports.code entry",
+    assets: "the embed",
+};
+/** The declaration behind a claim, for messages: `the controller candidate pkg:… on Telo.Definition/Reader`. */
+export function describeClaim(located) {
+    const { claim, where } = located;
+    return `${CLAIM_LABEL[claim.role]} ${claim.origin}${where === undefined ? "" : ` on ${where}`}`;
+}
+/**
+ * Every `native:` entry whose path the module also names as code or as an embed.
+ * Each declaration decides a different layer, and a file extracts from exactly
+ * one — a runtime materializing one would find the file missing through the other.
+ */
+export function nativeClaimConflicts(native, claims) {
+    const out = [];
+    for (const entry of native) {
+        for (const claim of claims) {
+            if (claim.claim.path === entry.path)
+                out.push({ entry, claim });
+        }
+    }
+    return out;
+}
+/**
+ * The files the module names that a `sources:` entry may stage: every `native:`
+ * entry's path, and every bundled controller candidate's `path=` that carries a
+ * platform qualifier. A platform-neutral candidate is one bundle for every host,
+ * which nothing stages.
+ */
+export function stageableFiles(native, claims) {
+    const out = new Map();
+    for (const entry of native) {
+        if (out.has(entry.path))
+            continue;
+        out.set(entry.path, {
+            path: entry.path,
+            label: `${entry.origin} for ${describeSelector(entry.selector)}`,
+            layer: `native ${describeSelector(entry.selector)}`,
+            built: false,
+        });
+    }
+    for (const { claim } of claims) {
+        if (claim.role !== "controller")
+            continue;
+        if (!PLATFORM_AXES.some((axis) => claim.selector[axis] !== undefined))
+            continue;
+        const existing = out.get(claim.path);
+        if (existing) {
+            if (claim.localPath && !existing.built)
+                out.set(claim.path, { ...existing, built: true });
+            continue;
+        }
+        out.set(claim.path, {
+            path: claim.path,
+            label: `controller candidate ${claim.origin}`,
+            layer: `controller ${describeSelector(claim.selector)}`,
+            built: claim.localPath !== undefined,
+        });
+    }
+    return out;
+}
+/**
+ * The staged entries nothing in the module names: not a stageable file, and not
+ * one of the entry's own source's notices. `alsoNamed` holds paths the caller
+ * knows are named though they did not read — a `native:` entry with an unrelated
+ * problem — so one defect is not reported twice.
+ */
+export function unclaimedSourceEntries(sources, stageable, alsoNamed = new Set()) {
+    const out = [];
+    for (const source of sources) {
+        for (const entry of source.entries) {
+            if (stageable.has(entry.path) || source.notices.includes(entry.path))
+                continue;
+            if (alsoNamed.has(entry.path))
+                continue;
+            out.push({ source, entry });
+        }
+    }
+    return out;
+}
+/**
+ * The link entries whose target ships in another layer. A runtime extracts only
+ * the layers it needs, so such a link dangles wherever the other layer is not
+ * materialized. A notice ships in `common`.
+ */
+export function crossLayerSourceLinks(sources, stageable) {
+    const layerOf = (source, path) => stageable.get(path)?.layer ?? (source.notices.includes(path) ? "common" : undefined);
+    const out = [];
+    for (const source of sources) {
+        for (const entry of source.entries) {
+            if (entry.kind !== "link")
+                continue;
+            const layer = layerOf(source, entry.path);
+            const targetLayer = layerOf(source, entry.resolved);
+            if (layer !== undefined && targetLayer !== undefined && layer !== targetLayer) {
+                out.push({ source, entry, layer, targetLayer });
+            }
+        }
+    }
+    return out;
+}

package/dist/native-entries.d.ts

@@ -0,0 +1,83 @@
+/**
+ * A module's **native files** — the `native:` block on a `Telo.Library` or
+ * `Telo.Application` doc, naming each platform-specific file the runtime does
+ * not import as a controller (a sidecar addon, a `dlopen`'d library, a
+ * per-platform data blob) once per platform tuple.
+ *
+ * ```yaml
+ * native:
+ *   - name: better-sqlite3
+ *     format: node
+ *     os: linux
+ *     arch: amd64
+ *     libc: gnu
+ *     abi: node-137
+ *     path: ./native/linux-amd64-gnu-node-137/better_sqlite3.node
+ * ```
+ *
+ * Declared on the module doc rather than on a controller candidate, so the
+ * platform matrix is written once whatever the kind count, and the
+ * platform-neutral bundle ships once. Publish places each entry's file in the
+ * `native` layer of its selector (spec §1.2).
+ *
+ * `format` plus the platform axes build the same `ArtifactSelector` a
+ * controller candidate does, through the one selector normalizer. The declared
+ * `path` is the in-layer path — never flattened — because every layer of a
+ * module extracts into one directory, so paths must be disjoint per tuple.
+ *
+ * The single reader: the strict half is `validate-native-entries.ts`, and
+ * publish consumes the entries this returns. Browser-safe: string work only.
+ */
+import { type ArtifactSelector } from "./artifact-selector.js";
+export interface NativeEntry {
+    /** The logical name controller code asks for. */
+    readonly name: string;
+    readonly selector: ArtifactSelector;
+    /** Module-root-relative POSIX path, normalized. */
+    readonly path: string;
+    /** Position in the `native:` list. */
+    readonly index: number;
+    /** Human-facing label for diagnostics: `native[0] ('better-sqlite3')`. */
+    readonly origin: string;
+}
+/**
+ * Why an entry could not be read.
+ *
+ * - `shape` — a missing, non-string or unknown key; the owner doc's JSON Schema
+ *   reports these in the same analysis pass.
+ * - `invalid` — a value the schema accepts and the grammar rejects: an empty
+ *   required string, a `name` or selector value outside the token grammar, an
+ *   `abi` outside its value form, a path that names no single file.
+ * - `escape` — a `path` pointing outside the module directory.
+ */
+export interface NativeEntryProblem {
+    readonly kind: "shape" | "invalid" | "escape";
+    readonly index?: number;
+    readonly origin: string;
+    /** Dotted/bracketed path from the module doc root, for `data.path`. */
+    readonly path: string;
+    /** What is wrong, prefixed with `origin`. */
+    readonly message: string;
+}
+export interface NativeEntries {
+    readonly entries: NativeEntry[];
+    readonly problems: NativeEntryProblem[];
+}
+export type PathVerdict = {
+    path: string;
+} | {
+    kind: "invalid" | "escape";
+    detail: string;
+};
+/** Normalize a module-relative path, deciding confinement from the written
+ *  path alone: the module root is the one directory every path is measured
+ *  from, so `..` below depth zero is an escape wherever the module sits. */
+export declare function normalizeNativePath(raw: string): PathVerdict;
+/**
+ * Read the `native:` block off an owner document's JSON projection.
+ *
+ * An entry with any problem is left out of `entries`, never read partially: a
+ * half-read entry would name a layer the author did not declare.
+ */
+export declare function readNativeEntries(ownerJson: unknown): NativeEntries;
+//# sourceMappingURL=native-entries.d.ts.map

package/dist/native-entries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-entries.d.ts","sourceRoot":"","sources":["../src/native-entries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,wBAAwB,CAAC;AAchC,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC9C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,WAAW,EAAE,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,EAAE,CAAC;CACzC;AAED,MAAM,MAAM,WAAW,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5F;;4EAE4E;AAC5E,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAgC5D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,OAAO,GAAG,aAAa,CA8FnE"}

package/dist/native-entries.js

@@ -0,0 +1,169 @@
+/**
+ * A module's **native files** — the `native:` block on a `Telo.Library` or
+ * `Telo.Application` doc, naming each platform-specific file the runtime does
+ * not import as a controller (a sidecar addon, a `dlopen`'d library, a
+ * per-platform data blob) once per platform tuple.
+ *
+ * ```yaml
+ * native:
+ *   - name: better-sqlite3
+ *     format: node
+ *     os: linux
+ *     arch: amd64
+ *     libc: gnu
+ *     abi: node-137
+ *     path: ./native/linux-amd64-gnu-node-137/better_sqlite3.node
+ * ```
+ *
+ * Declared on the module doc rather than on a controller candidate, so the
+ * platform matrix is written once whatever the kind count, and the
+ * platform-neutral bundle ships once. Publish places each entry's file in the
+ * `native` layer of its selector (spec §1.2).
+ *
+ * `format` plus the platform axes build the same `ArtifactSelector` a
+ * controller candidate does, through the one selector normalizer. The declared
+ * `path` is the in-layer path — never flattened — because every layer of a
+ * module extracts into one directory, so paths must be disjoint per tuple.
+ *
+ * The single reader: the strict half is `validate-native-entries.ts`, and
+ * publish consumes the entries this returns. Browser-safe: string work only.
+ */
+import { ArtifactSelectorError, PLATFORM_AXES, selectorFromQualifiers, } from "./artifact-selector.js";
+/** Every key an entry may carry. */
+const KNOWN_KEYS = new Set(["name", "format", "path", ...PLATFORM_AXES]);
+/** Axes an entry must state: a native file is built for one platform. */
+const REQUIRED_AXES = ["os", "arch"];
+/** The selector value grammar, applied to `name` as written. */
+const NAME_TOKEN = /^[a-z0-9][a-z0-9_.-]*$/;
+const GLOB_CHARS = /[*?[\]{}]/;
+const URI_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+/** Normalize a module-relative path, deciding confinement from the written
+ *  path alone: the module root is the one directory every path is measured
+ *  from, so `..` below depth zero is an escape wherever the module sits. */
+export function normalizeNativePath(raw) {
+    if (URI_SCHEME.test(raw) || raw.startsWith("/") || raw.startsWith("\\")) {
+        return {
+            kind: "escape",
+            detail: `path '${raw}' is not relative to the module root. A native file ships inside the module artifact, so name it relative to the directory holding telo.yaml.`,
+        };
+    }
+    if (GLOB_CHARS.test(raw)) {
+        return {
+            kind: "invalid",
+            detail: `path '${raw}' looks like a pattern. A native entry names exactly one file.`,
+        };
+    }
+    const out = [];
+    for (const segment of raw.split(/[/\\]+/)) {
+        if (segment === "" || segment === ".")
+            continue;
+        if (segment !== "..") {
+            out.push(segment);
+            continue;
+        }
+        if (out.length === 0) {
+            return {
+                kind: "escape",
+                detail: `path '${raw}' points above the module root. A native file must ship inside the module directory.`,
+            };
+        }
+        out.pop();
+    }
+    if (out.length === 0) {
+        return { kind: "invalid", detail: `path '${raw}' resolves to the module root, not to a file.` };
+    }
+    return { path: out.join("/") };
+}
+/**
+ * Read the `native:` block off an owner document's JSON projection.
+ *
+ * An entry with any problem is left out of `entries`, never read partially: a
+ * half-read entry would name a layer the author did not declare.
+ */
+export function readNativeEntries(ownerJson) {
+    const declared = ownerJson?.native;
+    const entries = [];
+    const problems = [];
+    if (declared === undefined)
+        return { entries, problems };
+    if (!Array.isArray(declared)) {
+        problems.push({
+            kind: "shape",
+            origin: "native",
+            path: "native",
+            message: "native: expected a list of entries.",
+        });
+        return { entries, problems };
+    }
+    declared.forEach((raw, index) => {
+        const at = `native[${index}]`;
+        const shape = (detail) => problems.push({ kind: "shape", index, origin: at, path: at, message: `${at}: ${detail}` });
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+            shape("expected an object.");
+            return;
+        }
+        const entry = raw;
+        const unknown = Object.keys(entry).filter((key) => !KNOWN_KEYS.has(key));
+        if (unknown.length > 0) {
+            shape(`unknown ${unknown.length === 1 ? "key" : "keys"} ${unknown.map((k) => `'${k}'`).join(", ")}. ` +
+                `Known: ${[...KNOWN_KEYS].join(", ")}.`);
+            return;
+        }
+        const requiredKeys = ["name", "format", ...REQUIRED_AXES, "path"];
+        const missing = requiredKeys.filter((key) => typeof entry[key] !== "string");
+        if (missing.length > 0) {
+            shape(`${missing.map((k) => `'${k}'`).join(", ")} must be strings.`);
+            return;
+        }
+        // A blank string satisfies the schema's `type: string`, so it is reported here.
+        const blank = requiredKeys.filter((key) => entry[key].trim() === "");
+        if (blank.length > 0) {
+            for (const key of blank) {
+                problems.push({
+                    kind: "invalid",
+                    index,
+                    origin: at,
+                    path: `${at}.${key}`,
+                    message: `${at}: '${key}' must not be empty.`,
+                });
+            }
+            return;
+        }
+        const name = entry.name;
+        const origin = `${at} ('${name}')`;
+        if (!NAME_TOKEN.test(name)) {
+            problems.push({
+                kind: "invalid",
+                index,
+                origin,
+                path: `${at}.name`,
+                message: `${origin}: name '${name}' is not a canonical token. Use lowercase letters, digits, ` +
+                    `'.', '-' or '_', starting with a letter or digit.`,
+            });
+            return;
+        }
+        let selector;
+        try {
+            selector = selectorFromQualifiers(entry.format, entry, origin);
+        }
+        catch (err) {
+            if (!(err instanceof ArtifactSelectorError))
+                throw err;
+            problems.push({ kind: "invalid", index, origin, path: at, message: err.message });
+            return;
+        }
+        const verdict = normalizeNativePath(entry.path.trim());
+        if (!("path" in verdict)) {
+            problems.push({
+                kind: verdict.kind,
+                index,
+                origin,
+                path: `${at}.path`,
+                message: `${origin}: ${verdict.detail}`,
+            });
+            return;
+        }
+        entries.push({ name, selector, path: verdict.path, index, origin });
+    });
+    return { entries, problems };
+}

package/dist/normalize-inline-resources.d.ts

@@ -1,23 +1,51 @@
-import type { ResourceManifest } from "@telorun/sdk";
-import type { DefinitionRegistry } from "./definition-registry.js";
+import { type ResourceManifest } from "@telorun/sdk";
 import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
 /**
  * Phase 2 — Inline resource normalization.
  *
- * After all manifests and definitions are loaded, walks every non-system resource's
- * x-telo-ref slots. For each inline resource value (has keys beyond kind/name/metadata),
- * assigns a deterministic name, extracts it as a first-class manifest, and replaces
- * the inline value in-place with `{kind, name}`. Newly extracted resources are enqueued
- * so nested inlines are resolved in the same pass.
+ * Every inline declaration (a `{kind, …config}` with no `name`) is extracted as a
+ * first-class manifest under a deterministic name and replaced in place with
+ * `{kind, name}`. Two kinds of slot carry one:
+ *
+ *  - a REFERENCE slot, found through the kind's field map, named
+ *    `{parentName}_{pathSegment}[_{itemName|index}]_{fieldName}`
+ *    (`TestBasicAddition_steps_AddTwoNumbers_invoke`);
+ *  - a STEP's dispatch target, at any nesting depth of a step body, named by
+ *    `inlineStepTargetName` — the name the step engine has always registered it
+ *    under, which is durable identity and so must not move with the extraction.
+ *
+ * Step slots are found through the kind's step-body annotation and walked with
+ * `walkStepArray`, never through the field map: that map is the kernel's Phase-5
+ * injection surface, and a step's target resolves at dispatch.
+ *
+ * Every extracted manifest is queued in turn, so an inline declaration nested in
+ * another's slots — a handler inside an inline step target — is extracted too.
+ * So is every member of an `x-telo-scope` array, which is a declaration of its
+ * own.
+ *
+ * WHERE an extraction is created:
+ *
+ *  - a reference slot lying in a region of a scope its owner declares (a
+ *    sequence's `targets:`) resolves against that scope, so its declaration
+ *    joins the scope's array and is created per scope run;
+ *  - a step target is created where its owner is — the module's top level, or
+ *    the scope array holding a scope member — and never in a scope the owner
+ *    declares, because that would make every step target of a sequence with a
+ *    `with:` block a scoped resource and move its durable identity;
+ *  - any other extraction is created where its owner is.
+ *
+ * A declaration written inside a scope's region and created outside it records
+ * the scope (`xTeloOrigin.outsideScopes`), and `validateScopedNameReach` reports
+ * a reference from it to a name that scope declares.
  *
- * Naming scheme:
- *   {parentName}_{pathSegment}[_{itemName|index}]_{fieldName}
- *   e.g. TestBasicAddition_steps_AddTwoNumbers_invoke
- *        TestBasicAddition_steps_0_invoke  (when step has no name)
+ * An extraction out of a dependency's forwarded manifest is that dependency's
+ * code: it is stamped `forwardedInternal` (see `isForwardedDeclaration`) and
+ * carries the declaring module's `moduleGlobals`, as its parent does.
  *
  * Returns a new array of deep-cloned manifests (the rewrites land on the clones)
- * plus all extracted manifests. The caller's manifests — array and elements — are
- * never mutated; this is the analyzer's immutability boundary.
+ * plus every top-level extraction. The caller's manifests — array and elements —
+ * are never mutated; this is the analyzer's immutability boundary.
  */
 export declare function normalizeInlineResources(resources: ResourceManifest[], registry: DefinitionRegistry, aliases?: AliasResolver, aliasesByModule?: Map<string, AliasResolver>): ResourceManifest[];
 //# sourceMappingURL=normalize-inline-resources.d.ts.map

package/dist/normalize-inline-resources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"normalize-inline-resources.d.ts","sourceRoot":"","sources":["../src/normalize-inline-resources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AA6CzD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC3C,gBAAgB,EAAE,CA0EpB"}
+{"version":3,"file":"normalize-inline-resources.d.ts","sourceRoot":"","sources":["../src/normalize-inline-resources.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiD,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEpG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAqGnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC3C,gBAAgB,EAAE,CAuGpB"}