@cplieger/deadset-ts 2.2.1 → 3.0.0

package/dist/src/sweep.js

@@ -0,0 +1,156 @@
+/**
+ * Which declarations of one graph are dead, under which liveness relation, and which
+ * dead component each belongs to. Reference counting holds a declaration live when any
+ * declaration references it, whatever that one's own liveness, and no root plays a part;
+ * 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 { componentsOf } from "./components.js";
+import { namesACaller, OUTSIDE } from "./graph.js";
+/**
+ * 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, the tests of dead code join it, and the components
+ * are computed over the set that results.
+ */
+export function sweep(graph, input) {
+    const marked = graph.symbols.map(() => false);
+    for (const id of input.marked) {
+        const at = graph.at(id);
+        if (at !== OUTSIDE) {
+            marked[at] = true;
+        }
+    }
+    // Every root and every mark 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.
+    const called = graph.symbols.map(() => false);
+    for (const root of graph.rooted) {
+        if (namesACaller(root.kind)) {
+            called[root.at] = true;
+        }
+    }
+    const counted = (at) => {
+        const made = graph.made[at];
+        if (made === undefined) {
+            return 0;
+        }
+        return input.mode.production ? made.production : made.production + made.test;
+    };
+    const reached = reachable(graph, marked, input.mode);
+    const liveUnder = graph.symbols.map((_symbol, at) => {
+        const relations = [];
+        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 && (liveUnder[at]?.length ?? 0) < 2);
+    const testOfDeadCode = admitTestsOfDeadCode(graph, dead, marked);
+    const candidates = [];
+    const live = new Map();
+    graph.symbols.forEach((symbol, at) => {
+        const relations = liveUnder[at] ?? [];
+        if (relations.length > 0) {
+            live.set(symbol.id, relations);
+        }
+        if (dead[at] !== true) {
+            return;
+        }
+        candidates.push({
+            id: symbol.id,
+            productionRefs: graph.made[at]?.production ?? 0,
+            testRefs: graph.made[at]?.test ?? 0,
+            relation: counted(at) === 0 ? "reference-counting" : "reachability",
+            testOfDeadCode: testOfDeadCode[at] === true,
+        });
+    });
+    return {
+        liveUnder: live,
+        candidates,
+        components: componentsOf(graph, dead, testOfDeadCode),
+    };
+}
+/**
+ * Per declaration, whether a seed reaches it. The two seeds reach through different
+ * reference sets: a marked declaration is live by a mechanism the analysis cannot see, so
+ * no mode withholds a reference it makes, while a root reaches through the references the
+ * mode counts. The marks run first, so what they reach is expanded under the wider rule.
+ */
+function reachable(graph, marked, mode) {
+    const reached = graph.symbols.map(() => false);
+    const expanded = graph.symbols.map(() => false);
+    const queue = [];
+    // A reference to a file is a reference to the module's namespace, which reaches what
+    // the module exports as well as its top level. A root does not expand: a file a
+    // runtime runs without reading its exports is a root by itself.
+    const enter = (at, viaReference) => {
+        if (!reached[at]) {
+            reached[at] = true;
+            queue.push(at);
+        }
+        if (!viaReference || expanded[at] === true) {
+            return;
+        }
+        expanded[at] = true;
+        for (const exported of graph.exportsOf[at] ?? []) {
+            enter(exported, false);
+        }
+    };
+    const walk = (held) => {
+        for (let at = queue.pop(); at !== undefined; at = queue.pop()) {
+            for (const edge of graph.out[at] ?? []) {
+                if (!held && mode.production && edge.test) {
+                    continue;
+                }
+                enter(edge.to, true);
+            }
+        }
+    };
+    marked.forEach((mark, at) => {
+        if (mark) {
+            enter(at, false);
+        }
+    });
+    walk(true);
+    for (const root of graph.rooted) {
+        enter(root.at, false);
+    }
+    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. The set is read from every
+ * reference the test makes, not the ones the mode counts: a production sweep counts none,
+ * which is what makes the targets dead. A test referencing one live target is never admitted.
+ */
+function admitTestsOfDeadCode(graph, dead, marked) {
+    const admitted = graph.symbols.map(() => false);
+    graph.symbols.forEach((_symbol, at) => {
+        if (graph.test[at] !== true || graph.subject[at] !== true || marked[at] === true) {
+            return;
+        }
+        let targets = 0;
+        let live = 0;
+        for (const edge of graph.out[at] ?? []) {
+            if (graph.test[edge.to] === true || graph.subject[edge.to] !== true) {
+                continue;
+            }
+            targets += 1;
+            if (dead[edge.to] !== true) {
+                live += 1;
+            }
+        }
+        if (targets > 0 && live === 0) {
+            dead[at] = true;
+            admitted[at] = true;
+        }
+    });
+    return admitted;
+}

package/dist/src/version.js

@@ -4,4 +4,4 @@
  * independently of the analyzer's own version, which is the one the host answers
  * from the package the analyzer was installed from.
  */
-export const CONTRACT_VERSION = "2.1.0";
+export const CONTRACT_VERSION = "2.2.0";

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "2.2.1",
+  "version": "3.0.0",
   "license": "GPL-3.0-or-later",
   "exports": {
     ".": "./src/index.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "2.2.1",
+  "version": "3.0.0",
   "type": "module",
   "sideEffects": false,
   "description": "Deterministic dead-code analysis for TypeScript, class and type members included",
@@ -33,9 +33,9 @@
   "devDependencies": {
     "@eslint/js": "10.0.1",
     "@types/node": "24.13.5",
-    "eslint": "10.10.0",
+    "eslint": "10.11.0",
     "fast-check": "4.10.1",
-    "prettier": "3.9.7",
+    "prettier": "3.9.8",
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "typescript-eslint": "8.70.0",
     "vitest": "5.0.1"

package/src/analysis.ts

@@ -0,0 +1,236 @@
+/**
+ * One run's passes, composed: the projects discovery names, opened in one snapshot
+ * of one client, each read through the stages in the order they depend on each
+ * other, and the per-project answers merged into the answer for the run.
+ *
+ * The stages take a project's view, which only this composition makes: a view
+ * carries a project's identity in its type so a handle cannot cross to another
+ * project's checker, and that holds only for views the session itself hands out.
+ */
+
+import type { Diagnostic } from "@typescript/native/unstable/sync";
+import type { Config, Provenance } from "./config.ts";
+import { diagnosticErrors, discoverProjects, DiscoveryError } from "./discover.ts";
+import type { Finding } from "./finding.ts";
+import { graphOf } from "./graph.ts";
+import type { Host } from "./host.ts";
+import { inventory, type Inventory, type InventorySymbol } from "./inventory.ts";
+import { readManifest } from "./manifest.ts";
+import { relativePath, resolvePath } from "./paths.ts";
+import { byPosition, type Position } from "./position.ts";
+import { references } from "./references.ts";
+import { roots, unmatchedEverywhere, unmatchedRoots, type RootKind, type Roots } from "./roots.ts";
+import type { Scope } from "./scope.ts";
+import { diagnosticsOf, runSession, type Engine, type ProjectView } from "./session.ts";
+import { sweep, type SweepInput, type SweepResult } from "./sweep.ts";
+
+/** The setting whose source decides where a finding about a configured root sits. */
+const ROOTS_SETTING = "roots.patterns";
+
+/** One root of the run, merged across the projects that hold it. */
+export interface RunRoot {
+  /** The stable reference of the declaration the root names. */
+  readonly ref: string;
+  /** Where that declaration is written. */
+  readonly position: Position;
+  readonly kind: RootKind;
+  readonly source: string;
+  /** The configurations whose project holds this root, in the run's order. */
+  readonly configurations: readonly string[];
+}
+
+/** The root set of one run, and the findings about the roots the configuration names. */
+export interface RunRoots {
+  /**
+   * The configurations the run analyzed, each by the name discovery gives its
+   * project, in discovery order.
+   */
+  readonly configurations: readonly string[];
+  /**
+   * Every root of the run, ordered by the site of its declaration, then by kind, then
+   * by the string that named it. A root several projects hold is one entry naming each.
+   */
+  readonly roots: readonly RunRoot[];
+  /** One finding per configured root or pattern that named nothing in any project. */
+  readonly findings: readonly Finding[];
+}
+
+/**
+ * The document that supplied one setting, below the target root, or the empty
+ * string where the setting came from no document of the target. Both paths are
+ * resolved against the working directory before one is read below the other, so a
+ * relative target and a relative document name the same place.
+ */
+function documentOf(
+  host: Host,
+  provenance: Provenance,
+  setting: string,
+  targetRoot: string,
+): string {
+  const origin = provenance.get(setting);
+  if (origin === undefined || origin.source === "default" || origin.source === "flag") {
+    return "";
+  }
+  const document = resolvePath(host.workingDirectory(), origin.label);
+  return relativePath(resolvePath(host.workingDirectory(), targetRoot), document) ?? "";
+}
+
+/** Two strings ordered bytewise. */
+function compare(a: string, b: string): number {
+  if (a === b) {
+    return 0;
+  }
+  return a < b ? -1 : 1;
+}
+
+/** What every stage after the root set reads of one project. */
+interface ProjectRead {
+  readonly configuration: string;
+  readonly held: Inventory;
+  readonly rooted: Roots;
+}
+
+/**
+ * Reads every project the scope discovers, in one snapshot: each is checked for errors
+ * first, then enumerated, then rooted, and `stage` reads the rest of what it needs from
+ * the project while its view is open. A project carrying an error fails the run with no
+ * answer, as every verb that reads declarations does.
+ */
+function readProjects<Answer>(
+  engine: Engine,
+  host: Host,
+  scope: Scope,
+  config: Config,
+  stage: <Brand>(project: ProjectView<Brand>, read: ProjectRead) => Answer,
+): readonly Answer[] {
+  const targetRoot = scope.target.path;
+  const discovered = discoverProjects(engine, host, scope, config.analysis.configurations);
+  const ids = new Map(discovered.projects.map((project) => [project.configFile, project.id]));
+  const options = {
+    manifest: readManifest(host, targetRoot),
+    patterns: config.rootPatterns,
+    entryFiles: config.ts.entryFiles,
+    testFiles: config.ts.testFiles,
+    publishedAPI: config.targetKind === "library",
+  };
+  const failures: Diagnostic[] = [];
+  const { projects } = runSession(engine, discovered.configFiles, (project) => {
+    const errors = diagnosticErrors(diagnosticsOf(project));
+    if (errors.length > 0) {
+      failures.push(...errors);
+      return undefined;
+    }
+    const held = inventory(project, host, targetRoot);
+    const rooted = roots(project, held, targetRoot, options);
+    const configuration =
+      ids.get(project.configFile) ??
+      relativePath(targetRoot, project.configFile) ??
+      project.configFile;
+    return stage(project, { configuration, held, rooted });
+  });
+  if (failures.length > 0) {
+    throw new DiscoveryError(
+      `${String(failures.length)} error(s); no answer was produced`,
+      failures,
+    );
+  }
+  return projects.filter((answer): answer is Answer => answer !== undefined);
+}
+
+/**
+ * The root set of the run the scope and the configuration describe.
+ *
+ * A configured string is a finding when it names nothing in every project, and the
+ * finding sits in the document that declared the roots.
+ */
+export function runRoots(
+  engine: Engine,
+  host: Host,
+  scope: Scope,
+  config: Config,
+  provenance: Provenance,
+): RunRoots {
+  const targetRoot = scope.target.path;
+  const projects = readProjects(engine, host, scope, config, (_project, read) => read);
+
+  const configurations: string[] = [];
+  const merged = new Map<string, Omit<RunRoot, "configurations"> & { configurations: string[] }>();
+  for (const answer of projects) {
+    const configuration = answer.configuration;
+    configurations.push(configuration);
+    const symbols = new Map(answer.held.symbols.map((symbol) => [symbol.id, symbol]));
+    for (const root of answer.rooted.liveUnderReachability) {
+      const symbol = symbols.get(root.id);
+      if (symbol === undefined) {
+        continue;
+      }
+      const key = [root.id, root.kind, root.source].join("\u0000");
+      const held = merged.get(key);
+      if (held === undefined) {
+        merged.set(key, {
+          ref: symbol.ref,
+          position: symbol.position,
+          kind: root.kind,
+          source: root.source,
+          configurations: [configuration],
+        });
+      } else if (!held.configurations.includes(configuration)) {
+        held.configurations.push(configuration);
+      }
+    }
+  }
+
+  const ordered = [...merged.values()].sort(
+    (a, b) =>
+      byPosition(a.position, b.position) || compare(a.kind, b.kind) || compare(a.source, b.source),
+  );
+  const unmatched = unmatchedEverywhere(
+    config.rootPatterns,
+    projects.map((answer) => answer.rooted),
+  );
+  return {
+    configurations,
+    roots: ordered,
+    findings: unmatchedRoots(unmatched, documentOf(host, provenance, ROOTS_SETTING, targetRoot)),
+  };
+}
+
+/** One configuration's sweep, beside the declarations it judged. */
+export interface ConfigurationSweep {
+  /** The name discovery gives the configuration's project. */
+  readonly configuration: string;
+  readonly symbols: readonly InventorySymbol[];
+  readonly sweep: SweepResult;
+}
+
+/**
+ * Sweeps every project of the run the scope and the configuration describe, one
+ * configuration at a time, in discovery order. Each project's references are read
+ * against its own inventory with the configured test-file patterns, and its graph is
+ * swept under the input the caller decided once for the run.
+ */
+export function runSweeps(
+  engine: Engine,
+  host: Host,
+  scope: Scope,
+  config: Config,
+  input: SweepInput,
+): readonly ConfigurationSweep[] {
+  const targetRoot = scope.target.path;
+  return readProjects(engine, host, scope, config, (project, read) => {
+    const resolved = references(project, read.held, targetRoot, {
+      testFiles: config.ts.testFiles,
+    });
+    const graph = graphOf(
+      read.held.symbols,
+      resolved.references,
+      read.rooted.liveUnderReachability,
+      resolved.testFilePaths,
+    );
+    return {
+      configuration: read.configuration,
+      symbols: read.held.symbols,
+      sweep: sweep(graph, input),
+    };
+  });
+}