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

package/dist/bin/node-host.js

@@ -1,5 +1,6 @@
-import { readdirSync, readFileSync, statSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { closeSync, fchmodSync, fsyncSync, openSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 /** The name the manifest of this package declares. */
 const PACKAGE_NAME = "@cplieger/deadset-ts";
@@ -43,6 +44,34 @@ function readVersion() {
         at = up;
     }
 }
+/** 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.
+ */
+function writeAtomically(path, text) {
+    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);
+            }
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(temporary, path);
+    }
+    catch (error) {
+        rmSync(temporary, { force: true });
+        throw error;
+    }
+}
 /**
  * The filesystem of the platform the command runs on, and the version of the
  * package it was installed from.
@@ -70,5 +99,6 @@ export function nodeHost() {
             found ??= readVersion();
             return found;
         },
+        writeFile: writeAtomically,
     };
 }

package/dist/src/analysis.js

@@ -11,9 +11,12 @@ import { decorator } from "./decorator.js";
 import { dependenciesOf, projectNeeds } from "./dependencies.js";
 import { deprecatedDeclarations } from "./deprecation.js";
 import { diagnosticErrors, discoverProjects, DiscoveryError } from "./discover.js";
+import { readEdgeSides } from "./edges.js";
 import { enumGroup } from "./enum-group.js";
 import { computeExemptions, disabledClasses, exemptionsOf, retainedIn, } from "./exempt.js";
 import { heldByInclusion, sourceTree } from "./file-facts.js";
+import { findingsPass } from "./findings-pass.js";
+import { NO_SELF_CHECK, unmatchedRootFindings, } from "./findings/self-check.js";
 import { frameworkLifecycle } from "./framework-lifecycle.js";
 import { implementations, mergeImplementations } from "./implementations.js";
 import { injectionContainer } from "./injection-container.js";
@@ -24,11 +27,13 @@ import { matrixOf, sweepMatrix } from "./matrix.js";
 import { relativePath, resolvePath } from "./paths.js";
 import { byPosition } from "./position.js";
 import { reflectiveLookup } from "./reflective-lookup.js";
-import { references } from "./references.js";
-import { roots, unmatchedEverywhere, unmatchedRoots } from "./roots.js";
+import { references, testFileRulesOf } from "./references.js";
+import { roots, unmatchedEverywhere } from "./roots.js";
 import { serializationContract } from "./serialization-contract.js";
 import { diagnosticsOf, runSession } from "./session.js";
 import { accessorsOf, storesOf } from "./stores.js";
+import { readBaseline, readIgnoreFile } from "./suppress-file.js";
+import { inlineDirectives, inlineSuppressions } from "./suppress-inline.js";
 import { readTemplates, templateField } from "./template-field.js";
 /** The setting whose source decides where a finding about a configured root sits. */
 const ROOTS_SETTING = "roots.patterns";
@@ -80,7 +85,7 @@ function readProjects(engine, host, scope, config, stage) {
         const held = inventory(project, host, targetRoot);
         const rooted = roots(project, held, targetRoot, options);
         const configuration = ids.get(project.configFile) ?? project.configFile;
-        return stage(project, { configuration, held, rooted });
+        return stage(project, { configuration, configFile: project.configFile, held, rooted });
     });
     if (failures.length > 0) {
         throw new DiscoveryError(`${String(failures.length)} error(s); no answer was produced`, failures);
@@ -128,7 +133,7 @@ export function runRoots(engine, host, scope, config, provenance) {
     return {
         configurations,
         roots: ordered,
-        findings: unmatchedRoots(unmatched, documentOf(host, provenance, ROOTS_SETTING, targetRoot)),
+        findings: unmatchedRootFindings(unmatched, documentOf(host, provenance, ROOTS_SETTING, targetRoot)),
     };
 }
 /** The exemption classes this analyzer detects, each by its detector; any other retains nothing. */
@@ -143,10 +148,11 @@ const DETECTORS = new Map([
     ["serialization-contract", serializationContract],
 ]);
 /**
- * Sweeps the run, reading each project's references and exemptions, and `extra`'s
- * answer, while the project's view is open.
+ * 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.
  */
-function sweepRun(engine, host, scope, config, input, detectors, extra) {
+function readRun(engine, host, scope, config, mode, detectors, extra) {
     const targetRoot = scope.target.path;
     const disabled = disabledClasses(config);
     const templates = disabled.has("template-field")
@@ -166,20 +172,31 @@ function sweepRun(engine, host, scope, config, input, detectors, extra) {
         };
         const exempt = computeExemptions({ project, held: projectRead.held, targetRoot, templates, ts: config.ts, consumers }, detectors, {
             disabled,
-            mode: input.mode,
+            mode,
             testFiles: new Set(resolved.testFilePaths),
         });
-        return { configured, exempt, extra: extra(project, projectRead) };
+        return {
+            configFile: projectRead.configFile,
+            configured,
+            exempt,
+            extra: extra(project, projectRead),
+        };
     });
-    const matrix = matrixOf(projects.map((one) => one.configured));
-    const exempt = exemptionsOf(projects.flatMap((one) => one.exempt));
-    const swept = { ...input, exempt };
     return {
-        swept: { matrix, sweep: sweepMatrix(matrix, swept), retained: retainedIn(matrix, swept) },
-        exempt,
+        matrix: matrixOf(projects.map((one) => one.configured)),
+        exempt: exemptionsOf(projects.flatMap((one) => one.exempt)),
         projects,
     };
 }
+/** The sweep of a run read once, under one set of marks. */
+function sweptOf(read, input) {
+    const swept = { ...input, exempt: read.exempt };
+    return {
+        matrix: read.matrix,
+        sweep: sweepMatrix(read.matrix, swept),
+        retained: retainedIn(read.matrix, swept),
+    };
+}
 /**
  * Sweeps the run the scope and the configuration describe. Each project's references
  * and exemptions are read against its own inventory while its view is open; the
@@ -191,24 +208,29 @@ function sweepRun(engine, host, scope, config, input, detectors, extra) {
  * project is swept.
  */
 export function runSweep(engine, host, scope, config, input, detectors = DETECTORS) {
-    return sweepRun(engine, host, scope, config, input, detectors, () => undefined).swept;
+    return sweptOf(readRun(engine, host, scope, config, input.mode, detectors, () => undefined), input);
 }
-/**
- * What every emitter reads of the run the scope and the configuration describe: the
- * run's sweep, and the facts beside it each kind family reads, every per-project one
- * read in the same session as the sweep. The run loads no consumer and reads no
- * declared cross-language edge, so its boundary names neither.
- */
-export function runEmitterInput(engine, host, scope, config, input, detectors = DETECTORS) {
+/** 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;
-    const run = sweepRun(engine, host, scope, config, input, detectors, (project, read) => ({
+    return readRun(engine, host, scope, config, mode, detectors, (project, read) => ({
         deprecated: deprecatedDeclarations(project, read.held),
         accessors: accessorsOf(project, read.held),
         needs: projectNeeds(project, read.held, host),
         implementations: implementations(project, read.held),
         heldByInclusion: heldByInclusion(project, targetRoot),
+        rooted: read.rooted,
+        directives: inlineDirectives(project, read.held, targetRoot),
     }));
-    const { swept, projects } = run;
+}
+/**
+ * The input every emitter reads over one sweep of a read run: the facts beside the sweep
+ * each kind family reads, every per-project one read in the same session as the sweep.
+ */
+function emitterInputOver(host, scope, config, read, input, selfCheck) {
+    const targetRoot = scope.target.path;
+    const swept = sweptOf(read, input);
+    const { projects } = read;
     return {
         config,
         swept,
@@ -216,7 +238,7 @@ export function runEmitterInput(engine, host, scope, config, input, detectors =
         stores: storesOf(projects.map((one) => ({
             references: one.configured.references,
             accessors: one.extra.accessors,
-        })), run.exempt, input.mode),
+        })), read.exempt, input.mode),
         dependencies: dependenciesOf(host, targetRoot, projects.map((one) => one.extra.needs), swept.sweep.candidates.map((candidate) => candidate.id)),
         implementations: mergeImplementations(projects.map((one) => one.extra.implementations)),
         files: {
@@ -226,7 +248,70 @@ export function runEmitterInput(engine, host, scope, config, input, detectors =
         boundary: {
             consumers: { declared: scope.consumers.map((consumer) => consumer.id), loaded: [] },
             encapsulated: readManifest(host, targetRoot).declaresExports,
-            edges: [],
+            edges: readEdgeSides(host, targetRoot),
+        },
+        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.
+ */
+export function runEmitterInput(engine, host, scope, config, input, detectors = DETECTORS) {
+    const read = readEmitterRun(engine, host, scope, config, input.mode, detectors);
+    return emitterInputOver(host, scope, config, read, input, NO_SELF_CHECK);
+}
+/**
+ * Reads the run the scope and the configuration describe for its findings. The inline
+ * directives, the ignore file's entries and the baseline's rows are read and bound before
+ * any sweep, and the run is swept once under every bound record's mark and once under
+ * none, so a record is decided against the finding its code would have produced. The
+ * self-check family reports the refused suppressions and the roots that named nothing.
+ * Beside the inputs it answers the projects and test-file rules a report names.
+ */
+function runAnalysisInputs(engine, host, scope, config, provenance, mode, detectors) {
+    const targetRoot = scope.target.path;
+    const read = readEmitterRun(engine, host, scope, config, mode, detectors);
+    const symbols = read.matrix.union.symbols;
+    const documents = [
+        inlineSuppressions(read.projects.map((one) => one.extra.directives)),
+        readIgnoreFile(host, targetRoot, symbols),
+        readBaseline(host, targetRoot, symbols),
+    ];
+    const suppressions = {
+        records: documents.flatMap((one) => one.records),
+        refusals: documents.flatMap((one) => one.refusals),
+    };
+    const facts = {
+        refusals: suppressions.refusals,
+        unmatchedRoots: unmatchedEverywhere(config.rootPatterns, read.projects.map((one) => one.extra.rooted)),
+        rootsDocument: documentOf(host, provenance, ROOTS_SETTING, targetRoot),
+    };
+    const marked = [...new Set(suppressions.records.map((record) => record.bound))].filter((id) => id !== "");
+    return {
+        inputs: {
+            marked: emitterInputOver(host, scope, config, read, { marked, mode }, facts),
+            unmarked: emitterInputOver(host, scope, config, read, { marked: [], mode }, facts),
+            suppressions,
+        },
+        run: {
+            projects: read.projects.map((one) => ({
+                id: one.configured.configuration,
+                configFile: one.configFile,
+            })),
+            testFileRules: testFileRulesOf(config.ts.testFiles, read.projects.flatMap((one) => one.configured.testFiles)),
         },
     };
 }
+/**
+ * The analysis of the run the scope and the configuration describe: the run read with its
+ * suppressions bound, every family's findings with the suppressions applied and the
+ * declared edges evaluated, and the projects and test-file rules the report names.
+ */
+export function runAnalysis(engine, host, scope, config, provenance, mode, detectors = DETECTORS) {
+    const { inputs, run } = runAnalysisInputs(engine, host, scope, config, provenance, mode, detectors);
+    return { result: findingsPass(inputs), run };
+}

package/dist/src/conformance.js

@@ -0,0 +1,22 @@
+/**
+ * What this analyzer states about its own conformance: the corpus version it is written
+ * against and its recorded result over that corpus, which `describe` and every report name.
+ */
+/** The version of the conformance corpus this analyzer is written against. */
+const CORPUS_VERSION = "1.9.0";
+/** The SHA-256 of zero bytes, which is the digest of a results document no run wrote. */
+const EMPTY_DIGEST = "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+/**
+ * The conformance run this analyzer records, or undefined where it records none. A
+ * description states exactly this, so a reader that requires a pass refuses an analyzer
+ * that has not answered the corpus.
+ */
+export const RECORDED_CONFORMANCE = undefined;
+/**
+ * The conformance a report states. A report requires the block, so an analyzer that
+ * records no run states a failed one over the results document no run wrote, which a merge
+ * refuses as it refuses any result other than a pass.
+ */
+export function reportedConformance(recorded) {
+    return recorded ?? { corpusVersion: CORPUS_VERSION, result: "fail", digest: EMPTY_DIGEST };
+}

package/dist/src/edges.js

@@ -0,0 +1,190 @@
+/**
+ * Declared cross-language edges: the sides of the target's edges document that name a
+ * symbol of this language, and the evaluation the report publishes for each. This analyzer
+ * never resolves the paired symbol: the other language's analyzer decides whether the
+ * pairing is a use, and the merge reads the two evaluations together.
+ */
+import { ConfigError } from "./config.js";
+import { positionAt, walkDocument } from "./json-document.js";
+import { joinPath } from "./paths.js";
+import { positionKey } from "./position.js";
+/** The name and the location the Contract fixes for the edges document. */
+export const EDGES_FILE = "deadset-edges.json";
+/** The language prefix of every reference this analyzer evaluates. */
+const OWN_PREFIX = "ts://";
+/** The closed key list of the document and of one edge. */
+const DOCUMENT_KEYS = new Set(["description", "edges"]);
+const EDGE_KEYS = new Set(["id", "because", "provides", "used_by"]);
+/** An edge identifier: solidus-separated segments of ASCII letters, digits, `_`, `.` and `-`. */
+const ID_FORM = /^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/u;
+/** A reference naming one symbol of some language: `<language>://<scope>#<fragment>`. */
+const REFERENCE_FORM = /^[a-z][a-z0-9]*:\/\/[^ \t\r\n#]+#[^ \t\r\n]*$/u;
+const DOCUMENT_WANT = "an object carrying the edges array, and an optional description";
+const EDGE_WANT = "an edge naming id, provides and used_by, each a string, and an optional because";
+const ID_WANT = "one or more solidus-separated segments of ASCII letters, digits, underscore, full stop and hyphen";
+const REFERENCE_WANT = "a stable symbol reference naming one symbol exactly, <language>://<scope>#<fragment>";
+/** An edges document the Contract refuses: a malformed input, answered with the usage code. */
+export class EdgesError extends ConfigError {
+    constructor(at, text, want) {
+        super("malformed", EDGES_FILE, `${at}: ${text}: want ${want}`);
+        this.name = "EdgesError";
+    }
+}
+/**
+ * Whether a reference carries a wildcard outside a quoted or a computed component, which
+ * would name a set of symbols rather than one.
+ */
+function carriesWildcard(ref) {
+    let quoted = false;
+    let computed = false;
+    let escaped = false;
+    for (const char of ref) {
+        if (escaped) {
+            escaped = false;
+        }
+        else if (quoted && char === "\\") {
+            escaped = true;
+        }
+        else if (quoted) {
+            quoted = char !== "'";
+        }
+        else if (computed) {
+            computed = char !== "]";
+        }
+        else if (char === "'") {
+            quoted = true;
+        }
+        else if (char === "[") {
+            computed = true;
+        }
+        else if (char === "*") {
+            return true;
+        }
+    }
+    return false;
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** One edge, checked: the closed key list, the value types and the value forms. */
+function readEdge(value, at) {
+    const refuse = (text, want) => {
+        throw new EdgesError(at, text, want);
+    };
+    if (!isObject(value)) {
+        return refuse(JSON.stringify(value), EDGE_WANT);
+    }
+    for (const [key, held] of Object.entries(value)) {
+        if (!EDGE_KEYS.has(key) || typeof held !== "string") {
+            refuse(`the member ${JSON.stringify(key)} holding ${JSON.stringify(held)}`, EDGE_WANT);
+        }
+    }
+    const edge = value;
+    const id = edge["id"] ?? refuse("an edge naming no id", EDGE_WANT);
+    const provides = edge["provides"] ?? refuse("an edge naming no provides side", EDGE_WANT);
+    const usedBy = edge["used_by"] ?? refuse("an edge naming no used_by side", EDGE_WANT);
+    if (!ID_FORM.test(id)) {
+        refuse(JSON.stringify(id), ID_WANT);
+    }
+    for (const ref of [provides, usedBy]) {
+        if (!REFERENCE_FORM.test(ref) || carriesWildcard(ref)) {
+            refuse(JSON.stringify(ref), REFERENCE_WANT);
+        }
+    }
+    return { id, provides, usedBy };
+}
+/**
+ * Every side of a declared edge that names a symbol of this language, in document order,
+ * `provides` before `used_by` within an edge. An absent document declares no edge. The
+ * document is strict JSON with a closed key list at both levels, and a defect in it is an
+ * {@link EdgesError}.
+ */
+export function readEdgeSides(host, targetRoot) {
+    const file = joinPath(targetRoot, EDGES_FILE);
+    if (host.kindOf(file) === "absent") {
+        return [];
+    }
+    const text = host.readFile(file);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new EdgesError(EDGES_FILE, error instanceof Error ? error.message : String(error), DOCUMENT_WANT);
+    }
+    if (!isObject(parsed)) {
+        throw new EdgesError(EDGES_FILE, JSON.stringify(parsed), DOCUMENT_WANT);
+    }
+    const walk = walkDocument(text, "edges");
+    if (walk.twice !== undefined) {
+        throw new EdgesError(positionKey(positionAt(text, EDGES_FILE, walk.twice.offset)), `the member ${JSON.stringify(walk.twice.name)} is written twice, so neither value is chosen`, DOCUMENT_WANT);
+    }
+    const unknown = Object.keys(parsed).find((key) => !DOCUMENT_KEYS.has(key));
+    const description = parsed["description"];
+    const edges = parsed["edges"];
+    if (unknown !== undefined ||
+        (description !== undefined && typeof description !== "string") ||
+        !Array.isArray(edges)) {
+        throw new EdgesError(EDGES_FILE, unknown === undefined ? EDGES_FILE : `the member ${JSON.stringify(unknown)}`, DOCUMENT_WANT);
+    }
+    const sides = [];
+    edges.forEach((value, index) => {
+        const offset = walk.opened[index];
+        const at = offset === undefined ? EDGES_FILE : positionKey(positionAt(text, EDGES_FILE, offset));
+        const edge = readEdge(value, at);
+        const named = [
+            ["provides", edge.provides],
+            ["used_by", edge.usedBy],
+        ];
+        for (const [side, symbol] of named) {
+            if (symbol.startsWith(OWN_PREFIX)) {
+                sides.push({ edge: edge.id, side, symbol });
+            }
+        }
+    });
+    return sides;
+}
+/** Two strings ordered bytewise. */
+function compare(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    return a < b ? -1 : 1;
+}
+/**
+ * Evaluates every declared side of this language over the run's findings. A side naming a
+ * symbol the run enumerates nothing under is `absent`; one naming a symbol the run holds a
+ * finding about is `dead` and carries that finding, pending until a merge reads the other
+ * side and reported nowhere else, a narrowing finding included; any other is `live`.
+ */
+export function evaluateEdges(findings, sides, symbols) {
+    if (sides.length === 0) {
+        return { findings, evaluations: [] };
+    }
+    const byRef = new Map();
+    for (const symbol of symbols) {
+        if (symbol.kind !== "file" && !byRef.has(symbol.ref)) {
+            byRef.set(symbol.ref, symbol.id);
+        }
+    }
+    const held = new Map();
+    findings.forEach((finding, at) => {
+        held.set(positionKey(finding.position), at);
+    });
+    const pending = new Set();
+    const evaluations = sides.map((side) => {
+        const id = byRef.get(side.symbol);
+        if (id === undefined) {
+            return { ...side, state: "absent" };
+        }
+        const at = held.get(id);
+        const finding = at === undefined ? undefined : findings[at];
+        if (at === undefined || finding === undefined) {
+            return { ...side, state: "live" };
+        }
+        pending.add(at);
+        return { ...side, state: "dead", finding };
+    });
+    evaluations.sort((a, b) => compare(a.edge, b.edge) || compare(a.side, b.side));
+    return { findings: findings.filter((_finding, at) => !pending.has(at)), evaluations };
+}

package/dist/src/findings/completion.js

@@ -7,6 +7,7 @@ import { componentId } from "../components.js";
 import { OUTSIDE } from "../graph.js";
 import { KINDS } from "../kinds.js";
 import { FAMILY_KEY_LENGTH } from "../resolve.js";
+import { isRowSubject } from "../suppress.js";
 /** The classes ranked by the claim each makes, the strongest highest. */
 const RANK = { certain: 3, probable: 2, possible: 1 };
 /** The weaker of two classes, which is a class capped by a ceiling. */
@@ -59,7 +60,8 @@ function findingComponents(swept) {
  * candidate's relation, counts, configurations and component; a live one carries no
  * 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.
+ * numbered past the computed ones in finding order, so no two families mint one; nothing
+ * falls with it, so its deletion removes no line.
  */
 export function completed(input, findings) {
     const { swept } = input;
@@ -74,7 +76,11 @@ export function completed(input, findings) {
         if (row === undefined) {
             throw new Error(`${finding.code} names no live row of the issue-kind vocabulary`);
         }
-        const at = positions.get(finding.symbol.ref) ?? OUTSIDE;
+        // A row's reference may spell a declaration's, as an ignore entry naming one does, and
+        // a row is still never the declaration.
+        const at = isRowSubject(finding.symbol.kind)
+            ? OUTSIDE
+            : (positions.get(finding.symbol.ref) ?? OUTSIDE);
         const symbol = union.symbols[at];
         const judged = union.subject[at] === true ? symbol : undefined;
         const candidate = judged === undefined ? undefined : candidates.get(judged.id);
@@ -89,7 +95,7 @@ export function completed(input, findings) {
                 id: componentId(minted),
                 root: true,
                 symbolCount: 1,
-                deletableLines: finding.symbol.sizeLines,
+                deletableLines: 0,
             };
         }
         const counts = candidate === undefined
@@ -119,17 +125,38 @@ export function completed(input, findings) {
         };
     });
 }
+/** Whether the dials withhold a finding by its own severity or confidence. */
+function dialed(finding, minConfidence) {
+    return finding.severity === "allow" || RANK[finding.confidence] < RANK[minConfidence];
+}
 /**
- * The findings no dial withholds. A finding at `allow` or below the minimum confidence
- * is withheld, and so is every finding of the component of a root the dials withhold,
- * because a symbol that falls with a root is dead only through it and its deletion
- * does not compile while the root stays. A withheld finding that is no root withholds
- * itself alone.
+ * The configuration's dials over one run's completed findings. A finding at `allow` or
+ * below the minimum confidence is withheld, and so is every finding of the component of a
+ * root the dials withhold, because a symbol that falls with a root is dead only through it
+ * and its deletion does not compile while the root stays. A withheld finding that is no
+ * root withholds itself alone. A code is withheld from a declaration when the finding it
+ * would report there, completed, is withheld by its own severity or confidence.
  */
-export function reportable(findings, minConfidence) {
-    const dialed = (finding) => finding.severity === "allow" || RANK[finding.confidence] < RANK[minConfidence];
+export function dialsOf(input, findings) {
+    const minConfidence = input.config.analysis.minConfidence;
+    const classOf = reachabilityClasses(input.swept);
     const components = new Set(findings
-        .filter((finding) => finding.component.root && dialed(finding))
+        .filter((finding) => finding.component.root && dialed(finding, minConfidence))
         .map((finding) => finding.component.id));
-    return findings.filter((finding) => !dialed(finding) && !components.has(finding.component.id));
+    return {
+        withholdsCode: (code, id) => {
+            const row = KINDS.get(code);
+            return (row !== undefined &&
+                dialed({
+                    severity: severityOf(input.config, code, row.defaultSeverity),
+                    confidence: capped(classOf(id), row.maxClass),
+                }, minConfidence));
+        },
+        withholds: (finding) => dialed(finding, minConfidence) || components.has(finding.component.id),
+    };
+}
+/** The findings of one run's completed findings that no dial withholds, in the order given. */
+export function reportable(input, findings) {
+    const dials = dialsOf(input, findings);
+    return findings.filter((finding) => !dials.withholds(finding));
 }