@telorun/analyzer 0.73.0 → 0.74.0

package/src/module-file-claims.ts

@@ -4,16 +4,22 @@ import {
   walkCelExpressions,
   type TemplatingEngineRegistry,
 } from "@telorun/templating";
+import type { ResourceManifest } from "@telorun/sdk";
 import { PackageURL } from "packageurl-js";
 import { parseAllDocuments } from "yaml";
-import { selectorFromQualifiers, selectorKey, type ArtifactSelector } from "./artifact-selector.js";
+import {
+  ArtifactSelectorError,
+  selectorFromQualifiers,
+  selectorKey,
+  type ArtifactSelector,
+} from "./artifact-selector.js";
 import { readLibraryCandidates } from "./module-library.js";
 
 /**
  * One module-relative file a manifest names, and the artifact layer it belongs
  * to.
  *
- * The single answer to "why is this file in the payload", replacing two
+ * The answer to "why is this file in the payload" for everything but `native:` entries (read by `native-entries.ts`), replacing two
  * derivations that happened to agree: publish used to re-parse the manifest with
  * PURL knowledge hardcoded into the CLI, and any second vocabulary — a tag that
  * embeds a file, say — would have had to be added there by hand. Here the
@@ -188,11 +194,64 @@ function claimKey(claim: ModuleFileClaim): string {
 export function collectModuleFileClaims(
   manifestText: string,
   registry: TemplatingEngineRegistry = defaultRegistry(),
+): ModuleFileClaim[] {
+  return collectDocumentFileClaims(
+    parseAllDocuments(manifestText, { customTags: defaultCustomTags() }).map(
+      (doc) => doc.toJSON() as unknown,
+    ),
+    registry,
+  );
+}
+
+/** A claim, with the document that made it when the caller knows which. */
+export interface LocatedClaim {
+  readonly claim: ModuleFileClaim;
+  /** `<kind>/<name>` of the declaring document. */
+  readonly where?: string;
+}
+
+/**
+ * The claims one module's own documents make, out of an analysis set that also
+ * holds its dependencies' documents. A document whose candidate selector cannot
+ * be read contributes none — `validateModuleArtifact` reports it.
+ */
+export function moduleDocumentClaims(
+  manifests: readonly ResourceManifest[],
+  moduleName: string | undefined,
+  registry: TemplatingEngineRegistry = defaultRegistry(),
+): LocatedClaim[] {
+  const out: LocatedClaim[] = [];
+  for (const doc of manifests) {
+    const metadata = (doc.metadata ?? {}) as Record<string, unknown>;
+    const docModule =
+      typeof metadata.module === "string"
+        ? metadata.module
+        : doc.kind === "Telo.Application" || doc.kind === "Telo.Library"
+          ? metadata.name
+          : undefined;
+    if (docModule !== moduleName) continue;
+    let claims: ModuleFileClaim[];
+    try {
+      claims = collectDocumentFileClaims([doc], registry);
+    } catch (err) {
+      if (err instanceof ArtifactSelectorError) continue;
+      throw err;
+    }
+    const where = `${doc.kind}/${typeof metadata.name === "string" ? metadata.name : "(unnamed)"}`;
+    for (const claim of claims) out.push({ claim, where });
+  }
+  return out;
+}
+
+/** The same claims, from one module's already-parsed documents — the form the
+ *  analysis pass holds. */
+export function collectDocumentFileClaims(
+  docs: readonly unknown[],
+  registry: TemplatingEngineRegistry = defaultRegistry(),
 ): ModuleFileClaim[] {
   const seen = new Set<string>();
   const claims: ModuleFileClaim[] = [];
-  for (const doc of parseAllDocuments(manifestText, { customTags: defaultCustomTags() })) {
-    const json = doc.toJSON() as unknown;
+  for (const json of docs) {
     for (const claim of [
       ...libraryClaims(json),
       ...controllerClaims(json),

package/src/module-named-files.ts

@@ -0,0 +1,162 @@
+/**
+ * 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";
+import type { LocatedClaim, ModuleFileClaim } from "./module-file-claims.js";
+import type { NativeEntry } from "./native-entries.js";
+import type { ModuleSource, SourceEntry } from "./source-entries.js";
+
+const CLAIM_LABEL: Record<ModuleFileClaim["role"], string> = {
+  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: LocatedClaim): string {
+  const { claim, where } = located;
+  return `${CLAIM_LABEL[claim.role]} ${claim.origin}${where === undefined ? "" : ` on ${where}`}`;
+}
+
+/** A `native:` entry whose path another declaration also names. */
+export interface NativeClaimConflict {
+  readonly entry: NativeEntry;
+  readonly claim: LocatedClaim;
+}
+
+/**
+ * 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: readonly NativeEntry[],
+  claims: readonly LocatedClaim[],
+): NativeClaimConflict[] {
+  const out: NativeClaimConflict[] = [];
+  for (const entry of native) {
+    for (const claim of claims) {
+      if (claim.claim.path === entry.path) out.push({ entry, claim });
+    }
+  }
+  return out;
+}
+
+/** A file a `sources:` entry may stage. */
+export interface StageableFile {
+  readonly path: string;
+  /** The declaration naming it, for messages. */
+  readonly label: string;
+  /** The layer it ships in, for messages. */
+  readonly layer: string;
+  /** Produced by a controller build (`local_path=`) rather than staged or committed. */
+  readonly built: boolean;
+}
+
+/**
+ * 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: readonly NativeEntry[],
+  claims: readonly LocatedClaim[],
+): Map<string, StageableFile> {
+  const out = new Map<string, StageableFile>();
+  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;
+}
+
+/** A `sources:` entry, with the source declaring it. */
+export interface LocatedSourceEntry {
+  readonly source: ModuleSource;
+  readonly entry: SourceEntry;
+}
+
+/**
+ * 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: readonly ModuleSource[],
+  stageable: ReadonlyMap<string, StageableFile>,
+  alsoNamed: ReadonlySet<string> = new Set(),
+): LocatedSourceEntry[] {
+  const out: LocatedSourceEntry[] = [];
+  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;
+}
+
+/** A link whose target ships in a different layer than the link. */
+export interface CrossLayerLink {
+  readonly source: ModuleSource;
+  readonly entry: Extract<SourceEntry, { kind: "link" }>;
+  readonly layer: string;
+  readonly targetLayer: string;
+}
+
+/**
+ * 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: readonly ModuleSource[],
+  stageable: ReadonlyMap<string, StageableFile>,
+): CrossLayerLink[] {
+  const layerOf = (source: ModuleSource, path: string): string | undefined =>
+    stageable.get(path)?.layer ?? (source.notices.includes(path) ? "common" : undefined);
+  const out: CrossLayerLink[] = [];
+  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/src/native-entries.ts

@@ -0,0 +1,227 @@
+/**
+ * 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,
+  type ArtifactSelector,
+} from "./artifact-selector.js";
+
+/** Every key an entry may carry. */
+const KNOWN_KEYS = new Set<string>(["name", "format", "path", ...PLATFORM_AXES]);
+
+/** Axes an entry must state: a native file is built for one platform. */
+const REQUIRED_AXES = ["os", "arch"] as const;
+
+/** 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;
+
+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 function normalizeNativePath(raw: string): PathVerdict {
+  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: string[] = [];
+  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: unknown): NativeEntries {
+  const declared = (ownerJson as { native?: unknown } | null)?.native;
+  const entries: NativeEntry[] = [];
+  const problems: NativeEntryProblem[] = [];
+  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: string) =>
+      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 as Record<string, unknown>;
+
+    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] as string).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 as string;
+    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: ArtifactSelector;
+    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 as string).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 };
+}