@telorun/analyzer 0.12.1 → 1.0.0

package/src/resolve-throws-union.ts

@@ -1,4 +1,5 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
+import { isTaggedSentinel } from "@telorun/templating";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 
@@ -6,6 +7,11 @@ export interface ThrowsCodeMeta {
   data?: Record<string, any>;
 }
 
+/** Code a non-`InvokeError` failure surfaces as inside a `catch` block. Mirrors
+ *  `PLAIN_ERROR_CODE` in `@telorun/run`'s `toSequenceError`: any invoke can throw
+ *  a plain error, which the catch sees as `error.code === "INTERNAL_ERROR"`. */
+export const PLAIN_ERROR_CODE = "INTERNAL_ERROR";
+
 export interface ThrowsUnion {
   /** Code → per-code metadata (data schema, etc). Keys are the declared codes. */
   codes: Map<string, ThrowsCodeMeta>;
@@ -14,6 +20,12 @@ export interface ThrowsUnion {
    *  an unknown kind was encountered, or a cycle short-circuited resolution.
    *  Callers must treat unbounded unions as requiring a catch-all entry. */
   unbounded: boolean;
+  /** True when the block can fail with a non-`InvokeError` (any `invoke:` step).
+   *  Such a failure surfaces inside an enclosing `catch` as `PLAIN_ERROR_CODE`,
+   *  so a `throw: { code: "${{ error.code }}" }` rethrow can propagate it. Not
+   *  injected into `codes` — only seeds `enclosingTryCodes` at a try/catch site,
+   *  leaving non-rethrow unions untouched. */
+  canThrowPlain?: boolean;
 }
 
 export interface ResolveCtx {
@@ -47,6 +59,7 @@ function unionInto(target: ThrowsUnion, src: ThrowsUnion): void {
     if (!target.codes.has(code)) target.codes.set(code, meta);
   }
   if (src.unbounded) target.unbounded = true;
+  if (src.canThrowPlain) target.canThrowPlain = true;
 }
 
 function definitionFor(
@@ -173,7 +186,11 @@ function collectStepThrows(
   ctx: ResolveCtx,
 ): ThrowsUnion {
   if (step[invokeField]) {
-    return resolveStepInvokeThrows(step, invokeField, enclosingTryCodes, ctx);
+    // Any invoked resource can throw a non-InvokeError at runtime, which an
+    // enclosing catch surfaces as PLAIN_ERROR_CODE — record that possibility.
+    const u = cloneUnion(resolveStepInvokeThrows(step, invokeField, enclosingTryCodes, ctx));
+    u.canThrowPlain = true;
+    return u;
   }
 
   if (step.throw && typeof step.throw === "object") {
@@ -188,6 +205,10 @@ function collectStepThrows(
       // 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());
+      // A plain (non-InvokeError) failure in the try block reaches the catch as
+      // `error.code === PLAIN_ERROR_CODE`, so a `throw: { code: error.code }`
+      // rethrow can propagate it — seed the set the catch resolves against.
+      if (tryUnion.canThrowPlain) tryCodes.add(PLAIN_ERROR_CODE);
       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).
@@ -247,6 +268,7 @@ function cloneUnion(u: ThrowsUnion): ThrowsUnion {
   const out = emptyUnion();
   for (const [c, m] of u.codes) out.codes.set(c, m);
   out.unbounded = u.unbounded;
+  if (u.canThrowPlain) out.canThrowPlain = true;
   return out;
 }
 
@@ -316,16 +338,22 @@ function resolveCodeExpression(
   codeInput: unknown,
   enclosingTryCodes: Set<string> | undefined,
 ): ThrowsUnion {
-  if (typeof codeInput !== "string" || codeInput.length === 0) {
+  // A `!cel`-tagged sentinel and a `${{ … }}` string must resolve identically —
+  // normalize both to the inner CEL expression (or a bare literal code).
+  let expr: string;
+  if (isTaggedSentinel(codeInput)) {
+    if (codeInput.engine !== "cel") return { codes: new Map(), unbounded: true };
+    expr = codeInput.source.trim();
+  } else if (typeof codeInput === "string" && codeInput.length > 0) {
+    const match = codeInput.match(/^\s*\$\{\{\s*([\s\S]+?)\s*\}\}\s*$/);
+    if (!match) {
+      return { codes: new Map([[codeInput, {}]]), unbounded: false };
+    }
+    expr = match[1].trim();
+  } else {
     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]!;

package/src/schema-compat.ts

@@ -204,9 +204,29 @@ export function navigateSchemaToExprPath(
   return current;
 }
 
+/**
+ * Recognized `x-telo-type` value brands and the CEL primitive each refines.
+ * A brand is a nominal type the analyzer registers (see cel-environment.ts) so
+ * structurally-identical values (a `TcpPort` and a `UdpPort` are both integers)
+ * stay distinct for static wiring checks. Brands carry no runtime effect — the
+ * value flows as its base type. Add new brands here (e.g. `Url: "string"`).
+ */
+export const VALUE_BRAND_BASE: Record<string, string> = {
+  TcpPort: "int",
+  UdpPort: "int",
+};
+
+/** Read a recognized `x-telo-type` brand off a schema, or undefined. */
+export function brandOfSchema(schema: Record<string, any> | undefined): string | undefined {
+  const brand = schema?.["x-telo-type"];
+  return typeof brand === "string" && brand in VALUE_BRAND_BASE ? brand : undefined;
+}
+
 /** Map a JSON Schema type annotation to a CEL type string. */
 export function jsonSchemaToCelType(schema: Record<string, any> | undefined): string {
   if (!schema || typeof schema !== "object") return "dyn";
+  const brand = brandOfSchema(schema);
+  if (brand) return brand;
   if (schema.anyOf || schema.oneOf || schema.allOf) return "dyn";
   if (Array.isArray(schema.type)) return "dyn";
   switch (schema.type) {
@@ -233,6 +253,18 @@ export function jsonSchemaToCelType(schema: Record<string, any> | undefined): st
 /** Check whether a CEL return type is compatible with a JSON Schema type constraint. */
 export function celTypeSatisfiesJsonSchema(celType: string, schema: Record<string, any>): boolean {
   if (celType === "dyn") return true;
+  // Nominal value brands: when the expression's type is a recognized brand,
+  // a branded consuming field must match exactly (a UdpPort wired into a
+  // TcpPort-branded field is the error we want). An unbranded field accepts
+  // the brand as its base type — gradual typing, so a TcpPort flows freely
+  // into a plain integer field. (A plain integer into a branded field is also
+  // allowed: only a *conflicting* brand is rejected.)
+  const sourceBase = VALUE_BRAND_BASE[celType];
+  if (sourceBase) {
+    const fieldBrand = brandOfSchema(schema);
+    if (fieldBrand) return fieldBrand === celType;
+    celType = sourceBase;
+  }
   if (!schema.type && !schema.anyOf && !schema.oneOf && !schema.allOf) return true;
   if (schema.anyOf || schema.oneOf || schema.allOf) return true;
   const schemaTypes = Array.isArray(schema.type) ? schema.type : [schema.type];

package/src/validate-cel-context.ts

@@ -266,3 +266,53 @@ function navigatePath(obj: unknown, segments: string[]): unknown {
   }
   return cur;
 }
+
+/**
+ * Walk a JSON Schema tree and collect all `x-telo-context` annotations,
+ * returning them as `{ scope, schema }` pairs using JSONPath-style scopes —
+ * the same format the analyzer uses for CEL context validation.
+ *
+ * Result is sorted by scope specificity (longer scope first) so that the
+ * per-expression resolver's first-match-wins logic picks the most-specific
+ * context. Without this, a broader ancestor scope (e.g. `$.resources[*]`)
+ * could shadow a narrower descendant scope whose activation differs.
+ */
+export function extractContextsFromSchema(
+  schema: Record<string, any>,
+  path = "$",
+): Array<{ scope: string; schema: Record<string, any> }> {
+  const all = collectContexts(schema, path);
+  return all.sort((a, b) => b.scope.length - a.scope.length);
+}
+
+function collectContexts(
+  schema: Record<string, any>,
+  path: string,
+): Array<{ scope: string; schema: Record<string, any> }> {
+  if (!schema || typeof schema !== "object") return [];
+  const results: Array<{ scope: string; schema: Record<string, any> }> = [];
+
+  if (schema["x-telo-context"]) {
+    results.push({ scope: path, schema: schema["x-telo-context"] });
+  }
+
+  if (schema.properties) {
+    for (const [key, value] of Object.entries(schema.properties as Record<string, any>)) {
+      results.push(...collectContexts(value, `${path}.${key}`));
+    }
+  }
+
+  if (schema.items && typeof schema.items === "object") {
+    results.push(...collectContexts(schema.items, `${path}[*]`));
+  }
+
+  for (const key of ["oneOf", "anyOf", "allOf"] as const) {
+    if (Array.isArray(schema[key])) {
+      for (const subschema of schema[key]) {
+        results.push(...collectContexts(subschema, path));
+      }
+    }
+  }
+
+  return results;
+}