@telorun/analyzer 0.73.0 → 0.74.0

package/src/validate-source-entries.ts

@@ -0,0 +1,120 @@
+import type { ResourceManifest } from "@telorun/sdk";
+
+import { moduleDocumentClaims } from "./module-file-claims.js";
+import {
+  crossLayerSourceLinks,
+  stageableFiles,
+  unclaimedSourceEntries,
+} from "./module-named-files.js";
+import { normalizeNativePath, readNativeEntries } from "./native-entries.js";
+import { readModuleSources } from "./source-entries.js";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/**
+ * The strict half of `source-entries.ts`: what `telo check` reports about a
+ * module doc's `sources:` block.
+ *
+ * Every rule the block alone decides is a reader problem, reported here under
+ * its own code. This adds the rules that need the rest of the module or that
+ * only publish enforces: an entry must stage a file the manifest names, a link
+ * ships in its target's layer, and every file entry and every build carries its
+ * pin. Shape errors are left to the owner doc's JSON Schema.
+ *
+ * Entry-module-scoped: a dependency's block is not the consumer's to fix.
+ */
+export function validateSourceEntries(
+  manifests: ResourceManifest[],
+  entryModules?: ReadonlySet<string>,
+): AnalysisDiagnostic[] {
+  const out: AnalysisDiagnostic[] = [];
+  for (const manifest of manifests) {
+    if (manifest.kind !== "Telo.Application" && manifest.kind !== "Telo.Library") continue;
+    const metadata = (manifest.metadata ?? {}) as Record<string, unknown>;
+    const name = typeof metadata.name === "string" ? metadata.name : undefined;
+    const owned =
+      entryModules === undefined ||
+      (typeof metadata.module === "string"
+        ? entryModules.has(metadata.module)
+        : name === undefined || entryModules.has(name));
+    if (!owned) continue;
+
+    const label = `${manifest.kind}/${name ?? "(unnamed)"}`;
+    const report = (code: string, path: string, message: string) =>
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code,
+        source: SOURCE,
+        message: `${label}: ${message}`,
+        data: {
+          resource: { kind: manifest.kind, name },
+          filePath: typeof metadata.source === "string" ? metadata.source : undefined,
+          path,
+        },
+      });
+
+    const { sources, problems } = readModuleSources(manifest);
+    for (const problem of problems) {
+      if (problem.code === "SHAPE") continue;
+      report(problem.code, problem.path, problem.message);
+    }
+    if (sources.length === 0) continue;
+
+    for (const source of sources) {
+      if (source.build && source.build.inputs === undefined) {
+        report(
+          "SOURCE_BUILD_UNPINNED",
+          `sources.${source.name}.build`,
+          `source '${source.name}' names the crate its files are built from but records no build ` +
+            `inputs, so a later edit to that crate cannot be caught — run \`telo release stage ` +
+            `--pin\` after building its files. \`telo release check\` and publish refuse it.`,
+        );
+      }
+      for (const entry of source.entries) {
+        if (entry.kind !== "file" || entry.pin) continue;
+        report(
+          "SOURCE_ENTRY_UNPINNED",
+          `sources.${source.name}.entries.${entry.key}`,
+          `source '${source.name}' entry '${entry.key}' carries no pin (sha256 and executable), so ` +
+            `nothing can verify the file it stages: a kernel refuses to read it and publish refuses ` +
+            `to ship it — run \`telo release stage --pin\`.`,
+        );
+      }
+    }
+
+    const moduleName = typeof metadata.module === "string" ? metadata.module : name;
+    const stageable = stageableFiles(
+      readNativeEntries(manifest).entries,
+      moduleDocumentClaims(manifests, moduleName),
+    );
+    for (const { source, entry, layer, targetLayer } of crossLayerSourceLinks(sources, stageable)) {
+      report(
+        "SOURCE_LINK_TARGET_UNRESOLVED",
+        `sources.${source.name}.entries.${entry.key}.target`,
+        `source '${source.name}' entry '${entry.key}': the link ships in the ${layer} layer, but ` +
+          `its target '${entry.resolved}' ships in the ${targetLayer} layer. A runtime extracts ` +
+          `only the layers it needs, so the link would dangle — point it at a file of its own layer.`,
+      );
+    }
+    // A `native:` entry with an unrelated problem still names its path; reported
+    // once, as that problem, rather than again as an unclaimed source entry.
+    const unreadNative = new Set<string>();
+    const native = (manifest as { native?: unknown }).native;
+    for (const entry of Array.isArray(native) ? native : []) {
+      const path = (entry as { path?: unknown } | null)?.path;
+      const verdict = typeof path === "string" ? normalizeNativePath(path.trim()) : undefined;
+      if (verdict && "path" in verdict) unreadNative.add(verdict.path);
+    }
+    for (const { source, entry } of unclaimedSourceEntries(sources, stageable, unreadNative)) {
+      report(
+        "SOURCE_ENTRY_UNCLAIMED",
+        `sources.${source.name}.entries.${entry.key}`,
+        `source '${source.name}' entry '${entry.key}': nothing in the module names '${entry.path}' ` +
+          `— no native: entry's path, no platform-qualified controller candidate's path=, and ` +
+          `none of the source's notices. Name the file where it is used, or remove the entry.`,
+      );
+    }
+  }
+  return out;
+}

package/src/validate-throws-coverage.ts

@@ -10,11 +10,14 @@ import { scopeResolverForModule, type AliasResolver } from "./alias-resolver.js"
 import type { DefinitionRegistry } from "./definition-registry.js";
 import {
   createResolveCtx,
+  handsFailureBack,
   resolveScopeUnion,
   resolveThrowsUnion,
+  throwsUses,
   type ThrowsCodeMeta,
   type ThrowsUnion,
 } from "./resolve-throws-union.js";
+import { forEachDeclaredSlot } from "./schema-walk.js";
 import {
   buildEnclosers,
   collectScopedManifests,
@@ -24,7 +27,6 @@ import {
 } from "./catch-scope.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
 import { extractAccessChains, validateChainAgainstSchema } from "./validate-cel-context.js";
-import { isStepSlot } from "./step-slot.js";
 
 const SOURCE = "telo-analyzer";
 const TEMPLATE_REGEX = /\$\{\{\s*([^}]+?)\s*\}\}/g;
@@ -507,12 +509,6 @@ function checkCelChainAgainstDataSchema(
   return diagnostics;
 }
 
-/** Rule 8 extension: `inherit: true` only makes sense on a definition whose
- *  schema declares at least one STEP BODY — an array whose items point at the
- *  shared grammar, or, for a module published before that fragment existed, one
- *  carrying the legacy `x-telo-step-context` annotation. That is what drives the
- *  resolver's generic step traversal; a definition with `inherit: true` and no
- *  such array has no invocables to inherit from. */
 /** The capabilities whose lifecycle includes a dispatch a caller can catch. On
  *  every other one a thrown error is a boot-time failure, not a structured
  *  runtime error for a downstream caller — a provider resolves configuration, a
@@ -574,10 +570,14 @@ function validateThrowsDeclarations(manifests: ResourceManifest[]): AnalysisDiag
           code: "INHERIT_WITHOUT_STEP_CONTEXT",
           source: SOURCE,
           message:
-            `Telo.Definition '${name}' declares throws.inherit: true but its schema declares no step ` +
-            `body. inherit is only meaningful on a definition that drives invocables through steps — ` +
-            `give an array field 'items: { $ref: "telo://manifest#/$defs/Step" }' (the legacy ` +
-            `x-telo-step-context annotation is also recognised).`,
+            `Telo.Definition '${name}' declares throws.inherit: true but its schema dispatches nothing ` +
+            `a failure can come back through. inherit makes the kind's union the union of what it ` +
+            `dispatches, so the schema needs a step body (an array field with ` +
+            `'items: { $ref: "telo://manifest#/$defs/Step" }', or the legacy x-telo-step-context ` +
+            `annotation) or a reference slot whose use includes 'call' or 'trigger.consumer' ` +
+            `(for a use case map, in any case; a slot declaring no use counts as 'call'). ` +
+            `'detached' and 'trigger.inbound' run where no caller awaits them, and ` +
+            `'dependency' / 'schema' dispatch nothing.`,
           data: { resource: { kind: m.kind, name }, filePath, path: "throws.inherit" },
         });
       }
@@ -586,28 +586,21 @@ function validateThrowsDeclarations(manifests: ResourceManifest[]): AnalysisDiag
   return diagnostics;
 }
 
+/** Rule 8 extension: `inherit: true` needs something to inherit from — a step
+ *  body, or a reference slot whose use (any case of a case map) hands a failure
+ *  back. The schema-only mode of the walk the resolver runs per instance, so the
+ *  check and the union reach the same slots. */
 function schemaDrivesInvocables(schema: Record<string, any> | undefined): boolean {
-  if (!schema || typeof schema !== "object") return false;
-  if (isStepSlot(schema)) return true;
-  const props = schema.properties;
-  if (props && typeof props === "object") {
-    for (const v of Object.values(props as Record<string, any>)) {
-      if (schemaDrivesInvocables(v)) return true;
+  let drives = false;
+  forEachDeclaredSlot(schema, (declared) => {
+    if (
+      declared.kind === "step" ||
+      declared.slots.some((slot) => throwsUses(slot).some(handsFailureBack))
+    ) {
+      drives = true;
     }
-  }
-  if (schema.items && schemaDrivesInvocables(schema.items)) return true;
-  for (const key of ["oneOf", "anyOf", "allOf"] as const) {
-    const arr = schema[key];
-    if (Array.isArray(arr)) {
-      for (const sub of arr) if (schemaDrivesInvocables(sub)) return true;
-    }
-  }
-  if (schema.$defs && typeof schema.$defs === "object") {
-    for (const v of Object.values(schema.$defs as Record<string, any>)) {
-      if (schemaDrivesInvocables(v)) return true;
-    }
-  }
-  return false;
+  });
+  return drives;
 }
 
 /** Entry point — invoked once per analyze() run. */

package/src/value-type-keyword.ts

@@ -76,6 +76,21 @@ export const ANNOTATION_KEYWORDS = [
   "x-telo-widget",
 ] as const;
 
+/** How an AJV instance treats a `live` value type. */
+export interface TeloKeywordOptions {
+  /**
+   * Assert a `live` type as an instance too, so a literal at such a slot is
+   * refused — a value written in a manifest can never be a live instance.
+   *
+   * STATIC analysis only, where a CEL leaf's stand-in is an instance
+   * (`celPlaceholderForSchema`). The kernel's instances leave it off: at
+   * dispatch a live value is exempt from validation, and the stage that pulls
+   * from it refuses a non-stream itself — so the static half refuses a strict
+   * subset of what the runtime refuses, and the two cannot disagree.
+   */
+  readonly assertLive?: boolean;
+}
+
 /**
  * The `x-telo-type` keyword.
  *
@@ -84,8 +99,10 @@ export const ANNOTATION_KEYWORDS = [
  *  - a `json` representation validates through its own declared schema, so the
  *    keyword emits nothing — the name carries nominal identity for static wiring
  *    and has no runtime existence at all;
- *  - a `live` instance is EXEMPT: its value is never traversed, because iterating
- *    a stream to check it is precisely what the exemption is for;
+ *  - a `live` instance is EXEMPT at dispatch: its value is never traversed,
+ *    because iterating a stream to check it is precisely what the exemption is
+ *    for. Statically ({@link TeloKeywordOptions.assertLive}) it is asserted like
+ *    any other instance, which checks what the value IS and never iterates it;
  *  - every other instance is ASSERTED against the constructor its binding names.
  *
  * An unknown name emits nothing here. It is a hard diagnostic in the analyzer
@@ -93,7 +110,7 @@ export const ANNOTATION_KEYWORDS = [
  * manifest that wrote it; failing compilation instead would take out every
  * validator in a module for one typo in one slot.
  */
-export function valueTypeKeyword(): KeywordDefinition {
+export function valueTypeKeyword(options: TeloKeywordOptions = {}): KeywordDefinition {
   return {
     keyword: X_TELO_TYPE,
     // Both spellings: a bare name, or the object form carrying type arguments.
@@ -102,7 +119,8 @@ export function valueTypeKeyword(): KeywordDefinition {
       const entry: ValueTypeEntry | undefined = readValueTypeSlot({
         [X_TELO_TYPE]: cxt.schema,
       })?.entry;
-      if (!entry || entry.representation !== "instance" || entry.live) return;
+      if (!entry || entry.representation !== "instance") return;
+      if (entry.live && !options.assertLive) return;
       const binding = VALUE_TYPE_BINDINGS[entry.binding!];
       if (!binding) return;
       // The constructor reaches generated code through AJV's value scope, which
@@ -118,6 +136,12 @@ export function valueTypeKeyword(): KeywordDefinition {
     error: {
       message: (cxt: any) => {
         const entry = readValueTypeSlot({ [X_TELO_TYPE]: cxt.schema })?.entry;
+        if (entry?.live) {
+          return (
+            `must be a live ${entry.name} — a value written in the manifest can never be one; ` +
+            "pass the result of a step that produces it, with a !cel expression"
+          );
+        }
         return entry?.binding === "bytes"
           ? "must be raw bytes (a Uint8Array) — bytes cannot be written inline in a manifest"
           : `must be a ${entry?.name ?? "declared value type"} — this value is not writable inline in a manifest`;
@@ -131,11 +155,13 @@ export function valueTypeKeyword(): KeywordDefinition {
  * `x-telo-type` as the one that checks.
  *
  * Every AJV instance in the runtime and the analyzer goes through this, so a
- * schema means the same thing wherever it is validated.
+ * schema means the same thing wherever it is validated — apart from the one
+ * posture {@link TeloKeywordOptions} names, which only static analysis takes.
  */
-export function registerTeloKeywords(ajv: {
-  addKeyword: (keyword: any, definition?: any) => unknown;
-}): void {
+export function registerTeloKeywords(
+  ajv: { addKeyword: (keyword: any, definition?: any) => unknown },
+  options: TeloKeywordOptions = {},
+): void {
   for (const keyword of ANNOTATION_KEYWORDS) ajv.addKeyword(keyword);
-  ajv.addKeyword(valueTypeKeyword());
+  ajv.addKeyword(valueTypeKeyword(options));
 }