@telorun/analyzer 0.63.0 → 0.64.0

package/src/invocation-contract.ts

@@ -1,4 +1,6 @@
 import { isLiveSlot, type ResourceDefinition, valueTypeOf } from "@telorun/sdk";
+import { AliasResolver, moduleScopedDefResolver, type ModuleScopes } from "./alias-resolver.js";
+import { DefinitionRegistry } from "./definition-registry.js";
 import {
   type ContractDirection,
   contractDeclarer,
@@ -14,6 +16,26 @@ import {
 
 export type { ContractDirection };
 
+/** The {@link ContractScope} the analyzer resolves invocation contracts in: kinds
+ *  resolve in the module that declared the definition they were read off (so an
+ *  `extends` chain crossing module boundaries re-scopes at every hop), and named
+ *  `telo#Type` references resolve against the flattened manifest list. `resolveIn`
+ *  is the top-level entry point, where the kind was written by the READING
+ *  module and there is no declaring definition yet. */
+export function analyzerContractScope(
+  defs: DefinitionRegistry,
+  aliases: AliasResolver,
+  scopes: ModuleScopes,
+  allManifests: Record<string, any>[],
+): ContractScope & { resolveIn(kind: string, module?: string): ResourceDefinition | undefined } {
+  const resolve = moduleScopedDefResolver<ResourceDefinition>(defs, aliases, scopes);
+  return {
+    resolveDefinition: resolve,
+    resolveIn: resolve.in,
+    typeManifestsFor: () => allManifests,
+  };
+}
+
 /**
  * The one answer to "what is this target's input / output schema".
  *

package/src/manifest-analysis.ts

@@ -0,0 +1,132 @@
+/**
+ * **One analyzed manifest set, and the questions asked of it.**
+ *
+ * Several answers a host needs require the SAME two things: the registry's
+ * definitions and aliases, and the manifest set they were resolved against. The
+ * registry deliberately holds no manifests — it is populated per analysis and
+ * reused across them — so each such answer would otherwise become another
+ * factory on the registry and another optional parameter on every IDE entry
+ * point. Four of those arrived in short order (CEL scope, step declarations,
+ * context-binding declarations, invocation contracts) and the next one is not
+ * hypothetical.
+ *
+ * So the pairing is named once and the questions hang off it. A host threads ONE
+ * object and gains later questions for free; each facet keeps its own honest
+ * name rather than accreting onto whichever one happened to exist first.
+ *
+ * Nothing here re-implements an answer. `contractFor` is the shared
+ * {@link resolveContract} — the one `telo check` runs and the kernel binds at
+ * dispatch — given the scope to run in; `celScope` is the same
+ * {@link CelScopeQuery} the analysis pass's rule is built from. That is the
+ * whole point: a completion list is a claim about what the checker accepts, and
+ * a second implementation of any of these could not be held to it.
+ */
+import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
+import { AliasResolver, type ModuleScopes } from "./alias-resolver.js";
+import { CelScopeQuery, type CelScopeQueryContext } from "./cel-scope-query.js";
+import { DefinitionRegistry } from "./definition-registry.js";
+import type { ContractDirection } from "./extends-resolution.js";
+import { analyzerContractScope, resolveContract } from "./invocation-contract.js";
+import { findManifest } from "./find-manifest.js";
+import { isModuleKind } from "./module-kinds.js";
+
+/**
+ * A reference as the loader leaves it — the internal `{kind, name, alias?}`
+ * shape `resolveRefSentinels` rewrites `!ref` into.
+ */
+export interface ManifestRef {
+  kind?: string;
+  name?: string;
+  alias?: string;
+}
+
+export class ManifestAnalysis {
+  private readonly scopes: ModuleScopes;
+  private celScopeQuery: CelScopeQuery | undefined;
+
+  constructor(
+    readonly manifests: ResourceManifest[],
+    private readonly ctx: CelScopeQueryContext,
+  ) {
+    const rootModules = new Set<string>();
+    for (const m of manifests) {
+      if (isModuleKind(m.kind) && m.metadata?.name) rootModules.add(m.metadata.name as string);
+    }
+    this.scopes = { aliasesByModule: ctx.aliasesByModule, rootModules };
+  }
+
+  /** What CEL sees, per site. Built on first use — its indices are a function of
+   *  the whole set, and a host that never opens a CEL body should not pay for
+   *  them. */
+  get celScope(): CelScopeQuery {
+    return (this.celScopeQuery ??= new CelScopeQuery(this.manifests, this.ctx));
+  }
+
+  /** The manifest a `(kind, name)` pair addresses. */
+  resourceFor(kind: string | undefined, name: string | undefined): ResourceManifest | undefined {
+    return findManifest(this.manifests, kind, name);
+  }
+
+  /**
+   * The invocation contract of the resource a reference names.
+   *
+   * The shared resolver, so an editor offering a target's input keys is offering
+   * exactly what `telo check` validates that call site against and what the
+   * kernel binds at dispatch. Layered instance-first: a resource declaring its
+   * own `inputType:` narrows the kind's, which is the common case for a
+   * `Run.Sequence` used as a handler.
+   */
+  contractFor(ref: ManifestRef, direction: ContractDirection): Record<string, any> | undefined {
+    const target = this.resolveRef(ref);
+    const definition = ref.kind ? this.definitionFor(ref.kind) : undefined;
+    if (!target && !definition) return undefined;
+    return resolveContract(
+      direction,
+      target as Record<string, any> | undefined,
+      definition,
+      analyzerContractScope(
+        this.ctx.defs,
+        this.ctx.aliases,
+        this.scopes,
+        this.manifests as Record<string, any>[],
+      ),
+    )?.schema;
+  }
+
+  /**
+   * The manifest a reference names.
+   *
+   * An ALIAS narrows before the name does: a flattened set carries every
+   * imported library's exported instances, so two libraries exporting a `store`
+   * are two manifests with one name. Matching the alias to its target module
+   * picks the right one; where the alias resolves to nothing the name alone is
+   * used, which is what a local reference needs anyway.
+   */
+  private resolveRef(ref: ManifestRef): ResourceManifest | undefined {
+    if (!ref.name) return undefined;
+    const byName = this.manifests.filter(
+      (m) => (m.metadata as { name?: string } | undefined)?.name === ref.name,
+    );
+    if (byName.length === 0) return undefined;
+    if (byName.length === 1) return byName[0];
+
+    const targetModule = ref.alias ? this.ctx.aliases.moduleForAlias?.(ref.alias) : undefined;
+    if (targetModule) {
+      const scoped = byName.find(
+        (m) => (m.metadata as { module?: string } | undefined)?.module === targetModule,
+      );
+      if (scoped) return scoped;
+    }
+    // Several candidates and nothing to choose between them: refusing is the
+    // honest answer, since typing a call site against the wrong resource's
+    // contract is worse than typing it against none.
+    return ref.kind ? byName.find((m) => m.kind === ref.kind) : undefined;
+  }
+
+  private definitionFor(kind: string): ResourceDefinition | undefined {
+    const canonical = this.ctx.aliases.resolveKind(kind);
+    return this.ctx.defs.resolve(kind) ?? (canonical ? this.ctx.defs.resolve(canonical) : undefined);
+  }
+}
+
+export type { CelScopeQueryContext, AliasResolver, DefinitionRegistry };

package/src/manifest-path.ts

@@ -0,0 +1,34 @@
+/**
+ * Navigating a MANIFEST by a concrete path (`routes[0].request.schema.query`).
+ *
+ * The counterpart to `schema-walk.ts`, which navigates a schema: this addresses
+ * the author's own document, indices and all. Its own module because three
+ * places needed it independently — the CEL scope query resolving a context
+ * binding's declaration, the call-site checker resolving an argument map, and
+ * the IDE resolving the same map for completion — and three copies of one
+ * traversal is exactly what the shared-answer rule exists to prevent.
+ */
+
+/**
+ * The value at `path`, or `undefined` when any segment is absent.
+ *
+ * Absence is what makes a candidate path a CHECK rather than a guess: a caller
+ * offering several possible shapes can try each and know a hit is a real node.
+ */
+export function navigateConcretePath(root: Record<string, any>, path: string): unknown {
+  let current: unknown = root;
+  for (const segment of path.split(".")) {
+    if (!segment) continue;
+    const match = segment.match(/^([^[]*)((?:\[\d+\])*)$/);
+    if (!match) return undefined;
+    if (match[1]) {
+      if (current === null || typeof current !== "object") return undefined;
+      current = (current as Record<string, unknown>)[match[1]];
+    }
+    for (const index of match[2].matchAll(/\[(\d+)\]/g)) {
+      if (!Array.isArray(current)) return undefined;
+      current = current[Number(index[1])];
+    }
+  }
+  return current;
+}

package/src/schema-walk.ts

@@ -0,0 +1,144 @@
+/**
+ * Structural traversal over a kind's JSON Schema and the step arrays it
+ * declares. Nothing here analyzes: these answer "what does this schema node
+ * point at" and "how do steps nest", the two questions every analyzer pass
+ * asks before it can say anything.
+ *
+ * Its own file so the CEL scope rule (`cel-scope.ts`) and the analysis pass
+ * (`analyzer.ts`) can both reach it without either importing the other — the
+ * scope rule is consumed by the IDE, which must not pull the pass in behind it.
+ */
+import { MANIFEST_SCHEMA_URI, ManifestRootSchema } from "./manifest-schemas.js";
+
+/** Resolve a local `$ref` (only `#/$defs/<name>` form) against the root schema.
+ *  Non-refs and unresolved refs pass through unchanged. */
+export function resolveLocalRef(
+  schema: Record<string, any> | undefined,
+  root: Record<string, any>,
+): Record<string, any> | undefined {
+  if (!schema) return undefined;
+  const ref = schema.$ref;
+  if (typeof ref === "string" && ref.startsWith("#/$defs/")) {
+    const defName = ref.slice("#/$defs/".length);
+    const resolved = root.$defs?.[defName];
+    if (resolved && typeof resolved === "object") return resolved as Record<string, any>;
+  }
+  // A kernel-owned structural fragment (`telo://manifest#/$defs/InvokeStep`).
+  // Resolved HERE rather than by each walker: this is the one chokepoint every
+  // structural walk already goes through — the step-array walks, the call graph,
+  // the zone projection, the eval-path collector — so a composer that points at a
+  // shared shape stays legible to all of them at once. Nothing is inlined into
+  // the stored schema, which keeps validator-cache identity stable and matches
+  // what `resolveSchemaTypeRefs` does for a named user type.
+  if (typeof ref === "string" && ref.startsWith(BUILTIN_FRAGMENT_PREFIX)) {
+    const defName = ref.slice(BUILTIN_FRAGMENT_PREFIX.length);
+    const resolved = (ManifestRootSchema.$defs as Record<string, unknown>)[defName];
+    if (resolved && typeof resolved === "object") return resolved as Record<string, any>;
+  }
+  return schema;
+}
+
+const BUILTIN_FRAGMENT_PREFIX = `${MANIFEST_SCHEMA_URI}#/$defs/`;
+
+/** Gather property schemas from a (possibly variant-bearing) object schema:
+ *  top-level `properties` plus every `oneOf` / `anyOf` / `allOf` branch.
+ *
+ *  Each branch is resolved through {@link resolveLocalRef} first, so a branch
+ *  that points at a shared shape — a `oneOf` arm that IS the kernel's dispatch
+ *  site — contributes its properties like an inline one. Without that, pointing a
+ *  composer at a shared shape would silently empty every role-driven lookup that
+ *  reads this (the inputs slot, the retry policy, the eval paths), which is a
+ *  failure with no diagnostic attached to it. */
+export function gatherPropertySchemas(
+  schema: Record<string, any>,
+  root?: Record<string, any>,
+): Array<[string, Record<string, any>]> {
+  const out: Array<[string, Record<string, any>]> = [];
+  const base = resolveLocalRef(schema, root ?? schema) ?? schema;
+  if (base.properties && typeof base.properties === "object") {
+    for (const [k, v] of Object.entries(base.properties as Record<string, any>)) {
+      out.push([k, v as Record<string, any>]);
+    }
+  }
+  for (const variantKey of ["oneOf", "anyOf", "allOf"] as const) {
+    const arr = base[variantKey];
+    if (!Array.isArray(arr)) continue;
+    for (const raw of arr) {
+      if (!raw || typeof raw !== "object") continue;
+      const variant = resolveLocalRef(raw as Record<string, any>, root ?? schema) ?? raw;
+      if (variant.properties) {
+        for (const [k, v] of Object.entries(variant.properties as Record<string, any>)) {
+          out.push([k, v as Record<string, any>]);
+        }
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Generic, role-driven walk over a step array. Calls
+ * `visit(step, stepPath)` for every step — top-level and nested through the
+ * `x-telo-topology-role` forms (`branch`, `branch-list`, `case-map`). This is
+ * the single definition of how steps nest, shared by `buildStepContextSchema`
+ * (which types `steps.<name>.result`) and `validateStepInvokeReferences` (which
+ * checks invoke refs), so the topology contract lives in one place — adding a
+ * role or nesting form updates both consumers at once. No resource kind is
+ * hardcoded; recursion is driven entirely by the schema annotations.
+ */
+export function walkStepArray(
+  steps: unknown[],
+  stepItemSchema: Record<string, any> | undefined,
+  rootSchema: Record<string, any>,
+  basePath: string,
+  visit: (step: Record<string, any>, stepPath: string) => void,
+): void {
+  const dispatchRole = (
+    data: unknown,
+    role: string,
+    itemsSchema: Record<string, any> | undefined,
+    path: string,
+  ): void => {
+    if (role === "branch" && Array.isArray(data)) {
+      walkStepArray(data, stepItemSchema, rootSchema, path, visit);
+    } else if (role === "case-map" && data && typeof data === "object" && !Array.isArray(data)) {
+      for (const [caseKey, arr] of Object.entries(data as Record<string, unknown>)) {
+        if (Array.isArray(arr)) walkStepArray(arr, stepItemSchema, rootSchema, `${path}.${caseKey}`, visit);
+      }
+    } else if (role === "branch-list" && Array.isArray(data)) {
+      const entrySchema = resolveLocalRef(itemsSchema, rootSchema);
+      if (!entrySchema) return;
+      data.forEach((entry, i) => {
+        if (!entry || typeof entry !== "object") return;
+        for (const [subKey, subSchema] of gatherPropertySchemas(entrySchema)) {
+          const subRole = subSchema["x-telo-topology-role"];
+          if (typeof subRole !== "string") continue;
+          dispatchRole(
+            (entry as Record<string, any>)[subKey],
+            subRole,
+            subSchema.items as Record<string, any> | undefined,
+            `${path}[${i}].${subKey}`,
+          );
+        }
+      });
+    }
+  };
+
+  steps.forEach((step, i) => {
+    if (!step || typeof step !== "object") return;
+    const s = step as Record<string, any>;
+    const stepPath = `${basePath}[${i}]`;
+    visit(s, stepPath);
+    if (!stepItemSchema) return;
+    for (const [propKey, propSchema] of gatherPropertySchemas(stepItemSchema)) {
+      const role = propSchema["x-telo-topology-role"];
+      if (typeof role !== "string") continue;
+      dispatchRole(
+        s[propKey],
+        role,
+        propSchema.items as Record<string, any> | undefined,
+        `${stepPath}.${propKey}`,
+      );
+    }
+  });
+}

package/src/telo-version.ts

@@ -6,4 +6,4 @@
 // written against, and every kernel in every language reports the same scale.
 
 /** The surface generation this analyzer implements. */
-export const TELO_SURFACE_VERSION = "0.79.0";
+export const TELO_SURFACE_VERSION = "0.80.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,
@@ -20,6 +20,12 @@ import {
   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;
@@ -66,6 +72,15 @@ 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 = readStepSlot(fieldSchema);
     if (!stepCtx) continue;
@@ -92,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
@@ -104,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`
@@ -163,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 ` +
@@ -184,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",
@@ -200,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;
 }