@telorun/analyzer 0.23.1 → 0.24.0

package/dist/normalize-inline-resources.d.ts

@@ -15,8 +15,9 @@ import type { AliasResolver } from "./alias-resolver.js";
  *   e.g. TestBasicAddition_steps_AddTwoNumbers_invoke
  *        TestBasicAddition_steps_0_invoke  (when step has no name)
  *
- * Returns a new array containing the original manifests (mutated in-place) plus all
- * extracted manifests. The original array is not mutated.
+ * Returns a new array of deep-cloned manifests (the rewrites land on the clones)
+ * plus all extracted manifests. The caller's manifests — array and elements — are
+ * never mutated; this is the analyzer's immutability boundary.
  */
 export declare function normalizeInlineResources(resources: ResourceManifest[], registry: DefinitionRegistry, aliases?: AliasResolver, aliasesByModule?: Map<string, AliasResolver>): ResourceManifest[];
 //# sourceMappingURL=normalize-inline-resources.d.ts.map

package/dist/normalize-inline-resources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"normalize-inline-resources.d.ts","sourceRoot":"","sources":["../src/normalize-inline-resources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAczD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC3C,gBAAgB,EAAE,CA+DpB"}
+{"version":3,"file":"normalize-inline-resources.d.ts","sourceRoot":"","sources":["../src/normalize-inline-resources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AA8BzD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,CAAC,EAAE,aAAa,EACvB,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC3C,gBAAgB,EAAE,CAsEpB"}

package/dist/normalize-inline-resources.js

@@ -9,6 +9,24 @@ const SYSTEM_KINDS = new Set([
 function sanitizeName(raw) {
     return raw.replace(/[^a-zA-Z0-9_]/g, "_");
 }
+/** Deep-clones a manifest value tree so the in-place rewrites this module and
+ *  `resolveRefSentinels` perform never reach caller-owned objects. Compiled-CEL
+ *  nodes (`{__compiled, source, call?}`) are opaque leaves carrying functions —
+ *  copied by reference, never descended into — matching how `resolveRefSentinels`
+ *  and `manifest-visitor` short-circuit on `__compiled`. */
+function cloneForMutation(value) {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (value.__compiled)
+        return value;
+    if (Array.isArray(value))
+        return value.map(cloneForMutation);
+    const out = {};
+    for (const key of Object.keys(value)) {
+        out[key] = cloneForMutation(value[key]);
+    }
+    return out;
+}
 /**
  * Phase 2 — Inline resource normalization.
  *
@@ -23,13 +41,21 @@ function sanitizeName(raw) {
  *   e.g. TestBasicAddition_steps_AddTwoNumbers_invoke
  *        TestBasicAddition_steps_0_invoke  (when step has no name)
  *
- * Returns a new array containing the original manifests (mutated in-place) plus all
- * extracted manifests. The original array is not mutated.
+ * Returns a new array of deep-cloned manifests (the rewrites land on the clones)
+ * plus all extracted manifests. The caller's manifests — array and elements — are
+ * never mutated; this is the analyzer's immutability boundary.
  */
 export function normalizeInlineResources(resources, registry, aliases, aliasesByModule) {
-    const result = [...resources];
+    // Deep-clone the input so this pass — and `resolveRefSentinels`, which runs on
+    // this output — never mutate caller-owned manifests. `extractInlinesAtPath`
+    // rewrites inline ref slots in place, so without cloning we'd corrupt shared
+    // state such as the editor's `LoadedFile.manifests` parse cache (a reused
+    // sentinel would be rewritten to `{kind, name}`, later misread as an authored
+    // reference form). The clone is the analyzer's immutability boundary.
+    const result = resources.map(cloneForMutation);
     // Queue: all non-system resources with a name. Extracted resources are appended.
-    const queue = resources.filter((r) => typeof r.metadata?.name === "string" && !!r.kind && !SYSTEM_KINDS.has(r.kind));
+    // Filter the CLONES (not the originals) so traversal mutates copies.
+    const queue = result.filter((r) => typeof r.metadata?.name === "string" && !!r.kind && !SYSTEM_KINDS.has(r.kind));
     let i = 0;
     while (i < queue.length) {
         const resource = queue[i++];

package/dist/validate-cel-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-cel-context.d.ts","sourceRoot":"","sources":["../src/validate-cel-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAEtF,MAAM,WAAW,kBAAkB;IACjC;mEAC+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC;;kDAE8C;IAC9C,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;KACxD,CAAC;IACF,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;KAC/C,CAAC;IACF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CACtC;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAClC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAkCjC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAoBzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,IAAI,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAChD,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAqGrB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAQrB;AAWD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,SAAM,GACT,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,CAAC,CAGvD"}
+{"version":3,"file":"validate-cel-context.d.ts","sourceRoot":"","sources":["../src/validate-cel-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAEtF,MAAM,WAAW,kBAAkB;IACjC;mEAC+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACnC;;kDAE8C;IAC9C,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;KACxD,CAAC;IACF,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;KAC/C,CAAC;IACF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;CACtC;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAClC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAkCjC;AA6DD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAoBzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,IAAI,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,GAChD,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAgHrB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAQrB;AAWD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,IAAI,SAAM,GACT,KAAK,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAAE,CAAC,CAGvD"}

package/dist/validate-cel-context.js

@@ -35,6 +35,63 @@ export function resolveTypeFieldToSchema(value, allManifests) {
     }
     return undefined;
 }
+/** Pull the raw expression source from a CEL field value — a compiled value
+ *  (`{ source }`), or a string (`!cel "x"` or `"${{ x }}"`). Strips a lone
+ *  `${{ }}` wrapper. Returns null when no source is recoverable. */
+function celExprSource(raw) {
+    let s;
+    if (typeof raw === "string")
+        s = raw;
+    else if (raw && typeof raw === "object" && typeof raw.source === "string")
+        s = raw.source;
+    if (s == null)
+        return null;
+    const exact = s.match(/^\s*\$\{\{\s*([^}]+?)\s*\}\}\s*$/);
+    return (exact ? exact[1] : s).trim();
+}
+/** Member-access chain for a bare dotted-identifier expression
+ *  (`inputs.user.tags` → ["inputs","user","tags"]). Returns null for anything
+ *  else (literals, calls, indexing, comprehensions) — those are not statically
+ *  reducible to a single typed path. */
+function purePathChain(raw) {
+    const expr = celExprSource(raw);
+    if (expr == null)
+        return null;
+    if (!/^[A-Za-z_]\w*(\.[A-Za-z_]\w*)*$/.test(expr))
+        return null;
+    return expr.split(".");
+}
+/** Walk a member-access chain through a JSON Schema (descending `properties`)
+ *  and return the terminal node, or undefined when the path leaves typed schema. */
+function schemaAtChain(chain, root) {
+    let cur = root;
+    for (const key of chain) {
+        if (!cur || typeof cur !== "object")
+            return undefined;
+        const props = cur.properties;
+        if (!props || !(key in props))
+            return undefined;
+        cur = props[key];
+    }
+    return cur && typeof cur === "object" ? cur : undefined;
+}
+/** The element schema of a sibling collection expression, when statically known.
+ *  Resolves `inputs.*` chains against the resource's `inputs:` contract and
+ *  returns the array's `items`. Returns undefined for non-chain or untyped
+ *  collections (caller substitutes `dyn`). */
+function resolveCollectionElementSchema(manifestRoot, field) {
+    const chain = purePathChain(manifestRoot?.[field]);
+    if (!chain || chain[0] !== "inputs")
+        return undefined;
+    const contract = manifestRoot.inputs;
+    if (!contract || typeof contract !== "object")
+        return undefined;
+    const terminal = schemaAtChain(chain.slice(1), { type: "object", properties: contract });
+    if (terminal && terminal.type === "array" && terminal.items && typeof terminal.items === "object") {
+        return terminal.items;
+    }
+    return undefined;
+}
 /**
  * Returns true when a CEL expression path (from walkCelExpressions, e.g. "routes[0].inputs.q")
  * falls within the scope of a context (e.g. "$.routes[*].inputs").
@@ -131,6 +188,16 @@ export function resolveContextAnnotations(schema, manifestItem, opts) {
             additionalProperties: false,
         };
     }
+    // Element typing: derive a variable's schema from the element type of a sibling
+    // collection expression (e.g. `item` from `collection`). Resolves only when the
+    // collection is a member-access chain into the resource's typed `inputs` contract
+    // (the common, statically-knowable case); list literals, comprehensions, and
+    // untyped sources fall back to `dyn` so a wrong element type is never invented.
+    const elementFrom = schema["x-telo-context-element-from"];
+    if (elementFrom) {
+        const items = resolveCollectionElementSchema(manifestRoot, elementFrom);
+        return items ?? {};
+    }
     const fromRoot = schema["x-telo-context-from-root"];
     const fromRefKindRaw = schema["x-telo-context-from-ref-kind"];
     const fromRefKinds = fromRefKindRaw == null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.23.1",
+  "version": "0.24.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -42,7 +42,7 @@
     "ajv-formats": "^3.0.1",
     "jsonpath-plus": "^10.3.0",
     "yaml": "^2.8.3",
-    "@telorun/templating": "0.8.0"
+    "@telorun/templating": "0.9.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/normalize-inline-resources.ts

@@ -15,6 +15,22 @@ function sanitizeName(raw: string): string {
   return raw.replace(/[^a-zA-Z0-9_]/g, "_");
 }
 
+/** Deep-clones a manifest value tree so the in-place rewrites this module and
+ *  `resolveRefSentinels` perform never reach caller-owned objects. Compiled-CEL
+ *  nodes (`{__compiled, source, call?}`) are opaque leaves carrying functions —
+ *  copied by reference, never descended into — matching how `resolveRefSentinels`
+ *  and `manifest-visitor` short-circuit on `__compiled`. */
+function cloneForMutation(value: unknown): unknown {
+  if (value === null || typeof value !== "object") return value;
+  if ((value as { __compiled?: unknown }).__compiled) return value;
+  if (Array.isArray(value)) return value.map(cloneForMutation);
+  const out: Record<string, unknown> = {};
+  for (const key of Object.keys(value)) {
+    out[key] = cloneForMutation((value as Record<string, unknown>)[key]);
+  }
+  return out;
+}
+
 /**
  * Phase 2 — Inline resource normalization.
  *
@@ -29,8 +45,9 @@ function sanitizeName(raw: string): string {
  *   e.g. TestBasicAddition_steps_AddTwoNumbers_invoke
  *        TestBasicAddition_steps_0_invoke  (when step has no name)
  *
- * Returns a new array containing the original manifests (mutated in-place) plus all
- * extracted manifests. The original array is not mutated.
+ * Returns a new array of deep-cloned manifests (the rewrites land on the clones)
+ * plus all extracted manifests. The caller's manifests — array and elements — are
+ * never mutated; this is the analyzer's immutability boundary.
  */
 export function normalizeInlineResources(
   resources: ResourceManifest[],
@@ -38,10 +55,17 @@ export function normalizeInlineResources(
   aliases?: AliasResolver,
   aliasesByModule?: Map<string, AliasResolver>,
 ): ResourceManifest[] {
-  const result = [...resources];
+  // Deep-clone the input so this pass — and `resolveRefSentinels`, which runs on
+  // this output — never mutate caller-owned manifests. `extractInlinesAtPath`
+  // rewrites inline ref slots in place, so without cloning we'd corrupt shared
+  // state such as the editor's `LoadedFile.manifests` parse cache (a reused
+  // sentinel would be rewritten to `{kind, name}`, later misread as an authored
+  // reference form). The clone is the analyzer's immutability boundary.
+  const result = resources.map(cloneForMutation) as ResourceManifest[];
 
   // Queue: all non-system resources with a name. Extracted resources are appended.
-  const queue = resources.filter(
+  // Filter the CLONES (not the originals) so traversal mutates copies.
+  const queue = result.filter(
     (r): r is ResourceManifest & { metadata: { name: string } } =>
       typeof r.metadata?.name === "string" && !!r.kind && !SYSTEM_KINDS.has(r.kind),
   );

package/src/validate-cel-context.ts

@@ -61,6 +61,65 @@ export function resolveTypeFieldToSchema(
   return undefined;
 }
 
+/** Pull the raw expression source from a CEL field value — a compiled value
+ *  (`{ source }`), or a string (`!cel "x"` or `"${{ x }}"`). Strips a lone
+ *  `${{ }}` wrapper. Returns null when no source is recoverable. */
+function celExprSource(raw: unknown): string | null {
+  let s: string | undefined;
+  if (typeof raw === "string") s = raw;
+  else if (raw && typeof raw === "object" && typeof (raw as Record<string, any>).source === "string")
+    s = (raw as Record<string, any>).source;
+  if (s == null) return null;
+  const exact = s.match(/^\s*\$\{\{\s*([^}]+?)\s*\}\}\s*$/);
+  return (exact ? exact[1] : s).trim();
+}
+
+/** Member-access chain for a bare dotted-identifier expression
+ *  (`inputs.user.tags` → ["inputs","user","tags"]). Returns null for anything
+ *  else (literals, calls, indexing, comprehensions) — those are not statically
+ *  reducible to a single typed path. */
+function purePathChain(raw: unknown): string[] | null {
+  const expr = celExprSource(raw);
+  if (expr == null) return null;
+  if (!/^[A-Za-z_]\w*(\.[A-Za-z_]\w*)*$/.test(expr)) return null;
+  return expr.split(".");
+}
+
+/** Walk a member-access chain through a JSON Schema (descending `properties`)
+ *  and return the terminal node, or undefined when the path leaves typed schema. */
+function schemaAtChain(
+  chain: string[],
+  root: Record<string, any>,
+): Record<string, any> | undefined {
+  let cur: Record<string, any> | undefined = root;
+  for (const key of chain) {
+    if (!cur || typeof cur !== "object") return undefined;
+    const props = cur.properties as Record<string, any> | undefined;
+    if (!props || !(key in props)) return undefined;
+    cur = props[key] as Record<string, any>;
+  }
+  return cur && typeof cur === "object" ? cur : undefined;
+}
+
+/** The element schema of a sibling collection expression, when statically known.
+ *  Resolves `inputs.*` chains against the resource's `inputs:` contract and
+ *  returns the array's `items`. Returns undefined for non-chain or untyped
+ *  collections (caller substitutes `dyn`). */
+function resolveCollectionElementSchema(
+  manifestRoot: Record<string, any>,
+  field: string,
+): Record<string, any> | undefined {
+  const chain = purePathChain(manifestRoot?.[field]);
+  if (!chain || chain[0] !== "inputs") return undefined;
+  const contract = manifestRoot.inputs;
+  if (!contract || typeof contract !== "object") return undefined;
+  const terminal = schemaAtChain(chain.slice(1), { type: "object", properties: contract });
+  if (terminal && terminal.type === "array" && terminal.items && typeof terminal.items === "object") {
+    return terminal.items as Record<string, any>;
+  }
+  return undefined;
+}
+
 /**
  * Returns true when a CEL expression path (from walkCelExpressions, e.g. "routes[0].inputs.q")
  * falls within the scope of a context (e.g. "$.routes[*].inputs").
@@ -162,6 +221,17 @@ export function resolveContextAnnotations(
     };
   }
 
+  // Element typing: derive a variable's schema from the element type of a sibling
+  // collection expression (e.g. `item` from `collection`). Resolves only when the
+  // collection is a member-access chain into the resource's typed `inputs` contract
+  // (the common, statically-knowable case); list literals, comprehensions, and
+  // untyped sources fall back to `dyn` so a wrong element type is never invented.
+  const elementFrom = schema["x-telo-context-element-from"] as string | undefined;
+  if (elementFrom) {
+    const items = resolveCollectionElementSchema(manifestRoot, elementFrom);
+    return items ?? {};
+  }
+
   const fromRoot = schema["x-telo-context-from-root"] as string | undefined;
   const fromRefKindRaw = schema["x-telo-context-from-ref-kind"] as
     | string