@cplieger/deadset-ts 2.2.1 → 3.0.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 2.1.0 and ships the analyzer's foundation: one compiler session per run over 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, and the one-pass reference resolution over that inventory. The inventory and the reference pass are library functions the package exports; no verb reports findings yet, so `analyze`, `explain`, `print-roots`, `print-retained` 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 2.2.0 and ships the analyzer's foundation: one compiler session per run over the projects `analysis.configurations` declares, 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. 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`, `print-retained` 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
 
@@ -28,14 +28,15 @@ The npm package carries the command and the library as JavaScript that the compi
 npx deadset-ts version
 ```
 
-`version` prints the analyzer version and the Contract version it implements, and exits 0. Any other invocation, including no arguments, prints the usage line and exits 2.
+`version` prints the analyzer version and the Contract version it implements, and exits 0. `print-config`, `print-projects` and `print-roots` print what their row of the table says and exit 0, or 1 when `print-roots` reports a `DS1704`. `analyze`, `explain`, `print-retained`, `describe`, any other invocation and no arguments print the usage line and exit 2.
 
 | Verb             | Job                                                                             |
 | ---------------- | ------------------------------------------------------------------------------- |
 | `analyze`        | Analyze a project and print the findings                                        |
 | `explain`        | Explain one finding: the relation, the roots and the references that decided it |
 | `print-config`   | Print the resolved configuration and where each setting came from               |
-| `print-roots`    | Print the resolved set of entry points                                          |
+| `print-projects` | Print the identifier of every project a run analyzes                            |
+| `print-roots`    | Print every declaration the analysis keeps live without a reference, and why    |
 | `print-retained` | Print every symbol an exemption class held back, with the class                 |
 | `describe`       | Describe the analyzer: version, Contract version, supported issue kinds         |
 | `version`        | Print the analyzer and Contract versions                                        |
@@ -48,7 +49,7 @@ npx deadset-ts version
 
 ## API
 
-The package exports the command line and the analyzer's own stages, for callers that embed them. Every one of them reads the platform through a `Host`: the filesystem, the directory relative paths resolve against, and the version of the package the analyzer was installed from. `bin/node-host.ts` is the Node one the command line binds; a caller embedding the analyzer, or running it on another platform, supplies its own and supplies its own version with it.
+The package exports the command line, for callers that run it in-process, and the vocabularies and helpers its output is spelled with. The command line reads the platform through a `Host`: the filesystem, the directory relative paths resolve against, and the version of the package the analyzer was installed from. `bin/node-host.ts` is the Node one the command line binds; a caller embedding the analyzer, or running it on another platform, supplies its own and supplies its own version with it.
 
 The command line:
 
@@ -61,18 +62,6 @@ The platform:
 - `Host`: the filesystem a run reads, the directory it reads relative paths against, and the analyzer's own version.
 - `DirectoryEntry`, `PathKind`: one entry of a directory read, and what one path names.
 
-The symbol inventory:
-
-- `inventory(project, host, targetRoot)`: every declaration one project's own files hold, in position order, down to class and type members.
-- `nodeKey(file, node)`: the key one declaration is recorded under.
-- `Inventory`, `InventorySymbol`, `InventoryCost`, `SymbolKind`, `Visibility`: one project's inventory, one declaration of it, what reading it cost, and the two vocabularies a declaration is described by.
-
-The reference pass:
-
-- `references(project, held, targetRoot, options)`: every reference from one project's own files to a declaration of its inventory, in position order, with the rules that classified files as test files.
-- `DEFAULT_BATCH_CAP`: the batch size the reference pass takes when its caller passes none; it is an option of the pass, not a configuration key. [Batch-cap calibration](docs/batch-cap-calibration.md) is the measurement that set it.
-- `Reference`, `References`, `ReferenceOptions`, `ReferenceCost`, `TestFileRule`, `Resolution`, `Use`: one reference, one project's set of them, how a run resolves them, what that cost, one test-file rule, which accessor answered a reference, and whether it reads or writes.
-
 Positions:
 
 - `renderPosition(file, root, offset)`: one compiler offset as a path, a line and a column, the column counting UTF-16 code units.
@@ -88,6 +77,10 @@ Stable symbol references:
 - `REF_EXPRESSIONS`: one regular expression per form the grammar defines.
 - `Module`, `Component`, `Fragment`, `DependencySection`: the module half of a reference, one component of its fragment, what the fragment names, and the manifest section a dependency was declared in.
 
+Entry points:
+
+- `DECLINED_CONVENTIONS`, `DeclinedConvention`: the entry-point conventions of other tools the analysis does not read, one row per tool or convention with the reason.
+
 Versions:
 
 - `CONTRACT_VERSION`: the contract version this analyzer implements.

package/dist/src/analysis.js

@@ -0,0 +1,142 @@
+/**
+ * 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.
+ */
+import { diagnosticErrors, discoverProjects, DiscoveryError } from "./discover.js";
+import { graphOf } from "./graph.js";
+import { inventory } from "./inventory.js";
+import { readManifest } from "./manifest.js";
+import { relativePath, resolvePath } from "./paths.js";
+import { byPosition } from "./position.js";
+import { references } from "./references.js";
+import { roots, unmatchedEverywhere, unmatchedRoots } from "./roots.js";
+import { diagnosticsOf, runSession } from "./session.js";
+import { sweep } from "./sweep.js";
+/** The setting whose source decides where a finding about a configured root sits. */
+const ROOTS_SETTING = "roots.patterns";
+/**
+ * The document that supplied one setting, below the target root, or the empty
+ * string where the setting came from no document of the target. Both paths are
+ * resolved against the working directory before one is read below the other, so a
+ * relative target and a relative document name the same place.
+ */
+function documentOf(host, provenance, setting, targetRoot) {
+    const origin = provenance.get(setting);
+    if (origin === undefined || origin.source === "default" || origin.source === "flag") {
+        return "";
+    }
+    const document = resolvePath(host.workingDirectory(), origin.label);
+    return relativePath(resolvePath(host.workingDirectory(), targetRoot), document) ?? "";
+}
+/** Two strings ordered bytewise. */
+function compare(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    return a < b ? -1 : 1;
+}
+/**
+ * Reads every project the scope discovers, in one snapshot: each is checked for errors
+ * first, then enumerated, then rooted, and `stage` reads the rest of what it needs from
+ * the project while its view is open. A project carrying an error fails the run with no
+ * answer, as every verb that reads declarations does.
+ */
+function readProjects(engine, host, scope, config, stage) {
+    const targetRoot = scope.target.path;
+    const discovered = discoverProjects(engine, host, scope, config.analysis.configurations);
+    const ids = new Map(discovered.projects.map((project) => [project.configFile, project.id]));
+    const options = {
+        manifest: readManifest(host, targetRoot),
+        patterns: config.rootPatterns,
+        entryFiles: config.ts.entryFiles,
+        testFiles: config.ts.testFiles,
+        publishedAPI: config.targetKind === "library",
+    };
+    const failures = [];
+    const { projects } = runSession(engine, discovered.configFiles, (project) => {
+        const errors = diagnosticErrors(diagnosticsOf(project));
+        if (errors.length > 0) {
+            failures.push(...errors);
+            return undefined;
+        }
+        const held = inventory(project, host, targetRoot);
+        const rooted = roots(project, held, targetRoot, options);
+        const configuration = ids.get(project.configFile) ??
+            relativePath(targetRoot, project.configFile) ??
+            project.configFile;
+        return stage(project, { configuration, held, rooted });
+    });
+    if (failures.length > 0) {
+        throw new DiscoveryError(`${String(failures.length)} error(s); no answer was produced`, failures);
+    }
+    return projects.filter((answer) => answer !== undefined);
+}
+/**
+ * The root set of the run the scope and the configuration describe.
+ *
+ * A configured string is a finding when it names nothing in every project, and the
+ * finding sits in the document that declared the roots.
+ */
+export function runRoots(engine, host, scope, config, provenance) {
+    const targetRoot = scope.target.path;
+    const projects = readProjects(engine, host, scope, config, (_project, read) => read);
+    const configurations = [];
+    const merged = new Map();
+    for (const answer of projects) {
+        const configuration = answer.configuration;
+        configurations.push(configuration);
+        const symbols = new Map(answer.held.symbols.map((symbol) => [symbol.id, symbol]));
+        for (const root of answer.rooted.liveUnderReachability) {
+            const symbol = symbols.get(root.id);
+            if (symbol === undefined) {
+                continue;
+            }
+            const key = [root.id, root.kind, root.source].join("\u0000");
+            const held = merged.get(key);
+            if (held === undefined) {
+                merged.set(key, {
+                    ref: symbol.ref,
+                    position: symbol.position,
+                    kind: root.kind,
+                    source: root.source,
+                    configurations: [configuration],
+                });
+            }
+            else if (!held.configurations.includes(configuration)) {
+                held.configurations.push(configuration);
+            }
+        }
+    }
+    const ordered = [...merged.values()].sort((a, b) => byPosition(a.position, b.position) || compare(a.kind, b.kind) || compare(a.source, b.source));
+    const unmatched = unmatchedEverywhere(config.rootPatterns, projects.map((answer) => answer.rooted));
+    return {
+        configurations,
+        roots: ordered,
+        findings: unmatchedRoots(unmatched, documentOf(host, provenance, ROOTS_SETTING, targetRoot)),
+    };
+}
+/**
+ * Sweeps every project of the run the scope and the configuration describe, one
+ * configuration at a time, in discovery order. Each project's references are read
+ * against its own inventory with the configured test-file patterns, and its graph is
+ * swept under the input the caller decided once for the run.
+ */
+export function runSweeps(engine, host, scope, config, input) {
+    const targetRoot = scope.target.path;
+    return readProjects(engine, host, scope, config, (project, read) => {
+        const resolved = references(project, read.held, targetRoot, {
+            testFiles: config.ts.testFiles,
+        });
+        const graph = graphOf(read.held.symbols, resolved.references, read.rooted.liveUnderReachability, resolved.testFilePaths);
+        return {
+            configuration: read.configuration,
+            symbols: read.held.symbols,
+            sweep: sweep(graph, input),
+        };
+    });
+}

package/dist/src/components.js

@@ -0,0 +1,289 @@
+/**
+ * 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.
+ */
+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 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. */
+export function listing(component, cascade) {
+    return {
+        roots: component.roots,
+        members: cascade === "full" ? component.members : [],
+        symbolCount: component.falls.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.
+ */
+export function componentsOf(graph, dead, testOfDeadCode) {
+    const { at, adjacent } = deadSubgraph(graph, dead, testOfDeadCode);
+    if (at.length === 0) {
+        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 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.
+            const container = graph.parent[at[position] ?? 0] ?? OUTSIDE;
+            return outsideReference[position] !== true && dead[container] !== true;
+        });
+        const fallen = falls[group] ?? [];
+        return {
+            id: `${ANALYZER}/c-${String(place + 1).padStart(ID_DIGITS, "0")}`,
+            members: own.map(idOf),
+            roots: roots.map(idOf),
+            falls: fallen.map(idOf),
+            deletableLines: linesSpanned(fallen.map((position) => graph.symbols[at[position] ?? 0])),
+        };
+    });
+}
+/**
+ * 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
+ * deleting the container removes it.
+ */
+function linesSpanned(symbols) {
+    const byPath = new Map();
+    for (const symbol of symbols) {
+        if (symbol === undefined) {
+            continue;
+        }
+        const span = [
+            symbol.position.line,
+            Math.max(symbol.position.line, symbol.endLine),
+        ];
+        const spans = byPath.get(symbol.position.path);
+        if (spans === undefined) {
+            byPath.set(symbol.position.path, [span]);
+        }
+        else {
+            spans.push(span);
+        }
+    }
+    let total = 0;
+    for (const spans of byPath.values()) {
+        spans.sort((a, b) => a[0] - b[0]);
+        let end = 0;
+        for (const [first, last] of spans) {
+            total += Math.max(0, last - Math.max(first - 1, end));
+            end = Math.max(end, last);
+        }
+    }
+    return total;
+}
+/**
+ * The dead declarations by their place in the subgraph, and the edges between them: each
+ * reference one makes to another, an edge each way between a dead member and its dead
+ * container (one direction alone leaves the member a component the container reaches),
+ * and an edge back from each production target of an admitted test, which puts the test in
+ * the component of the code it exercises because a subject never references its test.
+ */
+function deadSubgraph(graph, dead, testOfDeadCode) {
+    const at = [];
+    const position = graph.symbols.map((_symbol, index) => {
+        if (dead[index] !== true) {
+            return UNVISITED;
+        }
+        at.push(index);
+        return at.length - 1;
+    });
+    const adjacent = at.map(() => []);
+    at.forEach((index, from) => {
+        for (const edge of graph.out[index] ?? []) {
+            const to = position[edge.to] ?? UNVISITED;
+            if (to === UNVISITED) {
+                continue;
+            }
+            adjacent[from]?.push(to);
+            if (testOfDeadCode[index] === true &&
+                graph.test[edge.to] !== true &&
+                graph.subject[edge.to] === true) {
+                adjacent[to]?.push(from);
+            }
+        }
+        const container = position[graph.parent[index] ?? OUTSIDE] ?? UNVISITED;
+        if (container !== UNVISITED) {
+            adjacent[from]?.push(container);
+            adjacent[container]?.push(from);
+        }
+    });
+    return { at, adjacent };
+}
+/**
+ * Each declaration's component and each component'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.
+ */
+function connected(adjacent) {
+    const index = adjacent.map(() => UNVISITED);
+    const low = adjacent.map(() => UNVISITED);
+    const onStack = adjacent.map(() => false);
+    const stack = [];
+    const members = [];
+    let next = 0;
+    const open = (at, frames) => {
+        index[at] = next;
+        low[at] = next;
+        next += 1;
+        stack.push(at);
+        onStack[at] = true;
+        frames.push({ at, next: 0 });
+    };
+    adjacent.forEach((_edges, start) => {
+        if (index[start] !== UNVISITED) {
+            return;
+        }
+        const frames = [];
+        open(start, frames);
+        for (let frame = frames.at(-1); frame !== undefined; frame = frames.at(-1)) {
+            const edges = adjacent[frame.at] ?? [];
+            const to = edges[frame.next];
+            if (to !== undefined) {
+                frame.next += 1;
+                if (index[to] === UNVISITED) {
+                    open(to, frames);
+                }
+                else if (onStack[to] === true) {
+                    low[frame.at] = Math.min(low[frame.at] ?? 0, index[to] ?? 0);
+                }
+                continue;
+            }
+            frames.pop();
+            const parent = frames.at(-1);
+            if (parent !== undefined) {
+                low[parent.at] = Math.min(low[parent.at] ?? 0, low[frame.at] ?? 0);
+            }
+            if (low[frame.at] !== index[frame.at]) {
+                continue;
+            }
+            const group = [];
+            for (let top = stack.pop(); top !== undefined; top = stack.pop()) {
+                onStack[top] = false;
+                group.push(top);
+                if (top === frame.at) {
+                    break;
+                }
+            }
+            members.push(group.sort((a, b) => a - b));
+        }
+    });
+    const componentOf = adjacent.map(() => 0);
+    members.forEach((group, component) => {
+        for (const at of group) {
+            componentOf[at] = component;
+        }
+    });
+    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();
+    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;
+            }
+        }
+    });
+    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.
+ */
+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;
+        }
+    });
+    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] ?? []));
+            }
+        }
+        return set.sort((a, b) => a - b);
+    });
+}

package/dist/src/config.js

@@ -1,4 +1,10 @@
 import { CONTRACT_VERSION } from "./version.js";
+/**
+ * The name of the repository configuration at the target root, which is also the
+ * document a finding about the configuration names where no document of the
+ * target supplied the setting it is about.
+ */
+export const REPOSITORY_DOCUMENT = "deadset.json";
 /**
  * The configuration every documented default states. `targetKind` is empty: the
  * field has no default and is never inferred.

package/dist/src/discover.js

@@ -1,5 +1,5 @@
 import { DiagnosticCategory } from "@typescript/native/unstable/sync";
-import { dirnamePath, isAbsolutePath, joinPath, resolvePath } from "./paths.js";
+import { dirnamePath, isAbsolutePath, joinPath, relativePath, resolvePath } from "./paths.js";
 /** Directory names discovery does not descend into. */
 const IGNORED_DIRECTORIES = new Set(["node_modules", ".git"]);
 /** A compiler configuration file discovery recognises under a root. */
@@ -128,24 +128,77 @@ function scopeConfigFiles(host, scope) {
         .map((path) => resolvePath(host.workingDirectory(), path));
 }
 /**
- * Every project one run analyzes, in the order discovery reads them: the paths the
- * scope names, then every compiler configuration under the target root that is not
- * inside an ignored directory, then the configurations each of those references,
- * transitively. Each configuration appears once.
- *
- * A configuration file the compiler cannot read ends the run with the failure code,
- * so a project that would have been analyzed with no type information is never
- * analyzed at all. What a configuration's own contents say is refused once its
- * project is open, by {@link diagnosticErrors} over the three sets a program
- * reports, because a resolution carries no diagnostics.
+ * The name a derived project carries: its configuration file's path below the target
+ * root, or the absolute path of a file outside it.
+ */
+function derivedId(targetRoot, configFile) {
+    return relativePath(targetRoot, configFile) ?? configFile;
+}
+/**
+ * Resolves one compiler configuration file, or ends the run naming it: a project
+ * opened from a configuration the compiler cannot read would be analyzed with no
+ * type information.
+ */
+function parseOrRefuse(engine, configFile, named) {
+    try {
+        engine.parseConfigFile(configFile);
+    }
+    catch (error) {
+        throw new DiscoveryError(`${named} cannot be read as a compiler configuration: ` +
+            (error instanceof Error ? error.message : String(error)), []);
+    }
+}
+/**
+ * The projects a build matrix declares, in the order it lists them. Each entry
+ * names a file below the target root, and an entry naming a file that is absent,
+ * that is a directory, or that the compiler cannot read ends the run naming it.
  *
- * Nothing reads a build output: a project is the files its configuration names, so a
- * package whose sources ship as TypeScript is analyzed as it stands.
+ * A declared project's `references` are not followed, because the entries are the
+ * matrix, and a reference to a configuration the matrix does not name ends the run
+ * naming both: the compiler builds a referenced project's sources into the program
+ * that references it without reporting their diagnostics, so the project the matrix
+ * left out would be analyzed with its errors unread. An entry naming a file an
+ * earlier entry named adds nothing, so the earlier identifier stands.
+ */
+function declaredProjects(engine, host, targetRoot, entries) {
+    const seen = new Set();
+    const projects = [];
+    for (const entry of entries) {
+        const configFile = joinPath(targetRoot, entry.project);
+        const named = `the project ${JSON.stringify(entry.id)} (${configFile})`;
+        const kind = host.kindOf(configFile);
+        if (kind !== "file") {
+            throw new DiscoveryError(kind === "absent"
+                ? `${named} does not exist`
+                : `${named} is a directory, and a project names its compiler configuration file`, []);
+        }
+        if (seen.has(configFile)) {
+            continue;
+        }
+        seen.add(configFile);
+        parseOrRefuse(engine, configFile, named);
+        projects.push({ id: entry.id, configFile });
+    }
+    for (const project of projects) {
+        const unnamed = referencesOf(host, project.configFile).find((path) => !seen.has(path));
+        if (unnamed !== undefined) {
+            throw new DiscoveryError(`the project ${JSON.stringify(project.id)} (${project.configFile}) references ` +
+                `${unnamed}, which the build matrix does not name; a referenced project is built ` +
+                "into the program that references it, so the matrix names it too", []);
+        }
+    }
+    return { projects, configFiles: projects.map((project) => project.configFile), fromScope: [] };
+}
+/**
+ * The projects a run derives where the matrix declares none, in the order discovery
+ * reads them: the paths the scope names, then every compiler configuration under
+ * the target root that is not inside an ignored directory, then the configurations
+ * each of those references, transitively. Each configuration appears once.
  */
-export function discoverProjects(engine, host, scope) {
+function derivedProjects(engine, host, scope) {
     const fromScope = scopeConfigFiles(host, scope);
     const seen = new Set();
-    const configFiles = [];
+    const projects = [];
     const pending = [...fromScope, ...configFilesUnder(host, scope.target.path)];
     while (pending.length > 0) {
         const configFile = pending.shift();
@@ -157,15 +210,36 @@ export function discoverProjects(engine, host, scope) {
             continue;
         }
         seen.add(path);
-        try {
-            engine.parseConfigFile(path);
-        }
-        catch (error) {
-            throw new DiscoveryError(`${path} cannot be read as a compiler configuration: ` +
-                (error instanceof Error ? error.message : String(error)), []);
-        }
-        configFiles.push(path);
+        parseOrRefuse(engine, path, path);
+        projects.push({ id: derivedId(scope.target.path, path), configFile: path });
         pending.push(...referencesOf(host, path));
     }
-    return { configFiles, fromScope };
+    return { projects, configFiles: projects.map((project) => project.configFile), fromScope };
+}
+/**
+ * Every project one run analyzes.
+ *
+ * The project entries of the build matrix, where it holds any, are the projects:
+ * exactly those, in the order the matrix lists them, each named by its declared
+ * identifier, as {@link declaredProjects} reads them. A matrix holding no project
+ * entry, the empty one included, leaves discovery to derive the projects from the
+ * scope and the target tree. A platform entry names a configuration of another
+ * language and plays no part here.
+ *
+ * A configuration file the compiler cannot read ends the run with the failure code,
+ * so a project that would have been analyzed with no type information is never
+ * analyzed at all, whether the matrix declared it or discovery derived it. What a
+ * configuration's own contents say is refused once its project is open, by
+ * {@link diagnosticErrors} over the three sets a program reports, because a
+ * resolution carries no diagnostics.
+ *
+ * Nothing reads a build output: a project is the files its configuration names, so a
+ * package whose sources ship as TypeScript is analyzed as it stands.
+ */
+export function discoverProjects(engine, host, scope, configurations = []) {
+    const declared = configurations.filter((entry) => entry.shape === "project");
+    if (declared.length > 0) {
+        return declaredProjects(engine, host, scope.target.path, declared);
+    }
+    return derivedProjects(engine, host, scope);
 }