@cplieger/deadset-ts 3.5.0 → 3.7.0

package/src/implementations.ts

@@ -0,0 +1,286 @@
+/**
+ * Which classes of the target implement which of its interfaces, and how each writes
+ * every method such an interface declares. A class implements an interface its
+ * `implements` clause names, in any instantiation, or one with a member its instance
+ * type is assignable to, asked only of a class carrying every member the interface
+ * requires and one it declares, and never of a generic side.
+ */
+
+import {
+  isClassDeclaration,
+  isHeritageClause,
+  isInterfaceDeclaration,
+  isMethodDeclaration,
+  SyntaxKind,
+  type Node,
+} from "@typescript/native/unstable/ast";
+import { SymbolFlags, type Symbol as TSSymbol, type Type } from "@typescript/native/unstable/sync";
+import { aliasChains } from "./alias-chain.ts";
+import { nodeKey, type Inventory } from "./inventory.ts";
+import { DEFAULT_BATCH_CAP } from "./references.ts";
+import type { ProjectView } from "./session.ts";
+
+/** What one run knows about how its interfaces are implemented. */
+export interface Implementations {
+  /** Per interface declaration, the classes that implement it, each by its identifier. */
+  readonly classes: ReadonlyMap<string, ReadonlySet<string>>;
+  /**
+   * Per method an interface declares, each class that implements it and whether that
+   * class's implementation is a method whose body holds no statement.
+   */
+  readonly bodies: ReadonlyMap<string, ReadonlyMap<string, boolean>>;
+}
+
+/** One interface or class the inventory holds, by its declaration. */
+interface Declared {
+  readonly id: string;
+  readonly nameNode: Node;
+  readonly generic: boolean;
+}
+
+/** One entry of a class's `implements` clause. */
+interface Clause {
+  readonly owner: Declared;
+  readonly entry: Node;
+}
+
+/** One interface type, the declarations it has, and the members it carries. */
+interface InterfaceAt {
+  readonly ids: string[];
+  readonly type: Type;
+  generic: boolean;
+  members?: readonly TSSymbol[];
+}
+
+/** One class, its instance type, and the members that type carries by name. */
+interface ClassAt {
+  readonly owner: Declared;
+  readonly type: Type;
+  members?: ReadonlyMap<string, TSSymbol>;
+}
+
+/** The interfaces, the classes and the `implements` entries of one project's own files. */
+function walk<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+): {
+  readonly interfaces: readonly Declared[];
+  readonly classes: readonly Declared[];
+  readonly clauses: readonly Clause[];
+} {
+  const interfaces: Declared[] = [];
+  const classes: Declared[] = [];
+  const clauses: Clause[] = [];
+  for (const file of project.ownSourceFiles()) {
+    const visit = (node: Node): void => {
+      if (isInterfaceDeclaration(node) || isClassDeclaration(node)) {
+        const id = held.declarations.get(nodeKey(file, node));
+        const name = node.name;
+        if (id !== undefined && name !== undefined) {
+          const declared = { id, nameNode: name, generic: node.typeParameters !== undefined };
+          if (isInterfaceDeclaration(node)) {
+            interfaces.push(declared);
+          } else {
+            classes.push(declared);
+            for (const clause of node.heritageClauses ?? []) {
+              if (isHeritageClause(clause) && clause.token === SyntaxKind.ImplementsKeyword) {
+                clauses.push(...clause.types.map((entry) => ({ owner: declared, entry })));
+              }
+            }
+          }
+        }
+      }
+      node.forEachChild(visit);
+    };
+    file.forEachChild(visit);
+  }
+  return { interfaces, classes, clauses };
+}
+
+/** The type at each node, asked in capped batches. */
+function typesAt<Brand>(project: ProjectView<Brand>, nodes: readonly Node[]): Map<Node, Type> {
+  const typeAt = new Map<Node, Type>();
+  for (let from = 0; from < nodes.length; from += DEFAULT_BATCH_CAP) {
+    const run = nodes.slice(from, from + DEFAULT_BATCH_CAP);
+    project.checker.getTypeAtLocation(run).forEach((type, index) => {
+      const node = run[index];
+      if (type !== undefined && node !== undefined) {
+        typeAt.set(node, type);
+      }
+    });
+  }
+  return typeAt;
+}
+
+/** Whether one class member is a method whose every written body holds no statement. */
+function emptyImplementation<Brand>(project: ProjectView<Brand>, member: TSSymbol): boolean {
+  const own = new Set(project.ownSourceFiles().map((file) => file.fileName));
+  let bodies = 0;
+  for (const handle of member.declarations) {
+    // A body outside the target is one this analysis cannot read, so it is not empty.
+    if (!own.has(handle.path)) {
+      return false;
+    }
+    const node = project.declarationAt(handle)?.node;
+    if (node === undefined || !isMethodDeclaration(node)) {
+      return false;
+    }
+    if (node.body !== undefined) {
+      if (node.body.statements.length > 0) {
+        return false;
+      }
+      bodies += 1;
+    }
+  }
+  return bodies > 0;
+}
+
+/** How one project's interfaces are implemented by its classes. */
+export function implementations<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+): Implementations {
+  const classes = new Map<string, Set<string>>();
+  const bodies = new Map<string, Map<string, boolean>>();
+  const walked = walk(project, held);
+  if (walked.interfaces.length === 0 || walked.classes.length === 0) {
+    return { classes, bodies };
+  }
+
+  const checker = project.checker;
+  const typeAt = typesAt(project, [
+    ...walked.interfaces.map((one) => one.nameNode),
+    ...walked.classes.map((one) => one.nameNode),
+    ...walked.clauses.map((clause) => clause.entry),
+  ]);
+
+  // Two declarations of one interface merge into one type.
+  const byType = new Map<number, InterfaceAt>();
+  for (const declared of walked.interfaces) {
+    const type = typeAt.get(declared.nameNode);
+    if (type === undefined) {
+      continue;
+    }
+    const merged = byType.get(type.id);
+    if (merged === undefined) {
+      byType.set(type.id, { ids: [declared.id], type, generic: declared.generic });
+    } else {
+      merged.ids.push(declared.id);
+      merged.generic ||= declared.generic;
+    }
+  }
+  const classAt = new Map<string, ClassAt>();
+  for (const owner of walked.classes) {
+    const type = typeAt.get(owner.nameNode);
+    if (type !== undefined) {
+      classAt.set(owner.id, { owner, type });
+    }
+  }
+
+  const membersOf = (at: InterfaceAt): readonly TSSymbol[] =>
+    (at.members ??= checker.getPropertiesOfType(at.type));
+  const classMembers = (at: ClassAt): ReadonlyMap<string, TSSymbol> =>
+    (at.members ??= new Map(
+      checker.getPropertiesOfType(at.type).map((member) => [member.escapedName, member]),
+    ));
+
+  const methodIds = new Set(
+    held.symbols.filter((symbol) => symbol.kind === "interface-method").map((symbol) => symbol.id),
+  );
+  const chains = aliasChains(project, held);
+  const record = (at: InterfaceAt, implementer: ClassAt): void => {
+    for (const id of at.ids) {
+      let set = classes.get(id);
+      if (set === undefined) {
+        set = new Set();
+        classes.set(id, set);
+      }
+      set.add(implementer.owner.id);
+    }
+    const written = classMembers(implementer);
+    for (const member of membersOf(at)) {
+      const answering = written.get(member.escapedName);
+      if (answering === undefined) {
+        continue;
+      }
+      const empty = emptyImplementation(project, answering);
+      for (const id of chains.declarationsOf(member)) {
+        if (!methodIds.has(id)) {
+          continue;
+        }
+        let byClass = bodies.get(id);
+        if (byClass === undefined) {
+          byClass = new Map();
+          bodies.set(id, byClass);
+        }
+        byClass.set(implementer.owner.id, empty);
+      }
+    }
+  };
+
+  const recorded = new Set<string>();
+  const pair = (at: InterfaceAt, implementer: ClassAt): void => {
+    const key = `${String(at.type.id)}:${implementer.owner.id}`;
+    if (!recorded.has(key)) {
+      recorded.add(key);
+      record(at, implementer);
+    }
+  };
+
+  for (const clause of walked.clauses) {
+    const entry = typeAt.get(clause.entry);
+    const implementer = classAt.get(clause.owner.id);
+    if (entry === undefined || implementer === undefined) {
+      continue;
+    }
+    const at = byType.get(entry.isTypeReference() ? entry.getTarget().id : entry.id);
+    if (at !== undefined) {
+      pair(at, implementer);
+    }
+  }
+
+  for (const at of byType.values()) {
+    const members = at.generic ? [] : membersOf(at);
+    if (members.length === 0) {
+      continue;
+    }
+    const required = members.filter((member) => (member.flags & SymbolFlags.Optional) === 0);
+    for (const implementer of classAt.values()) {
+      if (implementer.owner.generic) {
+        continue;
+      }
+      const written = classMembers(implementer);
+      if (
+        required.every((member) => written.has(member.escapedName)) &&
+        members.some((member) => written.has(member.escapedName)) &&
+        checker.isTypeAssignableTo(implementer.type, at.type)
+      ) {
+        pair(at, implementer);
+      }
+    }
+  }
+  return { classes, bodies };
+}
+
+/** Every project's answers as one run's, each implementation once. */
+export function mergeImplementations(per: readonly Implementations[]): Implementations {
+  const classes = new Map<string, Set<string>>();
+  const bodies = new Map<string, Map<string, boolean>>();
+  for (const one of per) {
+    for (const [id, held] of one.classes) {
+      const set = classes.get(id) ?? new Set();
+      classes.set(id, set);
+      for (const owner of held) {
+        set.add(owner);
+      }
+    }
+    for (const [id, held] of one.bodies) {
+      const byClass = bodies.get(id) ?? new Map<string, boolean>();
+      bodies.set(id, byClass);
+      for (const [owner, empty] of held) {
+        byClass.set(owner, (byClass.get(owner) ?? true) && empty);
+      }
+    }
+  }
+  return { classes, bodies };
+}

package/src/inventory.ts

@@ -224,7 +224,7 @@ interface Named {
  * One directory is read at most once, because a package holds many files and a
  * manifest read is a filesystem call.
  */
-function packages(host: Host, root: string): (path: string) => Module {
+export function packageScope(host: Host, root: string): (path: string) => Module {
   const named = new Map<string, Named | undefined>();
 
   const manifestName = (dir: string): string | undefined => {
@@ -480,7 +480,7 @@ export function inventory<Brand>(
 ): Inventory {
   const files = project.ownSourceFiles();
   const ownFiles = new Set(files.map((file) => file.fileName));
-  const moduleOf = packages(host, targetRoot);
+  const moduleOf = packageScope(host, targetRoot);
 
   const building: Building[] = [];
   const byNode = new Map<string, Building>();

package/src/kinds.ts

@@ -1,53 +1,87 @@
+import type { Confidence, Severity } from "./config.ts";
+
+/** What a mechanical edit may do with a finding of one kind. */
+export type Fixability = "deletable" | "narrowable" | "manual" | "none";
+
+/** One live row of the issue-kind vocabulary, as far as an analyzer reads it. */
+export interface KindRow {
+  readonly code: string;
+  /** The kind's name, which a finding carries as its `kind`. */
+  readonly name: string;
+  /** The severity a finding carries where no severity key names its code or its family. */
+  readonly defaultSeverity: Severity;
+  /** The highest confidence a finding of the kind carries. */
+  readonly maxClass: Confidence;
+  readonly fixability: Fixability;
+  /**
+   * Whether the Contract fixes the kind on at its default severity, so a severity key
+   * naming the code, or a family prefix whose range holds it, is an unimplemented key.
+   */
+  readonly fixed: boolean;
+}
+
 /**
- * The issue-kind codes whose severity the Contract fixes. A severity key naming
- * one, or a family prefix whose range holds one, is an unimplemented key rather
- * than a setting.
- *
- * The codes are written out rather than read from the Contract at run time: the
- * Contract is data a reader outside this program consults, and a product that
- * read it while running would need it installed beside itself. A test compares
- * this list against the Contract release the analyzer is written against, so a
- * code the Contract fixes arrives here as a failing test.
+ * Every live row of the issue-kind vocabulary, in ascending code order, written out
+ * rather than read at run time, because a product that read the Contract while running
+ * would need it installed beside itself. A test compares this table against the
+ * Contract release the analyzer is written against.
  */
-export const FIXED_SEVERITY_CODES: readonly string[] = ["DS1703", "DS1704"];
+const ROWS: readonly KindRow[] = [
+  row("DS1001", "unused-exported", "deny", "deletable"),
+  row("DS1002", "unused-unexported", "deny", "deletable"),
+  row("DS1003", "unused-member", "deny", "deletable"),
+  row("DS1004", "test-only-use", "deny", "deletable"),
+  row("DS1005", "test-of-dead-code", "deny", "deletable"),
+  row("DS1006", "deprecated-unused", "deny", "deletable"),
+  row("DS1101", "unnecessary-export", "warn", "narrowable"),
+  row("DS1102", "unnecessary-exposure", "warn", "narrowable"),
+  row("DS1103", "unreachable-export", "deny", "deletable"),
+  row("DS1104", "redundant-export-keyword", "warn", "narrowable"),
+  row("DS1201", "unused-interface", "deny", "deletable"),
+  row("DS1203", "uncalled-interface-method", "warn", "manual"),
+  row("DS1204", "unused-satisfaction-assertion", "deny", "deletable"),
+  row("DS1301", "write-only-symbol", "deny", "deletable"),
+  row("DS1302", "unused-enum-member", "deny", "deletable"),
+  row("DS1303", "unused-type-parameter", "deny", "deletable"),
+  row("DS1501", "file-never-built", "deny", "deletable"),
+  row("DS1502", "file-never-imported", "deny", "deletable"),
+  row("DS1601", "unused-dependency", "deny", "manual"),
+  row("DS1605", "unused-module-directive", "warn", "deletable"),
+  row("DS1701", "suppression-without-reason", "deny", "none"),
+  row("DS1702", "unscoped-ignore-entry", "deny", "none"),
+  { ...row("DS1703", "stale-suppression", "deny", "none"), fixed: true },
+  { ...row("DS1704", "unmatched-root", "deny", "none"), fixed: true },
+  row("DS1705", "stale-cross-language-edge", "deny", "none"),
+  row("DS1801", "unused-parameter", "warn", "manual"),
+  row("DS1802", "unused-receiver", "warn", "deletable"),
+  row("DS1803", "unused-result", "warn", "manual"),
+  row("DS1805", "unreachable-statement", "deny", "deletable"),
+  row("DS1807", "dead-store", "deny", "deletable"),
+  row("DS1809", "unreachable-case", "deny", "deletable"),
+];
+
+/** A row at the `certain` ceiling whose severity a configuration may set. */
+function row(
+  code: string,
+  name: string,
+  defaultSeverity: Severity,
+  fixability: Fixability,
+): KindRow {
+  return { code, name, defaultSeverity, maxClass: "certain", fixability, fixed: false };
+}
+
+/** Every live row of the issue-kind vocabulary, by its code, in ascending code order. */
+export const KINDS: ReadonlyMap<string, KindRow> = new Map(ROWS.map((one) => [one.code, one]));
 
 /**
  * The code of every live issue kind, in ascending order. A severity key names one of
  * them or a family prefix whose range holds one; a key naming a retired code, an
  * unassigned code or a range holding no live kind is an unimplemented key, so every
- * severity a configuration sets is one some analyzer reports under. A test compares
- * this list against the Contract release the analyzer is written against.
+ * severity a configuration sets is one some analyzer reports under.
  */
-export const LIVE_CODES: readonly string[] = [
-  "DS1001",
-  "DS1002",
-  "DS1003",
-  "DS1004",
-  "DS1005",
-  "DS1006",
-  "DS1101",
-  "DS1102",
-  "DS1103",
-  "DS1104",
-  "DS1201",
-  "DS1203",
-  "DS1204",
-  "DS1301",
-  "DS1302",
-  "DS1303",
-  "DS1501",
-  "DS1502",
-  "DS1601",
-  "DS1605",
-  "DS1701",
-  "DS1702",
-  "DS1703",
-  "DS1704",
-  "DS1705",
-  "DS1801",
-  "DS1802",
-  "DS1803",
-  "DS1805",
-  "DS1807",
-  "DS1809",
-];
+export const LIVE_CODES: readonly string[] = ROWS.map((one) => one.code);
+
+/** The issue-kind codes whose severity the Contract fixes, in ascending order. */
+export const FIXED_SEVERITY_CODES: readonly string[] = ROWS.filter((one) => one.fixed).map(
+  (one) => one.code,
+);

package/src/resolve.ts

@@ -35,7 +35,7 @@ import {
 const FLAGS_LABEL = "the command-line flags";
 
 /** The length of a severity key naming a whole family: the prefix and two digits. */
-const FAMILY_KEY_LENGTH = 4;
+export const FAMILY_KEY_LENGTH = 4;
 
 const SEVERITY_KEY = /^DS[0-9]{2}([0-9]{2})?$/u;
 const EXEMPTION_CLASS = /^[a-z][a-z0-9-]*$/u;

package/src/stores.ts

@@ -0,0 +1,77 @@
+/**
+ * What a run knows about the stores into its declarations and the reads of them, which
+ * a sweep does not keep: a sweep asks whether anything names a declaration, and a store
+ * names it as surely as a read does.
+ */
+
+import {
+  isGetAccessorDeclaration,
+  isSetAccessorDeclaration,
+  type Node,
+} from "@typescript/native/unstable/ast";
+import { nodeKey, type Inventory } from "./inventory.ts";
+import type { Reference } from "./references.ts";
+import type { ProjectView } from "./session.ts";
+import type { Exemption, Mode } from "./sweep.ts";
+
+/** One run's stores and reads, over every configuration. */
+export interface Stores {
+  /**
+   * Every reference the run's mode counts, each configuration's in the run's order, so
+   * one written at a position several configurations compile appears once per
+   * configuration. A production mode counts none a test file made.
+   */
+  readonly references: readonly Reference[];
+  /**
+   * The class members declared by a getter or a setter. A store into one runs the
+   * setter, which is code rather than state.
+   */
+  readonly accessors: ReadonlySet<string>;
+  /**
+   * The declarations an exemption record names, whether or not the record held back
+   * anything dead: a mechanism the analysis cannot see uses each of them.
+   */
+  readonly exempt: ReadonlySet<string>;
+}
+
+/** What one configuration contributes to the run's stores. */
+export interface ConfigurationStores {
+  readonly references: readonly Reference[];
+  readonly accessors: readonly string[];
+}
+
+/** The class members one project's own files declare by a getter or a setter. */
+export function accessorsOf<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+): readonly string[] {
+  const found: string[] = [];
+  for (const file of project.ownSourceFiles()) {
+    const visit = (node: Node): void => {
+      if (isGetAccessorDeclaration(node) || isSetAccessorDeclaration(node)) {
+        const id = held.declarations.get(nodeKey(file, node));
+        if (id !== undefined) {
+          found.push(id);
+        }
+      }
+      node.forEachChild(visit);
+    };
+    file.forEachChild(visit);
+  }
+  return found;
+}
+
+/** The run's stores, from what each configuration contributed, the records and the mode. */
+export function storesOf(
+  per: readonly ConfigurationStores[],
+  exempt: readonly Exemption[],
+  mode: Mode,
+): Stores {
+  return {
+    references: per.flatMap((one) =>
+      one.references.filter((reference) => !mode.production || !reference.test),
+    ),
+    accessors: new Set(per.flatMap((one) => one.accessors)),
+    exempt: new Set(exempt.map((record) => record.id)),
+  };
+}