@cplieger/deadset-ts 7.2.0-dev.4 → 8.0.0-dev.10

package/src/suppress.ts

@@ -7,7 +7,13 @@
  * withholds every such finding anyway, and stale otherwise.
  */
 
-import { ConfigError } from "./config.ts";
+import {
+  type CODE,
+  KIND_ROWS,
+  SYMBOL_SUBJECTS,
+  type Subject,
+} from "./contract/contract.generated.ts";
+import { UsageError } from "./usage.ts";
 import type { Finding } from "./finding.ts";
 import { positionKey, type Position } from "./position.ts";
 import { isRef } from "./ref.ts";
@@ -15,15 +21,6 @@ import { isRef } from "./ref.ts";
 /** Which document a suppression is written in, spelled as a finding carries it. */
 export type Mechanism = "inline" | "ignore" | "baseline";
 
-/** The code a suppression that carries no reason is reported under. */
-export const SUPPRESSION_WITHOUT_REASON = "DS1701";
-
-/** The code an ignore entry or a baseline row that names no path is reported under. */
-export const UNSCOPED_ENTRY = "DS1702";
-
-/** The code a suppression that withholds nothing is reported under. */
-export const STALE_SUPPRESSION = "DS1703";
-
 /**
  * One suppression record: one code bound to one site. A directive naming two codes is two
  * records with one reason, and a directive above a line that declares two symbols is one
@@ -49,7 +46,7 @@ export interface SuppressionRecord {
  * nothing, and its finding reports the suppression as written.
  */
 export interface Refusal {
-  readonly reported: typeof SUPPRESSION_WITHOUT_REASON | typeof UNSCOPED_ENTRY;
+  readonly reported: typeof CODE.suppressionWithoutReason | typeof CODE.unscopedIgnoreEntry;
   readonly code: string;
   /** The reference the entry names, empty for a directive. */
   readonly symbol: string;
@@ -71,9 +68,9 @@ export interface Suppressions {
  * instruction the analysis cannot carry out. It is a malformed input, so the command line
  * answers it with the usage code.
  */
-export class SuppressionError extends ConfigError {
+export class SuppressionError extends UsageError {
   constructor(mechanism: Mechanism, at: string, text: string, want: string) {
-    super("malformed", at, `${mechanism} ${at}: ${text}: want ${want}`);
+    super(`${mechanism} ${at}: ${text}: want ${want}`);
     this.name = "SuppressionError";
   }
 }
@@ -115,6 +112,7 @@ export const GO_REF_EXPRESSIONS: readonly string[] = [
   `^go://${GO_PATH}#${GO_IDENT}$`,
   `^go://${GO_PATH}#${GO_IDENT}(?:\\.${GO_IDENT})+$`,
   `^go://${GO_PATH}#${GO_IDENT}(?:\\.${GO_IDENT})?\\[${GO_IDENT}\\]$`,
+  `^go://${GO_PATH}#(?:${GO_IDENT}(?:\\.${GO_IDENT})?)?\\(${GO_IDENT}\\)$`,
   `^go://${GO_PATH}#${GO_FILE}:file$`,
   `^go://${GO_PATH}#${GO_PATH}(?:@${GO_VERSION})?:require$`,
   `^go://${GO_PATH}#${GO_PATH}(?:@${GO_VERSION})?:replace$`,
@@ -157,48 +155,48 @@ export interface Ledger {
   readonly withheld: (finding: Finding) => boolean;
 }
 
-/**
- * The subject kinds that are a dependency row, each with the code that reports one. An
- * ignore entry or a baseline row naming the row's reference and file withholds its finding
- * and marks nothing, and an inline directive never binds one.
- */
-const DEPENDENCY_SUBJECTS: ReadonlyMap<string, readonly string[]> = new Map([
-  ["dependency", ["DS1601"]],
-  ["module-directive", ["DS1605"]],
-]);
+/** The subject of the kind each live code names. */
+const SUBJECT_OF_CODE: ReadonlyMap<string, Subject> = new Map(
+  KIND_ROWS.map((row): [string, Subject] => [row.code, row.subject]),
+);
+
+/** The subject a finding about one symbol kind is about. */
+function subjectOf(kind: string): Subject | undefined {
+  return Object.hasOwn(SYMBOL_SUBJECTS, kind)
+    ? SYMBOL_SUBJECTS[kind as keyof typeof SYMBOL_SUBJECTS]
+    : undefined;
+}
+
+/** Whether a subject is a row of a document rather than a declaration of the program. */
+function rowOf(subject: Subject | undefined): boolean {
+  return subject === "file" || subject === "dependency" || subject === "record";
+}
 
 /**
- * The subject kinds that are a row of a document rather than a declaration of the program,
- * each with the codes that report one. Apart from a dependency row, nothing withholds a
- * finding about one.
+ * Whether a finding's subject is a row of a document rather than a declaration. Apart
+ * from a dependency row, nothing withholds a finding about one.
  */
-const ROW_SUBJECTS: ReadonlyMap<string, readonly string[]> = new Map([
-  ["file", ["DS1501", "DS1502"]],
-  ...DEPENDENCY_SUBJECTS,
-  ["root", ["DS1704"]],
-  ["configured-declaration", ["DS1706"]],
-  ["suppression", ["DS1701", "DS1702", "DS1703"]],
-  ["edge", ["DS1705"]],
-]);
-
-/** Whether a finding's subject is a row of a document rather than a declaration. */
 export function isRowSubject(kind: string): boolean {
-  return ROW_SUBJECTS.has(kind);
+  return rowOf(subjectOf(kind));
 }
 
 /** Whether a code reports a row of a document. */
 export function isRowCode(code: string): boolean {
-  return [...ROW_SUBJECTS.values()].some((codes) => codes.includes(code));
+  return rowOf(SUBJECT_OF_CODE.get(code));
 }
 
-/** Whether a finding's subject is a dependency row. */
+/**
+ * Whether a finding's subject is a dependency row. An ignore entry or a baseline row
+ * naming the row's reference and file withholds its finding and marks nothing, and an
+ * inline directive never binds one.
+ */
 export function isDependencySubject(kind: string): boolean {
-  return DEPENDENCY_SUBJECTS.has(kind);
+  return subjectOf(kind) === "dependency";
 }
 
 /** Whether a code reports a dependency row, which only an ignore entry or a baseline row names. */
 export function isDependencyCode(code: string): boolean {
-  return [...DEPENDENCY_SUBJECTS.values()].some((codes) => codes.includes(code));
+  return SUBJECT_OF_CODE.get(code) === "dependency";
 }
 
 /** Whether a code reports a row of a document that no record of any mechanism can name. */
@@ -207,33 +205,20 @@ export function isUnsuppressibleCode(code: string): boolean {
 }
 
 /**
- * The subject kinds that are a part of a declaration rather than a declaration: a part
+ * Whether a finding's subject is a part of the declaration its reference names: a part
  * has no reference of its own, so a finding about one names the declaration that holds
  * it, and the part is decided inside that declaration whatever uses it.
  */
-const PART_SUBJECTS: ReadonlySet<string> = new Set([
-  "parameter",
-  "receiver",
-  "result",
-  "statement",
-  "case",
-  "store",
-]);
-
-/** Whether a finding's subject is a part of the declaration its reference names. */
 export function isPartSubject(kind: string): boolean {
-  return PART_SUBJECTS.has(kind);
+  return subjectOf(kind) === "part";
 }
 
-/** The prefix of the codes of the part kinds, the intra-function range. */
-const PART_KIND_PREFIX = "DS18";
-
 /**
  * Whether a code is a part kind, whose record withholds its finding and marks nothing:
  * the record says the part is wanted, not that the declaration holding it is.
  */
 export function isPartKind(code: string): boolean {
-  return code.startsWith(PART_KIND_PREFIX);
+  return SUBJECT_OF_CODE.get(code) === "part";
 }
 
 /** One finding's identity: its code and the position of the thing it names. */
@@ -243,29 +228,33 @@ function claimKey(finding: Finding): string {
 
 /**
  * Whether one record names one finding. A record reaches a finding in two ways: it bound
- * the declaration at the finding's position, or it names the finding's reference and the
- * file the finding is reported in, each exactly. The second is how an entry copied from a
- * finding about a part of a declaration reaches the part, and the only way any record
- * reaches a dependency row.
+ * the declaration at the finding's position, or it names the finding's reference, or the
+ * reference of the declaration holding a part that has one of its own, and the file the
+ * finding is reported in, each exactly. The second is how an entry copied from a finding
+ * about a part of a declaration reaches the part, and the only way any record reaches a
+ * dependency row.
  */
 export function pairs(record: SuppressionRecord, finding: Finding): boolean {
   if (record.code !== finding.code) {
     return false;
   }
-  if (DEPENDENCY_SUBJECTS.has(finding.symbol.kind)) {
+  if (isDependencySubject(finding.symbol.kind)) {
     return (
       record.mechanism !== "inline" &&
       record.symbol === finding.symbol.ref &&
       record.path === finding.position.path
     );
   }
-  if (ROW_SUBJECTS.has(finding.symbol.kind)) {
+  if (isRowSubject(finding.symbol.kind)) {
     return false;
   }
   if (record.bound !== "" && record.bound === positionKey(finding.position)) {
     return true;
   }
-  return record.symbol === finding.symbol.ref && record.path === finding.position.path;
+  return (
+    (record.symbol === finding.symbol.ref || record.symbol === finding.symbol.holder) &&
+    record.path === finding.position.path
+  );
 }
 
 /**

package/src/sweep.ts

@@ -8,6 +8,7 @@
 
 import type { TSExemptionClass } from "./exempt-classes.ts";
 import { namesACaller, OUTSIDE, type Edge, type Graph } from "./graph.ts";
+import type { InventorySymbol } from "./inventory.ts";
 import type { Position } from "./position.ts";
 
 /** The liveness relation that decided a declaration, as a finding spells it. */
@@ -32,6 +33,8 @@ export interface Exemption {
    * The record holds only while one of them is called through its interface.
    */
   readonly implementing?: Implementing;
+  /** Whether the record holds only where a write the mode counts stores into the declaration. */
+  readonly whileWritten?: true;
 }
 
 /** The interface methods one retained class member implements, and whether its body is empty. */
@@ -178,23 +181,45 @@ export function sweep(graph: Graph, input: SweepInput): Liveness {
   return { liveUnder: live, candidates };
 }
 
+/**
+ * The directory a test runner reads a manual mock from, whose exports it puts in place of
+ * the module's: https://jestjs.io/docs/manual-mocks
+ */
+const MANUAL_MOCKS = "__mocks__";
+
+/** Whether a test runner calls or reads one export of a test file: a function, or any export of a manual mock. */
+export function runnerCalls(symbol: InventorySymbol): boolean {
+  return symbol.kind === "function" || symbol.position.path.split("/").includes(MANUAL_MOCKS);
+}
+
 /**
  * Per declaration of the graph, whether the run that counts test references reaches it.
- * That run's roots are the graph's own and each test file, being the file's top level
- * and every declaration it exports, which a test runner may call; `held` seeds it as a
- * mark or an exemption seeds a sweep.
+ * That run's roots are the graph's own and, of each test file, its top level and every
+ * function it exports, which a test runner may call, and every export of a manual mock,
+ * which the runner reads; any other export of a test file, and test-support code, which
+ * runs where a test imports it, are judged as any file's are. `held` seeds it as a mark
+ * seeds a sweep; with `namespaces` false a file read reaches none of the file's exports.
  */
-export function reachedWithTheTests(graph: Graph, held: readonly string[]): readonly boolean[] {
+export function reachedWithTheTests(
+  graph: Graph,
+  held: readonly string[],
+  namespaces = true,
+): readonly boolean[] {
   const tests = graph.symbols.flatMap((symbol, at) => {
-    const top =
-      symbol.kind === "file" || graph.symbols[graph.parent[at] ?? OUTSIDE]?.kind === "file";
-    return graph.test[at] === true && top && (symbol.kind === "file" || symbol.exported)
+    const exported = symbol.exported && graph.symbols[graph.parent[at] ?? OUTSIDE]?.kind === "file";
+    const called = exported && runnerCalls(symbol);
+    return graph.test[at] === true &&
+      graph.support[at] !== true &&
+      (symbol.kind === "file" || called)
       ? [{ at, kind: "test-runner" as const }]
       : [];
   });
-  return reachable({ ...graph, rooted: [...graph.rooted, ...tests] }, flagged(graph, held), {
-    production: false,
-  });
+  return reachable(
+    { ...graph, rooted: [...graph.rooted, ...tests] },
+    flagged(graph, held),
+    { production: false },
+    namespaces,
+  );
 }
 
 /**
@@ -224,7 +249,12 @@ function flagged(graph: Graph, ids: readonly string[]): boolean[] {
  * included, while a root reaches through the references the mode counts. The held seed
  * runs first, so what it reaches is expanded under the wider rule.
  */
-function reachable(graph: Graph, held: readonly boolean[], mode: Mode): readonly boolean[] {
+function reachable(
+  graph: Graph,
+  held: readonly boolean[],
+  mode: Mode,
+  namespaces = true,
+): readonly boolean[] {
   const reached = graph.symbols.map(() => false);
   const expanded = graph.symbols.map(() => false);
   const queue: number[] = [];
@@ -253,7 +283,7 @@ function reachable(graph: Graph, held: readonly boolean[], mode: Mode): readonly
         if (!holding && mode.production && edge.test) {
           continue;
         }
-        enter(edge.to, !edge.evaluation);
+        enter(edge.to, namespaces && !edge.evaluation);
       }
     }
   };
@@ -269,7 +299,7 @@ function reachable(graph: Graph, held: readonly boolean[], mode: Mode): readonly
   }
   // A consumer's reference reaches what it names as one of the target's own does.
   for (const edge of callsOf(graph, mode)) {
-    enter(edge.to, !edge.evaluation);
+    enter(edge.to, namespaces && !edge.evaluation);
   }
   walk(false);
   return reached;
@@ -277,10 +307,11 @@ function reachable(graph: Graph, held: readonly boolean[], mode: Mode): readonly
 
 /**
  * Admits every test declaration whose set of referenced production declarations is
- * non-empty and wholly dead, and returns which it admitted. The set is read from every
- * reference the test makes, which a production sweep does not count. A test-support
- * declaration that a test referencing a live target also references is a live target of
- * every test referencing it. A marked or exempt test is never admitted.
+ * non-empty and wholly dead, and returns which it admitted. An ambient declaration describes
+ * code the target does not implement, so it is no production declaration here. The set is
+ * read from every reference the test makes, which a production sweep does not count. A
+ * test-support declaration a test referencing a live target also references is a live
+ * target of every test referencing it. A marked or exempt test is never admitted.
  */
 function admitTestsOfDeadCode(
   graph: Graph,
@@ -293,7 +324,11 @@ function admitTestsOfDeadCode(
     let live = 0;
     if (testCode(at) && graph.subject[at] === true && held[at] !== true) {
       for (const edge of graph.out[at] ?? []) {
-        if (testCode(edge.to) || graph.subject[edge.to] !== true) {
+        if (
+          testCode(edge.to) ||
+          graph.subject[edge.to] !== true ||
+          graph.ambient[edge.to] === true
+        ) {
           continue;
         }
         targets += 1;

package/src/symbol-keys.ts

@@ -2,24 +2,31 @@
  * The members a unique symbol keys, used through element accesses. `value[key]`, where
  * `key` is a constant of a `unique symbol` type, reads the member of the receiver's type
  * whose computed name is that same constant, and a store through the access writes it.
- * No name node resolves to such a member: the key's name resolves to the constant.
+ * No name node resolves to such a member: the key's name resolves to the constant. An
+ * iteration reads the member its well-known iteration symbol keys.
  */
 
 import {
   isComputedPropertyName,
+  isForOfStatement,
   isIdentifier,
   isNoSubstitutionTemplateLiteral,
   isNumericLiteral,
-  isParenthesizedExpression,
   isPropertyAccessExpression,
+  isSpreadElement,
   isStringLiteral,
   type ElementAccessExpression,
+  type Expression,
   type Node,
+  type SourceFile,
 } from "@typescript/native/ast";
+import { parenthesesRemoved } from "./unwrap.ts";
 import type { Symbol as TSSymbol, Type } from "@typescript/native/sync";
 import type { AliasChains } from "./alias-chain.ts";
-import type { InventorySymbol } from "./inventory.ts";
+import { nodeKey, type Inventory, type InventorySymbol } from "./inventory.ts";
+import { renderPosition } from "./position.ts";
 import { isAnswered, type PropertyTables } from "./query.ts";
+import type { Reference } from "./references.ts";
 import type { ProjectView } from "./session.ts";
 
 /** One element access whose key is a name, and how the access uses the member it selects. */
@@ -45,10 +52,7 @@ interface KeyedUse {
 
 /** The identifier an element access's argument names its key by, where it is a name. */
 export function keyNameOf(argument: Node): Node | undefined {
-  let at = argument;
-  while (isParenthesizedExpression(at)) {
-    at = at.expression;
-  }
+  const at = parenthesesRemoved(argument);
   if (isIdentifier(at)) {
     return at;
   }
@@ -170,3 +174,123 @@ export function keyedUses<Brand>(
     return ids.length === 0 ? [] : [{ access: one.access, ids: [...new Set(ids)] }];
   });
 }
+
+/** The well-known symbol a value's iteration calls, by the construct that iterates it. */
+type Protocol = "iterator" | "asyncIterator";
+
+/** The member name `[Symbol.<name>]` spells, where a computed name spells one. */
+function wellKnownName(name: Node | undefined): string | undefined {
+  if (name === undefined || !isComputedPropertyName(name)) {
+    return undefined;
+  }
+  const key = name.expression;
+  return isPropertyAccessExpression(key) &&
+    isIdentifier(key.expression) &&
+    key.expression.text === "Symbol" &&
+    isIdentifier(key.name)
+    ? key.name.text
+    : undefined;
+}
+
+/**
+ * The references the iterations of one project's own files make to the iteration members
+ * of the values they iterate: a `for…of` statement and a spread element read
+ * `[Symbol.iterator]`, and a `for await…of` statement reads `[Symbol.asyncIterator]` and,
+ * which it falls back to, `[Symbol.iterator]`. Each is made by the declaration holding it.
+ */
+export function iterationReferences<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+  chains: AliasChains,
+  root: string,
+  testFiles: ReadonlySet<string>,
+): readonly Reference[] {
+  const queries = project.queries;
+  const ownPaths = project.ownPaths();
+  const iterated: {
+    readonly file: SourceFile;
+    readonly from: string;
+    readonly operand: Expression;
+    readonly protocols: readonly Protocol[];
+  }[] = [];
+  for (const file of project.ownSourceFiles()) {
+    const fileId = held.declarations.get(nodeKey(file, file));
+    if (fileId === undefined) {
+      continue;
+    }
+    const visit = (node: Node, from: string): void => {
+      const holder = held.declarations.get(nodeKey(file, node)) ?? from;
+      if (isForOfStatement(node)) {
+        const protocols: readonly Protocol[] =
+          node.awaitModifier === undefined ? ["iterator"] : ["asyncIterator", "iterator"];
+        iterated.push({ file, from: holder, operand: node.expression, protocols });
+      } else if (isSpreadElement(node)) {
+        iterated.push({ file, from: holder, operand: node.expression, protocols: ["iterator"] });
+      }
+      node.forEachChild((child) => {
+        visit(child, holder);
+      });
+    };
+    file.forEachChild((child) => {
+      visit(child, fileId);
+    });
+  }
+  if (iterated.length === 0) {
+    return [];
+  }
+  const types = queries.typesAt(iterated.map((one) => one.operand));
+  const members = new Map<
+    number,
+    readonly { readonly name: string; readonly ids: readonly string[] }[]
+  >();
+  const membersOf = (
+    type: Type,
+  ): readonly { readonly name: string; readonly ids: readonly string[] }[] => {
+    const known = members.get(type.id);
+    if (known !== undefined) {
+      return known;
+    }
+    const keyed: { name: string; ids: readonly string[] }[] = [];
+    const properties = queries.propertiesOf(type);
+    for (const property of isAnswered(properties) ? properties : []) {
+      for (const handle of property.declarations) {
+        const node = ownPaths.has(handle.path) ? project.declarationAt(handle)?.node : undefined;
+        const name = wellKnownName((node as { readonly name?: Node } | undefined)?.name);
+        if (name !== undefined) {
+          keyed.push({ name, ids: chains.declarationsOf(property) });
+          break;
+        }
+      }
+    }
+    members.set(type.id, keyed);
+    return keyed;
+  };
+  const found: Reference[] = [];
+  iterated.forEach((one, index) => {
+    const type = types[index];
+    if (type === undefined || !isAnswered(type)) {
+      return;
+    }
+    const parts =
+      type.isUnionType() || type.isIntersectionType() ? queries.constituents(type) : [type];
+    const position = renderPosition(one.file, root, one.operand.getStart());
+    for (const part of isAnswered(parts) ? parts : []) {
+      for (const member of membersOf(part)) {
+        if (!(one.protocols as readonly string[]).includes(member.name)) {
+          continue;
+        }
+        for (const to of member.ids) {
+          found.push({
+            from: one.from,
+            to,
+            position,
+            use: "read",
+            resolution: "keyed",
+            test: testFiles.has(position.path),
+          });
+        }
+      }
+    }
+  });
+  return found;
+}

package/src/template-field.ts

@@ -13,13 +13,16 @@
  */
 
 import { readComponent } from "./component-files.ts";
-import { ConfigError, type Analysis, type TemplateDelimiters } from "./config.ts";
+import type { ResolvedConfig, TemplateDelimiters } from "./config.ts";
 import type { DetectorInput, Evidence } from "./exempt.ts";
 import type { Host } from "./host.ts";
 import type { SymbolKind } from "./inventory.ts";
 import { memberNames } from "./member-names.ts";
 import { extensionOf, isAbsolutePath, joinPath, normalizePath, relativePath } from "./paths.ts";
 import { isComponentFile, type Position } from "./position.ts";
+import { bytewise } from "./text/compare.ts";
+import { filesBelow } from "./fs/tree.ts";
+import { UsageError } from "./usage.ts";
 
 /** One template, by its path below the target root. */
 interface TemplateFile {
@@ -50,14 +53,6 @@ const READ_BY_MARKUP: ReadonlySet<SymbolKind> = new Set([...READ_BY_A_TEMPLATE,
 /** One identifier, as the grammar of the analyzed language spells one. */
 const IDENTIFIER = /[\p{ID_Start}$_][\p{ID_Continue}$\u200C\u200D]*/uy;
 
-/** Two strings ordered bytewise. */
-function compare(a: string, b: string): number {
-  if (a === b) {
-    return 0;
-  }
-  return a < b ? -1 : 1;
-}
-
 /**
  * Every template under the configured directories, read once for the run, in path
  * order and each file once. A directory is named relative to the target root, and
@@ -66,25 +61,22 @@ function compare(a: string, b: string): number {
  * exemption it was configured for off. A symbolic link to a directory is not
  * followed.
  */
-export function readTemplates(host: Host, targetRoot: string, analysis: Analysis): Templates {
+export function readTemplates(
+  host: Host,
+  targetRoot: string,
+  analysis: ResolvedConfig["analysis"],
+): Templates {
   const files = new Map<string, string>();
   const read = (dir: string): void => {
-    const entries = [...host.readDirectory(joinPath(targetRoot, dir))].sort((a, b) =>
-      compare(a.name, b.name),
-    );
-    for (const entry of entries) {
-      const path = joinPath(dir, entry.name);
-      if (entry.directory) {
-        read(path);
-        continue;
-      }
+    for (const below of filesBelow(host, joinPath(targetRoot, dir), () => true)) {
+      const path = joinPath(dir, below);
       const absolute = joinPath(targetRoot, path);
       if (!files.has(path) && host.kindOf(absolute) === "file") {
         files.set(path, host.readFile(absolute));
       }
     }
   };
-  for (const configured of analysis.templateDirs) {
+  for (const configured of analysis.template_dirs) {
     const dir = normalizePath(configured);
     if (
       isAbsolutePath(dir) ||
@@ -92,19 +84,17 @@ export function readTemplates(host: Host, targetRoot: string, analysis: Analysis
       dir.startsWith("../") ||
       host.kindOf(joinPath(targetRoot, dir)) !== "directory"
     ) {
-      throw new ConfigError(
-        "malformed",
-        "analysis.template_dirs",
+      throw new UsageError(
         `analysis.template_dirs: ${JSON.stringify(configured)} is not a directory below the target root`,
       );
     }
     read(dir);
   }
   return {
-    delimiters: analysis.templateDelimiters,
+    delimiters: analysis.template_delimiters,
     files: [...files]
       .map(([path, text]) => ({ path, text }))
-      .sort((a, b) => compare(a.path, b.path)),
+      .sort((a, b) => bytewise(a.path, b.path)),
   };
 }