@telorun/templating 0.3.1 → 0.4.0

package/dist/cel/analyze.d.ts

@@ -10,6 +10,21 @@ export declare function extractAccessChains(node: ASTNode): string[][];
  *  member that can't be resolved to a static name. Consumers that attribute
  *  chains to declared names treat this as "unknown member". */
 export declare const INDEX_SEGMENT = "[*]";
+interface NullableIssue {
+    /** Dotted path of the nullable value being dereferenced (e.g. "error"). */
+    path: string;
+    /** The member accessed on it (e.g. "code", or "[index]"). */
+    member: string;
+}
+/**
+ * Find member accesses on a nullable value that are not null-guarded in the
+ * surrounding expression. A context field whose schema admits `null` (e.g. the
+ * `error` object inside a `finally` block, typed `["object", "null"]`) must be
+ * narrowed before its members are read. Recognised guards: `x == null` /
+ * `x != null` flowing through `?:` ternaries and `&&` / `||` short-circuits.
+ * Returns one issue per unguarded dereference.
+ */
+export declare function findNullableAccessIssues(node: ASTNode, contextSchema: Record<string, any>): NullableIssue[];
 /**
  * Check whether a member-access chain accesses only fields declared in a JSON Schema.
  * Returns an error string if a field is unknown in a schema that declares explicit
@@ -18,4 +33,5 @@ export declare const INDEX_SEGMENT = "[*]";
  * Returns null when the chain is valid or the schema is too open to judge.
  */
 export declare function validateChainAgainstSchema(chain: string[], schema: Record<string, any>): string | null;
+export {};
 //# sourceMappingURL=analyze.d.ts.map

package/dist/cel/analyze.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/cel/analyze.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,EAAE,CAI7D;AA0DD;;+DAE+D;AAC/D,eAAO,MAAM,aAAa,QAAQ,CAAC;AAqBnC;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EAAE,EACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,MAAM,GAAG,IAAI,CA2Bf"}
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/cel/analyze.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,EAAE,CAI7D;AA0DD;;+DAE+D;AAC/D,eAAO,MAAM,aAAa,QAAQ,CAAC;AAqBnC,UAAU,aAAa;IACrB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;CAChB;AAoFD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,OAAO,EACb,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACjC,aAAa,EAAE,CAIjB;AA2FD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,EAAE,EACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC1B,MAAM,GAAG,IAAI,CA2Bf"}

package/dist/cel/analyze.js

@@ -86,6 +86,170 @@ function extractChain(node, boundVars) {
     }
     return null;
 }
+/** True when a JSON Schema admits `null` — `type: "null"` or a union that
+ *  includes it (e.g. `["object", "null"]`). */
+function schemaIsNullable(schema) {
+    if (!schema || typeof schema !== "object")
+        return false;
+    const t = schema.type;
+    return t === "null" || (Array.isArray(t) && t.includes("null"));
+}
+/** Navigate `schema` following a member chain, descending through `properties`.
+ *  Returns the schema node at that path, or undefined when it can't be resolved. */
+function schemaAtChain(chain, schema) {
+    let current = schema;
+    for (const key of chain) {
+        if (!current || typeof current !== "object")
+            return undefined;
+        const props = current.properties;
+        if (!props || !(key in props))
+            return undefined;
+        current = props[key];
+    }
+    return current;
+}
+function isNullLiteral(node) {
+    return node.op === "value" && node.args === null;
+}
+/** Dotted form of a static member chain rooted at a free identifier, or null
+ *  when the node isn't such a chain (call result, bound var, index, …). */
+function dottedChain(node, boundVars) {
+    const chain = extractChain(node, boundVars);
+    if (chain === null || chain.includes(INDEX_SEGMENT))
+        return null;
+    return chain.join(".");
+}
+const EMPTY_NARROWING = { whenTrue: new Set(), whenFalse: new Set() };
+/** Derive which chains a boolean condition proves non-null in its true / false
+ *  branches. Handles `x == null` / `x != null`, negation, and `&&` / `||`. */
+function deriveNarrowing(node, boundVars) {
+    if (node.op === "==" || node.op === "!=") {
+        const [l, r] = node.args;
+        const chain = isNullLiteral(r)
+            ? dottedChain(l, boundVars)
+            : isNullLiteral(l)
+                ? dottedChain(r, boundVars)
+                : null;
+        if (chain === null)
+            return EMPTY_NARROWING;
+        const proven = new Set([chain]);
+        return node.op === "!="
+            ? { whenTrue: proven, whenFalse: new Set() }
+            : { whenTrue: new Set(), whenFalse: proven };
+    }
+    if (node.op === "!_") {
+        const inner = deriveNarrowing(node.args, boundVars);
+        return { whenTrue: inner.whenFalse, whenFalse: inner.whenTrue };
+    }
+    if (node.op === "&&") {
+        const [a, b] = node.args;
+        const na = deriveNarrowing(a, boundVars);
+        const nb = deriveNarrowing(b, boundVars);
+        return { whenTrue: union(na.whenTrue, nb.whenTrue), whenFalse: new Set() };
+    }
+    if (node.op === "||") {
+        const [a, b] = node.args;
+        const na = deriveNarrowing(a, boundVars);
+        const nb = deriveNarrowing(b, boundVars);
+        return { whenTrue: new Set(), whenFalse: union(na.whenFalse, nb.whenFalse) };
+    }
+    return EMPTY_NARROWING;
+}
+function union(a, b) {
+    return new Set([...a, ...b]);
+}
+/**
+ * Find member accesses on a nullable value that are not null-guarded in the
+ * surrounding expression. A context field whose schema admits `null` (e.g. the
+ * `error` object inside a `finally` block, typed `["object", "null"]`) must be
+ * narrowed before its members are read. Recognised guards: `x == null` /
+ * `x != null` flowing through `?:` ternaries and `&&` / `||` short-circuits.
+ * Returns one issue per unguarded dereference.
+ */
+export function findNullableAccessIssues(node, contextSchema) {
+    const issues = [];
+    walkNullable(node, new Set(), new Set(), issues, contextSchema);
+    return issues;
+}
+function walkNullable(node, nonNull, boundVars, issues, schema) {
+    // Dereference of an object/array member — check the receiver's nullability.
+    if (node.op === "." || node.op === "[]") {
+        const [obj, field] = node.args;
+        const objChain = dottedChain(obj, boundVars);
+        if (objChain !== null && !nonNull.has(objChain)) {
+            const objSchema = schemaAtChain(objChain.split("."), schema);
+            if (schemaIsNullable(objSchema)) {
+                issues.push({
+                    path: objChain,
+                    member: node.op === "." ? String(field) : "[index]",
+                });
+            }
+        }
+        walkNullable(obj, nonNull, boundVars, issues, schema);
+        // The index expression (`obj[expr]`) is itself evaluated — descend so a
+        // nullable deref used as an index (e.g. `items[error.code]`) is caught.
+        if (node.op === "[]" && isASTNode(field)) {
+            walkNullable(field, nonNull, boundVars, issues, schema);
+        }
+        return;
+    }
+    if (node.op === "?:") {
+        const [cond, thenB, elseB] = node.args;
+        walkNullable(cond, nonNull, boundVars, issues, schema);
+        const n = deriveNarrowing(cond, boundVars);
+        walkNullable(thenB, union(nonNull, n.whenTrue), boundVars, issues, schema);
+        walkNullable(elseB, union(nonNull, n.whenFalse), boundVars, issues, schema);
+        return;
+    }
+    if (node.op === "&&" || node.op === "||") {
+        const [a, b] = node.args;
+        walkNullable(a, nonNull, boundVars, issues, schema);
+        const n = deriveNarrowing(a, boundVars);
+        const carried = node.op === "&&" ? n.whenTrue : n.whenFalse;
+        walkNullable(b, union(nonNull, carried), boundVars, issues, schema);
+        return;
+    }
+    // Comprehension macros bind a loop variable; mirror extractAccessChains so a
+    // bound var is never mistaken for a nullable context field.
+    if (node.op === "rcall" &&
+        Array.isArray(node.args) &&
+        typeof node.args[0] === "string" &&
+        COMPREHENSION_METHODS.has(node.args[0])) {
+        const receiver = node.args[1];
+        const comprehensionArgs = node.args[2];
+        if (isASTNode(receiver))
+            walkNullable(receiver, nonNull, boundVars, issues, schema);
+        if (Array.isArray(comprehensionArgs) &&
+            comprehensionArgs.length >= 2 &&
+            isASTNode(comprehensionArgs[0]) &&
+            comprehensionArgs[0].op === "id") {
+            const inner = new Set(boundVars);
+            inner.add(comprehensionArgs[0].args);
+            for (let i = 1; i < comprehensionArgs.length; i++) {
+                const arg = comprehensionArgs[i];
+                if (isASTNode(arg))
+                    walkNullable(arg, nonNull, inner, issues, schema);
+            }
+        }
+        return;
+    }
+    const args = node.args;
+    if (Array.isArray(args)) {
+        for (const arg of args) {
+            if (isASTNode(arg))
+                walkNullable(arg, nonNull, boundVars, issues, schema);
+            else if (Array.isArray(arg)) {
+                for (const item of arg) {
+                    if (isASTNode(item))
+                        walkNullable(item, nonNull, boundVars, issues, schema);
+                }
+            }
+        }
+    }
+    else if (isASTNode(args)) {
+        walkNullable(args, nonNull, boundVars, issues, schema);
+    }
+}
 /**
  * Check whether a member-access chain accesses only fields declared in a JSON Schema.
  * Returns an error string if a field is unknown in a schema that declares explicit

package/dist/engines/cel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cel.d.ts","sourceRoot":"","sources":["../../src/engines/cel.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAoB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEvE;;;kDAGkD;AAClD,eAAO,MAAM,SAAS,EAAE,gBA+BvB,CAAC"}
+{"version":3,"file":"cel.d.ts","sourceRoot":"","sources":["../../src/engines/cel.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAoB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEvE;;;kDAGkD;AAClD,eAAO,MAAM,SAAS,EAAE,gBA4CvB,CAAC"}

package/dist/engines/cel.js

@@ -1,4 +1,4 @@
-import { extractAccessChains, validateChainAgainstSchema } from "../cel/analyze.js";
+import { extractAccessChains, findNullableAccessIssues, validateChainAgainstSchema, } from "../cel/analyze.js";
 import { compileExpression } from "../cel/compile.js";
 /** The `!cel` engine. Treats the entire tagged scalar as a single CEL
  *  expression — no `${{ }}` wrapping. Analysis runs the same chain validator
@@ -31,6 +31,15 @@ export const celEngine = {
             if (err)
                 out.push({ code: "CEL_UNKNOWN_FIELD", message: err });
         }
+        for (const issue of findNullableAccessIssues(parsed.ast, env.contextSchema)) {
+            // Index access (member "[index]") attaches without a dot; a named field
+            // attaches with one — so the suggested CEL stays valid either way.
+            const access = issue.member === "[index]" ? issue.member : `.${issue.member}`;
+            out.push({
+                code: "CEL_NULLABLE_ACCESS",
+                message: `'${issue.path}' may be null — guard it (e.g. '${issue.path} != null && …' or '${issue.path} == null ? … : ${issue.path}${access}') before accessing '${access}'`,
+            });
+        }
         return out;
     },
 };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { buildCelEnvironment, type CelHandlers } from "./cel/environment.js";
 export { compileExpression, compileString, TEMPLATE_REGEX, EXACT_TEMPLATE_REGEX, } from "./cel/compile.js";
-export { extractAccessChains, INDEX_SEGMENT, validateChainAgainstSchema } from "./cel/analyze.js";
+export { extractAccessChains, findNullableAccessIssues, INDEX_SEGMENT, validateChainAgainstSchema, } from "./cel/analyze.js";
 export { walkCelExpressions } from "./cel/walk.js";
 export { celEngine } from "./engines/cel.js";
 export { literalEngine } from "./engines/literal.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAClG,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACvF,YAAY,EACV,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACzG,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,aAAa,EACb,0BAA0B,GAC3B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACvF,YAAY,EACV,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACzG,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -1,6 +1,6 @@
 export { buildCelEnvironment } from "./cel/environment.js";
 export { compileExpression, compileString, TEMPLATE_REGEX, EXACT_TEMPLATE_REGEX, } from "./cel/compile.js";
-export { extractAccessChains, INDEX_SEGMENT, validateChainAgainstSchema } from "./cel/analyze.js";
+export { extractAccessChains, findNullableAccessIssues, INDEX_SEGMENT, validateChainAgainstSchema, } from "./cel/analyze.js";
 export { walkCelExpressions } from "./cel/walk.js";
 export { celEngine } from "./engines/cel.js";
 export { literalEngine } from "./engines/literal.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/templating",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Telo Templating - Engine registry and shared CEL core for Telo manifests.",
   "keywords": [
     "telo",
@@ -44,7 +44,7 @@
     "vitest": "^2.1.8"
   },
   "peerDependencies": {
-    "@telorun/sdk": "0.12.0"
+    "@telorun/sdk": "0.13.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.lib.json",

package/src/cel/analyze.ts

@@ -92,6 +92,201 @@ function extractChain(node: ASTNode, boundVars: Set<string>): string[] | null {
   return null;
 }
 
+interface NullableIssue {
+  /** Dotted path of the nullable value being dereferenced (e.g. "error"). */
+  path: string;
+  /** The member accessed on it (e.g. "code", or "[index]"). */
+  member: string;
+}
+
+/** True when a JSON Schema admits `null` — `type: "null"` or a union that
+ *  includes it (e.g. `["object", "null"]`). */
+function schemaIsNullable(schema: Record<string, any> | undefined): boolean {
+  if (!schema || typeof schema !== "object") return false;
+  const t = schema.type;
+  return t === "null" || (Array.isArray(t) && t.includes("null"));
+}
+
+/** Navigate `schema` following a member chain, descending through `properties`.
+ *  Returns the schema node at that path, or undefined when it can't be resolved. */
+function schemaAtChain(
+  chain: string[],
+  schema: Record<string, any>,
+): Record<string, any> | undefined {
+  let current: Record<string, any> | undefined = schema;
+  for (const key of chain) {
+    if (!current || typeof current !== "object") return undefined;
+    const props = current.properties as Record<string, any> | undefined;
+    if (!props || !(key in props)) return undefined;
+    current = props[key];
+  }
+  return current;
+}
+
+function isNullLiteral(node: ASTNode): boolean {
+  return node.op === "value" && (node.args as unknown) === null;
+}
+
+/** Dotted form of a static member chain rooted at a free identifier, or null
+ *  when the node isn't such a chain (call result, bound var, index, …). */
+function dottedChain(node: ASTNode, boundVars: Set<string>): string | null {
+  const chain = extractChain(node, boundVars);
+  if (chain === null || chain.includes(INDEX_SEGMENT)) return null;
+  return chain.join(".");
+}
+
+interface Narrowing {
+  whenTrue: Set<string>;
+  whenFalse: Set<string>;
+}
+
+const EMPTY_NARROWING: Narrowing = { whenTrue: new Set(), whenFalse: new Set() };
+
+/** Derive which chains a boolean condition proves non-null in its true / false
+ *  branches. Handles `x == null` / `x != null`, negation, and `&&` / `||`. */
+function deriveNarrowing(node: ASTNode, boundVars: Set<string>): Narrowing {
+  if (node.op === "==" || node.op === "!=") {
+    const [l, r] = node.args as [ASTNode, ASTNode];
+    const chain = isNullLiteral(r)
+      ? dottedChain(l, boundVars)
+      : isNullLiteral(l)
+        ? dottedChain(r, boundVars)
+        : null;
+    if (chain === null) return EMPTY_NARROWING;
+    const proven = new Set([chain]);
+    return node.op === "!="
+      ? { whenTrue: proven, whenFalse: new Set() }
+      : { whenTrue: new Set(), whenFalse: proven };
+  }
+  if (node.op === "!_") {
+    const inner = deriveNarrowing(node.args as ASTNode, boundVars);
+    return { whenTrue: inner.whenFalse, whenFalse: inner.whenTrue };
+  }
+  if (node.op === "&&") {
+    const [a, b] = node.args as [ASTNode, ASTNode];
+    const na = deriveNarrowing(a, boundVars);
+    const nb = deriveNarrowing(b, boundVars);
+    return { whenTrue: union(na.whenTrue, nb.whenTrue), whenFalse: new Set() };
+  }
+  if (node.op === "||") {
+    const [a, b] = node.args as [ASTNode, ASTNode];
+    const na = deriveNarrowing(a, boundVars);
+    const nb = deriveNarrowing(b, boundVars);
+    return { whenTrue: new Set(), whenFalse: union(na.whenFalse, nb.whenFalse) };
+  }
+  return EMPTY_NARROWING;
+}
+
+function union(a: Set<string>, b: Set<string>): Set<string> {
+  return new Set([...a, ...b]);
+}
+
+/**
+ * Find member accesses on a nullable value that are not null-guarded in the
+ * surrounding expression. A context field whose schema admits `null` (e.g. the
+ * `error` object inside a `finally` block, typed `["object", "null"]`) must be
+ * narrowed before its members are read. Recognised guards: `x == null` /
+ * `x != null` flowing through `?:` ternaries and `&&` / `||` short-circuits.
+ * Returns one issue per unguarded dereference.
+ */
+export function findNullableAccessIssues(
+  node: ASTNode,
+  contextSchema: Record<string, any>,
+): NullableIssue[] {
+  const issues: NullableIssue[] = [];
+  walkNullable(node, new Set(), new Set(), issues, contextSchema);
+  return issues;
+}
+
+function walkNullable(
+  node: ASTNode,
+  nonNull: Set<string>,
+  boundVars: Set<string>,
+  issues: NullableIssue[],
+  schema: Record<string, any>,
+): void {
+  // Dereference of an object/array member — check the receiver's nullability.
+  if (node.op === "." || node.op === "[]") {
+    const [obj, field] = node.args as [ASTNode, unknown];
+    const objChain = dottedChain(obj, boundVars);
+    if (objChain !== null && !nonNull.has(objChain)) {
+      const objSchema = schemaAtChain(objChain.split("."), schema);
+      if (schemaIsNullable(objSchema)) {
+        issues.push({
+          path: objChain,
+          member: node.op === "." ? String(field) : "[index]",
+        });
+      }
+    }
+    walkNullable(obj, nonNull, boundVars, issues, schema);
+    // The index expression (`obj[expr]`) is itself evaluated — descend so a
+    // nullable deref used as an index (e.g. `items[error.code]`) is caught.
+    if (node.op === "[]" && isASTNode(field)) {
+      walkNullable(field as ASTNode, nonNull, boundVars, issues, schema);
+    }
+    return;
+  }
+
+  if (node.op === "?:") {
+    const [cond, thenB, elseB] = node.args as [ASTNode, ASTNode, ASTNode];
+    walkNullable(cond, nonNull, boundVars, issues, schema);
+    const n = deriveNarrowing(cond, boundVars);
+    walkNullable(thenB, union(nonNull, n.whenTrue), boundVars, issues, schema);
+    walkNullable(elseB, union(nonNull, n.whenFalse), boundVars, issues, schema);
+    return;
+  }
+
+  if (node.op === "&&" || node.op === "||") {
+    const [a, b] = node.args as [ASTNode, ASTNode];
+    walkNullable(a, nonNull, boundVars, issues, schema);
+    const n = deriveNarrowing(a, boundVars);
+    const carried = node.op === "&&" ? n.whenTrue : n.whenFalse;
+    walkNullable(b, union(nonNull, carried), boundVars, issues, schema);
+    return;
+  }
+
+  // Comprehension macros bind a loop variable; mirror extractAccessChains so a
+  // bound var is never mistaken for a nullable context field.
+  if (
+    node.op === "rcall" &&
+    Array.isArray(node.args) &&
+    typeof node.args[0] === "string" &&
+    COMPREHENSION_METHODS.has(node.args[0])
+  ) {
+    const receiver = node.args[1];
+    const comprehensionArgs = node.args[2];
+    if (isASTNode(receiver)) walkNullable(receiver, nonNull, boundVars, issues, schema);
+    if (
+      Array.isArray(comprehensionArgs) &&
+      comprehensionArgs.length >= 2 &&
+      isASTNode(comprehensionArgs[0]) &&
+      (comprehensionArgs[0] as ASTNode).op === "id"
+    ) {
+      const inner = new Set(boundVars);
+      inner.add((comprehensionArgs[0] as ASTNode).args as string);
+      for (let i = 1; i < comprehensionArgs.length; i++) {
+        const arg = comprehensionArgs[i];
+        if (isASTNode(arg)) walkNullable(arg as ASTNode, nonNull, inner, issues, schema);
+      }
+    }
+    return;
+  }
+
+  const args = node.args;
+  if (Array.isArray(args)) {
+    for (const arg of args) {
+      if (isASTNode(arg)) walkNullable(arg, nonNull, boundVars, issues, schema);
+      else if (Array.isArray(arg)) {
+        for (const item of arg) {
+          if (isASTNode(item)) walkNullable(item, nonNull, boundVars, issues, schema);
+        }
+      }
+    }
+  } else if (isASTNode(args)) {
+    walkNullable(args, nonNull, boundVars, issues, schema);
+  }
+}
+
 /**
  * Check whether a member-access chain accesses only fields declared in a JSON Schema.
  * Returns an error string if a field is unknown in a schema that declares explicit

package/src/engines/cel.ts

@@ -1,4 +1,8 @@
-import { extractAccessChains, validateChainAgainstSchema } from "../cel/analyze.js";
+import {
+  extractAccessChains,
+  findNullableAccessIssues,
+  validateChainAgainstSchema,
+} from "../cel/analyze.js";
 import { compileExpression } from "../cel/compile.js";
 import type { EngineDiagnostic, TemplatingEngine } from "../engine.js";
 
@@ -35,6 +39,19 @@ export const celEngine: TemplatingEngine = {
       const err = validateChainAgainstSchema(chain, env.contextSchema as Record<string, any>);
       if (err) out.push({ code: "CEL_UNKNOWN_FIELD", message: err });
     }
+
+    for (const issue of findNullableAccessIssues(
+      parsed.ast,
+      env.contextSchema as Record<string, any>,
+    )) {
+      // Index access (member "[index]") attaches without a dot; a named field
+      // attaches with one — so the suggested CEL stays valid either way.
+      const access = issue.member === "[index]" ? issue.member : `.${issue.member}`;
+      out.push({
+        code: "CEL_NULLABLE_ACCESS",
+        message: `'${issue.path}' may be null — guard it (e.g. '${issue.path} != null && …' or '${issue.path} == null ? … : ${issue.path}${access}') before accessing '${access}'`,
+      });
+    }
     return out;
   },
 };

package/src/index.ts

@@ -5,7 +5,12 @@ export {
   TEMPLATE_REGEX,
   EXACT_TEMPLATE_REGEX,
 } from "./cel/compile.js";
-export { extractAccessChains, INDEX_SEGMENT, validateChainAgainstSchema } from "./cel/analyze.js";
+export {
+  extractAccessChains,
+  findNullableAccessIssues,
+  INDEX_SEGMENT,
+  validateChainAgainstSchema,
+} from "./cel/analyze.js";
 export { walkCelExpressions } from "./cel/walk.js";
 
 export { celEngine } from "./engines/cel.js";