@cplieger/deadset-ts 3.11.0 → 3.12.0

package/README.md

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

package/dist/src/analysis.js

@@ -7,6 +7,7 @@
  * 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 { consumerLoads, consumerReferences, moduleIdentity, } from "./consumers.js";
 import { decorator } from "./decorator.js";
 import { dependenciesOf, projectNeeds } from "./dependencies.js";
 import { deprecatedDeclarations } from "./deprecation.js";
@@ -23,7 +24,7 @@ import { injectionContainer } from "./injection-container.js";
 import { interfaceSatisfaction } from "./interface-satisfaction.js";
 import { inventory } from "./inventory.js";
 import { readManifest } from "./manifest.js";
-import { matrixOf, sweepMatrix } from "./matrix.js";
+import { matrixOf, referenceKey, sweepMatrix, } from "./matrix.js";
 import { relativePath, resolvePath } from "./paths.js";
 import { byPosition } from "./position.js";
 import { reflectiveLookup } from "./reflective-lookup.js";
@@ -59,15 +60,19 @@ function compare(a, b) {
     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.
+ * 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.
  */
 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 loads = consumerLoads(engine, host, scope, discovered.configFiles);
+    const consumerOf = new Map(loads.flatMap((load) => load.configFiles.map((configFile) => [configFile, load.consumer])));
     const options = {
         manifest: readManifest(host, targetRoot),
         patterns: config.rootPatterns,
@@ -76,12 +81,23 @@ function readProjects(engine, host, scope, config, stage) {
         publishedAPI: config.targetKind === "library",
     };
     const failures = [];
-    const { projects } = runSession(engine, discovered.configFiles, (project) => {
+    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);
             return undefined;
         }
+        const consumer = consumerOf.get(project.configFile);
+        if (consumer !== undefined) {
+            for (const reference of consumerReferences(project, host, targetRoot, {
+                id: consumer.id,
+                root: consumer.path,
+            }, config)) {
+                consumed.set(referenceKey(reference), reference);
+            }
+            return undefined;
+        }
         const held = inventory(project, host, targetRoot);
         const rooted = roots(project, held, targetRoot, options);
         const configuration = ids.get(project.configFile) ?? project.configFile;
@@ -90,7 +106,13 @@ function readProjects(engine, host, scope, config, stage) {
     if (failures.length > 0) {
         throw new DiscoveryError(`${String(failures.length)} error(s); no answer was produced`, failures);
     }
-    return projects.filter((answer) => answer !== undefined);
+    return {
+        answers: projects.filter((answer) => answer !== undefined),
+        consumers: {
+            loaded: loads.map((load) => load.consumer),
+            references: [...consumed.values()],
+        },
+    };
 }
 /**
  * The root set of the run the scope and the configuration describe.
@@ -100,7 +122,7 @@ 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);
+    const projects = readProjects(engine, host, scope, config, (_project, read) => read).answers;
     const configurations = [];
     const merged = new Map();
     for (const answer of projects) {
@@ -150,7 +172,8 @@ const DETECTORS = new Map([
 /**
  * Reads every project of the run, its references and exemptions, and `extra`'s answer,
  * while the project's view is open, and merges the projects into one matrix in the run's
- * order.
+ * order. Every configuration holds every consumer's references beside its own, because a
+ * consumer calls the target whichever configuration the target is built under.
  */
 function readRun(engine, host, scope, config, mode, detectors, extra) {
     const targetRoot = scope.target.path;
@@ -159,7 +182,7 @@ function readRun(engine, host, scope, config, mode, detectors, extra) {
         ? { delimiters: config.analysis.templateDelimiters, files: [] }
         : readTemplates(host, targetRoot, config.analysis);
     const consumers = scope.consumers.map((consumer) => consumer.path);
-    const projects = readProjects(engine, host, scope, config, (project, projectRead) => {
+    const read = readProjects(engine, host, scope, config, (project, projectRead) => {
         const resolved = references(project, projectRead.held, targetRoot, {
             testFiles: config.ts.testFiles,
         });
@@ -182,10 +205,21 @@ function readRun(engine, host, scope, config, mode, detectors, extra) {
             extra: extra(project, projectRead),
         };
     });
+    const consumed = read.consumers.references;
+    const projects = read.answers.map((one) => consumed.length === 0
+        ? one
+        : {
+            ...one,
+            configured: {
+                ...one.configured,
+                references: [...one.configured.references, ...consumed],
+            },
+        });
     return {
         matrix: matrixOf(projects.map((one) => one.configured)),
         exempt: exemptionsOf(projects.flatMap((one) => one.exempt)),
         projects,
+        consumers: read.consumers.loaded,
     };
 }
 /** The sweep of a run read once, under one set of marks. */
@@ -246,7 +280,10 @@ function emitterInputOver(host, scope, config, read, input, selfCheck) {
             heldByInclusion: new Set(projects.flatMap((one) => one.extra.heldByInclusion)),
         },
         boundary: {
-            consumers: { declared: scope.consumers.map((consumer) => consumer.id), loaded: [] },
+            consumers: {
+                declared: scope.consumers.map((consumer) => moduleIdentity(host, consumer)),
+                loaded: read.consumers.map((consumer) => consumer.id),
+            },
             encapsulated: readManifest(host, targetRoot).declaresExports,
             edges: readEdgeSides(host, targetRoot),
         },
@@ -257,8 +294,8 @@ function emitterInputOver(host, scope, config, read, input, selfCheck) {
  * 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 loads no consumer, and it reads no suppression document, so the
- * self-check family has nothing to report.
+ * 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);
@@ -303,6 +340,7 @@ function runAnalysisInputs(engine, host, scope, config, provenance, mode, detect
                 configFile: one.configFile,
             })),
             testFileRules: testFileRulesOf(config.ts.testFiles, read.projects.flatMap((one) => one.configured.testFiles)),
+            consumers: read.consumers,
         },
         configured: read.projects.map((one) => one.configured),
     };

package/dist/src/conformance-record.js

@@ -3,8 +3,8 @@
 export const RECORD = {
     conformance: {
         corpusVersion: "1.9.0",
-        result: "fail",
-        digest: "sha256:8c29f19fc189f4f5d9ea210d556b62d12c3701c221eb7a8adde499b7060bec0d",
+        result: "pass",
+        digest: "sha256:3e9e40876551faa2c196311bf06d47d220ab5127a9fb8921969aae552c42e824",
     },
     gaps: [
         {
@@ -12,15 +12,5 @@ export const RECORD = {
             capability: "reflective-lookup",
             reason: "The reference pass resolves a string-literal element access to the member it names, so the member is live by that reference and the retained listing names no class for it.",
         },
-        {
-            fixture: "redundant-export-keyword",
-            capability: "DS1104",
-            reason: "No consumer is loaded beside the target, so the published surface is unknown and no export is narrowed; review an export only the target uses by hand.",
-        },
-        {
-            fixture: "unused-exported-consumer",
-            capability: "DS1001",
-            reason: "No consumer is loaded beside the target, so an export nothing in the target references is reported at the possible class rather than the certain one.",
-        },
     ],
 };

package/dist/src/consumers.js

@@ -0,0 +1,49 @@
+/**
+ * The consumers a scope declares, loaded beside the target: each a directory on the
+ * local filesystem whose compiler configurations open as projects of the run's one
+ * snapshot, and whose references to the target's declarations count against them.
+ */
+import { consumerProjects } from "./discover.js";
+import { inventory, packageScope } from "./inventory.js";
+import { relativePath } from "./paths.js";
+import { references } from "./references.js";
+import { narrowedTo } from "./session.js";
+/** The name one module publishes itself under: the scope's, else its manifest's. */
+export function moduleIdentity(host, module) {
+    return module.id === "" ? packageScope(host, module.path)("index.ts").package : module.id;
+}
+/**
+ * Every consumer the scope declares, in its order, with the projects it opens as. A
+ * configuration that is also one of the target's projects, or an earlier consumer's, is
+ * that project's alone. A consumer whose directory is absent, is no directory or holds
+ * no configuration ends the run naming it, before any project opens.
+ */
+export function consumerLoads(engine, host, scope, targetConfigFiles) {
+    const opened = new Set(targetConfigFiles);
+    return scope.consumers.map((module) => {
+        const configFiles = consumerProjects(engine, host, module.path).filter((configFile) => {
+            const fresh = !opened.has(configFile);
+            opened.add(configFile);
+            return fresh;
+        });
+        return { consumer: { id: moduleIdentity(host, module), path: module.path }, configFiles };
+    });
+}
+/**
+ * Every reference one consumer project's own files make to a declaration of the target.
+ * The target's declarations are enumerated over the target's files the consumer's
+ * program holds, against the target root, so each carries the identifier the target's
+ * own projects give it. A reference from a consumer's test file is a test reference
+ * unless the configuration counts it as a production one.
+ */
+export function consumerReferences(project, host, targetRoot, consumer, config) {
+    const held = inventory(narrowedTo(project, (file) => relativePath(targetRoot, file.fileName) !== undefined), host, targetRoot);
+    const found = references(project, held, targetRoot, {
+        testFiles: config.ts.testFiles,
+        consumer,
+    }).references;
+    if (config.analysis.consumerTests !== "production") {
+        return found;
+    }
+    return found.map((reference) => (reference.test ? { ...reference, test: false } : reference));
+}

package/dist/src/discover.js

@@ -117,16 +117,61 @@ function referencesOf(host, configFile) {
     return found;
 }
 /**
- * The configuration files the scope names directly: one per module the scope
- * declares whose path names a configuration file rather than a directory. A module
- * naming a directory is reached by the walk over that directory instead.
+ * The configuration file the scope names for the target directly, where its path
+ * names one rather than a directory. A target naming a directory is reached by the
+ * walk over that directory instead. A consumer's projects are a consumer's, never the
+ * target's, so no consumer path is read here.
  */
 function scopeConfigFiles(host, scope) {
-    return [scope.target, ...scope.consumers]
-        .map((module) => module.path)
+    return [scope.target.path]
         .filter((path) => path.endsWith(".json"))
         .map((path) => resolvePath(host.workingDirectory(), path));
 }
+/**
+ * Every configuration file reached from `pending`, in the order discovery reads them:
+ * each once, each followed by the configurations it references, transitively. A
+ * configuration the compiler cannot read ends the run naming it.
+ */
+function derivedFrom(engine, host, pending) {
+    const seen = new Set();
+    const found = [];
+    while (pending.length > 0) {
+        const configFile = pending.shift();
+        if (configFile === undefined) {
+            break;
+        }
+        const path = resolvePath(host.workingDirectory(), configFile);
+        if (seen.has(path)) {
+            continue;
+        }
+        seen.add(path);
+        parseOrRefuse(engine, path, path);
+        found.push(path);
+        pending.push(...referencesOf(host, path));
+    }
+    return found;
+}
+/**
+ * The compiler configurations one consumer is loaded through: every one under its
+ * root that is not inside an ignored directory, and the configurations each of those
+ * references, transitively, in that order. A root that is absent, that is no
+ * directory, or that holds no configuration ends the run naming it, because a
+ * finding computed without a declared consumer would claim a reference set the run
+ * never read.
+ */
+export function consumerProjects(engine, host, root) {
+    const kind = host.kindOf(root);
+    if (kind !== "directory") {
+        throw new DiscoveryError(kind === "absent"
+            ? `the consumer ${root} does not exist`
+            : `the consumer ${root} is not a directory`, []);
+    }
+    const found = derivedFrom(engine, host, configFilesUnder(host, root));
+    if (found.length === 0) {
+        throw new DiscoveryError(`the consumer ${root} holds no compiler configuration, so none of its references can be read`, []);
+    }
+    return found;
+}
 /**
  * The name a derived project carries: its configuration file's path below the target
  * root, or the absolute path of a file outside it.
@@ -197,24 +242,15 @@ function declaredProjects(engine, host, targetRoot, entries) {
  */
 function derivedProjects(engine, host, scope) {
     const fromScope = scopeConfigFiles(host, scope);
-    const seen = new Set();
-    const projects = [];
-    const pending = [...fromScope, ...configFilesUnder(host, scope.target.path)];
-    while (pending.length > 0) {
-        const configFile = pending.shift();
-        if (configFile === undefined) {
-            break;
-        }
-        const path = resolvePath(host.workingDirectory(), configFile);
-        if (seen.has(path)) {
-            continue;
-        }
-        seen.add(path);
-        parseOrRefuse(engine, path, path);
-        projects.push({ id: derivedId(scope.target.path, path), configFile: path });
-        pending.push(...referencesOf(host, path));
-    }
-    return { projects, configFiles: projects.map((project) => project.configFile), fromScope };
+    const configFiles = derivedFrom(engine, host, [
+        ...fromScope,
+        ...configFilesUnder(host, scope.target.path),
+    ]);
+    const projects = configFiles.map((configFile) => ({
+        id: derivedId(scope.target.path, configFile),
+        configFile,
+    }));
+    return { projects, configFiles, fromScope };
 }
 /**
  * Every project one run analyzes.

package/dist/src/findings/completion.js

@@ -14,26 +14,57 @@ const RANK = { certain: 3, probable: 2, possible: 1 };
 function capped(found, ceiling) {
     return RANK[found] <= RANK[ceiling] ? found : ceiling;
 }
+/** The kind whose default turns on what the run knows about the target's consumers. */
+const UNUSED_EXPORTED = "DS1001";
+/** Whether the run loaded every consumer the scope declared, which holds of a scope declaring none. */
+function everyDeclaredLoaded(boundary) {
+    const { declared, loaded } = boundary.consumers;
+    return declared.every((id) => loaded.includes(id));
+}
+/**
+ * Whether a library's published API may have a caller the run cannot see: the target is
+ * a library, and the run either holds no consumer information or did not load a consumer
+ * the scope declared. A configuration declaring the consumer set complete holds consumer
+ * information whether or not it declares a consumer, because it says no other exists.
+ */
+function openWorld(input) {
+    const known = input.config.consumersComplete || input.boundary.consumers.declared.length > 0;
+    return input.config.targetKind === "library" && !(known && everyDeclaredLoaded(input.boundary));
+}
 /**
  * The severity the configuration gives one code: the key naming the code, else the key
- * naming its family, else the code's default.
+ * naming its family, else the code's default. The unused-exported kind defaults to
+ * `allow` while a library's published API is open to callers the run cannot see.
  */
-function severityOf(config, code, fallback) {
-    return (config.severity.get(code) ?? config.severity.get(code.slice(0, FAMILY_KEY_LENGTH)) ?? fallback);
+function severityOf(input, code, fallback) {
+    const { config } = input;
+    const named = config.severity.get(code) ?? config.severity.get(code.slice(0, FAMILY_KEY_LENGTH));
+    if (named !== undefined) {
+        return named;
+    }
+    return code === UNUSED_EXPORTED && openWorld(input) ? "allow" : fallback;
 }
 /**
  * The reachability class of one declaration of the run. A declaration of a library's
- * published API has callers outside the target, and the run loads no consumer that
- * would name them, so it is `possible`; every other declaration has every reference
- * in the loaded program, a private member and a `#private` name among them, and is
- * `certain`.
+ * published API has callers outside the target: it is `certain` where the run loaded
+ * every consumer the scope declared and declared at least one, `probable` where it
+ * declared consumers and did not load them all, and `possible` where it declared none.
+ * Whether the configuration declares the consumer set complete decides nothing here.
+ * Every other declaration has every reference in the loaded program, a private member
+ * and a `#private` name among them, and is `certain`.
  */
-function reachabilityClasses(swept) {
-    const union = swept.matrix.union;
+function reachabilityClasses(input) {
+    const union = input.swept.matrix.union;
     const published = new Set(union.rooted
         .filter((root) => root.kind === "published-api")
         .map((root) => union.symbols[root.at]?.id));
-    return (id) => (published.has(id) ? "possible" : "certain");
+    const { declared } = input.boundary.consumers;
+    const outside = declared.length === 0
+        ? "possible"
+        : everyDeclaredLoaded(input.boundary)
+            ? "certain"
+            : "probable";
+    return (id) => (published.has(id) ? outside : "certain");
 }
 /** The component each dead declaration of the run falls in, and none for a live one. */
 function findingComponents(swept) {
@@ -61,18 +92,19 @@ function findingComponents(swept) {
  * relation and holds where it is declared; a file or a manifest row is `certain` and
  * holds in every configuration. A subject in no dead component gets one of its own,
  * numbered past the computed ones in finding order, so no two families mint one; nothing
- * falls with it, so its deletion removes no line.
+ * falls with it, so its deletion removes no line. `kinds` is the vocabulary each code's
+ * row is read from, the shipped one unless a caller supplies its own.
  */
-export function completed(input, findings) {
+export function completed(input, findings, kinds = KINDS) {
     const { swept } = input;
     const union = swept.matrix.union;
     const positions = new Map(union.symbols.map((symbol, at) => [symbol.ref, at]));
     const candidates = new Map(swept.sweep.candidates.map((candidate) => [candidate.id, candidate]));
-    const classOf = reachabilityClasses(swept);
+    const classOf = reachabilityClasses(input);
     const componentOf = findingComponents(swept);
     let minted = swept.sweep.components.length;
     return findings.map((finding) => {
-        const row = KINDS.get(finding.code);
+        const row = kinds.get(finding.code);
         if (row === undefined) {
             throw new Error(`${finding.code} names no live row of the issue-kind vocabulary`);
         }
@@ -119,7 +151,7 @@ export function completed(input, findings) {
                 (judged === undefined ? swept.matrix.configurations : (swept.matrix.heldIn[at] ?? [])),
             consumersLoaded: input.boundary.consumers.loaded,
             fixability: row.fixability,
-            severity: severityOf(input.config, finding.code, row.defaultSeverity),
+            severity: severityOf(input, finding.code, row.defaultSeverity),
             message: finding.message,
             details: finding.details ?? {},
         };
@@ -139,7 +171,7 @@ function dialed(finding, minConfidence) {
  */
 export function dialsOf(input, findings) {
     const minConfidence = input.config.analysis.minConfidence;
-    const classOf = reachabilityClasses(input.swept);
+    const classOf = reachabilityClasses(input);
     const components = new Set(findings
         .filter((finding) => finding.component.root && dialed(finding, minConfidence))
         .map((finding) => finding.component.id));
@@ -148,7 +180,7 @@ export function dialsOf(input, findings) {
             const row = KINDS.get(code);
             return (row !== undefined &&
                 dialed({
-                    severity: severityOf(input.config, code, row.defaultSeverity),
+                    severity: severityOf(input, code, row.defaultSeverity),
                     confidence: capped(classOf(id), row.maxClass),
                 }, minConfidence));
         },

package/dist/src/findings/non-code-artifacts.js

@@ -44,11 +44,18 @@ function fileNeverBuilt({ config, swept, files }) {
 }
 /**
  * The paths of every file a reference written in another file reaches, naming the
- * file or a declaration in it. An import is such a reference, so an import from any
- * file reaches what it names, whatever reaches the importing file.
+ * file or a declaration in it, a loaded consumer's file included. An import is such a
+ * reference, so an import from any file reaches what it names, whatever reaches the
+ * importing file.
  */
 function reachedFromOutside(union) {
     const reached = new Set();
+    for (const edge of union.consumed) {
+        const to = union.symbols[edge.to];
+        if (to !== undefined) {
+            reached.add(to.position.path);
+        }
+    }
     union.out.forEach((edges, from) => {
         const fromPath = union.symbols[from]?.position.path;
         for (const edge of edges) {

package/dist/src/findings/reads-and-writes.js

@@ -63,7 +63,9 @@ function writeOnlySymbols(run) {
             held = { writes: [], reads: 0 };
             uses.set(reference.to, held);
         }
-        if (reference.use !== "write") {
+        // A consumer's store is written at a position no report of the target can name, so
+        // it counts as a use that keeps the declaration from this kind.
+        if (reference.use !== "write" || reference.consumer !== undefined) {
             held.reads += 1;
             continue;
         }

package/dist/src/graph.js

@@ -71,6 +71,7 @@ export function graphOf(symbols, references, roots, testFiles) {
     const tests = new Set(testFiles);
     const out = symbols.map(() => []);
     const made = symbols.map(() => ({ production: 0, test: 0 }));
+    const consumed = [];
     for (const reference of references) {
         const to = at(reference.to);
         if (to === OUTSIDE) {
@@ -85,11 +86,12 @@ export function graphOf(symbols, references, roots, testFiles) {
                 counts.production += 1;
             }
         }
-        out[at(reference.from)]?.push({
-            to,
-            test: reference.test,
-            evaluation: reference.use === "evaluation",
-        });
+        const edge = { to, test: reference.test, evaluation: reference.use === "evaluation" };
+        if (reference.consumer !== undefined) {
+            consumed.push(edge);
+            continue;
+        }
+        out[at(reference.from)]?.push(edge);
     }
     const parent = symbols.map((symbol) => at(symbol.parent));
     const exportsOf = symbols.map(() => []);
@@ -115,6 +117,7 @@ export function graphOf(symbols, references, roots, testFiles) {
         subject: symbols.map((symbol) => swept(symbol.kind)),
         exportsOf,
         rooted,
+        consumed,
         at,
     };
 }

package/dist/src/matrix.js

@@ -14,10 +14,21 @@ function compare(a, b) {
     }
     return a < b ? -1 : 1;
 }
-/** What makes one reference one reference, whichever configuration made it. */
-function referenceKey(reference) {
+/**
+ * What makes one reference one reference, whichever configuration made it. A consumer's
+ * position is rendered against its own root, so the consumer is part of what it names.
+ */
+export function referenceKey(reference) {
     const { path, line, column } = reference.position;
-    return [reference.from, reference.to, path, String(line), String(column), reference.use].join("\u0000");
+    return [
+        reference.consumer ?? "",
+        reference.from,
+        reference.to,
+        path,
+        String(line),
+        String(column),
+        reference.use,
+    ].join("\u0000");
 }
 /**
  * Indexes what the passes answered for each configuration of one run, in the run's order.