@telorun/analyzer 0.72.0 → 0.74.0

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));
 }

package/dist/validate-template-dispatch.d.ts

@@ -1,27 +0,0 @@
-import type { ResourceManifest } from "@telorun/sdk";
-import { type AnalysisDiagnostic } from "./types.js";
-/**
- * A `!ref` at a definition's dispatch slot must name a sibling `resources:`
- * entry.
- *
- * `!ref` is the one spelling an author — and the editor's rename, completion and
- * go-to-definition — expects to be RESOLVED. But a `Telo.Definition` is in both
- * `REF_VALIDATION_SKIP_KINDS` and `REF_RESOLUTION_SKIP_KINDS`, and the dispatch
- * slots carry no `x-telo-ref` (the accepted targets are the definition's own
- * template-internal entries, not resources of any module), so no reference pass
- * reaches them. Introducing the tag at a slot nothing resolves would be worse
- * than the string form it replaces: a typo that used to be an obvious runtime
- * miss becomes a typo in a construct that advertises static resolution.
- *
- * Decidable only when every sibling name is LITERAL. A template routinely names
- * its entries with CEL (`name: !cel "self.name + '-query'"`), and an expression
- * could expand to the referenced name — so one dynamic sibling switches the
- * check off for that definition rather than inventing a miss.
- *
- * Entry-module-scoped, like every other declaration check: a published
- * dependency's template body is not the consumer's to fix.
- *
- * Browser-safe.
- */
-export declare function validateTemplateDispatch(manifests: ResourceManifest[], rootModules: ReadonlySet<string>): AnalysisDiagnostic[];
-//# sourceMappingURL=validate-template-dispatch.d.ts.map

package/dist/validate-template-dispatch.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"validate-template-dispatch.d.ts","sourceRoot":"","sources":["../src/validate-template-dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AASzE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,GAC/B,kBAAkB,EAAE,CAgDtB"}

package/dist/validate-template-dispatch.js

@@ -1,95 +0,0 @@
-import { isRefSentinel } from "@telorun/templating";
-import { distance } from "./levenshtein.js";
-import { DiagnosticSeverity } from "./types.js";
-const SOURCE = "telo-analyzer";
-/** The four slots a `Telo.Definition` names its dispatch target in. Each takes
- *  the same grammar; which one is legal for a given capability is
- *  `validate-provider-coherence`'s question, not this one's. */
-const DISPATCH_FIELDS = ["invoke", "run", "provide", "mount"];
-/**
- * A `!ref` at a definition's dispatch slot must name a sibling `resources:`
- * entry.
- *
- * `!ref` is the one spelling an author — and the editor's rename, completion and
- * go-to-definition — expects to be RESOLVED. But a `Telo.Definition` is in both
- * `REF_VALIDATION_SKIP_KINDS` and `REF_RESOLUTION_SKIP_KINDS`, and the dispatch
- * slots carry no `x-telo-ref` (the accepted targets are the definition's own
- * template-internal entries, not resources of any module), so no reference pass
- * reaches them. Introducing the tag at a slot nothing resolves would be worse
- * than the string form it replaces: a typo that used to be an obvious runtime
- * miss becomes a typo in a construct that advertises static resolution.
- *
- * Decidable only when every sibling name is LITERAL. A template routinely names
- * its entries with CEL (`name: !cel "self.name + '-query'"`), and an expression
- * could expand to the referenced name — so one dynamic sibling switches the
- * check off for that definition rather than inventing a miss.
- *
- * Entry-module-scoped, like every other declaration check: a published
- * dependency's template body is not the consumer's to fix.
- *
- * Browser-safe.
- */
-export function validateTemplateDispatch(manifests, rootModules) {
-    const out = [];
-    for (const m of manifests) {
-        if (m.kind !== "Telo.Definition")
-            continue;
-        const meta = m.metadata;
-        const name = meta?.name;
-        if (!name)
-            continue;
-        if (meta?.module && !rootModules.has(meta.module))
-            continue;
-        const bodies = m.resources;
-        if (!Array.isArray(bodies))
-            continue;
-        const siblings = [];
-        let anyDynamic = false;
-        for (const entry of bodies) {
-            const entryName = entry?.metadata?.name;
-            if (typeof entryName === "string" && !entryName.includes("${{"))
-                siblings.push(entryName);
-            else if (entryName !== undefined)
-                anyDynamic = true;
-        }
-        if (anyDynamic)
-            continue;
-        for (const field of DISPATCH_FIELDS) {
-            const value = m[field];
-            if (!isRefSentinel(value))
-                continue;
-            const source = value.source;
-            const target = source.startsWith("Self.") ? source.slice("Self.".length) : source;
-            if (siblings.includes(target))
-                continue;
-            const suggestion = nearest(target, siblings);
-            out.push({
-                severity: DiagnosticSeverity.Error,
-                code: "TEMPLATE_DISPATCH_UNKNOWN",
-                source: SOURCE,
-                message: `${m.kind}/${name}: '${field}: !ref ${source}' names no entry in 'resources:'. ` +
-                    `Available: ${siblings.join(", ") || "(none)"}.` +
-                    (suggestion ? ` Did you mean '${suggestion}'?` : ""),
-                data: {
-                    resource: { kind: m.kind, name },
-                    filePath: meta?.source,
-                    path: field,
-                    ...(suggestion ? { fix: { replacement: suggestion } } : {}),
-                },
-            });
-        }
-    }
-    return out;
-}
-/** The closest sibling name, when one is close enough to be a typo rather than a
- *  different name. */
-function nearest(target, candidates) {
-    let best;
-    for (const candidate of candidates) {
-        const d = distance(target, candidate);
-        if (!best || d < best.d)
-            best = { name: candidate, d };
-    }
-    const limit = Math.max(1, Math.floor(target.length / 3));
-    return best && best.d <= limit ? best.name : undefined;
-}

package/src/validate-template-dispatch.ts

@@ -1,99 +0,0 @@
-import type { ResourceManifest } from "@telorun/sdk";
-import { isRefSentinel } from "@telorun/templating";
-import { distance } from "./levenshtein.js";
-import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
-
-const SOURCE = "telo-analyzer";
-
-/** The four slots a `Telo.Definition` names its dispatch target in. Each takes
- *  the same grammar; which one is legal for a given capability is
- *  `validate-provider-coherence`'s question, not this one's. */
-const DISPATCH_FIELDS = ["invoke", "run", "provide", "mount"] as const;
-
-/**
- * A `!ref` at a definition's dispatch slot must name a sibling `resources:`
- * entry.
- *
- * `!ref` is the one spelling an author — and the editor's rename, completion and
- * go-to-definition — expects to be RESOLVED. But a `Telo.Definition` is in both
- * `REF_VALIDATION_SKIP_KINDS` and `REF_RESOLUTION_SKIP_KINDS`, and the dispatch
- * slots carry no `x-telo-ref` (the accepted targets are the definition's own
- * template-internal entries, not resources of any module), so no reference pass
- * reaches them. Introducing the tag at a slot nothing resolves would be worse
- * than the string form it replaces: a typo that used to be an obvious runtime
- * miss becomes a typo in a construct that advertises static resolution.
- *
- * Decidable only when every sibling name is LITERAL. A template routinely names
- * its entries with CEL (`name: !cel "self.name + '-query'"`), and an expression
- * could expand to the referenced name — so one dynamic sibling switches the
- * check off for that definition rather than inventing a miss.
- *
- * Entry-module-scoped, like every other declaration check: a published
- * dependency's template body is not the consumer's to fix.
- *
- * Browser-safe.
- */
-export function validateTemplateDispatch(
-  manifests: ResourceManifest[],
-  rootModules: ReadonlySet<string>,
-): AnalysisDiagnostic[] {
-  const out: AnalysisDiagnostic[] = [];
-
-  for (const m of manifests) {
-    if (m.kind !== "Telo.Definition") continue;
-    const meta = m.metadata as { name?: string; module?: string; source?: string } | undefined;
-    const name = meta?.name;
-    if (!name) continue;
-    if (meta?.module && !rootModules.has(meta.module)) continue;
-
-    const bodies = (m as Record<string, unknown>).resources;
-    if (!Array.isArray(bodies)) continue;
-
-    const siblings: string[] = [];
-    let anyDynamic = false;
-    for (const entry of bodies) {
-      const entryName = (entry as { metadata?: { name?: unknown } } | undefined)?.metadata?.name;
-      if (typeof entryName === "string" && !entryName.includes("${{")) siblings.push(entryName);
-      else if (entryName !== undefined) anyDynamic = true;
-    }
-    if (anyDynamic) continue;
-
-    for (const field of DISPATCH_FIELDS) {
-      const value = (m as Record<string, unknown>)[field];
-      if (!isRefSentinel(value)) continue;
-      const source = value.source;
-      const target = source.startsWith("Self.") ? source.slice("Self.".length) : source;
-      if (siblings.includes(target)) continue;
-      const suggestion = nearest(target, siblings);
-      out.push({
-        severity: DiagnosticSeverity.Error,
-        code: "TEMPLATE_DISPATCH_UNKNOWN",
-        source: SOURCE,
-        message:
-          `${m.kind}/${name}: '${field}: !ref ${source}' names no entry in 'resources:'. ` +
-          `Available: ${siblings.join(", ") || "(none)"}.` +
-          (suggestion ? ` Did you mean '${suggestion}'?` : ""),
-        data: {
-          resource: { kind: m.kind, name },
-          filePath: meta?.source,
-          path: field,
-          ...(suggestion ? { fix: { replacement: suggestion } } : {}),
-        },
-      });
-    }
-  }
-
-  return out;
-}
-
-/** The closest sibling name, when one is close enough to be a typo rather than a
- *  different name. */
-function nearest(target: string, candidates: readonly string[]): string | undefined {
-  let best: { name: string; d: number } | undefined;
-  for (const candidate of candidates) {
-    const d = distance(target, candidate);
-    if (!best || d < best.d) best = { name: candidate, d };
-  }
-  const limit = Math.max(1, Math.floor(target.length / 3));
-  return best && best.d <= limit ? best.name : undefined;
-}