@cplieger/deadset-ts 2.3.0 → 3.0.0

package/src/resolve.ts

@@ -38,6 +38,24 @@ const SEVERITY_KEY = /^DS[0-9]{2}([0-9]{2})?$/u;
 const EXEMPTION_CLASS = /^[a-z][a-z0-9-]*$/u;
 const CONTRACT_VERSION_PATTERN = /^[0-9]+\.[0-9]+\.[0-9]+$/u;
 
+/** The members only a platform build configuration carries. */
+const PLATFORM_MEMBERS = ["os", "arch", "tags"] as const;
+
+/** The member only a project build configuration carries. */
+const PROJECT_MEMBER = "project";
+
+/**
+ * One segment of a project path: not empty, not `.` or `..`, and holding no
+ * solidus, backslash or line break.
+ */
+const PROJECT_SEGMENT = String.raw`(?:[^/\\.\r\n][^/\\\r\n]*|\.[^/\\.\r\n][^/\\\r\n]*|\.\.[^/\\\r\n]+)`;
+
+/**
+ * A project path: segments joined by a solidus, so the path is relative, below
+ * the root it is read against, and spelled one way on every machine.
+ */
+const PROJECT_PATH = new RegExp(`^${PROJECT_SEGMENT}(?:/${PROJECT_SEGMENT})*$`, "u");
+
 const TARGET_KINDS: readonly TargetKind[] = ["application", "library"];
 const CONFIDENCES: readonly Confidence[] = ["certain", "probable", "possible"];
 const GENERATED_FILES: readonly GeneratedFiles[] = ["exclude", "include"];
@@ -252,10 +270,75 @@ function requireMember(value: string | undefined, path: string, label: string):
   return value;
 }
 
+/** One build configuration entry as a platform: an identifier, an operating system and an architecture. */
+function readPlatform(
+  entry: Record<string, unknown>,
+  at: string,
+  label: string,
+): BuildConfiguration {
+  return {
+    shape: "platform",
+    id: requireMember(readString(entry, "id", `${at}.id`, label), `${at}.id`, label),
+    os: requireMember(readString(entry, "os", `${at}.os`, label), `${at}.os`, label),
+    arch: requireMember(readString(entry, "arch", `${at}.arch`, label), `${at}.arch`, label),
+    tags: readStrings(entry, "tags", `${at}.tags`, label, 0) ?? [],
+  };
+}
+
+/** One build configuration entry as a project: an identifier and a configuration file below the target root. */
+function readProject(
+  entry: Record<string, unknown>,
+  at: string,
+  label: string,
+): BuildConfiguration {
+  const id = requireMember(readString(entry, "id", `${at}.id`, label), `${at}.id`, label);
+  const path = `${at}.${PROJECT_MEMBER}`;
+  const project = requireMember(readString(entry, PROJECT_MEMBER, path, label), path, label);
+  if (!PROJECT_PATH.test(project)) {
+    throw malformed(
+      label,
+      path,
+      `${JSON.stringify(project)} is not a path below the target root: segments joined by /, ` +
+        "none empty, . or .., and no backslash or line break",
+    );
+  }
+  return { shape: "project", id, project };
+}
+
 /**
- * The build matrix: every entry names an identifier, an operating system and an
- * architecture.
+ * One build configuration entry, read as the one shape its members name: a member
+ * only a platform carries makes it a platform, the member only a project carries
+ * makes it a project, and an entry naming members of both, or of neither, is
+ * refused at the entry, because the two shapes are exclusive.
  */
+function readConfiguration(entry: unknown, at: string, label: string): BuildConfiguration {
+  if (!isRecord(entry)) {
+    throw malformed(label, at, "is not an object");
+  }
+  const platform = PLATFORM_MEMBERS.filter((name) => Object.hasOwn(entry, name));
+  const project = Object.hasOwn(entry, PROJECT_MEMBER);
+  if (platform.length > 0 && project) {
+    throw malformed(
+      label,
+      at,
+      `carries ${spell(platform)} of a platform and ${JSON.stringify(PROJECT_MEMBER)} of a ` +
+        "project, and an entry is one shape or the other",
+    );
+  }
+  if (project) {
+    return readProject(entry, at, label);
+  }
+  if (platform.length === 0) {
+    throw malformed(
+      label,
+      at,
+      `names neither a platform's "os" and "arch" nor a project's ${JSON.stringify(PROJECT_MEMBER)}`,
+    );
+  }
+  return readPlatform(entry, at, label);
+}
+
+/** The build matrix, one entry in one shape at a time. */
 function readConfigurations(
   analysis: Record<string, unknown> | undefined,
   label: string,
@@ -267,18 +350,9 @@ function readConfigurations(
   if (!Array.isArray(value)) {
     throw malformed(label, "analysis.configurations", "is not an array");
   }
-  return (value as unknown[]).map((entry, index) => {
-    const at = `analysis.configurations[${String(index)}]`;
-    if (!isRecord(entry)) {
-      throw malformed(label, at, "is not an object");
-    }
-    return {
-      id: requireMember(readString(entry, "id", `${at}.id`, label), `${at}.id`, label),
-      os: requireMember(readString(entry, "os", `${at}.os`, label), `${at}.os`, label),
-      arch: requireMember(readString(entry, "arch", `${at}.arch`, label), `${at}.arch`, label),
-      tags: readStrings(entry, "tags", `${at}.tags`, label, 0) ?? [],
-    };
-  });
+  return (value as unknown[]).map((entry, index) =>
+    readConfiguration(entry, `analysis.configurations[${String(index)}]`, label),
+  );
 }
 
 /**
@@ -642,6 +716,35 @@ function checkLabels(provenance: ReadonlyMap<string, Origin>): void {
  * the usage exit code.
  */
 export function resolve(inputs: Inputs): { config: Config; provenance: Provenance } {
+  const { config, provenance } = settleAll(inputs);
+  if (config.targetKind === "") {
+    throw new ConfigError(
+      "missing-target-kind",
+      "target.kind",
+      "target.kind is not set, it has no default and is never inferred: searched " +
+        `${describeSource("the repository configuration", inputs.repository, inputs.repositoryLabel)} and ` +
+        describeSource("the central configuration", inputs.central, inputs.centralLabel),
+    );
+  }
+  checkLabels(provenance);
+  return { config, provenance };
+}
+
+/**
+ * The build matrix the configuration documents resolve to, every document read and
+ * refused as {@link resolve} refuses it, and nothing else required of them: which
+ * projects a run analyzes depends on the matrix alone, so a question about the
+ * projects asks no target kind.
+ */
+export function resolveMatrix(inputs: Inputs): readonly BuildConfiguration[] {
+  return settleAll(inputs).config.analysis.configurations;
+}
+
+/**
+ * Every setting the documents supply, each from the highest-ranked source carrying
+ * it, with the origin of each. The target kind is empty where no source names one.
+ */
+function settleAll(inputs: Inputs): { config: Config; provenance: Map<string, Origin> } {
   const sources = readSources(inputs);
   const defaults = defaultConfig();
   const provenance = new Map<string, Origin>();
@@ -718,15 +821,5 @@ export function resolve(inputs: Inputs): { config: Config; provenance: Provenanc
     },
   };
 
-  if (config.targetKind === "") {
-    throw new ConfigError(
-      "missing-target-kind",
-      "target.kind",
-      "target.kind is not set, it has no default and is never inferred: searched " +
-        `${describeSource("the repository configuration", inputs.repository, inputs.repositoryLabel)} and ` +
-        describeSource("the central configuration", inputs.central, inputs.centralLabel),
-    );
-  }
-  checkLabels(provenance);
   return { config, provenance };
 }

package/src/run.ts

@@ -9,7 +9,7 @@ import {
 import type { Host } from "./host.ts";
 import { joinPath, resolvePath } from "./paths.ts";
 import { printConfig } from "./print.ts";
-import { resolve } from "./resolve.ts";
+import { resolve, resolveMatrix } from "./resolve.ts";
 import { readScope, ScopeError, scopeForDir, type Scope } from "./scope.ts";
 import { diagnosticsOf, openEngine, runSession, type Engine } from "./session.ts";
 import { CONTRACT_VERSION } from "./version.ts";
@@ -245,8 +245,10 @@ function printConfigVerb(args: readonly string[], out: Writer, err: Writer, host
 }
 
 /**
- * Writes the compiler configuration of every project one run analyzes, one per
- * line, in discovery order, having read each project's diagnostics first.
+ * Writes the name of every project one run analyzes, one per line, having read each
+ * project's diagnostics first: the identifier the build matrix declares for it, or,
+ * where discovery derived the project, its configuration file's path below the
+ * target root.
  */
 function printProjectsVerb(
   args: readonly string[],
@@ -258,14 +260,16 @@ function printProjectsVerb(
   let engine: Engine | undefined;
   try {
     const options = readOptions(args);
+    const matrix = resolveMatrix(inputsOf(host, options));
     const scope = scopeOf(host, options);
     engine = openClient(false);
-    const discovered = discoverProjects(engine, host, scope);
+    const discovered = discoverProjects(engine, host, scope, matrix);
+    const ids = new Map(discovered.projects.map((project) => [project.configFile, project.id]));
     const failures: string[] = [];
     const { projects } = runSession(engine, discovered.configFiles, (project) => {
       const errors = diagnosticErrors(diagnosticsOf(project));
       failures.push(...errors.map(renderDiagnostic));
-      return project.configFile;
+      return ids.get(project.configFile) ?? project.configFile;
     });
     if (failures.length > 0) {
       for (const line of failures) {
@@ -274,8 +278,8 @@ function printProjectsVerb(
       err.write(`deadset-ts: ${String(failures.length)} error(s); no answer was produced\n`);
       return EXIT_FAILURE;
     }
-    for (const configFile of projects) {
-      out.write(`${configFile}\n`);
+    for (const id of projects) {
+      out.write(`${id}\n`);
     }
     return EXIT_CLEAN;
   } catch (error: unknown) {

package/src/schema.ts

@@ -8,7 +8,10 @@ import { ConfigError } from "./config.ts";
  *   holds no value of its own.
  * - `map` is an object whose member names the key list leaves open, its values
  *   scalars: the severity and provenance objects.
- * - `list` is an array whose entries are objects with declared members.
+ * - `list` is an array whose entries are objects with declared members. Where
+ *   the key list admits an entry in more than one shape, the members are every
+ *   shape's together, and which of them one entry may hold is the decoder's
+ *   refusal, not the walk's.
  * - `object` is one setting written as an object: its member names are declared
  *   and a source supplies the object whole.
  */
@@ -44,7 +47,7 @@ export const SCHEMA_ROOT: KeyNode = {
         consumer_tests: leaf,
         configurations: {
           kind: "list",
-          members: { id: leaf, os: leaf, arch: leaf, tags: leaf },
+          members: { id: leaf, os: leaf, arch: leaf, tags: leaf, project: leaf },
         },
         matrix: { kind: "section", members: { complete: leaf } },
         template_dirs: leaf,

package/src/sweep.ts

@@ -0,0 +1,230 @@
+/**
+ * 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, type Component } from "./components.ts";
+import { namesACaller, OUTSIDE, type Graph } from "./graph.ts";
+
+/** The liveness relation that decided a declaration, as a finding spells it. */
+export type Relation = "reference-counting" | "reachability";
+
+/**
+ * The run's reference mode, decided once by the composition and read by every stage
+ * that counts references.
+ */
+export interface Mode {
+  /**
+   * Counts no reference a test file made, under either relation. Every reference a root
+   * in a test file makes is such a reference, so nothing only a test reaches is live.
+   */
+  readonly production: boolean;
+}
+
+/** What one sweep runs over besides the graph. */
+export interface SweepInput {
+  /**
+   * The declarations a matched suppression names. A mark holds its declaration live
+   * under both relations and seeds reachability through every reference it makes, so
+   * nothing only a marked declaration references is dead.
+   */
+  readonly marked: readonly string[];
+  readonly mode: Mode;
+}
+
+/** One dead declaration, the relation that found it, and the counts a kind reads. */
+export interface Candidate {
+  readonly id: string;
+  /** The references a production file made to the declaration, whatever the mode counts. */
+  readonly productionRefs: number;
+  /** The references a test file made to it. */
+  readonly testRefs: number;
+  /**
+   * Reference counting where the mode counts no reference to the declaration, and
+   * reachability otherwise, so a declaration dead under both carries the stronger claim.
+   */
+  readonly relation: Relation;
+  /**
+   * Whether the test-of-dead-code rule admitted the declaration: a test declaration whose
+   * set of referenced production declarations is non-empty and wholly dead.
+   */
+  readonly testOfDeadCode: boolean;
+}
+
+/** One sweep's answer. */
+export interface SweepResult {
+  /**
+   * Per declaration, the relations that hold it live, reference counting first. A
+   * declaration neither holds live has no entry.
+   */
+  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[];
+}
+
+/**
+ * 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: 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.
+  const called = graph.symbols.map(() => false);
+  for (const root of graph.rooted) {
+    if (namesACaller(root.kind)) {
+      called[root.at] = true;
+    }
+  }
+
+  const counted = (at: number): number => {
+    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): readonly Relation[] => {
+    const relations: Relation[] = [];
+    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: Candidate[] = [];
+  const live = new Map<string, readonly Relation[]>();
+  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: Graph, marked: 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 => {
+    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: 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) {
+          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: Graph,
+  dead: boolean[],
+  marked: 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) {
+      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/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.1.0";
+export const CONTRACT_VERSION = "2.2.0";