okengine 0.21.1 → 0.22.0

package/src/compiler/effects-infer.ts

@@ -73,6 +73,12 @@ export interface InferBinding {
   readonly version?: number;
 }
 
+/** What a callee that is passed `fx` resolves to. */
+export type FxCalleeResolution =
+  | { readonly kind: "function"; readonly fn: AstNode; readonly file?: string }
+  | { readonly kind: "intrinsic"; readonly name: "liveQuery" | "applySearchEmbedCdc" }
+  | { readonly kind: "unresolved"; readonly label: string };
+
 /** Options for {@link inferEffects}. */
 export interface InferEffectsOptions {
   /** The `do` handler AST node (function / arrow). */
@@ -81,9 +87,25 @@ export interface InferEffectsOptions {
   readonly bindings: ReadonlyMap<string, InferBinding>;
   /**
    * True when the flow options already declare an `effects` object.
-   * Required for `fx.raw` to stay cache-eligible.
+   * Required for `fx.raw` to stay cache-eligible. Opaque `fx` (a renamed
+   * parameter, an escaped chain alias, an unresolved callee) is allowed
+   * only when this is set; the declared set must still cover every effect
+   * the walk can see.
    */
   readonly hasExplicitEffects: boolean;
+  /** Manifest flow name, used in OKE1900. */
+  readonly flowName?: string;
+  /**
+   * Resolve a callee in the flow's file. Absent only for unit tests that
+   * never pass `fx` into another function.
+   */
+  /** File that contains `do`, so imported helpers resolve from there. */
+  readonly file?: string;
+  /**
+   * Resolve a callee as seen from `file`. Absent only for unit tests that
+   * never pass `fx` into another function.
+   */
+  readonly resolveCallee?: (callee: AstNode, file: string) => FxCalleeResolution;
 }
 
 /** Result of effect inference for one flow body. */
@@ -171,10 +193,15 @@ export function inferEffects(options: InferEffectsOptions): InferredEffects {
   const steps: string[] = [];
   let usesRaw = false;
 
-  for (const call of collectCallExpressions(options.doNode)) {
-    const chain = fxMemberChain(call);
-    if (!chain) continue;
+  const opaque: string[] = [];
+  const userIdRoots: AstNode[] = [options.doNode];
+  const intrinsics: Array<{
+    name: "liveQuery" | "applySearchEmbedCdc";
+    call: CallExpression;
+  }> = [];
+  const chains = collectFxChains(options, opaque, userIdRoots, intrinsics);
 
+  for (const { call, chain } of chains) {
     if (chain.rootMethod === "raw") {
       usesRaw = true;
       continue;
@@ -301,14 +328,14 @@ export function inferEffects(options: InferEffectsOptions): InferredEffects {
     }
 
     if (chain.rootMethod === "store") {
-      const resolved = storeResourceFromCall(call, options.bindings);
+      const resolved = storeResourceFromCall(call, options.bindings, chain);
       if (!resolved) continue;
       const op = classifyStoreMethods(resolved.methods);
       if (op === "none") continue;
       // Skip incomplete chains (`select` before `.from`, `insert` before table) —
       // the sibling call that carries the table arg records the real resource.
       const leaf = resolved.methods[resolved.methods.length - 1]!;
-      const hasTable = tableFromStoreChain(call, options.bindings) !== undefined;
+      const hasTable = tableFromStoreChain(call, options.bindings, chain) !== undefined;
       if (!hasTable && (leaf === "select" || leaf === "insert" || leaf === "update")) {
         continue;
       }
@@ -323,6 +350,20 @@ export function inferEffects(options: InferEffectsOptions): InferredEffects {
     }
   }
 
+  for (const item of intrinsics) {
+    noteIntrinsic(item.name, item.call, options.bindings, reads, writes, embeds, (detail) => {
+      opaque.push(detail);
+    });
+  }
+
+  if (opaque.length > 0 && !options.hasExplicitEffects) {
+    const flow = options.flowName ?? "flow";
+    const detail = opaque[0] ?? "hides fx from effect inference";
+    throw new Error(
+      `OKE1900: flow "${flow}" ${detail}. Name the parameter fx and keep chain aliases in the same function, or declare effects that include every effect inference can see.`,
+    );
+  }
+
   const effects: Effects = {};
   if (reads.size > 0) effects.reads = sortUnique([...reads]);
   if (writes.size > 0) effects.writes = sortUnique([...writes]);
@@ -340,10 +381,42 @@ export function inferEffects(options: InferEffectsOptions): InferredEffects {
     usesRaw,
     cacheIneligible: usesRaw && !options.hasExplicitEffects,
     nondeterministic: asks.size > 0 || embeds.size > 0,
-    readsUserId: containsAuthUserId(options.doNode),
+    readsUserId: userIdRoots.some((node) => containsAuthUserId(node)),
   };
 }
 
+const EFFECT_KEYS = [
+  "reads",
+  "writes",
+  "emits",
+  "sends",
+  "asks",
+  "embeds",
+  "secrets",
+  "calls",
+  "fetches",
+] as const satisfies readonly (keyof Effects)[];
+
+/**
+ * Keys in `inferred` that `declared` does not include.
+ *
+ * An explicit `effects` object is a floor: it may add keys inference
+ * cannot see, and it must include every key the walk can see.
+ *
+ * @param declared - Author-declared effects
+ * @param inferred - Effects the walk can see
+ */
+export function effectsMissingFromDeclaration(declared: Effects, inferred: Effects): string[] {
+  const missing: string[] = [];
+  for (const key of EFFECT_KEYS) {
+    const have = new Set<string>(declared[key] ?? []);
+    for (const item of inferred[key] ?? []) {
+      if (!have.has(item)) missing.push(`${key} ${item}`);
+    }
+  }
+  return missing;
+}
+
 /**
  * Walk an AST and collect every CallExpression.
  *
@@ -380,6 +453,8 @@ interface FxChain {
   rootMethod: string;
   methods: string[];
   rootCall: CallExpression;
+  /** Outermost call of an alias init, when the continuation is a later statement. */
+  aliasLeaf?: CallExpression;
 }
 
 /**
@@ -451,15 +526,16 @@ export function fxMemberChain(call: CallExpression): FxChain | null {
 export function storeResourceFromCall(
   call: CallExpression,
   bindings: ReadonlyMap<string, InferBinding>,
+  known?: FxChain,
 ): { resource: ResourceRef; methods: string[] } | undefined {
-  const chain = fxMemberChain(call);
+  const chain = known ?? fxMemberChain(call);
   if (!chain || chain.rootMethod !== "store") return undefined;
 
   const storeArg = chain.rootCall.arguments[0];
   const storeBinding = resolveBinding(storeArg, bindings);
   const facet = storeBinding?.facet ?? "sql";
 
-  const table = tableFromStoreChain(call, bindings);
+  const table = tableFromStoreChain(call, bindings, chain);
 
   if (table) {
     return {
@@ -506,18 +582,36 @@ export function storeResourceFromCall(
 function tableFromStoreChain(
   call: CallExpression,
   bindings: ReadonlyMap<string, InferBinding>,
+  chain?: FxChain,
+): string | undefined {
+  const found = tableFromStoreWalk(call, bindings, chain);
+  if (found) return found;
+  if (chain?.aliasLeaf && chain.aliasLeaf !== call) {
+    return tableFromStoreWalk(chain.aliasLeaf, bindings);
+  }
+  return undefined;
+}
+
+function tableFromStoreWalk(
+  call: CallExpression,
+  bindings: ReadonlyMap<string, InferBinding>,
+  chain?: FxChain,
 ): string | undefined {
   let current: AstNode | undefined = call;
-  while (current && current.type === "CallExpression") {
+  const seen = new Set<AstNode>();
+  while (current && current.type === "CallExpression" && !seen.has(current)) {
+    seen.add(current);
     const c = current as CallExpression;
-    const link = fxMemberChain(c);
-    if (!link || link.rootMethod !== "store") break;
-    const leaf = link.methods[link.methods.length - 1]!;
+    const link = chain ? undefined : fxMemberChain(c);
+    if (!chain && (!link || link.rootMethod !== "store")) break;
+    const leaf = chain ? methodNameOfCall(c) : link?.methods[link.methods.length - 1];
+    if (!leaf) break;
     if (TABLE_ARG_METHODS.has(leaf)) {
       // KV / files / index take a key, not a table. Treating `delete(key)` as
       // `delete(table)` stamps `kv:key` instead of `kv:drafts` and the runtime
       // then throws OKE1002 on the real namespace.
-      const storeBinding = resolveBinding(link.rootCall.arguments[0], bindings);
+      const storeArg = chain?.rootCall.arguments[0] ?? link?.rootCall.arguments[0];
+      const storeBinding = resolveBinding(storeArg, bindings);
       if (storeBinding?.facet !== undefined && storeBinding.facet !== "sql") {
         // keep walking — no table on this link
       } else {
@@ -530,14 +624,24 @@ function tableFromStoreChain(
     }
     const callee = c.callee;
     if (callee.type === "MemberExpression") {
-      current = (callee as AstNode & { object: AstNode }).object;
-      continue;
+      const obj = (callee as AstNode & { object: AstNode }).object;
+      if (obj.type === "CallExpression") {
+        current = obj;
+        continue;
+      }
     }
     break;
   }
   return undefined;
 }
 
+function methodNameOfCall(call: CallExpression): string | undefined {
+  const callee = call.callee;
+  if (callee.type !== "MemberExpression") return undefined;
+  const property = (callee as AstNode & { property?: AstNode }).property;
+  return identifierName(property);
+}
+
 function classifyStoreMethods(methods: string[]): "read" | "write" | "both" | "none" {
   const ops = methods.slice(1);
   let read = false;
@@ -751,3 +855,609 @@ function containsAuthUserId(root: AstNode): boolean {
   });
   return found;
 }
+
+interface ChainAlias {
+  readonly methods: readonly string[];
+  readonly rootMethod: string;
+  readonly rootCall: CallExpression;
+  readonly leafCall: CallExpression;
+}
+
+interface ChainHit {
+  readonly call: CallExpression;
+  readonly chain: FxChain;
+}
+
+const VALUE_WRAPPERS = new Set([
+  "ParenthesizedExpression",
+  "TSAsExpression",
+  "TSTypeAssertion",
+  "TSSatisfiesExpression",
+  "TSNonNullExpression",
+  "AwaitExpression",
+]);
+
+function collectFxChains(
+  options: InferEffectsOptions,
+  opaque: string[],
+  userIdRoots: AstNode[],
+  intrinsics: Array<{ name: "liveQuery" | "applySearchEmbedCdc"; call: CallExpression }>,
+): ChainHit[] {
+  const hits: ChainHit[] = [];
+  const seen = new Set<AstNode>();
+
+  const follow = (
+    fn: AstNode,
+    file: string,
+    aliases: ReadonlyMap<string, ChainAlias>,
+    locals: ReadonlyMap<string, AstNode>,
+  ): void => {
+    analyzeFunction(fn, "fx", aliases, locals, file);
+  };
+
+  const analyzeFunction = (
+    fn: AstNode,
+    door: string,
+    outerAliases: ReadonlyMap<string, ChainAlias>,
+    outerLocals: ReadonlyMap<string, AstNode>,
+    file: string,
+  ): void => {
+    if (seen.has(fn)) return;
+    seen.add(fn);
+    userIdRoots.push(fn);
+    const body = (fn as AstNode & { body?: AstNode }).body;
+    if (!body) return;
+    analyzeBody(body, door, outerAliases, outerLocals, file);
+  };
+
+  const analyzeBody = (
+    body: AstNode,
+    door: string,
+    outerAliases: ReadonlyMap<string, ChainAlias>,
+    outerLocals: ReadonlyMap<string, AstNode>,
+    file: string,
+  ): void => {
+    const aliases = new Map(outerAliases);
+    const locals = new Map(outerLocals);
+    collectDirect(body, aliases, locals);
+    checkEscapes(body, door, new Set(aliases.keys()), (detail) => {
+      opaque.push(detail);
+    });
+    for (const call of callsSkippingNested(body)) {
+      const chain = chainFromCall(call, aliases);
+      if (chain) {
+        hits.push({ call, chain });
+        continue;
+      }
+      noteFxPass(call, door, aliases, locals, file, opaque, intrinsics, follow);
+    }
+    for (const nested of nestedFunctions(body)) {
+      if (seen.has(nested)) continue;
+      const shadows = functionParams(nested).some((param) => paramIdentifierName(param) === door);
+      if (shadows) continue;
+      analyzeFunction(nested, door, aliases, locals, file);
+    }
+  };
+
+  const startFile = options.file ?? "";
+  if (isFunctionNode(options.doNode)) {
+    const params = functionParams(options.doNode);
+    const second = params.length >= 2 ? params[1] : undefined;
+    if (second && paramIdentifierName(second) !== "fx") {
+      opaque.push("the do callback's second parameter is not named fx");
+    }
+    analyzeFunction(options.doNode, "fx", new Map(), new Map(), startFile);
+  } else {
+    analyzeBody(options.doNode, "fx", new Map(), new Map(), startFile);
+  }
+
+  return hits;
+
+  function noteFxPass(
+    call: CallExpression,
+    door: string,
+    aliases: ReadonlyMap<string, ChainAlias>,
+    locals: ReadonlyMap<string, AstNode>,
+    file: string,
+    reasons: string[],
+    foundIntrinsics: Array<{ name: "liveQuery" | "applySearchEmbedCdc"; call: CallExpression }>,
+    enter: (
+      fn: AstNode,
+      file: string,
+      aliases: ReadonlyMap<string, ChainAlias>,
+      locals: ReadonlyMap<string, AstNode>,
+    ) => void,
+  ): void {
+    const args = call.arguments ?? [];
+    for (let index = 0; index < args.length; index++) {
+      const arg = unwrapValue(args[index]);
+      if (!arg || arg.type !== "Identifier") continue;
+      const name = identifierName(arg);
+      if (!name) continue;
+      if (aliases.has(name)) {
+        reasons.push(`passes chain alias "${name}" to a call`);
+        continue;
+      }
+      if (name !== door) continue;
+      const resolved = resolveCallee(call.callee, locals, options, file);
+      if (resolved.kind === "function") {
+        const param = functionParams(resolved.fn)[index];
+        if (!param || paramIdentifierName(param) !== "fx") {
+          reasons.push("passes fx to a parameter that is not named fx");
+          continue;
+        }
+        const local = calleeLocal(call.callee, locals);
+        enter(
+          resolved.fn,
+          resolved.file ?? file,
+          local ? aliases : new Map(),
+          local ? locals : new Map(),
+        );
+        continue;
+      }
+      if (resolved.kind === "intrinsic") {
+        if (index !== 0) {
+          reasons.push(`passes fx to ${resolved.name} in a position inference cannot read`);
+          continue;
+        }
+        foundIntrinsics.push({ name: resolved.name, call });
+        continue;
+      }
+      reasons.push(`passes fx to "${resolved.label}", which inference cannot resolve`);
+    }
+  }
+}
+
+function calleeLocal(callee: AstNode, locals: ReadonlyMap<string, AstNode>): boolean {
+  if (callee.type !== "Identifier") return false;
+  const name = identifierName(callee);
+  return name !== undefined && locals.has(name);
+}
+
+function resolveCallee(
+  callee: AstNode,
+  locals: ReadonlyMap<string, AstNode>,
+  options: InferEffectsOptions,
+  file: string,
+): FxCalleeResolution {
+  if (callee.type === "Identifier") {
+    const name = identifierName(callee);
+    const local = name ? locals.get(name) : undefined;
+    if (local) return { kind: "function", fn: local, file };
+  }
+  if (options.resolveCallee) return options.resolveCallee(callee, file);
+  const label = identifierName(callee) ?? "callee";
+  return { kind: "unresolved", label };
+}
+
+function noteIntrinsic(
+  name: "liveQuery" | "applySearchEmbedCdc",
+  call: CallExpression,
+  bindings: ReadonlyMap<string, InferBinding>,
+  reads: Set<ResourceRef | SignalResourceRef | AuthApiKeysResourceRef | AuthTenantsResourceRef>,
+  writes: Set<ResourceRef | AuthApiKeysResourceRef | AuthTenantsResourceRef>,
+  embeds: Set<EmbedRef>,
+  opaque: (detail: string) => void,
+): void {
+  if (name === "liveQuery") {
+    const ref = sqlRefFromArg(call.arguments[1], bindings);
+    if (!ref) {
+      opaque("calls liveQuery with a table inference cannot resolve");
+      return;
+    }
+    reads.add(ref as ResourceRef);
+    return;
+  }
+  const sqlRef = stringArg(unwrapValueNode(call.arguments[5]));
+  if (!sqlRef) {
+    opaque("calls applySearchEmbedCdc with a sqlRef inference cannot resolve");
+    return;
+  }
+  const ref = (sqlRef.includes(":") ? sqlRef : `sql:${sqlRef}`) as ResourceRef;
+  reads.add(ref);
+  writes.add(ref);
+  const models = embedModelsFromColumns(call.arguments[3]);
+  if (!models) {
+    opaque("calls applySearchEmbedCdc with embed columns inference cannot resolve");
+    return;
+  }
+  for (const model of models) embeds.add(model);
+}
+
+function sqlRefFromArg(
+  arg: AstNode | undefined,
+  bindings: ReadonlyMap<string, InferBinding>,
+): string | undefined {
+  if (!arg) return undefined;
+  const node = unwrapValue(arg);
+  const lit = stringArg(node);
+  if (lit) return lit.includes(":") ? lit : `sql:${lit}`;
+  const binding = resolveBinding(node, bindings);
+  if (binding?.kind === "table") return sqlTableRef(binding.ref);
+  if (binding?.kind === "store") return binding.ref;
+  return undefined;
+}
+
+function embedModelsFromColumns(arg: AstNode | undefined): string[] | null {
+  if (!arg) return null;
+  const node = unwrapValue(arg);
+  if (!node || node.type !== "ArrayExpression") return null;
+  const elements = (node as AstNode & { elements?: readonly (AstNode | null)[] }).elements ?? [];
+  const models: string[] = [];
+  for (const element of elements) {
+    if (!element || element.type !== "ObjectExpression") return null;
+    const model = objectStringProp(element, "model");
+    if (model === undefined) {
+      if (objectHasProp(element, "model")) return null;
+      models.push("default");
+      continue;
+    }
+    models.push(model);
+  }
+  return models;
+}
+
+function objectStringProp(obj: AstNode, key: string): string | undefined {
+  for (const prop of objectProps(obj)) {
+    if (propKeyName(prop) !== key) continue;
+    return stringArg(unwrapValue((prop as AstNode & { value?: AstNode }).value));
+  }
+  return undefined;
+}
+
+function objectHasProp(obj: AstNode, key: string): boolean {
+  return objectProps(obj).some((prop) => propKeyName(prop) === key);
+}
+
+function objectProps(obj: AstNode): AstNode[] {
+  return ((obj as AstNode & { properties?: AstNode[] }).properties ?? []).filter(
+    (prop) => prop.type === "Property" || prop.type === "ObjectProperty",
+  );
+}
+
+function propKeyName(prop: AstNode): string | undefined {
+  const key = (prop as AstNode & { key?: AstNode }).key;
+  return identifierName(key) ?? stringArg(key);
+}
+
+function collectDirect(
+  body: AstNode,
+  aliases: Map<string, ChainAlias>,
+  locals: Map<string, AstNode>,
+): void {
+  walkStatements(body, (node) => {
+    if (node.type === "FunctionDeclaration") {
+      const name = identifierName((node as AstNode & { id?: AstNode }).id);
+      if (name) locals.set(name, node);
+      return;
+    }
+    if (node.type !== "VariableDeclarator") return;
+    const name = identifierName((node as AstNode & { id?: AstNode }).id);
+    const init = (node as AstNode & { init?: AstNode | null }).init;
+    if (!name || !init) return;
+    const value = unwrapValue(init);
+    if (value && isFunctionNode(value)) {
+      locals.set(name, value);
+      return;
+    }
+    const alias = aliasFromInit(init, aliases);
+    if (alias) aliases.set(name, alias);
+  });
+}
+
+function aliasFromInit(init: AstNode, aliases: ReadonlyMap<string, ChainAlias>): ChainAlias | null {
+  const node = unwrapValue(init);
+  if (!node || node.type !== "CallExpression") return null;
+  const chain = chainFromCall(node as CallExpression, aliases);
+  if (!chain || chain.rootMethod !== "store") return null;
+  // `const rows = await fx.store(db).select().from(table)` is the query
+  // result. `const q = await fx.store(db)` is still the handle.
+  if (expressionIsAwaited(init) && !isStoreHandle(chain)) return null;
+  return {
+    methods: chain.methods,
+    rootMethod: chain.rootMethod,
+    rootCall: chain.rootCall,
+    leafCall: chain.aliasLeaf ?? (node as CallExpression),
+  };
+}
+
+function isStoreHandle(chain: FxChain): boolean {
+  return chain.rootMethod === "store" && classifyStoreMethods(chain.methods) === "none";
+}
+
+function expressionIsAwaited(node: AstNode): boolean {
+  let current: AstNode | undefined = node;
+  for (let i = 0; i < 8 && current; i++) {
+    if (current.type === "AwaitExpression") return true;
+    if (!VALUE_WRAPPERS.has(current.type)) return false;
+    current =
+      (current as AstNode & { expression?: AstNode }).expression ??
+      (current as AstNode & { argument?: AstNode }).argument;
+  }
+  return false;
+}
+
+function chainFromCall(
+  call: CallExpression,
+  aliases: ReadonlyMap<string, ChainAlias>,
+): FxChain | null {
+  const direct = fxMemberChain(call);
+  if (direct) return direct;
+
+  let current: CallExpression | null = call;
+  const methods: string[] = [];
+  while (current) {
+    const callee = current.callee;
+    if (callee.type !== "MemberExpression") return null;
+    const member = callee as AstNode & {
+      object: AstNode;
+      property: AstNode;
+      computed?: boolean;
+    };
+    if (member.computed === true || member.property.type !== "Identifier") return null;
+    methods.unshift((member.property as Identifier).name);
+    if (member.object.type === "Identifier") {
+      const alias = aliases.get((member.object as Identifier).name);
+      if (!alias) return null;
+      return {
+        rootMethod: alias.rootMethod,
+        methods: [...alias.methods, ...methods],
+        rootCall: alias.rootCall,
+        aliasLeaf: alias.leafCall,
+      };
+    }
+    if (member.object.type === "CallExpression") {
+      current = member.object as CallExpression;
+      continue;
+    }
+    return null;
+  }
+  return null;
+}
+
+function checkEscapes(
+  root: AstNode,
+  door: string,
+  aliasNames: ReadonlySet<string>,
+  report: (detail: string) => void,
+): void {
+  const rec = (node: AstNode, parent: AstNode | undefined, inCallArg: boolean): void => {
+    if (node !== root && isFunctionNode(node)) return;
+    if (node.type === "Identifier") {
+      const name = (node as Identifier).name;
+      const isAlias = aliasNames.has(name);
+      const isDoor = name === door;
+      if (
+        (isAlias || isDoor) &&
+        !isTypePosition(parent) &&
+        !(isDoor && inCallArg) &&
+        !isAllowedFxUse(node, parent)
+      ) {
+        report(describeFxEscape(name, parent, isAlias));
+      }
+    }
+    if (node.type === "CallExpression") {
+      const call = node as CallExpression;
+      rec(call.callee, node, false);
+      for (const arg of call.arguments ?? []) {
+        if (arg) rec(arg, node, true);
+      }
+      return;
+    }
+    if (VALUE_WRAPPERS.has(node.type) && inCallArg) {
+      const inner =
+        (node as AstNode & { expression?: AstNode }).expression ??
+        (node as AstNode & { argument?: AstNode }).argument;
+      if (inner) rec(inner, node, true);
+      return;
+    }
+    for (const value of Object.values(node)) {
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          if (isAstNode(item)) rec(item, node, inCallArg);
+        }
+      } else if (isAstNode(value)) {
+        rec(value, node, inCallArg);
+      }
+    }
+  };
+  rec(root, undefined, false);
+}
+
+function isAllowedFxUse(node: AstNode, parent: AstNode | undefined): boolean {
+  if (!parent) return false;
+  if (parent.type === "MemberExpression") {
+    const member = parent as AstNode & { object?: AstNode; property?: AstNode; computed?: boolean };
+    if (member.property === node && member.computed !== true) return true;
+    if (member.object === node) return true;
+  }
+  if (parent.type === "VariableDeclarator" && (parent as AstNode & { id?: AstNode }).id === node) {
+    return true;
+  }
+  if (
+    (parent.type === "FunctionDeclaration" ||
+      parent.type === "FunctionExpression" ||
+      parent.type === "ArrowFunctionExpression") &&
+    (parent as AstNode & { id?: AstNode }).id === node
+  ) {
+    return true;
+  }
+  return false;
+}
+
+function describeFxEscape(name: string, parent: AstNode | undefined, isAlias: boolean): string {
+  if (isAlias) {
+    if (parent?.type === "ReturnStatement") return `returns chain alias "${name}"`;
+    if (parent?.type === "CallExpression") return `passes chain alias "${name}" to a call`;
+    if (
+      parent?.type === "ArrayExpression" ||
+      parent?.type === "ObjectExpression" ||
+      parent?.type === "Property" ||
+      parent?.type === "ObjectProperty"
+    ) {
+      return `puts chain alias "${name}" in an object or array`;
+    }
+    if (parent?.type === "AssignmentExpression") return `reassigns chain alias "${name}"`;
+    return `lets chain alias "${name}" escape`;
+  }
+  if (parent?.type === "VariableDeclarator") return "aliases fx";
+  if (
+    parent?.type === "ObjectPattern" ||
+    parent?.type === "ArrayPattern" ||
+    parent?.type === "Property" ||
+    parent?.type === "ObjectProperty" ||
+    parent?.type === "RestElement"
+  ) {
+    return "destructures fx";
+  }
+  return "lets fx escape";
+}
+
+function isTypePosition(parent: AstNode | undefined): boolean {
+  if (!parent) return false;
+  if (!parent.type.startsWith("TS")) return false;
+  return !VALUE_WRAPPERS.has(parent.type);
+}
+
+function callsSkippingNested(body: AstNode): CallExpression[] {
+  const out: CallExpression[] = [];
+  const take = (node: AstNode): void => {
+    if (node.type === "CallExpression") out.push(node as CallExpression);
+  };
+  take(body);
+  walkSkipFunctions(body, take);
+  return out;
+}
+
+function nestedFunctions(body: AstNode): AstNode[] {
+  const out: AstNode[] = [];
+  walkSkipFunctions(body, (node) => {
+    if (isFunctionNode(node)) out.push(node);
+  });
+  return out;
+}
+
+function walkSkipFunctions(root: AstNode, visit: (node: AstNode) => void): void {
+  const rec = (node: AstNode): void => {
+    for (const value of Object.values(node)) {
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          if (!isAstNode(item)) continue;
+          visit(item);
+          if (!isFunctionNode(item)) rec(item);
+        }
+      } else if (isAstNode(value)) {
+        visit(value);
+        if (!isFunctionNode(value)) rec(value);
+      }
+    }
+  };
+  rec(root);
+}
+
+function walkStatements(node: AstNode, visit: (node: AstNode) => void): void {
+  if (node.type === "BlockStatement" || node.type === "Program" || node.type === "StaticBlock") {
+    const body = (node as AstNode & { body?: AstNode[] }).body ?? [];
+    for (const stmt of body) walkStatement(stmt, visit);
+    return;
+  }
+  walkSkipFunctions(node, (child) => {
+    if (child.type === "VariableDeclarator" || child.type === "FunctionDeclaration") visit(child);
+  });
+}
+
+function walkStatement(stmt: AstNode, visit: (node: AstNode) => void): void {
+  if (stmt.type === "FunctionDeclaration") {
+    visit(stmt);
+    return;
+  }
+  if (stmt.type === "VariableDeclaration") {
+    const declarations = (stmt as AstNode & { declarations?: AstNode[] }).declarations ?? [];
+    for (const decl of declarations) visit(decl);
+    return;
+  }
+  if (stmt.type === "BlockStatement") {
+    walkStatements(stmt, visit);
+    return;
+  }
+  if (
+    stmt.type === "IfStatement" ||
+    stmt.type === "ForStatement" ||
+    stmt.type === "ForInStatement" ||
+    stmt.type === "ForOfStatement" ||
+    stmt.type === "WhileStatement" ||
+    stmt.type === "DoWhileStatement" ||
+    stmt.type === "LabeledStatement"
+  ) {
+    const consequent = (stmt as AstNode & { consequent?: AstNode }).consequent;
+    const alternate = (stmt as AstNode & { alternate?: AstNode }).alternate;
+    const body = (stmt as AstNode & { body?: AstNode }).body;
+    if (consequent) walkStatement(consequent, visit);
+    if (alternate) walkStatement(alternate, visit);
+    if (body && body !== consequent) walkStatement(body, visit);
+    return;
+  }
+  if (stmt.type === "TryStatement") {
+    const block = (stmt as AstNode & { block?: AstNode }).block;
+    const handler = (stmt as AstNode & { handler?: AstNode }).handler;
+    const finalizer = (stmt as AstNode & { finalizer?: AstNode }).finalizer;
+    if (block) walkStatement(block, visit);
+    const handlerBody = (handler as (AstNode & { body?: AstNode }) | undefined)?.body;
+    if (handlerBody) walkStatement(handlerBody, visit);
+    if (finalizer) walkStatement(finalizer, visit);
+    return;
+  }
+  if (stmt.type === "SwitchStatement") {
+    const cases = (stmt as AstNode & { cases?: AstNode[] }).cases ?? [];
+    for (const item of cases) {
+      const consequent = (item as AstNode & { consequent?: AstNode[] }).consequent ?? [];
+      for (const child of consequent) walkStatement(child, visit);
+    }
+  }
+}
+
+function functionParams(fn: AstNode): AstNode[] {
+  return (fn as AstNode & { params?: AstNode[] }).params ?? [];
+}
+
+function paramIdentifierName(param: AstNode): string | undefined {
+  if (param.type === "Identifier") return identifierName(param);
+  if (param.type === "AssignmentPattern" || param.type === "RestElement") {
+    const inner =
+      (param as AstNode & { left?: AstNode }).left ??
+      (param as AstNode & { argument?: AstNode }).argument;
+    return identifierName(inner);
+  }
+  return undefined;
+}
+
+function isFunctionNode(node: AstNode): boolean {
+  return (
+    node.type === "ArrowFunctionExpression" ||
+    node.type === "FunctionExpression" ||
+    node.type === "FunctionDeclaration"
+  );
+}
+
+function unwrapValue(node: AstNode | undefined): AstNode | undefined {
+  if (!node) return undefined;
+  return unwrapValueNode(node);
+}
+
+function unwrapValueNode(node: AstNode | undefined): AstNode | undefined {
+  if (!node) return undefined;
+  let current = node;
+  for (let i = 0; i < 8; i++) {
+    if (!VALUE_WRAPPERS.has(current.type)) break;
+    const next =
+      (current as AstNode & { expression?: AstNode }).expression ??
+      (current as AstNode & { argument?: AstNode }).argument;
+    if (!next) break;
+    current = next;
+  }
+  return current;
+}
+
+function isAstNode(value: unknown): value is AstNode {
+  return typeof value === "object" && value !== null && typeof (value as AstNode).type === "string";
+}