@cplieger/deadset-ts 3.4.0 → 3.6.0

package/README.md

@@ -8,7 +8,7 @@ deadset-ts is a command-line analyzer for TypeScript and JavaScript projects. It
 
 deadset-ts is report-only. It never edits source, and it refuses any `--fix` flag.
 
-**Status: pre-release.** This version implements contract 3.1.0 and ships the analyzer's foundation: one compiler session per run over the projects `analysis.configurations` declares, in the order it lists them, each a compiler configuration file below the target, or, where it declares none, every `tsconfig` project discovered under the target (the explicit scope, every `tsconfig*.json`, each project's `references`), a fail-closed read of every project's diagnostics, configuration decoding against the contract's closed key list with `print-config` and its provenance, `print-projects`, the report-only guard, the symbol inventory of every declaration a project's own files hold down to its class and type members, the one-pass reference resolution over that inventory, which resolves each file's identifiers in batches ([batch-cap calibration](docs/batch-cap-calibration.md) is the measurement behind the batch size), and the root set `print-roots` prints. A root is a declaration the analysis keeps live without a reference: what a file exports when the manifest names it through `main`, `module`, `types`, `bin` or `exports`, or when `ts.entry_files` matches it; a library target's published API; the configuration, setup and test files of Vitest, Stryker and Playwright, the flat configuration of ESLint, and a worker or service worker a call addresses by a string literal; and every declaration a `roots.patterns` entry names. An entry that names nothing is reported as `DS1704` and fails the run. The entry-point conventions of other tools are not read, and `DECLINED_CONVENTIONS` lists each one with the reason. Seven exemption classes hold a declaration back from the sweep, and `print-retained` lists what each one held back: `interface-satisfaction`, a member an interface requires of a class whose value reaches that interface; `decorator`, a decorated member and every member of a decorated class; `injection-container`, a decorated property of a class a dependency-injection container constructs, being a class passed to a call `ts.injection_registrations` names or one a parameter of whose constructor carries a decorator; `framework-lifecycle`, a member a `ts.lifecycle_contracts` entry lists, on a class that is the entry's component by a decorator or a call the entry names or by extending a class it names; `serialization-contract`, the properties of a class whose values reach `JSON.stringify` or a declaration `ts.serializers` names, and those and its `toJSON` and `toString` where a value is passed to an `unknown` or `any` parameter of a function outside the analysis; and, at the lowest confidence, `template-field`, a member an action of a template under `analysis.template_dirs` names, and `reflective-lookup`, a member a literal key of an element access or of `Reflect.get`, `Reflect.set` or `Reflect.has` names. None of them holds back a `#private` member. The analysis is reached through the command, and through `run()` for a caller that runs the command in-process; no other verb reports findings yet, so `analyze`, `explain` and `describe` exit with a usage message. The one runtime dependency is the `typescript` package at exactly 7.0.2, installed under the `@typescript/native` name until TypeScript 7.1 ships a compiler API the tooling can share.
+**Status: pre-release.** This version implements contract 3.2.0 and ships the analyzer's foundation: one compiler session per run over the projects `analysis.configurations` declares, in the order it lists them, each a compiler configuration file below the target, or, where it declares none, every `tsconfig` project discovered under the target (the explicit scope, every `tsconfig*.json`, each project's `references`), a fail-closed read of every project's diagnostics, configuration decoding against the contract's closed key list with `print-config` and its provenance, `print-projects`, the report-only guard, the symbol inventory of every declaration a project's own files hold down to its class and type members, the one-pass reference resolution over that inventory, which resolves each file's identifiers in batches ([batch-cap calibration](docs/batch-cap-calibration.md) is the measurement behind the batch size), and the root set `print-roots` prints. A root is a declaration the analysis keeps live without a reference: what a file exports when the manifest names it through `main`, `module`, `types`, `bin` or `exports`, or when `ts.entry_files` matches it; a library target's published API; the configuration, setup and test files of Vitest, Stryker and Playwright, the flat configuration of ESLint, and a worker or service worker a call addresses by a string literal; and every declaration a `roots.patterns` entry names. An entry that names nothing is reported as `DS1704` and fails the run. The entry-point conventions of other tools are not read, and `DECLINED_CONVENTIONS` lists each one with the reason. Seven exemption classes hold a declaration back from the sweep, and `print-retained` lists what each one held back: `interface-satisfaction`, a member an interface requires of a class whose value reaches that interface; `decorator`, a decorated member and every member of a decorated class; `injection-container`, a decorated property of a class a dependency-injection container constructs, being a class passed to a call `ts.injection_registrations` names or one a parameter of whose constructor carries a decorator; `framework-lifecycle`, a member a `ts.lifecycle_contracts` entry lists, on a class that is the entry's component by a decorator or a call the entry names or by extending a class it names; `serialization-contract`, the properties of a class whose values reach `JSON.stringify` or a declaration `ts.serializers` names, and those and its `toJSON` and `toString` where a value is passed to an `unknown` or `any` parameter of a function outside the analysis; and, at the lowest confidence, `template-field`, a member an action of a template under `analysis.template_dirs` names, and `reflective-lookup`, a member a literal key of an element access or of `Reflect.get`, `Reflect.set` or `Reflect.has` names. None of them holds back a `#private` member. The analysis is reached through the command, and through `run()` for a caller that runs the command in-process; no other verb reports findings yet, so `analyze`, `explain` and `describe` exit with a usage message. The one runtime dependency is the `typescript` package at exactly 7.0.2, installed under the `@typescript/native` name until TypeScript 7.1 ships a compiler API the tooling can share.
 
 ## Install
 

package/dist/src/analysis.js

@@ -8,9 +8,14 @@
  * project's checker, and that holds only for views the session itself hands out.
  */
 import { decorator } from "./decorator.js";
+import { dependenciesOf, projectNeeds } from "./dependencies.js";
+import { deprecatedDeclarations } from "./deprecation.js";
 import { diagnosticErrors, discoverProjects, DiscoveryError } from "./discover.js";
+import { enumGroup } from "./enum-group.js";
 import { computeExemptions, disabledClasses, exemptionsOf, retainedIn, } from "./exempt.js";
+import { heldByInclusion, sourceTree } from "./file-facts.js";
 import { frameworkLifecycle } from "./framework-lifecycle.js";
+import { implementations, mergeImplementations } from "./implementations.js";
 import { injectionContainer } from "./injection-container.js";
 import { interfaceSatisfaction } from "./interface-satisfaction.js";
 import { inventory } from "./inventory.js";
@@ -23,6 +28,7 @@ import { references } from "./references.js";
 import { roots, unmatchedEverywhere, unmatchedRoots } from "./roots.js";
 import { serializationContract } from "./serialization-contract.js";
 import { diagnosticsOf, runSession } from "./session.js";
+import { accessorsOf, storesOf } from "./stores.js";
 import { readTemplates, templateField } from "./template-field.js";
 /** The setting whose source decides where a finding about a configured root sits. */
 const ROOTS_SETTING = "roots.patterns";
@@ -128,6 +134,7 @@ export function runRoots(engine, host, scope, config, provenance) {
 /** The exemption classes this analyzer detects, each by its detector; any other retains nothing. */
 const DETECTORS = new Map([
     ["interface-satisfaction", interfaceSatisfaction],
+    ["enum-group", enumGroup],
     ["template-field", templateField],
     ["reflective-lookup", reflectiveLookup],
     ["decorator", decorator],
@@ -136,23 +143,17 @@ const DETECTORS = new Map([
     ["serialization-contract", serializationContract],
 ]);
 /**
- * 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(engine, host, scope, config, input, detectors = DETECTORS) {
+function sweepRun(engine, host, scope, config, input, detectors, 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,
         });
@@ -168,9 +169,64 @@ export function runSweep(engine, host, scope, config, input, detectors = DETECTO
             mode: input.mode,
             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 = { ...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 = { ...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, host, scope, config, input, detectors = DETECTORS) {
+    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, host, scope, config, input, detectors = DETECTORS) {
+    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/dist/src/components.js

@@ -1,30 +1,34 @@
 /**
- * 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 { OUTSIDE } from "./graph.js";
 /** The name every component identifier this analyzer mints starts with. */
 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) {
+    return `${ANALYZER}/c-${String(place).padStart(ID_DIGITS, "0")}`;
+}
 /** The index of a declaration the component walk has not reached. */
 const UNVISITED = -1;
-/** 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, cascade) {
     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, dead, testOfDeadCode) {
     const { at, adjacent } = deadSubgraph(graph, dead, testOfDeadCode);
@@ -32,25 +36,21 @@ export function componentsOf(graph, dead, testOfDeadCode) {
         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) => 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])),
         };
     });
 }
@@ -127,10 +127,9 @@ function deadSubgraph(graph, dead, testOfDeadCode) {
     return { at, adjacent };
 }
 /**
- * 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) {
     const index = adjacent.map(() => UNVISITED);
@@ -193,97 +192,57 @@ function connected(adjacent) {
     });
     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(adjacent, componentOf, count) {
-    const edges = Array.from({ length: count }, () => []);
-    const into = Array.from({ length: count }, () => 0);
-    const seen = new Set();
+/** Per cycle, whether a dead declaration outside it references one of its members. */
+function referencedCycles(adjacent, componentOf, count) {
+    const referenced = Array.from({ length: count }, () => false);
     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, componentOf) {
-    const referenced = adjacent.map(() => 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;
             }
         }
     });
     return referenced;
 }
 /**
- * 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, members) {
-    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, members, into) {
-    // 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();
-    const owners = edges.map(() => 0);
-    edges.forEach((_targets, root) => {
-        if (into[root] !== 0) {
-            return;
-        }
-        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);
-                }
-            }
-        }
-        reach.set(root, reached);
-        for (const component of reached) {
-            owners[component] = (owners[component] ?? 0) + 1;
+function joined(adjacent) {
+    const leader = adjacent.map((_edges, position) => position);
+    const find = (position) => {
+        let top = position;
+        while ((leader[top] ?? top) !== top) {
+            top = leader[top] ?? top;
+        }
+        // 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;
+        }
+        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();
+    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/dist/src/config.js

@@ -34,6 +34,12 @@ export function defaultConfig() {
             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: [],