@cplieger/deadset-ts 3.13.0 → 4.0.1

package/README.md

@@ -2,13 +2,22 @@
 
 [![npm](https://img.shields.io/npm/v/@cplieger/deadset-ts)](https://www.npmjs.com/package/@cplieger/deadset-ts) [![JSR](https://jsr.io/badges/@cplieger/deadset-ts)](https://jsr.io/@cplieger/deadset-ts)
 
-> Deterministic dead-code analysis for TypeScript, class and type members included.
+deadset-ts finds dead code in TypeScript projects, down to class members, type members and dead stores inside functions, and writes a report your CI can fail on.
 
-deadset-ts is a command-line analyzer for TypeScript and JavaScript projects. It builds the program from your `tsconfig.json` files through the TypeScript 7 compiler API, resolves every reference in one pass, and reports the declarations nothing reaches: unused exports, type-only exports without a consumer, unused class members (private, protected, static and accessors), unused interface, type-alias, enum and namespace members, exports that can be narrowed to a smaller visibility, whole groups of declarations that only keep each other alive, and inside a function the unused parameters, results nobody reads, unreachable statements, dead stores and unreachable cases. Every finding carries an issue code, a confidence and a stable symbol reference from the [deadset Contract](https://github.com/cplieger/deadset-spec), so the same report shape works for a Go analyzer and for a merged multi-language report. The analysis is deterministic: the same tree gives the same report, with no cache and no text search.
+It reads your `tsconfig.json` projects, `allowJs` JavaScript included, with the type information of TypeScript 7.1.0-dev.20261003.1, its one dependency. Your project keeps its own TypeScript version and must also compile under that version. deadset-ts reports and never edits your code. It is pre-release, tested only on Linux, needs Node.js 24 or later and is licensed under GPL-3.0-or-later.
 
-deadset-ts is report-only. It never edits source, and it refuses any `--fix` flag.
+## Why use it
 
-**Status: pre-release.** This version implements contract 4.0.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. `analyze` writes the report the Contract's report schema declares, with text, JSON, GitHub annotation, SARIF 2.1.0 and template renderings beside it on request. A scope document passed with `--scope` names the consumers loaded beside the target, each a directory whose compiler configurations open in the same session; a reference from a consumer keeps a target declaration live, the report names every consumer it loaded, and a consumer that is absent or does not load ends the run with exit code 3. A library target's published API is `certain` once every declared consumer loads and `possible` with no consumer information, and in that second case `DS1001` defaults to `allow` and the narrowing kinds report only in files no manifest export reaches. `explain` answers why one declaration is reported, retained, live or dead, from the same analysis the report is built from. `describe` prints the analyzer's description with its conformance record over the published corpus and the declared gaps `conformance.json` lists. The analysis is reached through the command, and through `run()` for a caller that runs the command in-process. 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.
+deadset-ts is built for a CI gate on dead code. Each finding names code to delete, an `export` to drop or a setting to fix.
+
+- It reports unused exports, files and dependencies, and unused members of classes, interfaces, type aliases, enums and namespaces, private and static included.
+- Inside a function, it reports unused parameters and results, unreachable statements and cases, and dead stores.
+- It reports an `export` only its own file uses, and declarations that only reference each other.
+- It keeps what decorators, reflective lookups, `JSON.stringify` and the frameworks, containers, serializers and templates you name in `deadset.json` use.
+- The same tree gives the same report, and a baseline keyed on code and symbol survives moved lines.
+- It writes text, JSON, GitHub annotations, SARIF 2.1.0 or a custom template.
+
+Consider [Knip](https://knip.dev) if you want issues fixed with `--fix`, plugins for over 100 tools, or Astro, MDX, Svelte and Vue files checked.
 
 ## Install
 
@@ -20,70 +29,79 @@ npx jsr add -D @cplieger/deadset-ts
 npx @cplieger/deadset-ts version
 ```
 
-The npm package carries the command and the library as JavaScript that the compiler emits at publish, so `npx deadset-ts` and `import("@cplieger/deadset-ts")` both run on plain Node.js 24 or later, with no loader and no flag. It carries the TypeScript source as well, which is what a TypeScript consumer's own compiler resolves. That consumer sets `allowImportingTsExtensions`, because the source names each import with its `.ts` extension. The JSR package ships source only, and Deno compiles it: a Deno program imports and type-checks the library, but the compiler's synchronous session does not open under Deno, so running an analysis needs Node.
-
 ## Usage
 
+Create a `deadset.json` at the project root that says whether the project is an `application` or a `library`, then run `analyze`. A run reads every `tsconfig` project under that folder, project references included, and reports a declaration only when it is dead in all of them.
+
 ```sh
-npx deadset-ts version
+echo '{ "target": { "kind": "application" } }' > deadset.json
+npx @cplieger/deadset-ts analyze --report=deadset-report.json
 ```
 
-`version` prints the analyzer version and the Contract version it implements, and exits 0. `print-config`, `print-projects`, `print-roots` and `print-retained` print what their row of the table says and exit 0, or 1 when `print-roots` reports a `DS1704`, and `print-retained` exits 2 when an `exemptions.disabled` entry is not an exemption class or an `analysis.template_dirs` entry is not a directory below the target root. `analyze --report=PATH` writes the JSON report to `PATH` through a temporary file renamed into place, each `--format` rendering at `PATH` with its suffix appended (`text` as `.txt`, `json` as `.json`, `github` as `.annotations` in GitHub workflow-command form, `sarif` as `.sarif`, and `template` as `.tmpl`, rendering the file `--template=FILE` names, written in a subset of Go's `text/template` action grammar over the report's JSON member names), and with `--baseline-write=FILE` a baseline of every finding; it writes nothing to standard output and exits with the Contract's exit-code table: 0 clean, 1 for a finding at or above `reporters.fail_on` or a stale suppression, 2 for a usage error, including a template that cannot be read or does not parse, 3 for a failed load or a rendering that cannot be written, and 4 for a pending finding, which outranks 1. `--exit-code=off` exits 0 whatever the verdict and names the verdict on standard error. The report names the target relative to the directory the run is invoked from, so a target outside that directory fails with 3. `describe` writes its JSON document to standard output and exits 0. `explain --why=SYM`, or the same request spelled `--why-live=SYM` or `--why-not=SYM`, prints why that one declaration is reported, retained, live or dead, with the shortest reference path from a root or a loaded consumer for a live one, and exits 0; a request that names no one declaration exits 2 and lists up to 20 declarations it partially matches. Any other invocation and no arguments print the usage line and exit 2.
-
-| Verb             | Job                                                                                |
-| ---------------- | ---------------------------------------------------------------------------------- |
-| `analyze`        | Analyze a project and write the report, its renderings and a baseline              |
-| `explain`        | Explain one declaration: the relation, the roots and the references that decide it |
-| `print-config`   | Print the resolved configuration and where each setting came from                  |
-| `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 declaration an exemption held back: each class, its site and detail    |
-| `describe`       | Describe the analyzer: versions, accepted report schemas, languages, conformance   |
-| `version`        | Print the analyzer and Contract versions                                           |
-
-## Requirements
-
-- Node.js 24 or later. The npm command is JavaScript the compiler emits at publish, so it runs with no loader and no flag; a clone of this repository runs the same command from its TypeScript sources through Node's own type stripping, which is what needs the version.
-- TypeScript 7. The analyzer is written against the `typescript` package at exactly version 7.0.2 and its `unstable/*` API. It does not run on TypeScript 6, whose compiler API TypeScript 7 removed, and it does not fall back to it.
-- Linux. Other platforms are untested.
+`analyze` writes the JSON report to `deadset-report.json` and a text rendering beside it as `deadset-report.json.txt`. Take this `src/greet.ts`, where the rest of the project calls only `greet` and `Counter.increment`:
+
+```ts
+export function greet(name: string): string {
+  return `hello ${name}`;
+}
+export function farewell(name: string): string {
+  return `bye ${name}`;
+}
+export class Counter {
+  private count = 0;
+  increment(): void {
+    this.count += 1;
+  }
+  reset(): void {
+    this.count = 0;
+  }
+}
+```
 
-## API
+The text rendering lists three findings:
 
-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.
+```text
+src/greet.ts:4:17: function farewell: exported function has no reference in the target and none from any loaded consumer [certain] (DS1001)
+src/greet.ts:8:11: class-member Counter.count: member Counter.count is written at 2 positions and never read [certain] (DS1301)
+src/greet.ts:12:3: method Counter.reset: method has no reference in the target [certain] (DS1003)
+summary: 3 findings (0 allow, 0 warn, 3 deny), 6 deletable lines, 0 suppressions in effect, 0 reasons recorded, 0 stale suppressions, 0 pending, 0 omitted
+```
 
-The command line:
+The run exits 1 because the report holds a finding at `deny` severity, and 0 when it holds none. Three common next steps:
 
-- `run(args, out, err, host, openClient?)`: runs the command line over `args` (the arguments after the program name), writing to the two `Writer` streams, and returns the exit code. It never exits the process.
-- `SETTING_OPTIONS`: the configuration setting each command-line option supplies, by option name.
-- `Writer`: `{ write(text: string): void }`. `process.stdout` and `process.stderr` satisfy it.
+- Add `--format=sarif` or `--format=github` for a SARIF file or GitHub workflow annotations. Naming any format turns off the default text rendering, so add `--format=text` as well to keep it.
+- Run `npx @cplieger/deadset-ts explain --why=farewell` to see why one declaration is reported, retained, held by an unanswered question, live or dead.
+- Add `--baseline-write=deadset-baseline.json` to record today's findings. Later runs fail on a new finding and on a baseline row whose finding has gone. To keep one declaration, put `// deadset:ignore DS1001 -- <reason>` on the line above it.
 
-The platform:
+[Commands and exit codes](docs/commands.md) covers every verb and option, and [Configuration](docs/configuration.md) covers every setting.
 
-- `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.
+## API
 
-Positions:
+The package exports the command line as a function, and the helpers that spell the positions and symbol references in a report.
 
-- `renderPosition(file, root, offset)`: one compiler offset as a path, a line and a column, the column counting UTF-16 code units.
-- `positionKey(position)`, `byPosition(a, b)`: the string one position is keyed by, and the order positions are reported in.
-- `PositionError`: the refusal for a position that cannot be rendered against the target root.
-- `Position`: one rendered position.
+- `run` runs the command line and returns its exit code, without exiting the process. `Writer` is its output stream, and `SETTING_OPTIONS` maps each option to the setting it sets.
+- `Host`, `DirectoryEntry` and `PathKind` describe the filesystem, working directory and version a run reads.
+- `renderPosition`, `positionKey`, `byPosition`, `PositionError` and `Position` render and order positions.
+- `renderRef`, `nameComponent`, `computedComponent`, `isRef`, `REF_EXPRESSIONS`, `Module`, `Component`, `Fragment` and `DependencySection` spell stable symbol references.
+- `DECLINED_CONVENTIONS` and `DeclinedConvention` list the entry-point conventions of other tools the analysis does not read.
+- `CONTRACT_VERSION` is the version of the [deadset Contract](https://github.com/cplieger/deadset-spec) this analyzer implements.
 
-Stable symbol references:
+A TypeScript caller that imports the source sets `allowImportingTsExtensions`, because each import in it ends in `.ts`. [Using deadset-ts as a library](docs/library.md) covers the packages and in-process runs, and [JSR](https://jsr.io/@cplieger/deadset-ts/doc) has the full reference.
 
-- `renderRef(module, fragment)`: one symbol's stable reference, in the canonical spelling the contract's grammar fixes.
-- `nameComponent(name)`, `computedComponent(text)`: the canonical spelling of one component of that reference, from a declared name or from a computed key.
-- `isRef(value)`: whether one string is a reference of this language's grammar.
-- `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.
+## Related projects
 
-Entry points:
+deadset-ts implements the [deadset Contract](https://github.com/cplieger/deadset-spec), which fixes the issue codes, the report schema and the exit codes. It passes the Contract's conformance corpus except one reflective-lookup fixture, the gap [`conformance.json`](conformance.json) declares.
 
-- `DECLINED_CONVENTIONS`, `DeclinedConvention`: the entry-point conventions of other tools the analysis does not read, one row per tool or convention with the reason.
+- [deadset-go](https://github.com/cplieger/deadset-go) is the same analysis for Go modules.
+- [deadset](https://github.com/cplieger/deadset) runs both analyzers as one command and merges their reports, resolving the edges between Go and TypeScript code.
 
-Versions:
+## Documentation
 
-- `CONTRACT_VERSION`: the contract version this analyzer implements.
+- [Commands and exit codes](docs/commands.md) lists every verb, option, rendering and exit code.
+- [Configuration](docs/configuration.md) lists every setting, the suppression files and the scope document.
+- [How deadset-ts works](docs/how-it-works.md) explains the projects it loads, the roots it starts from and what it holds back.
+- [Using deadset-ts as a library](docs/library.md) covers the npm and JSR packages and running the analyzer in-process.
+- [Batch-cap calibration](docs/batch-cap-calibration.md) is the measurement behind the batch size of the reference pass.
 
 ## Contributing
 

package/dist/bin/node-host.js

@@ -47,18 +47,21 @@ function readVersion() {
 /** The mode every document the command writes carries. */
 const DOCUMENT_MODE = 0o644;
 /**
- * Writes one document through a temporary file in the same directory, flushed and then
- * renamed into place, so a run that dies partway leaves no truncated document at the path.
+ * Writes one document through a temporary file in the same directory, piece by piece,
+ * flushed and then renamed into place, so a run that dies partway leaves no truncated
+ * document at the path.
  */
-function writeAtomically(path, text) {
+function writeAtomically(path, pieces) {
     const temporary = join(dirname(path), `.${basename(path)}.${randomBytes(6).toString("hex")}`);
     const fd = openSync(temporary, "wx", DOCUMENT_MODE);
     try {
         try {
             fchmodSync(fd, DOCUMENT_MODE);
-            const bytes = Buffer.from(text, "utf8");
-            for (let written = 0; written < bytes.length;) {
-                written += writeSync(fd, bytes, written);
+            for (const piece of pieces) {
+                const bytes = Buffer.from(piece, "utf8");
+                for (let written = 0; written < bytes.length;) {
+                    written += writeSync(fd, bytes, written);
+                }
             }
             fsyncSync(fd);
         }
@@ -99,6 +102,6 @@ export function nodeHost() {
             found ??= readVersion();
             return found;
         },
-        writeFile: writeAtomically,
+        writeDocument: writeAtomically,
     };
 }

package/dist/src/alias-chain.js

@@ -3,8 +3,10 @@
  * declaration of the target it is, and along the chain of aliases it heads to each
  * declaration every link of that chain is.
  */
+import { isExportAssignment, isExportSpecifier, isIdentifier, isImportClause, isImportSpecifier, isNamespaceExport, isNamespaceImport, } from "@typescript/native/unstable/ast";
 import { SymbolFlags } from "@typescript/native/unstable/sync";
-import { nodeKey } from "./inventory.js";
+import { declarationsByName, nodeKey } from "./inventory.js";
+import { UNANSWERED } from "./query.js";
 /**
  * The chain walks over one project, against the declarations of `held`, the same
  * project's inventory.
@@ -14,7 +16,7 @@ import { nodeKey } from "./inventory.js";
  * library file is never fetched to find out that the inventory does not hold it.
  */
 export function aliasChains(project, held) {
-    const ownFiles = new Set(project.ownSourceFiles().map((file) => file.fileName));
+    const ownFiles = project.ownPaths();
     const steps = new Map();
     const chains = new Map();
     let asked = 0;
@@ -50,23 +52,68 @@ export function aliasChains(project, held) {
         steps.set(symbol.id, next);
         return next;
     };
+    const files = held.symbols.filter((one) => one.kind === "file").map((one) => one.id);
+    /**
+     * The declarations an alias whose step went unanswered may stand for: every one the
+     * inventory holds under its own name or the name it carries forward, and every file
+     * where it carries a module, so a use through it still counts for what it reaches.
+     */
+    const sameNamed = (alias) => {
+        const names = new Set([alias.name]);
+        let module = false;
+        for (const handle of alias.declarations) {
+            const node = ownFiles.has(handle.path) ? project.declarationAt(handle)?.node : undefined;
+            if (node === undefined) {
+                continue;
+            }
+            if ((isImportSpecifier(node) || isExportSpecifier(node)) && node.propertyName !== undefined) {
+                names.add(node.propertyName.text);
+            }
+            else if (isImportClause(node)) {
+                names.add("default");
+            }
+            else if (isNamespaceImport(node) || isNamespaceExport(node)) {
+                module = true;
+            }
+            else if (isExportAssignment(node) && isIdentifier(node.expression)) {
+                names.add(node.expression.text);
+            }
+        }
+        const byName = declarationsByName(held);
+        const ids = [...names].flatMap((name) => byName.get(name) ?? []);
+        return [...new Set([...ids, ...(module ? files : [])])].map((id) => ({
+            id,
+            stepped: true,
+            guessed: true,
+        }));
+    };
     const chainOf = (symbol) => {
         const cached = chains.get(symbol.id);
         if (cached !== undefined) {
             return cached;
         }
         const targets = [];
+        const add = (id, stepped, guessed = false) => {
+            if (!targets.some((target) => target.id === id)) {
+                targets.push({ id, stepped, guessed });
+            }
+        };
         const walked = new Set();
         let at = symbol;
         let stepped = false;
         while (at !== undefined && !walked.has(at.id)) {
             walked.add(at.id);
             for (const id of declarationsOf(at)) {
-                if (!targets.some((target) => target.id === id)) {
-                    targets.push({ id, stepped });
+                add(id, stepped);
+            }
+            const next = stepOf(at);
+            if (next === UNANSWERED) {
+                for (const target of sameNamed(at)) {
+                    add(target.id, true, true);
                 }
+                break;
             }
-            at = stepOf(at);
+            at = next;
             stepped = true;
         }
         chains.set(symbol.id, targets);
@@ -74,13 +121,18 @@ export function aliasChains(project, held) {
     };
     const nextDeclared = (symbol) => {
         const walked = new Set([symbol.id]);
+        let from = symbol;
         let at = stepOf(symbol);
-        while (at !== undefined && !walked.has(at.id)) {
+        while (at !== undefined && (at === UNANSWERED || !walked.has(at.id))) {
+            if (at === UNANSWERED) {
+                return sameNamed(from);
+            }
             walked.add(at.id);
             const ids = declarationsOf(at);
             if (ids.length > 0) {
-                return ids;
+                return ids.map((id) => ({ id, stepped: true, guessed: false }));
             }
+            from = at;
             at = stepOf(at);
         }
         return [];

package/dist/src/analysis.js

@@ -12,10 +12,10 @@ import { configuredDeclarations, configuredRef, declarationsNamed, } from "./con
 import { decorator } from "./decorator.js";
 import { dependenciesOf, projectNeeds } from "./dependencies.js";
 import { deprecatedDeclarations } from "./deprecation.js";
-import { diagnosticErrors, discoverProjects, DiscoveryError } from "./discover.js";
+import { discoverProjects, DiscoveryError, isGuess, projectErrors, renderDiagnostic, targetRelative, } from "./discover.js";
 import { readEdgeSides } from "./edges.js";
 import { enumGroup } from "./enum-group.js";
-import { computeExemptions, disabledClasses, exemptionsOf, retainedIn, } from "./exempt.js";
+import { computeExemptions, disabledClasses, exemptionsOf, isUnansweredRecord, retainedIn, } from "./exempt.js";
 import { heldByInclusion, sourceTree } from "./file-facts.js";
 import { findingsPass, recordedFindings, rowKey } from "./findings-pass.js";
 import { NO_SELF_CHECK, unmatchedRootFindings, } from "./findings/self-check.js";
@@ -63,12 +63,12 @@ function compare(a, b) {
     return a < b ? -1 : 1;
 }
 /**
- * Reads every project the scope discovers, and every project of every consumer it
- * declares, in one snapshot. Each is checked for errors first. A target project is then
- * enumerated and rooted, and `stage` reads the rest of what it needs from the project
- * while its view is open; a consumer project is read for its references to the target's
- * declarations. A project carrying an error fails the run with no answer, as every verb
- * that reads declarations does, and so does a declared consumer that cannot be loaded.
+ * Reads every project the scope discovers, and every project of each consumer it
+ * declares, in one snapshot, each checked for errors first. A target project is
+ * enumerated, rooted and handed to `stage`; a consumer project is read for its references
+ * to the target. A guess that does not load is dropped into `notBuilt` (see
+ * {@link isGuess}); any other project that does not load or carries an error fails the
+ * run, as does a run whose every guess was dropped.
  */
 function readProjects(engine, host, scope, config, stage) {
     const targetRoot = scope.target.path;
@@ -83,15 +83,31 @@ function readProjects(engine, host, scope, config, stage) {
         testFiles: config.ts.testFiles,
         publishedAPI: config.targetKind === "library",
     };
+    const absoluteRoot = resolvePath(host.workingDirectory(), targetRoot);
+    const notBuilt = [...discovered.notBuilt];
+    const dropped = (configFile, error) => {
+        notBuilt.push({
+            id: ids.get(configFile) ?? configFile,
+            configFile,
+            error: targetRelative(error, absoluteRoot),
+        });
+    };
     const failures = [];
     const consumed = new Map();
-    const { projects } = runSession(engine, [...discovered.configFiles, ...consumerOf.keys()], (project) => {
-        const errors = diagnosticErrors(diagnosticsOf(project));
-        if (errors.length > 0) {
-            failures.push(...errors);
+    const session = runSession(engine, [...discovered.configFiles, ...consumerOf.keys()], (project) => {
+        const errors = projectErrors(diagnosticsOf(project));
+        const consumer = consumerOf.get(project.configFile);
+        const [unloaded] = errors.load;
+        if (unloaded !== undefined &&
+            consumer === undefined &&
+            isGuess(discovered, project.configFile)) {
+            dropped(project.configFile, renderDiagnostic(unloaded, (path) => relativePath(absoluteRoot, path) ?? path));
+            return undefined;
+        }
+        if (errors.load.length > 0 || errors.check.length > 0) {
+            failures.push(...errors.load, ...errors.check);
             return undefined;
         }
-        const consumer = consumerOf.get(project.configFile);
         if (consumer !== undefined) {
             for (const reference of consumerReferences(project, host, targetRoot, {
                 id: consumer.id,
@@ -105,16 +121,29 @@ function readProjects(engine, host, scope, config, stage) {
         const rooted = roots(project, held, targetRoot, options);
         const configuration = ids.get(project.configFile) ?? project.configFile;
         return stage(project, { configuration, configFile: project.configFile, held, rooted });
-    });
+    }, discovered.derived ? "record" : "refuse");
+    for (const configFile of session.unopened) {
+        if (consumerOf.has(configFile) || !isGuess(discovered, configFile)) {
+            throw new DiscoveryError(`${configFile} opened no project`, []);
+        }
+        dropped(configFile, "the compiler opened no project for the configuration");
+    }
     if (failures.length > 0) {
-        throw new DiscoveryError(`${String(failures.length)} error(s); no answer was produced`, failures);
+        throw new DiscoveryError(`${String(failures.length)} error(s), so no answer was produced`, failures);
+    }
+    const answers = session.projects.filter((answer) => answer !== undefined);
+    const [first] = notBuilt;
+    if (answers.length === 0 && first !== undefined) {
+        throw new DiscoveryError(`no configuration discovery derived could be built; ${first.id}: ${first.error}`, []);
     }
     return {
-        answers: projects.filter((answer) => answer !== undefined),
+        answers,
         consumers: {
             loaded: loads.map((load) => load.consumer),
             references: [...consumed.values()],
         },
+        notBuilt,
+        unanswered: session.unanswered,
     };
 }
 /**
@@ -125,7 +154,8 @@ function readProjects(engine, host, scope, config, stage) {
  */
 export function runRoots(engine, host, scope, config, provenance) {
     const targetRoot = scope.target.path;
-    const projects = readProjects(engine, host, scope, config, (_project, read) => read).answers;
+    const read = readProjects(engine, host, scope, config, (_project, projectRead) => projectRead);
+    const projects = read.answers;
     const configurations = [];
     const merged = new Map();
     for (const answer of projects) {
@@ -159,6 +189,8 @@ export function runRoots(engine, host, scope, config, provenance) {
         configurations,
         roots: ordered,
         findings: unmatchedRootFindings(unmatched, documentOf(host, provenance, ROOTS_SETTING, targetRoot)),
+        notBuilt: read.notBuilt,
+        unanswered: read.unanswered,
     };
 }
 /** The exemption classes this analyzer detects, each by its detector; any other retains nothing. */
@@ -201,10 +233,19 @@ function readRun(engine, host, scope, config, mode, detectors, extra) {
             mode,
             testFiles: new Set(resolved.testFilePaths),
         });
+        const unanswered = [
+            ...projectRead.held.unanswered,
+            ...projectRead.rooted.unanswered,
+            ...resolved.references
+                .filter((reference) => reference.resolution === "by-name")
+                .map((reference) => reference.to),
+            ...exempt.filter(isUnansweredRecord).map((record) => record.id),
+        ];
         return {
             configFile: projectRead.configFile,
             configured,
             exempt,
+            unanswered,
             extra: extra(project, projectRead, resolved.references),
         };
     });
@@ -221,17 +262,64 @@ function readRun(engine, host, scope, config, mode, detectors, extra) {
     return {
         matrix: matrixOf(projects.map((one) => one.configured)),
         exempt: exemptionsOf(projects.flatMap((one) => one.exempt)),
+        unansweredHeld: [
+            ...new Set([
+                ...read.answers.flatMap((one) => one.unanswered),
+                ...consumed.filter((one) => one.resolution === "by-name").map((one) => one.to),
+            ]),
+        ],
         projects,
         consumers: read.consumers.loaded,
+        notBuilt: read.notBuilt,
+        unanswered: read.unanswered,
     };
 }
-/** The sweep of a run read once, under one set of marks. */
+/**
+ * The sweep of a run read once, under one set of marks. Where a question went unanswered,
+ * the run is swept once more without what that question could have kept live and without
+ * the references that stood in for its answer, and every declaration that sweep judges
+ * dead and this one judges live, or dead by another rule, is held by the gap too, as is
+ * every declaration that makes such a reference.
+ */
 function sweptOf(read, input) {
-    const swept = { ...input, exempt: read.exempt };
+    const swept = { ...input, exempt: read.exempt, unanswered: read.unansweredHeld };
+    const result = sweepMatrix(read.matrix, swept);
+    const held = new Set(read.unansweredHeld);
+    if (held.size > 0) {
+        // What a declaration reads where the checker did not answer is unknown, so a rule
+        // over what it reads, the test of dead code among them, cannot judge it.
+        for (const { configured } of read.projects) {
+            for (const reference of configured.references) {
+                if (reference.resolution === "by-name") {
+                    held.add(reference.from);
+                }
+            }
+        }
+        const dead = new Map(result.candidates.map((candidate) => [candidate.id, candidate]));
+        const answered = matrixOf(read.projects.map(({ configured }) => ({
+            ...configured,
+            references: configured.references.filter((one) => one.resolution !== "by-name"),
+        })));
+        const bare = {
+            ...swept,
+            exempt: read.exempt.filter((record) => !isUnansweredRecord(record)),
+            unanswered: [],
+        };
+        for (const candidate of sweepMatrix(answered, bare).candidates) {
+            const kept = dead.get(candidate.id);
+            if (kept?.testOfDeadCode !== candidate.testOfDeadCode ||
+                kept.relation !== candidate.relation) {
+                held.add(candidate.id);
+            }
+        }
+    }
     return {
         matrix: read.matrix,
-        sweep: sweepMatrix(read.matrix, swept),
+        sweep: result,
         retained: retainedIn(read.matrix, swept),
+        notBuilt: read.notBuilt,
+        unanswered: read.unanswered,
+        heldByUnanswered: [...held],
     };
 }
 /**
@@ -250,8 +338,8 @@ export function runSweep(engine, host, scope, config, input, detectors = DETECTO
 /** Reads a run's projects with every per-project fact an emitter reads. */
 function readEmitterRun(engine, host, scope, config, mode, detectors) {
     const targetRoot = scope.target.path;
-    return readRun(engine, host, scope, config, mode, detectors, (project, read, references) => ({
-        deprecated: deprecatedDeclarations(project, read.held),
+    const run = readRun(engine, host, scope, config, mode, detectors, (project, read, references) => ({
+        deprecation: deprecatedDeclarations(project, read.held),
         accessors: accessorsOf(project, read.held),
         needs: projectNeeds(project, read.held, host),
         implementations: implementations(project, read.held),
@@ -261,6 +349,12 @@ function readEmitterRun(engine, host, scope, config, mode, detectors) {
         declarationsNamed: declarationsNamed(project, read.held, configuredDeclarations(config)),
         parts: projectParts(project, read.held, references, targetRoot),
     }));
+    // Whether a declaration carries the marker decides its code, so one whose marker went
+    // unread is reported by nothing.
+    const unread = run.projects.flatMap((one) => one.extra.deprecation.unanswered);
+    return unread.length === 0
+        ? run
+        : { ...run, unansweredHeld: [...new Set([...run.unansweredHeld, ...unread])] };
 }
 /**
  * The input every emitter reads over one sweep of a read run: the facts beside the sweep
@@ -273,7 +367,7 @@ function emitterInputOver(host, scope, config, read, input, selfCheck) {
     return {
         config,
         swept,
-        deprecated: new Set(projects.flatMap((one) => one.extra.deprecated)),
+        deprecated: new Set(projects.flatMap((one) => one.extra.deprecation.deprecated)),
         stores: storesOf(projects.map((one) => ({
             references: one.configured.references,
             accessors: one.extra.accessors,
@@ -293,7 +387,7 @@ function emitterInputOver(host, scope, config, read, input, selfCheck) {
             edges: readEdgeSides(host, targetRoot),
         },
         selfCheck,
-        intraFunction: intraFunctionFacts(projects.map((one) => one.extra.parts), projects.flatMap((one) => one.configured.references), new Set(read.exempt.map((one) => one.id))),
+        intraFunction: intraFunctionFacts(projects.map((one) => one.extra.parts), projects.flatMap((one) => one.configured.references), new Set([...read.exempt.map((one) => one.id), ...swept.heldByUnanswered])),
     };
 }
 /**
@@ -332,6 +426,8 @@ function readAnalysis(engine, host, scope, config, provenance, mode, detectors)
             })),
             testFileRules: testFileRulesOf(config.ts.testFiles, read.projects.flatMap((one) => one.configured.testFiles)),
             consumers: read.consumers,
+            notBuilt: read.notBuilt,
+            unanswered: read.unanswered,
         },
         configured: read.projects.map((one) => one.configured),
         symbols,