@cplieger/deadset-ts 2.3.0 → 3.1.0

package/dist/src/sweep.js

@@ -0,0 +1,152 @@
+/**
+ * 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 { 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, and the tests of dead code join it.
+ */
+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 };
+}
+/**
+ * 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 = [];
+    // 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, expands) => {
+        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 = (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, !edge.evaluation);
+            }
+        }
+    };
+    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.3.0",
+  "version": "3.1.0",
   "license": "GPL-3.0-or-later",
   "exports": {
     ".": "./src/index.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "2.3.0",
+  "version": "3.1.0",
   "type": "module",
   "sideEffects": false,
   "description": "Deterministic dead-code analysis for TypeScript, class and type members included",

package/src/alias-chain.ts

@@ -0,0 +1,135 @@
+/**
+ * Where an import or export chain leads in one project: from one symbol to each
+ * declaration of the target it is, and along the chain of aliases it heads to each
+ * declaration every link of that chain is.
+ */
+
+import { SymbolFlags, type Symbol as TSSymbol } from "@typescript/native/unstable/sync";
+import { nodeKey, type Inventory } from "./inventory.ts";
+import type { ProjectView } from "./session.ts";
+
+/** One declaration a chain reaches, and whether a step along an alias reached it. */
+export interface ChainTarget {
+  readonly id: string;
+  /** False for a declaration the head symbol itself is, true for one a link stands for. */
+  readonly stepped: boolean;
+}
+
+/** The chain walks over one project's aliases, each step asked of the compiler once. */
+export interface AliasChains {
+  /**
+   * The declarations of the inventory one symbol is, each once. A declaration outside
+   * the project's own files belongs to another program and is not one of them.
+   */
+  declarationsOf(symbol: TSSymbol): readonly string[];
+  /**
+   * The declarations one symbol is, and those of every link of the alias chain it
+   * stands at the head of, each once and in chain order. A link the inventory does
+   * not declare is stepped over rather than named.
+   */
+  chainOf(symbol: TSSymbol): readonly ChainTarget[];
+  /**
+   * The declarations of the first link after `symbol` along its chain that the
+   * inventory declares, stepping over the links it does not, or none where no later
+   * link is declared.
+   */
+  nextDeclared(symbol: TSSymbol): readonly string[];
+  /** How many steps the compiler was asked for: one per alias, whatever the chains it heads. */
+  readonly steps: number;
+}
+
+/**
+ * The chain walks over one project, against the declarations of `held`, the same
+ * project's inventory.
+ *
+ * A declaration handle carries the file it is in, so whether it is one of the
+ * project's own files is answered before the handle is resolved: a declaration of a
+ * library file is never fetched to find out that the inventory does not hold it.
+ */
+export function aliasChains<Brand>(project: ProjectView<Brand>, held: Inventory): AliasChains {
+  const ownFiles = new Set(project.ownSourceFiles().map((file) => file.fileName));
+  const steps = new Map<number, TSSymbol | undefined>();
+  const chains = new Map<number, readonly ChainTarget[]>();
+  let asked = 0;
+
+  const declarationsOf = (symbol: TSSymbol): string[] => {
+    const ids: string[] = [];
+    for (const handle of symbol.declarations) {
+      if (!ownFiles.has(handle.path)) {
+        continue;
+      }
+      const node = project.declarationAt(handle)?.node;
+      const id =
+        node === undefined ? undefined : held.declarations.get(nodeKey(node.getSourceFile(), node));
+      if (id !== undefined && !ids.includes(id)) {
+        ids.push(id);
+      }
+    }
+    return ids;
+  };
+
+  /**
+   * What one alias names, one link along. Only a symbol the binder flagged an alias is
+   * asked, which is the condition the step asserts on: a default export of an
+   * expression is written in an alias form and names nothing declared elsewhere, so its
+   * chain ends at itself.
+   */
+  const stepOf = (symbol: TSSymbol): TSSymbol | undefined => {
+    if ((symbol.flags & SymbolFlags.Alias) === 0) {
+      return undefined;
+    }
+    if (steps.has(symbol.id)) {
+      return steps.get(symbol.id);
+    }
+    const next = project.aliasStepOf(symbol);
+    asked += 1;
+    steps.set(symbol.id, next);
+    return next;
+  };
+
+  const chainOf = (symbol: TSSymbol): readonly ChainTarget[] => {
+    const cached = chains.get(symbol.id);
+    if (cached !== undefined) {
+      return cached;
+    }
+    const targets: ChainTarget[] = [];
+    const walked = new Set<number>();
+    let at: TSSymbol | undefined = symbol;
+    let stepped = false;
+    while (at !== undefined && !walked.has(at.id)) {
+      walked.add(at.id);
+      for (const id of declarationsOf(at)) {
+        if (!targets.some((target) => target.id === id)) {
+          targets.push({ id, stepped });
+        }
+      }
+      at = stepOf(at);
+      stepped = true;
+    }
+    chains.set(symbol.id, targets);
+    return targets;
+  };
+
+  const nextDeclared = (symbol: TSSymbol): readonly string[] => {
+    const walked = new Set<number>([symbol.id]);
+    let at = stepOf(symbol);
+    while (at !== undefined && !walked.has(at.id)) {
+      walked.add(at.id);
+      const ids = declarationsOf(at);
+      if (ids.length > 0) {
+        return ids;
+      }
+      at = stepOf(at);
+    }
+    return [];
+  };
+
+  return {
+    declarationsOf,
+    chainOf,
+    nextDeclared,
+    get steps() {
+      return asked;
+    },
+  };
+}

package/src/analysis.ts

@@ -13,13 +13,16 @@ import type { Config, Provenance } from "./config.ts";
 import { diagnosticErrors, discoverProjects, DiscoveryError } from "./discover.ts";
 import type { Finding } from "./finding.ts";
 import type { Host } from "./host.ts";
-import { inventory } from "./inventory.ts";
+import { inventory, type Inventory } from "./inventory.ts";
 import { readManifest } from "./manifest.ts";
+import { matrixOf, sweepMatrix, type Configured, type Matrix, type SweepResult } from "./matrix.ts";
 import { relativePath, resolvePath } from "./paths.ts";
 import { byPosition, type Position } from "./position.ts";
-import { roots, unmatchedEverywhere, unmatchedRoots, type RootKind } from "./roots.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 } from "./session.ts";
+import { diagnosticsOf, runSession, type Engine, type ProjectView } from "./session.ts";
+import type { SweepInput } from "./sweep.ts";
 
 /** The setting whose source decides where a finding about a configured root sits. */
 const ROOTS_SETTING = "roots.patterns";
@@ -39,8 +42,8 @@ export interface RunRoot {
 /** The root set of one run, and the findings about the roots the configuration names. */
 export interface RunRoots {
   /**
-   * The configurations the run analyzed: each compiler configuration file, by its
-   * path below the target root, in discovery order.
+   * The configurations the run analyzed, each by the name discovery gives its
+   * project, in discovery order: the order a declared matrix lists them in.
    */
   readonly configurations: readonly string[];
   /**
@@ -80,26 +83,31 @@ function compare(a: string, b: string): number {
   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;
+}
+
 /**
- * The root set of the run the scope and the configuration describe.
- *
- * Every project is read for errors before anything else, and a project carrying one
- * fails the run with no root set, as every verb that reads declarations does. A
- * configured string is a finding when it names nothing in every project, and the
- * finding sits in the document that declared the 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.
  */
-export function runRoots(
+function readProjects<Answer>(
   engine: Engine,
   host: Host,
   scope: Scope,
   config: Config,
-  provenance: Provenance,
-): RunRoots {
+  stage: <Brand>(project: ProjectView<Brand>, read: ProjectRead) => Answer,
+): readonly Answer[] {
   const targetRoot = scope.target.path;
-  const discovered = discoverProjects(engine, host, scope);
-  const manifest = readManifest(host, targetRoot);
+  const discovered = discoverProjects(engine, host, scope, config.analysis.configurations);
+  const ids = new Map(discovered.projects.map((project) => [project.configFile, project.id]));
   const options = {
-    manifest,
+    manifest: readManifest(host, targetRoot),
     patterns: config.rootPatterns,
     entryFiles: config.ts.entryFiles,
     testFiles: config.ts.testFiles,
@@ -113,7 +121,9 @@ export function runRoots(
       return undefined;
     }
     const held = inventory(project, host, targetRoot);
-    return { held, rooted: roots(project, held, targetRoot, options) };
+    const rooted = roots(project, held, targetRoot, options);
+    const configuration = ids.get(project.configFile) ?? project.configFile;
+    return stage(project, { configuration, held, rooted });
   });
   if (failures.length > 0) {
     throw new DiscoveryError(
@@ -121,15 +131,29 @@ export function runRoots(
       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) {
-    if (answer === undefined) {
-      continue;
-    }
-    const configuration =
-      relativePath(targetRoot, answer.rooted.configFile) ?? answer.rooted.configFile;
+    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) {
@@ -159,7 +183,7 @@ export function runRoots(
   );
   const unmatched = unmatchedEverywhere(
     config.rootPatterns,
-    projects.flatMap((answer) => (answer === undefined ? [] : [answer.rooted])),
+    projects.map((answer) => answer.rooted),
   );
   return {
     configurations,
@@ -167,3 +191,40 @@ export function runRoots(
     findings: unmatchedRoots(unmatched, documentOf(host, provenance, ROOTS_SETTING, targetRoot)),
   };
 }
+
+/** The run's sweep, beside the matrix it judged. */
+export interface RunSweep {
+  readonly matrix: Matrix;
+  readonly sweep: SweepResult;
+}
+
+/**
+ * Sweeps the run the scope and the configuration describe. Each project's references
+ * are read against its own inventory with the configured test-file patterns while its
+ * view is open; the projects then merge into one matrix in discovery order, which is
+ * swept under the input the caller decided once for the run. A project that carries
+ * an error ends the run before any project is swept.
+ */
+export function runSweep(
+  engine: Engine,
+  host: Host,
+  scope: Scope,
+  config: Config,
+  input: SweepInput,
+): RunSweep {
+  const targetRoot = scope.target.path;
+  const configured = readProjects(engine, host, scope, config, (project, read): Configured => {
+    const resolved = references(project, read.held, targetRoot, {
+      testFiles: config.ts.testFiles,
+    });
+    return {
+      configuration: read.configuration,
+      symbols: read.held.symbols,
+      references: resolved.references,
+      roots: read.rooted.liveUnderReachability,
+      testFiles: resolved.testFilePaths,
+    };
+  });
+  const matrix = matrixOf(configured);
+  return { matrix, sweep: sweepMatrix(matrix, input) };
+}