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

package/dist/src/exemptions/sites.js

@@ -0,0 +1,182 @@
+/**
+ * The one walk of a project's own files every detector shares: its calls and the class
+ * `this` stands for at each, its classes, the values it hands to positions typed by
+ * their context, its functions' parameters, its decorated declarations and its
+ * assignments to properties. The walk reads syntax only; what a call invokes through a
+ * method of `Function.prototype` asks the checker, once per project, at the first
+ * detector that needs it.
+ */
+import { isArrowFunction, isBinaryExpression, isClassDeclaration, isClassExpression, isClassStaticBlockDeclaration, isElementAccessExpression, isFunctionDeclaration, isFunctionExpression, isGetAccessorDeclaration, isIdentifier, isMethodDeclaration, isNoSubstitutionTemplateLiteral, isObjectLiteralExpression, isPropertyAccessExpression, isPropertyDeclaration, isSetAccessorDeclaration, isStringLiteral, isVariableDeclaration, ModifierFlags, SyntaxKind, } from "@typescript/native/ast";
+import { handedOn, valuesOf } from "../index/values.js";
+import { isParameterProperty, nodeKey } from "../inventory.js";
+import { parenthesesRemoved } from "../unwrap.js";
+import { decoratorsOf, invocations } from "./calls.js";
+/** The property one assignment's left side names on its receiver, where a written key names it. */
+function storeOf(node) {
+    if (!isBinaryExpression(node) || node.operatorToken.kind !== SyntaxKind.EqualsToken) {
+        return undefined;
+    }
+    const left = parenthesesRemoved(node.left);
+    if (isPropertyAccessExpression(left) && isIdentifier(left.name)) {
+        return { store: node, receiver: left.expression, key: left.name.text, value: node.right };
+    }
+    if (isElementAccessExpression(left) &&
+        (isStringLiteral(left.argumentExpression) ||
+            isNoSubstitutionTemplateLiteral(left.argumentExpression))) {
+        return {
+            store: node,
+            receiver: left.expression,
+            key: left.argumentExpression.text,
+            value: node.right,
+        };
+    }
+    return undefined;
+}
+/** Whether one node declares a static member, whose `this` is the class itself. */
+function isStatic(node) {
+    const flags = node.modifierFlags ?? 0;
+    return (flags & ModifierFlags.Static) !== 0;
+}
+/**
+ * Whether one node opens a body whose `this` is no instance of the enclosing class: a
+ * function that is not an arrow, a static block, a static member, and a method or an
+ * accessor of an object literal, whose `this` is the literal.
+ */
+function resetsThis(node) {
+    return (isFunctionDeclaration(node) ||
+        isFunctionExpression(node) ||
+        isClassStaticBlockDeclaration(node) ||
+        isStatic(node) ||
+        ((isMethodDeclaration(node) ||
+            isGetAccessorDeclaration(node) ||
+            isSetAccessorDeclaration(node)) &&
+            isObjectLiteralExpression(node.parent)));
+}
+/** The parameters and declaring node of one function-like declaration of the project. */
+function functionOf(node) {
+    if (isFunctionDeclaration(node) ||
+        (isMethodDeclaration(node) && !isObjectLiteralExpression(node.parent))) {
+        return { declared: node, parameters: node.parameters };
+    }
+    if (isVariableDeclaration(node) &&
+        node.initializer !== undefined &&
+        (isArrowFunction(node.initializer) || isFunctionExpression(node.initializer))) {
+        return { declared: node, parameters: node.initializer.parameters };
+    }
+    return undefined;
+}
+function walk(project, held) {
+    const calls = [];
+    const classes = [];
+    const flows = [];
+    const parameters = [];
+    const decorated = [];
+    const stores = [];
+    const parameterProperties = new Set();
+    const initialized = new Set();
+    for (const file of project.ownSourceFiles()) {
+        const visit = (node, self) => {
+            const id = held.declarations.get(nodeKey(file, node));
+            let inner = self;
+            if (isClassDeclaration(node) || isClassExpression(node)) {
+                inner = id;
+                if (id !== undefined) {
+                    classes.push({ id, node });
+                }
+            }
+            else if (resetsThis(node)) {
+                inner = undefined;
+            }
+            if (id !== undefined) {
+                if (isParameterProperty(node)) {
+                    parameterProperties.add(id);
+                }
+                if (decoratorsOf(node).length > 0) {
+                    decorated.push({ id, node });
+                }
+                if (isPropertyDeclaration(node) && node.initializer !== undefined) {
+                    initialized.add(id);
+                }
+            }
+            if (node.kind === SyntaxKind.CallExpression) {
+                calls.push({ call: node, self: inner });
+            }
+            const store = storeOf(node);
+            if (store !== undefined) {
+                stores.push(store);
+            }
+            for (const written of handedOn(node)) {
+                for (const value of valuesOf(written)) {
+                    flows.push({ value, self: value.kind === SyntaxKind.ThisKeyword ? inner : undefined });
+                }
+            }
+            const fn = functionOf(node);
+            const fnId = fn === undefined ? undefined : held.declarations.get(nodeKey(file, fn.declared));
+            if (fn !== undefined && fnId !== undefined) {
+                fn.parameters
+                    .filter((parameter) => !(isIdentifier(parameter.name) && parameter.name.text === "this"))
+                    .forEach((parameter, index) => {
+                    if (isIdentifier(parameter.name)) {
+                        parameters.push({
+                            fn: fnId,
+                            index,
+                            rest: parameter.dotDotDotToken !== undefined,
+                            name: parameter.name,
+                        });
+                    }
+                });
+            }
+            node.forEachChild((child) => {
+                visit(child, inner);
+            });
+        };
+        file.forEachChild((child) => {
+            visit(child, undefined);
+        });
+    }
+    return {
+        calls,
+        classes,
+        flows,
+        parameters,
+        decorated,
+        stores,
+        parameterProperties,
+        initialized,
+    };
+}
+/** The sites of one project's own files, each walk and each checker question made once. */
+export function projectSites(project, held) {
+    let walked;
+    let invoked;
+    const sites = () => (walked ??= walk(project, held));
+    return {
+        get calls() {
+            return sites().calls;
+        },
+        get classes() {
+            return sites().classes;
+        },
+        get flows() {
+            return sites().flows;
+        },
+        get parameters() {
+            return sites().parameters;
+        },
+        get decorated() {
+            return sites().decorated;
+        },
+        get stores() {
+            return sites().stores;
+        },
+        get parameterProperties() {
+            return sites().parameterProperties;
+        },
+        get initialized() {
+            return sites().initialized;
+        },
+        get invocations() {
+            return (invoked ??= invocations(project, sites().calls.map((one) => one.call)));
+        },
+    };
+}

package/dist/src/{template-field.js → exemptions/template-field.js}

@@ -11,13 +11,13 @@
  * instance members of classes and the members of interfaces and object types, on any
  * type, because nothing ties the name to a type.
  */
-import { readComponent } from "./component-files.js";
-import { memberNames } from "./member-names.js";
-import { extensionOf, isAbsolutePath, joinPath, normalizePath, relativePath } from "./paths.js";
-import { isComponentFile } from "./position.js";
-import { bytewise } from "./text/compare.js";
-import { filesBelow } from "./fs/tree.js";
-import { UsageError } from "./usage.js";
+import { readComponent } from "../component-files.js";
+import { memberNames } from "../member-names.js";
+import { extensionOf, isAbsolutePath, joinPath, normalizePath, relativePath } from "../paths.js";
+import { isComponentFile } from "../position.js";
+import { bytewise } from "../text/compare.js";
+import { filesBelow } from "../fs/tree.js";
+import { UsageError } from "../usage.js";
 /** The kinds of declaration an action can name. */
 const READ_BY_A_TEMPLATE = new Set([
     "method",

package/dist/src/{value-reach.js → exemptions/value-reach.js}

@@ -2,14 +2,15 @@
  * The classes of the target a value of one type carries, and the members of the other
  * object types the target writes that it carries, as a serializer walking the value reaches
  * them: through constituents, array and tuple elements, the data members and index
- * signatures of the types the target writes, and the values `stored` gives for a type where
- * it erases them. The walk stops at `any`, `unknown`, a type parameter, a function and an
- * interface or class of another program, so an instance held only there is missed.
+ * signatures of the types the target writes, a class's polymorphic `this` type, and the values
+ * `stored` gives for a type where it erases them. The walk stops at `any`, `unknown`, any
+ * other type parameter, a function and an interface or class of another program, so an
+ * instance held only there is missed.
  */
 import { isAsExpression, isParenthesizedExpression, isSatisfiesExpression, isTypeAssertion, } from "@typescript/native/ast";
-import { ObjectFlags, SymbolFlags, } from "@typescript/native/sync";
-import { classNames, typesAt } from "./class-members.js";
-import { must } from "./query.js";
+import { ObjectFlags, SymbolFlags, TypeFlags, } from "@typescript/native/sync";
+import { classNames, typesAt } from "../class-members.js";
+import { must } from "../query.js";
 /**
  * The object types whose members the walk reads whatever declares them. A reverse-mapped
  * type has no symbol: it is the shape the checker infers from an argument the target
@@ -19,7 +20,9 @@ const WRITTEN = ObjectFlags.ObjectLiteral | ObjectFlags.Mapped | ObjectFlags.Rev
 /** The symbols of an anonymous object type the target writes as a type. */
 const LITERAL_SYMBOLS = SymbolFlags.TypeLiteral | SymbolFlags.ObjectLiteral;
 /** The two conversion methods a serializer or a formatter resolves on a value's own shape. */
-const CONVERSION_NAMES = new Set(["toJSON", "toString"]);
+export const CONVERSION_NAMES = new Set(["toJSON", "toString"]);
+/** The types that keep nothing of a value they are given, or that a decode gives a value. */
+export const ERASED = TypeFlags.Any | TypeFlags.Unknown;
 /**
  * The members that can answer a conversion: a serializer reads the name with `[[Get]]`
  * and calls what it answers, so a getter answers it as a method does:
@@ -140,6 +143,10 @@ export function valueReach(project, held, stored = () => []) {
         if (type.isUnionType() || type.isIntersectionType()) {
             found = must(queries.constituents(type));
         }
+        else if (type.isTypeParameter() && type.isThisType === true) {
+            // A value of a class's polymorphic `this` type is an instance of the class.
+            found = [must(queries.constraintOf(type))].filter((one) => one !== undefined);
+        }
         else if (type.isObjectType()) {
             const target = targetOf(type);
             const isList = type.isTypeReference() &&

package/dist/src/index/sites.js

@@ -15,7 +15,7 @@ import { writtenName } from "../platform-calls.js";
 import { isLoadCall } from "../roots/unseen-loads.js";
 import { keyNameOf } from "../symbol-keys.js";
 import { parenthesesRemoved } from "../unwrap.js";
-import { handedOn, valuesOf } from "../value-flow.js";
+import { handedOn, valuesOf } from "./values.js";
 /**
  * The operators whose left side one assignment stores into. A compound assignment is
  * among them: where its value is discarded it reads its target only to write the result

package/dist/src/index/values.js

@@ -0,0 +1,124 @@
+/**
+ * What a written expression evaluates to, the one definition every pass shares: the
+ * values it can be, the values a call's argument carries inside the literals it writes,
+ * and the positions a program hands a value to that the checker types from their context.
+ */
+import { isArrayLiteralExpression, isArrowFunction, isAsExpression, isBinaryExpression, isCallExpression, isConditionalExpression, isIdentifier, isNewExpression, isNonNullExpression, isObjectLiteralExpression, isOmittedExpression, isParameterDeclaration, isParenthesizedExpression, isPropertyAccessExpression, isPropertyAssignment, isPropertyDeclaration, isReturnStatement, isSatisfiesExpression, isShorthandPropertyAssignment, isSpreadAssignment, isSpreadElement, isVariableDeclaration, SyntaxKind, } from "@typescript/native/ast";
+/** The operators of an assignment whose right side is stored into the left side's type. */
+const STORES = new Set([
+    SyntaxKind.EqualsToken,
+    SyntaxKind.QuestionQuestionEqualsToken,
+    SyntaxKind.BarBarEqualsToken,
+    SyntaxKind.AmpersandAmpersandEqualsToken,
+]);
+/** Whether a declaration writes its type, so its initializer is read in that type's context. */
+function writesType(node) {
+    return node.type !== undefined;
+}
+/**
+ * The expressions one written value can evaluate to, each read alone because the checker
+ * reduces a union by subtype, so the type at the whole drops a class another branch's
+ * extends: the operand of a spread, of parentheses and of `!`, each branch of a
+ * conditional, each operand of `??` and `||`, and the right operand of `&&` and of a
+ * comma. The left operand of `&&` is its value only where it is falsy, which no object
+ * is. An assertion is a value of its own, whose type its reader decides.
+ */
+export function valuesOf(expression) {
+    if (isSpreadElement(expression) || isParenthesizedExpression(expression)) {
+        return valuesOf(expression.expression);
+    }
+    if (isNonNullExpression(expression)) {
+        return valuesOf(expression.expression);
+    }
+    if (isConditionalExpression(expression)) {
+        return [...valuesOf(expression.whenTrue), ...valuesOf(expression.whenFalse)];
+    }
+    if (isBinaryExpression(expression)) {
+        const operator = expression.operatorToken.kind;
+        if (operator === SyntaxKind.QuestionQuestionToken || operator === SyntaxKind.BarBarToken) {
+            return [...valuesOf(expression.left), ...valuesOf(expression.right)];
+        }
+        if (operator === SyntaxKind.AmpersandAmpersandToken || operator === SyntaxKind.CommaToken) {
+            return valuesOf(expression.right);
+        }
+    }
+    return [expression];
+}
+/** The name node a callee, a decorator expression or a value resolves through, where it has one. */
+export function nameOf(expression) {
+    if (isParenthesizedExpression(expression)) {
+        return nameOf(expression.expression);
+    }
+    if (isPropertyAccessExpression(expression)) {
+        return expression.name;
+    }
+    return isIdentifier(expression) ? expression : undefined;
+}
+/**
+ * The values one argument carries: each value it can be ({@link valuesOf}), or what an
+ * array or object literal it can be holds, at any depth, through spreads and shorthand
+ * properties. Each value is read inside every assertion around it.
+ */
+export function carriedValues(argument) {
+    return valuesOf(argument).flatMap((value) => {
+        let at = value;
+        while (isAsExpression(at) || isSatisfiesExpression(at)) {
+            at = at.expression;
+        }
+        if (at !== value) {
+            return carriedValues(at);
+        }
+        if (isArrayLiteralExpression(value)) {
+            return value.elements.flatMap(carriedValues);
+        }
+        if (isObjectLiteralExpression(value)) {
+            return value.properties.flatMap((property) => {
+                if (isPropertyAssignment(property)) {
+                    return carriedValues(property.initializer);
+                }
+                if (isSpreadAssignment(property)) {
+                    return carriedValues(property.expression);
+                }
+                return isShorthandPropertyAssignment(property)
+                    ? [{ site: property.name, name: property, shorthand: true }]
+                    : [];
+            });
+        }
+        return isOmittedExpression(value)
+            ? []
+            : [{ site: value, name: nameOf(value), shorthand: false }];
+    });
+}
+/** The expressions one node hands to a position typed by its context. */
+export function handedOn(node) {
+    if ((isVariableDeclaration(node) || isPropertyDeclaration(node) || isParameterDeclaration(node)) &&
+        node.initializer !== undefined &&
+        writesType(node)) {
+        return [node.initializer];
+    }
+    if (isBinaryExpression(node) && STORES.has(node.operatorToken.kind)) {
+        return [node.right];
+    }
+    if (isCallExpression(node) || isNewExpression(node)) {
+        return (node.arguments ?? []).filter((argument) => !isSpreadElement(argument));
+    }
+    if (isReturnStatement(node)) {
+        return node.expression === undefined ? [] : [node.expression];
+    }
+    if (isArrowFunction(node)) {
+        return node.body.kind === SyntaxKind.Block ? [] : [node.body];
+    }
+    if (isArrayLiteralExpression(node)) {
+        return node.elements.filter((element) => !isSpreadElement(element) && element.kind !== SyntaxKind.OmittedExpression);
+    }
+    if (isPropertyAssignment(node)) {
+        return [node.initializer];
+    }
+    if (isShorthandPropertyAssignment(node)) {
+        return isIdentifier(node.name) ? [node.name] : [];
+    }
+    if (isAsExpression(node) || isSatisfiesExpression(node)) {
+        return [node.expression];
+    }
+    return [];
+}

package/dist/src/liveness/sweep.js

@@ -6,7 +6,7 @@
  * first: a caller, an exemption or a live component file's markup, a suppression mark, and an
  * unanswered checker question; each Contract rule "live only through" one is a view up to it.
  */
-import { exemptionsOf, isUnansweredRecord } from "../exempt.js";
+import { exemptionsOf } from "../exemptions/lifecycle.js";
 import { edgeWithheldBy } from "../tests/file-class.js";
 import { componentsOf } from "./components.js";
 import { namesACaller, OUTSIDE } from "./graph.js";
@@ -367,7 +367,7 @@ function seedsOf(graph, policy) {
         if (record.whileLive !== undefined) {
             gate(record.whileLive, seed);
         }
-        else if (isUnansweredRecord(record)) {
+        else if (record.unanswered === true) {
             unanswered.push(seed);
         }
         else {

package/dist/src/query.js

@@ -7,6 +7,7 @@
  * form where it has one and otherwise as one batch, one round trip per capped run.
  */
 import { isIdentifier } from "@typescript/native/ast";
+import { IndexKind, } from "@typescript/native/sync";
 /**
  * The greatest number of locations one batched request asks about. A batch is
  * answered by an array of its own length, so an uncapped batch over a large file
@@ -118,6 +119,41 @@ function partQuestion(type) {
     }
     return undefined;
 }
+/** How deep {@link mappedParameters} reads, as a recursive mapped type makes a new one at each level. */
+const MAPPED_DEPTH = 4;
+/** The type parameters a mapped type is over, as {@link Queries.mappedParametersOf} names them. */
+function mappedParameters(checker, mapped) {
+    const own = new Set();
+    const found = new Map();
+    const seen = new Set();
+    const visit = (type, depth) => {
+        if (depth > MAPPED_DEPTH || seen.has(type.id)) {
+            return;
+        }
+        seen.add(type.id);
+        if (type.isMappedType()) {
+            own.add(type.getTypeParameter().id);
+        }
+        if (type.isTypeParameter() && !type.isThisType) {
+            found.set(type.id, type);
+        }
+        const aliased = type
+            .aliasTypeArguments;
+        const inner = [
+            ...(type.isUnionType() || type.isIntersectionType() ? type.getTypes() : []),
+            ...(type.isTypeReference() ? checker.getTypeArguments(type) : []),
+            ...(aliased === undefined || aliased.length === 0 ? [] : type.getAliasTypeArguments()),
+            ...(partQuestion(type)?.() ?? []),
+        ];
+        for (const part of inner) {
+            if (part !== undefined) {
+                visit(part, depth + 1);
+            }
+        }
+    };
+    visit(mapped, 0);
+    return [...found.values()].filter((parameter) => !own.has(parameter.id));
+}
 /**
  * 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,
@@ -244,6 +280,7 @@ export function queriesOf(checker, configFile, batch, log, ask = ASK_DIRECTLY) {
         constraintOf: (type) => type.isTypeParameter()
             ? one("getConstraint", () => typeLocation(type), () => type.getConstraint())
             : undefined,
+        baseConstraintOf: (type) => one("getBaseConstraintOfType", () => typeLocation(type), () => checker.getBaseConstraintOfType(type)),
         indexedAccessOf: (type) => type.isIndexedAccessType()
             ? one("getObjectType", () => typeLocation(type), () => ({ object: type.getObjectType(), index: type.getIndexType() }))
             : undefined,
@@ -272,6 +309,17 @@ export function queriesOf(checker, configFile, batch, log, ask = ASK_DIRECTLY) {
             ? undefined
             : one("getTarget", () => `signature ${String(signature.id)}`, () => signature.getTarget()),
         typeAtPosition: (signature, index) => one("getTypeParameterAtPosition", () => `signature ${String(signature.id)} position ${String(index)}`, () => signature.getTypeParameterAtPosition(index)),
+        restTypeOf: (signature) => signature.hasRestParameter
+            ? one("getTypeOfSymbol", () => `signature ${String(signature.id)} rest parameter`, () => {
+                const rest = signature.getParameters().at(-1);
+                return rest === undefined ? undefined : checker.getTypeOfSymbol(rest);
+            })
+            : undefined,
+        numberIndexOf: (type) => one("getIndexTypeOfType", () => typeLocation(type), () => checker.getIndexTypeOfType(type, IndexKind.Number)),
+        mappedParametersOf: (type) => type.isMappedType()
+            ? one("getConstraintType", () => typeLocation(type), () => mappedParameters(checker, type))
+            : [],
+        propertyTypeOf: (type, name) => one("getTypeOfPropertyOfType", () => `${typeLocation(type)} property ${name}`, () => checker.getTypeOfPropertyOfType(type, name)),
         signatureOf: (declaration) => one("getSignatureFromDeclaration", () => nodeLocation(declaration), () => checker.getSignatureFromDeclaration(declaration)),
         returnTypeOf: (signature) => one("getReturnTypeOfSignature", () => `signature ${String(signature.id)}`, () => checker.getReturnTypeOfSignature(signature)),
         typeToString: (type) => one("typeToString", () => typeLocation(type), () => checker.typeToString(type)),

package/dist/src/roots/configured-declarations.js

@@ -6,7 +6,7 @@
  */
 import { isCallExpression, isExportDeclaration, isExternalModuleReference, isImportDeclaration, isImportEqualsDeclaration, isNoSubstitutionTemplateLiteral, isStringLiteral, SyntaxKind, } from "@typescript/native/ast";
 import { SymbolFlags } from "@typescript/native/sync";
-import { resolvedTargets } from "../calls.js";
+import { resolvedTargets } from "../alias-chain.js";
 import { declaredComponent } from "../inventory.js";
 import { must, Unanswerable } from "../query.js";
 import { nameComponent } from "../ref.js";

package/dist/src/verbs/print-retained.js

@@ -1,11 +1,33 @@
 import { EXIT_CLEAN } from "../contract/contract.generated.js";
 import { productionMode, runSweep } from "../analysis.js";
-import { retainedLines } from "../exempt.js";
 import { partialNotes } from "../partial.js";
+import { positionKey } from "../position.js";
 import { resolvePath } from "../paths.js";
 import { resolve } from "../resolve.js";
 import {} from "./verb.js";
 import { diagnose } from "../product.js";
+/**
+ * One line per held-back declaration, in site order: its reference and position, then
+ * each record's class, site and detail, all separated by tabs.
+ */
+function retainedLines(symbols, retained) {
+    const held = new Map();
+    for (const record of retained) {
+        held.set(record.id, [...(held.get(record.id) ?? []), record]);
+    }
+    return symbols.flatMap((symbol) => {
+        const records = held.get(symbol.id);
+        if (records === undefined) {
+            return [];
+        }
+        const fields = records.flatMap((record) => [
+            record.class,
+            positionKey(record.site),
+            record.detail,
+        ]);
+        return [[symbol.ref, positionKey(symbol.position), ...fields].join("\t")];
+    });
+}
 /**
  * Writes every declaration an exemption held back in the production sweep a report is
  * built from, one per line, and nothing where no exemption held one back. One fact

package/jsr.json

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

package/package.json

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

package/src/alias-chain.ts

@@ -1,7 +1,7 @@
 /**
  * Where an import or export chain leads in one project: from one symbol to each
  * declaration of the target it is, and along the chain of aliases it heads to each
- * declaration every link of that chain is.
+ * declaration every link of that chain is, and what a name resolves to through them.
  */
 
 import {
@@ -12,10 +12,11 @@ import {
   isImportSpecifier,
   isNamespaceExport,
   isNamespaceImport,
+  type Node,
 } from "@typescript/native/ast";
 import { SymbolFlags, type Symbol as TSSymbol } from "@typescript/native/sync";
 import { isParameterProperty, nodeKey, type Inventory } from "./inventory.ts";
-import { UNANSWERED, type Answer } from "./query.ts";
+import { must, UNANSWERED, type Answer } from "./query.ts";
 import type { ProjectView } from "./session.ts";
 
 /** One declaration a chain reaches, and whether a step along an alias reached it. */
@@ -195,3 +196,38 @@ export function aliasChains<Brand>(project: ProjectView<Brand>, held: Inventory)
     nextDeclared,
   };
 }
+
+/**
+ * What each of a batch of nodes resolves to, every alias followed to the declaration
+ * it stands for. A node the checker resolves to nothing, and an alias that resolves
+ * to nothing, are absent from the answer. Each alias is followed once. A question the
+ * checker does not answer stops the pass, as {@link must} stops.
+ */
+export function resolvedTargets<Brand>(
+  project: ProjectView<Brand>,
+  nodes: readonly Node[],
+): ReadonlyMap<Node, TSSymbol> {
+  const followed = new Map<number, TSSymbol | undefined>();
+  const targets = new Map<Node, TSSymbol>();
+  project
+    .symbolsAt(nodes.map((node) => project.handle(node)))
+    .map(must)
+    .forEach((symbol, index) => {
+      const node = nodes[index];
+      if (symbol === undefined || node === undefined) {
+        return;
+      }
+      let target: TSSymbol | undefined = symbol;
+      if ((symbol.flags & SymbolFlags.Alias) !== 0) {
+        if (!followed.has(symbol.id)) {
+          const aliased = must(project.queries.aliased(symbol));
+          followed.set(symbol.id, aliased.declarations.length === 0 ? undefined : aliased);
+        }
+        target = followed.get(symbol.id);
+      }
+      if (target !== undefined) {
+        targets.set(node, target);
+      }
+    });
+  return targets;
+}