@cplieger/deadset-ts 8.0.0-dev.2 → 8.0.0-dev.20

package/src/platform-symbols.ts

@@ -0,0 +1,189 @@
+/**
+ * The platform's names read through a program's checker: its `require` and `URL`, as
+ * `platform-calls.ts` decides them, its worker constructors and `navigator`, and Node's
+ * `Worker`.
+ */
+
+import {
+  isArrowFunction,
+  isClassDeclaration,
+  isClassExpression,
+  isFunctionDeclaration,
+  isFunctionExpression,
+  isMethodDeclaration,
+  isModuleDeclaration,
+  isPropertyAssignment,
+  isPropertyDeclaration,
+  isSourceFile,
+  isStringLiteralLikeNode,
+  isVariableDeclaration,
+  type Identifier,
+  type Node,
+} from "@typescript/native/ast";
+import { SymbolFlags, type Symbol as TSSymbol } from "@typescript/native/sync";
+import { UNANSWERED, type Answer } from "./query.ts";
+import type { ProjectView } from "./session.ts";
+import { boundExports, NAMESPACE } from "./entries/static-module.ts";
+import { isAmbient } from "./inventory.ts";
+import { callsPlatformBy, carriedNames, type BindingOf, type Bound } from "./platform-calls.ts";
+import { unwrapped } from "./unwrap.ts";
+
+/** The symbol one symbol names through its aliases, or the symbol itself where it is none. */
+function dealiased<Brand>(project: ProjectView<Brand>, symbol: TSSymbol): Answer<TSSymbol> {
+  if ((symbol.flags & SymbolFlags.Alias) === 0) {
+    return symbol;
+  }
+  return project.queries.aliased(symbol);
+}
+
+/** Each declaration of `symbol` in a file of the target, read in this project's program. */
+function ownDeclarations<Brand>(project: ProjectView<Brand>, symbol: TSSymbol): readonly Node[] {
+  const own = project.ownPaths();
+  return symbol.declarations.flatMap((handle) => {
+    const node = own.has(handle.path) ? project.declarationAt(handle)?.node : undefined;
+    return node === undefined ? [] : [node];
+  });
+}
+
+/**
+ * Whether one declaration writes a function or a class with a body (roots.23): a function
+ * or method declaration with a body, a class declaration, or a variable, a property or a
+ * class field whose initializer is a function, an arrow function or a class expression,
+ * under no `declare` modifier and in no declaration file.
+ */
+function writesBody(node: Node): boolean {
+  const value =
+    (isVariableDeclaration(node) || isPropertyAssignment(node) || isPropertyDeclaration(node)) &&
+    node.initializer !== undefined
+      ? unwrapped(node.initializer)
+      : node;
+  return (
+    (isFunctionDeclaration(value) || isMethodDeclaration(value)
+      ? value.body !== undefined
+      : isFunctionExpression(value) ||
+        isArrowFunction(value) ||
+        isClassDeclaration(value) ||
+        isClassExpression(value)) && !isAmbient(value.getSourceFile(), value)
+  );
+}
+
+/**
+ * What the checker binds `symbol` to, one alias step at a time: every name a step of the
+ * chain carries it by, and the declarations of the target its last step reaches, which
+ * prove it the target's own where one {@link writesBody}. A chain that ends at no
+ * declaration, or that the checker leaves unanswered, reaches none.
+ */
+function boundBy<Brand>(
+  project: ProjectView<Brand>,
+  symbol: Answer<TSSymbol> | undefined,
+): Bound | undefined {
+  if (typeof symbol !== "object") {
+    return undefined;
+  }
+  const names = new Set<string>();
+  const stepped = new Set<number>();
+  for (let at: TSSymbol | undefined = symbol; at !== undefined && !stepped.has(at.id);) {
+    stepped.add(at.id);
+    names.add(at.name);
+    const own = ownDeclarations(project, at);
+    for (const node of own) {
+      carriedNames(node).forEach((one) => names.add(one));
+    }
+    if ((at.flags & SymbolFlags.Alias) === 0) {
+      return { names, own, provenOwn: own.some(writesBody) };
+    }
+    const next = project.aliasStepOf(at);
+    at = typeof next === "object" ? next : undefined;
+  }
+  return { names, own: [], provenOwn: false };
+}
+
+/** Each written name's binding, as this project's checker answers it. */
+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`, 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" | "define" | "URL",
+  callee: Identifier,
+  symbol: Answer<TSSymbol> | undefined,
+): boolean {
+  const others = checkerBinding(project);
+  return callsPlatformBy(name, callee, (written) =>
+    written === callee ? boundBy(project, symbol) : others(written),
+  );
+}
+
+/**
+ * Whether a worker's constructor or `navigator`, the batch's answer for which is `symbol`, is
+ * the platform's (references-ts.2): a name the checker leaves unanswered, or one whose symbol
+ * is no alias and has a declaration outside the target's files.
+ */
+export function isPlatformGlobal<Brand>(
+  project: ProjectView<Brand>,
+  symbol: Answer<TSSymbol> | undefined,
+): boolean {
+  if (symbol === UNANSWERED) {
+    return true;
+  }
+  const own = project.ownPaths();
+  return (
+    symbol !== undefined &&
+    (symbol.flags & SymbolFlags.Alias) === 0 &&
+    symbol.declarations.some((handle) => !own.has(handle.path))
+  );
+}
+
+/** The module names Node's worker threads are imported by. */
+const THREADS: ReadonlySet<string> = new Set(["worker_threads", "node:worker_threads"]);
+
+function namesThreads(node: Node | undefined): boolean {
+  return node !== undefined && isStringLiteralLikeNode(node) && THREADS.has(node.text);
+}
+
+/** Whether one declaration is written in the body of `declare module "worker_threads"`. */
+function inThreadsModule(node: Node): boolean {
+  for (let at = node; !isSourceFile(at); at = at.parent) {
+    if (isModuleDeclaration(at) && namesThreads(at.name)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Whether a `Worker` constructor, the batch's answer for which is `symbol`, is Node's
+ * (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.
+ */
+export function startsThread<Brand>(
+  project: ProjectView<Brand>,
+  symbol: Answer<TSSymbol> | undefined,
+  holder: Answer<TSSymbol> | undefined,
+): boolean {
+  const bindingOf = checkerBinding(project);
+  const declared = (one: Answer<TSSymbol> | undefined, member: string): boolean =>
+    typeof one === "object" &&
+    ownDeclarations(project, one).some((node) =>
+      boundExports(node, (specifier) => THREADS.has(specifier), bindingOf).includes(member),
+    );
+  if (declared(symbol, "Worker") || declared(holder, NAMESPACE)) {
+    return true;
+  }
+  const named = typeof symbol === "object" ? dealiased(project, symbol) : undefined;
+  return (
+    typeof named === "object" &&
+    named.declarations.some((handle) => {
+      const node = project.declarationAt(handle)?.node;
+      return node !== undefined && inThreadsModule(node);
+    })
+  );
+}

package/src/position.ts

@@ -1,5 +1,6 @@
 import type { SourceFile } from "@typescript/native/ast";
 import { relativePath } from "./paths.ts";
+import { bytewise } from "./text/compare.ts";
 
 /**
  * Where one declaration is written, as every report renders it.
@@ -47,6 +48,48 @@ export function writtenLength(file: SourceFile): number {
   return isComponentFile(file) ? file.originalText.length : file.text.length;
 }
 
+/** Whether one character ends a line, under the language's line terminators. */
+function endsLine(char: string | undefined): boolean {
+  return char === "\n" || char === "\r" || char === "\u2028" || char === "\u2029";
+}
+
+/** The offset where the line holding `from` ends. */
+export function lineEnd(text: string, from: number): number {
+  let at = from;
+  while (at < text.length && !endsLine(text[at])) {
+    at += 1;
+  }
+  return at;
+}
+
+/**
+ * The offset of the first token at or after `from`: whitespace, comments and a leading
+ * hashbang are trivia.
+ */
+export function tokenStart(text: string, from: number): number {
+  let at = from;
+  if (at === 0 && text.startsWith("#!")) {
+    at = lineEnd(text, 0);
+  }
+  for (;;) {
+    if (/\s/u.test(text[at] ?? "")) {
+      at += 1;
+    } else if (text.startsWith("//", at)) {
+      at = lineEnd(text, at);
+    } else if (text.startsWith("/*", at)) {
+      const close = text.indexOf("*/", at + 2);
+      at = close < 0 ? text.length : close + 2;
+    } else {
+      return at;
+    }
+  }
+}
+
+/** The line, counted from one, of the first token at or after one offset of one file. */
+export function startLine(file: SourceFile, offset: number): number {
+  return file.getLineAndCharacterOfPosition(tokenStart(file.text, offset)).line + 1;
+}
+
 /**
  * The position of one offset of one file, rendered against the target root.
  *
@@ -87,7 +130,7 @@ export function positionKey(position: Position): string {
  */
 export function byPosition(a: Position, b: Position): number {
   if (a.path !== b.path) {
-    return a.path < b.path ? -1 : 1;
+    return bytewise(a.path, b.path);
   }
   if (a.line !== b.line) {
     return a.line - b.line;

package/src/print.ts

@@ -1,96 +1,16 @@
-import {
-  renderOrigin,
-  type Config,
-  type DeclarationEntry,
-  type Provenance,
-  type Provider,
-} from "./config.ts";
-
-/** One declaration entry as a document writes it: the members of its shape alone. */
-function declarationOf(entry: DeclarationEntry): Record<string, string> {
-  switch (entry.shape) {
-    case "symbol":
-      return { symbol: entry.symbol };
-    case "module":
-      return { module: entry.module, name: entry.name };
-    case "global":
-      return { global: entry.global };
-  }
-}
-
-/** One provider entry as a document writes it: the members of its shape alone. */
-function providerOf(entry: Provider): Record<string, unknown> {
-  const installed = { name: entry.name, languages: entry.languages, command: entry.command };
-  if (entry.shape === "installed") {
-    return installed;
-  }
-  return { ...installed, source: entry.source, version: entry.version, digest: entry.digest };
-}
+import { renderOrigin, type Provenance, type ResolvedConfig } from "./config.ts";
+import { bytewise } from "./text/compare.ts";
 
 /**
- * The resolved configuration and its provenance as one JSON object, indented,
- * ending in a newline.
- *
- * The output is an instance of the closed key list, so reading it back as a
- * repository configuration resolves to the same configuration: the provenance
- * object is a declared key resolution ignores. Keys are written in the schema's
- * order and the severity and provenance objects in ascending key order, so one
- * configuration renders to one string whatever order a source named its settings
- * in.
+ * The resolved configuration and its provenance as one JSON object, indented, ending
+ * in a newline: the configuration in the order resolution gives it, then the provenance
+ * object in ascending key order. Read back as a repository configuration it resolves to
+ * the same configuration, because resolution checks the provenance object and then
+ * ignores it.
  */
-export function printConfig(config: Config, provenance: Provenance): string {
-  const document = {
-    contract_version: config.contractVersion,
-    target: { kind: config.targetKind },
-    analysis: {
-      languages: config.analysis.languages,
-      min_confidence: config.analysis.minConfidence,
-      generated_files: config.analysis.generatedFiles,
-      consumer_tests: config.analysis.consumerTests,
-      configurations: config.analysis.configurations.map((entry) =>
-        entry.shape === "project"
-          ? { id: entry.id, project: entry.project }
-          : { id: entry.id, os: entry.os, arch: entry.arch, tags: entry.tags },
-      ),
-      matrix: { complete: config.analysis.matrixComplete },
-      template_dirs: config.analysis.templateDirs,
-      template_delimiters: {
-        left: config.analysis.templateDelimiters.left,
-        right: config.analysis.templateDelimiters.right,
-      },
-    },
-    consumers: { complete: config.consumersComplete },
-    roots: { patterns: config.rootPatterns },
-    severity: Object.fromEntries([...config.severity].sort(([a], [b]) => (a < b ? -1 : 1))),
-    exemptions: { disabled: config.exemptionsDisabled },
-    reporters: {
-      formats: config.reporters.formats,
-      sort: config.reporters.sort,
-      cascade: config.reporters.cascade,
-      max_findings: config.reporters.maxFindings,
-      fail_on: config.reporters.failOn,
-    },
-    providers: { analyzers: config.providers.analyzers.map(providerOf) },
-    go: {},
-    ts: {
-      test_files: config.ts.testFiles,
-      entry_files: config.ts.entryFiles,
-      component_extensions: config.ts.componentExtensions,
-      disabled_conventions: config.ts.disabledConventions,
-      injection_registrations: config.ts.injectionRegistrations.map(declarationOf),
-      lifecycle_contracts: config.ts.lifecycleContracts.map((entry) => ({
-        components: entry.components.map(declarationOf),
-        bases: entry.bases.map(declarationOf),
-        members: entry.members,
-      })),
-      serializers: config.ts.serializers.map(declarationOf),
-      roots_complete: config.ts.rootsComplete,
-    },
-    provenance: Object.fromEntries(
-      [...provenance]
-        .sort(([a], [b]) => (a < b ? -1 : 1))
-        .map(([path, origin]) => [path, renderOrigin(origin)]),
-    ),
-  };
-  return `${JSON.stringify(document, undefined, 2)}\n`;
+export function printConfig(config: ResolvedConfig, provenance: Provenance): string {
+  const origins = [...provenance]
+    .sort(([a], [b]) => bytewise(a, b))
+    .map(([path, origin]): [string, string] => [path, renderOrigin(origin)]);
+  return `${JSON.stringify({ ...config, provenance: Object.fromEntries(origins) }, undefined, 2)}\n`;
 }

package/src/product.ts

@@ -0,0 +1,18 @@
+import { LANGUAGE_ROWS } from "./contract/contract.generated.ts";
+import type { Writer } from "./run.ts";
+
+/** The language this analyzer reads. */
+export const LANGUAGE = "ts";
+
+/** The analyzer's name: the one its language's row names, which every output spells it with. */
+export const PRODUCT = LANGUAGE_ROWS[LANGUAGE].analyzer;
+
+/** Writes one diagnostic line to the error stream, named for the analyzer. */
+export function diagnose(err: Writer, text: string): void {
+  err.write(`${PRODUCT}: ${text}\n`);
+}
+
+/** The text one thrown value carries. */
+export function message(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/query.ts

@@ -207,10 +207,26 @@ export interface Queries {
   constraintOf(type: Type): Answer<Type | undefined>;
   /** The object and the index of an indexed-access type; none for another type. */
   indexedAccessOf(type: Type): Answer<{ readonly object: Type; readonly index: Type } | undefined>;
+  /**
+   * The types one type is spelled from besides its constituents, type arguments and members:
+   * a type parameter's constraint and default, a conditional's check, extends, true
+   * and false types, a mapped type's constraint, name and template, an indexed access's
+   * object and index, the operand of `keyof` or of a string mapping, a template literal's
+   * spans and a substitution's base and constraint. None for another type.
+   */
+  partsOf(type: Type): Answer<readonly Type[]>;
+  /** The type parameters of a signature, its `this` parameter's type and its predicate's type. */
+  signaturePartsOf(signature: Signature): Answer<readonly Type[]>;
   /** The symbol a type is declared by. */
   symbolOfType(type: Type): Answer<TSSymbol | undefined>;
+  /** The type alias a type was instantiated from, where it was. */
+  aliasSymbolOf(type: Type): Answer<TSSymbol | undefined>;
+  /** The type arguments the alias a type was instantiated from was given. */
+  aliasArgumentsOf(type: Type): Answer<readonly Type[]>;
   signaturesOf(type: Type, kind: SignatureKind): Answer<readonly Signature[]>;
   resolvedSignature(node: Node): Answer<Signature | undefined>;
+  /** The signature each call-like node resolves to. */
+  resolvedSignatures(nodes: readonly Node[], cap?: number): Answer<Signature | undefined>[];
   parameterType(signature: Signature, index: number): Answer<Type | undefined>;
   /** The generic signature an instantiated one instantiates; none for another signature. */
   genericOf(signature: Signature): Answer<Signature | undefined>;
@@ -221,6 +237,37 @@ export interface Queries {
   typeToString(type: Type): Answer<string>;
 }
 
+/** How to read the types one type is spelled from, as {@link Queries.partsOf} names them. */
+function partQuestion(type: Type): (() => readonly (Type | undefined)[]) | undefined {
+  if (type.isTypeParameter()) {
+    return () => [type.getConstraint(), type.getDefault()];
+  }
+  if (type.isConditionalType()) {
+    return () => [
+      type.getCheckType(),
+      type.getExtendsType(),
+      type.getTrueType(),
+      type.getFalseType(),
+    ];
+  }
+  if (type.isMappedType()) {
+    return () => [type.getConstraintType(), type.getNameType(), type.getTemplateType()];
+  }
+  if (type.isIndexedAccessType()) {
+    return () => [type.getObjectType(), type.getIndexType()];
+  }
+  if (type.isIndexType() || type.isStringMappingType()) {
+    return () => [type.getTarget()];
+  }
+  if (type.isTemplateLiteralType()) {
+    return () => type.getTypes();
+  }
+  if (type.isSubstitutionType()) {
+    return () => [type.getBaseType(), type.getConstraint()];
+  }
+  return undefined;
+}
+
 /**
  * The guarded questions over one project's checker. `configFile` names the project
  * in the log, `batch` sends many questions in one round trip, `log` is the run's,
@@ -526,12 +573,48 @@ export function queriesOf(
             () => ({ object: type.getObjectType(), index: type.getIndexType() }),
           )
         : undefined,
+    partsOf: (type) => {
+      const parts = partQuestion(type);
+      return parts === undefined
+        ? []
+        : one(
+            "getParts",
+            () => typeLocation(type),
+            () => parts().filter((part) => part !== undefined),
+          );
+    },
+    signaturePartsOf: (signature) =>
+      one(
+        "getSignatureParts",
+        () => `signature ${String(signature.id)}`,
+        () => {
+          const self =
+            signature.thisParameter === undefined ? undefined : signature.getThisParameter();
+          return [
+            ...((signature.typeParameters ?? []).length === 0 ? [] : signature.getTypeParameters()),
+            self === undefined ? undefined : checker.getTypeOfSymbol(self),
+            checker.getTypePredicateOfSignature(signature)?.type,
+          ].filter((part) => part !== undefined);
+        },
+      ),
     symbolOfType: (type) =>
       one(
         "getSymbol",
         () => typeLocation(type),
         () => type.getSymbol(),
       ),
+    aliasSymbolOf: (type) =>
+      one(
+        "getAliasSymbol",
+        () => typeLocation(type),
+        () => type.getAliasSymbol(),
+      ),
+    aliasArgumentsOf: (type) =>
+      one(
+        "getAliasTypeArguments",
+        () => typeLocation(type),
+        () => type.getAliasTypeArguments(),
+      ),
     signaturesOf: (type, kind) =>
       one(
         "getSignaturesOfType",
@@ -544,6 +627,15 @@ export function queriesOf(
         () => nodeLocation(node),
         () => checker.getResolvedSignature(node),
       ),
+    resolvedSignatures: (nodes, cap = DEFAULT_BATCH_CAP) =>
+      each(
+        "getResolvedSignature",
+        nodes,
+        cap,
+        nodeLocation,
+        (node) => checker.getResolvedSignature.gen(node),
+        (node) => checker.getResolvedSignature(node),
+      ),
     parameterType: (signature, index) =>
       one(
         "getParameterType",

package/src/ref.ts

@@ -1,13 +1,9 @@
 /**
- * The stable symbol reference: the identifier that names one declaration across
- * runs, across reports, in an ignore entry, in a configured root and in a
- * cross-language edge. It is built from names and containers only, so an edit above
- * a declaration leaves it unchanged, and it is compared as bytes, so there is one
- * canonical spelling per declaration and this module is where that spelling is
- * written.
- *
- * The position key of {@link ./position.ts} is the other identifier and has the
- * other job: it locates a finding inside one run, and the two never mix.
+ * The stable symbol reference: the identifier that names one declaration across runs,
+ * reports, ignore entries, configured roots and cross-language edges. It is built from
+ * names and containers only, so an edit above a declaration leaves it unchanged, and it
+ * is compared as bytes, so this module writes the one canonical spelling. The position
+ * key of {@link ./position.ts} locates a finding inside one run; the two never mix.
  */
 
 /** The language prefix, which namespaces every reference this analyzer emits. */
@@ -34,16 +30,10 @@ const SCOPE = `${PREFIX}${TS_PACKAGE}/${TS_FILE}`;
 const MANIFEST_SCOPE = `${PREFIX}${TS_PACKAGE}/${TS_DIRS}package\\.json`;
 
 /**
- * One expression per form the grammar defines, each anchored and each the whole of
- * a reference. Several forms share one expression because they differ in what the
- * symbol is rather than in how the reference is spelled, so the list is the set of
- * spellings and not the set of subjects. A reference is valid when it matches one.
- *
- * They are written here rather than read from the Contract at run time: the Contract
- * is data a reader outside this program consults, and a product that read it while
- * running would need it installed beside itself. A test compares this list against
- * the release this analyzer is written against, so a grammar that grows a form
- * arrives here as a failing test.
+ * One anchored expression per spelling the grammar defines; a reference is valid when it
+ * matches one. They are written here rather than read from the Contract at run time, so
+ * the product needs no Contract installed beside it; a test compares this list against
+ * the release this analyzer implements, so a grammar that grows a form fails it.
  */
 export const REF_EXPRESSIONS: readonly string[] = [
   `^${SCOPE}#$`,
@@ -52,6 +42,7 @@ export const REF_EXPRESSIONS: readonly string[] = [
   `^${SCOPE}#${TS_HEAD}:import$`,
   `^${SCOPE}#${TS_HEAD}(?:\\.${TS_MEMBER})+$`,
   `^${SCOPE}#${TS_HEAD}(?:\\.${TS_MEMBER})+:static$`,
+  `^${SCOPE}#${TS_HEAD}(?:\\.${TS_MEMBER})+\\.${TS_QUOTED}:case$`,
   `^${SCOPE}#${TS_HEAD}(?:\\.${TS_MEMBER})*(?::static)?<${TS_IDENT}>$`,
   `^${SCOPE}#(?:${TS_HEAD}(?:\\.${TS_MEMBER})*(?::static)?)?\\(${TS_IDENT}\\)$`,
   `^${MANIFEST_SCOPE}#${TS_PACKAGE}:(?:dependency|dev-dependency|peer-dependency)$`,
@@ -169,7 +160,8 @@ export function aliasFragment(name: string, block?: string): string {
   return `${head}${nameComponent(name)}:alias`;
 }
 
-function spell(component: Component): string {
+/** The canonical spelling of one component: a name, or a computed key. */
+export function spell(component: Component): string {
   return component.computed ? computedComponent(component.text) : nameComponent(component.text);
 }
 

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;
+}