@cplieger/deadset-ts 3.8.0 → 3.9.0

package/dist/src/run.js

@@ -8,6 +8,8 @@ import { printConfigVerb } from "./verbs/print-config.js";
 import { printProjectsVerb } from "./verbs/print-projects.js";
 import { printRetainedVerb } from "./verbs/print-retained.js";
 import { printRootsVerb } from "./verbs/print-roots.js";
+import { ANALYZE_OPTIONS, analyzeVerb } from "./verbs/analyze.js";
+import { describeVerb } from "./verbs/describe.js";
 import { EXIT_FAILURE, EXIT_USAGE } from "./verbs/verb.js";
 import { versionVerb } from "./verbs/version.js";
 /**
@@ -15,13 +17,13 @@ import { versionVerb } from "./verbs/version.js";
  * with no `run` is listed, and invoking it is a usage error.
  */
 const VERBS = [
-    { name: "analyze" },
+    { name: "analyze", run: analyzeVerb, options: ANALYZE_OPTIONS },
     { name: "explain" },
     { name: "print-config", run: printConfigVerb },
     { name: "print-projects", run: printProjectsVerb },
     { name: "print-roots", run: printRootsVerb },
     { name: "print-retained", run: printRetainedVerb },
-    { name: "describe" },
+    { name: "describe", run: describeVerb },
     { name: "version", run: versionVerb },
 ];
 const USAGE = `usage: deadset-ts <verb> [options]\nverbs: ${VERBS.map((verb) => verb.name).join(", ")}\n`;
@@ -55,6 +57,8 @@ const PLAIN_OPTIONS = new Set(["target", "config", "central", "scope"]);
 const INTEGER_OPTIONS = new Set(["max-findings"]);
 /** An integer as an option writes it: an optional minus sign and digits alone. */
 const INTEGER_TEXT = /^-?[0-9]+$/u;
+/** No option beyond the ones every verb takes. */
+const NO_OPTIONS = { plain: [], repeatable: [] };
 /**
  * The first option whose name carries a source-edit token, because every verb
  * reports and never edits. The match is on the name alone, so an option whose
@@ -73,24 +77,30 @@ function sourceEditOption(args) {
     }
     return undefined;
 }
-/** Reads one verb's options, refusing a name this command does not offer. */
-function readOptions(args) {
+/** Reads one verb's options, refusing a name neither this command nor the verb offers. */
+function readOptions(args, own) {
     const named = new Map();
+    const repeated = new Map();
     for (const arg of args) {
         if (!arg.startsWith("-")) {
             throw new ConfigError("malformed", "", `unexpected argument ${JSON.stringify(arg)}`);
         }
         const [spelled, ...rest] = arg.split("=");
         const name = (spelled ?? "").replace(/^-+/u, "");
-        if (!PLAIN_OPTIONS.has(name) && !SETTING_OPTIONS.has(name)) {
+        if (!PLAIN_OPTIONS.has(name) &&
+            !SETTING_OPTIONS.has(name) &&
+            !own.plain.includes(name) &&
+            !own.repeatable.includes(name)) {
             throw new ConfigError("malformed", "", `unknown option ${JSON.stringify(spelled ?? arg)}`);
         }
         if (rest.length === 0) {
             throw new ConfigError("malformed", "", `option ${JSON.stringify(spelled ?? arg)} takes a value`);
         }
-        named.set(name, rest.join("="));
+        const value = rest.join("=");
+        named.set(name, value);
+        repeated.set(name, [...(repeated.get(name) ?? []), value]);
     }
-    return { named };
+    return { named, repeated };
 }
 function readFileOr(host, path, orUndefined) {
     try {
@@ -160,7 +170,7 @@ export function run(args, out, err, host, openClient = (collectTiming) => openEn
     const name = args[0];
     const verb = VERBS.find((listed) => listed.name === name);
     if (verb?.run !== undefined) {
-        return invoke(verb.run, args.slice(1), { out, err, host }, openClient);
+        return invoke(verb.run, verb.options ?? NO_OPTIONS, args.slice(1), { out, err, host }, openClient);
     }
     if (verb !== undefined) {
         err.write(`deadset-ts: ${verb.name} is not implemented\n`);
@@ -177,15 +187,18 @@ export function run(args, out, err, host, openClient = (collectTiming) => openEn
  * time the verb asks for what they name, and a refusal the verb throws is written
  * and turned into its exit code once the client the verb opened is closed.
  */
-function invoke(verb, args, streams, openClient) {
+function invoke(verb, own, args, streams, openClient) {
     let options;
-    const read = () => (options ??= readOptions(args));
+    const read = () => (options ??= readOptions(args, own));
     let opened;
     try {
         return verb({
             ...streams,
+            args,
             inputs: () => inputsOf(streams.host, read()),
             scope: () => scopeOf(streams.host, read()),
+            option: (name) => read().named.get(name),
+            repeated: (name) => read().repeated.get(name) ?? [],
             openClient: (collectTiming) => {
                 opened = openClient(collectTiming);
                 return opened;

package/dist/src/verbs/analyze.js

@@ -0,0 +1,184 @@
+import { runAnalysis } from "../analysis.js";
+import { ConfigError } from "../config.js";
+import { RECORDED_CONFORMANCE, reportedConformance } from "../conformance.js";
+import { analyzerProvenance, recordedFindings, verdictOf } from "../findings-pass.js";
+import { packageScope } from "../inventory.js";
+import { normalizePath, relativePath, resolvePath } from "../paths.js";
+import { buildReport, capFindings, sortFindings, } from "../report.js";
+import { json } from "../reporters/json.js";
+import { RENDERINGS } from "../reporters/reporters.js";
+import { resolve } from "../resolve.js";
+import { writeBaseline } from "../suppress-file.js";
+import { CONTRACT_VERSION } from "../version.js";
+import { EXIT_CLEAN, EXIT_FAILURE } from "./verb.js";
+/** The options `analyze` takes beside the ones every verb takes. */
+export const ANALYZE_OPTIONS = {
+    plain: ["report", "baseline-write", "exit-code"],
+    repeatable: ["format"],
+};
+/** The two values `--exit-code` takes; on, the default, puts the run's verdict in the exit code. */
+const EXIT_CODE_ON = "on";
+const EXIT_CODE_OFF = "off";
+/** Why a declared consumer is not loaded, which every report names it with. */
+const NOT_LOADED = "this analyzer loads no consumer beside the target";
+/** A path of the run no report can name, which ends the run with the failure code. */
+class ReportPathError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ReportPathError";
+    }
+}
+/** The formats this analyzer renders, for a message that names them. */
+function formatNames() {
+    return [...RENDERINGS.keys()].sort().join(", ");
+}
+/** The renderings one invocation writes: the ones it named, else the configuration's. */
+function formatsOf(named, configured) {
+    const formats = named.length > 0 ? named : configured;
+    const seen = new Set();
+    for (const format of formats) {
+        if (!RENDERINGS.has(format)) {
+            throw new ConfigError("malformed", "", `${JSON.stringify(format)} is not a format this analyzer renders: the formats are ${formatNames()}`);
+        }
+        if (seen.has(format)) {
+            throw new ConfigError("malformed", "", `the format ${JSON.stringify(format)} is named twice`);
+        }
+        seen.add(format);
+    }
+    return formats;
+}
+/**
+ * One directory of the run below the directory the run was invoked from, as a report names
+ * it. A report admits that directory and every path below it and none that climbs out, so a
+ * target elsewhere has no spelling a report can carry and fails the run.
+ */
+function runRelative(invoked, path) {
+    if (normalizePath(invoked) === normalizePath(path)) {
+        return ".";
+    }
+    const below = relativePath(invoked, path);
+    if (below === undefined) {
+        throw new ReportPathError(`a report names its target relative to the directory the run was invoked from, and ${invoked} does not contain ${path}: run from a directory that does`);
+    }
+    return below;
+}
+/** Each project of the run as a report names it, by its configuration file below the target. */
+function configurationsOf(projects, targetRoot) {
+    return projects.map((one) => {
+        const project = relativePath(targetRoot, one.configFile);
+        if (project === undefined) {
+            throw new ReportPathError(`the project ${one.id} is opened from ${one.configFile}, which is not below the target ${targetRoot}, so no report can name it`);
+        }
+        return { id: one.id, project };
+    });
+}
+/** The name one module publishes itself under: the scope's, else its manifest's. */
+function identityOf(module, host) {
+    return module.id === "" ? packageScope(host, module.path)("index.ts").package : module.id;
+}
+/** A count with its noun, so a message reads for one record as well as for several. */
+function counted(n, noun) {
+    return `${String(n)} ${noun}${n === 1 ? "" : "s"}`;
+}
+/**
+ * Analyzes the scope under the configuration and writes the JSON report to the path
+ * `--report` names, each rendering `--format` names beside it at the report's path with the
+ * format's suffix appended, and a baseline of every finding where `--baseline-write` names a
+ * path. Nothing is written to the output stream; diagnostics go to the error stream and the
+ * verdict is the exit code, or 0 under `--exit-code=off`.
+ */
+export const analyzeVerb = ({ err, host, inputs, scope, openClient, option, repeated }) => {
+    const reportPath = option("report");
+    if (reportPath === undefined || reportPath === "") {
+        throw new ConfigError("malformed", "", "analyze writes its report to the path --report names, and no path was named");
+    }
+    const exitCode = option("exit-code") ?? EXIT_CODE_ON;
+    if (exitCode !== EXIT_CODE_ON && exitCode !== EXIT_CODE_OFF) {
+        throw new ConfigError("malformed", "", `--exit-code=${JSON.stringify(exitCode)}: the values are ${EXIT_CODE_ON} and ${EXIT_CODE_OFF}`);
+    }
+    const { config, provenance } = resolve(inputs());
+    const kind = config.targetKind;
+    if (kind === "") {
+        throw new ConfigError("missing-target-kind", "target.kind", "target.kind is not set");
+    }
+    const invoked = host.workingDirectory();
+    const baseline = option("baseline-write");
+    const documents = {
+        report: resolvePath(invoked, reportPath),
+        formats: formatsOf(repeated("format"), config.reporters.formats),
+        baseline: baseline === undefined ? undefined : resolvePath(invoked, baseline),
+    };
+    const scoped = scope();
+    const targetRoot = scoped.target.path;
+    let version;
+    try {
+        version = host.analyzerVersion();
+    }
+    catch (error) {
+        err.write(`deadset-ts: ${error instanceof Error ? error.message : String(error)}\n`);
+        return EXIT_FAILURE;
+    }
+    let report;
+    let recorded;
+    let verdict;
+    try {
+        const root = runRelative(invoked, targetRoot);
+        const { result, run } = runAnalysis(openClient(false), host, scoped, config, provenance, {
+            production: true,
+        });
+        const built = buildReport({
+            contractVersion: CONTRACT_VERSION,
+            version,
+            conformance: reportedConformance(RECORDED_CONFORMANCE),
+            target: { kind, root, identity: identityOf(scoped.target, host) },
+            configurations: configurationsOf(run.projects, targetRoot),
+            unavailable: scoped.consumers.map((consumer) => ({
+                id: identityOf(consumer, host),
+                reason: NOT_LOADED,
+            })),
+            result,
+            testFileRules: run.testFileRules,
+        });
+        // The baseline records every finding, so its rows are taken before the cap bounds what
+        // a rendering prints: a baseline missing a reported finding fails the next run on it.
+        recorded = recordedFindings(result);
+        report = capFindings(sortFindings(built, config.reporters.sort), config.reporters.maxFindings);
+        verdict = verdictOf(result, config);
+    }
+    catch (error) {
+        if (!(error instanceof ReportPathError)) {
+            throw error;
+        }
+        err.write(`deadset-ts: ${error.message}\n`);
+        return EXIT_FAILURE;
+    }
+    try {
+        host.writeFile(documents.report, json(report));
+        for (const format of documents.formats) {
+            const rendering = RENDERINGS.get(format);
+            if (rendering !== undefined) {
+                host.writeFile(documents.report + rendering.suffix, rendering.render(report));
+            }
+        }
+        if (documents.baseline !== undefined) {
+            host.writeFile(documents.baseline, writeBaseline(recorded, analyzerProvenance(version)));
+        }
+    }
+    catch (error) {
+        err.write(`deadset-ts: ${error instanceof Error ? error.message : String(error)}\n`);
+        return EXIT_FAILURE;
+    }
+    if (report.totals.pending > 0) {
+        err.write(`deadset-ts: ${counted(report.totals.pending, "pending finding")}: the report names a declared cross-language edge, and no merge has resolved it\n`);
+    }
+    if (report.totals.stale_suppressions > 0) {
+        err.write(`deadset-ts: ${counted(report.totals.stale_suppressions, "stale suppression")}\n`);
+    }
+    if (exitCode === EXIT_CODE_OFF) {
+        if (verdict !== EXIT_CLEAN) {
+            err.write(`deadset-ts: the exit code is configured off: the verdict of this run is ${String(verdict)}\n`);
+        }
+        return EXIT_CLEAN;
+    }
+    return verdict;
+};

package/dist/src/verbs/describe.js

@@ -0,0 +1,45 @@
+import { RECORDED_CONFORMANCE } from "../conformance.js";
+import { ANALYZER_NAME, LANGUAGE, SCHEMA_VERSION } from "../report.js";
+import { CONTRACT_VERSION } from "../version.js";
+import { EXIT_CLEAN, EXIT_FAILURE, EXIT_USAGE } from "./verb.js";
+/**
+ * The document `describe` writes: the analyzer, the Contract version it implements, the
+ * report schema versions it reads, the languages it claims, and its recorded result over
+ * the conformance corpus, absent where it records none.
+ */
+export function describeDocument(version, recorded) {
+    const document = {
+        name: ANALYZER_NAME,
+        version,
+        contract_version: CONTRACT_VERSION,
+        schema_versions_accepted: [SCHEMA_VERSION],
+        languages: [LANGUAGE],
+        ...(recorded === undefined
+            ? {}
+            : {
+                conformance: {
+                    corpus_version: recorded.corpusVersion,
+                    result: recorded.result,
+                    digest: recorded.digest,
+                },
+            }),
+    };
+    return `${JSON.stringify(document, null, 2)}\n`;
+}
+/** Writes this analyzer's description to the output stream, and nothing to the error stream. */
+export const describeVerb = ({ out, err, host, args }) => {
+    if (args.length > 0) {
+        err.write(`deadset-ts: describe takes no argument, got ${JSON.stringify(args[0])}\n`);
+        return EXIT_USAGE;
+    }
+    let version;
+    try {
+        version = host.analyzerVersion();
+    }
+    catch (error) {
+        err.write(`deadset-ts: describe: ${error instanceof Error ? error.message : String(error)}\n`);
+        return EXIT_FAILURE;
+    }
+    out.write(describeDocument(version, RECORDED_CONFORMANCE));
+    return EXIT_CLEAN;
+};

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "license": "GPL-3.0-or-later",
   "exports": {
     ".": "./src/index.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "type": "module",
   "sideEffects": false,
   "description": "Deterministic dead-code analysis for TypeScript, class and type members included",

package/src/analysis.ts

@@ -45,7 +45,7 @@ import { matrixOf, sweepMatrix, type Configured, type Matrix, type SweepResult }
 import { relativePath, resolvePath } from "./paths.ts";
 import { byPosition, type Position } from "./position.ts";
 import { reflectiveLookup } from "./reflective-lookup.ts";
-import { references } from "./references.ts";
+import { references, testFileRulesOf, type TestFileRule } from "./references.ts";
 import { roots, unmatchedEverywhere, type RootKind, type Roots } from "./roots.ts";
 import type { Scope } from "./scope.ts";
 import { serializationContract } from "./serialization-contract.ts";
@@ -119,6 +119,8 @@ function compare(a: string, b: string): number {
 /** What every stage after the root set reads of one project. */
 interface ProjectRead {
   readonly configuration: string;
+  /** The compiler configuration file the project was opened from, absolute. */
+  readonly configFile: string;
   readonly held: Inventory;
   readonly rooted: Roots;
 }
@@ -156,7 +158,7 @@ function readProjects<Answer>(
     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(
@@ -253,6 +255,7 @@ const DETECTORS: Detectors = new Map<TSExemptionClass, Detector>([
 
 /** What the sweep of one run reads of each project, beside what a caller's stage adds. */
 interface SweptProject<Extra> {
+  readonly configFile: string;
   readonly configured: Configured;
   readonly exempt: readonly Exemption[];
   readonly extra: Extra;
@@ -305,7 +308,12 @@ function readRun<Extra>(
         testFiles: new Set(resolved.testFilePaths),
       },
     );
-    return { configured, exempt, extra: extra(project, projectRead) };
+    return {
+      configFile: projectRead.configFile,
+      configured,
+      exempt,
+      extra: extra(project, projectRead),
+    };
   });
   return {
     matrix: matrixOf(projects.map((one) => one.configured)),
@@ -465,6 +473,7 @@ export interface AnalysisInputs {
  * 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: Engine,
@@ -473,8 +482,8 @@ function runAnalysisInputs(
   config: Config,
   provenance: Provenance,
   mode: Mode,
-  detectors: Detectors = DETECTORS,
-): AnalysisInputs {
+  detectors: Detectors,
+): { readonly inputs: AnalysisInputs; readonly run: RunFacts } {
   const targetRoot = scope.target.path;
   const read = readEmitterRun(engine, host, scope, config, mode, detectors);
   const symbols = read.matrix.union.symbols;
@@ -499,18 +508,51 @@ function runAnalysisInputs(
     (id) => id !== "",
   );
   return {
-    marked: emitterInputOver(host, scope, config, read, { marked, mode }, facts),
-    unmarked: emitterInputOver(host, scope, config, read, { marked: [], mode }, facts),
-    suppressions,
+    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),
+      ),
+    },
   };
 }
 
+/** One project of a run: the name the run gives it and the file it was opened from. */
+export interface RunProject {
+  readonly id: string;
+  /** The compiler configuration file, absolute. */
+  readonly configFile: string;
+}
+
+/** What a report states about the run beside its findings. */
+export interface RunFacts {
+  /** The projects the run analyzed, in the run's order. */
+  readonly projects: readonly RunProject[];
+  /** The rules that classified files as test files, each counted over every project at once. */
+  readonly testFileRules: readonly TestFileRule[];
+}
+
+/** The findings of one run, beside what a report states about the run itself. */
+export interface RunAnalysis {
+  readonly result: PassResult;
+  readonly run: RunFacts;
+}
+
 /**
- * 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.
+ * 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 runFindings(
+export function runAnalysis(
   engine: Engine,
   host: Host,
   scope: Scope,
@@ -518,6 +560,15 @@ export function runFindings(
   provenance: Provenance,
   mode: Mode,
   detectors: Detectors = DETECTORS,
-): PassResult {
-  return findingsPass(runAnalysisInputs(engine, host, scope, config, provenance, mode, detectors));
+): RunAnalysis {
+  const { inputs, run } = runAnalysisInputs(
+    engine,
+    host,
+    scope,
+    config,
+    provenance,
+    mode,
+    detectors,
+  );
+  return { result: findingsPass(inputs), run };
 }

package/src/conformance.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 result one product reached over the conformance corpus. */
+export interface Conformance {
+  readonly corpusVersion: string;
+  readonly result: "pass" | "fail";
+  /** `sha256:` and the lowercase hexadecimal SHA-256 of the results document the runner wrote. */
+  readonly digest: string;
+}
+
+/** 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: Conformance | undefined = 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: Conformance | undefined): Conformance {
+  return recorded ?? { corpusVersion: CORPUS_VERSION, result: "fail", digest: EMPTY_DIGEST };
+}

package/src/finding.ts

@@ -1,6 +1,7 @@
 import type { Confidence, Severity } from "./config.ts";
 import type { Fixability } from "./kinds.ts";
 import type { DependencySection } from "./ref.ts";
+import type { Mechanism } from "./suppress.ts";
 import type { Relation } from "./sweep.ts";
 
 /**
@@ -58,6 +59,18 @@ export interface FindingDetails {
   readonly writePositions?: readonly FindingPosition[];
   /** On `DS1601`: the manifest section that declares the dependency. */
   readonly dependencyClass?: DependencySection;
+  /** On `DS1701` and `DS1702`: the document that holds the refused suppression. */
+  readonly mechanism?: Mechanism;
+  /** On `DS1701` and `DS1702`: the refused suppression as written, a member absent where it lacks one. */
+  readonly entry?: SuppressionEntry;
+}
+
+/** One suppression in the four-member form the ignore file and the baseline share. */
+export interface SuppressionEntry {
+  readonly code: string;
+  readonly symbol?: string;
+  readonly path?: string;
+  readonly reason?: string;
 }
 
 /** One finding as its emitter states it. */

package/src/findings/completion.ts

@@ -11,7 +11,7 @@ import type { CompletedFinding, Finding, FindingComponent } from "../finding.ts"
 import { OUTSIDE } from "../graph.ts";
 import { KINDS } from "../kinds.ts";
 import { FAMILY_KEY_LENGTH } from "../resolve.ts";
-import type { Dials } from "../suppress.ts";
+import { isRowSubject, type Dials } from "../suppress.ts";
 import type { EmitterInput } from "./emitter.ts";
 
 /** The classes ranked by the claim each makes, the strongest highest. */
@@ -75,7 +75,8 @@ function findingComponents(swept: RunSweep): (id: string) => FindingComponent |
  * 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: EmitterInput,
@@ -94,7 +95,11 @@ export function completed(
     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);
@@ -109,7 +114,7 @@ export function completed(
         id: componentId(minted),
         root: true,
         symbolCount: 1,
-        deletableLines: finding.symbol.sizeLines,
+        deletableLines: 0,
       };
     }
     const counts =

package/src/findings/self-check.ts

@@ -1,5 +1,5 @@
 import { REPOSITORY_DOCUMENT } from "../config.ts";
-import type { Finding } from "../finding.ts";
+import type { Finding, FindingDetails, SuppressionEntry } from "../finding.ts";
 import type { InventorySymbol } from "../inventory.ts";
 import type { Position } from "../position.ts";
 import {
@@ -73,12 +73,32 @@ function spelled(codes: readonly string[]): string {
 }
 
 /** A finding about one suppression, at the suppression's own site. */
-function aboutSuppression(code: string, ref: string, site: Position, message: string): Finding {
+function aboutSuppression(
+  code: string,
+  ref: string,
+  site: Position,
+  message: string,
+  details: FindingDetails,
+): Finding {
   return {
     code,
     position: { ...site, endLine: site.line },
     symbol: { ref, kind: SUPPRESSION_SUBJECT, name: ref, sizeLines: 1 },
     message,
+    details,
+  };
+}
+
+/** Whether a reason holds a character other than whitespace. */
+const STATED = /[^ \t\r\n]/u;
+
+/** A refused suppression as written: a member it lacks is absent. */
+function writtenEntry(refused: Refusal): SuppressionEntry {
+  return {
+    code: refused.code,
+    ...(refused.symbol === "" ? {} : { symbol: refused.symbol }),
+    ...(refused.path === "" ? {} : { path: refused.path }),
+    ...(STATED.test(refused.reason) ? { reason: refused.reason } : {}),
   };
 }
 
@@ -108,6 +128,7 @@ export function refusedSuppressions(
           ? "carries no reason"
           : "names a symbol and no path"
       }`,
+      { mechanism: refused.mechanism, entry: writtenEntry(refused) },
     ),
   );
 }

package/src/host.ts

@@ -34,4 +34,9 @@ export interface Host {
    * says so at the one moment the value is asked for.
    */
   analyzerVersion(): string;
+  /**
+   * Writes one document whole, or a throw naming why it cannot. The write is atomic: a
+   * reader of the path sees the previous document or this one and never a part of it.
+   */
+  writeFile(path: string, text: string): void;
 }