@telorun/analyzer 0.1.3 → 0.2.0

package/src/resolve-throws-union.ts

@@ -0,0 +1,345 @@
+import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+
+export interface ThrowsCodeMeta {
+  data?: Record<string, any>;
+}
+
+export interface ThrowsUnion {
+  /** Code → per-code metadata (data schema, etc). Keys are the declared codes. */
+  codes: Map<string, ThrowsCodeMeta>;
+  /** True when the union cannot be fully resolved statically — e.g. a
+   *  `passthrough` call site uses a CEL expression the analyzer can't narrow,
+   *  an unknown kind was encountered, or a cycle short-circuited resolution.
+   *  Callers must treat unbounded unions as requiring a catch-all entry. */
+  unbounded: boolean;
+}
+
+export interface ResolveCtx {
+  allManifests: ResourceManifest[];
+  defs: DefinitionRegistry;
+  aliases: AliasResolver;
+  memo: Map<string, ThrowsUnion>;
+  inProgress: Set<string>;
+}
+
+export function createResolveCtx(
+  allManifests: ResourceManifest[],
+  defs: DefinitionRegistry,
+  aliases: AliasResolver,
+): ResolveCtx {
+  return {
+    allManifests,
+    defs,
+    aliases,
+    memo: new Map(),
+    inProgress: new Set(),
+  };
+}
+
+function emptyUnion(): ThrowsUnion {
+  return { codes: new Map(), unbounded: false };
+}
+
+function unionInto(target: ThrowsUnion, src: ThrowsUnion): void {
+  for (const [code, meta] of src.codes) {
+    if (!target.codes.has(code)) target.codes.set(code, meta);
+  }
+  if (src.unbounded) target.unbounded = true;
+}
+
+function definitionFor(
+  kind: string,
+  defs: DefinitionRegistry,
+  aliases: AliasResolver,
+): ResourceDefinition | undefined {
+  const resolved = aliases.resolveKind(kind);
+  return defs.resolve(kind) ?? (resolved ? defs.resolve(resolved) : undefined);
+}
+
+function codesFromDefinition(definition: ResourceDefinition): Map<string, ThrowsCodeMeta> {
+  const out = new Map<string, ThrowsCodeMeta>();
+  const raw = definition.throws?.codes ?? {};
+  for (const [code, meta] of Object.entries(raw)) {
+    out.set(code, { data: (meta as { data?: Record<string, any> }).data });
+  }
+  return out;
+}
+
+/** Resolve the effective throw union for a named manifest. The result combines
+ *  explicit `throws.codes`, `throws.inherit: true` dataflow (step-context
+ *  traversal with try/catch subtraction), and unbounded markers for
+ *  unresolvable passthrough call sites. Cycles short-circuit to an empty
+ *  result so resolution always terminates. */
+export function resolveThrowsUnion(
+  manifest: ResourceManifest,
+  ctx: ResolveCtx,
+): ThrowsUnion {
+  const name = manifest.metadata?.name as string | undefined;
+
+  if (name) {
+    const cached = ctx.memo.get(name);
+    if (cached) return cached;
+    if (ctx.inProgress.has(name)) return emptyUnion();
+  }
+
+  const definition = definitionFor(manifest.kind, ctx.defs, ctx.aliases);
+  if (!definition) {
+    const u: ThrowsUnion = { codes: new Map(), unbounded: true };
+    if (name) ctx.memo.set(name, u);
+    return u;
+  }
+
+  const throws = definition.throws;
+  if (!throws) {
+    const u = emptyUnion();
+    if (name) ctx.memo.set(name, u);
+    return u;
+  }
+
+  if (name) ctx.inProgress.add(name);
+  try {
+    const result: ThrowsUnion = { codes: new Map(), unbounded: false };
+
+    for (const [code, meta] of codesFromDefinition(definition)) {
+      result.codes.set(code, meta);
+    }
+
+    if (throws.passthrough) {
+      // Definition-level passthrough can't be resolved without a call site.
+      // resolveStepInvokeThrows handles passthrough call sites directly.
+      result.unbounded = true;
+    }
+
+    if (throws.inherit) {
+      const inherited = resolveInherited(manifest, definition, ctx);
+      unionInto(result, inherited);
+    }
+
+    if (name) ctx.memo.set(name, result);
+    return result;
+  } finally {
+    if (name) ctx.inProgress.delete(name);
+  }
+}
+
+function resolveInherited(
+  manifest: ResourceManifest,
+  definition: ResourceDefinition,
+  ctx: ResolveCtx,
+): ThrowsUnion {
+  const result: ThrowsUnion = { codes: new Map(), unbounded: false };
+  const props = definition.schema?.properties as Record<string, any> | undefined;
+  if (!props) return result;
+
+  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 steps = (manifest as Record<string, any>)[fieldName];
+    if (!Array.isArray(steps)) continue;
+    unionInto(result, collectStepArrayThrows(steps, stepCtx.invoke, undefined, ctx));
+  }
+
+  return result;
+}
+
+function collectStepArrayThrows(
+  steps: unknown[],
+  invokeField: string,
+  enclosingTryCodes: Set<string> | undefined,
+  ctx: ResolveCtx,
+): ThrowsUnion {
+  const result = emptyUnion();
+  for (const step of steps) {
+    if (!step || typeof step !== "object") continue;
+    unionInto(
+      result,
+      collectStepThrows(step as Record<string, any>, invokeField, enclosingTryCodes, ctx),
+    );
+  }
+  return result;
+}
+
+/** Walk one step, dispatching by shape. Generic for any Run.Sequence-style
+ *  composer: the step keys it recognises (`try` / `catch` / `finally` / `then`
+ *  / `else` / `elseif` / `do` / `cases` / `default`) are the same set already
+ *  traversed by the analyzer's `x-telo-step-context` schema builder, so future
+ *  composers that reuse those shape conventions work without changes here. */
+function collectStepThrows(
+  step: Record<string, any>,
+  invokeField: string,
+  enclosingTryCodes: Set<string> | undefined,
+  ctx: ResolveCtx,
+): ThrowsUnion {
+  if (step[invokeField]) {
+    return resolveStepInvokeThrows(step, invokeField, enclosingTryCodes, ctx);
+  }
+
+  if (step.throw && typeof step.throw === "object") {
+    return resolveThrowStepCode(step.throw as Record<string, any>, enclosingTryCodes);
+  }
+
+  if (Array.isArray(step.try)) {
+    const tryUnion = collectStepArrayThrows(step.try, invokeField, enclosingTryCodes, ctx);
+    let propagated: ThrowsUnion;
+    if (Array.isArray(step.catch)) {
+      // Catch absorbs the try block's codes; the catch's own throws propagate
+      // out instead. Sequence-specific subtraction — the plan explicitly
+      // anchors this to Run.Sequence's try/catch schema shape.
+      const tryCodes = new Set(tryUnion.codes.keys());
+      propagated = collectStepArrayThrows(step.catch, invokeField, tryCodes, ctx);
+      // Unbounded in the try block still signals the caller to expect
+      // arbitrary codes to flow through the catch (e.g. via passthrough).
+      if (tryUnion.unbounded) propagated.unbounded = true;
+    } else {
+      propagated = cloneUnion(tryUnion);
+    }
+    if (Array.isArray(step.finally)) {
+      unionInto(
+        propagated,
+        collectStepArrayThrows(step.finally, invokeField, enclosingTryCodes, ctx),
+      );
+    }
+    return propagated;
+  }
+
+  if (Array.isArray(step.then)) {
+    const result = emptyUnion();
+    unionInto(result, collectStepArrayThrows(step.then, invokeField, enclosingTryCodes, ctx));
+    if (Array.isArray(step.else)) {
+      unionInto(result, collectStepArrayThrows(step.else, invokeField, enclosingTryCodes, ctx));
+    }
+    if (Array.isArray(step.elseif)) {
+      for (const branch of step.elseif) {
+        if (Array.isArray(branch?.then)) {
+          unionInto(
+            result,
+            collectStepArrayThrows(branch.then, invokeField, enclosingTryCodes, ctx),
+          );
+        }
+      }
+    }
+    return result;
+  }
+
+  if (Array.isArray(step.do)) {
+    return collectStepArrayThrows(step.do, invokeField, enclosingTryCodes, ctx);
+  }
+
+  if (step.cases && typeof step.cases === "object") {
+    const result = emptyUnion();
+    for (const arr of Object.values(step.cases as Record<string, unknown>)) {
+      if (Array.isArray(arr)) {
+        unionInto(result, collectStepArrayThrows(arr, invokeField, enclosingTryCodes, ctx));
+      }
+    }
+    if (Array.isArray(step.default)) {
+      unionInto(result, collectStepArrayThrows(step.default, invokeField, enclosingTryCodes, ctx));
+    }
+    return result;
+  }
+
+  return emptyUnion();
+}
+
+function cloneUnion(u: ThrowsUnion): ThrowsUnion {
+  const out = emptyUnion();
+  for (const [c, m] of u.codes) out.codes.set(c, m);
+  out.unbounded = u.unbounded;
+  return out;
+}
+
+function resolveStepInvokeThrows(
+  step: Record<string, any>,
+  invokeField: string,
+  enclosingTryCodes: Set<string> | undefined,
+  ctx: ResolveCtx,
+): ThrowsUnion {
+  const invokeRef = step[invokeField];
+  if (!invokeRef || typeof invokeRef !== "object") return emptyUnion();
+  const invokedKind = invokeRef.kind as string | undefined;
+  if (!invokedKind) return emptyUnion();
+
+  const definition = definitionFor(invokedKind, ctx.defs, ctx.aliases);
+  if (!definition) return { codes: new Map(), unbounded: true };
+
+  if (definition.throws?.passthrough) {
+    return resolvePassthroughAtCallSite(step, enclosingTryCodes);
+  }
+
+  // Named manifest: resolve the full chain (covers transitive inherit).
+  const invokeName = invokeRef.name as string | undefined;
+  if (invokeName) {
+    const target = ctx.allManifests.find(
+      (m) =>
+        m.metadata?.name === invokeName &&
+        (m.kind === invokedKind ||
+          ctx.aliases.resolveKind(m.kind) === invokedKind ||
+          m.kind === ctx.aliases.resolveKind(invokedKind)),
+    );
+    if (target) return resolveThrowsUnion(target, ctx);
+  }
+
+  // Fall back to the definition's own explicit codes. Mark unbounded when the
+  // definition depends on call-site or transitive resolution we couldn't
+  // perform (no specific target manifest to recurse into).
+  const codes = codesFromDefinition(definition);
+  const unbounded =
+    definition.throws?.inherit === true || definition.throws?.passthrough === true;
+  return { codes, unbounded };
+}
+
+/** Resolve a passthrough-style invocable at a specific call site. Recognised forms
+ *  (see "passthrough: true" in the plan):
+ *  - constant literal (no template) → `{ <literal> }`
+ *  - `${{ 'FOO' }}` constant expression → `{ FOO }`
+ *  - `${{ error.code }}` inside a catch → enclosing try's propagated union
+ *  Anything else is unbounded; the analyzer flags it downstream. */
+function resolvePassthroughAtCallSite(
+  step: Record<string, any>,
+  enclosingTryCodes: Set<string> | undefined,
+): ThrowsUnion {
+  return resolveCodeExpression(step.inputs?.code, enclosingTryCodes);
+}
+
+/** Resolve the `code:` of a `throw:` step to a throws union. Uses the same
+ *  recognised forms as passthrough call sites. */
+function resolveThrowStepCode(
+  throwSpec: Record<string, any>,
+  enclosingTryCodes: Set<string> | undefined,
+): ThrowsUnion {
+  return resolveCodeExpression(throwSpec.code, enclosingTryCodes);
+}
+
+function resolveCodeExpression(
+  codeInput: unknown,
+  enclosingTryCodes: Set<string> | undefined,
+): ThrowsUnion {
+  if (typeof codeInput !== "string" || codeInput.length === 0) {
+    return { codes: new Map(), unbounded: true };
+  }
+
+  const match = codeInput.match(/^\s*\$\{\{\s*([\s\S]+?)\s*\}\}\s*$/);
+  if (!match) {
+    return { codes: new Map([[codeInput, {}]]), unbounded: false };
+  }
+
+  const expr = match[1].trim();
+  const litMatch = expr.match(/^'([^']+)'$|^"([^"]+)"$/);
+  if (litMatch) {
+    const code = litMatch[1] ?? litMatch[2]!;
+    return { codes: new Map([[code, {}]]), unbounded: false };
+  }
+
+  if (expr === "error.code") {
+    if (enclosingTryCodes) {
+      const codes = new Map<string, ThrowsCodeMeta>();
+      for (const c of enclosingTryCodes) codes.set(c, {});
+      return { codes, unbounded: false };
+    }
+    return { codes: new Map(), unbounded: true };
+  }
+
+  return { codes: new Map(), unbounded: true };
+}

package/src/types.ts

@@ -45,6 +45,16 @@ export interface ManifestAdapter {
   supports(url: string): boolean;
   read(url: string): Promise<{ text: string; source: string }>;
   resolveRelative(base: string, relative: string): string;
+
+  /** Expand glob patterns relative to a base source. Returns sources in the same
+   *  format as read().source — suitable to pass back into read() / resolveRelative().
+   *  Optional — only filesystem-capable adapters implement this. */
+  expandGlob?(base: string, patterns: string[]): Promise<string[]>;
+
+  /** Walk parent directories from fileUrl looking for the nearest telo.yaml.
+   *  Returns the source in the same format as read().source, or null if none found.
+   *  Optional — only filesystem-capable adapters implement this. */
+  resolveOwnerOf?(fileUrl: string): Promise<string | null>;
 }
 
 export interface LoadOptions {
@@ -64,6 +74,9 @@ export interface LoaderInitOptions {
   includeRegistryAdapter?: boolean;
   /** Base URL used by built-in RegistryAdapter when enabled. */
   registryUrl?: string;
+  /** Handlers for CEL stdlib functions (e.g. `sha256`). Analyzer-only callers may
+   *  omit this and get throwing stubs; runtime callers (kernel) must supply real impls. */
+  celHandlers?: import("./cel-environment.js").CelHandlers;
 }
 
 export interface AnalysisOptions {

package/src/validate-cel-context.ts

@@ -13,7 +13,7 @@ export function resolveTypeFieldToSchema(
   if (!value) return undefined;
 
   if (typeof value === "string") {
-    // Named type reference — find a Kernel.Type resource by name
+    // Named type reference — find a Telo.Type resource by name
     const typeManifest = allManifests.find(
       (m) =>
         (m.metadata as any)?.name === value &&

package/src/validate-references.ts

@@ -6,7 +6,12 @@ import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 
 const SOURCE = "telo-analyzer";
-const SYSTEM_KINDS = new Set(["Kernel.Definition", "Kernel.Abstract"]);
+/** Kinds skipped by reference validation. Telo.Application and Telo.Library
+ *  are intentionally not here: Application has `targets` with x-telo-ref that
+ *  must be validated, and Library has no ref-bearing fields so flows through
+ *  harmlessly. Telo.Import is also not here for the same reason — its
+ *  `source` field isn't x-telo-ref, so nothing gets checked. */
+const SYSTEM_KINDS = new Set(["Telo.Definition", "Telo.Abstract"]);
 
 /**
  * Checks whether `kind` satisfies the ref constraint in `entry`.
@@ -27,7 +32,7 @@ function checkKind(
     if (!targetKind) return [];
     const targetDef = registry.resolve(targetKind);
     if (!targetDef) return [];
-    if (targetDef.kind === "Kernel.Abstract") {
+    if (targetDef.kind === "Telo.Abstract") {
       const implementing = registry.getByExtends(targetKind);
       if (implementing.length === 0) return []; // partial context — no implementations loaded yet
       const implementingKinds = new Set(
@@ -71,7 +76,7 @@ export function validateReferences(
   if (!aliases || !registry) return diagnostics;
 
   // Build outer resource lookup by name for resolution check.
-  // Exclude system kinds (Kernel.Definition) — they are type blueprints, not instances,
+  // Exclude system kinds (Telo.Definition) — they are type blueprints, not instances,
   // and their names (e.g. "Server", "Job") would shadow user-defined resource instances.
   const byName = new Map<string, ResourceManifest>();
   for (const r of resources) {
@@ -86,6 +91,7 @@ export function validateReferences(
 
     const resourceLabel = `${r.kind}/${r.metadata.name as string}`;
     const resourceData = { kind: r.kind, name: r.metadata.name as string };
+    const filePath = (r.metadata as { source?: string } | undefined)?.source;
 
     // Collect scope visibility prefixes (JSON Pointer → dot prefix) and their manifests.
     // scope field path → flat array of ResourceManifest declared in that scope.
@@ -155,7 +161,7 @@ export function validateReferences(
               code: "UNRESOLVED_REFERENCE",
               source: SOURCE,
               message: `${resourceLabel}: reference at '${fieldPath}' → resource '${val}' not found`,
-              data: { resource: resourceData, path: fieldPath },
+              data: { resource: resourceData, filePath, path: fieldPath },
             });
             continue;
           }
@@ -166,7 +172,7 @@ export function validateReferences(
               code: "REFERENCE_KIND_MISMATCH",
               source: SOURCE,
               message: `${resourceLabel}: reference at '${fieldPath}' → ${kindErrors.join("; ")}`,
-              data: { resource: resourceData, path: fieldPath },
+              data: { resource: resourceData, filePath, path: fieldPath },
             });
           }
           continue;
@@ -185,7 +191,7 @@ export function validateReferences(
             code: "INVALID_REFERENCE",
             source: SOURCE,
             message: `${resourceLabel}: reference at '${fieldPath}' must have string 'kind' and 'name' fields`,
-            data: { resource: resourceData, path: fieldPath },
+            data: { resource: resourceData, filePath, path: fieldPath },
           });
           continue;
         }
@@ -198,7 +204,7 @@ export function validateReferences(
             code: "REFERENCE_KIND_MISMATCH",
             source: SOURCE,
             message: `${resourceLabel}: reference at '${fieldPath}' → ${kindErrors.join("; ")}`,
-            data: { resource: resourceData, path: fieldPath },
+            data: { resource: resourceData, filePath, path: fieldPath },
           });
         }
 
@@ -212,7 +218,7 @@ export function validateReferences(
             code: "UNRESOLVED_REFERENCE",
             source: SOURCE,
             message: `${resourceLabel}: reference at '${fieldPath}' → resource '${refVal.name}' not found`,
-            data: { resource: resourceData, path: fieldPath },
+            data: { resource: resourceData, filePath, path: fieldPath },
           });
         }
       }
@@ -231,6 +237,7 @@ export function validateReferences(
 
     const resourceLabel = `${r.kind}/${r.metadata.name as string}`;
     const resourceData = { kind: r.kind, name: r.metadata.name as string };
+    const filePath = (r.metadata as { source?: string } | undefined)?.source;
 
     for (const [fieldPath, entry] of fieldMap) {
       if (!isSchemaFromEntry(entry)) continue;
@@ -245,7 +252,7 @@ export function validateReferences(
           code: "INVALID_SCHEMA_FROM",
           source: SOURCE,
           message: `${resourceLabel}: x-telo-schema-from "${schemaFrom}" must contain at least one "/" to separate anchor from JSON Pointer`,
-          data: { resource: resourceData, path: fieldPath },
+          data: { resource: resourceData, filePath, path: fieldPath },
         });
         continue;
       }
@@ -288,7 +295,7 @@ export function validateReferences(
             code: "SCHEMA_FROM_MISSING_PATH",
             source: SOURCE,
             message: `${resourceLabel}: x-telo-schema-from at '${fieldPath}' → kind '${refVal.kind}' has no schema`,
-            data: { resource: resourceData, path: fieldPath },
+            data: { resource: resourceData, filePath, path: fieldPath },
           });
           continue;
         }
@@ -300,7 +307,7 @@ export function validateReferences(
             code: "SCHEMA_FROM_MISSING_PATH",
             source: SOURCE,
             message: `${resourceLabel}: x-telo-schema-from at '${fieldPath}' → kind '${refVal.kind}' has no schema path '${jsonPointer}'`,
-            data: { resource: resourceData, path: fieldPath },
+            data: { resource: resourceData, filePath, path: fieldPath },
           });
           continue;
         }
@@ -312,7 +319,7 @@ export function validateReferences(
             code: "DEPENDENT_SCHEMA_MISMATCH",
             source: SOURCE,
             message: `${resourceLabel}: '${fieldPath}' does not match schema from '${refVal.kind}${jsonPointer}': ${issue}`,
-            data: { resource: resourceData, path: fieldPath },
+            data: { resource: resourceData, filePath, path: fieldPath },
           });
         }
       }