@cplieger/deadset-ts 3.0.0 → 3.2.0

package/src/run.ts

@@ -1,4 +1,4 @@
-import { runRoots, type RunRoot } from "./analysis.ts";
+import { runRoots, runSweep, type RunRoot } from "./analysis.ts";
 import { ConfigError, REPOSITORY_DOCUMENT, type Inputs } from "./config.ts";
 import {
   diagnosticErrors,
@@ -6,6 +6,7 @@ import {
   DiscoveryError,
   renderDiagnostic,
 } from "./discover.ts";
+import { retainedLines } from "./exempt.ts";
 import type { Host } from "./host.ts";
 import { joinPath, resolvePath } from "./paths.ts";
 import { printConfig } from "./print.ts";
@@ -221,6 +222,9 @@ export function run(
   if (verb === "print-roots") {
     return printRootsVerb(args.slice(1), out, err, host, openClient);
   }
+  if (verb === "print-retained") {
+    return printRetainedVerb(args.slice(1), out, err, host, openClient);
+  }
   if (verb !== undefined && (VERBS as readonly string[]).includes(verb)) {
     err.write(`deadset-ts: ${verb} is not implemented\n`);
     return EXIT_USAGE;
@@ -337,6 +341,40 @@ function printRootsVerb(
   }
 }
 
+/**
+ * Writes every declaration an exemption held back in the production sweep a report is
+ * built from, one per line, and nothing where no exemption held one back. One fact
+ * several configurations found is one record, so the line names no configuration. The
+ * line shape is this command's own rather than a Contract format, so that sort and cut
+ * read it.
+ */
+function printRetainedVerb(
+  args: readonly string[],
+  out: Writer,
+  err: Writer,
+  host: Host,
+  openClient: (collectTiming: boolean) => Engine,
+): number {
+  let engine: Engine | undefined;
+  try {
+    const options = readOptions(args);
+    const { config } = resolve(inputsOf(host, options));
+    const scope = scopeOf(host, options);
+    engine = openClient(false);
+    const swept = runSweep(engine, host, scope, config, {
+      marked: [],
+      mode: { production: true },
+    });
+    for (const line of retainedLines(swept.matrix.union.symbols, swept.retained)) {
+      out.write(`${line}\n`);
+    }
+    return EXIT_CLEAN;
+  } catch (error: unknown) {
+    engine?.close();
+    return refuse(error, err);
+  }
+}
+
 /** Turns one refusal into the exit code the Contract's table gives it. */
 function refuse(error: unknown, err: Writer): number {
   if (error instanceof ConfigError) {

package/src/session.ts

@@ -12,6 +12,7 @@ import type {
 } from "@typescript/native/unstable/sync";
 import { isIdentifier } from "@typescript/native/unstable/ast";
 import type { Node, SourceFile } from "@typescript/native/unstable/ast";
+import { DiscoveryError } from "./discover.ts";
 
 /**
  * The compiler the analysis reads through. It is a client over a protocol to a
@@ -218,13 +219,16 @@ export interface SessionResult<Result> {
 
 /**
  * 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<Result>(
   engine: Engine,
@@ -234,7 +238,16 @@ export function runSession<Result>(
   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 {
       snapshot.dispose();

package/src/sweep.ts

@@ -1,17 +1,29 @@
 /**
- * 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, type Component } from "./components.ts";
+import type { TSExemptionClass } from "./exempt-classes.ts";
 import { namesACaller, OUTSIDE, type Graph } from "./graph.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 run's reference mode, decided once by the composition and read by every stage
  * that counts references.
@@ -32,6 +44,13 @@ export interface SweepInput {
    * 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[];
   readonly mode: Mode;
 }
 
@@ -54,8 +73,8 @@ export interface Candidate {
   readonly testOfDeadCode: boolean;
 }
 
-/** One sweep's answer. */
-export interface SweepResult {
+/** 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.
@@ -63,8 +82,6 @@ export interface SweepResult {
   readonly liveUnder: ReadonlyMap<string, readonly Relation[]>;
   /** The dead declarations, in the order the inventory holds them. */
   readonly candidates: readonly Candidate[];
-  /** The dead components, each before every component it reaches. */
-  readonly components: readonly Component[];
 }
 
 /**
@@ -72,20 +89,19 @@ export interface SweepResult {
  *
  * 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 no exemption holds back, and the tests of dead
+ * code join it.
  */
-export function sweep(graph: Graph, input: SweepInput): SweepResult {
-  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.
+export function sweep(graph: Graph, input: SweepInput): Liveness {
+  const marked = flagged(graph, input.marked);
+  const exempt = flagged(
+    graph,
+    (input.exempt ?? []).map((record) => record.id),
+  );
+  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)) {
@@ -100,7 +116,7 @@ export function sweep(graph: Graph, input: SweepInput): SweepResult {
     }
     return input.mode.production ? made.production : made.production + made.test;
   };
-  const reached = reachable(graph, marked, 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) {
@@ -113,9 +129,10 @@ export function sweep(graph: Graph, input: SweepInput): SweepResult {
   });
 
   const dead = graph.symbols.map(
-    (_symbol, at) => graph.subject[at] === true && (liveUnder[at]?.length ?? 0) < 2,
+    (_symbol, at) =>
+      graph.subject[at] === true && exempt[at] !== true && (liveUnder[at]?.length ?? 0) < 2,
   );
-  const testOfDeadCode = admitTestsOfDeadCode(graph, dead, marked);
+  const testOfDeadCode = admitTestsOfDeadCode(graph, dead, held);
 
   const candidates: Candidate[] = [];
   const live = new Map<string, readonly Relation[]>();
@@ -136,33 +153,44 @@ export function sweep(graph: Graph, input: SweepInput): SweepResult {
     });
   });
 
-  return {
-    liveUnder: live,
-    candidates,
-    components: componentsOf(graph, dead, testOfDeadCode),
-  };
+  return { liveUnder: live, candidates };
+}
+
+/** 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 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.
+ * 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, marked: readonly boolean[], mode: Mode): readonly boolean[] {
+function reachable(graph: Graph, held: readonly boolean[], mode: Mode): readonly boolean[] {
   const reached = graph.symbols.map(() => false);
   const expanded = graph.symbols.map(() => false);
   const queue: number[] = [];
 
-  // 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: number, viaReference: boolean): void => {
+  // 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 (!viaReference || expanded[at] === true) {
+    if (!expands || expanded[at] === true) {
       return;
     }
     expanded[at] = true;
@@ -170,19 +198,19 @@ function reachable(graph: Graph, marked: readonly boolean[], mode: Mode): readon
       enter(exported, false);
     }
   };
-  const walk = (held: boolean): void => {
+  const walk = (holding: boolean): void => {
     for (let at = queue.pop(); at !== undefined; at = queue.pop()) {
       for (const edge of graph.out[at] ?? []) {
-        if (!held && mode.production && edge.test) {
+        if (!holding && mode.production && edge.test) {
           continue;
         }
-        enter(edge.to, true);
+        enter(edge.to, !edge.evaluation);
       }
     }
   };
 
-  marked.forEach((mark, at) => {
-    if (mark) {
+  held.forEach((hold, at) => {
+    if (hold) {
       enter(at, false);
     }
   });
@@ -198,16 +226,17 @@ function reachable(graph: Graph, marked: readonly boolean[], mode: Mode): readon
  * 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.
+ * which is what makes the targets dead. A test referencing one live target is never
+ * admitted, and neither is a marked or exempt test.
  */
 function admitTestsOfDeadCode(
   graph: Graph,
   dead: boolean[],
-  marked: readonly boolean[],
+  held: readonly boolean[],
 ): readonly boolean[] {
   const admitted = graph.symbols.map(() => false);
   graph.symbols.forEach((_symbol, at) => {
-    if (graph.test[at] !== true || graph.subject[at] !== true || marked[at] === true) {
+    if (graph.test[at] !== true || graph.subject[at] !== true || held[at] === true) {
       return;
     }
     let targets = 0;

package/src/version.ts

@@ -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.2.0";
+export const CONTRACT_VERSION = "3.0.0";