@cplieger/deadset-ts 3.0.0 → 3.1.0

package/dist/src/roots.js

@@ -2,12 +2,13 @@
  * The root set of one project: every declaration the analysis keeps live without a
  * reference, and why.
  *
- * A root makes its declaration live under REACHABILITY and plays no part in
- * reference counting, which asks only whether some declaration of the loaded graph
- * names it. The two relations are different sets, so an exported declaration that
- * something outside the program reaches is live under the first and still a
- * candidate under the second.
+ * Every root seeds REACHABILITY, and no root counts as a reference. A root of a kind
+ * that names a caller is live under reference counting as well, which the sweep
+ * decides; a root that only supposes a consumer is not, so an exported declaration
+ * something outside the program reaches is live under reachability and still a
+ * candidate under reference counting.
  */
+import { aliasChains } from "./alias-chain.js";
 import { REPOSITORY_DOCUMENT } from "./config.js";
 import { entryPoints } from "./entry-points.js";
 import { globExpression } from "./glob.js";
@@ -143,7 +144,10 @@ export function roots(project, held, targetRoot, options) {
     for (const point of entryPoints(project, files, options.testFiles)) {
         enter(point.file, point.rule, point.source, point.exports);
     }
-    const exportsOf = exportTables(project, held, [...entered.filter((entry) => entry.exports).map((entry) => entry.file), ...published], files.byName);
+    const exportsOf = exportTables(project, held, [
+        ...entered.filter((entry) => entry.exports).map((entry) => entry.file),
+        ...published,
+    ]);
     for (const entry of entered) {
         const id = fileIds.get(entry.file.fileName);
         if (id === undefined) {
@@ -181,41 +185,14 @@ export function roots(project, held, targetRoot, options) {
  * its export table, star re-exports resolved into it. A file that is no module
  * exports nothing.
  */
-function exportTables(project, held, wanted, ownFiles) {
+function exportTables(project, held, wanted) {
     const unique = [...new Map(wanted.map((file) => [file.fileName, file])).values()];
     const tables = new Map();
     if (unique.length === 0) {
         return tables;
     }
     const modules = project.symbolsAt(unique.map((file) => project.handle(file)));
-    const chains = new Map();
-    const chainOf = (symbol) => {
-        const cached = chains.get(symbol.id);
-        if (cached !== undefined) {
-            return cached;
-        }
-        const ids = [];
-        const walked = new Set();
-        let at = symbol;
-        while (at !== undefined && !walked.has(at.id)) {
-            walked.add(at.id);
-            for (const handle of at.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);
-                }
-            }
-            at = project.aliasStepOf(at);
-        }
-        chains.set(symbol.id, ids);
-        return ids;
-    };
+    const chains = aliasChains(project, held);
     unique.forEach((file, index) => {
         const module = modules[index];
         if (module === undefined) {
@@ -224,8 +201,8 @@ function exportTables(project, held, wanted, ownFiles) {
         }
         const ids = new Set();
         for (const exported of project.checker.getExportsOfModule(module)) {
-            for (const id of chainOf(exported)) {
-                ids.add(id);
+            for (const target of chains.chainOf(exported)) {
+                ids.add(target.id);
             }
         }
         tables.set(file.fileName, [...ids]);

package/dist/src/session.js

@@ -1,5 +1,6 @@
 import { API, SymbolFlags } from "@typescript/native/unstable/sync";
 import { isIdentifier } from "@typescript/native/unstable/ast";
+import { DiscoveryError } from "./discover.js";
 /**
  * Opens the compiler client the analysis reads through.
  *
@@ -81,19 +82,29 @@ export function diagnosticsOf(project) {
 }
 /**
  * Runs `visit` over every project the compiler configurations name, inside one
- * snapshot of one client.
+ * snapshot of one client, in the order they are named, and answers in that order.
  *
  * The snapshot is opened once with every configuration, so each becomes a project
  * with its own program and checker; it is never updated, because the analysis
- * reads and the tree does not change under it. It is disposed once when the last
- * project has been visited, and the client is released after it, whether the visit
- * completed or threw.
+ * reads and the tree does not change under it. The order the snapshot lists its
+ * projects in is the compiler's own, so each named configuration is looked up in it
+ * instead, and a configuration the snapshot opened no project for ends the run: the
+ * run would otherwise answer for fewer projects than it was asked to analyze. The
+ * snapshot is disposed once when the last project has been visited, and the client
+ * is released after it, whether the visit completed or threw.
  */
 export function runSession(engine, configFiles, visit) {
     try {
         const snapshot = engine.updateSnapshot(configFiles);
         try {
-            const projects = snapshot.getProjects().map((project) => visit(viewOf(project)));
+            const opened = new Map(snapshot.getProjects().map((project) => [project.configFileName, project]));
+            const projects = configFiles.map((configFile) => {
+                const project = opened.get(configFile);
+                if (project === undefined) {
+                    throw new DiscoveryError(`${configFile} opened no project`, []);
+                }
+                return visit(viewOf(project));
+            });
             return { projects, timing: engine.getTimingInfo() };
         }
         finally {

package/dist/src/sweep.js

@@ -1,19 +1,17 @@
 /**
- * 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;
+ * 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 { 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.
+ * 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);
@@ -70,11 +68,7 @@ export function sweep(graph, input) {
             testOfDeadCode: testOfDeadCode[at] === true,
         });
     });
-    return {
-        liveUnder: live,
-        candidates,
-        components: componentsOf(graph, dead, testOfDeadCode),
-    };
+    return { liveUnder: live, candidates };
 }
 /**
  * Per declaration, whether a seed reaches it. The two seeds reach through different
@@ -86,15 +80,17 @@ 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) => {
+    // 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 (!viaReference || expanded[at] === true) {
+        if (!expands || expanded[at] === true) {
             return;
         }
         expanded[at] = true;
@@ -108,7 +104,7 @@ function reachable(graph, marked, mode) {
                 if (!held && mode.production && edge.test) {
                     continue;
                 }
-                enter(edge.to, true);
+                enter(edge.to, !edge.evaluation);
             }
         }
     };

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "3.0.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": "3.0.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

@@ -12,17 +12,17 @@ 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 { 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 { 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";
+import type { SweepInput } from "./sweep.ts";
 
 /** The setting whose source decides where a finding about a configured root sits. */
 const ROOTS_SETTING = "roots.patterns";
@@ -43,7 +43,7 @@ export interface RunRoot {
 export interface RunRoots {
   /**
    * The configurations the run analyzed, each by the name discovery gives its
-   * project, in discovery order.
+   * project, in discovery order: the order a declared matrix lists them in.
    */
   readonly configurations: readonly string[];
   /**
@@ -122,10 +122,7 @@ function readProjects<Answer>(
     }
     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;
+    const configuration = ids.get(project.configFile) ?? project.configFile;
     return stage(project, { configuration, held, rooted });
   });
   if (failures.length > 0) {
@@ -195,42 +192,39 @@ export function runRoots(
   };
 }
 
-/** 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[];
+/** The run's sweep, beside the matrix it judged. */
+export interface RunSweep {
+  readonly matrix: Matrix;
   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.
+ * 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 runSweeps(
+export function runSweep(
   engine: Engine,
   host: Host,
   scope: Scope,
   config: Config,
   input: SweepInput,
-): readonly ConfigurationSweep[] {
+): RunSweep {
   const targetRoot = scope.target.path;
-  return readProjects(engine, host, scope, config, (project, read) => {
+  const configured = readProjects(engine, host, scope, config, (project, read): Configured => {
     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),
+      references: resolved.references,
+      roots: read.rooted.liveUnderReachability,
+      testFiles: resolved.testFilePaths,
     };
   });
+  const matrix = matrixOf(configured);
+  return { matrix, sweep: sweepMatrix(matrix, input) };
 }

package/src/components.ts

@@ -35,7 +35,7 @@ export interface Component {
    * neither and is counted by its own component.
    */
   readonly falls: readonly string[];
-  /** The source lines the deletion removes, summed over {@link Component.falls}. */
+  /** The source lines the deletion removes: the distinct lines {@link Component.falls} spans. */
   readonly deletableLines: number;
 }
 

package/src/graph.ts

@@ -72,6 +72,11 @@ export function namesACaller(kind: RootKind): boolean {
 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. */
@@ -102,8 +107,8 @@ export interface Graph {
   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 to a file is a reference to the
-   * module's namespace, which reaches everything the module exports.
+   * 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. */
@@ -144,7 +149,11 @@ export function graphOf(
         counts.production += 1;
       }
     }
-    out[at(reference.from)]?.push({ to, test: reference.test });
+    out[at(reference.from)]?.push({
+      to,
+      test: reference.test,
+      evaluation: reference.use === "evaluation",
+    });
   }
 
   const parent = symbols.map((symbol) => at(symbol.parent));