@cplieger/deadset-ts 7.0.0-dev.1 → 7.0.0-dev.3

package/dist/src/analysis.js

@@ -1,11 +1,9 @@
 /**
- * One run's passes, composed: the projects discovery names, opened in one snapshot
- * of one client, each read through the stages in the order they depend on each
- * other, and the per-project answers merged into the answer for the run.
- *
- * The stages take a project's view, which only this composition makes: a view
- * carries a project's identity in its type so a handle cannot cross to another
- * project's checker, and that holds only for views the session itself hands out.
+ * One run's passes, composed: the projects discovery names, opened in one snapshot of one
+ * client, each read through the stages in dependency order, and the per-project answers
+ * merged into the run's. The stages take a project's view, which only this composition
+ * makes: a view carries a project's identity in its type so a handle cannot cross to
+ * another project's checker, which holds only for views the session hands out.
  */
 import { lineOf, readComponent } from "./component-files.js";
 import { consumerLoads, consumerReferences, moduleIdentity, } from "./consumers.js";
@@ -18,12 +16,13 @@ import { conventionFailuresFor, generatedFiles, readConventions, } from "./conve
 import { readEdgeSides } from "./edges.js";
 import { enumGroup } from "./enum-group.js";
 import { generatedFile, generatedFilesOf } from "./generated-file.js";
+import { inOperandNames } from "./in-operands.js";
 import { sourceFilesOf } from "./source-files.js";
 import { evidenceRecords, heldRecords, disabledClasses, exemptionsOf, holdingWhile, isUnansweredRecord, retainedIn, } from "./exempt.js";
 import { heldByInclusion, sourcePaths, sourceTree } from "./file-facts.js";
 import { globExpression } from "./glob.js";
 import { findingsPass, recordedFindings, rowKey } from "./findings-pass.js";
-import { NO_SELF_CHECK, unmatchedRootFindings, } from "./findings/self-check.js";
+import { unmatchedRootFindings } from "./findings/self-check.js";
 import { frameworkLifecycle } from "./framework-lifecycle.js";
 import { implementations, mergeImplementations } from "./implementations.js";
 import { injectionContainer } from "./injection-container.js";
@@ -38,12 +37,12 @@ import { SetupError, setupLine } from "./setup-failure.js";
 import { pathsOf, readErrors, skippedRoots, skippedUnits, } from "./type-errors.js";
 import { reflectiveLookup } from "./reflective-lookup.js";
 import { references, testFileRulesOf } from "./references.js";
-import { roots, unmatchedEverywhere } from "./roots.js";
+import { roots, unmatchedEverywhere, } from "./roots.js";
 import { serializationContract } from "./serialization-contract.js";
 import { outsideTestReferences, testFilesAt } from "./outside-tests.js";
 import { joinedTestFiles, withJoinedTests } from "./test-joins.js";
 import { supportReferences, testSupportFiles } from "./test-support.js";
-import { diagnosticsOf, ownedAs, runSession } from "./session.js";
+import { diagnosticsOf, ownedAs, runSession, } from "./session.js";
 import { accessorsOf, storesOf } from "./stores.js";
 import { isPartKind } from "./suppress.js";
 import { bindRows, readBaseline, readIgnoreFile } from "./suppress-file.js";
@@ -75,21 +74,47 @@ function compare(a, b) {
 }
 /**
  * The manifests the analysis reads, each once: the target's own, then every workspace
- * member's below the target root.
+ * member's and every nested package's below the target root.
  */
-function conventionManifests(host, targetRoot, memberDirs) {
+function conventionManifests(host, targetRoot, memberDirs, nestedDirs) {
     const found = new Map();
     if (host.kindOf(joinPath(targetRoot, "package.json")) === "file") {
         found.set(targetRoot, { dir: targetRoot, path: "package.json" });
     }
-    for (const dir of memberDirs) {
-        const below = relativePath(targetRoot, dir);
-        if (below !== undefined && !found.has(dir)) {
-            found.set(dir, { dir, path: `${below}/package.json` });
+    for (const [dirs, nested] of [
+        [memberDirs, false],
+        [nestedDirs, true],
+    ]) {
+        for (const dir of dirs) {
+            const below = relativePath(targetRoot, dir);
+            if (below !== undefined && !found.has(dir)) {
+                found.set(dir, { dir, path: `${below}/package.json`, nested });
+            }
         }
     }
     return [...found.values()];
 }
+/**
+ * The nested packages of a run: each directory below the target root, in no `node_modules`
+ * directory and none of `known`, that holds a `package.json` and lies at or above one of
+ * `files`, the program's source files and the compiler configuration files, in path order.
+ */
+function nestedPackageDirs(host, targetRoot, files, known) {
+    const seen = new Set();
+    const found = [];
+    for (const file of files) {
+        for (let dir = dirnamePath(file); dir !== targetRoot && !seen.has(dir) && relativePath(targetRoot, dir) !== undefined; dir = dirnamePath(dir)) {
+            seen.add(dir);
+            const below = relativePath(targetRoot, dir) ?? "";
+            if (!below.split("/").includes("node_modules") &&
+                !known.has(dir) &&
+                host.kindOf(joinPath(dir, "package.json")) === "file") {
+                found.push(dir);
+            }
+        }
+    }
+    return found.sort(compare);
+}
 /**
  * Reads every project the scope discovers, and each declared consumer's, in one snapshot,
  * each checked for errors first. `stage` is handed a target project and enumerates and roots
@@ -101,26 +126,41 @@ function conventionManifests(host, targetRoot, memberDirs) {
 function readProjects(engine, host, scope, config, stage) {
     const targetRoot = scope.target.path;
     const discovered = discoverProjects(engine, host, scope, config.analysis.configurations);
+    if (discovered.configFiles.length === 0 && discovered.notBuilt.length === 0) {
+        throw new DiscoveryError(`${targetRoot} holds no compiler configuration, so the run holds no program`, []);
+    }
     const ids = new Map(discovered.projects.map((project) => [project.configFile, project.id]));
     const loads = consumerLoads(engine, host, scope, discovered.configFiles);
     const consumerOf = new Map(loads.flatMap((load) => load.configFiles.map((configFile) => [configFile, load.consumer])));
     const absoluteRoot = resolvePath(host.workingDirectory(), targetRoot);
     const workspace = workspaceRun(engine, host, absoluteRoot, discovered.configFiles, readManifest(host, targetRoot));
-    const conventions = readConventions(host, (fileName, text) => engine.parseSourceFile(fileName, text), conventionManifests(host, absoluteRoot, workspace?.memberDirs ?? []), config.ts.disabledConventions);
-    const options = {
-        host,
-        manifest: workspace?.manifest ?? readManifest(host, targetRoot),
-        otherPackages: [
-            ...(workspace?.entries ?? []),
-            ...packageEntries(host, normalizePath(absoluteRoot), discovered.configFiles, new Set(workspace?.memberDirs ?? [])),
-        ],
-        patterns: config.rootPatterns,
-        entryFiles: config.ts.entryFiles,
-        conventions,
-        testFiles: config.ts.testFiles,
-        parse: (fileName, text) => engine.parseSourceFile(fileName, text),
-        publishedAPI: config.targetKind === "library",
-        publishedMembers: new Set((workspace?.entries ?? []).filter((entry) => entry.published).map((entry) => entry.dir)),
+    const parse = (fileName, text) => engine.parseSourceFile(fileName, text);
+    const memberDirs = workspace?.memberDirs ?? [];
+    // The nested packages are known only once every program is open, and every visit reads
+    // the conventions and options they decide, so both are set in the session's first step.
+    let nestedDirs = [];
+    let conventions = readConventions(host, parse, [], config.ts.disabledConventions);
+    let options;
+    const readManifests = (opened) => {
+        nestedDirs = nestedPackageDirs(host, normalizePath(absoluteRoot), opened
+            .filter((one) => !consumerOf.has(one.configFile))
+            .flatMap((one) => [one.configFile, ...one.fileNames()]), new Set(memberDirs));
+        conventions = readConventions(host, parse, conventionManifests(host, absoluteRoot, memberDirs, nestedDirs), config.ts.disabledConventions);
+        options = {
+            host,
+            manifest: workspace?.manifest ?? readManifest(host, targetRoot),
+            otherPackages: [
+                ...(workspace?.entries ?? []),
+                ...packageEntries(host, normalizePath(absoluteRoot), nestedDirs),
+            ],
+            patterns: config.rootPatterns,
+            entryFiles: config.ts.entryFiles,
+            conventions,
+            testFiles: config.ts.testFiles,
+            parse,
+            publishedAPI: config.targetKind === "library",
+            publishedMembers: new Set((workspace?.entries ?? []).filter((entry) => entry.published).map((entry) => entry.dir)),
+        };
     };
     const notBuilt = [...discovered.notBuilt];
     const dropped = (configFile, error) => {
@@ -243,6 +283,7 @@ function readProjects(engine, host, scope, config, stage) {
                     .filter((file) => referenceOnly(file.fileName))
                     .flatMap((file) => relativePath(absoluteRoot, file.fileName) ?? []),
                 generated: generatedFilesOf(own, generatedFiles(conventions, own)),
+                testFileNames: conventions.testFiles,
             };
         };
         for (const file of project.ownSourceFiles()) {
@@ -252,8 +293,8 @@ function readProjects(engine, host, scope, config, stage) {
     }, discovered.derived ? "record" : "refuse", joins.size === 0
         ? workspace?.programs
         : withJoinedTests(engine, host, workspace?.programs ?? new Map(), joins), () => {
-        outsideTests = testFilesAt(host, targetRoot, sourcePaths(host, targetRoot).filter((path) => !heldFiles.has(path) && testPatterns.some((pattern) => pattern.test(path))), options.parse);
-    });
+        outsideTests = testFilesAt(host, targetRoot, sourcePaths(host, targetRoot).filter((path) => !heldFiles.has(path) && testPatterns.some((pattern) => pattern.test(path))), parse);
+    }, readManifests);
     for (const configFile of session.unopened) {
         if (consumerOf.has(configFile) || !isGuess(discovered, configFile)) {
             throw new DiscoveryError(`${configFile} opened no project`, []);
@@ -285,7 +326,8 @@ function readProjects(engine, host, scope, config, stage) {
         componentsUnread: workspace?.componentsUnread ?? [],
         conventionsApplied: conventions.applied,
         conventionUses: conventions.uses,
-        memberDirs: workspace?.memberDirs ?? [],
+        memberDirs,
+        nestedDirs,
         outsideTests,
     };
 }
@@ -346,7 +388,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([
+export const DETECTORS = new Map([
     ["interface-satisfaction", interfaceSatisfaction],
     ["enum-group", enumGroup],
     ["generated-file", generatedFile],
@@ -374,6 +416,7 @@ function readRun(engine, host, scope, config, mode, detectors, extra) {
         const projectRead = opened.read();
         const resolved = references(project, projectRead.held, targetRoot, {
             testFiles: config.ts.testFiles,
+            testFileNames: projectRead.testFileNames,
         });
         const evidence = evidenceRecords({
             project,
@@ -399,7 +442,7 @@ function readRun(engine, host, scope, config, mode, detectors, extra) {
                 line: lineOf(file.originalText, warning.offset),
                 reason: warning.reason,
             }))),
-            extra: extra(project, projectRead, resolved.references),
+            extra: extra(project, projectRead, resolved.references, resolved.testFilePaths),
         };
     });
     const outsidePaths = read.outsideTests.map((one) => one.path);
@@ -419,7 +462,6 @@ function readRun(engine, host, scope, config, mode, detectors, extra) {
         const { projectRead } = one;
         const satisfied = settled[index];
         const detected = heldRecords(satisfied?.evidence ?? one.evidence, {
-            disabled,
             mode,
             testFiles: new Set([...one.testFiles, ...support]),
         });
@@ -437,6 +479,9 @@ function readRun(engine, host, scope, config, mode, detectors, extra) {
             ...(projectRead.referenceOnly.length === 0
                 ? {}
                 : { referenceOnly: projectRead.referenceOnly }),
+            ...(projectRead.held.dependents.size === 0
+                ? {}
+                : { dependents: projectRead.held.dependents }),
         };
         return {
             configFile: projectRead.configFile,
@@ -484,6 +529,7 @@ function readRun(engine, host, scope, config, mode, detectors, extra) {
         conventionsApplied: read.conventionsApplied,
         conventionUses: read.conventionUses,
         memberDirs: read.memberDirs,
+        nestedDirs: read.nestedDirs,
     };
 }
 /**
@@ -610,28 +656,27 @@ function sweptOf(read, input) {
     };
 }
 /**
- * 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 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 run order, swept under the caller's marks and mode with every
+ * project's exemptions. A record found in one configuration holds in every configuration
+ * that holds its declaration, because an exemption evidences a use the analysis cannot see.
+ * 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 sweptOf(readRun(engine, host, scope, config, input.mode, detectors, () => undefined), input);
 }
 /** Reads a run's projects with every per-project fact an emitter reads. */
-function readEmitterRun(engine, host, scope, config, mode, detectors) {
+export function readEmitterRun(engine, host, scope, config, mode, detectors) {
     const targetRoot = scope.target.path;
-    const run = readRun(engine, host, scope, config, mode, detectors, (project, read, references) => ({
+    const run = readRun(engine, host, scope, config, mode, detectors, (project, read, references, testFiles) => ({
         deprecation: deprecatedDeclarations(project, read.held),
         accessors: accessorsOf(project, read.held),
         needs: projectNeeds(project, read.held, host, targetRoot, (fileName, text) => engine.parseSourceFile(fileName, text)),
         implementations: implementations(project, read.held),
         heldByInclusion: heldByInclusion(project, targetRoot),
         generated: [...read.generated.keys()],
+        inOperands: inOperandNames(project, targetRoot, testFiles),
         rooted: read.rooted,
         directives: inlineDirectives(project, read.held, targetRoot).filter((directive) => !read.referenceOnly.includes(directive.site.path)),
         declarationsNamed: declarationsNamed(project, read.held, configuredDeclarations(config)),
@@ -682,7 +727,7 @@ function nearestManifestDir(host, root, file) {
  * The input every emitter reads over one sweep of a read run: the facts beside the sweep
  * each kind family reads, every per-project one read in the same session as the sweep.
  */
-function emitterInputOver(host, scope, config, read, input, selfCheck) {
+export function emitterInputOver(host, scope, config, read, input, selfCheck) {
     const targetRoot = scope.target.path;
     const swept = sweptOf(read, input);
     const { projects } = read;
@@ -695,12 +740,13 @@ function emitterInputOver(host, scope, config, read, input, selfCheck) {
             references: one.configured.references,
             accessors: one.extra.accessors,
         })), swept.exempt, input.mode),
-        dependencies: dependenciesOf(host, targetRoot, [...projects.map((one) => one.extra.needs), configurationNeeds(read.conventionUses)], swept.sweep.candidates.map((candidate) => candidate.id), members.read, members.unbuilt),
+        dependencies: dependenciesOf(host, targetRoot, [...projects.map((one) => one.extra.needs), configurationNeeds(read.conventionUses)], swept.sweep.candidates.map((candidate) => candidate.id), members.read, members.unbuilt, read.nestedDirs),
         implementations: mergeImplementations(projects.map((one) => one.extra.implementations)),
         files: {
             tree: sourceTree(host, targetRoot),
             heldByInclusion: new Set(projects.flatMap((one) => one.extra.heldByInclusion)),
             generated: new Set(projects.flatMap((one) => one.extra.generated)),
+            inOperands: new Set(projects.flatMap((one) => one.extra.inOperands)),
         },
         boundary: {
             consumers: {
@@ -714,17 +760,6 @@ function emitterInputOver(host, scope, config, read, input, selfCheck) {
         intraFunction: intraFunctionFacts(projects.map((one) => one.extra.parts), projects.flatMap((one) => one.configured.references), new Set([...swept.exempt.map((one) => one.id), ...swept.heldByUnanswered])),
     };
 }
-/**
- * What every emitter reads of the run the scope and the configuration describe, swept
- * under the caller's marks: the run's sweep, the facts beside it each kind family reads,
- * and the sides of the target's declared cross-language edges that name a symbol of this
- * language. The run reads no suppression document, so the self-check family has nothing
- * to report.
- */
-export function runEmitterInput(engine, host, scope, config, input, detectors = DETECTORS) {
-    const read = readEmitterRun(engine, host, scope, config, input.mode, detectors);
-    return emitterInputOver(host, scope, config, read, input, NO_SELF_CHECK);
-}
 /**
  * Reads the run the scope and the configuration describe for its findings. The inline
  * directives, the ignore file's entries and the baseline's rows are bound before any

package/dist/src/augmentations.js

@@ -1,9 +1,10 @@
 /**
- * The references a use of an augmentation's declaration makes to what holds it. No name
- * spells a `declare global` block, so a use of a declaration it holds is a use of the
- * block. An interface or namespace an augmentation block holds merges with the one of its
- * name, which the language or a library may type a value by where the target never names
- * it, as it types `import.meta` or `process.env`, so a use of its member is a use of it.
+ * The references a use of an augmentation's declaration makes to what holds it. A use of
+ * a declaration a `declare global` block or a module declaration holds is a use of the
+ * block, which no name spells or no import may name. An interface or namespace such a
+ * block, or the top level of a file that is no module, holds merges with the one of its
+ * name, which the language or a library types values by where the target never names it,
+ * as `import.meta` or `process.env`, so a use of its member is a use of it.
  */
 /** Whether one declaration is a `declare global` block: a module-level namespace named `global`. */
 function isGlobalBlock(symbol, held, files) {
@@ -13,24 +14,25 @@ function isGlobalBlock(symbol, held, files) {
         !held.modules.has(symbol.id));
 }
 /**
- * For each reference to a declaration an augmentation block holds, a read at the same place
- * of every interface and namespace between it and the block, and of a `declare global` block
- * itself.
+ * For each reference to a declaration an augmentation block, or the global scope of a
+ * file in `scripts`, holds, a read at the same place of every interface and namespace
+ * between it and the block or the file, and of the block itself. `scripts` holds the
+ * files that are no module, by identifier.
  */
-export function augmentationReferences(held, found) {
+export function augmentationReferences(held, found, scripts = new Set()) {
     const files = new Set(held.symbols.filter((one) => one.kind === "file").map((one) => one.id));
     const globals = new Set(held.symbols.filter((one) => isGlobalBlock(one, held, files)).map((one) => one.id));
-    if (globals.size === 0 && held.modules.size === 0) {
+    if (globals.size === 0 && held.modules.size === 0 && scripts.size === 0) {
         return [];
     }
     const byId = new Map(held.symbols.map((one) => [one.id, one]));
     const holders = (id) => {
         const ids = [];
         for (let at = byId.get(byId.get(id)?.parent ?? ""); at !== undefined; at = byId.get(at.parent)) {
-            if (globals.has(at.id)) {
+            if (globals.has(at.id) || held.modules.has(at.id)) {
                 return [...ids, at.id];
             }
-            if (held.modules.has(at.id)) {
+            if (scripts.has(at.id)) {
                 return ids;
             }
             if (at.kind === "interface" || at.kind === "namespace") {

package/dist/src/component-layer.js

@@ -7,7 +7,7 @@
  */
 import { dirnamePath, joinPath } from "./paths.js";
 /** The name the mapper's manifest declares and every configuration's entry names. */
-export const MAPPER_PACKAGE = "deadset-ts-component-files";
+const MAPPER_PACKAGE = "deadset-ts-component-files";
 /** The manifest of the mapper's package, which runs `command`. */
 export function mapperManifest(command) {
     return `${JSON.stringify({

package/dist/src/components.js

@@ -26,34 +26,74 @@ export function listing(component, cascade) {
 /**
  * Groups the declarations `dead` marks into components, ordered by their first member's
  * site; `dead`, `testOfDeadCode` and `unreferencedTest` 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.
+ * the graph. Root members sit on the cycles no other cycle references. A component is a
+ * weakly connected part of the dead subgraph, because a cycle two roots reach is dead only
+ * through both. The held declarations `positional` decides form components of their own,
+ * and a dead declaration that is not held shares one with each of its dead dependents.
  */
-export function componentsOf(graph, dead, testOfDeadCode, unreferencedTest = []) {
-    const { at, adjacent } = deadSubgraph(graph, dead, testOfDeadCode, unreferencedTest);
+export function componentsOf(graph, dead, testOfDeadCode, unreferencedTest = [], positional = { dependents: [], live: [] }) {
+    const { at, position, adjacent, references } = deadSubgraph(graph, dead, testOfDeadCode, unreferencedTest);
     if (at.length === 0) {
         return [];
     }
-    const { componentOf, members } = connected(adjacent);
-    const referenced = referencedCycles(adjacent, componentOf, members.length);
-    const groups = joined(adjacent);
-    const idOf = (position) => graph.symbols[at[position] ?? 0]?.id ?? "";
+    const dependents = at.map((index) => (positional.dependents[index] ?? []).map((to) => ({
+        to: position[to] ?? UNVISITED,
+        live: positional.live[to] === true,
+    })));
+    const held = heldSet(dependents, references);
+    const kept = adjacent.map((targets, from) => targets.filter((to) => held[to] === held[from]));
+    const { componentOf, members } = connected(kept);
+    const referenced = referencedCycles(kept, componentOf, members.length);
+    const groups = joined(kept.map((targets, from) => [
+        ...targets,
+        ...(held[from] === true
+            ? []
+            : (dependents[from] ?? []).flatMap(({ to }) => to === UNVISITED || held[to] === true ? [] : [to])),
+    ]));
+    const idOf = (place) => graph.symbols[at[place] ?? 0]?.id ?? "";
     return groups.map((group, place) => {
-        const roots = group.filter((position) => {
+        const roots = group.filter((one) => {
             // 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 referenced[componentOf[position] ?? 0] !== true && dead[container] !== true;
+            const container = graph.parent[at[one] ?? 0] ?? OUTSIDE;
+            return referenced[componentOf[one] ?? 0] !== true && dead[container] !== true;
         });
+        const isHeld = group.every((one) => held[one] === true);
         return {
             id: componentId(place + 1),
             members: group.map(idOf),
             roots: roots.map(idOf),
-            deletableLines: linesSpanned(group.map((position) => graph.symbols[at[position] ?? 0])),
+            deletableLines: isHeld ? 0 : linesSpanned(group.map((one) => graph.symbols[at[one] ?? 0])),
+            held: isHeld,
         };
     });
 }
+/**
+ * Per place of the dead subgraph, whether the declaration is held: one with a live
+ * dependent, and each dead declaration a held one references or has as a dependent,
+ * until no further one joins.
+ */
+function heldSet(dependents, references) {
+    const held = dependents.map((after) => after.some((one) => one.live));
+    const before = dependents.map(() => []);
+    dependents.forEach((after, from) => {
+        for (const { to } of after) {
+            if (to !== UNVISITED) {
+                before[to]?.push(from);
+            }
+        }
+    });
+    const pending = held.flatMap((one, place) => (one ? [place] : []));
+    for (let next = pending.pop(); next !== undefined; next = pending.pop()) {
+        for (const reached of [...(references[next] ?? []), ...(before[next] ?? [])]) {
+            if (held[reached] !== true) {
+                held[reached] = true;
+                pending.push(reached);
+            }
+        }
+    }
+    return held;
+}
 /**
  * The distinct source lines a set of declarations spans, each declaration at least the
  * line it starts on. A member written inside its container's span adds no line, because
@@ -89,12 +129,12 @@ function linesSpanned(symbols) {
     return total;
 }
 /**
- * The dead declarations by their place in the subgraph, a test file's declaration only
- * where it is a test of dead code or nothing the tests reach, and the edges between them:
- * each reference one makes to another, except an unreferenced test-file declaration's
- * reference to production code, which decides nothing of its target, an edge each way
- * between a dead member and its dead container, and an edge back from each production
- * target of an admitted test, which puts the test in its subject's component.
+ * The dead declarations by subgraph place (`at`, and `position` per graph declaration),
+ * a test file's only where it tests dead code or nothing the tests reach. `adjacent` holds
+ * each reference one makes to another, except an unreferenced test-file declaration's to
+ * production code, which decides nothing of its target; an edge each way between a dead
+ * member and its dead container; and one back from each production target of an admitted
+ * test, which puts the test in its subject's component. `references` holds the first alone.
  */
 function deadSubgraph(graph, dead, testOfDeadCode, unreferencedTest) {
     const at = [];
@@ -107,6 +147,7 @@ function deadSubgraph(graph, dead, testOfDeadCode, unreferencedTest) {
         return at.length - 1;
     });
     const adjacent = at.map(() => []);
+    const references = at.map(() => []);
     at.forEach((index, from) => {
         for (const edge of graph.out[index] ?? []) {
             const to = position[edge.to] ?? UNVISITED;
@@ -114,6 +155,7 @@ function deadSubgraph(graph, dead, testOfDeadCode, unreferencedTest) {
                 continue;
             }
             adjacent[from]?.push(to);
+            references[from]?.push(to);
             if (testOfDeadCode[index] === true &&
                 graph.test[edge.to] !== true &&
                 graph.subject[edge.to] === true) {
@@ -126,7 +168,7 @@ function deadSubgraph(graph, dead, testOfDeadCode, unreferencedTest) {
             adjacent[container]?.push(from);
         }
     });
-    return { at, adjacent };
+    return { at, position, adjacent, references };
 }
 /**
  * Each declaration's cycle and each cycle's members by site, by Tarjan's