@cplieger/deadset-ts 8.0.0-dev.16 → 8.0.0-dev.17

package/src/overrides.ts

@@ -15,14 +15,14 @@ import {
   SyntaxKind,
   type HeritageClauseElement,
   type Node,
+  type SourceFile,
 } from "@typescript/native/ast";
-import type { AliasChains } from "./alias-chain.ts";
 import { memberComponent } from "./class-members.ts";
-import { nodeKey, type Inventory, type InventorySymbol } from "./inventory.ts";
+import { nodeKey, type InventorySymbol } from "./inventory.ts";
 import { SymbolFlags, type Symbol as TSSymbol, type Type } from "@typescript/native/sync";
 import { UNANSWERED } from "./query.ts";
 import { nameComponent } from "./ref.ts";
-import type { Reference } from "./references.ts";
+import type { Read, ReadRule } from "./references/read-rule.ts";
 import type { ProjectView } from "./session.ts";
 
 const CLASS_DECLARATIONS: ReadonlySet<SyntaxKind> = new Set([
@@ -41,141 +41,157 @@ function nameOf(entry: HeritageClauseElement): Node {
   return isQualifiedName(entry.typeName) ? entry.typeName.right : entry.typeName;
 }
 
-/** Each class of the target whose `extends` clause names a class, with the name node. */
-function extending<Brand>(
-  project: ProjectView<Brand>,
-  held: Inventory,
-): readonly { readonly id: string; readonly base: Node }[] {
-  const found: { id: string; base: Node }[] = [];
-  for (const file of project.ownSourceFiles()) {
-    const visit = (node: Node): void => {
-      if (isClassDeclaration(node) || isClassExpression(node)) {
-        const id = held.declarations.get(nodeKey(file, node));
-        const clause = node.heritageClauses?.find((one) => one.token === SyntaxKind.ExtendsKeyword);
-        const base = clause?.types[0];
-        if (id !== undefined && base !== undefined) {
-          found.push({ id, base: nameOf(base) });
-        }
-      }
-      node.forEachChild(visit);
-    };
-    file.forEachChild(visit);
-  }
-  return found;
+/** One class whose `extends` clause names a class, with the name node and its file. */
+interface Extending {
+  readonly node: Node;
+  readonly file: SourceFile;
+  readonly base: Node;
 }
 
 /**
- * The references each base class member makes to its overrides, for the classes of one
- * project that extend another class of the target, and each class makes to its members
- * that override a member of a class declared outside the target. A member a nearer base
- * already overrides is reached through that override. A private member is not
- * overridden. Each reference is placed at the override and made by its file.
+ * The reads each base class member makes of its overrides, for the classes of the target that
+ * extend another class of the target, and each class makes of its members that override a
+ * member of a class declared outside the target. A member a nearer base already overrides is
+ * reached through that override. A private member is not overridden. Each read is placed at
+ * the override. A class whose base the checker leaves unanswered holds every member it could
+ * override.
  */
-export function overrideReferences<Brand>(
-  project: ProjectView<Brand>,
-  held: Inventory,
-  chains: AliasChains,
-  testFiles: ReadonlySet<string>,
-): readonly Reference[] {
-  const classes = extending(project, held);
-  if (classes.length === 0) {
-    return [];
-  }
-  const byId = new Map(held.symbols.map((symbol) => [symbol.id, symbol]));
-  const members = new Map<string, Map<string, InventorySymbol>>();
-  for (const symbol of held.symbols) {
-    const component = memberComponent(symbol, byId);
-    if (
-      component === undefined ||
-      !OVERRIDABLE.has(symbol.kind) ||
-      symbol.visibility === "private" ||
-      symbol.visibility === "private-name"
-    ) {
-      continue;
-    }
-    const own = members.get(symbol.parent) ?? new Map<string, InventorySymbol>();
-    own.set(component, symbol);
-    members.set(symbol.parent, own);
-  }
-  const bases = new Map<string, readonly string[]>();
-  const outsideBases = new Map<string, TSSymbol>();
-  const own = project.ownPaths();
-  const symbols = project.symbolsAt(classes.map((one) => project.handle(one.base)));
-  classes.forEach(({ id }, index) => {
-    const symbol = symbols[index];
-    if (symbol !== undefined && symbol !== UNANSWERED) {
-      const inTarget = chains
-        .chainOf(symbol)
-        .map((target) => target.id)
-        .filter((target) => byId.get(target)?.kind === "class" && target !== id);
-      bases.set(id, inTarget);
-      const declared =
-        (symbol.flags & SymbolFlags.Alias) === 0 ? symbol : project.queries.aliased(symbol);
-      if (
-        inTarget.length === 0 &&
-        declared !== UNANSWERED &&
-        (((declared.flags & SymbolFlags.Class) !== 0 &&
-          // The target's augmentation of an outside class merges an interface into it,
-          // so only a class declaration says where the class is.
-          declared.declarations.some(
-            (handle) => CLASS_DECLARATIONS.has(handle.kind) && !own.has(handle.path),
-          )) ||
-          ((declared.flags & SymbolFlags.Interface) !== 0 &&
-            declared.declarations.some(
-              (handle) => handle.kind === SyntaxKind.VariableDeclaration && !own.has(handle.path),
-            )))
-      ) {
-        outsideBases.set(id, declared);
-      }
-    }
-  });
-
-  /** The nearest member of one component the class or a class it extends declares. */
-  const declaredAbove = (classId: string, component: string, seen: Set<string>): string[] => {
-    if (seen.has(classId)) {
-      return [];
-    }
-    seen.add(classId);
-    const own = members.get(classId)?.get(component);
-    if (own !== undefined) {
-      return [own.id];
-    }
-    return (bases.get(classId) ?? []).flatMap((base) => declaredAbove(base, component, seen));
-  };
-
-  const found: Reference[] = [];
-  const outsideNames = outsideMemberNames(project, bases, outsideBases);
-  for (const [classId, names] of outsideNames) {
-    for (const [component, member] of members.get(classId) ?? []) {
-      if (names.has(component)) {
-        found.push({
-          from: classId,
-          to: member.id,
-          position: member.position,
-          use: "read",
-          resolution: "override",
-          test: testFiles.has(member.position.path),
+export const overrides: ReadRule = {
+  start() {
+    const extending: Extending[] = [];
+    return {
+      visit(node, { file }) {
+        if (isClassDeclaration(node) || isClassExpression(node)) {
+          const clause = node.heritageClauses?.find(
+            (one) => one.token === SyntaxKind.ExtendsKeyword,
+          );
+          const base = clause?.types[0];
+          if (base !== undefined) {
+            extending.push({ node, file, base: nameOf(base) });
+          }
+        }
+      },
+      reads({ project, held, chains }) {
+        const found: Read[] = [];
+        const classes = extending.flatMap((one) => {
+          const id = held.declarations.get(nodeKey(one.file, one.node));
+          return id === undefined ? [] : [{ ...one, id }];
         });
-      }
-    }
-  }
-  for (const [classId, baseIds] of bases) {
-    for (const [component, member] of members.get(classId) ?? []) {
-      const seen = new Set([classId]);
-      for (const base of baseIds.flatMap((one) => declaredAbove(one, component, seen))) {
-        found.push({
-          from: base,
-          to: member.id,
-          position: member.position,
-          use: "read",
-          resolution: "override",
-          test: testFiles.has(member.position.path),
+        if (classes.length === 0) {
+          return found;
+        }
+        const byId = new Map(held.symbols.map((symbol) => [symbol.id, symbol]));
+        const members = new Map<string, Map<string, InventorySymbol>>();
+        for (const symbol of held.symbols) {
+          const component = memberComponent(symbol, byId);
+          if (
+            component === undefined ||
+            !OVERRIDABLE.has(symbol.kind) ||
+            symbol.visibility === "private" ||
+            symbol.visibility === "private-name"
+          ) {
+            continue;
+          }
+          const own = members.get(symbol.parent) ?? new Map<string, InventorySymbol>();
+          own.set(component, symbol);
+          members.set(symbol.parent, own);
+        }
+        const bases = new Map<string, readonly string[]>();
+        const outsideBases = new Map<string, TSSymbol>();
+        const fileOf = new Map(classes.map((one) => [one.id, one.file]));
+        const own = project.ownPaths();
+        const unanswered = new Set<string>();
+        const symbols = project.symbolsAt(classes.map((one) => project.handle(one.base)));
+        classes.forEach(({ id }, index) => {
+          const symbol = symbols[index];
+          if (symbol === UNANSWERED) {
+            unanswered.add(id);
+            return;
+          }
+          if (symbol === undefined) {
+            return;
+          }
+          const inTarget = chains
+            .chainOf(symbol)
+            .map((target) => target.id)
+            .filter((target) => byId.get(target)?.kind === "class" && target !== id);
+          bases.set(id, inTarget);
+          const declared =
+            (symbol.flags & SymbolFlags.Alias) === 0 ? symbol : project.queries.aliased(symbol);
+          if (declared === UNANSWERED) {
+            unanswered.add(id);
+            return;
+          }
+          if (
+            inTarget.length === 0 &&
+            (((declared.flags & SymbolFlags.Class) !== 0 &&
+              // The target's augmentation of an outside class merges an interface into it,
+              // so only a class declaration says where the class is.
+              declared.declarations.some(
+                (handle) => CLASS_DECLARATIONS.has(handle.kind) && !own.has(handle.path),
+              )) ||
+              ((declared.flags & SymbolFlags.Interface) !== 0 &&
+                declared.declarations.some(
+                  (handle) =>
+                    handle.kind === SyntaxKind.VariableDeclaration && !own.has(handle.path),
+                )))
+          ) {
+            outsideBases.set(id, declared);
+          }
         });
-      }
-    }
-  }
-  return found;
-}
+
+        /** The nearest member of one component the class or a class it extends declares. */
+        const declaredAbove = (classId: string, component: string, seen: Set<string>): string[] => {
+          if (seen.has(classId)) {
+            return [];
+          }
+          seen.add(classId);
+          const member = members.get(classId)?.get(component);
+          if (member !== undefined) {
+            return [member.id];
+          }
+          return (bases.get(classId) ?? []).flatMap((base) => declaredAbove(base, component, seen));
+        };
+
+        const read = (classId: string, from: string, member: InventorySymbol): void => {
+          const file = fileOf.get(classId);
+          if (file !== undefined) {
+            found.push({
+              kind: "named",
+              from,
+              to: member.id,
+              file,
+              at: member.position,
+              use: "read",
+              via: "override",
+            });
+          }
+        };
+        const outside = outsideMemberNames(project, bases, outsideBases);
+        for (const classId of [...unanswered, ...outside.unanswered]) {
+          const ids = [...(members.get(classId)?.values() ?? [])].map((member) => member.id);
+          found.push({ kind: "held", from: classId, ids });
+        }
+        for (const [classId, names] of outside.names) {
+          for (const [component, member] of members.get(classId) ?? []) {
+            if (names.has(component)) {
+              read(classId, classId, member);
+            }
+          }
+        }
+        for (const [classId, baseIds] of bases) {
+          for (const [component, member] of members.get(classId) ?? []) {
+            const seen = new Set([classId]);
+            for (const base of baseIds.flatMap((one) => declaredAbove(one, component, seen))) {
+              read(classId, base, member);
+            }
+          }
+        }
+        return found;
+      },
+    };
+  },
+};
 
 /**
  * Per class of the target with a class declared outside the target in its `extends`
@@ -186,12 +202,24 @@ function outsideMemberNames<Brand>(
   project: ProjectView<Brand>,
   bases: ReadonlyMap<string, readonly string[]>,
   outsideBases: ReadonlyMap<string, TSSymbol>,
-): ReadonlyMap<string, ReadonlySet<string>> {
+): {
+  readonly names: ReadonlyMap<string, ReadonlySet<string>>;
+  readonly unanswered: readonly string[];
+} {
   const direct = new Map<string, ReadonlySet<string>>();
+  const unanswered: string[] = [];
   const error = errorType(project);
   for (const [classId, base] of outsideBases) {
     const instance = project.queries.declaredTypeOf(base);
     const statics = project.queries.typeOfSymbol(base);
+    if (
+      instance === UNANSWERED ||
+      statics === UNANSWERED ||
+      project.queries.propertiesOf(instance) === UNANSWERED ||
+      (statics !== undefined && project.queries.propertiesOf(statics) === UNANSWERED)
+    ) {
+      unanswered.push(classId);
+    }
     const components = [
       ...namesOf(project, instance === UNANSWERED ? undefined : instance).map(nameComponent),
       ...(instance !== UNANSWERED && reaches(project, instance, error) ? ["toString"] : []),
@@ -220,7 +248,7 @@ function outsideMemberNames<Brand>(
       names.set(classId, found);
     }
   }
-  return names;
+  return { names, unanswered };
 }
 
 /** The global `Error` instance type's identifier, where the program's library declares one. */

package/src/paths.ts

@@ -11,6 +11,58 @@ export function isAbsolutePath(path: string): boolean {
   return path.startsWith(SEPARATOR);
 }
 
+/** Whether a specifier starts a path relative to the file that writes it: `./` or `../`. */
+export function startsRelativePath(specifier: string): boolean {
+  return specifier.startsWith("./") || specifier.startsWith("../");
+}
+
+/** Whether a specifier names a path relative to the file that writes it: `.`, `..`, `./` or `../` first. */
+export function isRelativeSpecifier(specifier: string): boolean {
+  return specifier === "." || specifier === ".." || startsRelativePath(specifier);
+}
+
+/**
+ * Whether a module specifier names a path rather than a package, as the compiler reads one:
+ * a relative specifier or an absolute path.
+ */
+export function isPathSpecifier(specifier: string): boolean {
+  return isRelativeSpecifier(specifier) || isAbsolutePath(specifier);
+}
+
+/**
+ * Whether a string starts with `./`, `../` or `/`, the specifiers a browser reads as a URL
+ * rather than a bare name, so a bare `.` or `..` stays a request:
+ * https://html.spec.whatwg.org/multipage/webappapis.html#resolve-a-url-like-module-specifier
+ */
+export function isExplicitPath(text: string): boolean {
+  return startsRelativePath(text) || isAbsolutePath(text);
+}
+
+/**
+ * Whether a string starts with `.` or `/`, which no npm package name does, so a reader that
+ * takes any other string as a package's takes it as a path:
+ * https://docs.npmjs.com/cli/v11/configuring-npm/package-json#name
+ */
+export function cannotStartPackageName(text: string): boolean {
+  return text.startsWith(".") || isAbsolutePath(text);
+}
+
+/** A URL scheme, `file:` and `node:` among them: https://url.spec.whatwg.org/#url-scheme-string */
+const URL_SCHEME = /^[a-z][a-z\d+.-]*:/iu;
+
+/** Whether a string starts with a URL scheme. */
+export function hasURLScheme(text: string): boolean {
+  return URL_SCHEME.test(text);
+}
+
+/**
+ * Whether a URL reference is a relative one that does not start with a solidus, the bare
+ * name included: https://url.spec.whatwg.org/#relative-url-string
+ */
+export function isPathRelativeURL(reference: string): boolean {
+  return reference !== "" && !reference.startsWith(SEPARATOR) && !hasURLScheme(reference);
+}
+
 /**
  * One path with `.` removed, `..` applied to the segment before it, and repeated
  * separators collapsed. A `..` that walks past the root of an absolute path is
@@ -97,18 +149,12 @@ export function resolvePath(against: string, path: string): string {
   return isAbsolutePath(path) ? normalizePath(path) : joinPath(against, path);
 }
 
-/**
- * A URL reference's scheme. A reference with none that does not start with a solidus is
- * relative, the bare name included: https://url.spec.whatwg.org/#relative-url-string
- */
-const URL_SCHEME = /^[a-z][a-z\d+.-]*:/iu;
-
 /**
  * The path a relative URL reference names against `dir`, its query and its fragment
  * removed, which name no part of the file; undefined where the reference is not relative.
  */
 export function relativeURLPath(dir: string, reference: string): string | undefined {
-  if (reference === "" || reference.startsWith("/") || URL_SCHEME.test(reference)) {
+  if (!isPathRelativeURL(reference)) {
     return undefined;
   }
   const cut = reference.search(/[?#]/u);
@@ -123,7 +169,7 @@ export function relativeURLPath(dir: string, reference: string): string | undefi
  */
 export function queriedModulePath(specifier: string): string | undefined {
   const query = specifier.indexOf("?");
-  if (query < 0 || !(specifier.startsWith("./") || specifier.startsWith("../"))) {
+  if (query < 0 || !startsRelativePath(specifier)) {
     return undefined;
   }
   const raw = specifier

package/src/platform-calls.ts

@@ -1,6 +1,6 @@
 /**
- * Which calls are the platform's `require` and which constructions its `URL` (roots.23,
- * references-ts.1), decided once over the bindings of the names a callee is written with: the
+ * Which calls are the platform's `require` or AMD's `define` and which constructions its `URL`
+ * (roots.23, references-ts.37, references-ts.1), decided once over the bindings of the names a callee is written with: the
  * checker's in a program, the file's own scopes in a module read outside every program.
  */
 
@@ -19,7 +19,7 @@ import {
 import { parenthesesRemoved, unwrapped } from "./unwrap.ts";
 
 /** A name of the platform the analysis reads calls of. */
-type PlatformName = "require" | "createRequire" | "URL";
+type PlatformName = "require" | "createRequire" | "define" | "URL";
 
 /** What one written name is bound to, as far as its reader can tell. */
 export interface Bound {

package/src/platform-symbols.ts

@@ -28,19 +28,11 @@ import { isAmbient } from "./inventory.ts";
 import { callsPlatformBy, carriedNames, type BindingOf, type Bound } from "./platform-calls.ts";
 import { unwrapped } from "./unwrap.ts";
 
-/** Counts one request a platform decision puts to the checker. */
-type Asked = () => void;
-
 /** The symbol one symbol names through its aliases, or the symbol itself where it is none. */
-function dealiased<Brand>(
-  project: ProjectView<Brand>,
-  symbol: TSSymbol,
-  asked: Asked,
-): Answer<TSSymbol> {
+function dealiased<Brand>(project: ProjectView<Brand>, symbol: TSSymbol): Answer<TSSymbol> {
   if ((symbol.flags & SymbolFlags.Alias) === 0) {
     return symbol;
   }
-  asked();
   return project.queries.aliased(symbol);
 }
 
@@ -84,7 +76,6 @@ function writesBody(node: Node): boolean {
 function boundBy<Brand>(
   project: ProjectView<Brand>,
   symbol: Answer<TSSymbol> | undefined,
-  asked: Asked,
 ): Bound | undefined {
   if (typeof symbol !== "object") {
     return undefined;
@@ -101,7 +92,6 @@ function boundBy<Brand>(
     if ((at.flags & SymbolFlags.Alias) === 0) {
       return { names, own, provenOwn: own.some(writesBody) };
     }
-    asked();
     const next = project.aliasStepOf(at);
     at = typeof next === "object" ? next : undefined;
   }
@@ -109,29 +99,24 @@ function boundBy<Brand>(
 }
 
 /** Each written name's binding, as this project's checker answers it. */
-function checkerBinding<Brand>(project: ProjectView<Brand>, asked: Asked): BindingOf {
-  return (written) => {
-    asked();
-    return boundBy(project, project.symbolsAt([project.handle(written)])[0], asked);
-  };
+function checkerBinding<Brand>(project: ProjectView<Brand>): BindingOf {
+  return (written) => boundBy(project, project.symbolsAt([project.handle(written)])[0]);
 }
 
 /**
  * Whether a call or construction through `callee`, the batch's answer for which is `symbol`,
- * is one of the platform's `require` or `URL` (roots.23, references-ts.1), as
- * {@link callsPlatformBy} decides it over this project's checker, each request it puts
- * counted by `asked`.
+ * is one of the platform's `require`, AMD's `define` or `URL` (roots.23, references-ts.37,
+ * references-ts.1), as {@link callsPlatformBy} decides it over this project's checker.
  */
 export function callsPlatform<Brand>(
   project: ProjectView<Brand>,
-  name: "require" | "URL",
+  name: "require" | "define" | "URL",
   callee: Identifier,
   symbol: Answer<TSSymbol> | undefined,
-  asked: Asked,
 ): boolean {
-  const others = checkerBinding(project, asked);
+  const others = checkerBinding(project);
   return callsPlatformBy(name, callee, (written) =>
-    written === callee ? boundBy(project, symbol, asked) : others(written),
+    written === callee ? boundBy(project, symbol) : others(written),
   );
 }
 
@@ -177,15 +162,14 @@ function inThreadsModule(node: Node): boolean {
  * (references-ts.2): its symbol resolves to a declaration of `worker_threads`, or one of its
  * own declarations binds the module's `Worker`, or `holder`, the namespace it is read
  * through, binds the module, each binding read as {@link boundExports} reads one, which
- * decides where the module has no declaration. Each request it puts is counted by `asked`.
+ * decides where the module has no declaration.
  */
 export function startsThread<Brand>(
   project: ProjectView<Brand>,
   symbol: Answer<TSSymbol> | undefined,
   holder: Answer<TSSymbol> | undefined,
-  asked: Asked,
 ): boolean {
-  const bindingOf = checkerBinding(project, asked);
+  const bindingOf = checkerBinding(project);
   const declared = (one: Answer<TSSymbol> | undefined, member: string): boolean =>
     typeof one === "object" &&
     ownDeclarations(project, one).some((node) =>
@@ -194,7 +178,7 @@ export function startsThread<Brand>(
   if (declared(symbol, "Worker") || declared(holder, NAMESPACE)) {
     return true;
   }
-  const named = typeof symbol === "object" ? dealiased(project, symbol, asked) : undefined;
+  const named = typeof symbol === "object" ? dealiased(project, symbol) : undefined;
   return (
     typeof named === "object" &&
     named.declarations.some((handle) => {

package/src/references/read-rule.ts

@@ -0,0 +1,60 @@
+import type { Node, SourceFile } from "@typescript/native/ast";
+import type { Type } from "@typescript/native/sync";
+import type { AliasChains } from "../alias-chain.ts";
+import type { Inventory } from "../inventory.ts";
+import type { Position } from "../position.ts";
+import type { Resolution } from "../references.ts";
+import type { ProjectView } from "../session.ts";
+
+/** Where the walk offered a read rule one node: the file, and the declaration enclosing the node. */
+interface ReadSite {
+  readonly file: SourceFile;
+  readonly from: string;
+}
+
+/** What a read rule reads its answers through, after the walk of every file of the side. */
+export interface ReadContext<Brand> {
+  readonly project: ProjectView<Brand>;
+  readonly held: Inventory;
+  readonly chains: AliasChains;
+}
+
+/**
+ * One read a rule makes: a use of the declaration `to` by `from` at a node of a walked file,
+ * or, where a question the read needed went unanswered, a hold. A hold names what the answer
+ * could have made live (program.33): the declarations `ids`, each declaration bearing one of
+ * `names`, each member of one of `types`, or with `members` every member the inventory holds;
+ * the declaration making the read is held as well. A named read sits at a node of `file`, or
+ * at a declaration's own position in it.
+ */
+export type Read =
+  | {
+      readonly kind: "named";
+      readonly from: string;
+      readonly to: string;
+      readonly file: SourceFile;
+      readonly at: Node | Position;
+      readonly use: "read" | "write";
+      readonly via: Resolution;
+      /** A read a rule counts as production code's whoever writes it. */
+      readonly production?: true;
+    }
+  | {
+      readonly kind: "held";
+      readonly from: string;
+      readonly ids?: readonly string[];
+      readonly names?: readonly string[];
+      readonly types?: readonly Type[];
+      readonly members?: true;
+    };
+
+/** One pass of one read rule over the files of one side: it collects while the walk offers nodes, then reads. */
+interface ReadRuleRun {
+  visit(node: Node, site: ReadSite): void;
+  reads<Brand>(context: ReadContext<Brand>): readonly Read[];
+}
+
+/** One rule of the references pages that reads declarations no name node names. */
+export interface ReadRule {
+  start(): ReadRuleRun;
+}

package/src/references/read-rules.ts

@@ -0,0 +1,55 @@
+import { elementAccess } from "../element-access.ts";
+import { indexedAccess } from "../indexed-access.ts";
+import { keyofComparisons } from "../keyof-comparisons.ts";
+import { moduleDeclarations } from "../module-declarations.ts";
+import { overrides } from "../overrides.ts";
+import { isAnswered } from "../query.ts";
+import { iteration } from "../symbol-keys.ts";
+import { typeParameterReads } from "../type-parameter-reads.ts";
+import { unimplementedCallees } from "../unimplemented-callees.ts";
+import type { Read, ReadContext, ReadRule } from "./read-rule.ts";
+
+/** The member kinds a hold of every member names. */
+const MEMBER_KINDS: ReadonlySet<string> = new Set([
+  "method",
+  "class-member",
+  "interface-method",
+  "type-member",
+  "enum-member",
+]);
+
+/**
+ * Every read rule, each run over every side's walked files with the reference sources:
+ * a consumer's read of a target member is a reference as the target's own is.
+ */
+export const READ_RULES: readonly ReadRule[] = [
+  overrides,
+  indexedAccess,
+  elementAccess,
+  keyofComparisons,
+  iteration,
+  typeParameterReads,
+  unimplementedCallees,
+  moduleDeclarations,
+];
+
+/** The declarations one hold names, with the declaration whose read it is. */
+export function heldBy<Brand>(
+  read: Extract<Read, { kind: "held" }>,
+  { project, held, chains }: ReadContext<Brand>,
+): readonly string[] {
+  const ids = [...(read.from === "" ? [] : [read.from]), ...(read.ids ?? [])];
+  for (const name of read.names ?? []) {
+    ids.push(...(held.byName.get(name) ?? []));
+  }
+  for (const type of read.types ?? []) {
+    const properties = project.queries.propertiesOf(type);
+    for (const property of isAnswered(properties) ? properties : []) {
+      ids.push(...chains.declarationsOf(property));
+    }
+  }
+  if (read.members === true) {
+    ids.push(...held.symbols.filter((one) => MEMBER_KINDS.has(one.kind)).map((one) => one.id));
+  }
+  return ids;
+}