@facilis.dev/analyze 0.0.0-stage → 0.1.1

package/src/passes/route-handler.ts

@@ -0,0 +1,105 @@
+/**
+ * Facts read from a route handler expression (docs/findings/ast-dsl-contract.md §3.1).
+ *
+ * The security rules need to know whether a handler reads the request input — the JSON body
+ * or the multipart form: the fact must come from the AST, not from a comment or a string, so
+ * a route cannot look validated by mentioning `body`/`form` in prose.
+ *
+ * The same reasoning drives the direct-DB warning: a handler that reaches the raw client
+ * through `event.context.facilis.db` or imports the `createDb` factory bypasses the
+ * policy-scoped client, and only the AST can tell a real access from a string mention.
+ */
+
+import {
+  asNode,
+  callArguments,
+  memberName,
+  objectEntries,
+  propertyName,
+  unwrapExpression,
+  type AstNode,
+} from "../ast/node.ts";
+import { walk } from "../ast/walk.ts";
+import { warning } from "../diagnostics.ts";
+import type { ProjectFile } from "../module-graph.ts";
+import { sourceRef } from "../source.ts";
+import type { Diagnostic, SourceRef } from "../types.ts";
+
+const RAW_DB_SPECIFIER = "@facilis.dev/db";
+const RAW_DB_FACTORY = "createDb";
+
+/** Warning text for raw/direct DB access in a route file. */
+export const ROUTE_DIRECT_DB_MESSAGE =
+  "Direct DB access bypasses the policy-scoped client; use ctx.db for user-scoped work and ctx.system/ctx.sudo for audited system operations (not recommended).";
+
+function nodeRef(file: ProjectFile, node: AstNode, fallback: SourceRef): SourceRef {
+  return typeof node.start === "number" ? sourceRef(file.path, file.source, node.start) : fallback;
+}
+
+/** True when the object chain of `node` contains a `.facilis` property. */
+function touchesFacilisContext(node: AstNode): boolean {
+  let current: AstNode | undefined = node;
+  while (current !== undefined && current.type === "MemberExpression") {
+    if (memberName(current) === "facilis") return true;
+    current = asNode(unwrapExpression(current.object));
+  }
+  return false;
+}
+
+/** `event.context.facilis.db` (or any `*.facilis.db` access): the raw policy-free client. */
+function isDirectDbMember(node: AstNode): boolean {
+  if (node.type !== "MemberExpression" || memberName(node) !== "db") return false;
+  const object = asNode(unwrapExpression(node.object));
+  return object !== undefined && touchesFacilisContext(object);
+}
+
+/** True when the handler reads `name` off the request: member access or destructuring. */
+function handlerReads(call: AstNode, name: string): boolean {
+  const handler = callArguments(call)[1];
+  if (handler === undefined) return false;
+  let found = false;
+  walk(handler, (node) => {
+    if (found) return;
+    if (node.type === "MemberExpression" && memberName(node) === name) {
+      found = true;
+      return;
+    }
+    if (
+      node.type === "ObjectPattern" &&
+      objectEntries(node).some((entry) => entry.type === "Property" && propertyName(entry) === name)
+    ) {
+      found = true;
+    }
+  });
+  return found;
+}
+
+/** True when the handler reads `.body` or destructures a `{ body }` pattern. */
+export function handlerReadsBody(call: AstNode): boolean {
+  return handlerReads(call, "body");
+}
+
+/** True when the handler reads `.form` or destructures a `{ form }` pattern (D-053). */
+export function handlerReadsForm(call: AstNode): boolean {
+  return handlerReads(call, "form");
+}
+
+/**
+ * Warnings for raw/direct DB access in a route file: `event.context.facilis.db` bypasses
+ * the policy-scoped client, and importing the `createDb` factory is the raw-client path.
+ * The source points at the offending node (or the route when a node has no position), so
+ * the IDE can jump to it.
+ */
+export function directDbWarnings(file: ProjectFile, fallback: SourceRef): Diagnostic[] {
+  const refs: SourceRef[] = [];
+  walk(file.program, (node) => {
+    if (isDirectDbMember(node)) refs.push(nodeRef(file, node, fallback));
+  });
+  for (const imported of file.module.imports) {
+    if (imported.specifier === RAW_DB_SPECIFIER && imported.imported === RAW_DB_FACTORY) {
+      refs.push(imported.source);
+    }
+  }
+  refs.sort((left, right) => left.line - right.line);
+  return refs.map((source) => warning("route-direct-db", ROUTE_DIRECT_DB_MESSAGE, source));
+}

package/src/passes/route-location.ts

@@ -0,0 +1,62 @@
+/**
+ * Route file name -> method/path (Nitro's file router, SPEC §4.2).
+ *
+ * Kept apart from the route pass so the filename rules are testable and the pass stays within
+ * the file-length limit. Two deliberate extensions over @facilis.dev/nitro's route-path: every
+ * HTTP method is recognized, and a method-less file serves ALL methods (Nitro's behavior).
+ */
+
+import type { HttpMethod, RouteFact } from "../types.ts";
+
+export interface RouteLocation {
+  readonly method: HttpMethod;
+  readonly path: string;
+}
+
+const METHOD_SUFFIX = /\.(get|post|put|patch|delete|head|options|trace|connect)$/;
+const ENV_SUFFIX = /\.(dev|prod|prerender)$/;
+const SOURCE_EXTENSION = /\.(?:[cm]?[jt]sx?)$/;
+
+function toOpenApiSegment(segment: string): string {
+  // Optional params `[[id]]` and catch-all `[...slug]` keep their special form; named
+  // params become OpenAPI templates, matching the spec Nitro generates.
+  const optional = /^\[\[(.+)\]\]$/.exec(segment);
+  if (optional?.[1] !== undefined) return "{" + optional[1] + "}";
+  const catchAll = /^\[\.\.\.(.+)\]$/.exec(segment);
+  if (catchAll?.[1] !== undefined) return "{*" + catchAll[1] + "}";
+  const named = /^\[(.+)\]$/.exec(segment);
+  if (named?.[1] !== undefined) return "{" + named[1] + "}";
+  return segment.replace(/:([A-Za-z0-9_]+)/g, "{$1}");
+}
+
+function parseRouteSegment(segment: string): { name: string; method: HttpMethod } | undefined {
+  let name = segment;
+  const env = name.match(ENV_SUFFIX);
+  if (env !== null) name = name.slice(0, -env[0].length);
+  let method: HttpMethod = "ALL";
+  const methodMatch = name.match(METHOD_SUFFIX);
+  if (methodMatch?.[1] !== undefined) {
+    method = methodMatch[1].toUpperCase() as HttpMethod;
+    name = name.slice(0, -methodMatch[0].length);
+  }
+  return name.length === 0 ? undefined : { name, method };
+}
+
+/** Derive the route location from its file name relative to the routes directory. */
+export function routeLocationFromFile(relativeRouteFile: string): RouteLocation | undefined {
+  const normalized = relativeRouteFile.replace(/\\/g, "/").replace(SOURCE_EXTENSION, "");
+  const segments = normalized.split("/").filter(Boolean);
+  const last = segments.length - 1;
+  if (last < 0) return undefined;
+  const parsed = parseRouteSegment(segments[last] ?? "");
+  if (parsed === undefined) return undefined;
+  if (parsed.name === "index") segments.pop();
+  else segments[last] = parsed.name;
+  const path = segments.filter((segment) => !/^\(.+\)$/.test(segment)).map(toOpenApiSegment);
+  return { method: parsed.method, path: path.length === 0 ? "/" : "/" + path.join("/") };
+}
+
+/** Stable route id shared by facts and the project graph. */
+export function routeFactId(route: Pick<RouteFact, "method" | "path">): string {
+  return "route:" + route.method + " " + route.path;
+}

package/src/passes/route-relation-resolve.ts

@@ -0,0 +1,228 @@
+/**
+ * Name resolution for the route-relations pass (D-157). Split from route-relations.ts so both
+ * files stay under the 300-line limit.
+ *
+ * Two questions are answered here, without executing project code:
+ * - which relation (table or view) an expression denotes, following same-file consts, project
+ *   imports, re-exports and namespace members;
+ * - which db client an expression denotes, so a use can be attributed to `ctx.db` or to one
+ *   audited elevation callback.
+ *
+ * Anything outside the static subset is explicit: "opaque" means a package binding we cannot
+ * inspect (no error, the runtime guard is the authority), "unresolved" means dynamic project
+ * code (an error, D-157: route-table-unresolved).
+ */
+
+import {
+  callArguments,
+  identifierName,
+  memberName,
+  unwrapExpression,
+  type AstNode,
+} from "../ast/node.ts";
+import { walk } from "../ast/walk.ts";
+import { localInitializer } from "../module-info.ts";
+import type { ModuleGraph, ProjectFile } from "../module-graph.ts";
+import type { TableFact, ViewFact } from "../types.ts";
+import { findDeclaration } from "./static-read.ts";
+
+export interface DbClient {
+  /** Elevation index in RouteRelationsFact.elevations; null is the route's ctx.db. */
+  readonly elevation: number | null;
+}
+
+export const ROUTE_CLIENT: DbClient = { elevation: null };
+export type ClientEnv = ReadonlyMap<string, DbClient>;
+
+export type RelationResolution =
+  | { readonly kind: "resolved"; readonly name: string }
+  | { readonly kind: "unresolved" }
+  | { readonly kind: "opaque" };
+
+const UNRESOLVED: RelationResolution = { kind: "unresolved" };
+const OPAQUE: RelationResolution = { kind: "opaque" };
+
+export interface RelationIndex {
+  readonly names: ReadonlySet<string>;
+  resolve(
+    graph: ModuleGraph,
+    file: ProjectFile,
+    node: AstNode | undefined,
+    aliases: ReadonlyMap<string, string>,
+    depth?: number,
+  ): RelationResolution;
+}
+
+interface RelationLookup {
+  readonly byBinding: ReadonlyMap<string, string>;
+  readonly names: ReadonlySet<string>;
+}
+
+/** Table and view bindings, keyed by declaring file + binding (D-157). */
+export function createRelationIndex(
+  tables: readonly TableFact[],
+  views: readonly ViewFact[],
+): RelationIndex {
+  const byBinding = new Map<string, string>();
+  const names = new Set<string>();
+  for (const table of tables) {
+    names.add(table.name);
+    if (table.binding !== null) byBinding.set(table.source.file + "#" + table.binding, table.name);
+  }
+  for (const view of views) {
+    names.add(view.name);
+    if (view.binding !== null) byBinding.set(view.source.file + "#" + view.binding, view.name);
+  }
+  const lookup: RelationLookup = { byBinding, names };
+  return {
+    names,
+    resolve: (graph, file, node, aliases, depth = 0) =>
+      resolveRelation(graph, file, node, aliases, lookup, depth),
+  };
+}
+
+const MAX_RELATION_DEPTH = 8;
+
+function resolveRelation(
+  graph: ModuleGraph,
+  file: ProjectFile,
+  node: AstNode | undefined,
+  aliases: ReadonlyMap<string, string>,
+  lookup: RelationLookup,
+  depth: number,
+): RelationResolution {
+  const expression = unwrapExpression(node);
+  if (expression === undefined || depth > MAX_RELATION_DEPTH) return UNRESOLVED;
+  if (expression.type === "Identifier") {
+    const local = identifierName(expression);
+    if (local === undefined) return UNRESOLVED;
+    const alias = aliases.get(local);
+    if (alias !== undefined) return { kind: "resolved", name: alias };
+    const initializer = localInitializer(file.program, local);
+    if (initializer !== undefined) {
+      return resolveRelation(graph, file, initializer, aliases, lookup, depth + 1);
+    }
+    const binding = graph.resolveBinding(file.path, local);
+    if (binding === null) {
+      // Framework/package sources are often absent from the file map (the browser IDE's VFS
+      // carries project files only): an imported binding we cannot inspect is opaque, so the
+      // runtime guard stays the authority instead of a false "unresolved" error (D-157).
+      if (file.module.imports.some((entry) => entry.local === local)) return OPAQUE;
+      // A project file map may still omit a framework source: fall back to the SQL name.
+      return lookup.names.has(local) ? { kind: "resolved", name: local } : UNRESOLVED;
+    }
+    const direct = lookup.byBinding.get(binding.file + "#" + binding.name);
+    if (direct !== undefined) return { kind: "resolved", name: direct };
+    return binding.file.startsWith("node_modules/") ? OPAQUE : UNRESOLVED;
+  }
+  if (expression.type === "MemberExpression") {
+    const property = memberName(expression);
+    const object = unwrapExpression(expression.object);
+    if (property === undefined || object?.type !== "Identifier") return UNRESOLVED;
+    const namespace = identifierName(object);
+    if (namespace === undefined) return UNRESOLVED;
+    const imported = file.module.imports.find((entry) => entry.local === namespace);
+    if (imported === undefined || imported.kind !== "namespace") return UNRESOLVED;
+    const target = graph.resolve(file.path, imported.specifier);
+    if (target === null) return OPAQUE;
+    const name = lookup.byBinding.get(target + "#" + property);
+    return name === undefined ? UNRESOLVED : { kind: "resolved", name };
+  }
+  if (expression.type === "CallExpression") {
+    // alias(todos, "t") and similar wrappers: the relation is the first argument that resolves.
+    for (const argument of callArguments(expression)) {
+      const resolution = resolveRelation(graph, file, argument, aliases, lookup, depth + 1);
+      if (resolution.kind !== "unresolved") return resolution;
+    }
+    return UNRESOLVED;
+  }
+  return UNRESOLVED;
+}
+
+/** The db client an expression denotes directly (a local binding or `ctx.db`), if any. */
+export function clientOf(
+  node: unknown,
+  env: ClientEnv,
+  contextName: string | null,
+): DbClient | null {
+  const expression = unwrapExpression(node);
+  if (expression === undefined) return null;
+  if (expression.type === "Identifier") {
+    const local = identifierName(expression);
+    return local === undefined ? null : (env.get(local) ?? null);
+  }
+  if (expression.type === "MemberExpression" && memberName(expression) === "db") {
+    const object = unwrapExpression(expression.object);
+    if (object?.type === "Identifier" && identifierName(object) === contextName)
+      return ROUTE_CLIENT;
+  }
+  return null;
+}
+
+/** The client at the root of a fluent chain (`db.select()`, `db.query.todos`). */
+export function chainClient(
+  node: unknown,
+  env: ClientEnv,
+  contextName: string | null,
+): DbClient | null {
+  const expression = unwrapExpression(node);
+  if (expression === undefined) return null;
+  const direct = clientOf(expression, env, contextName);
+  if (direct !== null) return direct;
+  if (expression.type === "CallExpression") return chainClient(expression.callee, env, contextName);
+  if (expression.type === "MemberExpression")
+    return chainClient(expression.object, env, contextName);
+  return null;
+}
+
+/** True when a callee argument carries a db client anywhere (opaque callee detection). */
+export function carriesClient(node: AstNode, env: ClientEnv, contextName: string | null): boolean {
+  let found = false;
+  walk(node, (candidate) => {
+    if (!found && clientOf(candidate, env, contextName) !== null) found = true;
+  });
+  return found;
+}
+
+export interface LocalFunction {
+  /** Stable identity for the call stack (cycle guard). */
+  readonly key: string;
+  readonly file: ProjectFile;
+  readonly node: AstNode;
+}
+
+const FUNCTION_TYPES = new Set([
+  "FunctionExpression",
+  "FunctionDeclaration",
+  "ArrowFunctionExpression",
+]);
+
+function functionNode(node: AstNode | undefined): AstNode | undefined {
+  const candidate = unwrapExpression(node);
+  return candidate !== undefined && FUNCTION_TYPES.has(candidate.type) ? candidate : undefined;
+}
+
+/** A project-local function (never a package one: package calls stay opaque, D-157). */
+export function resolveLocalFunction(
+  graph: ModuleGraph,
+  file: ProjectFile,
+  callee: unknown,
+): LocalFunction | null {
+  const expression = unwrapExpression(callee);
+  if (expression?.type !== "Identifier") return null;
+  const name = identifierName(expression);
+  if (name === undefined) return null;
+  const declared =
+    functionNode(localInitializer(file.program, name)) ??
+    functionNode(findDeclaration(file.program, name));
+  if (declared !== undefined) return { key: file.path + "#" + name, file, node: declared };
+  const binding = graph.resolveBinding(file.path, name);
+  if (binding === null || binding.file.startsWith("node_modules/")) return null;
+  const target = graph.file(binding.file);
+  if (target === undefined) return null;
+  const found =
+    functionNode(localInitializer(target.program, binding.name)) ??
+    functionNode(findDeclaration(target.program, binding.name));
+  if (found === undefined) return null;
+  return { key: target.path + "#" + binding.name, file: target, node: found };
+}

package/src/passes/route-relations-diagnostics.ts

@@ -0,0 +1,115 @@
+/**
+ * D-157 diagnostics derived from a route's relation-usage fact:
+ *
+ * - route-table-undeclared (error): used and not declared in dbTables;
+ * - route-table-unused (warning): declared and not used — suppressed when a project-external
+ *   callee received the client or db.execute is present, where the declaration stays
+ *   authoritative (the runtime guard is the enforcement);
+ * - route-table-unresolved (error): dynamic/unresolvable relation expression;
+ * - route-raw-sql (error): db.execute without rawSql: true;
+ * - route-elevation-undeclared (error): used inside an elevation outside its tables option.
+ */
+
+import { error, warning } from "../diagnostics.ts";
+import type { RouteRelationsFact } from "../types-relations.ts";
+import type { Diagnostic, RouteFact } from "../types.ts";
+
+function usedNames(usage: RouteRelationsFact): ReadonlySet<string> {
+  const names = new Set(usage.used.map((use) => use.name));
+  for (const elevation of usage.elevations) {
+    for (const use of elevation.used) names.add(use.name);
+  }
+  return names;
+}
+
+function unusedSuppressed(usage: RouteRelationsFact): boolean {
+  return (
+    usage.opaque ||
+    usage.rawSql.length > 0 ||
+    usage.elevations.some((elevation) => elevation.opaque || elevation.tablesUnknown)
+  );
+}
+
+function undeclared(usage: RouteRelationsFact, declarations: ReadonlySet<string>): Diagnostic[] {
+  const diagnostics: Diagnostic[] = [];
+  for (const use of usage.used) {
+    if (declarations.has(use.name)) continue;
+    diagnostics.push(
+      error(
+        "route-table-undeclared",
+        'relation "' + use.name + '" is used through the route db but not declared in dbTables',
+        use.source,
+      ),
+    );
+  }
+  for (const elevation of usage.elevations) {
+    for (const use of elevation.used) {
+      if (declarations.has(use.name)) continue;
+      diagnostics.push(
+        error(
+          "route-table-undeclared",
+          'relation "' + use.name + '" is used inside an elevation but not declared in dbTables',
+          use.source,
+        ),
+      );
+    }
+  }
+  return diagnostics;
+}
+
+/** Every diagnostic the relation pass derives from one route's usage fact. */
+export function routeRelationDiagnostics(
+  route: RouteFact,
+  usage: RouteRelationsFact,
+): Diagnostic[] {
+  const diagnostics: Diagnostic[] = [];
+  const declared = route.dbTables === null ? null : new Set(route.dbTables);
+  if (declared !== null) diagnostics.push(...undeclared(usage, declared));
+  for (const source of usage.unresolved) {
+    diagnostics.push(
+      error(
+        "route-table-unresolved",
+        "a relation used through the route db cannot be resolved statically",
+        source,
+      ),
+    );
+  }
+  for (const source of usage.rawSql) {
+    if (route.rawSql === true) continue;
+    diagnostics.push(
+      error("route-raw-sql", "db.execute() requires rawSql: true on the route config", source),
+    );
+  }
+  for (const elevation of usage.elevations) {
+    if (elevation.tablesUnknown || elevation.opaque) continue;
+    const tables = new Set(elevation.tables);
+    for (const use of elevation.used) {
+      if (tables.has(use.name)) continue;
+      diagnostics.push(
+        error(
+          "route-elevation-undeclared",
+          'relation "' +
+            use.name +
+            '" is used inside a "' +
+            elevation.kind +
+            '" elevation but not declared in its tables option',
+          use.source,
+        ),
+      );
+    }
+  }
+  if (declared !== null && !unusedSuppressed(usage)) {
+    const used = usedNames(usage);
+    for (const name of route.dbTables ?? []) {
+      if (used.has(name)) continue;
+      diagnostics.push(
+        warning(
+          "route-table-unused",
+          'dbTables declares "' + name + '" but the route never uses it',
+          route.source,
+        ),
+      );
+    }
+  }
+  return diagnostics;
+}

package/src/passes/route-relations-follow.ts

@@ -0,0 +1,146 @@
+/**
+ * Interprocedural part of the route-relations pass (D-157): follow a project-local function
+ * with argument mapping, and enter an audited elevation callback with its elevated client.
+ *
+ * Package calls stay opaque: the runtime guard is the authority there. Following is bounded
+ * by MAX_DEPTH (walk) and guarded by `scope.stack`, so recursion with a db client terminates.
+ */
+
+import {
+  asNode,
+  callArguments,
+  identifierName,
+  memberName,
+  nodeArray,
+  unwrapExpression,
+  type AstNode,
+} from "../ast/node.ts";
+import { sourceRef } from "../source.ts";
+import type { ElevationKind, SourceRef } from "../types.ts";
+import type { DbClient, LocalFunction } from "./route-relation-resolve.ts";
+import { clientOf } from "./route-relation-resolve.ts";
+import type { MutableElevation, RelationScope } from "./route-relations-usage.ts";
+import { readStaticObject } from "./static-read.ts";
+
+export type Visit = (node: AstNode, scope: RelationScope) => void;
+
+function refOf(scope: RelationScope, node: AstNode): SourceRef {
+  return sourceRef(
+    scope.file.path,
+    scope.file.source,
+    typeof node.start === "number" ? node.start : 0,
+  );
+}
+
+function stringArray(value: unknown): string[] | null {
+  if (!Array.isArray(value)) return null;
+  return value.every((entry): entry is string => typeof entry === "string") ? [...value] : null;
+}
+
+/** Follow a project-local call, mapping db clients, elevation handlers and relation bindings. */
+export function followFunction(
+  visit: Visit,
+  node: AstNode,
+  scope: RelationScope,
+  local: LocalFunction,
+): void {
+  if (scope.stack.has(local.key)) return;
+  const args = callArguments(node);
+  // Usage inside the arguments belongs to the caller (e.g. a query handed to a helper).
+  for (const argument of args) visit(argument, scope);
+  const env = new Map(scope.env);
+  const aliases = new Map(scope.aliases);
+  const elevationFns = new Map(scope.elevationFns);
+  for (const [position, param] of nodeArray(local.node, "params").entries()) {
+    const name = identifierName(param);
+    const argument = args[position];
+    if (name === undefined || argument === undefined) continue;
+    const client = clientOf(argument, scope.env, scope.contextName);
+    if (client !== null) {
+      env.set(name, client);
+      continue;
+    }
+    const kind = elevationKindOf(argument, scope);
+    if (kind !== null) {
+      elevationFns.set(name, kind);
+      continue;
+    }
+    const resolution = scope.index.resolve(scope.graph, scope.file, argument, scope.aliases);
+    if (resolution.kind === "resolved") aliases.set(name, resolution.name);
+  }
+  const body = asNode(local.node.body);
+  if (body === undefined) return;
+  visit(body, {
+    ...scope,
+    file: local.file,
+    env,
+    aliases,
+    elevationFns,
+    contextName: null,
+    depth: scope.depth + 1,
+    stack: new Set([...scope.stack, local.key]),
+  });
+}
+
+/** An argument that denotes `ctx.sudo`/`ctx.system` (destructured or forwarded). */
+function elevationKindOf(argument: AstNode, scope: RelationScope): ElevationKind | null {
+  const expression = unwrapExpression(argument);
+  if (expression?.type === "Identifier") {
+    return scope.elevationFns.get(identifierName(expression) ?? "") ?? null;
+  }
+  if (expression?.type !== "MemberExpression") return null;
+  const name = memberName(expression);
+  const kind = name === "sudo" || name === "system" ? name : null;
+  if (kind === null) return null;
+  const object = unwrapExpression(expression.object);
+  return object?.type === "Identifier" && identifierName(object) === scope.contextName
+    ? kind
+    : null;
+}
+
+/** Enter an elevation callback with its elevated client bound to the first parameter. */
+export function handleElevation(
+  visit: Visit,
+  node: AstNode,
+  scope: RelationScope,
+  kind: ElevationKind,
+): boolean {
+  const options = readStaticObject(
+    callArguments(node)[0],
+    { graph: scope.graph, file: scope.file.path },
+    { code: "route-relations-static", report: false },
+  );
+  const field = options.fields.get("tables");
+  const read = field !== undefined && field.ok ? stringArray(field.value) : null;
+  const tables: string[] = read ?? [];
+  const tablesUnknown = read === null;
+  const elevation: MutableElevation = {
+    kind,
+    source: refOf(scope, node),
+    tables,
+    tablesUnknown,
+    used: new Map(),
+    unresolved: [],
+    opaque: false,
+  };
+  const index = scope.usage.elevations.push(elevation) - 1;
+  const callback = unwrapExpression(callArguments(node)[1]);
+  if (
+    callback === undefined ||
+    (callback.type !== "ArrowFunctionExpression" && callback.type !== "FunctionExpression")
+  ) {
+    // A callback we cannot inspect leaves the elevated usage unknown, never guessed.
+    elevation.opaque = true;
+    return false;
+  }
+  const body = asNode(callback.body);
+  if (body === undefined) {
+    elevation.opaque = true;
+    return false;
+  }
+  const env = new Map<string, DbClient>(scope.env);
+  const param = identifierName(nodeArray(callback, "params")[0]);
+  if (param !== undefined) env.set(param, { elevation: index });
+  visit(body, { ...scope, env, elevation: index, depth: scope.depth + 1 });
+  return true;
+}