@cplieger/deadset-ts 3.5.0 → 3.6.0

package/src/findings/visibility-narrowing.ts

@@ -1,4 +1,325 @@
-import type { Emitter } from "./emitter.ts";
+import type { Finding } from "../finding.ts";
+import { OUTSIDE, type Graph } from "../graph.ts";
+import type { InventorySymbol, SymbolKind } from "../inventory.ts";
+import type { MatrixCandidate } from "../matrix.ts";
+import type { RootKind } from "../roots.ts";
+import type { PendingFinding } from "./boundary.ts";
+import type { Emitter, EmitterInput } from "./emitter.ts";
+import { writeOnlyDeclarations } from "./reads-and-writes.ts";
 
-/** The findings of the visibility-narrowing family, `DS1100` to `DS1199`. */
-export const visibilityNarrowing: Emitter = () => [];
+const UNNECESSARY_EXPORT = "DS1101";
+const UNREACHABLE_EXPORT = "DS1103";
+const REDUNDANT_EXPORT_KEYWORD = "DS1104";
+
+/** How far the references to one declaration reach, from the narrowest. */
+type Reach = "file" | "package" | "outside";
+
+/**
+ * The root kinds by which a consumer importing the package reaches a declaration. A
+ * declaration or a file rooted by any other kind is entered by something that names it
+ * from outside the reference graph: a runtime, a tool, a framework or the configuration.
+ */
+const PUBLISHING: ReadonlySet<RootKind> = new Set<RootKind>(["manifest-entry", "published-api"]);
+
+/** The reader's word for each kind of declaration this family reports. */
+const WORDS: Partial<Readonly<Record<SymbolKind, string>>> = {
+  function: "function",
+  class: "class",
+  interface: "interface",
+  type: "type alias",
+  enum: "enum",
+  namespace: "namespace",
+  variable: "variable",
+  "export-alias": "re-export",
+};
+
+/** What the family found: the findings it reports, and those a declared edge holds pending. */
+export interface Narrowings {
+  readonly findings: readonly Finding[];
+  /** Ordered by edge, then by side. */
+  readonly pending: readonly PendingFinding[];
+}
+
+/** Per declaration of the run, the facts both rules read. */
+interface Facts {
+  readonly graph: Graph;
+  /** The position of the file that holds each declaration. */
+  readonly fileOf: readonly number[];
+  /** The root kinds naming each declaration. */
+  readonly rootedBy: readonly ReadonlySet<RootKind>[];
+  /** Per file, whether a manifest export reaches a declaration it holds. */
+  readonly published: readonly boolean[];
+  /** Per declaration, how many references name it, and how far they reach. */
+  readonly named: readonly number[];
+  readonly reach: readonly Reach[];
+}
+
+function publishes(kinds: ReadonlySet<RootKind> | undefined): boolean {
+  return [...(kinds ?? [])].some((kind) => PUBLISHING.has(kind));
+}
+
+function entersByName(kinds: ReadonlySet<RootKind> | undefined): boolean {
+  return [...(kinds ?? [])].some((kind) => !PUBLISHING.has(kind));
+}
+
+/**
+ * Folds the run's references into the reach of each declaration.
+ *
+ * A reference reaches the file that holds the declaration that makes it. A reference
+ * from a declaration the inventory does not hold is made by a consumer, and one from a
+ * re-export a manifest export reaches stands for every consumer importing the name it
+ * publishes; either reaches outside the package.
+ */
+function factsOf(graph: Graph): Facts {
+  const { symbols, parent } = graph;
+  const fileOf = symbols.map((_symbol, at) => {
+    let file = at;
+    while (file !== OUTSIDE && symbols[file]?.kind !== "file") {
+      file = parent[file] ?? OUTSIDE;
+    }
+    return file;
+  });
+  const rootedBy = symbols.map(() => new Set<RootKind>());
+  for (const root of graph.rooted) {
+    rootedBy[root.at]?.add(root.kind);
+  }
+  const published = symbols.map(() => false);
+  symbols.forEach((_symbol, at) => {
+    const file = fileOf[at] ?? OUTSIDE;
+    if (file !== OUTSIDE && publishes(rootedBy[at])) {
+      published[file] = true;
+    }
+  });
+
+  const order: readonly Reach[] = ["file", "package", "outside"];
+  const wider = (a: Reach, b: Reach): Reach => (order.indexOf(a) >= order.indexOf(b) ? a : b);
+  const inGraph = symbols.map(() => 0);
+  const reach = symbols.map((): Reach => "file");
+  graph.out.forEach((edges, from) => {
+    const republished = symbols[from]?.kind === "export-alias" && publishes(rootedBy[from]);
+    for (const edge of edges) {
+      inGraph[edge.to] = (inGraph[edge.to] ?? 0) + 1;
+      const scope: Reach = republished
+        ? "outside"
+        : fileOf[from] === fileOf[edge.to]
+          ? "file"
+          : "package";
+      reach[edge.to] = wider(reach[edge.to] ?? "file", scope);
+    }
+  });
+  const named = graph.made.map((counts) => counts.production + counts.test);
+  named.forEach((count, at) => {
+    if (count > (inGraph[at] ?? 0)) {
+      reach[at] = "outside";
+    }
+  });
+  return { graph, fileOf, rootedBy, published, named, reach };
+}
+
+/** Whether one declaration is a declaration its file's export table names. */
+function topLevelExport(facts: Facts, at: number, symbol: InventorySymbol): boolean {
+  const parent = facts.graph.parent[at] ?? OUTSIDE;
+  return symbol.exported && parent !== OUTSIDE && facts.graph.symbols[parent]?.kind === "file";
+}
+
+function wordOf(symbol: InventorySymbol): string {
+  return WORDS[symbol.kind] ?? symbol.kind;
+}
+
+/** A finding of this family, with the visibility a narrowing would give its subject. */
+interface NarrowingFinding extends Finding {
+  readonly details: { readonly narrowerVisibility?: "file" | "package" };
+}
+
+/** The visibility each narrowing code names, which only the narrowing codes carry. */
+const NARROWER: Readonly<Record<string, "file" | "package">> = {
+  [REDUNDANT_EXPORT_KEYWORD]: "file",
+  [UNNECESSARY_EXPORT]: "package",
+};
+
+function findingOf(symbol: InventorySymbol, code: string, message: string): NarrowingFinding {
+  const { path, line, column } = symbol.position;
+  const narrower = Object.hasOwn(NARROWER, code) ? NARROWER[code] : undefined;
+  const endLine = Math.max(line, symbol.endLine);
+  return {
+    code,
+    position: { path, line, column, endLine },
+    symbol: {
+      ref: symbol.ref,
+      kind: symbol.kind,
+      name: symbol.name,
+      sizeLines: endLine - line + 1,
+    },
+    message,
+    details: narrower === undefined ? {} : { narrowerVisibility: narrower },
+  };
+}
+
+/**
+ * The narrowing finding about one live declaration, if one holds: an export of a file,
+ * no re-export and none the write-only kind reports, that a reference names and nothing
+ * enters by name. Every reference inside its own file makes it a redundant export
+ * keyword, where no manifest export reaches the file or the world is closed; references
+ * from other files of the package alone make a published one unnecessary when closed.
+ */
+function narrowing(
+  facts: Facts,
+  at: number,
+  symbol: InventorySymbol,
+  world: { readonly closed: boolean; readonly writeOnly: ReadonlySet<string> },
+): Finding | undefined {
+  const { closed } = world;
+  const file = facts.fileOf[at] ?? OUTSIDE;
+  if (
+    !topLevelExport(facts, at, symbol) ||
+    world.writeOnly.has(symbol.ref) ||
+    symbol.kind === "export-alias" ||
+    entersByName(facts.rootedBy[at]) ||
+    entersByName(facts.rootedBy[file]) ||
+    (facts.named[at] ?? 0) === 0
+  ) {
+    return undefined;
+  }
+  const word = wordOf(symbol);
+  switch (facts.reach[at]) {
+    case "file":
+      if (facts.published[file] === true && !closed) {
+        return undefined;
+      }
+      return findingOf(
+        symbol,
+        REDUNDANT_EXPORT_KEYWORD,
+        `exported ${word} is referenced only inside the file that declares it`,
+      );
+    case "package":
+      if (!closed || !publishes(facts.rootedBy[at])) {
+        return undefined;
+      }
+      return findingOf(
+        symbol,
+        UNNECESSARY_EXPORT,
+        `exported ${word} is referenced only inside the package that declares it`,
+      );
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * The unreachable-export finding about one dead declaration, if one holds: an unused
+ * export no code outside the target can import, because the manifest declares
+ * `exports` and no root reaches it. Each arm yields to a more specific kind, so one
+ * declaration is reported once: a test whose every subject is dead, an interface, a
+ * declaration only a test file references, and a deprecated one.
+ */
+function unreachable(
+  facts: Facts,
+  at: number,
+  symbol: InventorySymbol,
+  candidate: MatrixCandidate,
+  input: EmitterInput,
+): Finding | undefined {
+  if (
+    !input.boundary.encapsulated ||
+    !topLevelExport(facts, at, symbol) ||
+    (facts.rootedBy[at]?.size ?? 0) > 0 ||
+    candidate.testOfDeadCode ||
+    symbol.kind === "interface" ||
+    (candidate.productionRefs === 0 && candidate.testRefs > 0) ||
+    (candidate.productionRefs === 0 && input.deprecated.has(symbol.id))
+  ) {
+    return undefined;
+  }
+  const found =
+    candidate.relation === "reachability"
+      ? "is referenced only from declarations that are themselves dead"
+      : "has no reference in the target";
+  return findingOf(
+    symbol,
+    UNREACHABLE_EXPORT,
+    `exported ${wordOf(symbol)} ${found}, and nothing outside can import the file that declares it`,
+  );
+}
+
+/** Two strings ordered bytewise. */
+function compare(a: string, b: string): number {
+  if (a === b) {
+    return 0;
+  }
+  return a < b ? -1 : 1;
+}
+
+/**
+ * The visibility-narrowing family over one run: `DS1101`, `DS1103` and `DS1104`.
+ *
+ * A finding about a symbol a declared cross-language edge names is pending instead of
+ * reported, once per side naming it: the edge counts as a reference from outside the
+ * file and the package, and whether it is a use is decided on the side in the other
+ * language.
+ */
+export function narrowings(input: EmitterInput): Narrowings {
+  const { boundary } = input;
+  const facts = factsOf(input.swept.matrix.union);
+  const { declared, loaded } = boundary.consumers;
+  const closed = input.config.consumersComplete && declared.every((id) => loaded.includes(id));
+  const world = { closed, writeOnly: writeOnlyDeclarations(input) };
+  const candidates = new Map(
+    input.swept.sweep.candidates.map((candidate) => [candidate.id, candidate]),
+  );
+
+  const findings: Finding[] = [];
+  const pending: PendingFinding[] = [];
+  facts.graph.symbols.forEach((symbol, at) => {
+    const candidate = candidates.get(symbol.id);
+    const found =
+      candidate === undefined
+        ? narrowing(facts, at, symbol, world)
+        : unreachable(facts, at, symbol, candidate, input);
+    if (found === undefined) {
+      return;
+    }
+    const named = boundary.edges.filter((side) => side.symbol === symbol.ref);
+    if (named.length === 0) {
+      findings.push(found);
+      return;
+    }
+    for (const side of named) {
+      pending.push({ ...side, finding: found });
+    }
+  });
+  pending.sort((a, b) => compare(a.edge, b.edge) || compare(a.side, b.side));
+  return { findings, pending };
+}
+
+/**
+ * The declarations the unreachable-export kind reports, whether or not a declared edge
+ * holds the finding pending: the unused-declaration kinds yield each to it.
+ */
+export function unreachableExports(input: EmitterInput): ReadonlySet<string> {
+  const facts = factsOf(input.swept.matrix.union);
+  const found = new Set<string>();
+  for (const candidate of input.swept.sweep.candidates) {
+    const at = facts.graph.at(candidate.id);
+    const symbol = facts.graph.symbols[at];
+    if (symbol !== undefined && unreachable(facts, at, symbol, candidate, input) !== undefined) {
+      found.add(symbol.id);
+    }
+  }
+  return found;
+}
+
+/**
+ * The findings of the visibility-narrowing family, `DS1100` to `DS1199`. A finding a
+ * declared edge holds pending belongs in that edge's evaluation, which this analyzer
+ * does not publish yet, so a run that holds one is refused rather than reported
+ * without it.
+ */
+export const visibilityNarrowing: Emitter = (input) => {
+  const { findings, pending } = narrowings(input);
+  if (pending.length > 0) {
+    throw new Error(
+      `${String(pending.length)} finding(s) a declared edge holds pending, and no edge evaluation is published`,
+    );
+  }
+  return findings;
+};

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/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;