@cplieger/deadset-ts 3.9.0 → 3.10.0

package/dist/src/conformance-record.js

@@ -0,0 +1,26 @@
+// Written by the conformance run from conformance.json and conformance-results.json.
+// Regenerate it with `UPDATE_GOLDEN=1 npx vitest --run src/conformance.corpus.test.ts`.
+export const RECORD = {
+    conformance: {
+        corpusVersion: "1.9.0",
+        result: "fail",
+        digest: "sha256:8c29f19fc189f4f5d9ea210d556b62d12c3701c221eb7a8adde499b7060bec0d",
+    },
+    gaps: [
+        {
+            fixture: "private-member-unread",
+            capability: "reflective-lookup",
+            reason: "The reference pass resolves a string-literal element access to the member it names, so the member is live by that reference and the retained listing names no class for it.",
+        },
+        {
+            fixture: "redundant-export-keyword",
+            capability: "DS1104",
+            reason: "No consumer is loaded beside the target, so the published surface is unknown and no export is narrowed; review an export only the target uses by hand.",
+        },
+        {
+            fixture: "unused-exported-consumer",
+            capability: "DS1001",
+            reason: "No consumer is loaded beside the target, so an export nothing in the target references is reported at the possible class rather than the certain one.",
+        },
+    ],
+};

package/dist/src/conformance.js

@@ -1,22 +1,10 @@
 /**
- * What this analyzer states about its own conformance: the corpus version it is written
- * against and its recorded result over that corpus, which `describe` and every report name.
+ * What this analyzer states about its own conformance: its recorded result over the
+ * conformance corpus and every capability it declines, which `describe` and every report
+ * name.
  */
-/** The version of the conformance corpus this analyzer is written against. */
-const CORPUS_VERSION = "1.9.0";
-/** The SHA-256 of zero bytes, which is the digest of a results document no run wrote. */
-const EMPTY_DIGEST = "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
-/**
- * The conformance run this analyzer records, or undefined where it records none. A
- * description states exactly this, so a reader that requires a pass refuses an analyzer
- * that has not answered the corpus.
- */
-export const RECORDED_CONFORMANCE = undefined;
-/**
- * The conformance a report states. A report requires the block, so an analyzer that
- * records no run states a failed one over the results document no run wrote, which a merge
- * refuses as it refuses any result other than a pass.
- */
-export function reportedConformance(recorded) {
-    return recorded ?? { corpusVersion: CORPUS_VERSION, result: "fail", digest: EMPTY_DIGEST };
-}
+import { RECORD } from "./conformance-record.js";
+/** The conformance run this analyzer records. */
+export const CONFORMANCE = RECORD.conformance;
+/** Every capability this analyzer declines, in the order `conformance.json` declares them. */
+export const DECLARED_GAPS = RECORD.gaps;

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/dist/src/report.js

@@ -133,6 +133,15 @@ function canonicalStale(a, b) {
         compare(a.code, b.code) ||
         compare(a.symbol, b.symbol));
 }
+/** One declared gap as a report carries it, its members in the schema's order. */
+function wireGap(gap) {
+    return {
+        fixture: gap.fixture,
+        ...(gap.symbol === undefined ? {} : { symbol: gap.symbol }),
+        capability: gap.capability,
+        reason: gap.reason,
+    };
+}
 /** Edge evaluations by edge, then side, then their compact encodings. */
 function byEdge(a, b) {
     return (compare(a.edge, b.edge) ||
@@ -202,7 +211,11 @@ export function buildReport(input) {
         findings,
         edge_evaluations: input.result.edgeEvaluations.map(wireEvaluation).sort(byEdge),
         stale_suppressions: input.result.staleSuppressions.map(wireStale).sort(canonicalStale),
-        declared_gaps: [],
+        // Every gap shares the one component of the canonical key a gap supplies, the analyzer's
+        // name, so the compact encodings alone order them.
+        declared_gaps: input.declaredGaps
+            .map(wireGap)
+            .sort((a, b) => compare(JSON.stringify(a), JSON.stringify(b))),
         excluded_by_cgo: [],
         test_file_rules: [...input.testFileRules]
             .sort((a, b) => compare(a.rule, b.rule) || a.matched - b.matched)

package/dist/src/verbs/analyze.js

@@ -1,6 +1,6 @@
 import { runAnalysis } from "../analysis.js";
 import { ConfigError } from "../config.js";
-import { RECORDED_CONFORMANCE, reportedConformance } from "../conformance.js";
+import { CONFORMANCE, DECLARED_GAPS } from "../conformance.js";
 import { analyzerProvenance, recordedFindings, verdictOf } from "../findings-pass.js";
 import { packageScope } from "../inventory.js";
 import { normalizePath, relativePath, resolvePath } from "../paths.js";
@@ -129,7 +129,8 @@ export const analyzeVerb = ({ err, host, inputs, scope, openClient, option, repe
         const built = buildReport({
             contractVersion: CONTRACT_VERSION,
             version,
-            conformance: reportedConformance(RECORDED_CONFORMANCE),
+            conformance: CONFORMANCE,
+            declaredGaps: DECLARED_GAPS,
             target: { kind, root, identity: identityOf(scoped.target, host) },
             configurations: configurationsOf(run.projects, targetRoot),
             unavailable: scoped.consumers.map((consumer) => ({

package/dist/src/verbs/describe.js

@@ -1,11 +1,11 @@
-import { RECORDED_CONFORMANCE } from "../conformance.js";
+import { CONFORMANCE } from "../conformance.js";
 import { ANALYZER_NAME, LANGUAGE, SCHEMA_VERSION } from "../report.js";
 import { CONTRACT_VERSION } from "../version.js";
 import { EXIT_CLEAN, EXIT_FAILURE, EXIT_USAGE } from "./verb.js";
 /**
  * The document `describe` writes: the analyzer, the Contract version it implements, the
  * report schema versions it reads, the languages it claims, and its recorded result over
- * the conformance corpus, absent where it records none.
+ * the conformance corpus.
  */
 export function describeDocument(version, recorded) {
     const document = {
@@ -14,15 +14,11 @@ export function describeDocument(version, recorded) {
         contract_version: CONTRACT_VERSION,
         schema_versions_accepted: [SCHEMA_VERSION],
         languages: [LANGUAGE],
-        ...(recorded === undefined
-            ? {}
-            : {
-                conformance: {
-                    corpus_version: recorded.corpusVersion,
-                    result: recorded.result,
-                    digest: recorded.digest,
-                },
-            }),
+        conformance: {
+            corpus_version: recorded.corpusVersion,
+            result: recorded.result,
+            digest: recorded.digest,
+        },
     };
     return `${JSON.stringify(document, null, 2)}\n`;
 }
@@ -40,6 +36,6 @@ export const describeVerb = ({ out, err, host, args }) => {
         err.write(`deadset-ts: describe: ${error instanceof Error ? error.message : String(error)}\n`);
         return EXIT_FAILURE;
     }
-    out.write(describeDocument(version, RECORDED_CONFORMANCE));
+    out.write(describeDocument(version, CONFORMANCE));
     return EXIT_CLEAN;
 };

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "3.9.0",
+  "version": "3.10.0",
   "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.10.0",
   "type": "module",
   "sideEffects": false,
   "description": "Deterministic dead-code analysis for TypeScript, class and type members included",

package/src/conformance-record.ts

@@ -0,0 +1,29 @@
+// Written by the conformance run from conformance.json and conformance-results.json.
+// Regenerate it with `UPDATE_GOLDEN=1 npx vitest --run src/conformance.corpus.test.ts`.
+export const RECORD = {
+  conformance: {
+    corpusVersion: "1.9.0",
+    result: "fail",
+    digest: "sha256:8c29f19fc189f4f5d9ea210d556b62d12c3701c221eb7a8adde499b7060bec0d",
+  },
+  gaps: [
+    {
+      fixture: "private-member-unread",
+      capability: "reflective-lookup",
+      reason:
+        "The reference pass resolves a string-literal element access to the member it names, so the member is live by that reference and the retained listing names no class for it.",
+    },
+    {
+      fixture: "redundant-export-keyword",
+      capability: "DS1104",
+      reason:
+        "No consumer is loaded beside the target, so the published surface is unknown and no export is narrowed; review an export only the target uses by hand.",
+    },
+    {
+      fixture: "unused-exported-consumer",
+      capability: "DS1001",
+      reason:
+        "No consumer is loaded beside the target, so an export nothing in the target references is reported at the possible class rather than the certain one.",
+    },
+  ],
+} as const;

package/src/conformance.ts

@@ -1,34 +1,32 @@
 /**
- * What this analyzer states about its own conformance: the corpus version it is written
- * against and its recorded result over that corpus, which `describe` and every report name.
+ * What this analyzer states about its own conformance: its recorded result over the
+ * conformance corpus and every capability it declines, which `describe` and every report
+ * name.
  */
+import { RECORD } from "./conformance-record.ts";
 
-/** The result one product reached over the conformance corpus. */
+/**
+ * The result one product reached over the conformance corpus. A declared gap never lowers
+ * it: the result is `pass` when no fixture fails, gaps or not, and `fail` otherwise.
+ */
 export interface Conformance {
   readonly corpusVersion: string;
   readonly result: "pass" | "fail";
-  /** `sha256:` and the lowercase hexadecimal SHA-256 of the results document the runner wrote. */
+  /** `sha256:` and the lowercase hexadecimal SHA-256 of the results document the run wrote. */
   readonly digest: string;
 }
 
-/** The version of the conformance corpus this analyzer is written against. */
-const CORPUS_VERSION = "1.9.0";
+/** One capability this analyzer declines, as `conformance.json` declares it. */
+export interface DeclaredGap {
+  readonly fixture: string;
+  /** The one expectation the gap covers, where it is narrower than the fixture. */
+  readonly symbol?: string;
+  readonly capability: string;
+  readonly reason: string;
+}
 
-/** The SHA-256 of zero bytes, which is the digest of a results document no run wrote. */
-const EMPTY_DIGEST = "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+/** The conformance run this analyzer records. */
+export const CONFORMANCE: Conformance = RECORD.conformance;
 
-/**
- * The conformance run this analyzer records, or undefined where it records none. A
- * description states exactly this, so a reader that requires a pass refuses an analyzer
- * that has not answered the corpus.
- */
-export const RECORDED_CONFORMANCE: Conformance | undefined = undefined;
-
-/**
- * The conformance a report states. A report requires the block, so an analyzer that
- * records no run states a failed one over the results document no run wrote, which a merge
- * refuses as it refuses any result other than a pass.
- */
-export function reportedConformance(recorded: Conformance | undefined): Conformance {
-  return recorded ?? { corpusVersion: CORPUS_VERSION, result: "fail", digest: EMPTY_DIGEST };
-}
+/** Every capability this analyzer declines, in the order `conformance.json` declares them. */
+export const DECLARED_GAPS: readonly DeclaredGap[] = RECORD.gaps;

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

package/src/report.ts

@@ -5,7 +5,7 @@
  */
 
 import type { Severity, Sort, TargetKind } from "./config.ts";
-import type { Conformance } from "./conformance.ts";
+import type { Conformance, DeclaredGap } from "./conformance.ts";
 import type { EdgeEvaluation } from "./edges.ts";
 import type {
   CompletedFinding,
@@ -105,6 +105,13 @@ export interface WireStaleSuppression {
   readonly message: string;
 }
 
+interface WireDeclaredGap {
+  readonly fixture: string;
+  readonly symbol?: string;
+  readonly capability: string;
+  readonly reason: string;
+}
+
 export interface WireTotals {
   readonly findings: number;
   readonly by_severity: { readonly allow: number; readonly warn: number; readonly deny: number };
@@ -159,7 +166,7 @@ export interface Report {
   readonly findings: readonly WireFinding[];
   readonly edge_evaluations: readonly WireEdgeEvaluation[];
   readonly stale_suppressions: readonly WireStaleSuppression[];
-  readonly declared_gaps: readonly never[];
+  readonly declared_gaps: readonly WireDeclaredGap[];
   readonly excluded_by_cgo: readonly never[];
   readonly test_file_rules: readonly TestFileRule[];
   readonly totals: WireTotals;
@@ -170,6 +177,7 @@ export interface ReportInput {
   readonly contractVersion: string;
   readonly version: string;
   readonly conformance: Conformance;
+  readonly declaredGaps: readonly DeclaredGap[];
   readonly target: { readonly kind: TargetKind; readonly root: string; readonly identity: string };
   readonly configurations: readonly ReportConfiguration[];
   readonly unavailable: readonly UnavailableConsumer[];
@@ -318,6 +326,16 @@ function canonicalStale(a: WireStaleSuppression, b: WireStaleSuppression): numbe
   );
 }
 
+/** One declared gap as a report carries it, its members in the schema's order. */
+function wireGap(gap: DeclaredGap): WireDeclaredGap {
+  return {
+    fixture: gap.fixture,
+    ...(gap.symbol === undefined ? {} : { symbol: gap.symbol }),
+    capability: gap.capability,
+    reason: gap.reason,
+  };
+}
+
 /** Edge evaluations by edge, then side, then their compact encodings. */
 function byEdge(a: WireEdgeEvaluation, b: WireEdgeEvaluation): number {
   return (
@@ -392,7 +410,11 @@ export function buildReport(input: ReportInput): Report {
     findings,
     edge_evaluations: input.result.edgeEvaluations.map(wireEvaluation).sort(byEdge),
     stale_suppressions: input.result.staleSuppressions.map(wireStale).sort(canonicalStale),
-    declared_gaps: [],
+    // Every gap shares the one component of the canonical key a gap supplies, the analyzer's
+    // name, so the compact encodings alone order them.
+    declared_gaps: input.declaredGaps
+      .map(wireGap)
+      .sort((a, b) => compare(JSON.stringify(a), JSON.stringify(b))),
     excluded_by_cgo: [],
     test_file_rules: [...input.testFileRules]
       .sort((a, b) => compare(a.rule, b.rule) || a.matched - b.matched)

package/src/verbs/analyze.ts

@@ -1,6 +1,6 @@
 import { runAnalysis, type RunProject } from "../analysis.ts";
 import { ConfigError, type Format } from "../config.ts";
-import { RECORDED_CONFORMANCE, reportedConformance } from "../conformance.ts";
+import { CONFORMANCE, DECLARED_GAPS } from "../conformance.ts";
 import { analyzerProvenance, recordedFindings, verdictOf } from "../findings-pass.ts";
 import { packageScope } from "../inventory.ts";
 import { normalizePath, relativePath, resolvePath } from "../paths.ts";
@@ -175,7 +175,8 @@ export const analyzeVerb: Verb = ({ err, host, inputs, scope, openClient, option
     const built = buildReport({
       contractVersion: CONTRACT_VERSION,
       version,
-      conformance: reportedConformance(RECORDED_CONFORMANCE),
+      conformance: CONFORMANCE,
+      declaredGaps: DECLARED_GAPS,
       target: { kind, root, identity: identityOf(scoped.target, host) },
       configurations: configurationsOf(run.projects, targetRoot),
       unavailable: scoped.consumers.map((consumer) => ({

package/src/verbs/describe.ts

@@ -1,4 +1,4 @@
-import { RECORDED_CONFORMANCE, type Conformance } from "../conformance.ts";
+import { CONFORMANCE, type Conformance } from "../conformance.ts";
 import { ANALYZER_NAME, LANGUAGE, SCHEMA_VERSION } from "../report.ts";
 import { CONTRACT_VERSION } from "../version.ts";
 import { EXIT_CLEAN, EXIT_FAILURE, EXIT_USAGE, type Verb } from "./verb.ts";
@@ -6,24 +6,20 @@ import { EXIT_CLEAN, EXIT_FAILURE, EXIT_USAGE, type Verb } from "./verb.ts";
 /**
  * The document `describe` writes: the analyzer, the Contract version it implements, the
  * report schema versions it reads, the languages it claims, and its recorded result over
- * the conformance corpus, absent where it records none.
+ * the conformance corpus.
  */
-export function describeDocument(version: string, recorded: Conformance | undefined): string {
+export function describeDocument(version: string, recorded: Conformance): string {
   const document = {
     name: ANALYZER_NAME,
     version,
     contract_version: CONTRACT_VERSION,
     schema_versions_accepted: [SCHEMA_VERSION],
     languages: [LANGUAGE],
-    ...(recorded === undefined
-      ? {}
-      : {
-          conformance: {
-            corpus_version: recorded.corpusVersion,
-            result: recorded.result,
-            digest: recorded.digest,
-          },
-        }),
+    conformance: {
+      corpus_version: recorded.corpusVersion,
+      result: recorded.result,
+      digest: recorded.digest,
+    },
   };
   return `${JSON.stringify(document, null, 2)}\n`;
 }
@@ -41,6 +37,6 @@ export const describeVerb: Verb = ({ out, err, host, args }) => {
     err.write(`deadset-ts: describe: ${error instanceof Error ? error.message : String(error)}\n`);
     return EXIT_FAILURE;
   }
-  out.write(describeDocument(version, RECORDED_CONFORMANCE));
+  out.write(describeDocument(version, CONFORMANCE));
   return EXIT_CLEAN;
 };