@cplieger/deadset-ts 3.4.0 → 3.6.0

package/src/analysis.ts

@@ -11,7 +11,10 @@
 import type { Diagnostic } from "@typescript/native/unstable/sync";
 import type { Config, Provenance } from "./config.ts";
 import { decorator } from "./decorator.ts";
+import { dependenciesOf, projectNeeds } from "./dependencies.ts";
+import { deprecatedDeclarations } from "./deprecation.ts";
 import { diagnosticErrors, discoverProjects, DiscoveryError } from "./discover.ts";
+import { enumGroup } from "./enum-group.ts";
 import {
   computeExemptions,
   disabledClasses,
@@ -21,9 +24,12 @@ import {
   type Detectors,
 } from "./exempt.ts";
 import type { TSExemptionClass } from "./exempt-classes.ts";
+import { heldByInclusion, sourceTree } from "./file-facts.ts";
 import type { Finding } from "./finding.ts";
+import type { EmitterInput } from "./findings/emitter.ts";
 import { frameworkLifecycle } from "./framework-lifecycle.ts";
 import type { Host } from "./host.ts";
+import { implementations, mergeImplementations } from "./implementations.ts";
 import { injectionContainer } from "./injection-container.ts";
 import { interfaceSatisfaction } from "./interface-satisfaction.ts";
 import { inventory, type Inventory } from "./inventory.ts";
@@ -37,6 +43,7 @@ import { roots, unmatchedEverywhere, unmatchedRoots, type RootKind, type Roots }
 import type { Scope } from "./scope.ts";
 import { serializationContract } from "./serialization-contract.ts";
 import { diagnosticsOf, runSession, type Engine, type ProjectView } from "./session.ts";
+import { accessorsOf, storesOf } from "./stores.ts";
 import type { Exemption, SweepInput } from "./sweep.ts";
 import { readTemplates, templateField } from "./template-field.ts";
 
@@ -222,6 +229,7 @@ export interface RunSweep {
 /** The exemption classes this analyzer detects, each by its detector; any other retains nothing. */
 const DETECTORS: Detectors = new Map<TSExemptionClass, Detector>([
   ["interface-satisfaction", interfaceSatisfaction],
+  ["enum-group", enumGroup],
   ["template-field", templateField],
   ["reflective-lookup", reflectiveLookup],
   ["decorator", decorator],
@@ -230,31 +238,40 @@ const DETECTORS: Detectors = new Map<TSExemptionClass, Detector>([
   ["serialization-contract", serializationContract],
 ]);
 
+/** What the sweep of one run reads of each project, beside what a caller's stage adds. */
+interface SweptProject<Extra> {
+  readonly configured: Configured;
+  readonly exempt: readonly Exemption[];
+  readonly extra: Extra;
+}
+
+/** The run's sweep, the exemption records it was swept with, and each project's extra answer. */
+interface SweptRun<Extra> {
+  readonly swept: RunSweep;
+  readonly exempt: readonly Exemption[];
+  readonly projects: readonly SweptProject<Extra>[];
+}
+
 /**
- * Sweeps the run the scope and the configuration describe. Each project's references
- * and exemptions are read against its own inventory while its view is open; the
- * projects then merge into one matrix in the run's order, which is swept under the
- * caller's marks and mode with the exemptions every project found. A record found in
- * one configuration holds in every configuration that holds its declaration, because
- * an exemption is evidence of a use the analysis cannot see and a use in one
- * configuration is a use. A project that carries an error ends the run before any
- * project is swept.
+ * Sweeps the run, reading each project's references and exemptions, and `extra`'s
+ * answer, while the project's view is open.
  */
-export function runSweep(
+function sweepRun<Extra>(
   engine: Engine,
   host: Host,
   scope: Scope,
   config: Config,
   input: Pick<SweepInput, "marked" | "mode">,
-  detectors: Detectors = DETECTORS,
-): RunSweep {
+  detectors: Detectors,
+  extra: <Brand>(project: ProjectView<Brand>, read: ProjectRead) => Extra,
+): SweptRun<Extra> {
   const targetRoot = scope.target.path;
   const disabled = disabledClasses(config);
   const templates = disabled.has("template-field")
     ? { delimiters: config.analysis.templateDelimiters, files: [] }
     : readTemplates(host, targetRoot, config.analysis);
   const consumers = scope.consumers.map((consumer) => consumer.path);
-  const read = readProjects(engine, host, scope, config, (project, projectRead) => {
+  const projects = readProjects(engine, host, scope, config, (project, projectRead) => {
     const resolved = references(project, projectRead.held, targetRoot, {
       testFiles: config.ts.testFiles,
     });
@@ -274,9 +291,89 @@ export function runSweep(
         testFiles: new Set(resolved.testFilePaths),
       },
     );
-    return { configured, exempt };
+    return { configured, exempt, extra: extra(project, projectRead) };
   });
-  const matrix = matrixOf(read.map((one) => one.configured));
-  const swept: SweepInput = { ...input, exempt: exemptionsOf(read.flatMap((one) => one.exempt)) };
-  return { matrix, sweep: sweepMatrix(matrix, swept), retained: retainedIn(matrix, swept) };
+  const matrix = matrixOf(projects.map((one) => one.configured));
+  const exempt = exemptionsOf(projects.flatMap((one) => one.exempt));
+  const swept: SweepInput = { ...input, exempt };
+  return {
+    swept: { matrix, sweep: sweepMatrix(matrix, swept), retained: retainedIn(matrix, swept) },
+    exempt,
+    projects,
+  };
+}
+
+/**
+ * Sweeps the run the scope and the configuration describe. Each project's references
+ * and exemptions are read against its own inventory while its view is open; the
+ * projects then merge into one matrix in the run's order, which is swept under the
+ * caller's marks and mode with the exemptions every project found. A record found in
+ * one configuration holds in every configuration that holds its declaration, because
+ * an exemption is evidence of a use the analysis cannot see and a use in one
+ * configuration is a use. 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: Pick<SweepInput, "marked" | "mode">,
+  detectors: Detectors = DETECTORS,
+): RunSweep {
+  return sweepRun(engine, host, scope, config, input, detectors, () => undefined).swept;
+}
+
+/**
+ * What every emitter reads of the run the scope and the configuration describe: the
+ * run's sweep, and the facts beside it each kind family reads, every per-project one
+ * read in the same session as the sweep. The run loads no consumer and reads no
+ * declared cross-language edge, so its boundary names neither.
+ */
+export function runEmitterInput(
+  engine: Engine,
+  host: Host,
+  scope: Scope,
+  config: Config,
+  input: Pick<SweepInput, "marked" | "mode">,
+  detectors: Detectors = DETECTORS,
+): EmitterInput {
+  const targetRoot = scope.target.path;
+  const run = sweepRun(engine, host, scope, config, input, detectors, (project, read) => ({
+    deprecated: deprecatedDeclarations(project, read.held),
+    accessors: accessorsOf(project, read.held),
+    needs: projectNeeds(project, read.held, host),
+    implementations: implementations(project, read.held),
+    heldByInclusion: heldByInclusion(project, targetRoot),
+  }));
+  const { swept, projects } = run;
+  return {
+    config,
+    swept,
+    deprecated: new Set(projects.flatMap((one) => one.extra.deprecated)),
+    stores: storesOf(
+      projects.map((one) => ({
+        references: one.configured.references,
+        accessors: one.extra.accessors,
+      })),
+      run.exempt,
+      input.mode,
+    ),
+    dependencies: dependenciesOf(
+      host,
+      targetRoot,
+      projects.map((one) => one.extra.needs),
+      swept.sweep.candidates.map((candidate) => candidate.id),
+    ),
+    implementations: mergeImplementations(projects.map((one) => one.extra.implementations)),
+    files: {
+      tree: sourceTree(host, targetRoot),
+      heldByInclusion: new Set(projects.flatMap((one) => one.extra.heldByInclusion)),
+    },
+    boundary: {
+      consumers: { declared: scope.consumers.map((consumer) => consumer.id), loaded: [] },
+      encapsulated: readManifest(host, targetRoot).declaresExports,
+      edges: [],
+    },
+  };
 }

package/src/components.ts

@@ -1,7 +1,7 @@
 /**
- * The dead components of one graph: the strongly connected components of the subgraph
- * the dead declarations induce, ordered so a report is worked from the top down, each
- * with the root members a deletion starts at and what falls with it.
+ * The dead components of one graph. A component is a set of dead declarations one
+ * deletion removes together: its root members, which are where the deletion starts,
+ * and every dead declaration that falls with them, being dead only through them.
  */
 
 import type { Cascade } from "./config.ts";
@@ -14,28 +14,30 @@ const ANALYZER = "deadset-ts";
 /** The fewest digits a component identifier's number is written with. */
 const ID_DIGITS = 4;
 
+/** The identifier of the component at one place of the run's order, counted from one. */
+export function componentId(place: number): string {
+  return `${ANALYZER}/c-${String(place).padStart(ID_DIGITS, "0")}`;
+}
+
 /** The index of a declaration the component walk has not reached. */
 const UNVISITED = -1;
 
-/** One dead component and its place in the acyclic graph over the components. */
+/** One dead component. */
 export interface Component {
   /** The analyzer's name, a solidus, and `c-` followed by the component's place in the order. */
   readonly id: string;
-  /** The component's declarations, by site. A dead member of a dead container is one of them. */
-  readonly members: readonly string[];
   /**
-   * The members no other dead component references and whose container is not dead,
-   * which are where a deletion starts. A cycle has as many as it has members no dead
-   * component outside it references.
+   * The component's declarations by site: its root members and every dead declaration
+   * that falls with them. A dead member of a dead container is one of them.
    */
-  readonly roots: readonly string[];
+  readonly members: readonly string[];
   /**
-   * What one deletion of the component removes: its members, and every dead declaration
-   * only this component reaches. A dead declaration two components both reach falls with
-   * neither and is counted by its own component.
+   * The root members, by site. A root member is a member of a cycle no dead declaration
+   * outside the cycle references, whose container is not dead; every member of such a
+   * cycle with a live container is one, so a component has at least one.
    */
-  readonly falls: readonly string[];
-  /** The source lines the deletion removes: the distinct lines {@link Component.falls} spans. */
+  readonly roots: readonly string[];
+  /** The source lines one deletion of the component removes: the distinct lines its members span. */
   readonly deletableLines: number;
 }
 
@@ -48,22 +50,22 @@ export interface Listing {
   readonly deletableLines: number;
 }
 
-/** What a report carries for one component: its roots and what falls, and its members in full. */
+/** What a report carries for one component: its roots and counts, and its members in full. */
 export function listing(component: Component, cascade: Cascade): Listing {
   return {
     roots: component.roots,
     members: cascade === "full" ? component.members : [],
-    symbolCount: component.falls.length,
+    symbolCount: component.members.length,
     deletableLines: component.deletableLines,
   };
 }
 
 /**
- * Groups the declarations `dead` marks into components and orders them so each precedes
- * every component it reaches, two that neither reaches ordered by their first member's
- * site. `dead` and `testOfDeadCode` hold one flag per declaration of the graph; the dead
- * set arrives rather than being read from a sweep, so a set several sweeps intersect is
- * grouped over this graph's edges the same way.
+ * Groups the declarations `dead` marks into components, ordered by their first member's
+ * site; `dead` and `testOfDeadCode` hold one flag per declaration of the graph. Root
+ * members sit on the cycles no other cycle references. A cycle two roots both reach is
+ * dead only through both, so a component is a weakly connected part of the dead
+ * subgraph: no dead declaration of one references a declaration of another.
  */
 export function componentsOf(
   graph: Graph,
@@ -75,26 +77,22 @@ export function componentsOf(
     return [];
   }
   const { componentOf, members } = connected(adjacent);
-  const { edges, into } = condense(adjacent, componentOf, members.length);
-  const falls = fallSets(edges, members, into);
-  const outsideReference = externallyReferenced(adjacent, componentOf);
+  const referenced = referencedCycles(adjacent, componentOf, members.length);
+  const groups = joined(adjacent);
   const idOf = (position: number): string => graph.symbols[at[position] ?? 0]?.id ?? "";
 
-  return order(edges, members).map((group, place) => {
-    const own = members[group] ?? [];
-    const roots = own.filter((position) => {
-      // A dead member of a dead container is never a root: the container is where the
-      // deletion starts and the member falls with it.
+  return groups.map((group, place) => {
+    const roots = group.filter((position) => {
+      // A dead member's dead container is on the member's own cycle, and the container
+      // is where the deletion starts.
       const container = graph.parent[at[position] ?? 0] ?? OUTSIDE;
-      return outsideReference[position] !== true && dead[container] !== true;
+      return referenced[componentOf[position] ?? 0] !== true && dead[container] !== true;
     });
-    const fallen = falls[group] ?? [];
     return {
-      id: `${ANALYZER}/c-${String(place + 1).padStart(ID_DIGITS, "0")}`,
-      members: own.map(idOf),
+      id: componentId(place + 1),
+      members: group.map(idOf),
       roots: roots.map(idOf),
-      falls: fallen.map(idOf),
-      deletableLines: linesSpanned(fallen.map((position) => graph.symbols[at[position] ?? 0])),
+      deletableLines: linesSpanned(group.map((position) => graph.symbols[at[position] ?? 0])),
     };
   });
 }
@@ -185,10 +183,9 @@ interface Frame {
 }
 
 /**
- * Each declaration's component and each component's members by site, by Tarjan's
+ * Each declaration's cycle and each cycle's members by site, by Tarjan's
  * algorithm in one pass. The walk keeps its own stack of frames, so a chain of any length
- * is walked without growing the call stack. Components are closed in an order in which
- * each follows every component it reaches.
+ * is walked without growing the call stack.
  */
 function connected(adjacent: readonly (readonly number[])[]): {
   readonly componentOf: readonly number[];
@@ -257,45 +254,18 @@ function connected(adjacent: readonly (readonly number[])[]): {
   return { componentOf, members };
 }
 
-/**
- * Per component, the components it reaches in one step, and how many components reach
- * it, each pair counted once. An edge inside a component is not an edge between two, so
- * the result is acyclic.
- */
-function condense(
+/** Per cycle, whether a dead declaration outside it references one of its members. */
+function referencedCycles(
   adjacent: readonly (readonly number[])[],
   componentOf: readonly number[],
   count: number,
-): { readonly edges: readonly (readonly number[])[]; readonly into: readonly number[] } {
-  const edges: number[][] = Array.from({ length: count }, () => []);
-  const into = Array.from({ length: count }, () => 0);
-  const seen = new Set<string>();
-  adjacent.forEach((targets, from) => {
-    for (const to of targets) {
-      const a = componentOf[from] ?? 0;
-      const b = componentOf[to] ?? 0;
-      const pair = `${String(a)}>${String(b)}`;
-      if (a === b || seen.has(pair)) {
-        continue;
-      }
-      seen.add(pair);
-      edges[a]?.push(b);
-      into[b] = (into[b] ?? 0) + 1;
-    }
-  });
-  return { edges, into };
-}
-
-/** Per dead declaration, whether a dead component other than its own references it. */
-function externallyReferenced(
-  adjacent: readonly (readonly number[])[],
-  componentOf: readonly number[],
 ): readonly boolean[] {
-  const referenced = adjacent.map(() => false);
+  const referenced = Array.from({ length: count }, () => false);
   adjacent.forEach((targets, from) => {
     for (const to of targets) {
-      if (componentOf[from] !== componentOf[to]) {
-        referenced[to] = true;
+      const cycle = componentOf[to] ?? 0;
+      if (componentOf[from] !== cycle) {
+        referenced[cycle] = true;
       }
     }
   });
@@ -303,70 +273,42 @@ function externallyReferenced(
 }
 
 /**
- * The components in the order a report is worked in. Tarjan closes each component after
- * every one it reaches, so reading the closing order backwards is a topological order,
- * and one pass over it gives each component its depth below the roots.
- */
-function order(
-  edges: readonly (readonly number[])[],
-  members: readonly (readonly number[])[],
-): readonly number[] {
-  const sequence = edges.map((_targets, component) => component).reverse();
-  const depth = edges.map(() => 0);
-  for (const from of sequence) {
-    for (const to of edges[from] ?? []) {
-      depth[to] = Math.max(depth[to] ?? 0, (depth[from] ?? 0) + 1);
-    }
-  }
-  return sequence.sort(
-    (a, b) => (depth[a] ?? 0) - (depth[b] ?? 0) || (members[a]?.[0] ?? 0) - (members[b]?.[0] ?? 0),
-  );
-}
-
-/**
- * Per component, the dead declarations one deletion of it removes. A root of the
- * condensation carries its members and every component only it reaches; any other
- * component carries its own members alone, because what it reaches is reached through a
- * root above it as well.
+ * The weakly connected parts of the dead subgraph, each its positions in ascending
+ * order, ordered by their first position. Positions follow the graph's declaration
+ * order, so a part's first position is its first member's site.
  */
-function fallSets(
-  edges: readonly (readonly number[])[],
-  members: readonly (readonly number[])[],
-  into: readonly number[],
-): readonly (readonly number[])[] {
-  // Each root's walk stamps what it reaches with the root's own number, so the walks
-  // share one array rather than allocating one per root.
-  const stamp = edges.map(() => UNVISITED);
-  const reach = new Map<number, readonly number[]>();
-  const owners = edges.map(() => 0);
-  edges.forEach((_targets, root) => {
-    if (into[root] !== 0) {
-      return;
+function joined(adjacent: readonly (readonly number[])[]): readonly (readonly number[])[] {
+  const leader = adjacent.map((_edges, position) => position);
+  const find = (position: number): number => {
+    let top = position;
+    while ((leader[top] ?? top) !== top) {
+      top = leader[top] ?? top;
     }
-    const reached = [root];
-    stamp[root] = root;
-    // An array's iterator reads its length at every step, so what a step pushes is
-    // walked in the same loop.
-    for (const at of reached) {
-      for (const to of edges[at] ?? []) {
-        if (stamp[to] !== root) {
-          stamp[to] = root;
-          reached.push(to);
-        }
-      }
+    // Every position on the walk points at the top afterwards, so a later find is short.
+    for (let step = position; step !== top;) {
+      const next = leader[step] ?? top;
+      leader[step] = top;
+      step = next;
     }
-    reach.set(root, reached);
-    for (const component of reached) {
-      owners[component] = (owners[component] ?? 0) + 1;
+    return top;
+  };
+  adjacent.forEach((targets, from) => {
+    for (const to of targets) {
+      const a = find(from);
+      const b = find(to);
+      // The smaller position leads, so a part's leader is its first position.
+      leader[Math.max(a, b)] = Math.min(a, b);
     }
   });
-  return members.map((own, component) => {
-    const set = [...own];
-    for (const other of reach.get(component) ?? []) {
-      if (other !== component && owners[other] === 1) {
-        set.push(...(members[other] ?? []));
-      }
+  const parts = new Map<number, number[]>();
+  adjacent.forEach((_edges, position) => {
+    const top = find(position);
+    const part = parts.get(top);
+    if (part === undefined) {
+      parts.set(top, [position]);
+    } else {
+      part.push(position);
     }
-    return set.sort((a, b) => a - b);
   });
+  return [...parts.values()];
 }

package/src/config.ts

@@ -122,6 +122,34 @@ export interface LifecycleContract {
   readonly members: readonly string[];
 }
 
+/**
+ * One analyzer the orchestrator may run, in exactly one of two shapes: an installed
+ * analyzer, named by its command alone, or an acquirable one, which also names the
+ * artifact acquisition fetches and verifies. This analyzer validates and prints the
+ * list and runs nothing from it.
+ */
+export type Provider =
+  | {
+      readonly shape: "installed";
+      readonly name: string;
+      readonly languages: readonly Language[];
+      readonly command: string;
+    }
+  | {
+      readonly shape: "acquirable";
+      readonly name: string;
+      readonly languages: readonly Language[];
+      readonly command: string;
+      readonly source: string;
+      readonly version: string;
+      readonly digest: string;
+    };
+
+/** The analyzers the orchestrator runs. */
+export interface Providers {
+  readonly analyzers: readonly Provider[];
+}
+
 /** The section the TypeScript analyzer owns. */
 export interface TSSection {
   readonly testFiles: readonly string[];
@@ -152,6 +180,7 @@ export interface Config {
   readonly severity: ReadonlyMap<string, Severity>;
   readonly exemptionsDisabled: readonly string[];
   readonly reporters: Reporters;
+  readonly providers: Providers;
   readonly ts: TSSection;
 }
 
@@ -184,6 +213,12 @@ export function defaultConfig(): Config {
       maxFindings: 0,
       failOn: "deny",
     },
+    providers: {
+      analyzers: [
+        { shape: "installed", name: "deadset-go", languages: ["go"], command: "deadset-go" },
+        { shape: "installed", name: "deadset-ts", languages: ["ts"], command: "deadset-ts" },
+      ],
+    },
     ts: {
       testFiles: ["**/*.test.{ts,tsx,mts,cts}"],
       entryFiles: [],
@@ -246,8 +281,8 @@ export type ErrorKind =
    */
   | "malformed"
   /**
-   * A key the closed key list does not declare, or a severity key naming a kind
-   * whose severity the Contract fixes.
+   * A key the closed key list does not declare, or a severity key naming no live
+   * kind or a kind whose severity the Contract fixes.
    */
   | "unimplemented-key"
   /** A resolved configuration no source supplied a target kind for. */