@cplieger/deadset-ts 2.3.0 → 3.1.0

package/src/graph.ts

@@ -0,0 +1,187 @@
+/**
+ * One project's declarations, the references between them and the roots that seed
+ * reachability, indexed for the sweep. The graph reads no file and asks the compiler
+ * nothing, so a sweep over it is a function of the values it was built from, and the
+ * inventory's order is the order every set a sweep answers reads in.
+ */
+
+import type { InventorySymbol, SymbolKind } from "./inventory.ts";
+import type { Reference } from "./references.ts";
+import type { Root, RootKind } from "./roots.ts";
+
+/** The position of a declaration the inventory does not hold. */
+export const OUTSIDE = -1;
+
+/**
+ * Whether the sweep judges a declaration of each kind. A file is not judged by either
+ * relation: whether a file is built and whether anything imports it are the subjects of
+ * the file kinds, which read the program rather than ask whether anything references the
+ * file. The Contract's finding schema names the kinds that carry no liveness relation,
+ * and a test holds this table to that list.
+ */
+const SWEPT: Readonly<Record<SymbolKind, boolean>> = {
+  file: false,
+  function: true,
+  class: true,
+  interface: true,
+  type: true,
+  enum: true,
+  namespace: true,
+  variable: true,
+  "export-alias": true,
+  method: true,
+  "class-member": true,
+  "interface-method": true,
+  "type-member": true,
+  "enum-member": true,
+  "type-parameter": true,
+};
+
+/**
+ * Whether a root of each kind names a caller, which holds it live under both relations: a
+ * tool reads the configuration it loads, a runtime runs a test file, a setup file and a
+ * worker, and a configured root asserts a caller. The other kinds only suppose a consumer
+ * that imports what a manifest entry, a binary or an entry file exports, or names a
+ * library's published API, so such a root is live under reachability alone.
+ */
+const NAMES_A_CALLER: Readonly<Record<RootKind, boolean>> = {
+  "entry-file": false,
+  "manifest-entry": false,
+  "manifest-binary": false,
+  "published-api": false,
+  configured: true,
+  pattern: true,
+  "test-runner": true,
+  "lint-configuration": true,
+  "mutation-testing": true,
+  "browser-tests": true,
+  worker: true,
+};
+
+/** Whether the sweep judges a declaration of one kind. */
+export function swept(kind: SymbolKind): boolean {
+  return SWEPT[kind];
+}
+
+/** Whether a root of one kind names a caller rather than supposing one. */
+export function namesACaller(kind: RootKind): boolean {
+  return NAMES_A_CALLER[kind];
+}
+
+/** One reference as the sweep reads it: the declaration named, and whether a test file made it. */
+export interface Edge {
+  readonly to: number;
+  readonly test: boolean;
+  /**
+   * Whether the reference evaluates the module whose file it names, which reaches the
+   * module's top level and none of what it exports.
+   */
+  readonly evaluation: boolean;
+}
+
+/** How many references one declaration carries, split by the classification of the file that made each. */
+export interface Counts {
+  readonly production: number;
+  readonly test: number;
+}
+
+/** One root the inventory holds, at the position of the declaration it names. */
+export interface Rooted {
+  readonly at: number;
+  readonly kind: RootKind;
+}
+
+/** The index the sweep and the component pass read. */
+export interface Graph {
+  /** The declarations, in the order the inventory returns them. */
+  readonly symbols: readonly InventorySymbol[];
+  /** Per declaration, the references it makes to declarations the inventory holds. */
+  readonly out: readonly (readonly Edge[])[];
+  /** Per declaration, the references made to it, whoever made them. */
+  readonly made: readonly Counts[];
+  /** Per declaration, the position of its container, or {@link OUTSIDE} for a file. */
+  readonly parent: readonly number[];
+  /** Per declaration, whether a test file holds it. */
+  readonly test: readonly boolean[];
+  /** Per declaration, whether the sweep judges its liveness. */
+  readonly subject: readonly boolean[];
+  /**
+   * Per declaration, the declarations its export table names where it is a file, and
+   * nothing for any other declaration. A reference that reads a file reads the module's
+   * namespace, which reaches everything the module exports.
+   */
+  readonly exportsOf: readonly (readonly number[])[];
+  /** Every root naming a declaration the inventory holds, in the order the root set gives them. */
+  readonly rooted: readonly Rooted[];
+  /** The position of the declaration one identifier names, or {@link OUTSIDE}. */
+  at(id: string): number;
+}
+
+/**
+ * Indexes one project's inventory, references and roots. `testFiles` are the paths the
+ * reference pass classified as test files, so a declaration one holds is a test
+ * declaration. A reference to a declaration the inventory does not hold is dropped; one
+ * from such a declaration still counts toward its target, because reference counting
+ * asks whether any declaration names the target. A root naming nothing is dropped.
+ */
+export function graphOf(
+  symbols: readonly InventorySymbol[],
+  references: readonly Reference[],
+  roots: readonly Root[],
+  testFiles: readonly string[],
+): Graph {
+  const index = new Map(symbols.map((symbol, at) => [symbol.id, at]));
+  const at = (id: string): number => index.get(id) ?? OUTSIDE;
+  const tests = new Set(testFiles);
+
+  const out: Edge[][] = symbols.map(() => []);
+  const made = symbols.map(() => ({ production: 0, test: 0 }));
+  for (const reference of references) {
+    const to = at(reference.to);
+    if (to === OUTSIDE) {
+      continue;
+    }
+    const counts = made[to];
+    if (counts !== undefined) {
+      if (reference.test) {
+        counts.test += 1;
+      } else {
+        counts.production += 1;
+      }
+    }
+    out[at(reference.from)]?.push({
+      to,
+      test: reference.test,
+      evaluation: reference.use === "evaluation",
+    });
+  }
+
+  const parent = symbols.map((symbol) => at(symbol.parent));
+  const exportsOf: number[][] = symbols.map(() => []);
+  symbols.forEach((symbol, position) => {
+    const container = parent[position] ?? OUTSIDE;
+    if (symbol.exported && symbols[container]?.kind === "file") {
+      exportsOf[container]?.push(position);
+    }
+  });
+
+  const rooted: Rooted[] = [];
+  for (const root of roots) {
+    const position = at(root.id);
+    if (position !== OUTSIDE) {
+      rooted.push({ at: position, kind: root.kind });
+    }
+  }
+
+  return {
+    symbols,
+    out,
+    made,
+    parent,
+    test: symbols.map((symbol) => tests.has(symbol.position.path)),
+    subject: symbols.map((symbol) => swept(symbol.kind)),
+    exportsOf,
+    rooted,
+    at,
+  };
+}

package/src/index.ts

@@ -1,26 +1,6 @@
 export { run, SETTING_OPTIONS, type Writer } from "./run.ts";
 export type { DirectoryEntry, Host, PathKind } from "./host.ts";
 export { DECLINED_CONVENTIONS, type DeclinedConvention } from "./entry-point-gaps.ts";
-export {
-  inventory,
-  nodeKey,
-  type Inventory,
-  type InventoryCost,
-  type InventorySymbol,
-  type SymbolKind,
-  type Visibility,
-} from "./inventory.ts";
-export {
-  DEFAULT_BATCH_CAP,
-  references,
-  type Reference,
-  type ReferenceCost,
-  type ReferenceOptions,
-  type References,
-  type Resolution,
-  type TestFileRule,
-  type Use,
-} from "./references.ts";
 export {
   byPosition,
   positionKey,

package/src/matrix.ts

@@ -0,0 +1,212 @@
+/**
+ * One run's projects as one matrix: every declaration any project holds, keyed by its
+ * position and carrying the configurations that hold it, swept once per configuration
+ * and intersected, with the dead components computed once over every configuration.
+ */
+
+import { componentsOf, type Component } from "./components.ts";
+import { graphOf, type Graph } from "./graph.ts";
+import type { InventorySymbol } from "./inventory.ts";
+import { byPosition } from "./position.ts";
+import type { Reference } from "./references.ts";
+import type { Root } from "./roots.ts";
+import { sweep, type Candidate, type Liveness, type Relation, type SweepInput } from "./sweep.ts";
+
+/** What the passes answered for one configuration of the run. */
+export interface Configured {
+  /** The name discovery gives the configuration's project. */
+  readonly configuration: string;
+  readonly symbols: readonly InventorySymbol[];
+  readonly references: readonly Reference[];
+  readonly roots: readonly Root[];
+  /** The paths the reference pass classified as test files. */
+  readonly testFiles: readonly string[];
+}
+
+/** The run's configurations, indexed for the sweep. */
+export interface Matrix {
+  /** The configurations, in the run's order. */
+  readonly configurations: readonly string[];
+  /** Per configuration, in the same order, the graph of what that configuration holds. */
+  readonly graphs: readonly Graph[];
+  /**
+   * The graph over every configuration at once: every declaration any configuration
+   * holds, once per position and in site order, and every reference any configuration
+   * makes, a reference several configurations make at one position counted once.
+   */
+  readonly union: Graph;
+  /**
+   * Per declaration of {@link Matrix.union}, at its position there, the configurations
+   * whose project holds it, in the run's order.
+   */
+  readonly heldIn: readonly (readonly string[])[];
+}
+
+/** One declaration dead in every configuration that holds it. */
+export interface MatrixCandidate extends Candidate {
+  /** The configurations the declaration is dead in, which are every one that holds it. */
+  readonly configurations: readonly string[];
+}
+
+/** One run's sweep. */
+export interface SweepResult {
+  /**
+   * Per declaration, the relations that hold it live in at least one configuration,
+   * reference counting first. A declaration no relation holds live anywhere has no entry.
+   */
+  readonly liveUnder: ReadonlyMap<string, readonly Relation[]>;
+  /** The declarations dead in every configuration that holds them, in site order. */
+  readonly candidates: readonly MatrixCandidate[];
+  /** The dead components, each before every component it reaches, each identifier once per run. */
+  readonly components: readonly Component[];
+}
+
+/** Two strings ordered bytewise. */
+function compare(a: string, b: string): number {
+  if (a === b) {
+    return 0;
+  }
+  return a < b ? -1 : 1;
+}
+
+/** What makes one reference one reference, whichever configuration made it. */
+function referenceKey(reference: Reference): string {
+  const { path, line, column } = reference.position;
+  return [reference.from, reference.to, path, String(line), String(column), reference.use].join(
+    "\u0000",
+  );
+}
+
+/**
+ * Indexes what the passes answered for each configuration of one run, in the run's order.
+ *
+ * A declaration is keyed across configurations by its identifier, which is its rendered
+ * position and so is the same in every configuration that compiles its file; the fields
+ * of the first configuration that holds it are the ones kept. A declaration one
+ * configuration alone holds is in the union with that one configuration, so it is
+ * judged where it exists rather than skipped.
+ *
+ * One reference written at one position of a file several configurations compile is seen
+ * once per configuration and is one reference, so the union holds it once; two references
+ * one configuration makes at one position are two.
+ */
+export function matrixOf(per: readonly Configured[]): Matrix {
+  const symbols: InventorySymbol[] = [];
+  const holders = new Map<string, string[]>();
+  const references: Reference[] = [];
+  const firstSeen = new Map<string, number>();
+  per.forEach((one, index) => {
+    for (const symbol of one.symbols) {
+      const held = holders.get(symbol.id);
+      if (held === undefined) {
+        holders.set(symbol.id, [one.configuration]);
+        symbols.push(symbol);
+      } else if (!held.includes(one.configuration)) {
+        held.push(one.configuration);
+      }
+    }
+    for (const reference of one.references) {
+      const key = referenceKey(reference);
+      const seen = firstSeen.get(key);
+      if (seen === undefined) {
+        firstSeen.set(key, index);
+      } else if (seen !== index) {
+        continue;
+      }
+      references.push(reference);
+    }
+  });
+  symbols.sort((a, b) => byPosition(a.position, b.position) || compare(a.ref, b.ref));
+
+  return {
+    configurations: per.map((one) => one.configuration),
+    graphs: per.map((one) => graphOf(one.symbols, one.references, one.roots, one.testFiles)),
+    union: graphOf(
+      symbols,
+      references,
+      per.flatMap((one) => one.roots),
+      [...new Set(per.flatMap((one) => one.testFiles))],
+    ),
+    heldIn: symbols.map((symbol) => holders.get(symbol.id) ?? []),
+  };
+}
+
+/**
+ * Answers which declarations of the run are dead in every configuration that holds them.
+ *
+ * Liveness is a question about one configuration, because a file another configuration
+ * does not compile makes no reference there and a root it does not hold seeds nothing
+ * there, so each configuration is swept on its own graph under the run's input. A
+ * declaration is a candidate when every configuration holding it judged it one: a
+ * reference under one configuration is a reference, so what one project uses is never
+ * reported, and a configuration that does not hold a declaration says nothing about it.
+ * The candidate's relation is reference counting where every configuration found it so,
+ * and reachability otherwise; its counts are the union's, one per reference.
+ *
+ * The components are computed once, over the union and the intersected dead set, so one
+ * dead component is one entry of the run with one identifier.
+ */
+export function sweepMatrix(matrix: Matrix, input: SweepInput): SweepResult {
+  const per = matrix.graphs.map((graph) => sweep(graph, input));
+  const byConfiguration = new Map<string, ReadonlyMap<string, Candidate>>(
+    matrix.configurations.map((configuration, index) => [
+      configuration,
+      new Map((per[index]?.candidates ?? []).map((candidate) => [candidate.id, candidate])),
+    ]),
+  );
+
+  const union = matrix.union;
+  const dead = union.symbols.map(() => false);
+  const testOfDeadCode = union.symbols.map(() => false);
+  const candidates: MatrixCandidate[] = [];
+  union.symbols.forEach((symbol, at) => {
+    const held = matrix.heldIn[at] ?? [];
+    const found = held.map((configuration) => byConfiguration.get(configuration)?.get(symbol.id));
+    if (held.length === 0 || found.some((candidate) => candidate === undefined)) {
+      return;
+    }
+    const all = found.filter((candidate): candidate is Candidate => candidate !== undefined);
+    const admitted = all.every((candidate) => candidate.testOfDeadCode);
+    dead[at] = true;
+    testOfDeadCode[at] = admitted;
+    candidates.push({
+      id: symbol.id,
+      productionRefs: union.made[at]?.production ?? 0,
+      testRefs: union.made[at]?.test ?? 0,
+      relation: all.every((candidate) => candidate.relation === "reference-counting")
+        ? "reference-counting"
+        : "reachability",
+      testOfDeadCode: admitted,
+      configurations: held,
+    });
+  });
+
+  return {
+    liveUnder: liveAnywhere(union.symbols, per),
+    candidates,
+    components: componentsOf(union, dead, testOfDeadCode),
+  };
+}
+
+/** The relations in the order a declaration's entry lists them. */
+const RELATIONS: readonly Relation[] = ["reference-counting", "reachability"];
+
+/**
+ * Per declaration, in site order, every relation that holds it live in at least one
+ * configuration.
+ */
+function liveAnywhere(
+  symbols: readonly InventorySymbol[],
+  per: readonly Liveness[],
+): ReadonlyMap<string, readonly Relation[]> {
+  const live = new Map<string, readonly Relation[]>();
+  for (const symbol of symbols) {
+    const relations = RELATIONS.filter((relation) =>
+      per.some((liveness) => (liveness.liveUnder.get(symbol.id) ?? []).includes(relation)),
+    );
+    if (relations.length > 0) {
+      live.set(symbol.id, relations);
+    }
+  }
+  return live;
+}

package/src/print.ts

@@ -20,12 +20,11 @@ export function printConfig(config: Config, provenance: Provenance): string {
       min_confidence: config.analysis.minConfidence,
       generated_files: config.analysis.generatedFiles,
       consumer_tests: config.analysis.consumerTests,
-      configurations: config.analysis.configurations.map((entry) => ({
-        id: entry.id,
-        os: entry.os,
-        arch: entry.arch,
-        tags: entry.tags,
-      })),
+      configurations: config.analysis.configurations.map((entry) =>
+        entry.shape === "project"
+          ? { id: entry.id, project: entry.project }
+          : { id: entry.id, os: entry.os, arch: entry.arch, tags: entry.tags },
+      ),
       matrix: { complete: config.analysis.matrixComplete },
       template_dirs: config.analysis.templateDirs,
       template_delimiters: {