@cplieger/deadset-ts 8.0.0-dev.17 → 8.0.0-dev.18

package/src/sweep.ts

@@ -1,384 +0,0 @@
-/**
- * Which declarations of one graph are dead, and under which liveness relation.
- * Reference counting holds a declaration live when any declaration references it,
- * whatever that one's own liveness, or when it is a root of a kind that names a caller;
- * reachability holds it live when a path of references reaches it from a root. So a
- * declaration only unreachable ones reference is live under the first, dead under the second.
- */
-
-import type { TSExemptionClass } from "./exempt-classes.ts";
-import { namesACaller, OUTSIDE, type Counts, type Edge, type Graph } from "./graph.ts";
-import { edgeWithheldBy } from "./tests/file-class.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. */
-export type Relation = "reference-counting" | "reachability";
-
-/** One declaration an exemption class holds back, and the evidence it was found by. */
-export interface Exemption {
-  /** The identifier of the declaration held back. */
-  readonly id: string;
-  readonly class: TSExemptionClass;
-  /** One clause naming the relation, then the thing it relates to: `passed to JSON.stringify`. */
-  readonly detail: string;
-  /** Where the evidence is written. */
-  readonly site: Position;
-  /**
-   * The component file, below the target root, whose markup holds the evidence. The
-   * record holds only while that file is live.
-   */
-  readonly whileLive?: string;
-  /**
-   * The interface methods the retained member implements, and whether its body is empty.
-   * 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. */
-export interface Implementing {
-  /** The declarations of the interface's methods the member answers, by identifier. */
-  readonly methods: readonly string[];
-  readonly empty: boolean;
-}
-
-/**
- * The run's reference mode, decided once by the composition and read by every stage
- * that counts references.
- */
-export interface Mode {
-  /**
-   * Counts no reference a test file made, under either relation. Every reference a root
-   * in a test file makes is such a reference, so nothing only a test reaches is live.
-   */
-  readonly production: boolean;
-  /**
-   * Classes a reference a loaded consumer's test file made as a production one rather than a
-   * test one, `analysis.consumer_tests` at `production`: a classification, not a filter, so it
-   * decides the split a candidate reports as well as what a production sweep counts.
-   */
-  readonly consumerTestsProduction?: boolean;
-}
-
-/** The references to one declaration the mode counts: under `production` none test code made but those it classes as production. */
-function countedRefs(made: Counts | undefined, mode: Mode): number {
-  if (made === undefined) {
-    return 0;
-  }
-  if (!mode.production) {
-    return made.production + made.test;
-  }
-  return made.production + (mode.consumerTestsProduction === true ? made.consumerTest : 0);
-}
-
-/** The references to one declaration, split as the mode classes them, whatever it counts. */
-export function splitRefs(
-  made: Counts | undefined,
-  mode: Mode,
-): { readonly production: number; readonly test: number } {
-  const moved = mode.consumerTestsProduction === true ? (made?.consumerTest ?? 0) : 0;
-  return { production: (made?.production ?? 0) + moved, test: (made?.test ?? 0) - moved };
-}
-
-/** What one sweep runs over besides the graph. */
-export interface SweepInput {
-  /**
-   * The declarations a matched suppression names. A mark holds its declaration live
-   * under both relations and seeds reachability through every reference it makes, so
-   * nothing only a marked declaration references is dead.
-   */
-  readonly marked: readonly string[];
-  /**
-   * The exemptions the run computed. An exempt declaration is never a candidate, and it
-   * seeds reachability as a mark does, so nothing it references is dead; it is live
-   * under reference counting only where something references it. Absent, the sweep
-   * holds nothing back.
-   */
-  readonly exempt?: readonly Exemption[];
-  /**
-   * The declarations a question the checker did not answer could have kept live. Each
-   * is held as an exempt declaration is. Absent, the sweep holds nothing back for one.
-   */
-  readonly unanswered?: readonly string[];
-  readonly mode: Mode;
-}
-
-/** One dead declaration, the relation that found it, and the counts a kind reads. */
-export interface Candidate {
-  readonly id: string;
-  /** The references a production file made to the declaration, whatever the mode counts. */
-  readonly productionRefs: number;
-  /** The references a test file made to it. */
-  readonly testRefs: number;
-  /**
-   * Reference counting where the mode counts no reference to the declaration, and
-   * reachability otherwise, so a declaration dead under both carries the stronger claim.
-   */
-  readonly relation: Relation;
-  /**
-   * Whether the test-of-dead-code rule admitted the declaration: a test declaration whose
-   * set of referenced production declarations is non-empty and wholly dead.
-   */
-  readonly testOfDeadCode: boolean;
-}
-
-/** One graph's answer: what each relation holds live, and what is dead. */
-export interface Liveness {
-  /**
-   * Per declaration, the relations that hold it live, reference counting first. A
-   * declaration neither holds live has no entry.
-   */
-  readonly liveUnder: ReadonlyMap<string, readonly Relation[]>;
-  /** The dead declarations, in the order the inventory holds them. */
-  readonly candidates: readonly Candidate[];
-}
-
-/**
- * Answers which declarations of one graph are dead under the input's mode.
- *
- * The order is the order the answers depend on: the callers and the marks are live
- * before either relation runs, the candidate set is every judged declaration at least
- * one relation does not hold live and no exemption holds back, and the tests of dead
- * code join it.
- */
-export function sweep(graph: Graph, input: SweepInput): Liveness {
-  const marked = flagged(graph, input.marked);
-  const exempt = flagged(graph, [
-    ...(input.exempt ?? []).map((record) => record.id),
-    ...(input.unanswered ?? []),
-  ]);
-  const held = marked.map((mark, at) => mark || exempt[at] === true);
-  // Every root, every mark and every exemption seeds reachability. A root of a kind that
-  // names a caller, and a mark, are live under reference counting as well; a root that
-  // only supposes a caller is not, and neither is an exemption.
-  const called = graph.symbols.map(() => false);
-  for (const root of graph.rooted) {
-    if (namesACaller(root.kind)) {
-      called[root.at] = true;
-    }
-  }
-
-  const counted = (at: number): number => countedRefs(graph.made[at], input.mode);
-  const reached = reachable(graph, held, input.mode);
-  const liveUnder = graph.symbols.map((_symbol, at): readonly Relation[] => {
-    const relations: Relation[] = [];
-    if (marked[at] === true || called[at] === true || counted(at) > 0) {
-      relations.push("reference-counting");
-    }
-    if (reached[at] === true) {
-      relations.push("reachability");
-    }
-    return relations;
-  });
-
-  const dead = graph.symbols.map(
-    (_symbol, at) =>
-      graph.subject[at] === true && exempt[at] !== true && (liveUnder[at]?.length ?? 0) < 2,
-  );
-  const testOfDeadCode = admitTestsOfDeadCode(graph, dead, held);
-
-  const candidates: Candidate[] = [];
-  const live = new Map<string, readonly Relation[]>();
-  graph.symbols.forEach((symbol, at) => {
-    const relations = liveUnder[at] ?? [];
-    if (relations.length > 0) {
-      live.set(symbol.id, relations);
-    }
-    if (dead[at] !== true) {
-      return;
-    }
-    const split = splitRefs(graph.made[at], input.mode);
-    candidates.push({
-      id: symbol.id,
-      productionRefs: split.production,
-      testRefs: split.test,
-      relation: counted(at) === 0 ? "reference-counting" : "reachability",
-      testOfDeadCode: testOfDeadCode[at] === true,
-    });
-  });
-
-  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, 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[],
-  namespaces = true,
-): readonly boolean[] {
-  const tests = graph.symbols.flatMap((symbol, at) => {
-    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 },
-    namespaces,
-  );
-}
-
-/**
- * The references a loaded consumer or an unheld file makes that the mode counts. A
- * production mode counts no test reference, but a loaded consumer's where the mode classes
- * a consumer's tests as production.
- */
-function callsOf(graph: Graph, mode: Mode): readonly Edge[] {
-  return graph.consumed.filter((edge) => !edgeWithheldBy(mode, edge));
-}
-
-/** Per declaration of the graph, whether one of the identifiers names it. */
-function flagged(graph: Graph, ids: readonly string[]): boolean[] {
-  const flags = graph.symbols.map(() => false);
-  for (const id of ids) {
-    const at = graph.at(id);
-    if (at !== OUTSIDE) {
-      flags[at] = true;
-    }
-  }
-  return flags;
-}
-
-/**
- * Per declaration, whether a seed reaches it. The two seeds reach through different
- * reference sets: a held declaration, marked or exempt, is live by a mechanism the
- * analysis cannot see, so no mode withholds a reference it makes, a test declaration's
- * 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,
-  namespaces = true,
-): readonly boolean[] {
-  const reached = graph.symbols.map(() => false);
-  const expanded = graph.symbols.map(() => false);
-  const queue: number[] = [];
-
-  // Reaching a file reaches its top level: the references written outside every
-  // declaration it holds. A reference that reads a file reads the module's namespace,
-  // which reaches what the module exports as well. An evaluation runs the top level
-  // and reads no export, and a root does not expand either: a file a runtime runs
-  // without reading its exports is a root by itself.
-  const enter = (at: number, expands: boolean): void => {
-    if (!reached[at]) {
-      reached[at] = true;
-      queue.push(at);
-    }
-    if (!expands || expanded[at] === true) {
-      return;
-    }
-    expanded[at] = true;
-    for (const exported of graph.exportsOf[at] ?? []) {
-      enter(exported, false);
-    }
-  };
-  const walk = (holding: boolean): void => {
-    for (let at = queue.pop(); at !== undefined; at = queue.pop()) {
-      for (const edge of graph.out[at] ?? []) {
-        if (!holding && edgeWithheldBy(mode, edge)) {
-          continue;
-        }
-        enter(edge.to, namespaces && !edge.evaluation);
-      }
-    }
-  };
-
-  held.forEach((hold, at) => {
-    if (hold) {
-      enter(at, false);
-    }
-  });
-  walk(true);
-  for (const root of graph.rooted) {
-    enter(root.at, false);
-  }
-  // 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, namespaces && !edge.evaluation);
-  }
-  walk(false);
-  return reached;
-}
-
-/**
- * Admits every test declaration whose set of referenced production declarations is
- * 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,
-  dead: boolean[],
-  held: readonly boolean[],
-): readonly boolean[] {
-  const testCode = (at: number): boolean => graph.test[at] === true || graph.support[at] === true;
-  const judged = graph.symbols.map((_symbol, at) => {
-    let targets = 0;
-    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 ||
-          graph.ambient[edge.to] === true
-        ) {
-          continue;
-        }
-        targets += 1;
-        if (dead[edge.to] !== true) {
-          live += 1;
-        }
-      }
-    }
-    return { targets, live };
-  });
-  const shared = new Set<number>();
-  judged.forEach(({ live }, at) => {
-    if (live > 0) {
-      for (const edge of graph.out[at] ?? []) {
-        if (graph.support[edge.to] === true) {
-          shared.add(edge.to);
-        }
-      }
-    }
-  });
-  const admitted = graph.symbols.map(() => false);
-  judged.forEach(({ targets, live }, at) => {
-    const sharing = (graph.out[at] ?? []).some((edge) => shared.has(edge.to) && edge.to !== at);
-    if (targets > 0 && live === 0 && !sharing) {
-      dead[at] = true;
-      admitted[at] = true;
-    }
-  });
-  return admitted;
-}