@telorun/analyzer 0.62.1 → 0.64.0

package/src/validate-step-inputs.ts

@@ -9,7 +9,7 @@ import {
   validateAgainstSchema,
 } from "./schema-compat.js";
 import { plainChainOf } from "@telorun/templating";
-import { isLiveSlot, valueTypeOf } from "@telorun/sdk";
+import { isLiveSlot, valueTypeOf, type ResourceDefinition } from "@telorun/sdk";
 import { manifestFragmentOf } from "./manifest-schemas.js";
 import {
   analyzerContractScope,
@@ -19,6 +19,13 @@ import {
   resolveLocalRef,
   walkStepArray,
 } from "./analyzer.js";
+import { readStepSlot } from "./step-slot.js";
+import { navigateConcretePath } from "./manifest-path.js";
+import {
+  isRefEntry,
+  resolveFieldEntries,
+  type ReferenceFieldMap,
+} from "./reference-field-map.js";
 
 export interface StepInputIssue {
   path: string;
@@ -42,7 +49,8 @@ export interface StepInputIssue {
  * CEL leaves are replaced by schema-shaped placeholders first (`substituteCelFields`),
  * so an expression is never a false positive — only structural disagreement is
  * reported. Nothing is hardcoded about `Run.Sequence`: the invoke field comes
- * from `x-telo-step-context`, and the paired inputs field from whichever sibling
+ * from the step slot (the shared grammar, or the legacy `x-telo-step-context`),
+ * and the paired inputs field from whichever sibling
  * property carries `x-telo-topology-role: inputs`.
  */
 export function collectStepInputIssues(
@@ -64,9 +72,18 @@ export function collectStepInputIssues(
   const contractScope = analyzerContractScope(defs, aliases, scopes, allManifests);
   const readingModule = (manifest.metadata as { module?: string } | undefined)?.module;
 
+  const ctx: CallCheckContext = {
+    manifest,
+    allManifests,
+    defs,
+    contractScope,
+    readingModule,
+    stepContext,
+  };
+
   for (const [fieldName, fieldSchema] of Object.entries(props)) {
-    const stepCtx = fieldSchema["x-telo-step-context"] as Record<string, string> | undefined;
-    if (!stepCtx?.invoke) continue;
+    const stepCtx = readStepSlot(fieldSchema);
+    if (!stepCtx) continue;
     const steps = manifest[fieldName];
     if (!Array.isArray(steps)) continue;
 
@@ -90,6 +107,127 @@ export function collectStepInputIssues(
       if (!invoke || typeof invoke !== "object") return;
       if (!values || typeof values !== "object" || Array.isArray(values)) return;
 
+      out.push(
+        ...checkCallSite(
+          {
+            inputsPath: `${stepPath}.${inputsField}`,
+            values: values as Record<string, any>,
+            invoke,
+            // Only a step declares a re-attempt policy, so only a step can carry
+            // the live-value-retried finding.
+            declaredRetryFor: (invokedManifest, invokedDef) =>
+              declaredRetry(step, stepItemSchema, invokedManifest, invokedDef),
+          },
+          ctx,
+        ),
+      );
+    });
+  }
+  return out;
+}
+
+/**
+ * Validate the argument map of every call this resource makes through a
+ * REFERENCE SLOT, as opposed to a step.
+ *
+ * A slot that transfers control names its argument slot on its own `x-telo-ref`
+ * (`inputs:`, a JSON Pointer relative to the object enclosing the slot). That
+ * annotation is the only thing tying an otherwise-open `inputs:` map to the
+ * resource it holds arguments for — an HTTP route's `handler:` + `inputs:` pair
+ * is exactly this shape, and nothing about it is a step.
+ *
+ * Discovery is driven by the annotation rather than by any kind's topology, so
+ * a composer that names its argument slot gets its call sites checked without
+ * the analyzer learning what a route is. It is the same check the step driver
+ * runs, because it is the same question.
+ */
+export function collectRefInputIssues(
+  manifest: Record<string, any>,
+  fieldMap: ReferenceFieldMap | undefined,
+  allManifests: Record<string, any>[],
+  defs: DefinitionRegistry,
+  aliases: AliasResolver,
+  scopes: ModuleScopes,
+): StepInputIssue[] {
+  const out: StepInputIssue[] = [];
+  if (!fieldMap) return out;
+
+  const contractScope = analyzerContractScope(defs, aliases, scopes, allManifests);
+  const ctx: CallCheckContext = {
+    manifest,
+    allManifests,
+    defs,
+    contractScope,
+    readingModule: (manifest.metadata as { module?: string } | undefined)?.module,
+  };
+
+  for (const [fieldPath, entry] of fieldMap) {
+    if (!isRefEntry(entry) || !entry.inputs) continue;
+    const pointer = pointerSegments(entry.inputs);
+    if (!pointer) continue;
+
+    for (const { value: invoke, path: slotPath } of resolveFieldEntries(manifest, fieldPath)) {
+      if (!invoke || typeof invoke !== "object" || Array.isArray(invoke)) continue;
+      // Relative to the object ENCLOSING the slot, which is the annotation's
+      // documented anchor.
+      const enclosing = slotPath.slice(0, Math.max(0, slotPath.lastIndexOf(".")));
+      const inputsPath = [enclosing, ...pointer].filter(Boolean).join(".");
+      const values = navigateConcretePath(manifest, inputsPath);
+      if (!values || typeof values !== "object" || Array.isArray(values)) continue;
+
+      out.push(
+        ...checkCallSite(
+          { inputsPath, values: values as Record<string, any>, invoke: invoke as Record<string, any> },
+          ctx,
+        ),
+      );
+    }
+  }
+  return out;
+}
+
+/** A JSON Pointer naming a sibling FIELD path. An array index is not a field,
+ *  so a pointer carrying one names nothing this can resolve. */
+function pointerSegments(pointer: string): string[] | undefined {
+  if (!pointer.startsWith("/")) return undefined;
+  const segments = pointer
+    .slice(1)
+    .split("/")
+    .map((s) => s.replace(/~1/g, "/").replace(/~0/g, "~"));
+  return segments.every((s) => s.length > 0 && !/^\d+$/.test(s)) ? segments : undefined;
+}
+
+/** One call site: the arguments written, and the reference they are for. */
+interface CallSite {
+  /** Concrete path of the argument map, for anchoring a diagnostic. */
+  inputsPath: string;
+  values: Record<string, any>;
+  invoke: Record<string, any>;
+  declaredRetryFor?(
+    invokedManifest: Record<string, any> | undefined,
+    invokedDef: ResourceDefinition | undefined,
+  ): string | undefined;
+}
+
+interface CallCheckContext {
+  manifest: Record<string, any>;
+  allManifests: Record<string, any>[];
+  defs: DefinitionRegistry;
+  contractScope: ReturnType<typeof analyzerContractScope>;
+  readingModule: string | undefined;
+  stepContext?: Record<string, any>;
+}
+
+/**
+ * The check itself, shared by both drivers: the arguments written at a call site
+ * against the contract the target declares.
+ */
+function checkCallSite(site: CallSite, ctx: CallCheckContext): StepInputIssue[] {
+  const out: StepInputIssue[] = [];
+  const { manifest, allManifests, defs, contractScope, readingModule, stepContext } = ctx;
+  const { invoke, values } = site;
+  {
+    {
       const invokedKind = invoke.kind as string | undefined;
       const invokedName = invoke.name as string | undefined;
       const invokedManifest = invokedName
@@ -102,7 +240,7 @@ export function collectStepInputIssues(
         ? contractScope.resolveIn(invokedKind, readingModule)
         : undefined;
       const contract = resolveContract("inputType", invokedManifest, invokedDef, contractScope);
-      if (!contract) return;
+      if (!contract) return out;
 
       // Findings AT a substituted path are about a placeholder, not about
       // anything the author wrote — a `pattern`-constrained string or a `oneOf`
@@ -161,10 +299,10 @@ export function collectStepInputIssues(
           // already declared: the value's liveness by its value type, and the
           // re-attempt by the retry policy. No kind is named.
           if (isLiveSlot(produced)) {
-            const retry = declaredRetry(step, stepItemSchema, invokedManifest, invokedDef);
+            const retry = site.declaredRetryFor?.(invokedManifest, invokedDef);
             if (retry !== undefined) {
               out.push({
-                path: `${stepPath}.${inputsField}.${inputName}`,
+                path: `${site.inputsPath}.${inputName}`,
                 targetLabel: invokedName ?? invokedKind ?? "the invoked resource",
                 message:
                   `'${inputName}' is a live value, which is consumed by reading and so exists ` +
@@ -182,7 +320,7 @@ export function collectStepInputIssues(
           );
           if (compatible) continue;
           out.push({
-            path: `${stepPath}.${inputsField}.${inputName}`,
+            path: `${site.inputsPath}.${inputName}`,
             targetLabel: invokedName ?? invokedKind ?? "the invoked resource",
             message: issues.join("; "),
             code: "CEL_TYPE_ARGUMENT_MISMATCH",
@@ -198,12 +336,12 @@ export function collectStepInputIssues(
         // container that should have held it, which does exist.
         const anchor = missingRequired(issue) ? containerOf(issue.path) : issue.path;
         out.push({
-          path: anchor ? `${stepPath}.${inputsField}.${anchor}` : `${stepPath}.${inputsField}`,
+          path: anchor ? `${site.inputsPath}.${anchor}` : site.inputsPath,
           targetLabel: invokedName ?? invokedKind ?? "the invoked resource",
           message: issue.message,
         });
       }
-    });
+    }
   }
   return out;
 }

package/src/validate-throws-coverage.ts

@@ -15,6 +15,7 @@ import {
 } from "./resolve-throws-union.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;
@@ -457,9 +458,11 @@ function checkCelChainAgainstDataSchema(
 }
 
 /** Rule 8 extension: `inherit: true` only makes sense on a definition whose
- *  schema contains at least one `x-telo-step-context` array — the annotation
- *  that drives the resolver's generic step traversal. A definition with
- *  `inherit: true` and no such array has no invocables to inherit from. */
+ *  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. */
 function validateThrowsDeclarations(manifests: ResourceManifest[]): AnalysisDiagnostic[] {
   const diagnostics: AnalysisDiagnostic[] = [];
   for (const m of manifests) {
@@ -475,7 +478,11 @@ function validateThrowsDeclarations(manifests: ResourceManifest[]): AnalysisDiag
           severity: DiagnosticSeverity.Error,
           code: "INHERIT_WITHOUT_STEP_CONTEXT",
           source: SOURCE,
-          message: `Telo.Definition '${name}' declares throws.inherit: true but its schema has no field annotated with x-telo-step-context. inherit is only meaningful on definitions that drive invocables via step arrays.`,
+          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).`,
           data: { resource: { kind: m.kind, name }, filePath, path: "throws.inherit" },
         });
       }
@@ -486,7 +493,7 @@ function validateThrowsDeclarations(manifests: ResourceManifest[]): AnalysisDiag
 
 function schemaHasStepContext(schema: Record<string, any> | undefined): boolean {
   if (!schema || typeof schema !== "object") return false;
-  if ("x-telo-step-context" in schema) return true;
+  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>)) {

package/src/validate-zone-slots.ts

@@ -26,10 +26,11 @@
  *
  * Browser-safe: no Node built-ins.
  */
-import type { ResourceManifest } from "@telorun/sdk";
+import { ZONE_ATTRIBUTES, zoneAttributeNames, type ResourceManifest } from "@telorun/sdk";
+import { distance } from "./levenshtein.js";
 
 export interface ZoneSlotIssue {
-  code: "ZONE_ANNOTATION_INVALID";
+  code: "ZONE_ANNOTATION_INVALID" | "ZONE_ATTRIBUTE_UNKNOWN" | "ZONE_ATTRIBUTE_INCOMPLETE";
   manifest: ResourceManifest;
   /** Schema path of the annotated slot. */
   path: string;
@@ -38,6 +39,7 @@ export interface ZoneSlotIssue {
 
 const PROVIDES = "x-telo-provides-zone";
 const REQUIRES = "x-telo-requires-zone";
+const VIOLATES = "x-telo-violates-zone";
 
 /** A self-relative JSON Pointer, the only correlation-key spelling both halves
  *  read identically. `""` (whole document) is meaningless as a key, so a
@@ -53,6 +55,107 @@ function describe(value: unknown): string {
   return typeof value;
 }
 
+/** The closest declared attribute name within an edit-distance threshold, or
+ *  undefined. Mirrors `suggestValueType`: case-sensitive, and silent on a tie,
+ *  because a coin-flip suggestion is worse than none. */
+function suggestAttribute(name: string): string | undefined {
+  if (!name) return undefined;
+  const threshold = Math.min(3, Math.floor(name.length / 3));
+  if (threshold < 1) return undefined;
+  let best: string | undefined;
+  let bestDist = threshold + 1;
+  let tied = false;
+  for (const candidate of ZONE_ATTRIBUTES.keys()) {
+    const d = distance(name, candidate);
+    if (d < bestDist) {
+      best = candidate;
+      bestDist = d;
+      tied = false;
+    } else if (d === bestDist) {
+      tied = true;
+    }
+  }
+  return !best || bestDist > threshold || tied ? undefined : best;
+}
+
+/**
+ * The attributes half of the object form.
+ *
+ * The composed `additionalProperties: false` schema would already reject an
+ * unknown name; the dedicated code earns its place by NAMING the valid ones and
+ * suggesting a spelling, instead of reporting a schema violation on a key the
+ * author believed was real — the same standing `X_TELO_TYPE_UNKNOWN` has over
+ * the value-type vocabulary it is modelled on.
+ */
+function checkAttributes(
+  obj: Record<string, unknown>,
+  definition: ResourceManifest,
+  path: string,
+  issues: ZoneSlotIssue[],
+  annotation: string = PROVIDES,
+): void {
+  const declared = new Set<string>();
+
+  for (const [name, value] of Object.entries(obj)) {
+    if (name === "key") continue;
+    const entry = ZONE_ATTRIBUTES.get(name);
+    if (!entry) {
+      const suggestion = suggestAttribute(name);
+      issues.push({
+        code: "ZONE_ATTRIBUTE_UNKNOWN",
+        manifest: definition,
+        path,
+        message:
+          `${annotation} at '${path}' declares '${name}', which is not a zone attribute. ` +
+          (suggestion ? `Did you mean '${suggestion}'? ` : "") +
+          `The vocabulary is closed: ${zoneAttributeNames().join(", ")}. An attribute ` +
+          `states a property of everything executed inside this zone, and every reader ` +
+          `of one is core — a name outside the set would be read by nothing.`,
+      });
+      continue;
+    }
+    // Each value is the REASON, and it is required by being the value itself
+    // rather than a sibling of a boolean. That is also what makes a type check
+    // possible at all: there is no `true` to accept, so `atomic: true` is caught
+    // here rather than reading as a valid declaration with nothing to say.
+    if (typeof value !== "string" || !value) {
+      issues.push({
+        code: "ZONE_ANNOTATION_INVALID",
+        manifest: definition,
+        path,
+        message:
+          `${annotation} at '${path}' declares '${name}' as ${describe(value)}. Every zone ` +
+          `attribute's value is the author's REASON — a non-empty sentence, quoted verbatim ` +
+          `by the diagnostics that enforce it (${entry.description}).`,
+      });
+      continue;
+    }
+    declared.add(name);
+  }
+
+  // The completeness rule is about what a region PROMISES: declaring `atomic`
+  // without `noSuspend` is an incomplete promise. A VIOLATION is not a promise —
+  // breaking one guarantee implies nothing about breaking another — so the rule
+  // does not apply there.
+  if (annotation !== PROVIDES) return;
+  // `requires:` lives in the vocabulary entry rather than as a hardcoded pair of
+  // names here, so the completeness rule sits beside the thing it constrains.
+  for (const name of declared) {
+    for (const dependency of ZONE_ATTRIBUTES.get(name)!.requires) {
+      if (declared.has(dependency)) continue;
+      issues.push({
+        code: "ZONE_ATTRIBUTE_INCOMPLETE",
+        manifest: definition,
+        path,
+        message:
+          `${PROVIDES} at '${path}' declares '${name}' without '${dependency}', which it ` +
+          `requires. ${ZONE_ATTRIBUTES.get(dependency)!.description} Declare it with its own ` +
+          `reason — a generic message is exactly what the required reason exists to prevent.`,
+      });
+    }
+  }
+}
+
 function checkProvides(
   raw: unknown,
   definition: ResourceManifest,
@@ -61,16 +164,38 @@ function checkProvides(
 ): void {
   if (raw === true) return;
   if (isPointer(raw)) return;
+
+  if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+    const obj = raw as Record<string, unknown>;
+    // `key` keeps the meaning it has in the scalar spelling; only its absence is
+    // legitimate here (an uncorrelated zone that still declares attributes).
+    if (obj.key !== undefined && !isPointer(obj.key)) {
+      issues.push({
+        code: "ZONE_ANNOTATION_INVALID",
+        manifest: definition,
+        path,
+        message:
+          `${PROVIDES} at '${path}' declares the correlation key ${describe(obj.key)}, which ` +
+          `is not a self-relative JSON Pointer. Write '/connection'. A bare field name is ` +
+          `read as a pointer by the runtime but skipped by the checker, so the two halves ` +
+          `would disagree about what this manifest means.`,
+      });
+    }
+    checkAttributes(obj, definition, path, issues);
+    return;
+  }
+
   issues.push({
     code: "ZONE_ANNOTATION_INVALID",
     manifest: definition,
     path,
     message:
       `${PROVIDES} at '${path}' is ${describe(raw)}. It takes 'true' (the zone is ` +
-      `uncorrelated) or a self-relative JSON Pointer naming this kind's own field ` +
+      `uncorrelated), a self-relative JSON Pointer naming this kind's own field ` +
       `whose resolved reference the zone carries as its correlation payload ` +
-      `(e.g. '/connection'). It never names the zone — the zone a slot provides ` +
-      `is always the declaring kind.`,
+      `(e.g. '/connection'), or an object carrying that pointer as 'key' beside the ` +
+      `zone attributes this region declares (${zoneAttributeNames().join(", ")}). It ` +
+      `never names the zone — the zone a slot provides is always the declaring kind.`,
   });
 }
 
@@ -129,17 +254,74 @@ function checkRequires(
     fail(`${REQUIRES} at '${path}' declares a non-string 'reason'.`);
   }
 
+  // `attributes` is the GUARANTEE half — what the satisfying zone must declare,
+  // as opposed to which kind it is. It is a list of NAMES with no reasons: the
+  // reason belongs to whoever makes the promise, and a requirer restating it
+  // would be a second sentence to keep in step with the one that is enforced.
+  if (obj.attributes !== undefined) {
+    if (!Array.isArray(obj.attributes) || obj.attributes.length === 0) {
+      fail(
+        `${REQUIRES} at '${path}' declares 'attributes' as ${describe(obj.attributes)}. It ` +
+          `takes a non-empty list of zone attribute names; omit it to require the kind alone.`,
+      );
+    } else {
+      for (const name of obj.attributes) {
+        if (typeof name === "string" && ZONE_ATTRIBUTES.has(name)) continue;
+        const suggestion = typeof name === "string" ? suggestAttribute(name) : undefined;
+        issues.push({
+          code: "ZONE_ATTRIBUTE_UNKNOWN",
+          manifest: definition,
+          path,
+          message:
+            `${REQUIRES} at '${path}' requires '${String(name)}', which is not a zone ` +
+            `attribute. ` +
+            (suggestion ? `Did you mean '${suggestion}'? ` : "") +
+            `The vocabulary is closed: ${zoneAttributeNames().join(", ")}.`,
+        });
+      }
+    }
+  }
+
   for (const key of Object.keys(obj)) {
-    if (key === "zone" || key === "key" || key === "reason") {
+    if (key === "zone" || key === "key" || key === "reason" || key === "attributes") {
       continue;
     }
     fail(
       `${REQUIRES} at '${path}' declares an unknown property '${key}'. The object form takes ` +
-        `'zone', 'key' and 'reason'.`,
+        `'zone', 'key', 'reason' and 'attributes'.`,
     );
   }
 }
 
+/**
+ * The third annotation: what this kind cannot honour.
+ *
+ * Only the object form, because a violation without a reason is exactly the
+ * shape the vocabulary refuses everywhere else — the diagnostic that fires on it
+ * prints the region's promise and this resource's rebuttal side by side, and one
+ * of the two would otherwise be a generated sentence.
+ */
+function checkViolates(
+  raw: unknown,
+  definition: ResourceManifest,
+  path: string,
+  issues: ZoneSlotIssue[],
+): void {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    issues.push({
+      code: "ZONE_ANNOTATION_INVALID",
+      manifest: definition,
+      path,
+      message:
+        `${VIOLATES} at '${path}' is ${describe(raw)}. It takes a map of zone attribute ` +
+        `names to the reason this kind cannot honour each — ` +
+        `\`noSuspend: this waits for a delivery that may be days away\`.`,
+    });
+    return;
+  }
+  checkAttributes(raw as Record<string, unknown>, definition, path, issues, VIOLATES);
+}
+
 /** Walk a definition schema, reporting every zone annotation it cannot read.
  *  Pure-schema walk, so it needs a visited guard for cyclic `$defs`. */
 function walkSchema(
@@ -159,8 +341,10 @@ function walkSchema(
   const obj = node as Record<string, unknown>;
   if (obj[PROVIDES] !== undefined) checkProvides(obj[PROVIDES], definition, path, issues);
   if (obj[REQUIRES] !== undefined) checkRequires(obj[REQUIRES], definition, path, issues);
+  if (obj[VIOLATES] !== undefined) checkViolates(obj[VIOLATES], definition, path, issues);
   for (const [key, value] of Object.entries(obj)) {
-    if (key === PROVIDES || key === REQUIRES || key === "examples" || key === "default") continue;
+    if (key === PROVIDES || key === REQUIRES || key === VIOLATES) continue;
+    if (key === "examples" || key === "default") continue;
     walkSchema(value, path ? `${path}.${key}` : key, visited, definition, issues);
   }
 }