@cplieger/deadset-ts 5.0.0 → 5.1.0

package/dist/src/findings/unused-declarations.js

@@ -114,6 +114,43 @@ function messageOf(code, judged) {
     }
     return `${subject} has no reference in the target`;
 }
+/**
+ * The members nothing writes or reads that are brands: each names a type parameter of
+ * its declaring type that no other part of the declaration names, other than another
+ * such member. They are what make two instantiations of the type distinct types, so
+ * deleting them would let one instantiation stand for another.
+ */
+function brandMembers(input) {
+    const union = input.swept.matrix.union;
+    const unreferenced = new Map(input.swept.sweep.candidates
+        .filter((candidate) => candidate.productionRefs + candidate.testRefs === 0)
+        .map((candidate) => [candidate.id, candidate]));
+    const namedBy = new Map();
+    for (const reference of input.stores.references) {
+        const to = union.symbols[union.at(reference.to)];
+        if (to?.kind === "type-parameter") {
+            namedBy.set(to.id, (namedBy.get(to.id) ?? new Set()).add(reference.from));
+        }
+    }
+    const brands = new Set();
+    for (const [parameter, from] of namedBy) {
+        const owner = union.symbols[union.at(parameter)]?.parent;
+        const members = [...from].map((id) => union.symbols[union.at(id)]);
+        if (members.every((member) => member !== undefined &&
+            member.parent === owner &&
+            BRANDS.has(member.kind) &&
+            unreferenced.has(member.id))) {
+            for (const member of members) {
+                if (member !== undefined) {
+                    brands.add(member.id);
+                }
+            }
+        }
+    }
+    return brands;
+}
+/** The kinds of member a brand is: a data member of a type or of a class. */
+const BRANDS = new Set(["type-member", "class-member"]);
 /** The findings of the unused-declarations family, `DS1000` to `DS1099`. */
 export const unusedDeclarations = (input) => familyFindings(input, false);
 /**
@@ -127,6 +164,7 @@ function familyFindings(input, fallen) {
     const union = input.swept.matrix.union;
     const dead = new Set(input.swept.sweep.candidates.map((candidate) => candidate.id));
     const unreachable = unreachableExports(input);
+    let brands;
     const found = [];
     for (const candidate of input.swept.sweep.candidates) {
         const at = union.at(candidate.id);
@@ -148,7 +186,8 @@ function familyFindings(input, fallen) {
             unreachable: unreachable.has(symbol.id),
         };
         const code = codeOf(judged);
-        if (code === undefined) {
+        if (code === undefined ||
+            (code === "DS1003" && (brands ??= brandMembers(input)).has(symbol.id))) {
             continue;
         }
         const endLine = Math.max(symbol.position.line, symbol.endLine);

package/dist/src/generated-file.js

@@ -0,0 +1,24 @@
+/**
+ * The generated-file class on TypeScript: every declaration in a file below a directory
+ * an applied convention row names as generated is retained, because the framework owns
+ * the file and a deletion there is undone at the next generation.
+ */
+/** The generated-file detector, recording each file's first line. */
+export function generatedFile(input) {
+    const generated = input.generated;
+    if (generated === undefined || generated.size === 0) {
+        return [];
+    }
+    return input.held.symbols.flatMap((symbol) => {
+        const row = generated.get(symbol.position.path);
+        return symbol.kind === "file" || row === undefined
+            ? []
+            : [
+                {
+                    id: symbol.id,
+                    detail: `generated below a directory the convention row ${row} names`,
+                    site: { path: symbol.position.path, line: 1, column: 1 },
+                },
+            ];
+    });
+}

package/dist/src/interface-satisfaction.js

@@ -12,19 +12,13 @@
  * the contextual lookup has none, so it is asked only of a value whose type is a class
  * of the target, and each distinct pair, interface and class is asked once.
  */
-import { isArrayLiteralExpression, isArrowFunction, isAsExpression, isBinaryExpression, isCallExpression, isClassDeclaration, isClassExpression, isClassStaticBlockDeclaration, isConditionalExpression, isFunctionDeclaration, isFunctionExpression, isGetAccessorDeclaration, isHeritageClause, isIdentifier, isMethodDeclaration, isNewExpression, isObjectLiteralExpression, isParameterDeclaration, isParenthesizedExpression, isPropertyAssignment, isPropertyDeclaration, isReturnStatement, isSatisfiesExpression, isSetAccessorDeclaration, isShorthandPropertyAssignment, isSpreadElement, isVariableDeclaration, ModifierFlags, SyntaxKind, } from "@typescript/native/unstable/ast";
+import { isClassDeclaration, isClassExpression, isClassStaticBlockDeclaration, isFunctionDeclaration, isFunctionExpression, isGetAccessorDeclaration, isHeritageClause, isMethodDeclaration, isObjectLiteralExpression, isSetAccessorDeclaration, ModifierFlags, SyntaxKind, } from "@typescript/native/unstable/ast";
 import { SymbolFlags } from "@typescript/native/unstable/sync";
 import { aliasChains } from "./alias-chain.js";
 import { nodeKey } from "./inventory.js";
 import { renderPosition } from "./position.js";
 import { must } from "./query.js";
-/** 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,
-]);
+import { handedOn, valuesOf } from "./value-flow.js";
 /** Whether one node declares a static member, whose `this` is the class itself. */
 function isStatic(node) {
     const flags = node.modifierFlags ?? 0;
@@ -37,66 +31,6 @@ function isObjectLiteralMethod(node) {
         isSetAccessorDeclaration(node)) &&
         isObjectLiteralExpression(node.parent));
 }
-/** Whether a declaration writes its type, so its initializer is read in that type's context. */
-function writesType(node) {
-    return node.type !== undefined;
-}
-/**
- * The values one written expression hands on: the expression itself, or what it
- * evaluates to through parentheses, a conditional and the operators whose result is
- * one of their operands.
- */
-function valuesOf(expression) {
-    if (isParenthesizedExpression(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 expressions one node hands to a position typed by its context. */
-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 [];
-}
 /**
  * The classes, the `implements` entries and the flowing values of one project's own
  * files. `this` is the class an instance member belongs to, so a function that is not

package/dist/src/inventory.js

@@ -69,7 +69,10 @@ function modifiersOf(node) {
 function typeParametersOf(node) {
     if (isFunctionDeclaration(node) ||
         isMethodDeclaration(node) ||
-        isMethodSignatureDeclaration(node)) {
+        isMethodSignatureDeclaration(node) ||
+        isClassDeclaration(node) ||
+        isInterfaceDeclaration(node) ||
+        isTypeAliasDeclaration(node)) {
         return node.typeParameters ?? [];
     }
     return [];

package/dist/src/kinds.js

@@ -30,6 +30,7 @@ const ROWS = [
         name: "unused-member",
         languages: ["go", "ts"],
         rule: "A struct field, class member or type member with no reference, a private member included. A member referenced only from its own declaration site counts as unreferenced.",
+        precondition: "A TypeScript member that no value writes and nothing reads, whose type names a type parameter of its declaring interface, class or type alias, is not reported when every part of that declaration that names the type parameter is a member no value writes and nothing reads. TypeScript compares object types by their members, so such members are what make two instantiations of their type distinct types, and deleting them leaves the type parameter phantom and lets one instantiation stand for another. A member a value writes is decided by the rule of DS1301 instead, whatever its type names.",
         defaultSeverity: "deny",
         maxClass: "certain",
         fixability: "deletable",
@@ -70,7 +71,7 @@ const ROWS = [
         name: "unnecessary-export",
         languages: ["go", "ts"],
         rule: "An exported symbol whose every reference is inside the symbol's own package or module, reported as a candidate for unexporting. The subject is a package-level declaration or a method, and three subjects are excluded: an interface method, whose exportedness is the contract of the interface that declares it; a struct field, which an encoder reads by name; and a method that satisfies an interface some symbol uses as a type, which cannot be unexported without its type ceasing to satisfy that interface. The finding names the narrower visibility the references support. A declared cross-language edge counts as an out-of-package reference; where the edge's other side is unknown to the analyzer the finding is emitted pending.",
-        precondition: "Closed world only. Reported always for a main package and an internal/ directory tree, and for a published package only when the configuration declares the consumer set complete and every declared consumer loads. A library with no consumer loaded and no complete consumer set declared gets this finding on its internal/ tree and its main packages and never on its published API. A symbol the rule of DS1301 holds for is not reported under this code, whatever severity the configuration gives DS1301, because the write-only finding names the defect to fix first.",
+        precondition: "Closed world only. Reported always for a main package and an internal/ directory tree, and for a published package only when the configuration declares the consumer set complete and every declared consumer loads. A library with no consumer loaded and no complete consumer set declared gets this finding on its internal/ tree and its main packages and never on its published API. A symbol the rule of DS1301 holds for is not reported under this code, whatever severity the configuration gives DS1301, because the write-only finding names the defect to fix first. A type that a parameter or a result of an exported function or method of its own package names is not reported when a reference from outside the package references that function or method, because the caller holds values of the type, and unexporting it would leave an exported signature naming a type its callers cannot name.",
         defaultSeverity: "warn",
         maxClass: "certain",
         fixability: "narrowable",
@@ -81,7 +82,7 @@ const ROWS = [
         name: "unnecessary-exposure",
         languages: ["go"],
         rule: "An exported symbol of a non-internal package whose every reference is inside the target module, reported as a candidate for relocation behind an internal boundary. The subject is a package-level declaration or a method, and three subjects are excluded: an interface method, whose exportedness is the contract of the interface that declares it; a struct field, which an encoder reads by name; and a method that satisfies an interface some symbol uses as a type, which cannot be unexported without its type ceasing to satisfy that interface. The finding names the narrower visibility the references support. A declared cross-language edge counts as an out-of-package reference; where the edge's other side is unknown to the analyzer the finding is emitted pending.",
-        precondition: "Closed world only. Reported always for a main package and an internal/ directory tree, and for a published package only when the configuration declares the consumer set complete and every declared consumer loads. A library with no consumer loaded and no complete consumer set declared gets this finding on its internal/ tree and its main packages and never on its published API. A symbol the rule of DS1301 holds for is not reported under this code, whatever severity the configuration gives DS1301, because the write-only finding names the defect to fix first.",
+        precondition: "Closed world only. Reported always for a main package and an internal/ directory tree, and for a published package only when the configuration declares the consumer set complete and every declared consumer loads. A library with no consumer loaded and no complete consumer set declared gets this finding on its internal/ tree and its main packages and never on its published API. A symbol the rule of DS1301 holds for is not reported under this code, whatever severity the configuration gives DS1301, because the write-only finding names the defect to fix first. A type that a parameter or a result of an exported function or method of its own package names is not reported when a reference from outside the target module references that function or method, because the caller holds values of the type, and moving it behind an internal boundary would leave an exported signature naming a type its callers cannot name.",
         defaultSeverity: "warn",
         maxClass: "certain",
         fixability: "narrowable",
@@ -143,7 +144,7 @@ const ROWS = [
         code: "DS1301",
         name: "write-only-symbol",
         languages: ["go", "ts"],
-        rule: "A package-level or module-level variable, struct field, class member or collection that production code writes and never reads. In production mode a read from a test file counts as no read. A comparison of struct values reads every field of the type: in Go, a value of a struct type used as an operand of `==` or `!=`, as a map key, or as a `switch` tag or `case` expression is a read of every field of that type, transitively through the fields of every struct type it holds, recorded at the comparison, because equality reads every field and a field that decides equality carries information. In TypeScript a comparison of two object references reads no member, because `===` compares identity and never a member. The finding names each write position, so the deletion set is visible.",
+        rule: "A package-level or module-level variable, struct field, class member, type member or collection that production code writes and never reads. In production mode a read from a test file counts as no read. A comparison of struct values reads every field of the type: in Go, a value of a struct type used as an operand of `==` or `!=`, as a map key, or as a `switch` tag or `case` expression is a read of every field of that type, transitively through the fields of every struct type it holds, recorded at the comparison, because equality reads every field and a field that decides equality carries information. In TypeScript a comparison of two object references reads no member, because `===` compares identity and never a member. In TypeScript a property of an object literal writes the member of the same name that the literal's contextual type declares, whether or not the compiler checks the literal for excess properties. Where that contextual type is a union or an intersection, the property writes the member of that name on each constituent that declares one. So a literal that a declaration annotates, a function returns, a call passes or a `satisfies` expression checks writes the members of the type it is given. A store through the value a field or a member holds reads that field or member rather than writing it, because the store lands in storage every other holder of the value reads. In Go that store is an assignment, an increment, a compound assignment or a `delete` whose target is reached through a struct field holding a map, a slice or a pointer. Examples are `s.f[k] = v`, `s.f.x = v` and `delete(s.f, k)`. The same store through a field holding an array or a struct is a store into the field itself. TypeScript holds every object by reference, so an element or property store through a member's value reads the member. The finding names each write position, so the deletion set is visible. Deleting the subject and its writes also deletes every declaration whose only uses they hold. Such a declaration is a type parameter of the subject's declaring type that the subject's type alone names, or an import binding the writes alone use. The finding's message names each such declaration.",
         defaultSeverity: "deny",
         maxClass: "certain",
         fixability: "deletable",

package/dist/src/query.js

@@ -73,6 +73,21 @@ function symbolLocation(symbol) {
 function typeLocation(type) {
     return `type ${String(type.id)}`;
 }
+/** The property tables over one project's questions. */
+export function propertyTables(queries) {
+    const held = new Map();
+    return {
+        of: (type) => {
+            const known = held.get(type.id);
+            if (known !== undefined) {
+                return { properties: known, asked: false };
+            }
+            const properties = queries.propertiesOf(type);
+            held.set(type.id, properties);
+            return { properties, asked: true };
+        },
+    };
+}
 /**
  * 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,

package/dist/src/references.js

@@ -1,12 +1,14 @@
-import { isArrayLiteralExpression, isBinaryExpression, isCallExpression, isDecorator, isDeleteExpression, isElementAccessExpression, isExportDeclaration, isExpressionStatement, isExternalModuleReference, isForInStatement, isForOfStatement, isForStatement, isImportDeclaration, isImportEqualsDeclaration, isNamespaceExport, isNoSubstitutionTemplateLiteral, isObjectLiteralExpression, isParenthesizedExpression, isPostfixUnaryExpression, isPrefixUnaryExpression, isPropertyAccessExpression, isPropertyAssignment, isShorthandPropertyAssignment, isSpreadAssignment, isSpreadElement, isStringLiteral, isVoidExpression, SyntaxKind, } from "@typescript/native/unstable/ast";
+import { isArrayLiteralExpression, isAsExpression, isBinaryExpression, isCallExpression, isDecorator, isDeleteExpression, isElementAccessExpression, isExportDeclaration, isExpressionStatement, isExternalModuleReference, isForInStatement, isForOfStatement, isForStatement, isImportDeclaration, isImportEqualsDeclaration, isNamespaceExport, isNoSubstitutionTemplateLiteral, isObjectLiteralExpression, isParenthesizedExpression, isPostfixUnaryExpression, isPrefixUnaryExpression, isPropertyAccessExpression, isPropertyAssignment, isShorthandPropertyAssignment, isSpreadAssignment, isSpreadElement, isStringLiteral, isVoidExpression, SyntaxKind, } from "@typescript/native/unstable/ast";
 import { aliasChains } from "./alias-chain.js";
+import { contextualUses } from "./contextual-uses.js";
 import { destructuring, propertyReadsOf } from "./destructuring.js";
 import { globExpression } from "./glob.js";
 import { declarationsByName, nodeKey } from "./inventory.js";
 import { relativePath } from "./paths.js";
 import { byPosition, isComponentFile, renderPosition } from "./position.js";
-import { DEFAULT_BATCH_CAP, UNANSWERED } from "./query.js";
+import { DEFAULT_BATCH_CAP, propertyTables, UNANSWERED } from "./query.js";
 import { typeQueryAliases } from "./type-query-alias.js";
+import { handedOn, valuesOf } from "./value-flow.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
@@ -94,7 +96,11 @@ function markWrite(target, writes) {
         return;
     }
     if (isElementAccessExpression(held)) {
-        markWrite(held.expression, writes);
+        // A store through a member's value lands in storage every holder of the value
+        // reads, so it reads the member; a variable only ever stored into stays written.
+        if (!isPropertyAccessExpression(unparenthesized(held.expression))) {
+            markWrite(held.expression, writes);
+        }
         return;
     }
     if (isArrayLiteralExpression(held)) {
@@ -232,6 +238,27 @@ function linksOf(file, node, declarations, enclosing) {
     }
     return found;
 }
+/**
+ * Whether one object literal is a destructuring target, written on the left of an
+ * assignment or as a `for` loop's initializer, through the literals and spreads it nests in.
+ */
+function isAssignmentPattern(node) {
+    let child = node;
+    let parent = node.parent;
+    while (isParenthesizedExpression(parent) ||
+        isArrayLiteralExpression(parent) ||
+        isObjectLiteralExpression(parent) ||
+        isSpreadElement(parent) ||
+        isSpreadAssignment(parent) ||
+        (isPropertyAssignment(parent) && parent.initializer === child)) {
+        child = parent;
+        parent = parent.parent;
+    }
+    if (isBinaryExpression(parent)) {
+        return parent.operatorToken.kind === SyntaxKind.EqualsToken && parent.left === child;
+    }
+    return (isForInStatement(parent) || isForOfStatement(parent)) && parent.initializer === child;
+}
 /**
  * Every name node one file holds that is a use rather than a declaration, in source
  * order, each with its enclosing declaration and its use, and every re-export the file
@@ -246,6 +273,8 @@ function sitesOf(file, declarations, fileId, unread) {
     const links = [];
     const evaluations = [];
     const decorated = [];
+    const literals = [];
+    const flows = [];
     const writes = new Set();
     const alsoRead = new Set();
     const declared = new Set();
@@ -286,6 +315,13 @@ function sitesOf(file, declarations, fileId, unread) {
         }
         markNames(node);
         markStores(node, writes, alsoRead);
+        if (isObjectLiteralExpression(node) && !isAssignmentPattern(node)) {
+            literals.push({ literal: node, from: enclosing });
+        }
+        // An assertion needs only comparability, so no member of its operand is read by it.
+        for (const written of isAsExpression(node) ? [] : handedOn(node)) {
+            flows.push(...valuesOf(written).map((value) => ({ value, from: enclosing })));
+        }
         for (const read of propertyReadsOf(node)) {
             reads.push({ ...read, from: enclosing });
         }
@@ -308,8 +344,16 @@ function sitesOf(file, declarations, fileId, unread) {
         enclosing = outer;
     };
     file.forEachChild(visit);
-    return { uses: found, reads, links, evaluations, decorated };
+    return { uses: found, literals, flows, reads, links, evaluations, decorated };
 }
+/** The declaration kinds of a property an object literal declares. */
+const LITERAL_PROPERTY_KINDS = new Set([
+    SyntaxKind.PropertyAssignment,
+    SyntaxKind.ShorthandPropertyAssignment,
+    SyntaxKind.MethodDeclaration,
+    SyntaxKind.GetAccessor,
+    SyntaxKind.SetAccessor,
+]);
 /** The rule a file the analysis classified as test-support code is counted under. */
 const TEST_SUPPORT_RULE = "test-support";
 /**
@@ -412,6 +456,59 @@ function importBindings(file) {
     }
     return found;
 }
+/** The value one assignment stores through the name it writes, where it is a plain assignment. */
+function storedValue(name) {
+    let target = name;
+    if (isPropertyAccessExpression(name.parent) && name.parent.name === name) {
+        target = name.parent;
+    }
+    while (isParenthesizedExpression(target.parent)) {
+        target = target.parent;
+    }
+    const parent = target.parent;
+    return isBinaryExpression(parent) &&
+        parent.operatorToken.kind === SyntaxKind.EqualsToken &&
+        parent.left === target
+        ? parent.right
+        : undefined;
+}
+/**
+ * The import bindings of one file that only the values written into one declaration
+ * use, for each write into it. A binding is named by an identifier that spells its
+ * local name and is not the member a property access names.
+ */
+function aloneIn(file, uses, writes, found) {
+    const bindings = new Set(importBindings(file).map((binding) => binding.node.getText()));
+    if (bindings.size === 0) {
+        return [];
+    }
+    const occurrences = new Map();
+    for (const site of uses) {
+        const text = site.node.getText();
+        const parent = site.node.parent;
+        if (!bindings.has(text) || (isPropertyAccessExpression(parent) && parent.name === site.node)) {
+            continue;
+        }
+        if (!occurrences.get(text)?.includes(site.node)) {
+            occurrences.set(text, [...(occurrences.get(text) ?? []), site.node]);
+        }
+    }
+    const inside = (node, value) => node.pos >= value.pos && node.end <= value.end;
+    const result = [];
+    for (const write of writes) {
+        const to = found[write.index]?.to;
+        const sameTarget = writes.filter((one) => found[one.index]?.to === to);
+        const names = [...occurrences]
+            .filter(([, nodes]) => nodes.some((node) => inside(node, write.value)) &&
+            nodes.every((node) => sameTarget.some((one) => inside(node, one.value))))
+            .map(([name]) => name)
+            .sort(compare);
+        if (names.length > 0) {
+            result.push({ index: write.index, names });
+        }
+    }
+    return result;
+}
 /** Two strings ordered bytewise, which is the order every set of a run is read in. */
 function compare(a, b) {
     if (a === b) {
@@ -442,7 +539,8 @@ export function references(project, held, targetRoot, options) {
     const found = [];
     const tests = [];
     const chains = aliasChains(project, held);
-    const destructured = destructuring(project, cap);
+    const tables = propertyTables(project.queries);
+    const destructured = destructuring(project, cap, tables);
     let batched = 0;
     let fileBatches = 0;
     let residueFallbacks = 0;
@@ -455,6 +553,7 @@ export function references(project, held, targetRoot, options) {
             .ownSourceFiles()
             .filter((file) => relativePath(consumer.root, file.fileName) !== undefined &&
             relativePath(targetRoot, file.fileName) === undefined);
+    const ownPaths = project.ownPaths();
     const fileIds = new Set(held.symbols.filter((symbol) => symbol.kind === "file").map((symbol) => symbol.id));
     let topLevel;
     /** The declarations one file's top level holds. */
@@ -551,14 +650,89 @@ export function references(project, held, targetRoot, options) {
         residueFallbacks += 1;
         return project.resolvedSymbolAt(project.handle(site.node));
     };
-    for (const file of files) {
+    const walked = files.map((file) => {
+        const fileId = declaredAt(file) ?? "";
+        return { file, fileId, ...sitesOf(file, declarations, fileId, unread) };
+    });
+    const contextual = contextualUses(project, held, chains, walked.flatMap((one) => one.literals), walked.flatMap((one) => one.flows), cap, tables);
+    const writtenBy = new Map();
+    for (const write of contextual.writes) {
+        const property = write.at.parent;
+        writtenBy.set(nodeKey(property.getSourceFile(), property), write.ids);
+    }
+    const forwardedCache = new Map();
+    /**
+     * The members a literal property one symbol declares writes: a use of the property
+     * reaches them, because the literal's type carries the data the member describes.
+     */
+    const forwarded = (symbol) => {
+        const known = forwardedCache.get(symbol.id);
+        if (known !== undefined) {
+            return known;
+        }
+        const found = [];
+        if (writtenBy.size > 0) {
+            for (const handle of symbol.declarations) {
+                if (!LITERAL_PROPERTY_KINDS.has(handle.kind) || !ownPaths.has(handle.path)) {
+                    continue;
+                }
+                const node = project.declarationAt(handle)?.node;
+                const ids = node === undefined ? undefined : writtenBy.get(nodeKey(node.getSourceFile(), node));
+                for (const id of ids ?? []) {
+                    if (!found.some((target) => target.id === id)) {
+                        found.push({ id, stepped: true, guessed: false });
+                    }
+                }
+            }
+        }
+        forwardedCache.set(symbol.id, found);
+        return found;
+    };
+    /** One resolved symbol's declarations along its chain, and the members its literal properties write. */
+    const targetsOf = (symbol) => {
+        const through = forwarded(symbol);
+        return through.length === 0 ? chains.chainOf(symbol) : [...chains.chainOf(symbol), ...through];
+    };
+    const testFile = new Map();
+    for (const { file } of walked) {
         const path = renderPosition(file, root, 0).path;
         const test = patterns.some((pattern) => pattern.test(path));
+        testFile.set(file, test);
         if (test) {
             tests.push(path);
         }
-        const fileId = declaredAt(file) ?? "";
-        const { uses, reads, links, evaluations, decorated } = sitesOf(file, declarations, fileId, unread);
+    }
+    /** Each write reference's index in `found`, by its file, with the value it stores. */
+    const valued = new Map();
+    const holdsValue = (file, value) => {
+        if (value !== undefined) {
+            valued.set(file, [...(valued.get(file) ?? []), { index: found.length - 1, value }]);
+        }
+    };
+    for (const [use, sites] of [
+        ["write", contextual.writes],
+        ["read", contextual.reads],
+    ]) {
+        for (const site of sites) {
+            const file = site.at.getSourceFile();
+            const position = renderPosition(file, root, site.at.getStart());
+            for (const id of site.ids) {
+                found.push({
+                    from: site.from,
+                    to: id,
+                    position,
+                    use,
+                    resolution: "contextual",
+                    test: testFile.get(file) === true,
+                });
+                if (use === "write") {
+                    holdsValue(file, site.at.parent);
+                }
+            }
+        }
+    }
+    for (const { file, fileId, uses, reads, links, evaluations, decorated } of walked) {
+        const test = testFile.get(file) === true;
         // A component file's markup may use any binding its blocks declare at the top level.
         const markup = isComponentFile(file);
         const bindings = markup ? importBindings(file) : [];
@@ -697,7 +871,7 @@ export function references(project, held, targetRoot, options) {
                     stepped: false,
                     guessed: true,
                 }))
-                : chains.chainOf(symbol);
+                : targetsOf(symbol);
             for (const target of targets) {
                 found.push({
                     from: read.from,
@@ -724,7 +898,7 @@ export function references(project, held, targetRoot, options) {
             // the use names every link of the chain its name stands at the head of.
             const targets = throughAliases(symbol === UNANSWERED
                 ? named(site.node).map((id) => ({ id, stepped: false, guessed: true }))
-                : chains.chainOf(symbol));
+                : targetsOf(symbol));
             for (const target of targets) {
                 found.push({
                     from: site.from,
@@ -734,6 +908,19 @@ export function references(project, held, targetRoot, options) {
                     resolution: target.guessed ? "by-name" : target.stepped ? "alias" : direct,
                     test,
                 });
+                if (site.use === "write") {
+                    holdsValue(file, storedValue(site.node));
+                }
+            }
+        }
+    }
+    const usesOf = new Map(walked.map((one) => [one.file, one.uses]));
+    for (const [file, writes] of valued) {
+        const uses = usesOf.get(file) ?? [];
+        for (const { index, names } of aloneIn(file, uses, writes, found)) {
+            const reference = found[index];
+            if (reference !== undefined) {
+                found[index] = { ...reference, alone: names };
             }
         }
     }
@@ -755,6 +942,8 @@ export function references(project, held, targetRoot, options) {
             aliasSteps: chains.steps,
             patternBatches: destructured.cost.patternBatches,
             patternLookups: destructured.cost.patternLookups,
+            contextualBatches: contextual.batches,
+            contextualLookups: contextual.lookups,
         },
     };
 }

package/dist/src/resolve.js

@@ -133,18 +133,19 @@ function readStrings(parent, name, path, label, minItems, allowed) {
         throw malformed(label, path, `holds ${String(value.length)} entries, want at least ${String(minItems)}`);
     }
     const seen = new Set();
-    for (const entry of value) {
+    for (const [index, entry] of value.entries()) {
+        const at = `${path}[${String(index)}]`;
         if (typeof entry !== "string") {
-            throw malformed(label, path, "holds an entry that is not a string");
+            throw malformed(label, at, "is not a string");
         }
         if (entry === "") {
-            throw malformed(label, path, "holds an empty entry");
+            throw malformed(label, at, "is empty");
         }
         if (seen.has(entry)) {
-            throw malformed(label, path, `names ${JSON.stringify(entry)} twice`);
+            throw malformed(label, at, `names ${JSON.stringify(entry)} again`);
         }
         if (allowed !== undefined && !allowed.includes(entry)) {
-            throw malformed(label, path, `${JSON.stringify(entry)} is not one of ${spell(allowed)}`);
+            throw malformed(label, at, `${JSON.stringify(entry)} is not one of ${spell(allowed)}`);
         }
         seen.add(entry);
     }
@@ -154,9 +155,9 @@ function readStrings(parent, name, path, label, minItems, allowed) {
 const COMPONENT_EXTENSION = /^\.[A-Za-z0-9]+$/u;
 function readComponentExtensions(ts, label) {
     const extensions = readStrings(ts, "component_extensions", "ts.component_extensions", label, 0);
-    const wrong = extensions?.find((one) => !COMPONENT_EXTENSION.test(one));
-    if (wrong !== undefined) {
-        throw malformed(label, "ts.component_extensions", `${JSON.stringify(wrong)} is not a full stop followed by letters and digits`);
+    const wrong = extensions?.findIndex((one) => !COMPONENT_EXTENSION.test(one)) ?? -1;
+    if (extensions !== undefined && wrong !== -1) {
+        throw malformed(label, `ts.component_extensions[${String(wrong)}]`, `${JSON.stringify(extensions[wrong])} is not a full stop followed by letters and digits`);
     }
     return extensions;
 }
@@ -164,9 +165,9 @@ function readComponentExtensions(ts, label) {
 const CONVENTION_NAMES = new Set(CONVENTION_ROWS.map((row) => row.name));
 function readDisabledConventions(ts, label) {
     const names = readStrings(ts, "disabled_conventions", "ts.disabled_conventions", label, 0);
-    const unknown = names?.find((one) => !CONVENTION_NAMES.has(one));
-    if (unknown !== undefined) {
-        throw malformed(label, "ts.disabled_conventions", `${JSON.stringify(unknown)} names no convention row this analyzer carries`);
+    const unknown = names?.findIndex((one) => !CONVENTION_NAMES.has(one)) ?? -1;
+    if (names !== undefined && unknown !== -1) {
+        throw malformed(label, `ts.disabled_conventions[${String(unknown)}]`, `${JSON.stringify(names[unknown])} names no convention row this analyzer carries`);
     }
     return names;
 }

package/dist/src/roots.js

@@ -158,7 +158,7 @@ export function roots(project, held, targetRoot, options) {
         : conventionEntries(options.conventions, files)) {
         enter(file, "convention", row, true);
     }
-    for (const point of entryPoints(project, files, options.testFiles, options.host, targetRoot)) {
+    for (const point of entryPoints(project, files, options.testFiles, options.host, targetRoot, options.parse)) {
         enter(point.file, point.rule, point.source, point.exports);
     }
     for (const file of files.byPath.values()) {

package/dist/src/stores.js

@@ -26,6 +26,9 @@ export function accessorsOf(project, held) {
 export function storesOf(per, exempt, mode) {
     return {
         references: per.flatMap((one) => one.references.filter((reference) => !mode.production || !reference.test)),
+        readInTests: new Set(per.flatMap((one) => one.references
+            .filter((reference) => reference.test && reference.use !== "write")
+            .map((reference) => reference.to))),
         accessors: new Set(per.flatMap((one) => one.accessors)),
         exempt: new Set(exempt.map((record) => record.id)),
     };