@cplieger/deadset-ts 3.9.0 → 3.9.1

package/dist/src/destructuring.js

@@ -0,0 +1,273 @@
+/**
+ * The members a destructuring reads. An object pattern reads each property it names
+ * from the value it destructures, so the property's name in the pattern is a read of
+ * the member the value's type declares under that name, whether the pattern binds it
+ * to a local of the same name, renames it, gives it a default or nests a pattern under
+ * it. A rest element names no property: what it copies is read where the copy is.
+ */
+import { isArrayLiteralExpression, isBinaryExpression, isForOfStatement, isIdentifier, isNoSubstitutionTemplateLiteral, isNumericLiteral, isObjectBindingPattern, isObjectLiteralExpression, isParameterDeclaration, isParenthesizedExpression, isPropertyAssignment, isShorthandPropertyAssignment, isStringLiteral, SyntaxKind, } from "@typescript/native/unstable/ast";
+import { TypeFlags } from "@typescript/native/unstable/sync";
+/** The text a property name spells, or `undefined` for a computed name. */
+function nameText(node) {
+    if (node === undefined) {
+        return undefined;
+    }
+    if (isIdentifier(node) ||
+        isStringLiteral(node) ||
+        isNoSubstitutionTemplateLiteral(node) ||
+        isNumericLiteral(node)) {
+        return node.text;
+    }
+    return undefined;
+}
+/** The node one expression is written inside, through however many parentheses enclose it. */
+function container(node) {
+    let child = node;
+    while (isParenthesizedExpression(child.parent)) {
+        child = child.parent;
+    }
+    return { child, parent: child.parent };
+}
+/** The plain assignment one node is the left side of, if it is one. */
+function assignmentOf(node, parent) {
+    return isBinaryExpression(parent) &&
+        parent.operatorToken.kind === SyntaxKind.EqualsToken &&
+        parent.left === node
+        ? parent
+        : undefined;
+}
+/**
+ * Whether an object or array literal is a destructuring target rather than a value: the
+ * left side of an assignment, the target of a `for…of`, or an element of a literal that
+ * is one, with or without a default.
+ */
+function isDestructuringTarget(literal) {
+    const { child, parent } = container(literal);
+    if (assignmentOf(child, parent) !== undefined) {
+        return true;
+    }
+    if (isForOfStatement(parent)) {
+        return parent.initializer === child;
+    }
+    return isElement(child, parent);
+}
+/** Whether one node is an element of a destructuring target: a property's value, or an array element. */
+function isElement(child, parent) {
+    if (isPropertyAssignment(parent)) {
+        return parent.initializer === child && isDestructuringTarget(parent.parent);
+    }
+    return isArrayLiteralExpression(parent) && isDestructuringTarget(parent);
+}
+/**
+ * Whether an object binding pattern runs: a pattern in the parameter list of a signature
+ * with no body, a function type or an overload among them, binds nothing at runtime.
+ */
+function binds(pattern) {
+    let at = pattern.parent;
+    while (at.kind === SyntaxKind.BindingElement) {
+        at = at.parent.parent;
+    }
+    if (!isParameterDeclaration(at)) {
+        return true;
+    }
+    return at.parent.body !== undefined;
+}
+/** The properties one node reads, where it is an object pattern; none otherwise. */
+export function propertyReadsOf(node) {
+    const reads = [];
+    if (isObjectBindingPattern(node)) {
+        if (!binds(node)) {
+            return reads;
+        }
+        for (const element of node.elements) {
+            const key = element.propertyName ?? element.name;
+            const name = nameText(key);
+            if (element.dotDotDotToken === undefined && key !== undefined && name !== undefined) {
+                reads.push({ pattern: node, key, name });
+            }
+        }
+        return reads;
+    }
+    if (isObjectLiteralExpression(node) && isDestructuringTarget(node)) {
+        for (const property of node.properties) {
+            if (isShorthandPropertyAssignment(property) || isPropertyAssignment(property)) {
+                const name = nameText(property.name);
+                if (name !== undefined) {
+                    reads.push({ pattern: node, key: property.name, name });
+                }
+            }
+        }
+    }
+    return reads;
+}
+/**
+ * Where the value one destructuring target receives comes from. The checker answers for
+ * a binding pattern's type itself, so this is asked of an assignment target only, whose
+ * own type is the literal's rather than the assigned value's. A default does not move
+ * the source: `{ a: { b } = fallback }` reads `b` from `a`. A target inside a spread
+ * takes the rest of a value and has no source here.
+ */
+function sourceOf(target) {
+    const steps = [];
+    let at = target;
+    for (;;) {
+        const { child, parent } = container(at);
+        const assignment = assignmentOf(child, parent);
+        if (assignment !== undefined) {
+            const outer = container(assignment);
+            if (!isElement(outer.child, outer.parent)) {
+                return { expression: assignment.right, steps: steps.reverse() };
+            }
+            at = assignment;
+            continue;
+        }
+        if (isForOfStatement(parent) && parent.initializer === child) {
+            steps.push({ kind: "iterated" });
+            return { expression: parent.expression, steps: steps.reverse() };
+        }
+        if (isPropertyAssignment(parent) && parent.initializer === child) {
+            const name = nameText(parent.name);
+            if (name === undefined) {
+                return undefined;
+            }
+            steps.push({ kind: "property", name });
+            at = parent.parent;
+            continue;
+        }
+        if (isArrayLiteralExpression(parent)) {
+            steps.push({
+                kind: "element",
+                index: parent.elements.findIndex((element) => element === child),
+            });
+            at = parent;
+            continue;
+        }
+        return undefined;
+    }
+}
+/**
+ * The resolution over one project, its batches capped at `cap`. Property tables are
+ * read once per type for the whole project, since one type is destructured in many
+ * places and a table answers every name of it.
+ */
+export function destructuring(project, cap) {
+    const checker = project.checker;
+    const tables = new Map();
+    let patternBatches = 0;
+    let patternLookups = 0;
+    const typesAt = (nodes) => {
+        const types = [];
+        for (let from = 0; from < nodes.length; from += cap) {
+            types.push(...checker.getTypeAtLocation(nodes.slice(from, from + cap)));
+            patternBatches += 1;
+        }
+        return types;
+    };
+    const tableOf = (type) => {
+        const known = tables.get(type.id);
+        if (known !== undefined) {
+            return known;
+        }
+        const table = new Map();
+        if ((type.flags & TypeFlags.AnyOrUnknown) === 0) {
+            patternLookups += 1;
+            for (const property of checker.getPropertiesOfType(type)) {
+                table.set(property.name, property);
+            }
+        }
+        tables.set(type.id, table);
+        return table;
+    };
+    const definedOf = (type) => {
+        if ((type.flags & TypeFlags.Union) === 0) {
+            return type;
+        }
+        patternLookups += 1;
+        return checker.getNonNullableType(type);
+    };
+    /**
+     * The type one element of an array or tuple value has: a tuple's element at `index`,
+     * an array's element type at any index, and `undefined` for a tuple iterated whole.
+     */
+    const elementOf = (type, index) => {
+        if (!type.isTypeReference()) {
+            return undefined;
+        }
+        patternLookups += 1;
+        if (checker.isTupleType(type)) {
+            if (index === undefined) {
+                return undefined;
+            }
+            patternLookups += 1;
+            return checker.getTypeArguments(type)[index];
+        }
+        patternLookups += 1;
+        if (!checker.isArrayType(type)) {
+            return undefined;
+        }
+        patternLookups += 1;
+        return checker.getTypeArguments(type)[0];
+    };
+    const step = (type, next) => {
+        const defined = definedOf(type);
+        if (defined === undefined) {
+            return undefined;
+        }
+        if (next.kind === "property") {
+            const property = tableOf(defined).get(next.name);
+            if (property === undefined) {
+                return undefined;
+            }
+            patternLookups += 1;
+            return checker.getTypeOfSymbol(property);
+        }
+        return elementOf(defined, next.kind === "element" ? next.index : undefined);
+    };
+    const resolve = (reads) => {
+        const patterns = [...new Set(reads.map((read) => read.pattern))];
+        const sources = new Map();
+        const asking = new Set();
+        for (const pattern of patterns) {
+            if (isObjectBindingPattern(pattern)) {
+                asking.add(pattern);
+                continue;
+            }
+            const source = sourceOf(pattern);
+            sources.set(pattern, source);
+            if (source !== undefined) {
+                asking.add(source.expression);
+            }
+        }
+        const answered = new Map();
+        const asked = [...asking];
+        typesAt(asked).forEach((type, index) => {
+            const node = asked[index];
+            if (type !== undefined && node !== undefined) {
+                answered.set(node, type);
+            }
+        });
+        const patternTypes = new Map();
+        for (const pattern of patterns) {
+            const source = sources.get(pattern);
+            if (source === undefined) {
+                patternTypes.set(pattern, answered.get(pattern));
+                continue;
+            }
+            let type = answered.get(source.expression);
+            for (const next of source.steps) {
+                type = type === undefined ? undefined : step(type, next);
+            }
+            patternTypes.set(pattern, type === undefined ? undefined : definedOf(type));
+        }
+        return reads.map((read) => {
+            const type = patternTypes.get(read.pattern);
+            return type === undefined ? undefined : tableOf(type).get(read.name);
+        });
+    };
+    return {
+        resolve,
+        get cost() {
+            return { patternBatches, patternLookups };
+        },
+    };
+}

package/dist/src/references.js

@@ -1,5 +1,6 @@
 import { isArrayLiteralExpression, isBinaryExpression, isCallExpression, isDecorator, isDeleteExpression, isElementAccessExpression, isExportDeclaration, isExternalModuleReference, isForInStatement, isForOfStatement, isImportDeclaration, isImportEqualsDeclaration, isNamespaceExport, isNoSubstitutionTemplateLiteral, isObjectLiteralExpression, isParenthesizedExpression, isPostfixUnaryExpression, isPrefixUnaryExpression, isPropertyAccessExpression, isPropertyAssignment, isShorthandPropertyAssignment, isSpreadAssignment, isSpreadElement, isStringLiteral, SyntaxKind, } from "@typescript/native/unstable/ast";
 import { aliasChains } from "./alias-chain.js";
+import { destructuring, propertyReadsOf } from "./destructuring.js";
 import { globExpression } from "./glob.js";
 import { nodeKey } from "./inventory.js";
 import { byPosition, renderPosition } from "./position.js";
@@ -205,6 +206,7 @@ function linksOf(file, node, declarations, enclosing) {
  */
 function sitesOf(file, declarations, fileId) {
     const found = [];
+    const reads = [];
     const links = [];
     const evaluations = [];
     const decorated = [];
@@ -243,6 +245,9 @@ function sitesOf(file, declarations, fileId) {
         }
         markNames(node);
         markStores(node, writes);
+        for (const read of propertyReadsOf(node)) {
+            reads.push({ ...read, from: enclosing });
+        }
         links.push(...linksOf(file, node, declarations, enclosing));
         const evaluated = evaluatedBy(node);
         if (evaluated !== undefined) {
@@ -262,7 +267,7 @@ function sitesOf(file, declarations, fileId) {
         enclosing = outer;
     };
     file.forEachChild(visit);
-    return { uses: found, links, evaluations, decorated };
+    return { uses: found, reads, links, evaluations, decorated };
 }
 /**
  * The name one test-file rule takes. A rule's name is a word list the report's own
@@ -316,6 +321,7 @@ export function references(project, held, targetRoot, options) {
     const found = [];
     const tests = [];
     const chains = aliasChains(project, held);
+    const destructured = destructuring(project, cap);
     let batched = 0;
     let fileBatches = 0;
     let residueFallbacks = 0;
@@ -351,7 +357,7 @@ export function references(project, held, targetRoot, options) {
         if (test) {
             tests.push(path);
         }
-        const { uses, links, evaluations, decorated } = sitesOf(file, declarations, declaredAt(file) ?? "");
+        const { uses, reads, links, evaluations, decorated } = sitesOf(file, declarations, declaredAt(file) ?? "");
         // A decorator is written inside the declaration it is attached to and receives it,
         // so the declaration is used where the decorator is written, whatever the
         // decorator does with it.
@@ -426,6 +432,25 @@ export function references(project, held, targetRoot, options) {
                 }
             }
         }
+        // A pattern names a property of the value it destructures, which no name node of
+        // the pattern resolves to: a shorthand's name is the local it binds.
+        destructured.resolve(reads).forEach((symbol, index) => {
+            const read = reads[index];
+            if (symbol === undefined || read === undefined) {
+                return;
+            }
+            const position = renderPosition(file, targetRoot, read.key.getStart());
+            for (const target of chains.chainOf(symbol)) {
+                found.push({
+                    from: read.from,
+                    to: target.id,
+                    position,
+                    use: "read",
+                    resolution: "destructured",
+                    test,
+                });
+            }
+        });
         for (const site of uses) {
             const direct = site.shorthand !== undefined
                 ? "shorthand"
@@ -459,6 +484,14 @@ export function references(project, held, targetRoot, options) {
         configFile: project.configFile,
         references: found,
         testFilePaths: tests.sort(compare),
-        cost: { batched, fileBatches, residueFallbacks, shorthandLookups, aliasSteps: chains.steps },
+        cost: {
+            batched,
+            fileBatches,
+            residueFallbacks,
+            shorthandLookups,
+            aliasSteps: chains.steps,
+            patternBatches: destructured.cost.patternBatches,
+            patternLookups: destructured.cost.patternLookups,
+        },
     };
 }

package/jsr.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "3.9.0",
+  "version": "3.9.1",
   "type": "module",
   "sideEffects": false,
   "description": "Deterministic dead-code analysis for TypeScript, class and type members included",

package/src/destructuring.ts

@@ -0,0 +1,353 @@
+/**
+ * The members a destructuring reads. An object pattern reads each property it names
+ * from the value it destructures, so the property's name in the pattern is a read of
+ * the member the value's type declares under that name, whether the pattern binds it
+ * to a local of the same name, renames it, gives it a default or nests a pattern under
+ * it. A rest element names no property: what it copies is read where the copy is.
+ */
+
+import {
+  isArrayLiteralExpression,
+  isBinaryExpression,
+  isForOfStatement,
+  isIdentifier,
+  isNoSubstitutionTemplateLiteral,
+  isNumericLiteral,
+  isObjectBindingPattern,
+  isObjectLiteralExpression,
+  isParameterDeclaration,
+  isParenthesizedExpression,
+  isPropertyAssignment,
+  isShorthandPropertyAssignment,
+  isStringLiteral,
+  SyntaxKind,
+  type BinaryExpression,
+  type Node,
+} from "@typescript/native/unstable/ast";
+import { TypeFlags, type Symbol as TSSymbol, type Type } from "@typescript/native/unstable/sync";
+import type { ProjectView } from "./session.ts";
+
+/** One property one object pattern reads. */
+export interface PropertyRead {
+  /** The pattern, whose destructured value declares the property. */
+  readonly pattern: Node;
+  /** The property's name as the pattern writes it, which is where the read is written. */
+  readonly key: Node;
+  /** The property's name. */
+  readonly name: string;
+}
+
+/** The text a property name spells, or `undefined` for a computed name. */
+function nameText(node: Node | undefined): string | undefined {
+  if (node === undefined) {
+    return undefined;
+  }
+  if (
+    isIdentifier(node) ||
+    isStringLiteral(node) ||
+    isNoSubstitutionTemplateLiteral(node) ||
+    isNumericLiteral(node)
+  ) {
+    return node.text;
+  }
+  return undefined;
+}
+
+/** The node one expression is written inside, through however many parentheses enclose it. */
+function container(node: Node): { readonly child: Node; readonly parent: Node } {
+  let child = node;
+  while (isParenthesizedExpression(child.parent)) {
+    child = child.parent;
+  }
+  return { child, parent: child.parent };
+}
+
+/** The plain assignment one node is the left side of, if it is one. */
+function assignmentOf(node: Node, parent: Node): BinaryExpression | undefined {
+  return isBinaryExpression(parent) &&
+    parent.operatorToken.kind === SyntaxKind.EqualsToken &&
+    parent.left === node
+    ? parent
+    : undefined;
+}
+
+/**
+ * Whether an object or array literal is a destructuring target rather than a value: the
+ * left side of an assignment, the target of a `for…of`, or an element of a literal that
+ * is one, with or without a default.
+ */
+function isDestructuringTarget(literal: Node): boolean {
+  const { child, parent } = container(literal);
+  if (assignmentOf(child, parent) !== undefined) {
+    return true;
+  }
+  if (isForOfStatement(parent)) {
+    return parent.initializer === child;
+  }
+  return isElement(child, parent);
+}
+
+/** Whether one node is an element of a destructuring target: a property's value, or an array element. */
+function isElement(child: Node, parent: Node): boolean {
+  if (isPropertyAssignment(parent)) {
+    return parent.initializer === child && isDestructuringTarget(parent.parent);
+  }
+  return isArrayLiteralExpression(parent) && isDestructuringTarget(parent);
+}
+
+/**
+ * Whether an object binding pattern runs: a pattern in the parameter list of a signature
+ * with no body, a function type or an overload among them, binds nothing at runtime.
+ */
+function binds(pattern: Node): boolean {
+  let at = pattern.parent;
+  while (at.kind === SyntaxKind.BindingElement) {
+    at = at.parent.parent;
+  }
+  if (!isParameterDeclaration(at)) {
+    return true;
+  }
+  return (at.parent as { readonly body?: Node }).body !== undefined;
+}
+
+/** The properties one node reads, where it is an object pattern; none otherwise. */
+export function propertyReadsOf(node: Node): readonly PropertyRead[] {
+  const reads: PropertyRead[] = [];
+  if (isObjectBindingPattern(node)) {
+    if (!binds(node)) {
+      return reads;
+    }
+    for (const element of node.elements) {
+      const key = element.propertyName ?? element.name;
+      const name = nameText(key);
+      if (element.dotDotDotToken === undefined && key !== undefined && name !== undefined) {
+        reads.push({ pattern: node, key, name });
+      }
+    }
+    return reads;
+  }
+  if (isObjectLiteralExpression(node) && isDestructuringTarget(node)) {
+    for (const property of node.properties) {
+      if (isShorthandPropertyAssignment(property) || isPropertyAssignment(property)) {
+        const name = nameText(property.name);
+        if (name !== undefined) {
+          reads.push({ pattern: node, key: property.name, name });
+        }
+      }
+    }
+  }
+  return reads;
+}
+
+/** One step from a destructured value to the value a nested target destructures. */
+type Step =
+  | { readonly kind: "property"; readonly name: string }
+  | { readonly kind: "element"; readonly index: number }
+  | { readonly kind: "iterated" };
+
+/** Where an assignment target's value comes from: an expression, and the steps into it. */
+interface Source {
+  readonly expression: Node;
+  readonly steps: readonly Step[];
+}
+
+/**
+ * Where the value one destructuring target receives comes from. The checker answers for
+ * a binding pattern's type itself, so this is asked of an assignment target only, whose
+ * own type is the literal's rather than the assigned value's. A default does not move
+ * the source: `{ a: { b } = fallback }` reads `b` from `a`. A target inside a spread
+ * takes the rest of a value and has no source here.
+ */
+function sourceOf(target: Node): Source | undefined {
+  const steps: Step[] = [];
+  let at = target;
+  for (;;) {
+    const { child, parent } = container(at);
+    const assignment = assignmentOf(child, parent);
+    if (assignment !== undefined) {
+      const outer = container(assignment);
+      if (!isElement(outer.child, outer.parent)) {
+        return { expression: assignment.right, steps: steps.reverse() };
+      }
+      at = assignment;
+      continue;
+    }
+    if (isForOfStatement(parent) && parent.initializer === child) {
+      steps.push({ kind: "iterated" });
+      return { expression: parent.expression, steps: steps.reverse() };
+    }
+    if (isPropertyAssignment(parent) && parent.initializer === child) {
+      const name = nameText(parent.name);
+      if (name === undefined) {
+        return undefined;
+      }
+      steps.push({ kind: "property", name });
+      at = parent.parent;
+      continue;
+    }
+    if (isArrayLiteralExpression(parent)) {
+      steps.push({
+        kind: "element",
+        index: parent.elements.findIndex((element) => element === child),
+      });
+      at = parent;
+      continue;
+    }
+    return undefined;
+  }
+}
+
+/** What resolving one project's property reads cost at the client boundary. */
+interface DestructuringCost {
+  /** Batched type lookups, one per capped run of a file's patterns and assigned values. */
+  readonly patternBatches: number;
+  /**
+   * Per-type lookups: one property table per distinct destructured type, and each step
+   * an assignment target takes into its assigned value.
+   */
+  readonly patternLookups: number;
+}
+
+/** Resolves property reads to the symbols the destructured values' types declare. */
+interface Destructuring {
+  /**
+   * The property symbol each read names, in the order given, `undefined` where the
+   * destructured value's type declares no property of that name or is not known.
+   */
+  resolve(reads: readonly PropertyRead[]): readonly (TSSymbol | undefined)[];
+  readonly cost: DestructuringCost;
+}
+
+/**
+ * The resolution over one project, its batches capped at `cap`. Property tables are
+ * read once per type for the whole project, since one type is destructured in many
+ * places and a table answers every name of it.
+ */
+export function destructuring<Brand>(project: ProjectView<Brand>, cap: number): Destructuring {
+  const checker = project.checker;
+  const tables = new Map<number, ReadonlyMap<string, TSSymbol>>();
+  let patternBatches = 0;
+  let patternLookups = 0;
+
+  const typesAt = (nodes: readonly Node[]): (Type | undefined)[] => {
+    const types: (Type | undefined)[] = [];
+    for (let from = 0; from < nodes.length; from += cap) {
+      types.push(...checker.getTypeAtLocation(nodes.slice(from, from + cap)));
+      patternBatches += 1;
+    }
+    return types;
+  };
+
+  const tableOf = (type: Type): ReadonlyMap<string, TSSymbol> => {
+    const known = tables.get(type.id);
+    if (known !== undefined) {
+      return known;
+    }
+    const table = new Map<string, TSSymbol>();
+    if ((type.flags & TypeFlags.AnyOrUnknown) === 0) {
+      patternLookups += 1;
+      for (const property of checker.getPropertiesOfType(type)) {
+        table.set(property.name, property);
+      }
+    }
+    tables.set(type.id, table);
+    return table;
+  };
+
+  const definedOf = (type: Type): Type | undefined => {
+    if ((type.flags & TypeFlags.Union) === 0) {
+      return type;
+    }
+    patternLookups += 1;
+    return checker.getNonNullableType(type);
+  };
+
+  /**
+   * The type one element of an array or tuple value has: a tuple's element at `index`,
+   * an array's element type at any index, and `undefined` for a tuple iterated whole.
+   */
+  const elementOf = (type: Type, index: number | undefined): Type | undefined => {
+    if (!type.isTypeReference()) {
+      return undefined;
+    }
+    patternLookups += 1;
+    if (checker.isTupleType(type)) {
+      if (index === undefined) {
+        return undefined;
+      }
+      patternLookups += 1;
+      return checker.getTypeArguments(type)[index];
+    }
+    patternLookups += 1;
+    if (!checker.isArrayType(type)) {
+      return undefined;
+    }
+    patternLookups += 1;
+    return checker.getTypeArguments(type)[0];
+  };
+
+  const step = (type: Type, next: Step): Type | undefined => {
+    const defined = definedOf(type);
+    if (defined === undefined) {
+      return undefined;
+    }
+    if (next.kind === "property") {
+      const property = tableOf(defined).get(next.name);
+      if (property === undefined) {
+        return undefined;
+      }
+      patternLookups += 1;
+      return checker.getTypeOfSymbol(property);
+    }
+    return elementOf(defined, next.kind === "element" ? next.index : undefined);
+  };
+
+  const resolve = (reads: readonly PropertyRead[]): readonly (TSSymbol | undefined)[] => {
+    const patterns = [...new Set(reads.map((read) => read.pattern))];
+    const sources = new Map<Node, Source | undefined>();
+    const asking = new Set<Node>();
+    for (const pattern of patterns) {
+      if (isObjectBindingPattern(pattern)) {
+        asking.add(pattern);
+        continue;
+      }
+      const source = sourceOf(pattern);
+      sources.set(pattern, source);
+      if (source !== undefined) {
+        asking.add(source.expression);
+      }
+    }
+    const answered = new Map<Node, Type>();
+    const asked = [...asking];
+    typesAt(asked).forEach((type, index) => {
+      const node = asked[index];
+      if (type !== undefined && node !== undefined) {
+        answered.set(node, type);
+      }
+    });
+    const patternTypes = new Map<Node, Type | undefined>();
+    for (const pattern of patterns) {
+      const source = sources.get(pattern);
+      if (source === undefined) {
+        patternTypes.set(pattern, answered.get(pattern));
+        continue;
+      }
+      let type = answered.get(source.expression);
+      for (const next of source.steps) {
+        type = type === undefined ? undefined : step(type, next);
+      }
+      patternTypes.set(pattern, type === undefined ? undefined : definedOf(type));
+    }
+    return reads.map((read) => {
+      const type = patternTypes.get(read.pattern);
+      return type === undefined ? undefined : tableOf(type).get(read.name);
+    });
+  };
+
+  return {
+    resolve,
+    get cost() {
+      return { patternBatches, patternLookups };
+    },
+  };
+}

package/src/references.ts

@@ -29,6 +29,7 @@ import {
 } from "@typescript/native/unstable/ast";
 import type { Symbol as TSSymbol } from "@typescript/native/unstable/sync";
 import { aliasChains } from "./alias-chain.ts";
+import { destructuring, propertyReadsOf, type PropertyRead } from "./destructuring.ts";
 import { globExpression } from "./glob.ts";
 import { nodeKey, type Inventory } from "./inventory.ts";
 import { byPosition, renderPosition, type Position } from "./position.ts";
@@ -71,8 +72,11 @@ export type Use = "read" | "write" | "evaluation" | "decorator";
  *   the literal declares rather than to the declaration that name reads.
  * - `alias` is a step along an import or export chain, from one link to what it names.
  * - `syntax` is the tree alone, which says what a decorator is attached to.
+ * - `destructured` is the property a pattern names, looked up on the type of the value
+ *   the pattern destructures.
  */
-export type Resolution = "batch" | "resolved-symbol" | "shorthand" | "alias" | "syntax";
+export type Resolution =
+  "batch" | "resolved-symbol" | "shorthand" | "alias" | "syntax" | "destructured";
 
 /** One use of one declaration by one declaration. */
 export interface Reference {
@@ -119,6 +123,16 @@ export interface ReferenceCost {
   readonly shorthandLookups: number;
   /** Per-symbol lookups that step from one alias to what it names, one per alias. */
   readonly aliasSteps: number;
+  /**
+   * Batched type lookups for the object patterns: per file, the patterns and the values
+   * assigned to destructuring targets, divided by the batch cap, rounded up.
+   */
+  readonly patternBatches: number;
+  /**
+   * Per-type lookups for the object patterns: one property table per distinct type a
+   * pattern destructures, and each step a nested assignment target takes into its value.
+   */
+  readonly patternLookups: number;
 }
 
 /** One project's references, in position order, and what reading them cost. */
@@ -326,9 +340,15 @@ interface Decorated {
   readonly declaration: string;
 }
 
+/** One property a pattern reads, and the declaration the pattern is written inside. */
+interface Read extends PropertyRead {
+  readonly from: string;
+}
+
 /** Everything one file's walk found to resolve, and the decorators it needs no resolution for. */
 interface FileSites {
   readonly uses: readonly Site[];
+  readonly reads: readonly Read[];
   readonly links: readonly Link[];
   readonly evaluations: readonly Evaluation[];
   readonly decorated: readonly Decorated[];
@@ -425,6 +445,7 @@ function sitesOf(
   fileId: string,
 ): FileSites {
   const found: Site[] = [];
+  const reads: Read[] = [];
   const links: Link[] = [];
   const evaluations: Evaluation[] = [];
   const decorated: Decorated[] = [];
@@ -465,6 +486,9 @@ function sitesOf(
     }
     markNames(node);
     markStores(node, writes);
+    for (const read of propertyReadsOf(node)) {
+      reads.push({ ...read, from: enclosing });
+    }
     links.push(...linksOf(file, node, declarations, enclosing));
     const evaluated = evaluatedBy(node);
     if (evaluated !== undefined) {
@@ -485,7 +509,7 @@ function sitesOf(
   };
 
   file.forEachChild(visit);
-  return { uses: found, links, evaluations, decorated };
+  return { uses: found, reads, links, evaluations, decorated };
 }
 
 /**
@@ -551,6 +575,7 @@ export function references<Brand>(
   const found: Reference[] = [];
   const tests: string[] = [];
   const chains = aliasChains(project, held);
+  const destructured = destructuring(project, cap);
   let batched = 0;
   let fileBatches = 0;
   let residueFallbacks = 0;
@@ -595,7 +620,7 @@ export function references<Brand>(
     if (test) {
       tests.push(path);
     }
-    const { uses, links, evaluations, decorated } = sitesOf(
+    const { uses, reads, links, evaluations, decorated } = sitesOf(
       file,
       declarations,
       declaredAt(file) ?? "",
@@ -679,6 +704,26 @@ export function references<Brand>(
       }
     }
 
+    // A pattern names a property of the value it destructures, which no name node of
+    // the pattern resolves to: a shorthand's name is the local it binds.
+    destructured.resolve(reads).forEach((symbol, index) => {
+      const read = reads[index];
+      if (symbol === undefined || read === undefined) {
+        return;
+      }
+      const position = renderPosition(file, targetRoot, read.key.getStart());
+      for (const target of chains.chainOf(symbol)) {
+        found.push({
+          from: read.from,
+          to: target.id,
+          position,
+          use: "read",
+          resolution: "destructured",
+          test,
+        });
+      }
+    });
+
     for (const site of uses) {
       const direct: Resolution =
         site.shorthand !== undefined
@@ -718,6 +763,14 @@ export function references<Brand>(
     configFile: project.configFile,
     references: found,
     testFilePaths: tests.sort(compare),
-    cost: { batched, fileBatches, residueFallbacks, shorthandLookups, aliasSteps: chains.steps },
+    cost: {
+      batched,
+      fileBatches,
+      residueFallbacks,
+      shorthandLookups,
+      aliasSteps: chains.steps,
+      patternBatches: destructured.cost.patternBatches,
+      patternLookups: destructured.cost.patternLookups,
+    },
   };
 }