@cplieger/deadset-ts 1.1.0 → 1.2.0

package/README.md

@@ -8,7 +8,7 @@ deadset-ts is a command-line analyzer for TypeScript and JavaScript projects. It
 
 deadset-ts is report-only. It never edits source, and it refuses any `--fix` flag.
 
-**Status: pre-release.** This version implements contract 1.5.0 and ships the analyzer's foundation: one compiler session per run over every `tsconfig` project discovered under the target (the explicit scope, every `tsconfig*.json`, each project's `references`), a fail-closed read of every project's diagnostics, configuration decoding against the contract's closed key list with `print-config` and its provenance, `print-projects`, and the report-only guard. `analyze` and `explain` are not implemented yet and exit with a usage message. The one runtime dependency is the `typescript` package at exactly 7.0.2, installed under the `@typescript/native` name until TypeScript 7.1 ships a compiler API the tooling can share. Running the command from an npm install under plain Node does not work yet, because Node does not strip types under `node_modules`; run it from a checkout or the JSR package until the command ships as JavaScript.
+**Status: pre-release.** This version implements contract 1.5.0 and ships the analyzer's foundation: one compiler session per run over every `tsconfig` project discovered under the target (the explicit scope, every `tsconfig*.json`, each project's `references`), a fail-closed read of every project's diagnostics, configuration decoding against the contract's closed key list with `print-config` and its provenance, `print-projects`, and the report-only guard. `analyze` and `explain` are not implemented yet and exit with a usage message. The one runtime dependency is the `typescript` package at exactly 7.0.2, installed under the `@typescript/native` name until TypeScript 7.1 ships a compiler API the tooling can share.
 
 ## Install
 
@@ -16,9 +16,11 @@ deadset-ts is report-only. It never edits source, and it refuses any `--fix` fla
 npm i -D @cplieger/deadset-ts
 # or
 npx jsr add -D @cplieger/deadset-ts
+# or run the command without installing it
+npx @cplieger/deadset-ts version
 ```
 
-The package ships TypeScript source, not compiled JavaScript: the `deadset-ts` command is a `.ts` file that Node.js 24 or later runs directly through its built-in type stripping, and the exported API is imported as source by the consumer's own compiler. There is no build step on either side.
+The package ships TypeScript source, not compiled JavaScript, and there is no build step on either side. The `deadset-ts` command runs on plain Node.js 24 or later; its entry strips the types of the package's own source itself, because Node refuses to do that for a file under `node_modules`. The exported API is source too, so a consumer compiles it with its own TypeScript, or imports it under Deno from the JSR package; plain Node cannot import it.
 
 ## Usage
 

package/bin/deadset-ts.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// Node refuses to strip types from a .ts file under node_modules, so the
+// TypeScript entry cannot start from an install. A load hook scoped to this
+// package's own files supplies the stripped source instead.
+// https://nodejs.org/api/typescript.html#type-stripping-in-dependencies
+import { readFileSync } from "node:fs";
+import { registerHooks, stripTypeScriptTypes } from "node:module";
+
+const packageRoot = new URL("../", import.meta.url).href;
+
+registerHooks({
+  load(url, context, nextLoad) {
+    if (!url.startsWith(packageRoot) || !url.endsWith(".ts")) {
+      return nextLoad(url, context);
+    }
+    return {
+      format: "module",
+      source: stripTypeScriptTypes(readFileSync(new URL(url), "utf8")),
+      shortCircuit: true,
+    };
+  },
+});
+
+await import("./deadset-ts.ts");

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "license": "GPL-3.0-or-later",
   "exports": {
     ".": "./src/index.ts"

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "sideEffects": false,
   "description": "Deterministic dead-code analysis for TypeScript, class and type members included",
   "license": "GPL-3.0-or-later",
   "bin": {
-    "deadset-ts": "./bin/deadset-ts.ts"
+    "deadset-ts": "./bin/deadset-ts.mjs"
   },
   "exports": {
     ".": "./src/index.ts"
@@ -29,6 +29,7 @@
     "@eslint/js": "10.0.1",
     "@types/node": "24.13.5",
     "eslint": "10.10.0",
+    "fast-check": "4.10.1",
     "prettier": "3.9.7",
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "typescript-eslint": "8.70.0",

package/src/index.ts

@@ -1,3 +1,29 @@
 export { run, SETTING_OPTIONS, type Writer } from "./run.ts";
 export type { DirectoryEntry, Host, PathKind } from "./host.ts";
+export {
+  inventory,
+  type Inventory,
+  type InventoryCost,
+  type InventorySymbol,
+  type SymbolKind,
+  type Visibility,
+} from "./inventory.ts";
+export {
+  byPosition,
+  positionKey,
+  PositionError,
+  renderPosition,
+  type Position,
+} from "./position.ts";
+export {
+  computedComponent,
+  isRef,
+  nameComponent,
+  REF_EXPRESSIONS,
+  renderRef,
+  type Component,
+  type DependencySection,
+  type Fragment,
+  type Module,
+} from "./ref.ts";
 export { CONTRACT_VERSION, version } from "./version.ts";

package/src/inventory.ts

@@ -0,0 +1,941 @@
+import {
+  isClassDeclaration,
+  isComputedPropertyName,
+  isEnumDeclaration,
+  isEnumMember,
+  isExportAssignment,
+  isExportDeclaration,
+  isFunctionDeclaration,
+  isGetAccessorDeclaration,
+  isIdentifier,
+  isInterfaceDeclaration,
+  isIntersectionTypeNode,
+  isMethodDeclaration,
+  isMethodSignatureDeclaration,
+  isModuleBlock,
+  isModuleDeclaration,
+  isNamespaceExport,
+  isPrivateIdentifier,
+  isPropertyDeclaration,
+  isPropertySignatureDeclaration,
+  isSetAccessorDeclaration,
+  isTypeAliasDeclaration,
+  isTypeLiteralNode,
+  isUnionTypeNode,
+  isVariableStatement,
+  ModifierFlags,
+  type Node,
+  type SourceFile,
+} from "@typescript/native/unstable/ast";
+import type { Symbol as TSSymbol } from "@typescript/native/unstable/sync";
+import type { Host } from "./host.ts";
+import { dirnamePath, joinPath, relativePath } from "./paths.ts";
+import { byPosition, positionKey, renderPosition, type Position } from "./position.ts";
+import { computedComponent, nameComponent, renderRef, type Component, type Module } from "./ref.ts";
+import type { Handle, ProjectView } from "./session.ts";
+
+/**
+ * The symbol inventory of one project: every declaration the target's own files
+ * hold, at its own position, with the container it belongs to and the reference
+ * that survives an edit above it.
+ *
+ * Two mechanisms produce it and neither is redundant. A container's symbol table is
+ * the binder's own answer, so it holds a member of a declaration that merges with
+ * another and it holds a member whatever its visibility, a private name included;
+ * a container's syntactic member list holds a member whose key is computed, which
+ * the binder resolves later and does not put in the table. The set is the union,
+ * keyed by the member's own reference component, so a member both sources name
+ * appears once.
+ */
+
+/**
+ * What one declaration is, from the vocabulary the Contract's finding schema
+ * closes. A Go rendering of the same vocabulary names other members of it; these
+ * are the ones a TypeScript declaration takes.
+ */
+export type SymbolKind =
+  | "file"
+  | "function"
+  | "class"
+  | "interface"
+  | "type"
+  | "enum"
+  | "namespace"
+  | "variable"
+  | "export-alias"
+  | "method"
+  | "class-member"
+  | "interface-method"
+  | "type-member"
+  | "enum-member"
+  | "type-parameter";
+
+/**
+ * How a member may be named from outside the container that declares it.
+ *
+ * The last two are two facts rather than one. A `private` modifier is a
+ * compile-time constraint only, so the member is still reachable at run time by its
+ * name through a string index, a decorator, a container or a serializer; a private
+ * name is not reachable by any of them, because the name does not exist outside the
+ * class body. An exemption class that finds its evidence in a name therefore
+ * applies to the first and never to the second, and the Contract's exemption
+ * vocabulary records that per class.
+ */
+export type Visibility = "public" | "protected" | "private" | "private-name";
+
+/** One declaration of the target. */
+export interface InventorySymbol {
+  /** The identifier of the declaration's own position, which the graph keys on. */
+  readonly id: string;
+  /** The stable symbol reference, which survives an edit above the declaration. */
+  readonly ref: string;
+  /**
+   * The display name a text line renders: the chain from the container inward, each
+   * component in the spelling a reference gives it, and the declared local name of a
+   * default export, whose reference carries its export name instead.
+   */
+  readonly name: string;
+  readonly kind: SymbolKind;
+  readonly position: Position;
+  /** The line the declaration ends on, so its size in source lines is readable. */
+  readonly endLine: number;
+  /** The container's id: the file for a module-level declaration, empty for a file. */
+  readonly parent: string;
+  /**
+   * Whether the export table of the module or namespace that holds the declaration
+   * names it. It is a fact about that one table, so it is false for every member of
+   * a class, an interface, a type or an enum and for every type parameter, whose
+   * reach outside its container is {@link InventorySymbol.visibility} and the state
+   * of the container the parent names.
+   */
+  readonly exported: boolean;
+  readonly visibility: Visibility;
+  /** Whether the declaration is a static member of a class. */
+  readonly static: boolean;
+}
+
+/** What one project's inventory cost at the client boundary. */
+export interface InventoryCost {
+  /** Batched symbol lookups. One pass over every module and container of the project. */
+  readonly batches: number;
+  /** Export-table reads: one per module and one per namespace. */
+  readonly exportTables: number;
+  /**
+   * Member-table reads: one per interface and enum, and two per class, because a
+   * class keeps its instance members and its static members in two tables. Never
+   * one per member.
+   */
+  readonly memberTables: number;
+}
+
+/** One project's declarations, in position order, and what reading them cost. */
+export interface Inventory {
+  /** The compiler configuration the project was opened from. */
+  readonly configFile: string;
+  readonly symbols: readonly InventorySymbol[];
+  readonly cost: InventoryCost;
+  /**
+   * The module specifiers of the bare star re-exports the project's files carry, in
+   * the order they were read. A bare star re-export declares nothing here: the names
+   * it carries forward are the declarations of the module it names, so it is a
+   * reference to that module and not a declaration of this one.
+   */
+  readonly starReExports: readonly string[];
+  /**
+   * The number of member declarations that were left out because the file declaring
+   * them is not one of the target's own files. Such a declaration belongs to another
+   * program, so the target's inventory does not name it, and the count is reported so
+   * that the omission is a number rather than a silence.
+   */
+  readonly outsideOwnFiles: number;
+}
+
+/** A declaration under construction, before its reference is rendered. */
+interface Building {
+  readonly file: SourceFile;
+  readonly node: Node;
+  readonly module: Module;
+  readonly position: Position;
+  endLine: number;
+  readonly kind: SymbolKind;
+  /** The chain of the container, without this declaration's own component. */
+  readonly parentChain: readonly Component[];
+  /**
+   * This declaration's own component. A default export's is its export name, which
+   * is where the component and the declared name part company.
+   */
+  readonly component: Component;
+  /** The declared name, where it is not what the component spells. */
+  readonly localName: string | undefined;
+  readonly parent: Building | undefined;
+  readonly visibility: Visibility;
+  readonly static: boolean;
+  exported: boolean;
+  /** The type parameter this declaration is, where it is one. */
+  readonly typeParameter: string | undefined;
+}
+
+/** A container whose members are read from a symbol table, from the tree, or both. */
+interface Container {
+  readonly owner: Building;
+  /** The container's name node, which is what a batch resolves to its symbol. */
+  readonly nameNode: Node | undefined;
+  readonly members: readonly Node[];
+  readonly memberKind: SymbolKind;
+  /** Whether the container is a class, whose static members are a second table. */
+  readonly isClass: boolean;
+  /** Whether the container keeps its members in the export table, as an enum does. */
+  readonly membersAreExports: boolean;
+}
+
+/** A module or namespace whose export table says which of its declarations it exports. */
+interface ExportScope {
+  readonly owner: Building;
+  readonly nameNode: Node;
+}
+
+const MANIFEST = "package.json";
+
+/** One manifest that names a package, and the directory below the root that holds it. */
+interface Named {
+  readonly name: string;
+  readonly at: string;
+}
+
+/**
+ * Resolves each file's package scope: the name of the nearest manifest at or above
+ * its directory up to the target root, and the file's path below that manifest.
+ * Where no manifest up to the root carries a name, the package is a single dot and
+ * the path is read from the root, which cannot collide, because a package name never
+ * starts with a dot.
+ *
+ * One directory is read at most once, because a package holds many files and a
+ * manifest read is a filesystem call.
+ */
+function packages(host: Host, root: string): (path: string) => Module {
+  const named = new Map<string, Named | undefined>();
+
+  const manifestName = (dir: string): string | undefined => {
+    let text: string;
+    try {
+      text = host.readFile(joinPath(root, dir, MANIFEST));
+    } catch {
+      return undefined;
+    }
+    let value: unknown;
+    try {
+      value = JSON.parse(text);
+    } catch {
+      // A manifest this program cannot read names no package, which is the same
+      // answer as an absent one: the file is then scoped by the target root.
+      return undefined;
+    }
+    if (typeof value !== "object" || value === null) {
+      return undefined;
+    }
+    const name = (value as Record<string, unknown>)["name"];
+    return typeof name === "string" && name !== "" ? name : undefined;
+  };
+
+  const nearest = (dir: string): Named | undefined => {
+    if (named.has(dir)) {
+      return named.get(dir);
+    }
+    const name = manifestName(dir);
+    const found =
+      name !== undefined ? { name, at: dir } : dir === "" ? undefined : nearest(parentOf(dir));
+    named.set(dir, found);
+    return found;
+  };
+
+  return (path) => {
+    const found = nearest(parentOf(path));
+    if (found === undefined) {
+      return { package: ".", path };
+    }
+    return { package: found.name, path: found.at === "" ? path : path.slice(found.at.length + 1) };
+  };
+}
+
+/** The directory one path below the root sits in, and the root itself as the empty path. */
+function parentOf(path: string): string {
+  const dir = dirnamePath(path);
+  return dir === "." ? "" : dir;
+}
+
+/** The modifier flags one node carries, and zero for a node that carries none. */
+function modifiersOf(node: Node): number {
+  return (node as { readonly modifierFlags?: number }).modifierFlags ?? 0;
+}
+
+/** The type parameters one node declares, and none for a node that declares none. */
+function typeParametersOf(node: Node): readonly Node[] {
+  if (
+    isFunctionDeclaration(node) ||
+    isMethodDeclaration(node) ||
+    isMethodSignatureDeclaration(node)
+  ) {
+    return node.typeParameters ?? [];
+  }
+  return [];
+}
+
+/**
+ * The reference component one declaration name node spells, and undefined for a
+ * name the grammar does not represent: a binding pattern, and a computed key whose
+ * source text carries a closing bracket.
+ */
+function componentOf(name: Node | undefined): Component | undefined {
+  if (name === undefined) {
+    return undefined;
+  }
+  if (isComputedPropertyName(name)) {
+    const text = name.expression.getText();
+    return text.includes("]") ? undefined : { text, computed: true };
+  }
+  if (isIdentifier(name) || isPrivateIdentifier(name)) {
+    return { text: name.getText(), computed: false };
+  }
+  if (isStringOrNumericName(name)) {
+    // A string or numeric key's own text carries its quotes and its numeric
+    // spelling; the reference carries the value, which the component then quotes.
+    return { text: literalTextOf(name), computed: false };
+  }
+  return undefined;
+}
+
+function isStringOrNumericName(name: Node): boolean {
+  const text = name.getText();
+  return (
+    text.startsWith('"') || text.startsWith("'") || text.startsWith("`") || /^[0-9]/u.test(text)
+  );
+}
+
+/** One member's identity inside its container: its component, and its side of a class. */
+function memberKey(component: Component, isStatic: boolean): string {
+  return `${component.computed ? "[" : ""}${component.text}${isStatic ? ":static" : ""}`;
+}
+
+/**
+ * The members one type alias declares: the members of the object type it writes, and
+ * of every object type that is a direct constituent of a union or an intersection it
+ * writes. A constituent naming another type declares nothing here, because that
+ * declaration carries its own members.
+ *
+ * A name two constituents both declare is left out of all of them. The alias stands
+ * for such a member, because the two declarations are one member of the type and
+ * neither of them is the one a reference to it would name.
+ */
+function aliasMembers(type: Node): readonly Node[] {
+  const literals = isTypeLiteralNode(type)
+    ? [type]
+    : isUnionTypeNode(type) || isIntersectionTypeNode(type)
+      ? type.types.filter(isTypeLiteralNode)
+      : [];
+  if (literals.length < 2) {
+    return literals[0]?.members ?? [];
+  }
+
+  const declaring = new Map<string, number>();
+  for (const literal of literals) {
+    for (const key of new Set(literal.members.map(keyOf))) {
+      if (key !== undefined) {
+        declaring.set(key, (declaring.get(key) ?? 0) + 1);
+      }
+    }
+  }
+  return literals.flatMap((literal) =>
+    literal.members.filter((member) => {
+      const key = keyOf(member);
+      return key !== undefined && declaring.get(key) === 1;
+    }),
+  );
+}
+
+/** One type member's identity, and undefined for a member the grammar cannot name. */
+function keyOf(member: Node): string | undefined {
+  const component = componentOf(nameNodeOf(member));
+  return component === undefined ? undefined : memberKey(component, false);
+}
+
+/** The value one string or numeric key denotes, which is what the reference names. */
+function literalTextOf(name: Node): string {
+  const text = name.getText();
+  if (text.startsWith('"') || text.startsWith("'") || text.startsWith("`")) {
+    return text.slice(1, -1);
+  }
+  return text;
+}
+
+/**
+ * The component one declaration's reference carries, and its declared name where the
+ * two differ.
+ *
+ * A declaration its module exports as the default is named `default`, because that is
+ * its export name and a module has at most one, so the spelling is unambiguous and it
+ * holds for an anonymous declaration too. Its declared name is a fact about the source
+ * rather than about the export, so it travels beside the component as the display name.
+ */
+function exportedAs(
+  node: Node,
+  name: Node | undefined,
+): { readonly component: Component | undefined; readonly localName: string | undefined } {
+  const declared = componentOf(name);
+  if ((modifiersOf(node) & ModifierFlags.Default) === 0) {
+    return { component: declared, localName: undefined };
+  }
+  return { component: { text: "default", computed: false }, localName: declared?.text };
+}
+
+/** The visibility one member declaration's modifiers and name give it. */
+function visibilityOf(node: Node, name: Node | undefined): Visibility {
+  if (name !== undefined && isPrivateIdentifier(name)) {
+    return "private-name";
+  }
+  const flags = modifiersOf(node);
+  if ((flags & ModifierFlags.Private) !== 0) {
+    return "private";
+  }
+  if ((flags & ModifierFlags.Protected) !== 0) {
+    return "protected";
+  }
+  return "public";
+}
+
+/** The name node of one declaration, for the kinds that carry one. */
+function nameNodeOf(node: Node): Node | undefined {
+  return (node as { readonly name?: Node }).name;
+}
+
+/** One node's identity across the two mechanisms, which resolve it separately. */
+function nodeKey(file: SourceFile, node: Node): string {
+  return `${file.fileName}:${String(node.pos)}:${String(node.end)}`;
+}
+
+/** The kind a class element takes: a method, or a property or accessor. */
+function classMemberKind(node: Node): SymbolKind {
+  return isMethodDeclaration(node) ? "method" : "class-member";
+}
+
+/** The kind a type element takes: a method of an interface, or any other member. */
+function typeMemberKind(node: Node, inInterface: boolean): SymbolKind {
+  return inInterface && isMethodSignatureDeclaration(node) ? "interface-method" : "type-member";
+}
+
+/**
+ * Every declaration one project's own files hold.
+ *
+ * `targetRoot` is the absolute path every position is rendered against; a file the
+ * program holds that is not below it ends the enumeration rather than being passed
+ * over. `host` is the filesystem the manifests that name each file's package are
+ * read through, and nothing else is read from it.
+ *
+ * The order is by rendered position, so two enumerations of one project return the
+ * same list whatever order the program reported its files in.
+ */
+export function inventory<Brand>(
+  project: ProjectView<Brand>,
+  host: Host,
+  targetRoot: string,
+): Inventory {
+  const files = project.ownSourceFiles();
+  const ownFiles = new Set(files.map((file) => file.fileName));
+  const moduleOf = packages(host, targetRoot);
+
+  const building: Building[] = [];
+  const byNode = new Map<string, Building>();
+  const exportScopes: ExportScope[] = [];
+  const containers: Container[] = [];
+  const starReExports: string[] = [];
+  let outsideOwnFiles = 0;
+
+  const keep = (record: Building): Building => {
+    building.push(record);
+    byNode.set(nodeKey(record.file, record.node), record);
+    return record;
+  };
+
+  for (const file of files) {
+    const path = relativePath(targetRoot, file.fileName);
+    if (path === undefined) {
+      // renderPosition states the refusal, with the root it was rendered against.
+      renderPosition(file, targetRoot, 0);
+      continue;
+    }
+    const module = moduleOf(path);
+    const fileRecord = keep({
+      file,
+      node: file,
+      module,
+      position: renderPosition(file, targetRoot, 0),
+      endLine: renderPosition(file, targetRoot, Math.max(file.end - 1, 0)).line,
+      kind: "file",
+      parentChain: [],
+      // A file's reference names its module, so no component of it is ever spelled;
+      // the path is what a text line renders for it.
+      component: { text: path, computed: false },
+      localName: path,
+      parent: undefined,
+      visibility: "public",
+      static: false,
+      exported: false,
+      typeParameter: undefined,
+    });
+    exportScopes.push({ owner: fileRecord, nameNode: file });
+    walkStatements(file.statements, fileRecord);
+  }
+
+  /** One declaration of a module, a namespace or a container body. */
+  function walkStatements(statements: readonly Node[], owner: Building): void {
+    for (const statement of statements) {
+      walkStatement(statement, owner);
+    }
+  }
+
+  function declare(
+    node: Node,
+    owner: Building,
+    kind: SymbolKind,
+    name: Node | undefined,
+    named: { readonly component: Component; readonly localName: string | undefined },
+  ): Building {
+    const at = name ?? node;
+    const record = keep({
+      file: owner.file,
+      node,
+      module: owner.module,
+      position: renderPosition(owner.file, targetRoot, at.getStart()),
+      endLine: renderPosition(owner.file, targetRoot, Math.max(node.end - 1, 0)).line,
+      kind,
+      parentChain: owner.kind === "file" ? [] : chainOf(owner),
+      component: named.component,
+      localName: named.localName,
+      parent: owner,
+      visibility: visibilityOf(node, name),
+      static: (modifiersOf(node) & ModifierFlags.Static) !== 0,
+      exported: false,
+      typeParameter: undefined,
+    });
+    declareTypeParameters(node, record);
+    return record;
+  }
+
+  function declareTypeParameters(node: Node, owner: Building): void {
+    for (const parameter of typeParametersOf(node)) {
+      const name = nameNodeOf(parameter);
+      if (name === undefined) {
+        continue;
+      }
+      keep({
+        file: owner.file,
+        node: parameter,
+        module: owner.module,
+        position: renderPosition(owner.file, targetRoot, name.getStart()),
+        endLine: renderPosition(owner.file, targetRoot, Math.max(parameter.end - 1, 0)).line,
+        kind: "type-parameter",
+        parentChain: owner.parentChain,
+        component: owner.component,
+        localName: undefined,
+        parent: owner,
+        visibility: "public",
+        static: owner.static,
+        exported: false,
+        typeParameter: name.getText(),
+      });
+    }
+  }
+
+  function walkStatement(node: Node, owner: Building): void {
+    if (isFunctionDeclaration(node)) {
+      const named = exportedAs(node, node.name);
+      if (named.component !== undefined) {
+        declare(node, owner, "function", node.name, { ...named, component: named.component });
+      }
+      return;
+    }
+    if (isClassDeclaration(node)) {
+      const named = exportedAs(node, node.name);
+      if (named.component === undefined) {
+        return;
+      }
+      const record = declare(node, owner, "class", node.name, {
+        ...named,
+        component: named.component,
+      });
+      containers.push({
+        owner: record,
+        nameNode: node.name,
+        members: node.members,
+        memberKind: "class-member",
+        isClass: true,
+        membersAreExports: false,
+      });
+      return;
+    }
+    if (isInterfaceDeclaration(node)) {
+      const named = exportedAs(node, node.name);
+      if (named.component === undefined) {
+        return;
+      }
+      const record = declare(node, owner, "interface", node.name, {
+        ...named,
+        component: named.component,
+      });
+      containers.push({
+        owner: record,
+        nameNode: node.name,
+        members: node.members,
+        memberKind: "interface-method",
+        isClass: false,
+        membersAreExports: false,
+      });
+      return;
+    }
+    if (isTypeAliasDeclaration(node)) {
+      const named = exportedAs(node, node.name);
+      if (named.component === undefined) {
+        return;
+      }
+      const record = declare(node, owner, "type", node.name, {
+        ...named,
+        component: named.component,
+      });
+      // A type alias keeps no member table of its own: the members belong to the
+      // object types its declaration writes, so the declaration is what carries them.
+      const members = aliasMembers(node.type);
+      if (members.length > 0) {
+        containers.push({
+          owner: record,
+          nameNode: undefined,
+          members,
+          memberKind: "type-member",
+          isClass: false,
+          membersAreExports: false,
+        });
+      }
+      return;
+    }
+    if (isEnumDeclaration(node)) {
+      const named = exportedAs(node, node.name);
+      if (named.component === undefined) {
+        return;
+      }
+      const record = declare(node, owner, "enum", node.name, {
+        ...named,
+        component: named.component,
+      });
+      containers.push({
+        owner: record,
+        nameNode: node.name,
+        members: node.members,
+        memberKind: "enum-member",
+        isClass: false,
+        membersAreExports: true,
+      });
+      return;
+    }
+    if (isModuleDeclaration(node)) {
+      const component = componentOf(node.name);
+      if (component === undefined) {
+        return;
+      }
+      const record = declare(node, owner, "namespace", node.name, {
+        component,
+        localName: undefined,
+      });
+      exportScopes.push({ owner: record, nameNode: node.name });
+      const body = node.body;
+      if (body === undefined) {
+        return;
+      }
+      if (isModuleBlock(body)) {
+        walkStatements(body.statements, record);
+        return;
+      }
+      walkStatement(body, record);
+      return;
+    }
+    if (isVariableStatement(node)) {
+      for (const declaration of node.declarationList.declarations) {
+        const component = componentOf(declaration.name);
+        if (component === undefined) {
+          // A destructuring pattern declares binding elements, which the reference
+          // grammar does not represent; the statement stands for them.
+          continue;
+        }
+        declare(declaration, owner, "variable", declaration.name, {
+          component,
+          localName: undefined,
+        });
+      }
+      return;
+    }
+    if (isExportDeclaration(node)) {
+      walkExportDeclaration(node, owner);
+      return;
+    }
+    if (isExportAssignment(node) && !node.isExportEquals) {
+      declare(node, owner, "export-alias", undefined, {
+        component: { text: "default", computed: false },
+        localName: undefined,
+      });
+    }
+  }
+
+  function walkExportDeclaration(
+    node: { readonly exportClause?: Node; readonly moduleSpecifier?: Node },
+    owner: Building,
+  ): void {
+    const clause = node.exportClause;
+    if (clause === undefined) {
+      const specifier = node.moduleSpecifier;
+      starReExports.push(specifier === undefined ? "" : literalTextOf(specifier));
+      return;
+    }
+    if (isNamespaceExport(clause)) {
+      const component = componentOf(clause.name);
+      if (component !== undefined) {
+        declare(clause, owner, "export-alias", clause.name, { component, localName: undefined });
+      }
+      return;
+    }
+    for (const element of (clause as { readonly elements?: readonly Node[] }).elements ?? []) {
+      const name = nameNodeOf(element);
+      const component = componentOf(name);
+      if (component !== undefined) {
+        declare(element, owner, "export-alias", name, { component, localName: undefined });
+      }
+    }
+  }
+
+  // One batch for every module and every container the walk found, because a
+  // checker accessor with an array overload costs one round trip for the batch and
+  // one per node without it.
+  const batched: Node[] = [
+    ...exportScopes.map((scope) => scope.nameNode),
+    ...containers.map((container) => container.nameNode).filter((node) => node !== undefined),
+  ];
+  const handles: Handle<Brand>[] = batched.map((node) => project.handle(node));
+  const resolved = project.symbolsAt(handles);
+  const symbolOf = new Map<Node, TSSymbol>();
+  batched.forEach((node, index) => {
+    const symbol = resolved[index];
+    if (symbol !== undefined) {
+      symbolOf.set(node, symbol);
+    }
+  });
+
+  let exportTables = 0;
+  for (const scope of exportScopes) {
+    const symbol = symbolOf.get(scope.nameNode);
+    if (symbol === undefined) {
+      continue;
+    }
+    exportTables += 1;
+    for (const [, exported] of symbol.getExports()) {
+      for (const declaration of exported.declarations) {
+        const held = project.declarationAt(declaration);
+        if (held === undefined) {
+          continue;
+        }
+        const record = byNode.get(nodeKey(held.node.getSourceFile(), held.node));
+        if (record === undefined) {
+          continue;
+        }
+        record.exported = true;
+      }
+    }
+  }
+
+  let memberTables = 0;
+  for (const container of containers) {
+    const symbol = container.nameNode === undefined ? undefined : symbolOf.get(container.nameNode);
+    const seen = new Map<string, Building>();
+    if (symbol !== undefined) {
+      if (!container.membersAreExports) {
+        memberTables += 1;
+        outsideOwnFiles += readTable(container, symbol.getMembers(), seen, false);
+      }
+      if (container.membersAreExports || container.isClass) {
+        memberTables += 1;
+        outsideOwnFiles += readTable(container, symbol.getExports(), seen, container.isClass);
+      }
+    }
+    completeFromTree(container, seen);
+  }
+
+  /**
+   * One container's members as its symbol table holds them, each positioned at the
+   * declaration the table names. A member with no declaration is the language's own
+   * (a class's `prototype`), and a member declared outside the target's own files
+   * belongs to another program; neither is a declaration of the target.
+   */
+  function readTable(
+    container: Container,
+    table: ReadonlyMap<string, TSSymbol>,
+    seen: Map<string, Building>,
+    areStatic: boolean,
+  ): number {
+    let outside = 0;
+    for (const [, member] of table) {
+      const declarations = member.declarations
+        .map((handle) => project.declarationAt(handle))
+        .filter((held): held is Handle<Brand> => held !== undefined);
+      if (declarations.length === 0) {
+        continue;
+      }
+      const own = declarations.filter((held) => ownFiles.has(held.node.getSourceFile().fileName));
+      if (own.length === 0) {
+        outside += declarations.length;
+        continue;
+      }
+      for (const held of own) {
+        keepMember(container, held.node, seen, areStatic);
+      }
+    }
+    return outside;
+  }
+
+  /**
+   * One container's members as its own declaration writes them, for the members its
+   * symbol table does not hold: a member whose key is computed is bound to the
+   * container's type later than the table is built.
+   */
+  function completeFromTree(container: Container, seen: Map<string, Building>): void {
+    for (const member of container.members) {
+      keepMember(container, member, seen, (modifiersOf(member) & ModifierFlags.Static) !== 0);
+    }
+  }
+
+  function keepMember(
+    container: Container,
+    node: Node,
+    seen: Map<string, Building>,
+    areStatic: boolean,
+  ): void {
+    const kind = memberKindOf(container, node);
+    if (kind === undefined) {
+      return;
+    }
+    const name = nameNodeOf(node);
+    const component = componentOf(name);
+    if (component === undefined) {
+      return;
+    }
+    const file = node.getSourceFile();
+    const key = memberKey(component, areStatic);
+    const held = seen.get(key);
+    const endLine = renderPosition(file, targetRoot, Math.max(node.end - 1, 0)).line;
+    if (held !== undefined) {
+      // A getter and a setter of one name are one symbol and one reference, so the
+      // second declaration widens the first record rather than making a second.
+      held.endLine = Math.max(held.endLine, endLine);
+      return;
+    }
+    const at = name ?? node;
+    const record = keep({
+      file,
+      node,
+      module: container.owner.module,
+      position: renderPosition(file, targetRoot, at.getStart()),
+      endLine,
+      kind,
+      parentChain: chainOf(container.owner),
+      component,
+      localName: undefined,
+      parent: container.owner,
+      visibility: visibilityOf(node, name),
+      static: areStatic,
+      exported: false,
+      typeParameter: undefined,
+    });
+    seen.set(key, record);
+    declareTypeParameters(node, record);
+  }
+
+  function memberKindOf(container: Container, node: Node): SymbolKind | undefined {
+    if (container.isClass) {
+      if (
+        isPropertyDeclaration(node) ||
+        isMethodDeclaration(node) ||
+        isGetAccessorDeclaration(node) ||
+        isSetAccessorDeclaration(node)
+      ) {
+        return classMemberKind(node);
+      }
+      return undefined;
+    }
+    if (container.memberKind === "enum-member") {
+      return isEnumMember(node) ? "enum-member" : undefined;
+    }
+    if (isPropertySignatureDeclaration(node) || isMethodSignatureDeclaration(node)) {
+      return typeMemberKind(node, container.memberKind === "interface-method");
+    }
+    if (isGetAccessorDeclaration(node) || isSetAccessorDeclaration(node)) {
+      return "type-member";
+    }
+    return undefined;
+  }
+
+  const symbols = building
+    .map(render)
+    .sort((a, b) => byPosition(a.position, b.position) || (a.ref < b.ref ? -1 : 1));
+
+  return {
+    configFile: project.configFile,
+    symbols,
+    cost: { batches: 1, exportTables, memberTables },
+    starReExports,
+    outsideOwnFiles,
+  };
+}
+
+/** The chain of components that names one declaration, read from the module inward. */
+function chainOf(record: Building): readonly Component[] {
+  return [...record.parentChain, record.component];
+}
+
+/**
+ * One declaration as the inventory reports it. The display name is the chain in the
+ * spelling a reference gives it, except where the declaration carries a name of its
+ * own the reference does not: a file, whose reference names its module, and a default
+ * export, whose reference carries its export name.
+ */
+function render(record: Building): InventorySymbol {
+  const chain = chainOf(record);
+  const spelled = chain
+    .map((component) =>
+      component.computed ? computedComponent(component.text) : nameComponent(component.text),
+    )
+    .join(".");
+  const name =
+    record.localName ??
+    (record.typeParameter === undefined ? spelled : `${spelled}<${record.typeParameter}>`);
+  return {
+    id: positionKey(record.position),
+    ref: refOf(record, chain),
+    name,
+    kind: record.kind,
+    position: record.position,
+    endLine: record.endLine,
+    parent: record.parent === undefined ? "" : positionKey(record.parent.position),
+    exported: record.exported,
+    visibility: record.visibility,
+    static: record.static,
+  };
+}
+
+function refOf(record: Building, chain: readonly Component[]): string {
+  if (record.kind === "file") {
+    return renderRef(record.module, { of: "module" });
+  }
+  if (record.kind === "export-alias") {
+    return renderRef(record.module, { of: "alias", name: record.component.text });
+  }
+  return renderRef(record.module, {
+    of: "declaration",
+    chain,
+    static: record.static,
+    ...(record.typeParameter === undefined ? {} : { typeParameter: record.typeParameter }),
+  });
+}

package/src/paths.ts

@@ -71,3 +71,23 @@ export function dirnamePath(path: string): string {
 export function resolvePath(against: string, path: string): string {
   return isAbsolutePath(path) ? normalizePath(path) : joinPath(against, path);
 }
+
+/**
+ * One path as it reads below a root, or undefined when it is not below the root.
+ * Both are normalized first, so a root written with a trailing separator or a `.`
+ * segment reaches the same answer, and the comparison is then lexical, so a root
+ * and a path spelled through different symbolic links name nothing in common. The
+ * root itself is not below itself.
+ *
+ * The caller resolves both against the same directory before calling: a relative
+ * root and an absolute path are two spellings this cannot reconcile.
+ */
+export function relativePath(root: string, path: string): string | undefined {
+  const at = normalizePath(root);
+  const prefix = at.endsWith(SEPARATOR) ? at : at + SEPARATOR;
+  const under = normalizePath(path);
+  if (!under.startsWith(prefix) || under.length === prefix.length) {
+    return undefined;
+  }
+  return under.slice(prefix.length);
+}

package/src/position.ts

@@ -0,0 +1,75 @@
+import type { SourceFile } from "@typescript/native/unstable/ast";
+import { relativePath } from "./paths.ts";
+
+/**
+ * Where one declaration is written, as every report renders it.
+ *
+ * The column counts UTF-16 code units, which is the unit the SARIF specification
+ * and the Language Server Protocol count in, and which is also the unit the
+ * compiler's own positions are measured in, so no conversion stands between the
+ * two.
+ */
+export interface Position {
+  /** The declaring file's path below the target root, with the solidus as separator. */
+  readonly path: string;
+  /** The line the declaration starts on, counted from one. */
+  readonly line: number;
+  /** The column, counted from one in UTF-16 code units. */
+  readonly column: number;
+}
+
+/**
+ * A file the program holds whose path is not below the target root, which leaves
+ * the analysis unable to name a declaration it found. It ends the run rather than
+ * being passed over, so a position that does not render is never silently dropped.
+ */
+export class PositionError extends Error {
+  /** The file as the program named it. */
+  readonly file: string;
+
+  constructor(file: string, root: string) {
+    super(`${file} is not below ${root}`);
+    this.name = "PositionError";
+    this.file = file;
+  }
+}
+
+/**
+ * The position of one offset of one file, rendered against the target root.
+ *
+ * `offset` is a UTF-16 code unit offset into the file's text, which is what every
+ * node of the tree carries.
+ */
+export function renderPosition(file: SourceFile, root: string, offset: number): Position {
+  const path = relativePath(root, file.fileName);
+  if (path === undefined) {
+    throw new PositionError(file.fileName, root);
+  }
+  const { line, character } = file.getLineAndCharacterOfPosition(offset);
+  return { path, line: line + 1, column: character + 1 };
+}
+
+/**
+ * The identifier of the declaration written at one position: the path, the line and
+ * the column joined by colons. It is what the graph keys on inside one run, and
+ * what the configuration intersection compares across projects, because a handle is
+ * meaningful only inside the program that produced it while a rendered position is
+ * meaningful anywhere.
+ */
+export function positionKey(position: Position): string {
+  return `${position.path}:${String(position.line)}:${String(position.column)}`;
+}
+
+/**
+ * Two positions ordered by file, line and column, which is the order the inventory
+ * reads in and the order every set of a run is reported in.
+ */
+export function byPosition(a: Position, b: Position): number {
+  if (a.path !== b.path) {
+    return a.path < b.path ? -1 : 1;
+  }
+  if (a.line !== b.line) {
+    return a.line - b.line;
+  }
+  return a.column - b.column;
+}

package/src/ref.ts

@@ -0,0 +1,179 @@
+/**
+ * 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 language prefix, which namespaces every reference this analyzer emits. */
+const PREFIX = "ts://";
+
+/**
+ * The building blocks of the reference grammar, spelled in the intersection of the
+ * two regular-expression dialects a reference is checked in: Go's `regexp` and an
+ * ECMAScript `RegExp` with no flags. Neither dialect offers a Unicode identifier
+ * property without a flag, so a character outside ASCII is admitted as a class;
+ * the expressions check the form of a reference and never validate a name, because
+ * the compiler that accepted the declaration has already validated it.
+ */
+const TS_IDENT = String.raw`(?:[A-Za-z_$]|[^\x00-\x7F])(?:[A-Za-z0-9_$]|[^\x00-\x7F])*`;
+const TS_QUOTED = String.raw`'(?:[^'\\\r\n]|\\['\\nr])*'`;
+const TS_COMPUTED = String.raw`\[[^\]\r\n\t ]+\]`;
+const TS_HEAD = `(?:${TS_IDENT}|${TS_QUOTED})`;
+const TS_MEMBER = `(?:${TS_IDENT}|#${TS_IDENT}|${TS_QUOTED}|${TS_COMPUTED})`;
+const TS_PACKAGE = String.raw`(?:@[A-Za-z0-9._-]+/)?[A-Za-z0-9._-]+`;
+const TS_FILE = String.raw`(?:[^/#\r\n]+/)*[^/#\r\n]+(?:(?:\.d)?\.[mc]?ts|\.tsx|\.[mc]?js|\.jsx)`;
+
+const SCOPE = `${PREFIX}${TS_PACKAGE}/${TS_FILE}`;
+const MANIFEST_SCOPE = `${PREFIX}${TS_PACKAGE}/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.
+ */
+export const REF_EXPRESSIONS: readonly string[] = [
+  `^${SCOPE}#$`,
+  `^${SCOPE}#${TS_HEAD}$`,
+  `^${SCOPE}#${TS_HEAD}:alias$`,
+  `^${SCOPE}#${TS_HEAD}(?:\\.${TS_MEMBER})+$`,
+  `^${SCOPE}#${TS_HEAD}(?:\\.${TS_MEMBER})+:static$`,
+  `^${SCOPE}#${TS_HEAD}(?:\\.${TS_MEMBER})*(?::static)?<${TS_IDENT}>$`,
+  `^${MANIFEST_SCOPE}#${TS_PACKAGE}:(?:dependency|dev-dependency|peer-dependency)$`,
+];
+
+const REF_FORMS: readonly RegExp[] = REF_EXPRESSIONS.map(
+  (expression) => new RegExp(expression, "u"),
+);
+
+const IDENTIFIER = new RegExp(`^${TS_IDENT}$`, "u");
+const PRIVATE_NAME = new RegExp(`^#${TS_IDENT}$`, "u");
+const ASCII_WHITESPACE = /[\t\n\v\f\r ]/gu;
+
+/** The section of a manifest that declares a dependency. */
+export type DependencySection = "dependency" | "dev-dependency" | "peer-dependency";
+
+/** The scope half of a reference: the package a file belongs to, and its path in it. */
+export interface Module {
+  /**
+   * The name of the package the file belongs to, or a single dot where no manifest
+   * at or above it up to the target root carries one. The two cannot collide,
+   * because a package name never starts with a dot.
+   */
+  readonly package: string;
+  /** The file's path inside that package, with its own extension. */
+  readonly path: string;
+}
+
+/**
+ * One component of a fragment: a declared name, or the source text of a computed
+ * key. The two are spelled differently and cannot be told apart from the text
+ * alone, so the caller says which it has.
+ */
+export interface Component {
+  /** The declared name, or the source text between the brackets of a computed key. */
+  readonly text: string;
+  /** Whether the text is a computed key rather than a name. */
+  readonly computed: boolean;
+}
+
+/** What one reference's fragment names. */
+export type Fragment =
+  /** The module itself, which is the parent of every module-level declaration. */
+  | { readonly of: "module" }
+  /**
+   * One declaration, named by the chain of components from the module inward with
+   * its own last. A static member of a class is always marked, whether or not the
+   * class also declares an instance member of that name, so the spelling does not
+   * depend on what else the class declares. A type parameter is the declaring
+   * function's or method's own chain followed by the parameter's name.
+   */
+  | {
+      readonly of: "declaration";
+      readonly chain: readonly Component[];
+      readonly static: boolean;
+      readonly typeParameter?: string;
+    }
+  /** One export specifier, a symbol of its own beside the declaration it names. */
+  | { readonly of: "alias"; readonly name: string }
+  /** One dependency of a manifest, scoped by that manifest. */
+  | { readonly of: "dependency"; readonly name: string; readonly section: DependencySection };
+
+/**
+ * The canonical spelling of one declared name as a fragment component: bare when
+ * the name is an identifier name, reserved words included; with its leading number
+ * sign kept when the name is a private name, because the sign is part of the name
+ * in the language and a class may declare both spellings side by side; and in
+ * single quotes otherwise. The quotes are single so that a reference sits inside a
+ * JSON string with no escaping, which is where every document carries one.
+ */
+export function nameComponent(name: string): string {
+  if (IDENTIFIER.test(name) || PRIVATE_NAME.test(name)) {
+    return name;
+  }
+  const escaped = name
+    .replaceAll("\\", "\\\\")
+    .replaceAll("'", "\\'")
+    .replaceAll("\n", "\\n")
+    .replaceAll("\r", "\\r");
+  return `'${escaped}'`;
+}
+
+/**
+ * The canonical spelling of one computed key: its source text between square
+ * brackets with every ASCII whitespace character removed. The text is compared as
+ * written, so two spellings of one well-known symbol are two references, which is
+ * right, because they are two declarations.
+ */
+export function computedComponent(text: string): string {
+  return `[${text.replaceAll(ASCII_WHITESPACE, "")}]`;
+}
+
+function spell(component: Component): string {
+  return component.computed ? computedComponent(component.text) : nameComponent(component.text);
+}
+
+/**
+ * The reference of one symbol. The chain of a declaration fragment is read from the
+ * module-level declaration inward and is never empty; the module fragment is what
+ * names the module itself.
+ */
+export function renderRef(module: Module, fragment: Fragment): string {
+  const scope = `${PREFIX}${module.package}/${module.path}`;
+  switch (fragment.of) {
+    case "module":
+      return `${scope}#`;
+    case "alias":
+      return `${scope}#${nameComponent(fragment.name)}:alias`;
+    case "dependency":
+      return `${scope}#${fragment.name}:${fragment.section}`;
+    case "declaration": {
+      const chain = fragment.chain.map(spell).join(".");
+      const isStatic = fragment.static ? ":static" : "";
+      const parameter = fragment.typeParameter === undefined ? "" : `<${fragment.typeParameter}>`;
+      return `${scope}#${chain}${isStatic}${parameter}`;
+    }
+  }
+}
+
+/**
+ * Whether one string is a reference of this language's grammar, in its canonical
+ * spelling. A string that is not, whether misspelled or spelled in a form the
+ * grammar does not define, matches no symbol; a reference of another language is
+ * not one of this language's either, which is what the language prefix is for.
+ */
+export function isRef(value: string): boolean {
+  return REF_FORMS.some((form) => form.test(value));
+}

package/src/session.ts

@@ -3,6 +3,7 @@ import type {
   Checker,
   Diagnostic,
   DocumentIdentifier,
+  NodeHandle,
   Project,
   Program,
   Snapshot,
@@ -101,6 +102,17 @@ export interface ProjectView<Brand> {
    * resolve.
    */
   symbolsAt(handles: readonly Handle<Brand>[]): readonly (TSSymbol | undefined)[];
+  /**
+   * The node one symbol's declaration handle names, read in this project's program,
+   * or `undefined` where this project's program does not hold that file.
+   *
+   * A symbol is shared by every project of the snapshot and remembers the project it
+   * was first seen in, so resolving its handle without saying which program to read
+   * would answer out of whichever project reached the symbol first. The project is
+   * named here instead, and the answer becomes a handle of this project like any
+   * other. The read is local once the file has been fetched.
+   */
+  declarationAt(handle: NodeHandle): Handle<Brand> | undefined;
 }
 
 /**
@@ -149,6 +161,10 @@ function viewOf<Brand>(project: Project): ProjectView<Brand> {
         .filter((file): file is SourceFile => file !== undefined),
     handle: (node) => ({ node }),
     symbolsAt: (handles) => project.checker.getSymbolAtLocation(handles.map(({ node }) => node)),
+    declarationAt: (handle) => {
+      const node = handle.resolve(project);
+      return node === undefined ? undefined : { node };
+    },
   };
 }
 

package/src/version.ts

@@ -5,7 +5,7 @@ import manifest from "../package.json" with { type: "json" };
  * `contract_version` when no configuration source supplies one, and it moves
  * independently of {@link version}.
  */
-export const CONTRACT_VERSION = "1.5.0";
+export const CONTRACT_VERSION = "1.6.0";
 
 /**
  * This analyzer's own version, which the published package carries rather than