@telorun/analyzer 0.61.0 → 0.62.0

package/dist/requires-block.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The single reader of a module doc's `requires:` block — the version ranges of
+ * runtime a module declares itself verified against. The load gate, the CLI's
+ * publish preflight and `upgrade`'s candidate filter all recognise the block
+ * here and nowhere else, the one-accessor rule `ref-slot.ts` and `zone-slot.ts`
+ * established. Browser-safe: no Node built-ins, so the editor reaches the
+ * identical rule the kernel does.
+ *
+ * ```yaml
+ * requires:
+ *   telo: ">=0.80.0"
+ *   host:
+ *     node: ">=20.0.0"
+ * ```
+ *
+ * **Two tiers, and the split is not cosmetic.** `telo` names the *manifest
+ * surface generation* a runtime implements — one scale shared by every kernel,
+ * Node, Rust or Go, independent of each kernel's own release identity — and it
+ * is the one axis verified by EXECUTION, by running the CLI at each edge of the
+ * declared range. Host axes cannot be edge-verified by any CI; they are asserted
+ * by the author and compared against the version the running host reports
+ * ({@link HostVersions}). A flat map would imply one semantics for both.
+ *
+ * Nesting is also what disambiguates the names: `nodejs` and `rust` are already
+ * *kernel labels* in this repo (`LABEL_TO_PURL_TYPE`, an `imports:` entry's
+ * `runtime:`), so a top-level `node:` reads as the Node kernel rather than the
+ * Node.js runtime — and no word escapes that, because the host runtime and the
+ * kernel implementation genuinely share a name. Under `host:` position carries
+ * the disambiguation and no word has to.
+ *
+ * **Ordering is normative: `telo` is checked before `host`, and before any
+ * unknown-axis complaint.** A module using an axis introduced in telo 0.85 also
+ * declares telo `>=0.85`, so an older runtime fails on the telo axis first and
+ * never has to decide what an axis it has never heard of means. That is what
+ * makes the block safely extensible; consumers get the order from
+ * {@link evaluateRequires} rather than re-deriving it.
+ */
+import { type VersionRange } from "./version-range.js";
+/**
+ * Host axes this analyzer knows.
+ *
+ * **An axis is in this list only when something checks it.** A declared
+ * requirement nothing compares is worse than no requirement at all: it validates,
+ * it reads as protection, and it silently protects nobody — the exact failure
+ * class this whole mechanism exists to remove, reintroduced inside it. So `rustc`
+ * is deliberately absent until the slice that builds controller crates can
+ * compare it; adding it there is a one-line change here plus a supplier in
+ * {@link HostVersions}, and until then an author writing it is told it is not a
+ * known axis rather than quietly reassured.
+ *
+ * Extending the set is a telo release, which is exactly why a module using a new
+ * axis must also raise its `telo` bound — and why `telo` is checked first.
+ */
+export declare const KNOWN_HOST_AXES: readonly ["node"];
+export type HostAxis = (typeof KNOWN_HOST_AXES)[number];
+export interface RequiresBlock {
+    /** The surface generation range, when declared. */
+    telo?: VersionRange;
+    /** Declared host axes, keyed by axis name. Empty when `host:` is absent. */
+    host: Partial<Record<HostAxis, VersionRange>>;
+}
+export interface RequiresIssue {
+    /** Dotted path within the doc, e.g. `requires.telo` or `requires.host.node`. */
+    path: string;
+    message: string;
+    /** The spelling to use instead, when there is an unambiguous one. */
+    hint?: string;
+    /** True for an unrecognized axis, which consumers suppress while the `telo`
+     *  requirement itself is unmet — an older runtime not knowing a newer axis is
+     *  a consequence of the version skew, not a second defect to report. */
+    unknownAxis?: boolean;
+}
+export interface ReadRequiresResult {
+    /** Present whenever the doc carries a `requires:` key at all, even a malformed
+     *  one — so a consumer can tell "declared nothing" from "declared badly". */
+    declared: boolean;
+    block: RequiresBlock;
+    issues: RequiresIssue[];
+}
+/**
+ * Read and parse the block off a module doc. Never throws. A malformed entry
+ * yields an issue AND is omitted from the block, so a consumer enforcing the
+ * block never silently treats garbage as a satisfied requirement — the issue is
+ * what makes the manifest fail, exactly as a malformed zone annotation does.
+ */
+export declare function readRequires(doc: Record<string, unknown> | undefined): ReadRequiresResult;
+/** What a runtime concluded about a module's declared requirements. */
+export type RequiresVerdict = {
+    satisfied: true;
+}
+/** An axis whose declared range excludes the version this runtime reported. */
+ | {
+    satisfied: false;
+    axis: "telo" | HostAxis;
+    declared: VersionRange;
+    running: string;
+};
+/** The versions a host can speak for. Absent entries are not checked — the
+ *  editor has no host to report, and an axis nothing supplies is skipped rather
+ *  than guessed. Every axis in {@link KNOWN_HOST_AXES} has a supplier; an axis
+ *  with none does not belong in the vocabulary (see the note there). */
+export interface HostVersions {
+    node?: string;
+}
+/**
+ * Evaluate a module's declared requirements against the runtime performing the
+ * analysis.
+ *
+ * `telo` is checked FIRST and short-circuits: a module using a host axis
+ * introduced in a later telo also declares that telo, so an older runtime must
+ * report the version skew rather than a host axis it may not even know. Absent
+ * declarations are satisfied — the bootstrap rule, permanent for everything
+ * published before the mechanism existed.
+ *
+ * **A version this cannot PARSE is satisfied, on every axis.** A runtime that
+ * cannot name its own version must not start rejecting modules on the strength
+ * of a number it could not read — the refusal-to-guess `module-version-order.ts`
+ * makes, pointed in the safe direction. The test is a parse, not a shape: `0.76`
+ * and `2024.1` look like versions and are not three-part ones, so a cheaper
+ * check (a leading digit, say) would fail them CLOSED and gate every module in
+ * the graph on a number nothing could compare. `AnalysisOptions.teloVersion` is
+ * hand-written by definition, so that is exactly where such a value arrives.
+ */
+export declare function evaluateRequires(block: RequiresBlock, running: string | undefined, host?: HostVersions): RequiresVerdict;
+//# sourceMappingURL=requires-block.d.ts.map

package/dist/requires-block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requires-block.d.ts","sourceRoot":"","sources":["../src/requires-block.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,eAAe,mBAAoB,CAAC;AACjD,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAKxD,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,4EAA4E;IAC5E,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC;CAC/C;AAED,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;4EAEwE;IACxE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC;iFAC6E;IAC7E,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAID;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,kBAAkB,CA4DzF;AAsBD,uEAAuE;AACvE,MAAM,MAAM,eAAe,GACvB;IAAE,SAAS,EAAE,IAAI,CAAA;CAAE;AACrB,+EAA+E;GAC7E;IACE,SAAS,EAAE,KAAK,CAAC;IACjB,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;IACxB,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEN;;;wEAGwE;AACxE,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,IAAI,GAAE,YAAiB,GACtB,eAAe,CAQjB"}

package/dist/requires-block.js

@@ -0,0 +1,182 @@
+/**
+ * The single reader of a module doc's `requires:` block — the version ranges of
+ * runtime a module declares itself verified against. The load gate, the CLI's
+ * publish preflight and `upgrade`'s candidate filter all recognise the block
+ * here and nowhere else, the one-accessor rule `ref-slot.ts` and `zone-slot.ts`
+ * established. Browser-safe: no Node built-ins, so the editor reaches the
+ * identical rule the kernel does.
+ *
+ * ```yaml
+ * requires:
+ *   telo: ">=0.80.0"
+ *   host:
+ *     node: ">=20.0.0"
+ * ```
+ *
+ * **Two tiers, and the split is not cosmetic.** `telo` names the *manifest
+ * surface generation* a runtime implements — one scale shared by every kernel,
+ * Node, Rust or Go, independent of each kernel's own release identity — and it
+ * is the one axis verified by EXECUTION, by running the CLI at each edge of the
+ * declared range. Host axes cannot be edge-verified by any CI; they are asserted
+ * by the author and compared against the version the running host reports
+ * ({@link HostVersions}). A flat map would imply one semantics for both.
+ *
+ * Nesting is also what disambiguates the names: `nodejs` and `rust` are already
+ * *kernel labels* in this repo (`LABEL_TO_PURL_TYPE`, an `imports:` entry's
+ * `runtime:`), so a top-level `node:` reads as the Node kernel rather than the
+ * Node.js runtime — and no word escapes that, because the host runtime and the
+ * kernel implementation genuinely share a name. Under `host:` position carries
+ * the disambiguation and no word has to.
+ *
+ * **Ordering is normative: `telo` is checked before `host`, and before any
+ * unknown-axis complaint.** A module using an axis introduced in telo 0.85 also
+ * declares telo `>=0.85`, so an older runtime fails on the telo axis first and
+ * never has to decide what an axis it has never heard of means. That is what
+ * makes the block safely extensible; consumers get the order from
+ * {@link evaluateRequires} rather than re-deriving it.
+ */
+import { parseModuleVersion } from "./module-version-order.js";
+import { isUnsatisfiable, parseVersionRange, rangeAccepts, } from "./version-range.js";
+/**
+ * Host axes this analyzer knows.
+ *
+ * **An axis is in this list only when something checks it.** A declared
+ * requirement nothing compares is worse than no requirement at all: it validates,
+ * it reads as protection, and it silently protects nobody — the exact failure
+ * class this whole mechanism exists to remove, reintroduced inside it. So `rustc`
+ * is deliberately absent until the slice that builds controller crates can
+ * compare it; adding it there is a one-line change here plus a supplier in
+ * {@link HostVersions}, and until then an author writing it is told it is not a
+ * known axis rather than quietly reassured.
+ *
+ * Extending the set is a telo release, which is exactly why a module using a new
+ * axis must also raise its `telo` bound — and why `telo` is checked first.
+ */
+export const KNOWN_HOST_AXES = ["node"];
+/** Top-level keys of the block. `host` is a container, `telo` a range. */
+const KNOWN_AXES = ["telo", "host"];
+const EMPTY = { host: {} };
+/**
+ * Read and parse the block off a module doc. Never throws. A malformed entry
+ * yields an issue AND is omitted from the block, so a consumer enforcing the
+ * block never silently treats garbage as a satisfied requirement — the issue is
+ * what makes the manifest fail, exactly as a malformed zone annotation does.
+ */
+export function readRequires(doc) {
+    const raw = doc?.requires;
+    if (raw === undefined)
+        return { declared: false, block: EMPTY, issues: [] };
+    const issues = [];
+    const block = { host: {} };
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        issues.push({
+            path: "requires",
+            message: `'requires' must be a mapping of axes, got ${describe(raw)}.`,
+        });
+        return { declared: true, block, issues };
+    }
+    const entries = raw;
+    for (const key of Object.keys(entries)) {
+        if (!KNOWN_AXES.includes(key)) {
+            issues.push({
+                path: `requires.${key}`,
+                message: `'requires.${key}' is not a known axis. This runtime knows ` +
+                    `${KNOWN_AXES.map((a) => `'${a}'`).join(" and ")}; host requirements go under 'host'.`,
+                unknownAxis: true,
+            });
+        }
+    }
+    if (entries.telo !== undefined) {
+        const range = parseRangeAt(entries.telo, "requires.telo", issues);
+        if (range)
+            block.telo = range;
+    }
+    if (entries.host !== undefined) {
+        const host = entries.host;
+        if (host === null || typeof host !== "object" || Array.isArray(host)) {
+            issues.push({
+                path: "requires.host",
+                message: `'requires.host' must be a mapping of host axes, got ${describe(host)}.`,
+            });
+        }
+        else {
+            for (const [axis, value] of Object.entries(host)) {
+                if (!KNOWN_HOST_AXES.includes(axis)) {
+                    issues.push({
+                        path: `requires.host.${axis}`,
+                        message: `'requires.host.${axis}' is not a known host axis. This runtime knows ` +
+                            `${KNOWN_HOST_AXES.map((a) => `'${a}'`).join(", ")}.`,
+                        unknownAxis: true,
+                    });
+                    continue;
+                }
+                const range = parseRangeAt(value, `requires.host.${axis}`, issues);
+                if (range)
+                    block.host[axis] = range;
+            }
+        }
+    }
+    return { declared: true, block, issues };
+}
+function parseRangeAt(value, path, issues) {
+    const result = parseVersionRange(value);
+    if (!result.ok) {
+        issues.push({ path, message: `'${path}': ${result.error.message}.`, hint: result.error.hint });
+        return undefined;
+    }
+    if (isUnsatisfiable(result.range)) {
+        issues.push({
+            path,
+            message: `'${path}': '${result.range.raw}' admits no version — its bounds exclude each other.`,
+        });
+        return undefined;
+    }
+    return result.range;
+}
+/**
+ * Evaluate a module's declared requirements against the runtime performing the
+ * analysis.
+ *
+ * `telo` is checked FIRST and short-circuits: a module using a host axis
+ * introduced in a later telo also declares that telo, so an older runtime must
+ * report the version skew rather than a host axis it may not even know. Absent
+ * declarations are satisfied — the bootstrap rule, permanent for everything
+ * published before the mechanism existed.
+ *
+ * **A version this cannot PARSE is satisfied, on every axis.** A runtime that
+ * cannot name its own version must not start rejecting modules on the strength
+ * of a number it could not read — the refusal-to-guess `module-version-order.ts`
+ * makes, pointed in the safe direction. The test is a parse, not a shape: `0.76`
+ * and `2024.1` look like versions and are not three-part ones, so a cheaper
+ * check (a leading digit, say) would fail them CLOSED and gate every module in
+ * the graph on a number nothing could compare. `AnalysisOptions.teloVersion` is
+ * hand-written by definition, so that is exactly where such a value arrives.
+ */
+export function evaluateRequires(block, running, host = {}) {
+    const telo = check("telo", block.telo, running);
+    if (telo)
+        return telo;
+    for (const axis of KNOWN_HOST_AXES) {
+        const verdict = check(axis, block.host[axis], host[axis]);
+        if (verdict)
+            return verdict;
+    }
+    return { satisfied: true };
+}
+/** One axis, or `undefined` when it is satisfied / undeclared / unreportable. */
+function check(axis, declared, running) {
+    if (!declared || !running)
+        return undefined;
+    if (!parseModuleVersion(running))
+        return undefined;
+    if (rangeAccepts(declared, running))
+        return undefined;
+    return { satisfied: false, axis, declared, running };
+}
+function describe(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "an array";
+    return typeof value;
+}

package/dist/schema-keywords.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The JSON Schema vocabulary an author writes inside a manifest, as data.
+ *
+ * WHY THIS EXISTS. A schema-valued slot used to be declared `type: object` and
+ * nothing more, so every surface that reads a kind schema — completion, hover,
+ * the editor's field walk, AJV — knew only "some object". Autocompletion was
+ * dead from the first key, and a typo (`requred:`, `type: 5`) was carried all
+ * the way to a runtime validation failure that named the wrong thing.
+ *
+ * ONE SOURCE, TWO SURFACES. The maps below are the whole vocabulary; the
+ * fragments in `manifest-schemas.ts` are built FROM them, and completion reads
+ * them directly. A second hand-written list is exactly how the IDE's suggestions
+ * and the validator's rules would drift apart.
+ *
+ * WHY THE ANNOTATIONS ARE NOT IN THE VALIDATING FRAGMENT. `x-telo-*` keys are
+ * offered by completion but deliberately never appear as literal property names
+ * in the schema that gets hoisted into a manifest. Several passes walk a
+ * definition's schema testing every object for an annotation KEY
+ * (`resolveSchemaRefKinds`, `validate-ref-slots`, `validate-zone-slots`), and a
+ * `properties` map holding a key spelled `x-telo-ref` reads to them as an
+ * annotated node — inventing diagnostics about a slot the author never wrote.
+ * So the hoisted body stays open (`additionalProperties: true`, which admits
+ * every annotation) and the annotation vocabulary stays here, on the analyzer
+ * side of the boundary, where no manifest walk can reach it.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+import { X_TELO_TYPE } from "@telorun/sdk";
+import { ANNOTATION_KEYWORDS } from "./value-type-keyword.js";
+/** A keyword entry: the JSON Schema its VALUE must satisfy, carrying the title
+ *  and description completion and hover show. */
+export type SchemaKeywords = Record<string, Record<string, unknown>>;
+/**
+ * The draft-07 keywords, as a property map for a fragment named `self`.
+ *
+ * Parameterized by the fragment name because a schema's nested positions hold
+ * schemas of the SAME flavour: a property of a kind schema may carry
+ * annotations, a property of a data schema may not. Both recurse into
+ * themselves, and the document-local pointer is what the hoisting in
+ * `expandManifestFragments` makes resolvable.
+ */
+export declare function jsonSchemaKeywords(self: string): SchemaKeywords;
+/**
+ * The `x-telo-*` annotation vocabulary — completion and hover only.
+ *
+ * TOTAL over {@link ANNOTATION_KEYWORDS} plus `x-telo-type`, which is what makes
+ * it a description of the existing list rather than a second copy of it: adding
+ * an annotation without a completion entry is a compile error here, and the
+ * first draft of this map — hand-written — had already silently dropped four
+ * annotations that live stdlib manifests use.
+ *
+ * Values are intentionally loose. What an annotation MEANS is checked by the
+ * pass that owns it (`validate-ref-slots`, `validate-zone-slots`,
+ * `validate-value-type-slots`), which reports in that annotation's own
+ * vocabulary; restating the shape here would give one mistake two diagnostics
+ * that disagree about what is wrong.
+ *
+ * A KNOWN BLIND SPOT, and not an oversight: several annotations
+ * (`x-telo-context`, `x-telo-error-context`, `x-telo-step-context`) hold JSON
+ * Schema themselves, and cannot be typed by the fragment this file feeds. A
+ * literal `x-telo-*` key inside a hoisted `properties` map reads to the
+ * annotation walkers as an annotated node, so the vocabulary has to stay out of
+ * anything that enters a manifest — which leaves an annotation's VALUE with
+ * neither validation nor completion. Closing it needs the walkers to distinguish
+ * a schema describing an annotation from an annotation, which nothing does yet.
+ */
+export declare const TELO_SCHEMA_ANNOTATIONS: Record<(typeof ANNOTATION_KEYWORDS)[number] | typeof X_TELO_TYPE, Record<string, unknown>>;
+//# sourceMappingURL=schema-keywords.d.ts.map

package/dist/schema-keywords.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-keywords.d.ts","sourceRoot":"","sources":["../src/schema-keywords.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAE9D;iDACiD;AACjD,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AASrE;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAuJ/D;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAC1C,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,GAAG,OAAO,WAAW,EACzD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgIxB,CAAC"}