@tinvar/renderer 0.0.0-stage → 0.4.1

package/src/can-branch.js

@@ -0,0 +1,1666 @@
+// The lint rule that holds a query called inside a can() branch to an
+// #[Authorize] of its own.
+//
+// tinvar-spec.md, "Defaults and build rules": "Server-component `can()`
+// checks control what is displayed, not access. A lint flags queries
+// rendered inside a `can()` branch that lack an equivalent `#[Authorize]`."
+//
+// A check in a server component decides what this render draws. It decides
+// nothing about who may call the query the branch renders with: the query is
+// answered over /_query to any caller whose route lists it, from a fragment
+// rendered under the route's allowlist, and from any other page that calls
+// it -- and in none of those does the branch run. So a query written inside
+// `{order.can.cancel && ...}` reads as guarded, and is not. What guards it is
+// the query's own #[Authorize], which PHP runs before the cache lookup on
+// every path; this rule asks that it check the same ability.
+//
+// A can() check is either of what a server component holds one by:
+//   - a call of a function or method named `can` -- `can('cancel', order)`,
+//     `gate.can('cancel')` -- whose ability is its first argument, written out;
+//   - a read of a `can` map, the serializable form tinvar-spec.md names
+//     ("Authorization"): `order.can.cancel`, `can['cancel']`, whose ability is
+//     the key read.
+// Or either of those read into a variable first -- `const { cancel } =
+// order.can`, `const allowed = can('cancel', order)`, `const perms =
+// order.can` -- or returned by a function the test calls, in this module or
+// one it imports: the check is followed to where it is written.
+//
+// A branch is what runs only on the check's say: an `if`'s branches, a
+// conditional's, what follows `&&`, `||` or `??`, and the statements after an
+// `if` on a check that returns or throws -- `if (!can.view) return null;`
+// guards the rest of the block. Functions are not a boundary: a callback
+// written inside the branch is rendered from it.
+//
+// A query is a call of query() from @tinvar/react/server (or the root, which
+// re-exports it), or of a function imported from a @queries/* module -- the
+// calls the build puts on a route's allowlist (vite.js), named the way it
+// names them, from what `tinvar codegen` wrote (QUERY_MAP). The query's
+// abilities come from the same file. The guard is satisfied when the query
+// declares an #[Authorize] for one of the abilities its check reads; the
+// subject is not compared, since the check and the attribute name it in two
+// languages.
+//
+// What the branch renders or calls is followed, across files: a component or
+// function it names -- `<OrderShipments />`, `renderRow(row)`, one handed on
+// as a prop -- is read where it is defined, in this module or the module it
+// is imported from, and so is everything that one names in turn; a
+// `<Deferred component="Name">` is read where the rsc entry's
+// deferredRegistry() says Name comes from. Every query any of them calls is
+// held to the branch's check. And a component that renders what it is handed
+// -- `children`, a prop -- under a check of its own carries that check to
+// whatever a module hands it: `<IfCan ...><Refunds /></IfCan>` holds Refunds
+// to IfCan's check.
+//
+// It fails closed. A check whose ability is not written out, a query whose
+// name is not, a query the map does not know and a map that lists no
+// abilities are each reported. So is what the branch reaches and the rule
+// cannot read: an application module it cannot resolve or parse, an export
+// it cannot find, a module loaded at runtime, a <Deferred> naming no
+// registered component, and a component or function the branch renders or
+// calls that was handed in as a parameter, or computed, where it cannot see
+// what it is. A package -- a module under node_modules -- is not read: its
+// code is not the application's, and names no query of the application's.
+
+import { readFileSync, statSync } from 'node:fs';
+import { dirname, extname, relative, resolve } from 'node:path';
+import { QUERIES_MODULE, QUERY_MAP, readQueryAuthorization, readQueryMap } from './query-map.js';
+
+/** The specifiers query() is imported by in a server component: its module, and the root re-exporting it. */
+const QUERY_SPECIFIERS = new Set(['@tinvar/react/server', '@tinvar/react']);
+
+/** The specifiers <Deferred> is imported by. */
+const DEFERRED_SPECIFIERS = new Set(['@tinvar/react/deferred', '@tinvar/react']);
+
+/** Where an application's rsc entry declares its deferred components, under the root. */
+const DEFERRED_REGISTRY = 'resources/entries/rsc.tsx';
+
+/** The call the rsc entry declares them with (vite.js's REGISTRY_FUNCTION). */
+const REGISTRY_FUNCTION = 'deferredRegistry';
+
+/** What `tinvar codegen` types for actions: references to PHP, which call no query. */
+const ACTION_MODULE = /^@actions(?:\/|$)/;
+
+const DECLARATION_FILE = /\.d\.[cm]?ts$/;
+
+/** The extensions an import written without one is looked for under, in order. */
+const EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js', '.mts', '.mjs', '.cts', '.cjs'];
+
+/** Nodes around an expression that leave its value as it is. */
+const WRAPPERS = new Set([
+  'ChainExpression',
+  'TSAsExpression',
+  'TSNonNullExpression',
+  'TSSatisfiesExpression',
+  'TSTypeAssertion',
+  'TSInstantiationExpression',
+  'ParenthesizedExpression',
+]);
+
+/** Where nested code runs at another time, so a check inside it is not this test's. */
+const FUNCTIONS = new Set(['FunctionExpression', 'ArrowFunctionExpression', 'FunctionDeclaration']);
+
+/** Keys under which a node holds only types, or what is no value. */
+const SKIPPED_KEYS = new Set([
+  'parent',
+  'range',
+  'loc',
+  'tokens',
+  'comments',
+  'typeAnnotation',
+  'typeParameters',
+  'typeArguments',
+  'returnType',
+  'superTypeArguments',
+  'implements',
+]);
+
+const WHY =
+  'A can() check decides what a render displays, not who may read: the query is answered over /_query, and from every page and fragment that lists it, where this branch never runs (tinvar-spec.md, "Defaults and build rules").';
+
+/** @type {import('eslint').Rule.RuleModule} */
+export const authorizeQueriesInCanBranches = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require a query called inside a can() branch to declare an #[Authorize] for the same ability: the check only decides what is displayed.',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          queryMap: { type: 'string' },
+          deferredRegistry: { type: 'string' },
+          aliases: { type: 'object', additionalProperties: { type: 'string' } },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      unauthorized: `'{{query}}' is called inside a branch shown only when the visitor can '{{abilities}}', and the query checks no such ability itself. ${WHY} Give the query an #[Authorize('{{ability}}', ...)] of its own.`,
+      unauthorizedVia: `'{{query}}' is called by {{via}}, rendered inside a branch shown only when the visitor can '{{abilities}}', and the query checks no such ability itself. ${WHY} Give the query an #[Authorize('{{ability}}', ...)] of its own.`,
+      unreadableAbility: `This query is called inside a branch on a can() check whose ability is not written out, so whether the query checks the same one cannot be read. ${WHY} Write the ability out: can('cancel', ...), or order.can.cancel.`,
+      unreadableQuery: `This calls query() inside a can() branch with a name that is not written out, so whether the query checks the ability cannot be read. ${WHY} Write the name out: query('orders.shipments', ...).`,
+      unknownQuery: `'{{query}}' is called inside a can() branch, and {{file}} does not list it, so whether it checks the ability cannot be read. Run tinvar codegen.`,
+      noMap: `This query is called inside a can() branch, and {{file}} {{why}}, so whether it checks the ability cannot be read. Run tinvar codegen.`,
+      unreadable: `{{via}} is rendered inside a can() branch, and {{why}}, so whether the queries it calls check the ability cannot be read. ${WHY}`,
+    },
+  },
+  create(context) {
+    if (DECLARATION_FILE.test(context.filename)) return {};
+    const option =
+      /** @type {{ queryMap?: string, deferredRegistry?: string, aliases?: Record<string, string> } | undefined} */ (
+        context.options[0]
+      );
+    const settings = {
+      mapFile: resolve(context.cwd, option?.queryMap ?? QUERY_MAP),
+      registryFile: resolve(context.cwd, option?.deferredRegistry ?? DEFERRED_REGISTRY),
+      aliases: Object.entries(option?.aliases ?? {}).map(([prefix, target]) => ({
+        prefix,
+        target: resolve(context.cwd, target),
+      })),
+      cwd: context.cwd,
+    };
+
+    return {
+      'Program:exit'(program) {
+        if (isClientModule(program)) return;
+        check(context, program, settings);
+      },
+    };
+  },
+};
+
+/**
+ * @typedef {{ kind: 'query', name: string | null, function: string | null, via: string | null }
+ *   | { kind: 'unreadable', why: string, via: string }} Finding
+ *   a query some code calls -- its name, or null where it is not written out --
+ *   or why what it reaches cannot be read; `via` names the component or
+ *   function it was reached through, null for a call written in the branch
+ */
+
+/**
+ * @typedef {{
+ *   file: string,
+ *   program: any,
+ *   client: boolean,
+ *   bindings: ReturnType<typeof queryBindings>,
+ *   top: Map<string, { kind: 'local', node: any } | { kind: 'import', source: string, imported: string }>,
+ *   exports: Map<string, { local: string } | { source: string, imported: string } | { node: any }>,
+ *   stars: string[],
+ * }} Module
+ */
+
+/**
+ * @param {import('eslint').Rule.RuleContext} context
+ * @param {any} program
+ * @param {{ mapFile: string, registryFile: string, aliases: Array<{ prefix: string, target: string }>, cwd: string }} settings
+ */
+function check(context, program, settings) {
+  const sourceCode = context.sourceCode;
+  const current = moduleOf(context.filename, program);
+
+  /** @type {ReturnType<typeof readMaps> | null} */
+  let maps = null;
+  const reader = {
+    settings,
+    parser: context.languageOptions.parser,
+    parserOptions: context.languageOptions.parserOptions ?? {},
+    mapsOf: () => (maps ??= readMaps(settings.mapFile)),
+    current,
+    /** @type {Map<string, Finding[]>} */
+    reached: new Map(),
+    /** @type {Set<string>} */
+    reaching: new Set(),
+    /** @type {Map<any, Array<string | null>>} */
+    checks: new Map(),
+    /** @param {any} node */
+    scopeOf: (node) => sourceCode.getScope(node),
+  };
+
+  /** @type {Set<string>} */
+  const reported = new Set();
+  /** @param {any} node @param {string} messageId @param {Record<string, string>} [data] */
+  const report = (node, messageId, data = {}) => {
+    const key = `${node.range?.[0]}:${node.range?.[1]}:${messageId}:${JSON.stringify(data)}`;
+    if (reported.has(key)) return;
+    reported.add(key);
+    context.report({ node, messageId, data });
+  };
+
+  walk(program, (node) => {
+    // What runs here: a query called, or a component or function named.
+    /** @type {(() => Finding[]) | null} */
+    let findings = null;
+    if (node.type === 'CallExpression') {
+      const call = queryOf(node, current.bindings, reader.mapsOf);
+      if (call !== null) findings = () => [{ kind: 'query', ...call, via: null }];
+    }
+    if (findings === null && isReference(node) && !isQueryCallee(node, current, reader)) {
+      findings = () => reachOfReference(reader, node);
+    }
+    if (findings === null && node.type === 'JSXOpeningElement') {
+      const deferred = deferredOf(reader, current, node);
+      if (deferred !== null) findings = () => deferred;
+    }
+
+    if (findings !== null) {
+      const guards = guardsOf(node).map((guard) => checksIn(reader, guard));
+      if (guards.some((abilities) => abilities.length > 0)) {
+        const found = findings();
+        for (const abilities of guards) {
+          if (abilities.length > 0 && !holds(reader, node, found, abilities, report)) break;
+        }
+      }
+    }
+
+    // A component that renders what it is handed under a check of its own:
+    // what is handed to it here is held to that check.
+    if (node.type === 'JSXElement') {
+      for (const { abilities, nodes } of handedUnderCheck(reader, node)) {
+        for (const handed of nodes) {
+          const found = reachOfSubtree(reader, current, handed, null);
+          holds(reader, handed, found, abilities, report);
+        }
+      }
+    }
+    return undefined;
+  });
+}
+
+/**
+ * Whether every query found checks one of the abilities; reports each that
+ * does not, and each that cannot be read.
+ *
+ * @param {any} reader
+ * @param {any} node where the findings were reached from, reported on
+ * @param {Finding[]} found
+ * @param {Array<string | null>} abilities
+ * @param {(node: any, messageId: string, data?: Record<string, string>) => void} report
+ */
+function holds(reader, node, found, abilities, report) {
+  let held = true;
+  for (const finding of found) {
+    if (finding.kind === 'unreadable') {
+      report(node, 'unreadable', { via: finding.via, why: finding.why });
+      held = false;
+      continue;
+    }
+    const { authorize, why } = reader.mapsOf();
+    if (authorize === null) {
+      report(node, 'noMap', { file: reader.settings.mapFile, why });
+      return false;
+    }
+    if (finding.name === null) {
+      report(
+        node,
+        ...(finding.function === null
+          ? /** @type {const} */ (['unreadableQuery'])
+          : /** @type {const} */ ([
+              'unknownQuery',
+              { query: finding.function, file: reader.settings.mapFile },
+            ])),
+      );
+      held = false;
+      continue;
+    }
+    if (!Object.hasOwn(authorize, finding.name)) {
+      report(node, 'unknownQuery', { query: finding.name, file: reader.settings.mapFile });
+      held = false;
+      continue;
+    }
+    const declared = authorize[finding.name];
+    if (abilities.some((ability) => ability !== null && declared.includes(ability))) continue;
+
+    const written = abilities.filter((ability) => ability !== null);
+    if (written.length === 0) {
+      report(node, 'unreadableAbility');
+      held = false;
+      continue;
+    }
+    const data = { query: finding.name, abilities: written.join("' or '"), ability: written[0] };
+    report(
+      node,
+      finding.via === null ? 'unauthorized' : 'unauthorizedVia',
+      finding.via === null ? data : { ...data, via: finding.via },
+    );
+    held = false;
+  }
+  return held;
+}
+
+// ---------------------------------------------------------------------------
+// What code reaches: the queries it calls, followed through what it names.
+
+/**
+ * What a reference in the linted module reaches, by what its name is bound
+ * to here: an import, a function or class, a variable holding one -- or,
+ * where it is rendered or called, a parameter or a value it cannot see into.
+ *
+ * @param {any} reader
+ * @param {any} node an Identifier or JSXIdentifier
+ * @returns {Finding[]}
+ */
+function reachOfReference(reader, node) {
+  const name = node.name;
+  // `<kit.Card />`, `orders.Shipments()`: the export read of a namespace import.
+  const parent = node.parent;
+  if (
+    (parent?.type === 'MemberExpression' || parent?.type === 'JSXMemberExpression') &&
+    parent.object === node
+  ) {
+    const binding = reader.current.top.get(name);
+    const property = parent.type === 'JSXMemberExpression' ? parent.property.name : propertyName(parent);
+    if (
+      binding?.kind === 'import' &&
+      binding.imported === '*' &&
+      property !== null &&
+      findVariable(reader.scopeOf(node), name)?.defs[0]?.type === 'ImportBinding'
+    ) {
+      return reachOfImport(reader, reader.current, binding.source, property, property);
+    }
+  }
+  const variable = findVariable(reader.scopeOf(node), name);
+  const used = usedAs(node);
+  if (variable === null) {
+    // A global: nothing of the application's, unless the module's own
+    // top-level binding was missed by the scope.
+    return reader.current.top.has(name) ? reachOfBinding(reader, reader.current, name) : [];
+  }
+  return reachOfVariable(reader, variable, name, used, new Set());
+}
+
+/**
+ * @param {any} reader
+ * @param {any} variable an eslint-scope variable
+ * @param {string} name
+ * @param {'rendered' | 'called' | 'value'} used
+ * @param {Set<any>} seen
+ * @returns {Finding[]}
+ */
+function reachOfVariable(reader, variable, name, used, seen) {
+  if (seen.has(variable)) return [];
+  seen.add(variable);
+  /** @type {Finding[]} */
+  const found = [];
+  for (const def of variable.defs) {
+    if (def.type === 'ImportBinding') {
+      found.push(...reachOfBinding(reader, reader.current, name));
+    } else if (def.type === 'FunctionName' || def.type === 'ClassName') {
+      found.push(...reachOfSubtree(reader, reader.current, def.node, null));
+    } else if (def.type === 'Variable') {
+      const init = unwrap(def.node.init);
+      if (init === null || init === undefined) {
+        if (used !== 'value') found.push(cannotSee(name, used, 'is given no value where it is declared'));
+      } else if (def.node.id.type !== 'Identifier') {
+        if (used !== 'value')
+          found.push(cannotSee(name, used, 'is destructured from a value the lint cannot follow'));
+      } else if (isFunctionLike(init)) {
+        found.push(...reachOfSubtree(reader, reader.current, init, null));
+      } else if (isAlias(init)) {
+        // `const Shown = flag ? Shipments : Refunds`: each name it may be.
+        for (const alias of identifiersOf(init)) {
+          const target = findVariable(reader.scopeOf(alias), alias.name);
+          if (target === null) continue;
+          found.push(...reachOfVariable(reader, target, alias.name, used, seen));
+        }
+      } else if (used !== 'value') {
+        found.push(cannotSee(name, used, 'holds a value the lint cannot follow to a component or function'));
+      } else {
+        // Data: what a query answered, or a value made here. Its own calls
+        // are read where they are written.
+      }
+    } else if (def.type === 'Parameter') {
+      // Handed in: what the caller hands is written where it renders this,
+      // and read there -- inside the branch, or, for a component that
+      // renders what it is handed under a check, held to that check where
+      // it is handed over (handedUnderCheck()).
+    } else if (used !== 'value') {
+      found.push(cannotSee(name, used, 'is bound in a way the lint cannot follow'));
+    }
+  }
+  return found;
+}
+
+/**
+ * @param {string} name
+ * @param {'rendered' | 'called' | 'value'} used
+ * @param {string} why
+ * @returns {Finding}
+ */
+function cannotSee(name, used, why) {
+  return { kind: 'unreadable', via: used === 'rendered' ? `<${name}>` : `${name}()`, why: `${name} ${why}` };
+}
+
+/**
+ * What a module's top-level binding reaches: its definition, or the export
+ * of the module it is imported from.
+ *
+ * @param {any} reader
+ * @param {Module} module
+ * @param {string} name
+ * @returns {Finding[]}
+ */
+function reachOfBinding(reader, module, name) {
+  const key = `${module.file}#${name}`;
+  const known = reader.reached.get(key);
+  if (known !== undefined) return known;
+  if (reader.reaching.has(key)) return [];
+  reader.reaching.add(key);
+
+  /** @type {Finding[]} */
+  let found = [];
+  const binding = module.top.get(name);
+  if (binding?.kind === 'local') {
+    // Named for where the query is called: the component or function that
+    // calls it, in the module that defines it.
+    found = reachOfSubtree(reader, module, binding.node, null).map((finding) =>
+      module === reader.current ? finding : withVia(finding, name, module.file, reader),
+    );
+  } else if (binding?.kind === 'import') {
+    found = reachOfImport(reader, module, binding.source, binding.imported, name);
+  }
+
+  reader.reaching.delete(key);
+  reader.reached.set(key, found);
+  return found;
+}
+
+/**
+ * What an import reaches: nothing for a package, for @tinvar's own modules
+ * and codegen's action references; the export in the module it resolves to;
+ * and, refused, a module that cannot be resolved or read.
+ *
+ * @param {any} reader
+ * @param {Module} module the importer
+ * @param {string} source
+ * @param {string} imported the name it is imported by: '*', 'default' or an export's
+ * @param {string} local how the importer names it, for a message
+ * @returns {Finding[]}
+ */
+function reachOfImport(reader, module, source, imported, local) {
+  if (QUERY_SPECIFIERS.has(source) || QUERIES_MODULE.test(source)) {
+    // A query function handed on rather than called is still its query.
+    if (QUERIES_MODULE.test(source) && imported !== '*') {
+      const functions = reader.mapsOf().modules[source];
+      const name = functions !== undefined && Object.hasOwn(functions, imported) ? functions[imported] : null;
+      return [{ kind: 'query', name, function: `${source}'s ${imported}()`, via: null }];
+    }
+    return [];
+  }
+  const target = resolveImport(reader, module.file, source);
+  if (target.kind === 'leaf') return [];
+  const via = `${local} (${display(reader, module.file)})`;
+  if (target.kind === 'unresolved') {
+    return [{ kind: 'unreadable', via, why: `'${source}' cannot be resolved to a module the lint can read` }];
+  }
+  const loaded = loadModule(reader, target.file);
+  if ('error' in loaded) return [{ kind: 'unreadable', via, why: loaded.error }];
+  if (loaded.client) return [];
+  return reachOfExport(reader, loaded, imported, new Set()).map((finding) =>
+    withVia(finding, local, loaded.file, reader),
+  );
+}
+
+/**
+ * What a module's export reaches: `*` the whole module.
+ *
+ * @param {any} reader
+ * @param {Module} module
+ * @param {string} name
+ * @param {Set<string>} seen
+ * @returns {Finding[]}
+ */
+function reachOfExport(reader, module, name, seen) {
+  const key = `${module.file}#${name}`;
+  if (seen.has(key)) return [];
+  seen.add(key);
+
+  if (name === '*') {
+    // The whole module: its own code, and what it re-exports.
+    const found = reachOfSubtree(reader, module, module.program, null);
+    for (const [exported, target] of module.exports) {
+      if ('source' in target)
+        found.push(...reachOfImport(reader, module, target.source, target.imported, exported));
+    }
+    for (const source of module.stars) found.push(...reachOfImport(reader, module, source, '*', '*'));
+    return found;
+  }
+
+  const exported = module.exports.get(name);
+  if (exported !== undefined) {
+    if ('local' in exported) return reachOfBinding(reader, module, exported.local);
+    if ('node' in exported) return reachOfSubtree(reader, module, exported.node, null);
+    return reachOfImport(reader, module, exported.source, exported.imported, name);
+  }
+  for (const source of module.stars) {
+    const target = resolveImport(reader, module.file, source);
+    if (target.kind !== 'file') continue;
+    const loaded = loadModule(reader, target.file);
+    if ('error' in loaded) continue;
+    if (exportsName(reader, loaded, name, new Set())) return reachOfExport(reader, loaded, name, seen);
+  }
+  return [
+    {
+      kind: 'unreadable',
+      via: `${name} (${display(reader, module.file)})`,
+      why: `${display(reader, module.file)} exports no '${name}' the lint can find`,
+    },
+  ];
+}
+
+/**
+ * Whether a module exports a name, itself or through `export *`.
+ *
+ * @param {any} reader
+ * @param {Module} module
+ * @param {string} name
+ * @param {Set<string>} seen
+ */
+function exportsName(reader, module, name, seen) {
+  if (seen.has(module.file)) return false;
+  seen.add(module.file);
+  if (module.exports.has(name)) return true;
+  for (const source of module.stars) {
+    const target = resolveImport(reader, module.file, source);
+    if (target.kind !== 'file') continue;
+    const loaded = loadModule(reader, target.file);
+    if (!('error' in loaded) && exportsName(reader, loaded, name, seen)) return true;
+  }
+  return false;
+}
+
+/**
+ * What a subtree of a module reaches: each query it calls, each <Deferred>
+ * it renders, and what each name it reads that is bound at the module's top
+ * reaches in turn. In another module than the linted one, a name is read by
+ * its spelling alone, which follows more than runs and never less.
+ *
+ * @param {any} reader
+ * @param {Module} module
+ * @param {any} root
+ * @param {string | null} via
+ * @returns {Finding[]}
+ */
+function reachOfSubtree(reader, module, root, via) {
+  /** @type {Finding[]} */
+  const found = [];
+  const linted = module === reader.current;
+  walk(root, (node) => {
+    if (node.type === 'ImportDeclaration' || node.type === 'ExportAllDeclaration') return false;
+    if (node.type === 'ExportNamedDeclaration' && node.source) return false;
+
+    if (node.type === 'CallExpression') {
+      const call = queryOf(node, module.bindings, reader.mapsOf);
+      if (call !== null) found.push({ kind: 'query', ...call, via });
+    }
+    if (node.type === 'ImportExpression') {
+      found.push({
+        kind: 'unreadable',
+        via: via ?? display(reader, module.file),
+        why: 'it loads a module at runtime (import()), which the lint cannot follow',
+      });
+    }
+    if (node.type === 'JSXOpeningElement') {
+      const deferred = deferredOf(reader, module, node);
+      if (deferred !== null) found.push(...deferred);
+    }
+    if (isReference(node) && !isQueryCallee(node, module, reader)) {
+      if (linted) {
+        found.push(...reachOfReference(reader, node));
+      } else if (module.top.has(node.name)) {
+        found.push(...reachOfBinding(reader, module, node.name));
+      }
+    }
+    // `<kit.Card />`, `orders.Shipments()`: an export of a namespace import.
+    const member = node.type === 'MemberExpression' || node.type === 'JSXMemberExpression' ? node : null;
+    if (member !== null && member.object.type.endsWith('Identifier')) {
+      const binding = module.top.get(member.object.name);
+      if (binding?.kind === 'import' && binding.imported === '*' && !QUERY_SPECIFIERS.has(binding.source)) {
+        const property = member.type === 'JSXMemberExpression' ? member.property.name : propertyName(member);
+        found.push(...reachOfImport(reader, module, binding.source, property ?? '*', member.object.name));
+      }
+    }
+    return undefined;
+  });
+  return found;
+}
+
+/**
+ * A <Deferred> element's component, read where the rsc entry's registry
+ * says it comes from; null for an element that is no <Deferred>.
+ *
+ * @param {any} reader
+ * @param {Module} module
+ * @param {any} opening a JSXOpeningElement
+ * @returns {Finding[] | null}
+ */
+function deferredOf(reader, module, opening) {
+  if (opening.name.type !== 'JSXIdentifier') return null;
+  const binding = module.top.get(opening.name.name);
+  if (
+    binding?.kind !== 'import' ||
+    !DEFERRED_SPECIFIERS.has(binding.source) ||
+    binding.imported !== 'Deferred'
+  ) {
+    return null;
+  }
+  const attribute = opening.attributes.find(
+    (/** @type {any} */ a) =>
+      a.type === 'JSXAttribute' && a.name.type === 'JSXIdentifier' && a.name.name === 'component',
+  );
+  const value =
+    attribute?.value?.type === 'JSXExpressionContainer' ? attribute.value.expression : attribute?.value;
+  const name = literal(value);
+  if (name === null) {
+    return [{ kind: 'unreadable', via: '<Deferred>', why: 'the component it names is not written out' }];
+  }
+  const registry = loadModule(reader, reader.settings.registryFile);
+  if ('error' in registry) {
+    return [
+      {
+        kind: 'unreadable',
+        via: `<Deferred component="${name}">`,
+        why: `the registry it is read from ${registry.error}`,
+      },
+    ];
+  }
+  const registered = registeredComponents(registry);
+  const local = registered.get(name);
+  if (local === undefined) {
+    return [
+      {
+        kind: 'unreadable',
+        via: `<Deferred component="${name}">`,
+        why: `${display(reader, registry.file)} registers no component '${name}' with ${REGISTRY_FUNCTION}()`,
+      },
+    ];
+  }
+  return reachOfBinding(reader, registry, local).map((finding) =>
+    withVia(finding, `<Deferred component="${name}">`, registry.file, reader),
+  );
+}
+
+/**
+ * The components a module's deferredRegistry() call registers: each name,
+ * and the binding its value is.
+ *
+ * @param {Module} module
+ * @returns {Map<string, string>}
+ */
+function registeredComponents(module) {
+  /** @type {Map<string, string>} */
+  const components = new Map();
+  walk(module.program, (node) => {
+    if (node.type !== 'CallExpression') return undefined;
+    const callee = unwrap(node.callee);
+    if (callee.type !== 'Identifier' || callee.name !== REGISTRY_FUNCTION) return undefined;
+    const object = unwrap(node.arguments[0]);
+    if (object?.type !== 'ObjectExpression') return undefined;
+    for (const property of object.properties) {
+      if (property.type !== 'Property') continue;
+      const key = property.computed
+        ? literal(property.key)
+        : property.key.type === 'Identifier'
+          ? property.key.name
+          : literal(property.key);
+      const value = unwrap(property.value);
+      if (key !== null && value?.type === 'Identifier') components.set(key, value.name);
+    }
+    return undefined;
+  });
+  return components;
+}
+
+/**
+ * What a JSX element hands a component that renders it under a check of
+ * its own: for each such check, its abilities and the children and
+ * attribute values that check holds.
+ *
+ * @param {any} reader
+ * @param {any} element a JSXElement
+ * @returns {Array<{ abilities: Array<string | null>, nodes: any[] }>}
+ */
+function handedUnderCheck(reader, element) {
+  const tag = element.openingElement.name;
+  if (tag.type !== 'JSXIdentifier' || !/^[A-Z]/.test(tag.name)) return [];
+  const definition = definitionOf(reader, tag);
+  if (definition === null) return [];
+
+  const guarded = guardedProps(reader, definition.module, definition.node);
+  /** @type {Array<{ abilities: Array<string | null>, nodes: any[] }>} */
+  const held = [];
+  for (const { props, abilities } of guarded) {
+    /** @type {any[]} */
+    const nodes = [];
+    if (props === null || props.has('children')) nodes.push(...element.children);
+    for (const attribute of element.openingElement.attributes) {
+      if (attribute.type === 'JSXSpreadAttribute') {
+        if (props === null) nodes.push(attribute.argument);
+      } else if (
+        props === null ||
+        (attribute.name.type === 'JSXIdentifier' && props.has(attribute.name.name))
+      ) {
+        if (attribute.value) nodes.push(attribute.value);
+      }
+    }
+    if (nodes.length > 0) held.push({ abilities, nodes });
+  }
+  return held;
+}
+
+/**
+ * Where a component the linted module renders is defined: a function in
+ * this module, or the export of the module it is imported from.
+ *
+ * @param {any} reader
+ * @param {any} tag
+ * @returns {{ module: Module, node: any } | null}
+ */
+function definitionOf(reader, tag) {
+  const variable = findVariable(reader.scopeOf(tag), tag.name);
+  if (variable === null) return null;
+  const def = variable.defs[0];
+  if (def?.type === 'FunctionName') return { module: reader.current, node: def.node };
+  if (def?.type === 'Variable' && isFunctionLike(unwrap(def.node.init))) {
+    return { module: reader.current, node: unwrap(def.node.init) };
+  }
+  if (def?.type !== 'ImportBinding') return null;
+  const binding = reader.current.top.get(tag.name);
+  if (binding?.kind !== 'import') return null;
+  return exportedFunction(reader, reader.current, binding.source, binding.imported, new Set());
+}
+
+/**
+ * The function an import names, through re-exports; null for one the lint
+ * cannot find, which holds nothing handed to it.
+ *
+ * @param {any} reader
+ * @param {Module} module
+ * @param {string} source
+ * @param {string} name
+ * @param {Set<string>} seen
+ * @returns {{ module: Module, node: any } | null}
+ */
+function exportedFunction(reader, module, source, name, seen) {
+  const target = resolveImport(reader, module.file, source);
+  if (target.kind !== 'file') return null;
+  const loaded = loadModule(reader, target.file);
+  if ('error' in loaded || loaded.client) return null;
+  const key = `${loaded.file}#${name}`;
+  if (seen.has(key)) return null;
+  seen.add(key);
+
+  const exported = loaded.exports.get(name);
+  if (exported === undefined) {
+    for (const star of loaded.stars) {
+      const found = exportedFunction(reader, loaded, star, name, seen);
+      if (found !== null) return found;
+    }
+    return null;
+  }
+  if ('source' in exported) return exportedFunction(reader, loaded, exported.source, exported.imported, seen);
+  const node = 'node' in exported ? unwrap(exported.node) : localFunction(loaded, exported.local);
+  return node !== null && isFunctionLike(node) ? { module: loaded, node } : null;
+}
+
+/** @param {Module} module @param {string} name */
+function localFunction(module, name) {
+  const binding = module.top.get(name);
+  if (binding?.kind !== 'local') return null;
+  const node = binding.node.type === 'VariableDeclarator' ? unwrap(binding.node.init) : binding.node;
+  return node ?? null;
+}
+
+/**
+ * The props a component renders under a check of its own, each check with
+ * the props it holds: `children`, a prop by name, or every prop (null) where
+ * the component renders `props` whole or a name it cannot tie to one.
+ *
+ * @param {any} reader
+ * @param {Module} module
+ * @param {any} component a function
+ * @returns {Array<{ props: Set<string> | null, abilities: Array<string | null> }>}
+ */
+function guardedProps(reader, module, component) {
+  const first = component.params?.[0];
+  if (first === undefined) return [];
+  /** @type {Map<string, string | null>} local name => the prop it is (null: all of them) */
+  const names = new Map();
+  if (first.type === 'Identifier') names.set(first.name, null);
+  else if (first.type === 'ObjectPattern') {
+    for (const property of first.properties) {
+      if (property.type === 'RestElement' && property.argument.type === 'Identifier') {
+        names.set(property.argument.name, null);
+      } else if (property.type === 'Property') {
+        const key = property.key.type === 'Identifier' ? property.key.name : literal(property.key);
+        const value = property.value.type === 'AssignmentPattern' ? property.value.left : property.value;
+        if (value.type === 'Identifier') names.set(value.name, key);
+      }
+    }
+  }
+  if (names.size === 0) return [];
+
+  /** @type {Array<{ props: Set<string> | null, abilities: Array<string | null> }>} */
+  const guarded = [];
+  walk(component.body, (node) => {
+    if (node.type !== 'Identifier' || !names.has(node.name) || !isReference(node)) return undefined;
+    // `props.children`: the prop read; `props` alone: all of them.
+    let prop = names.get(node.name) ?? null;
+    if (prop === null && node.parent?.type === 'MemberExpression' && node.parent.object === node) {
+      prop = propertyName(node.parent);
+    }
+    for (const guard of guardsOf(node)) {
+      const abilities = module === reader.current ? checksIn(reader, guard) : canChecksIn(guard, null);
+      if (abilities.length === 0) continue;
+      guarded.push({ props: prop === null ? null : new Set([prop]), abilities });
+    }
+    return undefined;
+  });
+  return guarded;
+}
+
+/**
+ * The module's own name for a finding reached through `local`, from `file`.
+ *
+ * @param {Finding} finding
+ * @param {string} local
+ * @param {string} file
+ * @param {any} reader
+ * @returns {Finding}
+ */
+function withVia(finding, local, file, reader) {
+  if (finding.via !== null) return finding;
+  return { ...finding, via: `${local} (${display(reader, file)})` };
+}
+
+// ---------------------------------------------------------------------------
+// The caches below live as long as the process: an editor's lint server is
+// shown every file it is ever opened on, so each is capped, the least
+// recently used going first. A Map keeps insertion order; a use moves the
+// key to the end, and the oldest is the first key.
+
+/** How many parsed modules are held; a lint run reads each once a version. */
+const MODULE_LIMIT = 1000;
+
+/** How many query maps are held: one for each app the server lints. */
+const MAP_LIMIT = 16;
+
+/**
+ * The value held for `key`, counted as a use.
+ *
+ * @template K, V
+ * @param {Map<K, V>} cache
+ * @param {K} key
+ * @returns {V | undefined}
+ */
+export function heldIn(cache, key) {
+  if (!cache.has(key)) return undefined;
+  const value = /** @type {V} */ (cache.get(key));
+  cache.delete(key);
+  cache.set(key, value);
+  return value;
+}
+
+/**
+ * Holds `value` for `key` as the newest, dropping the oldest past `limit`.
+ *
+ * @template K, V
+ * @param {Map<K, V>} cache
+ * @param {K} key
+ * @param {V} value
+ * @param {number} limit
+ */
+export function hold(cache, key, value, limit) {
+  cache.delete(key);
+  cache.set(key, value);
+  while (cache.size > limit) {
+    const oldest = cache.keys().next();
+    if (oldest.done === true) break;
+    cache.delete(oldest.value);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Modules: resolved, parsed and read once for each version of the file.
+
+/** @type {Map<string, { stamp: string, module: Module | { error: string } }>} */
+const modules = new Map();
+
+/**
+ * @param {any} reader
+ * @param {string} file
+ * @returns {Module | { error: string }}
+ */
+function loadModule(reader, file) {
+  let stamp;
+  try {
+    const stat = statSync(file);
+    stamp = `${stat.mtimeMs}:${stat.size}`;
+  } catch {
+    return { error: `${display(reader, file)} cannot be read` };
+  }
+  const held = heldIn(modules, file);
+  if (held !== undefined && held.stamp === stamp) return held.module;
+
+  /** @type {Module | { error: string }} */
+  let module;
+  try {
+    const code = readFileSync(file, 'utf8');
+    const parser = reader.parser;
+    const options = {
+      ...reader.parserOptions,
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      range: true,
+      loc: true,
+      filePath: file,
+      ecmaFeatures: { ...(reader.parserOptions.ecmaFeatures ?? {}), jsx: true },
+    };
+    const parsed =
+      typeof parser?.parseForESLint === 'function'
+        ? parser.parseForESLint(code, options).ast
+        : typeof parser?.parse === 'function'
+          ? parser.parse(code, options)
+          : null;
+    if (parsed === null) throw new Error('no parser to read it with');
+    setParents(parsed, null);
+    module = moduleOf(file, parsed);
+  } catch (error) {
+    module = { error: `${display(reader, file)} cannot be parsed (${/** @type {Error} */ (error).message})` };
+  }
+  hold(modules, file, { stamp, module }, MODULE_LIMIT);
+  return module;
+}
+
+/**
+ * A module's top-level bindings and exports.
+ *
+ * @param {string} file
+ * @param {any} program
+ * @returns {Module}
+ */
+function moduleOf(file, program) {
+  /** @type {Module['top']} */
+  const top = new Map();
+  /** @type {Module['exports']} */
+  const exports = new Map();
+  /** @type {string[]} */
+  const stars = [];
+
+  /** @param {any} declaration */
+  const declare = (declaration) => {
+    if (declaration === null || declaration === undefined) return [];
+    if (declaration.type === 'FunctionDeclaration' || declaration.type === 'ClassDeclaration') {
+      if (declaration.id) top.set(declaration.id.name, { kind: 'local', node: declaration });
+      return declaration.id ? [declaration.id.name] : [];
+    }
+    if (declaration.type === 'VariableDeclaration') {
+      const names = [];
+      for (const declarator of declaration.declarations) {
+        for (const name of patternNames(declarator.id)) {
+          top.set(name, { kind: 'local', node: declarator });
+          names.push(name);
+        }
+      }
+      return names;
+    }
+    return [];
+  };
+
+  for (const node of program.body) {
+    if (node.type === 'ImportDeclaration') {
+      if (node.importKind === 'type') continue;
+      for (const specifier of node.specifiers) {
+        if (specifier.importKind === 'type') continue;
+        const imported =
+          specifier.type === 'ImportNamespaceSpecifier'
+            ? '*'
+            : specifier.type === 'ImportDefaultSpecifier'
+              ? 'default'
+              : importedName(specifier);
+        top.set(specifier.local.name, { kind: 'import', source: node.source.value, imported });
+      }
+    } else if (node.type === 'ExportNamedDeclaration') {
+      if (node.exportKind === 'type') continue;
+      if (node.declaration) {
+        for (const name of declare(node.declaration)) exports.set(name, { local: name });
+      }
+      for (const specifier of node.specifiers ?? []) {
+        if (specifier.exportKind === 'type') continue;
+        const exported =
+          specifier.exported.type === 'Identifier' ? specifier.exported.name : specifier.exported.value;
+        const local = specifier.local.type === 'Identifier' ? specifier.local.name : specifier.local.value;
+        exports.set(exported, node.source ? { source: node.source.value, imported: local } : { local });
+      }
+    } else if (node.type === 'ExportDefaultDeclaration') {
+      const declaration = node.declaration;
+      const names = declare(declaration);
+      if (names.length > 0) exports.set('default', { local: names[0] });
+      else if (declaration.type === 'Identifier') exports.set('default', { local: declaration.name });
+      else exports.set('default', { node: declaration });
+    } else if (node.type === 'ExportAllDeclaration') {
+      if (node.exportKind === 'type') continue;
+      if (node.exported) {
+        const name = node.exported.type === 'Identifier' ? node.exported.name : node.exported.value;
+        exports.set(name, { source: node.source.value, imported: '*' });
+      } else {
+        stars.push(node.source.value);
+      }
+    } else {
+      declare(node);
+    }
+  }
+
+  return {
+    file,
+    program,
+    client: isClientModule(program),
+    bindings: queryBindings(program),
+    top,
+    exports,
+    stars,
+  };
+}
+
+/**
+ * Where an import leads: a file of the application's, a leaf -- a package,
+ * @tinvar's own modules, codegen's action references -- or nowhere the lint
+ * can find, which it refuses.
+ *
+ * @param {any} reader
+ * @param {string} from the importing file
+ * @param {string} source
+ * @returns {{ kind: 'file', file: string } | { kind: 'leaf' } | { kind: 'unresolved' }}
+ */
+function resolveImport(reader, from, source) {
+  if (source.startsWith('@tinvar/') || ACTION_MODULE.test(source) || source.startsWith('node:')) {
+    return { kind: 'leaf' };
+  }
+  /** @type {string | null} */
+  let base = null;
+  if (source.startsWith('./') || source.startsWith('../') || source === '.' || source === '..') {
+    base = resolve(dirname(from), source);
+  } else if (source.startsWith('/')) {
+    base = source;
+  } else {
+    for (const { prefix, target } of reader.settings.aliases) {
+      if (source === prefix || source.startsWith(prefix.endsWith('/') ? prefix : `${prefix}/`)) {
+        base = resolve(target, source.slice(prefix.length).replace(/^\//, ''));
+        break;
+      }
+    }
+  }
+  if (base === null) return isPackage(from, source) ? { kind: 'leaf' } : { kind: 'unresolved' };
+
+  // As the bundler does: the path, a TypeScript file for a `.js` written,
+  // with each extension, or a directory's index.
+  const stem = /\.[cm]?jsx?$/.test(base) ? base.replace(/\.[cm]?jsx?$/, '') : null;
+  const candidates = [
+    base,
+    ...(stem === null ? [] : EXTENSIONS.map((extension) => stem + extension)),
+    ...EXTENSIONS.map((extension) => base + extension),
+    ...EXTENSIONS.map((extension) => resolve(base, `index${extension}`)),
+  ];
+  for (const candidate of candidates) {
+    try {
+      if (statSync(candidate).isFile()) {
+        return EXTENSIONS.includes(extname(candidate)) ? { kind: 'file', file: candidate } : { kind: 'leaf' };
+      }
+    } catch {
+      // Not this one.
+    }
+  }
+  return { kind: 'unresolved' };
+}
+
+/** Whether a bare specifier names a package installed where the importer would find it. */
+function isPackage(from, source) {
+  const name = source.startsWith('@') ? source.split('/').slice(0, 2).join('/') : source.split('/')[0];
+  if (name === '' || (name.startsWith('@') && !name.includes('/'))) return false;
+  for (let directory = dirname(from); ; directory = dirname(directory)) {
+    try {
+      if (statSync(resolve(directory, 'node_modules', name)).isDirectory()) return true;
+    } catch {
+      // Not installed here.
+    }
+    if (dirname(directory) === directory) return false;
+  }
+}
+
+/** @param {any} reader @param {string} file */
+function display(reader, file) {
+  const path = relative(reader.settings.cwd, file);
+  return path.startsWith('..') ? file : path;
+}
+
+// ---------------------------------------------------------------------------
+// Checks: the abilities a test reads.
+
+/**
+ * The abilities the can() checks in a test of the linted module read --
+ * null for one not written out -- following a variable the check was read
+ * into and a function that returns one.
+ *
+ * @param {any} reader
+ * @param {any} test
+ * @returns {Array<string | null>}
+ */
+function checksIn(reader, test) {
+  const held = reader.checks.get(test);
+  if (held !== undefined) return held;
+  reader.checks.set(test, []);
+  const found = canChecksIn(test, {
+    /** @param {any} node */
+    variable: (node) => {
+      const variable = findVariable(reader.scopeOf(node), node.name);
+      return variable === null ? null : (variable.defs[0] ?? null);
+    },
+    /** @param {any} def @param {string} name */
+    function: (def, name) => {
+      if (def.type === 'FunctionName') return { module: reader.current, node: def.node };
+      if (def.type === 'Variable' && isFunctionLike(unwrap(def.node.init))) {
+        return { module: reader.current, node: unwrap(def.node.init) };
+      }
+      if (def.type !== 'ImportBinding') return null;
+      const binding = reader.current.top.get(name);
+      return binding?.kind === 'import'
+        ? exportedFunction(reader, reader.current, binding.source, binding.imported, new Set())
+        : null;
+    },
+    reader,
+  });
+  reader.checks.set(test, found);
+  return found;
+}
+
+/**
+ * The abilities the can() checks in a test read -- null for one not written
+ * out -- and none when it holds no check. With a resolver, a name the test
+ * reads is followed to the check it was given, and a function it calls to
+ * the checks it makes.
+ *
+ * @param {any} test
+ * @param {{ variable: (node: any) => any, function: (def: any, name: string) => { module: Module, node: any } | null, reader: any } | null} resolver
+ * @param {Set<any>} [seen]
+ * @returns {Array<string | null>}
+ */
+function canChecksIn(test, resolver, seen = new Set()) {
+  /** @type {Array<string | null>} */
+  const found = [];
+  if (seen.has(test)) return found;
+  seen.add(test);
+  walk(test, (node) => {
+    if (FUNCTIONS.has(node.type) && node !== test) return false;
+
+    if (node.type === 'CallExpression') {
+      const callee = unwrap(node.callee);
+      const named =
+        (callee.type === 'Identifier' && callee.name === 'can') ||
+        (callee.type === 'MemberExpression' && propertyName(callee) === 'can');
+      if (named) {
+        found.push(literal(node.arguments[0]));
+      } else if (callee.type === 'Identifier' && resolver !== null) {
+        // canCancel(order): the checks the function makes.
+        const def = resolver.variable(callee);
+        const fn = def === null ? null : resolver.function(def, callee.name);
+        if (fn !== null) found.push(...canChecksIn(fn.node.body ?? fn.node, null, seen));
+      }
+      return undefined;
+    }
+
+    if (node.type === 'MemberExpression') {
+      const object = unwrap(node.object);
+      const isMap =
+        (object.type === 'Identifier' && (object.name === 'can' || canMapVariable(object, resolver))) ||
+        (object.type === 'MemberExpression' && propertyName(object) === 'can');
+      // `x.can(...)` is a call, read above; `x.can.y` reads the map.
+      if (isMap && !(node.parent?.type === 'CallExpression' && node.parent.callee === node)) {
+        found.push(propertyName(node));
+      }
+      return undefined;
+    }
+
+    // `cancel`, read from `const { cancel } = order.can` or `const cancel =
+    // order.can.cancel`.
+    if (
+      node.type === 'Identifier' &&
+      resolver !== null &&
+      isReference(node) &&
+      node.parent?.type !== 'MemberExpression'
+    ) {
+      const def = resolver.variable(node);
+      if (def?.type !== 'Variable' || !def.node.init) return undefined;
+      if (def.node.id.type === 'Identifier') {
+        found.push(...canChecksIn(def.node.init, resolver, seen));
+      } else if (def.node.id.type === 'ObjectPattern' && isCanMap(unwrap(def.node.init), resolver)) {
+        const key = keyBinding(def.node.id, node.name);
+        if (key !== undefined) found.push(key);
+      }
+    }
+    return undefined;
+  });
+  return found;
+}
+
+/** Whether an expression is a `can` map: `can`, `x.can`, or a name given one. */
+function isCanMap(node, resolver) {
+  if (node?.type === 'Identifier') return node.name === 'can' || canMapVariable(node, resolver);
+  return node?.type === 'MemberExpression' && propertyName(node) === 'can';
+}
+
+/** Whether a name was given a `can` map: `const perms = order.can`, `const { can: perms } = order`. */
+function canMapVariable(node, resolver) {
+  if (resolver === null || node.name === 'can') return false;
+  const def = resolver.variable(node);
+  if (def?.type !== 'Variable' || !def.node.init) return false;
+  if (def.node.id.type === 'Identifier') return isCanMap(unwrap(def.node.init), null);
+  return def.node.id.type === 'ObjectPattern' && keyBinding(def.node.id, node.name) === 'can';
+}
+
+/** The key an object pattern binds a name from, or undefined; null for a computed one. */
+function keyBinding(pattern, name) {
+  for (const property of pattern.properties) {
+    if (property.type !== 'Property') continue;
+    const value = property.value.type === 'AssignmentPattern' ? property.value.left : property.value;
+    if (value.type === 'Identifier' && value.name === name) {
+      return property.computed
+        ? literal(property.key)
+        : property.key.type === 'Identifier'
+          ? property.key.name
+          : literal(property.key);
+    }
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Queries, guards and syntax.
+
+/**
+ * The names query() and the @queries/* functions are bound to in this
+ * module, from its imports.
+ *
+ * @param {any} program
+ */
+function queryBindings(program) {
+  /** @type {Set<string>} local names of query() */
+  const callees = new Set();
+  /** @type {Set<string>} namespaces whose `.query` is query() */
+  const namespaces = new Set();
+  /** @type {Map<string, { module: string, name: string }>} a @queries/* function imported by name */
+  const functions = new Map();
+  /** @type {Map<string, string>} a @queries/* module imported whole => its specifier */
+  const queryModules = new Map();
+
+  for (const node of program.body) {
+    if (node.type !== 'ImportDeclaration' || node.importKind === 'type') continue;
+    const from = node.source.value;
+    for (const specifier of node.specifiers) {
+      if (specifier.importKind === 'type') continue;
+      if (QUERY_SPECIFIERS.has(from)) {
+        if (specifier.type === 'ImportNamespaceSpecifier') namespaces.add(specifier.local.name);
+        else if (specifier.type === 'ImportSpecifier' && importedName(specifier) === 'query') {
+          callees.add(specifier.local.name);
+        }
+      } else if (typeof from === 'string' && QUERIES_MODULE.test(from)) {
+        if (specifier.type === 'ImportSpecifier') {
+          functions.set(specifier.local.name, { module: from, name: importedName(specifier) });
+        } else if (specifier.type === 'ImportNamespaceSpecifier') {
+          queryModules.set(specifier.local.name, from);
+        }
+      }
+    }
+  }
+  return { callees, namespaces, functions, queryModules };
+}
+
+/**
+ * The query a call makes -- its name, or null where it is not written out --
+ * or null when the call is not one.
+ *
+ * @param {any} node
+ * @param {ReturnType<typeof queryBindings>} bindings
+ * @param {() => ReturnType<typeof readMaps>} mapsOf
+ * @returns {{ name: string | null, function: string | null } | null}
+ *          `function` names the @queries/* function called, for one the map does not list
+ */
+function queryOf(node, bindings, mapsOf) {
+  const callee = unwrap(node.callee);
+
+  const isQuery =
+    (callee.type === 'Identifier' && bindings.callees.has(callee.name)) ||
+    (callee.type === 'MemberExpression' &&
+      !callee.computed &&
+      callee.object.type === 'Identifier' &&
+      bindings.namespaces.has(callee.object.name) &&
+      callee.property.type === 'Identifier' &&
+      callee.property.name === 'query');
+  if (isQuery) return { name: literal(node.arguments[0]), function: null };
+
+  /** @type {{ module: string, name: string } | undefined} */
+  let imported;
+  if (callee.type === 'Identifier') imported = bindings.functions.get(callee.name);
+  else if (
+    callee.type === 'MemberExpression' &&
+    callee.object.type === 'Identifier' &&
+    bindings.queryModules.has(callee.object.name)
+  ) {
+    const module = /** @type {string} */ (bindings.queryModules.get(callee.object.name));
+    const name = propertyName(callee);
+    imported = { module, name: name ?? '' };
+  }
+  if (imported === undefined) return null;
+
+  const functions = mapsOf().modules[imported.module];
+  const name =
+    functions !== undefined && Object.hasOwn(functions, imported.name) ? functions[imported.name] : null;
+  return { name, function: `${imported.module}'s ${imported.name || '(computed)'}()` };
+}
+
+/**
+ * The tests whose say a node runs on, innermost first: each `if` or
+ * conditional it is a branch of, each `&&`, `||` or `??` it is the right of,
+ * and each `if` before it in a block that leaves the block when it holds.
+ *
+ * @param {any} node
+ * @returns {any[]}
+ */
+function guardsOf(node) {
+  const guards = [];
+  for (let child = node, parent = node.parent; parent; child = parent, parent = parent.parent) {
+    if (parent.type === 'IfStatement' && (parent.consequent === child || parent.alternate === child)) {
+      guards.push(parent.test);
+    } else if (
+      parent.type === 'ConditionalExpression' &&
+      (parent.consequent === child || parent.alternate === child)
+    ) {
+      guards.push(parent.test);
+    } else if (parent.type === 'LogicalExpression' && parent.right === child) {
+      guards.push(parent.left);
+    } else if (
+      parent.type === 'BlockStatement' ||
+      parent.type === 'Program' ||
+      parent.type === 'SwitchCase'
+    ) {
+      const statements = parent.type === 'SwitchCase' ? parent.consequent : parent.body;
+      const index = statements.indexOf(child);
+      for (const before of statements.slice(0, Math.max(0, index)).reverse()) {
+        if (before.type === 'IfStatement' && before.alternate === null && exits(before.consequent)) {
+          guards.push(before.test);
+        }
+      }
+    }
+  }
+  return guards;
+}
+
+/** Whether a statement always leaves its block: a return or throw, or a block ending in one. */
+function exits(statement) {
+  if (statement.type === 'ReturnStatement' || statement.type === 'ThrowStatement') return true;
+  if (statement.type === 'BlockStatement') {
+    const last = statement.body.at(-1);
+    return last !== undefined && exits(last);
+  }
+  return false;
+}
+
+/**
+ * Whether a node is a name read as a value -- not a declaration, a property
+ * key, an attribute's name or a closing tag -- that may be bound by the
+ * module: an Identifier, or a JSX tag that names a component.
+ *
+ * @param {any} node
+ */
+function isReference(node) {
+  const parent = node.parent;
+  if (node.type === 'JSXIdentifier') {
+    // `<Card>` names a component, `<div>` an element; `<kit.Card>` reads kit.
+    return (
+      (parent?.type === 'JSXOpeningElement' && parent.name === node && /^[A-Z]/.test(node.name)) ||
+      (parent?.type === 'JSXMemberExpression' && parent.object === node)
+    );
+  }
+  if (node.type !== 'Identifier' || parent === null || parent === undefined) return false;
+  switch (parent.type) {
+    case 'MemberExpression':
+      return parent.object === node || parent.computed;
+    case 'Property':
+      return parent.value === node && parent.parent?.type !== 'ObjectPattern';
+    case 'PropertyDefinition':
+    case 'MethodDefinition':
+      return parent.value === node || (parent.computed && parent.key === node);
+    case 'VariableDeclarator':
+      return parent.init === node;
+    case 'FunctionDeclaration':
+    case 'FunctionExpression':
+    case 'ArrowFunctionExpression':
+    case 'ClassDeclaration':
+    case 'ClassExpression':
+      return parent.body === node || parent.superClass === node;
+    case 'ImportSpecifier':
+    case 'ImportDefaultSpecifier':
+    case 'ImportNamespaceSpecifier':
+    case 'ExportSpecifier':
+    case 'LabeledStatement':
+    case 'BreakStatement':
+    case 'ContinueStatement':
+    case 'RestElement':
+    case 'ArrayPattern':
+    case 'ObjectPattern':
+    case 'CatchClause':
+    case 'JSXAttribute':
+      return false;
+    case 'AssignmentPattern':
+      return parent.right === node;
+    case 'AssignmentExpression':
+      return parent.right === node;
+    default:
+      return !parent.type.startsWith('TS') || WRAPPERS.has(parent.type);
+  }
+}
+
+/**
+ * Whether a name is what a query call calls -- `query`, `shipments` in
+ * `shipments(...)` -- which the call itself is read as.
+ *
+ * @param {any} node
+ * @param {Module} module
+ * @param {any} reader
+ */
+function isQueryCallee(node, module, reader) {
+  let child = node;
+  // `orders.refunds(...)`: the namespace read for the function called.
+  if (child.parent?.type === 'MemberExpression' && child.parent.object === child) child = child.parent;
+  while (child.parent && WRAPPERS.has(child.parent.type)) child = child.parent;
+  const parent = child.parent;
+  return (
+    parent?.type === 'CallExpression' &&
+    parent.callee === child &&
+    queryOf(parent, module.bindings, reader.mapsOf) !== null
+  );
+}
+
+/** How a reference is used: rendered as a tag, called, or read as a value. */
+function usedAs(node) {
+  if (node.type === 'JSXIdentifier') return 'rendered';
+  let child = node;
+  while (child.parent && WRAPPERS.has(child.parent.type)) child = child.parent;
+  const parent = child.parent;
+  if ((parent?.type === 'CallExpression' || parent?.type === 'NewExpression') && parent.callee === child)
+    return 'called';
+  return 'value';
+}
+
+/** A function or class written here, whose body is read. */
+function isFunctionLike(node) {
+  return (
+    node !== null &&
+    node !== undefined &&
+    (FUNCTIONS.has(node.type) || node.type === 'ClassExpression' || node.type === 'ClassDeclaration')
+  );
+}
+
+/** A value that is one of some names: `A`, `ns.A`, `flag ? A : B`, `a ?? B`. */
+function isAlias(node) {
+  if (node === null || node === undefined) return false;
+  if (WRAPPERS.has(node.type)) return isAlias(node.expression);
+  if (node.type === 'Identifier') return true;
+  if (node.type === 'ConditionalExpression') return isAlias(node.consequent) && isAlias(node.alternate);
+  if (node.type === 'LogicalExpression') return isAlias(node.right);
+  return false;
+}
+
+/** The names an alias may be. */
+function identifiersOf(node) {
+  if (WRAPPERS.has(node.type)) return identifiersOf(node.expression);
+  if (node.type === 'Identifier') return [node];
+  if (node.type === 'ConditionalExpression')
+    return [...identifiersOf(node.consequent), ...identifiersOf(node.alternate)];
+  if (node.type === 'LogicalExpression')
+    return [...(isAlias(node.left) ? identifiersOf(node.left) : []), ...identifiersOf(node.right)];
+  return [];
+}
+
+/** @param {any} scope @param {string} name */
+function findVariable(scope, name) {
+  for (let current = scope; current; current = current.upper) {
+    const variable = current.set.get(name);
+    if (variable !== undefined) return variable;
+  }
+  return null;
+}
+
+/** The names a pattern binds. */
+function patternNames(pattern) {
+  if (pattern === null || pattern === undefined) return [];
+  switch (pattern.type) {
+    case 'Identifier':
+      return [pattern.name];
+    case 'ObjectPattern':
+      return pattern.properties.flatMap((/** @type {any} */ p) =>
+        patternNames(p.type === 'RestElement' ? p.argument : p.value),
+      );
+    case 'ArrayPattern':
+      return pattern.elements.flatMap((/** @type {any} */ e) => patternNames(e));
+    case 'RestElement':
+      return patternNames(pattern.argument);
+    case 'AssignmentPattern':
+      return patternNames(pattern.left);
+    default:
+      return [];
+  }
+}
+
+/** Whether a module's prologue says 'use client'. */
+function isClientModule(program) {
+  return program.body.some(
+    (/** @type {any} */ statement) =>
+      statement.type === 'ExpressionStatement' && statement.directive === 'use client',
+  );
+}
+
+/** A string written out: a literal, or a template with nothing in it. Null for anything else. */
+function literal(node) {
+  if (node?.type === 'Literal' && typeof node.value === 'string' && node.value !== '') return node.value;
+  if (node?.type === 'TemplateLiteral' && node.expressions.length === 0) {
+    const cooked = node.quasis[0]?.value.cooked;
+    if (typeof cooked === 'string' && cooked !== '') return cooked;
+  }
+  return null;
+}
+
+/** A member's property as written, or null when it is computed from something other than a literal. */
+function propertyName(member) {
+  const property = member.property;
+  if (!member.computed) return property.type === 'Identifier' ? property.name : null;
+  return literal(property);
+}
+
+function importedName(specifier) {
+  return specifier.imported.type === 'Identifier' ? specifier.imported.name : specifier.imported.value;
+}
+
+function unwrap(node) {
+  while (node && WRAPPERS.has(node.type)) node = node.expression;
+  return node;
+}
+
+/** Each node's parent, which a parser leaves to ESLint to set. */
+function setParents(node, parent) {
+  if (node === null || typeof node !== 'object') return;
+  if (Array.isArray(node)) {
+    for (const child of node) setParents(child, parent);
+    return;
+  }
+  if (typeof node.type !== 'string') return;
+  node.parent = parent;
+  for (const key of Object.keys(node)) {
+    if (key === 'parent' || key === 'range' || key === 'loc' || key === 'tokens' || key === 'comments')
+      continue;
+    const child = node[key];
+    if (child !== null && typeof child === 'object') setParents(child, node);
+  }
+}
+
+/**
+ * Depth-first over every node that holds a value -- not TypeScript's types
+ * -- the visitor returning false to skip a subtree.
+ *
+ * @param {any} node
+ * @param {(node: any) => boolean | undefined} visit
+ */
+function walk(node, visit) {
+  if (node === null || typeof node !== 'object') return;
+  if (Array.isArray(node)) {
+    for (const child of node) walk(child, visit);
+    return;
+  }
+  if (typeof node.type !== 'string') return;
+  if (node.type.startsWith('TS') && !WRAPPERS.has(node.type) && node.type !== 'TSParameterProperty') return;
+  if (visit(node) === false) return;
+  for (const key of Object.keys(node)) {
+    if (SKIPPED_KEYS.has(key)) continue;
+    const child = node[key];
+    if (child !== null && typeof child === 'object') walk(child, visit);
+  }
+}
+
+/** @type {Map<string, { stamp: string, maps: { modules: Record<string, Record<string, string>>, authorize: Record<string, string[]> | null, why: string } }>} */
+const cache = new Map();
+
+/**
+ * What codegen wrote, read once for each version of the file: a lint run
+ * reads it for every server module, and an editor's for every keystroke.
+ *
+ * @param {string} file
+ */
+function readMaps(file) {
+  let stamp = 'missing';
+  try {
+    const stat = statSync(file);
+    stamp = `${stat.mtimeMs}:${stat.size}`;
+  } catch {
+    // Missing: read as no map.
+  }
+  const held = heldIn(cache, file);
+  if (held !== undefined && held.stamp === stamp) return held.maps;
+
+  let maps;
+  try {
+    const authorize = readQueryAuthorization(file);
+    maps = {
+      modules: readQueryMap(file),
+      authorize,
+      why: authorize === null ? 'is missing, or lists no query’s abilities' : '',
+    };
+  } catch (error) {
+    maps = {
+      modules: /** @type {Record<string, Record<string, string>>} */ ({}),
+      authorize: null,
+      why: `cannot be read (${/** @type {Error} */ (error).message})`,
+    };
+  }
+  hold(cache, file, { stamp, maps }, MAP_LIMIT);
+  return maps;
+}