@cplieger/deadset-ts 3.7.0 → 3.8.0

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";
@@ -25,10 +28,12 @@ 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 { 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";
@@ -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,26 @@ 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) };
     });
-    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 +203,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 +233,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 +243,59 @@ 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.
+ */
+function runAnalysisInputs(engine, host, scope, config, provenance, mode, detectors = 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 {
+        marked: emitterInputOver(host, scope, config, read, { marked, mode }, facts),
+        unmarked: emitterInputOver(host, scope, config, read, { marked: [], mode }, facts),
+        suppressions,
+    };
+}
+/**
+ * The findings of the run the scope and the configuration describe: the run read with its
+ * suppressions bound, then every family's findings with the suppressions applied and the
+ * declared edges evaluated.
+ */
+export function runFindings(engine, host, scope, config, provenance, mode, detectors = DETECTORS) {
+    return findingsPass(runAnalysisInputs(engine, host, scope, config, provenance, mode, detectors));
+}

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

@@ -119,17 +119,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));
 }

package/dist/src/findings/emitters.js

@@ -1,5 +1,7 @@
+import { evaluateEdges } from "../edges.js";
+import { ledgerOf } from "../suppress.js";
+import { completed, dialsOf, reportable } from "./completion.js";
 import { dependenciesAndModuleMachinery } from "./dependencies-and-module-machinery.js";
-import { completed, reportable } from "./completion.js";
 import { interfaces } from "./interfaces.js";
 import { intraFunction } from "./intra-function.js";
 import { nonCodeArtifacts } from "./non-code-artifacts.js";
@@ -18,12 +20,46 @@ export const EMITTERS = new Map([
     ["self-check", selfCheck],
     ["intra-function", intraFunction],
 ]);
+/** Every family's findings over one sweep, completed by one step. */
+function completedOver(input) {
+    return completed(input, [...EMITTERS.values()].flatMap((emit) => emit(input)));
+}
 /**
- * Every finding of the run the dials do not withhold, each family's in table order: every
- * family's findings completed by one step, then withheld by one step, so a root one
- * family reports withholds what another family reports in its component.
+ * The dials over the findings a record could name, each read against the sweep that
+ * produced it, so a component one sweep numbers withholds nothing of the other's.
  */
+function dialsOver(input, found, suppressed, unmarked) {
+    const marked = dialsOf(input, found);
+    const before = dialsOf(suppressed.unmarked, unmarked);
+    const fromUnmarked = new Set(unmarked);
+    return {
+        withholdsCode: marked.withholdsCode,
+        withholds: (finding) => fromUnmarked.has(finding) ? before.withholds(finding) : marked.withholds(finding),
+    };
+}
+/**
+ * Every finding of one run swept under its suppressions' marks, decided in one pass: every
+ * family's findings completed by one step, so every component number is minted once, a
+ * pending finding's among them; the finding each record claims withheld, whatever its
+ * kind; the rest withheld by the dials, so a root one family reports withholds what
+ * another family reports in its component; and every declared edge evaluated over what
+ * remains, so a finding it holds pending is in its evaluation and nowhere else.
+ */
+export function decidedFindings(input, suppressed = { unmarked: input, records: [] }) {
+    const found = completedOver(input);
+    const unmarked = suppressed.records.length === 0 ? [] : completedOver(suppressed.unmarked);
+    const would = [...unmarked, ...found];
+    const ledger = ledgerOf(suppressed.records, would, dialsOver(input, found, suppressed, unmarked));
+    const kept = reportable(input, found.filter((finding) => !ledger.withheld(finding)));
+    const evaluated = evaluateEdges(kept, input.boundary.edges, input.swept.matrix.union.symbols);
+    return {
+        findings: evaluated.findings,
+        evaluations: evaluated.evaluations,
+        ledger,
+        would,
+    };
+}
+/** Every finding the run reports, each family's in table order. */
 export function findingsOf(input) {
-    const found = [...EMITTERS.values()].flatMap((emit) => emit(input));
-    return reportable(completed(input, found), input.config.analysis.minConfidence);
+    return decidedFindings(input).findings;
 }

package/dist/src/findings/self-check.js

@@ -1,2 +1,127 @@
-/** The findings of the self-check family, `DS1700` to `DS1799`. */
-export const selfCheck = () => [];
+import { REPOSITORY_DOCUMENT } from "../config.js";
+import { STALE_SUPPRESSION, SUPPRESSION_WITHOUT_REASON, } from "../suppress.js";
+/** The code a configured root that matches nothing is reported under. */
+const UNMATCHED_ROOT = "DS1704";
+/** The subject kind of a finding about a suppression record. */
+const SUPPRESSION_SUBJECT = "suppression";
+/** The subject kind of a finding about a configured root. */
+const ROOT_SUBJECT = "root";
+/** The fixed position of a finding about a document rather than about a line of one. */
+const DOCUMENT_POSITION = 1;
+/** A run with nothing for the self-check family to report. */
+export const NO_SELF_CHECK = {
+    refusals: [],
+    unmatchedRoots: [],
+    rootsDocument: "",
+};
+/** The words a message names a mechanism by. */
+const WRITTEN = {
+    inline: "inline directive",
+    ignore: "ignore entry",
+    baseline: "baseline row",
+};
+/** The file references of a run's declarations, by path. */
+export function fileRefsOf(symbols) {
+    const byPath = new Map(symbols
+        .filter((symbol) => symbol.kind === "file")
+        .map((symbol) => [symbol.position.path, symbol.ref]));
+    return (path) => byPath.get(path);
+}
+/** A list of codes as a sentence names them. */
+function spelled(codes) {
+    if (codes.length < 2) {
+        return codes.join("");
+    }
+    return `${codes.slice(0, -1).join(", ")} and ${codes.at(-1) ?? ""}`;
+}
+/** A finding about one suppression, at the suppression's own site. */
+function aboutSuppression(code, ref, site, message) {
+    return {
+        code,
+        position: { ...site, endLine: site.line },
+        symbol: { ref, kind: SUPPRESSION_SUBJECT, name: ref, sizeLines: 1 },
+        message,
+    };
+}
+/**
+ * The reference a finding about a suppression names: the symbol it names or bound, else
+ * the file form of the document that holds it, else that document's path.
+ */
+function suppressionRef(symbol, path, files) {
+    return symbol === "" ? (files(path) ?? path) : symbol;
+}
+/** One finding per refused suppression: the grammar's reason refusal and its scope refusal. */
+export function refusedSuppressions(refusals, files) {
+    return refusals.map((refused) => aboutSuppression(refused.reported, suppressionRef(refused.symbol, refused.path, files), refused.site, `${WRITTEN[refused.mechanism]} for ${refused.code} ${refused.reported === SUPPRESSION_WITHOUT_REASON
+        ? "carries no reason"
+        : "names a symbol and no path"}`));
+}
+/**
+ * One record per site at which a suppression matched nothing, whatever the number of
+ * codes or declarations written there: the first record names the entry, and the message
+ * names every code the site's records named and every code the declaration reports
+ * instead, so the maintainer corrects the code rather than hunting for it.
+ */
+export function staleSuppressions(stale, files) {
+    const bySite = new Map();
+    for (const one of stale) {
+        const { site, mechanism } = one.record;
+        const key = `${mechanism}\u0000${site.path}\u0000${String(site.line)}\u0000${String(site.column)}`;
+        const held = bySite.get(key) ?? { first: one.record, records: [] };
+        held.records.push(one);
+        bySite.set(key, held);
+    }
+    return [...bySite.values()].map(({ first, records }) => {
+        const codes = [...new Set(records.map((one) => one.record.code))].sort();
+        const reports = [...new Set(records.flatMap((one) => one.reports))]
+            .filter((code) => !codes.includes(code))
+            .sort();
+        const instead = reports.length === 0 ? "" : `, and its declaration reports ${spelled(reports)}`;
+        return {
+            code: STALE_SUPPRESSION,
+            mechanism: first.mechanism,
+            entry: {
+                code: first.code,
+                ...(first.symbol === "" ? {} : { symbol: first.symbol }),
+                path: first.path,
+                reason: first.reason,
+            },
+            position: first.site,
+            symbol: suppressionRef(first.symbol, first.path, files),
+            message: `${WRITTEN[first.mechanism]} for ${spelled(codes)} matches no current finding${instead}`,
+        };
+    });
+}
+/**
+ * One finding per configured root or pattern that named nothing in any project. A finding
+ * names the document that declared the roots, or the conventional repository configuration
+ * where no document of the target did, and every finding of one run sits at that
+ * document's first position: the roots are an array whose members carry no line of their
+ * own, so the string each finding names tells one from another.
+ */
+export function unmatchedRootFindings(sources, document) {
+    const position = {
+        path: document === "" ? REPOSITORY_DOCUMENT : document,
+        line: DOCUMENT_POSITION,
+        column: DOCUMENT_POSITION,
+        endLine: DOCUMENT_POSITION,
+    };
+    return sources.map((source) => ({
+        code: UNMATCHED_ROOT,
+        position,
+        symbol: { ref: source, kind: ROOT_SUBJECT, name: source, sizeLines: 1 },
+        message: source.includes("*") || source.includes("?")
+            ? "configured root pattern matches no symbol of the inventory"
+            : "configured root matches no symbol of the inventory",
+    }));
+}
+/**
+ * The findings of the self-check family, `DS1700` to `DS1799`: a suppression refused for
+ * carrying no reason or naming no path, and a configured root that named nothing. A
+ * suppression that matched nothing is a record of the report's stale suppressions, which
+ * {@link staleSuppressions} builds, and a stale cross-language edge is the merge's to report.
+ */
+export const selfCheck = ({ selfCheck: facts, swept }) => [
+    ...refusedSuppressions(facts.refusals, fileRefsOf(swept.matrix.union.symbols)),
+    ...unmatchedRootFindings(facts.unmatchedRoots, facts.rootsDocument),
+];