@cplieger/deadset-ts 3.8.0 → 3.9.1

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

@@ -27,7 +27,7 @@ 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 { references, testFileRulesOf } from "./references.js";
 import { roots, unmatchedEverywhere } from "./roots.js";
 import { serializationContract } from "./serialization-contract.js";
 import { diagnosticsOf, runSession } from "./session.js";
@@ -85,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);
@@ -175,7 +175,12 @@ function readRun(engine, host, scope, config, mode, detectors, extra) {
             mode,
             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)),
@@ -265,8 +270,9 @@ export function runEmitterInput(engine, host, scope, config, input, detectors =
  * 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 = DETECTORS) {
+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;
@@ -286,16 +292,26 @@ function runAnalysisInputs(engine, host, scope, config, provenance, mode, detect
     };
     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,
+        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 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(engine, host, scope, config, provenance, mode, detectors = DETECTORS) {
-    return findingsPass(runAnalysisInputs(engine, host, scope, config, provenance, mode, detectors));
+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/destructuring.js

@@ -0,0 +1,273 @@
+/**
+ * The members a destructuring reads. An object pattern reads each property it names
+ * from the value it destructures, so the property's name in the pattern is a read of
+ * the member the value's type declares under that name, whether the pattern binds it
+ * to a local of the same name, renames it, gives it a default or nests a pattern under
+ * it. A rest element names no property: what it copies is read where the copy is.
+ */
+import { isArrayLiteralExpression, isBinaryExpression, isForOfStatement, isIdentifier, isNoSubstitutionTemplateLiteral, isNumericLiteral, isObjectBindingPattern, isObjectLiteralExpression, isParameterDeclaration, isParenthesizedExpression, isPropertyAssignment, isShorthandPropertyAssignment, isStringLiteral, SyntaxKind, } from "@typescript/native/unstable/ast";
+import { TypeFlags } from "@typescript/native/unstable/sync";
+/** The text a property name spells, or `undefined` for a computed name. */
+function nameText(node) {
+    if (node === undefined) {
+        return undefined;
+    }
+    if (isIdentifier(node) ||
+        isStringLiteral(node) ||
+        isNoSubstitutionTemplateLiteral(node) ||
+        isNumericLiteral(node)) {
+        return node.text;
+    }
+    return undefined;
+}
+/** The node one expression is written inside, through however many parentheses enclose it. */
+function container(node) {
+    let child = node;
+    while (isParenthesizedExpression(child.parent)) {
+        child = child.parent;
+    }
+    return { child, parent: child.parent };
+}
+/** The plain assignment one node is the left side of, if it is one. */
+function assignmentOf(node, parent) {
+    return isBinaryExpression(parent) &&
+        parent.operatorToken.kind === SyntaxKind.EqualsToken &&
+        parent.left === node
+        ? parent
+        : undefined;
+}
+/**
+ * Whether an object or array literal is a destructuring target rather than a value: the
+ * left side of an assignment, the target of a `for…of`, or an element of a literal that
+ * is one, with or without a default.
+ */
+function isDestructuringTarget(literal) {
+    const { child, parent } = container(literal);
+    if (assignmentOf(child, parent) !== undefined) {
+        return true;
+    }
+    if (isForOfStatement(parent)) {
+        return parent.initializer === child;
+    }
+    return isElement(child, parent);
+}
+/** Whether one node is an element of a destructuring target: a property's value, or an array element. */
+function isElement(child, parent) {
+    if (isPropertyAssignment(parent)) {
+        return parent.initializer === child && isDestructuringTarget(parent.parent);
+    }
+    return isArrayLiteralExpression(parent) && isDestructuringTarget(parent);
+}
+/**
+ * Whether an object binding pattern runs: a pattern in the parameter list of a signature
+ * with no body, a function type or an overload among them, binds nothing at runtime.
+ */
+function binds(pattern) {
+    let at = pattern.parent;
+    while (at.kind === SyntaxKind.BindingElement) {
+        at = at.parent.parent;
+    }
+    if (!isParameterDeclaration(at)) {
+        return true;
+    }
+    return at.parent.body !== undefined;
+}
+/** The properties one node reads, where it is an object pattern; none otherwise. */
+export function propertyReadsOf(node) {
+    const reads = [];
+    if (isObjectBindingPattern(node)) {
+        if (!binds(node)) {
+            return reads;
+        }
+        for (const element of node.elements) {
+            const key = element.propertyName ?? element.name;
+            const name = nameText(key);
+            if (element.dotDotDotToken === undefined && key !== undefined && name !== undefined) {
+                reads.push({ pattern: node, key, name });
+            }
+        }
+        return reads;
+    }
+    if (isObjectLiteralExpression(node) && isDestructuringTarget(node)) {
+        for (const property of node.properties) {
+            if (isShorthandPropertyAssignment(property) || isPropertyAssignment(property)) {
+                const name = nameText(property.name);
+                if (name !== undefined) {
+                    reads.push({ pattern: node, key: property.name, name });
+                }
+            }
+        }
+    }
+    return reads;
+}
+/**
+ * Where the value one destructuring target receives comes from. The checker answers for
+ * a binding pattern's type itself, so this is asked of an assignment target only, whose
+ * own type is the literal's rather than the assigned value's. A default does not move
+ * the source: `{ a: { b } = fallback }` reads `b` from `a`. A target inside a spread
+ * takes the rest of a value and has no source here.
+ */
+function sourceOf(target) {
+    const steps = [];
+    let at = target;
+    for (;;) {
+        const { child, parent } = container(at);
+        const assignment = assignmentOf(child, parent);
+        if (assignment !== undefined) {
+            const outer = container(assignment);
+            if (!isElement(outer.child, outer.parent)) {
+                return { expression: assignment.right, steps: steps.reverse() };
+            }
+            at = assignment;
+            continue;
+        }
+        if (isForOfStatement(parent) && parent.initializer === child) {
+            steps.push({ kind: "iterated" });
+            return { expression: parent.expression, steps: steps.reverse() };
+        }
+        if (isPropertyAssignment(parent) && parent.initializer === child) {
+            const name = nameText(parent.name);
+            if (name === undefined) {
+                return undefined;
+            }
+            steps.push({ kind: "property", name });
+            at = parent.parent;
+            continue;
+        }
+        if (isArrayLiteralExpression(parent)) {
+            steps.push({
+                kind: "element",
+                index: parent.elements.findIndex((element) => element === child),
+            });
+            at = parent;
+            continue;
+        }
+        return undefined;
+    }
+}
+/**
+ * The resolution over one project, its batches capped at `cap`. Property tables are
+ * read once per type for the whole project, since one type is destructured in many
+ * places and a table answers every name of it.
+ */
+export function destructuring(project, cap) {
+    const checker = project.checker;
+    const tables = new Map();
+    let patternBatches = 0;
+    let patternLookups = 0;
+    const typesAt = (nodes) => {
+        const types = [];
+        for (let from = 0; from < nodes.length; from += cap) {
+            types.push(...checker.getTypeAtLocation(nodes.slice(from, from + cap)));
+            patternBatches += 1;
+        }
+        return types;
+    };
+    const tableOf = (type) => {
+        const known = tables.get(type.id);
+        if (known !== undefined) {
+            return known;
+        }
+        const table = new Map();
+        if ((type.flags & TypeFlags.AnyOrUnknown) === 0) {
+            patternLookups += 1;
+            for (const property of checker.getPropertiesOfType(type)) {
+                table.set(property.name, property);
+            }
+        }
+        tables.set(type.id, table);
+        return table;
+    };
+    const definedOf = (type) => {
+        if ((type.flags & TypeFlags.Union) === 0) {
+            return type;
+        }
+        patternLookups += 1;
+        return checker.getNonNullableType(type);
+    };
+    /**
+     * The type one element of an array or tuple value has: a tuple's element at `index`,
+     * an array's element type at any index, and `undefined` for a tuple iterated whole.
+     */
+    const elementOf = (type, index) => {
+        if (!type.isTypeReference()) {
+            return undefined;
+        }
+        patternLookups += 1;
+        if (checker.isTupleType(type)) {
+            if (index === undefined) {
+                return undefined;
+            }
+            patternLookups += 1;
+            return checker.getTypeArguments(type)[index];
+        }
+        patternLookups += 1;
+        if (!checker.isArrayType(type)) {
+            return undefined;
+        }
+        patternLookups += 1;
+        return checker.getTypeArguments(type)[0];
+    };
+    const step = (type, next) => {
+        const defined = definedOf(type);
+        if (defined === undefined) {
+            return undefined;
+        }
+        if (next.kind === "property") {
+            const property = tableOf(defined).get(next.name);
+            if (property === undefined) {
+                return undefined;
+            }
+            patternLookups += 1;
+            return checker.getTypeOfSymbol(property);
+        }
+        return elementOf(defined, next.kind === "element" ? next.index : undefined);
+    };
+    const resolve = (reads) => {
+        const patterns = [...new Set(reads.map((read) => read.pattern))];
+        const sources = new Map();
+        const asking = new Set();
+        for (const pattern of patterns) {
+            if (isObjectBindingPattern(pattern)) {
+                asking.add(pattern);
+                continue;
+            }
+            const source = sourceOf(pattern);
+            sources.set(pattern, source);
+            if (source !== undefined) {
+                asking.add(source.expression);
+            }
+        }
+        const answered = new Map();
+        const asked = [...asking];
+        typesAt(asked).forEach((type, index) => {
+            const node = asked[index];
+            if (type !== undefined && node !== undefined) {
+                answered.set(node, type);
+            }
+        });
+        const patternTypes = new Map();
+        for (const pattern of patterns) {
+            const source = sources.get(pattern);
+            if (source === undefined) {
+                patternTypes.set(pattern, answered.get(pattern));
+                continue;
+            }
+            let type = answered.get(source.expression);
+            for (const next of source.steps) {
+                type = type === undefined ? undefined : step(type, next);
+            }
+            patternTypes.set(pattern, type === undefined ? undefined : definedOf(type));
+        }
+        return reads.map((read) => {
+            const type = patternTypes.get(read.pattern);
+            return type === undefined ? undefined : tableOf(type).get(read.name);
+        });
+    };
+    return {
+        resolve,
+        get cost() {
+            return { patternBatches, patternLookups };
+        },
+    };
+}

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

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

@@ -35,12 +35,24 @@ function spelled(codes) {
     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) {
+function aboutSuppression(code, ref, site, message, details) {
     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) {
+    return {
+        code: refused.code,
+        ...(refused.symbol === "" ? {} : { symbol: refused.symbol }),
+        ...(refused.path === "" ? {} : { path: refused.path }),
+        ...(STATED.test(refused.reason) ? { reason: refused.reason } : {}),
     };
 }
 /**
@@ -54,7 +66,7 @@ function suppressionRef(symbol, path, files) {
 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"}`));
+        : "names a symbol and no path"}`, { mechanism: refused.mechanism, entry: writtenEntry(refused) }));
 }
 /**
  * One record per site at which a suppression matched nothing, whatever the number of