@cplieger/deadset-ts 3.10.0 → 3.11.0

package/README.md

@@ -8,7 +8,7 @@ deadset-ts is a command-line analyzer for TypeScript and JavaScript projects. It
 
 deadset-ts is report-only. It never edits source, and it refuses any `--fix` flag.
 
-**Status: pre-release.** This version implements contract 3.2.0 and ships the analyzer's foundation: one compiler session per run over the projects `analysis.configurations` declares, in the order it lists them, each a compiler configuration file below the target, or, where it declares none, every `tsconfig` project discovered under the target (the explicit scope, every `tsconfig*.json`, each project's `references`), a fail-closed read of every project's diagnostics, configuration decoding against the contract's closed key list with `print-config` and its provenance, `print-projects`, the report-only guard, the symbol inventory of every declaration a project's own files hold down to its class and type members, the one-pass reference resolution over that inventory, which resolves each file's identifiers in batches ([batch-cap calibration](docs/batch-cap-calibration.md) is the measurement behind the batch size), and the root set `print-roots` prints. A root is a declaration the analysis keeps live without a reference: what a file exports when the manifest names it through `main`, `module`, `types`, `bin` or `exports`, or when `ts.entry_files` matches it; a library target's published API; the configuration, setup and test files of Vitest, Stryker and Playwright, the flat configuration of ESLint, and a worker or service worker a call addresses by a string literal; and every declaration a `roots.patterns` entry names. An entry that names nothing is reported as `DS1704` and fails the run. The entry-point conventions of other tools are not read, and `DECLINED_CONVENTIONS` lists each one with the reason. Seven exemption classes hold a declaration back from the sweep, and `print-retained` lists what each one held back: `interface-satisfaction`, a member an interface requires of a class whose value reaches that interface; `decorator`, a decorated member and every member of a decorated class; `injection-container`, a decorated property of a class a dependency-injection container constructs, being a class passed to a call `ts.injection_registrations` names or one a parameter of whose constructor carries a decorator; `framework-lifecycle`, a member a `ts.lifecycle_contracts` entry lists, on a class that is the entry's component by a decorator or a call the entry names or by extending a class it names; `serialization-contract`, the properties of a class whose values reach `JSON.stringify` or a declaration `ts.serializers` names, and those and its `toJSON` and `toString` where a value is passed to an `unknown` or `any` parameter of a function outside the analysis; and, at the lowest confidence, `template-field`, a member an action of a template under `analysis.template_dirs` names, and `reflective-lookup`, a member a literal key of an element access or of `Reflect.get`, `Reflect.set` or `Reflect.has` names. None of them holds back a `#private` member. `analyze` writes the report the Contract's report schema declares, with 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.
+**Status: pre-release.** This version implements contract 3.2.0 and ships the analyzer's foundation: one compiler session per run over the projects `analysis.configurations` declares, in the order it lists them, each a compiler configuration file below the target, or, where it declares none, every `tsconfig` project discovered under the target (the explicit scope, every `tsconfig*.json`, each project's `references`), a fail-closed read of every project's diagnostics, configuration decoding against the contract's closed key list with `print-config` and its provenance, `print-projects`, the report-only guard, the symbol inventory of every declaration a project's own files hold down to its class and type members, the one-pass reference resolution over that inventory, which resolves each file's identifiers in batches ([batch-cap calibration](docs/batch-cap-calibration.md) is the measurement behind the batch size), and the root set `print-roots` prints. A root is a declaration the analysis keeps live without a reference: what a file exports when the manifest names it through `main`, `module`, `types`, `bin` or `exports`, or when `ts.entry_files` matches it; a library target's published API; the configuration, setup and test files of Vitest, Stryker and Playwright, the flat configuration of ESLint, and a worker or service worker a call addresses by a string literal; and every declaration a `roots.patterns` entry names. An entry that names nothing is reported as `DS1704` and fails the run. The entry-point conventions of other tools are not read, and `DECLINED_CONVENTIONS` lists each one with the reason. Seven exemption classes hold a declaration back from the sweep, and `print-retained` lists what each one held back: `interface-satisfaction`, a member an interface requires of a class whose value reaches that interface; `decorator`, a decorated member and every member of a decorated class; `injection-container`, a decorated property of a class a dependency-injection container constructs, being a class passed to a call `ts.injection_registrations` names or one a parameter of whose constructor carries a decorator; `framework-lifecycle`, a member a `ts.lifecycle_contracts` entry lists, on a class that is the entry's component by a decorator or a call the entry names or by extending a class it names; `serialization-contract`, the properties of a class whose values reach `JSON.stringify` or a declaration `ts.serializers` names, and those and its `toJSON` and `toString` where a value is passed to an `unknown` or `any` parameter of a function outside the analysis; and, at the lowest confidence, `template-field`, a member an action of a template under `analysis.template_dirs` names, and `reflective-lookup`, a member a literal key of an element access or of `Reflect.get`, `Reflect.set` or `Reflect.has` names. None of them holds back a `#private` member. `analyze` writes the report the Contract's report schema declares, with text, JSON, GitHub annotation, SARIF 2.1.0 and template renderings beside it on request. `explain` answers why one declaration is reported, retained, live or dead, from the same analysis the report is built from. `describe` prints the analyzer's description with its recorded conformance result, which is `fail` for this version because consumer projects are not loaded yet, so an orchestrator that requires a conformance pass refuses this analyzer. The analysis is reached through the command, and through `run()` for a caller that runs the command in-process. The one runtime dependency is the `typescript` package at exactly 7.0.2, installed under the `@typescript/native` name until TypeScript 7.1 ships a compiler API the tooling can share.
 
 ## 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 --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                                         |
+`version` prints the analyzer version and the Contract version it implements, and exits 0. `print-config`, `print-projects`, `print-roots` and `print-retained` print what their row of the table says and exit 0, or 1 when `print-roots` reports a `DS1704`, and `print-retained` exits 2 when an `exemptions.disabled` entry is not an exemption class or an `analysis.template_dirs` entry is not a directory below the target root. `analyze --report=PATH` writes the JSON report to `PATH` through a temporary file renamed into place, each `--format` rendering at `PATH` with its suffix appended (`text` as `.txt`, `json` as `.json`, `github` as `.annotations` in GitHub workflow-command form, `sarif` as `.sarif`, and `template` as `.tmpl`, rendering the file `--template=FILE` names, written in a subset of Go's `text/template` action grammar over the report's JSON member names), and with `--baseline-write=FILE` a baseline of every finding; it writes nothing to standard output and exits with the Contract's exit-code table: 0 clean, 1 for a finding at or above `reporters.fail_on` or a stale suppression, 2 for a usage error, including a template that cannot be read or does not parse, 3 for a failed load or a rendering that cannot be written, and 4 for a pending finding, which outranks 1. `--exit-code=off` exits 0 whatever the verdict and names the verdict on standard error. The report names the target relative to the directory the run is invoked from, so a target outside that directory fails with 3. `describe` writes its JSON document to standard output and exits 0. `explain --why=SYM`, or the same request spelled `--why-live=SYM` or `--why-not=SYM`, prints why that one declaration is reported, retained, live or dead, with the shortest reference path from a root for a live one, and exits 0; a request that names no one declaration exits 2 and lists up to 20 declarations it partially matches. Any other invocation and no arguments print the usage line and exit 2.
+
+| Verb             | Job                                                                                |
+| ---------------- | ---------------------------------------------------------------------------------- |
+| `analyze`        | Analyze a project and write the report, its renderings and a baseline              |
+| `explain`        | Explain one declaration: the relation, the roots and the references that decide 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/src/analysis.js

@@ -304,14 +304,16 @@ function runAnalysisInputs(engine, host, scope, config, provenance, mode, detect
             })),
             testFileRules: testFileRulesOf(config.ts.testFiles, read.projects.flatMap((one) => one.configured.testFiles)),
         },
+        configured: read.projects.map((one) => one.configured),
     };
 }
 /**
  * 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.
+ * declared edges evaluated, the projects and test-file rules the report names, and the sweep
+ * an explanation reads.
  */
 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 };
+    const { inputs, run, configured } = runAnalysisInputs(engine, host, scope, config, provenance, mode, detectors);
+    return { result: findingsPass(inputs), run, swept: inputs.marked.swept, configured };
 }

package/dist/src/config.js

@@ -5,6 +5,12 @@ import { CONTRACT_VERSION } from "./version.js";
  * target supplied the setting it is about.
  */
 export const REPOSITORY_DOCUMENT = "deadset.json";
+/** The severities ranked, the strongest highest. */
+const SEVERITY_RANK = { allow: 0, warn: 1, deny: 2 };
+/** Whether a finding at one severity fails a run under the failing severity. */
+export function fails(severity, failOn) {
+    return SEVERITY_RANK[severity] >= SEVERITY_RANK[failOn];
+}
 /**
  * The configuration every documented default states. `targetKind` is empty: the
  * field has no default and is never inferred.

package/dist/src/findings-pass.js

@@ -3,14 +3,13 @@
  * applied and the declared edges evaluated, and the stale suppressions, the totals and the
  * verdict a report carries beside them.
  */
+import { fails } from "./config.js";
 import { decidedFindings } from "./findings/emitters.js";
 import { fileRefsOf, staleSuppressions, } from "./findings/self-check.js";
 import { isRowSubject, pairs, suppressionCounts } from "./suppress.js";
 import { EXIT_CLEAN, EXIT_FINDINGS } from "./verbs/verb.js";
 /** The exit code of a report holding at least one pending finding. */
 export const EXIT_PENDING = 4;
-/** The severities ranked, the strongest highest. */
-const SEVERITY_RANK = { allow: 0, warn: 1, deny: 2 };
 /** Two strings ordered bytewise. */
 function compare(a, b) {
     if (a === b) {
@@ -73,9 +72,8 @@ export function verdictOf(result, config) {
     if (result.totals.staleSuppressions > 0) {
         return EXIT_FINDINGS;
     }
-    const failing = SEVERITY_RANK[config.reporters.failOn];
-    const fails = result.findings.some((finding) => SEVERITY_RANK[finding.severity] >= failing);
-    return fails ? EXIT_FINDINGS : EXIT_CLEAN;
+    const failing = result.findings.some((finding) => fails(finding.severity, config.reporters.failOn));
+    return failing ? EXIT_FINDINGS : EXIT_CLEAN;
 }
 /**
  * The findings of a report as a baseline records them, in report order. A finding about a

package/dist/src/reporters/annotations.js

@@ -0,0 +1,36 @@
+import { fails } from "../config.js";
+import { KINDS } from "../kinds.js";
+/** The escapes a workflow command's message needs, so a line break does not end the command. */
+const DATA_ESCAPES = { "%": "%25", "\r": "%0D", "\n": "%0A" };
+/** The escapes a property value needs: a message's, and the property list's two separators. */
+const PROPERTY_ESCAPES = {
+    ...DATA_ESCAPES,
+    ":": "%3A",
+    ",": "%2C",
+};
+function escapeData(value) {
+    return value.replace(/[%\r\n]/gu, (char) => DATA_ESCAPES[char] ?? char);
+}
+function escapeProperty(value) {
+    return value.replace(/[%\r\n:,]/gu, (char) => PROPERTY_ESCAPES[char] ?? char);
+}
+/** The name of the kind a code names, and the code itself where no live kind carries it. */
+function kindName(code) {
+    return KINDS.get(code)?.name ?? code;
+}
+function command(level, at, endLine, title, message) {
+    return `::${level} file=${escapeProperty(at.path)},line=${String(at.line)},col=${String(at.column)},endLine=${String(endLine)},title=${escapeProperty(title)}::${escapeData(message)}`;
+}
+/**
+ * One workflow annotation per finding, then one per stale suppression, each naming its
+ * file, line, column and last line, titled by its code and kind. A finding at or above the
+ * failing severity is an error and one below it a warning; a stale suppression is an error,
+ * because its kind is fixed on at the failing severity.
+ */
+export function annotations(report, options) {
+    const lines = report.findings.map((found) => command(fails(found.severity, options.failOn) ? "error" : "warning", found.position, found.position.end_line, `${found.code} ${found.kind}`, found.message));
+    for (const stale of report.stale_suppressions) {
+        lines.push(command("error", stale.position, stale.position.line, `${stale.code} ${kindName(stale.code)}`, stale.message));
+    }
+    return lines.map((line) => `${line}\n`).join("");
+}

package/dist/src/reporters/fingerprint.js

@@ -0,0 +1,61 @@
+import { sha256Hex } from "./sha256.js";
+/** The unit appended after the last unit of a file. */
+const SENTINEL = 0xffffn;
+/** The number of significant units one line's hash covers. */
+const WINDOW = 100;
+const FACTOR = 37n;
+/** Arithmetic is unsigned 64-bit with wraparound. */
+const MASK = (1n << 64n) - 1n;
+const SPACE = 0x20;
+const TAB = 0x09;
+const CR = 0x0d;
+const LF = 0x0a;
+/**
+ * The units of one file the line fingerprint counts: every UTF-16 code unit but a space or
+ * a tab, a carriage return read as a line feed and the line feed following it dropped, then
+ * the sentinel.
+ */
+function significantUnits(text) {
+    const kept = [];
+    let afterCR = false;
+    for (let i = 0; i < text.length; i += 1) {
+        const unit = text.charCodeAt(i);
+        if (unit === SPACE || unit === TAB || (afterCR && unit === LF)) {
+            afterCR = false;
+            continue;
+        }
+        afterCR = unit === CR;
+        kept.push(BigInt(afterCR ? LF : unit));
+    }
+    kept.push(SENTINEL);
+    return kept;
+}
+/**
+ * The line fingerprint of every line of one file, indexed from zero. The procedure is the one
+ * a code-scanning service computes for a result that carries none, followed exactly, because
+ * a value that differs from the service's opens a second alert for one finding.
+ */
+export function lineHashes(text) {
+    const units = significantUnits(text);
+    const starts = [0];
+    for (let i = 0; i < units.length - 1; i += 1) {
+        if (units[i] === BigInt(LF)) {
+            starts.push(i + 1);
+        }
+    }
+    const seen = new Map();
+    return starts.map((start) => {
+        let hash = 0n;
+        for (let i = start; i < start + WINDOW; i += 1) {
+            hash = (hash * FACTOR + (units[i] ?? 0n)) & MASK;
+        }
+        const rendered = hash.toString(16);
+        const count = (seen.get(rendered) ?? 0) + 1;
+        seen.set(rendered, count);
+        return `${rendered}:${String(count)}`;
+    });
+}
+/** The key a baseline joins on, which a line move leaves unchanged. */
+export function symbolFingerprint(code, ref) {
+    return sha256Hex(`${code}\n${ref}`);
+}

package/dist/src/reporters/reporter.js

@@ -1 +1,7 @@
-export {};
+/** A rendering that cannot be written, which ends the run with the failure code. */
+export class RenderError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RenderError";
+    }
+}

package/dist/src/reporters/reporters.js

@@ -1,4 +1,8 @@
+import { annotations } from "./annotations.js";
 import { json } from "./json.js";
+import { RenderError } from "./reporter.js";
+import { sarif } from "./sarif.js";
+import { renderTemplate } from "./template.js";
 import { text } from "./text.js";
 /**
  * Every format this analyzer renders, each by its reporter and its file suffix. A format
@@ -7,4 +11,18 @@ import { text } from "./text.js";
 export const RENDERINGS = new Map([
     ["text", { render: text, suffix: ".txt" }],
     ["json", { render: json, suffix: ".json" }],
+    ["github", { render: annotations, suffix: ".annotations" }],
+    ["sarif", { render: sarif, suffix: ".sarif" }],
+    [
+        "template",
+        {
+            render: (report, options) => {
+                if (options.template === undefined) {
+                    throw new RenderError("the template rendering renders a template, and none was named");
+                }
+                return renderTemplate(options.template, report);
+            },
+            suffix: ".tmpl",
+        },
+    ],
 ]);

package/dist/src/reporters/rules.js

@@ -0,0 +1,178 @@
+/**
+ * The text of every live issue kind this analyzer's language carries, which a SARIF rule
+ * describes the kind with, written out rather than read at run time. A test compares this
+ * table against the Contract release the analyzer is written against.
+ */
+/** Every live issue kind whose languages include this analyzer's, by code, in ascending order. */
+export const RULE_TEXTS = new Map([
+    [
+        "DS1001",
+        {
+            rule: "An exported symbol with no reference in the target and no reference from any loaded consumer. A symbol referenced only from its own declaration site counts as unreferenced.",
+        },
+    ],
+    [
+        "DS1002",
+        {
+            rule: "An unexported symbol with no reference in the target. A symbol referenced only from its own declaration site counts as unreferenced.",
+        },
+    ],
+    [
+        "DS1003",
+        {
+            rule: "A struct field, class member or type member with no reference, a private member included. A member referenced only from its own declaration site counts as unreferenced.",
+        },
+    ],
+    [
+        "DS1004",
+        {
+            rule: "A symbol with zero production references and at least one test reference: an unused-exported or unused-unexported candidate whose test reference count is not zero, reported once under this code. A reference from a consumer's test files is a test reference unless the configuration counts consumer tests as production.",
+        },
+    ],
+    [
+        "DS1005",
+        {
+            rule: "A test symbol whose set of referenced target symbols is non-empty and every member of that set is reported dead. A test that references at least one live target symbol is never reported, no notion of a test's subject and no name matching enters the rule, and the message states the rule. The test joins the dead component of the symbols it references.",
+        },
+    ],
+    [
+        "DS1006",
+        {
+            rule: "A symbol carrying a deprecation marker and no production reference: an unused-exported, unused-unexported or unused-member candidate whose symbol is deprecated, reported once under this code. Go identifies the marker by the convention the standard tools recognize, TypeScript by the documentation tag its tools recognize.",
+        },
+    ],
+    [
+        "DS1101",
+        {
+            rule: "An exported symbol whose every reference is inside the symbol's own package or module, reported as a candidate for unexporting. The subject is a package-level declaration or a method, and three subjects are excluded: an interface method, whose exportedness is the contract of the interface that declares it; a struct field, which an encoder reads by name; and a method that satisfies an interface some symbol uses as a type, which cannot be unexported without its type ceasing to satisfy that interface. The finding names the narrower visibility the references support. A declared cross-language edge counts as an out-of-package reference; where the edge's other side is unknown to the analyzer the finding is emitted pending.",
+            precondition: "Closed world only. Reported always for a main package and an internal/ directory tree, and for a published package only when the configuration declares the consumer set complete and every declared consumer loads. A library with no consumer loaded and no complete consumer set declared gets this finding on its internal/ tree and its main packages and never on its published API.",
+        },
+    ],
+    [
+        "DS1103",
+        {
+            rule: "An unused exported symbol in a package or file no external code can import: an unused-exported candidate whose enclosing package or file is unimportable from outside, reported once under this code at the certain class, because unimportability is a property of the package graph rather than of the consumer set.",
+        },
+    ],
+    [
+        "DS1104",
+        {
+            rule: "An exported declaration used only inside its own file, reported as a candidate for removing the export keyword. The finding names the narrower visibility the references support.",
+            precondition: "Closed world only. Reported in a file that is not an entry file and that either belongs to a project whose consumer set the configuration declares complete or is reached by no manifest export. A declared cross-language edge counts as a reference from outside the file; where the edge's other side is unknown to the analyzer the finding is emitted pending.",
+        },
+    ],
+    [
+        "DS1201",
+        {
+            rule: "An interface no symbol uses as a type, counting uses from every loaded module. The finding names the concrete implementations and their positions, and the interface's members join its dead component rather than being reported as independent unused declarations.",
+        },
+    ],
+    [
+        "DS1203",
+        {
+            rule: "An interface method that no call site invokes or selects through the interface, whatever the number of implementations. The finding names the concrete implementations and their positions.",
+            precondition: "Exempt: every method of an interface that declares an unexported method, the sum-type shape whose method set exists to restrict the implementors; and every marker method, an interface method whose every implementation carries an empty body.",
+        },
+    ],
+    [
+        "DS1301",
+        {
+            rule: "A package-level or module-level variable, struct field, class member or collection that production code writes and never reads. In production mode a read from a test file counts as no read. A comparison of struct values reads every field of the type: in Go, a value of a struct type used as an operand of `==` or `!=`, as a map key, or as a `switch` tag or `case` expression is a read of every field of that type, transitively through the fields of every struct type it holds, recorded at the comparison, because equality reads every field and a field that decides equality carries information. In TypeScript a comparison of two object references reads no member, because `===` compares identity and never a member. The finding names each write position, so the deletion set is visible.",
+        },
+    ],
+    [
+        "DS1302",
+        {
+            rule: "An enumerated member that no symbol names, at the reachability class derived for the member and with no confidence ceiling below it. Every member of a type that carries a string, text or binary conversion method, or that a conversion from an integer or a wire value produces, is retained by the enum-group exemption first, so a member reached only by value is never a candidate.",
+        },
+    ],
+    [
+        "DS1303",
+        {
+            rule: "A type parameter of a function or method that no part of the declaration's signature and no part of the declaration's body names, at the certain class. The deletion is local to the declaration and the explicit instantiations the reference set already lists.",
+            precondition: "Function and method type parameters only. A type parameter of a type declaration is never reported, because a phantom type parameter such as `type ID[T any] int` makes two instantiations distinct types while naming the parameter nowhere, so deleting it changes the program.",
+        },
+    ],
+    [
+        "DS1501",
+        {
+            rule: "A source file no configuration in the build matrix builds. On the Go side the finding names the build constraint that excluded the file. A file whose build constraint is the ignore tag is never reported: the toolchain applies no build constraint to a file named on its own command line, so that tag is the toolchain's convention for a file built by hand. A file any other custom tag excludes is reported under a matrix the configuration declares complete, because completeness is the maintainer's assertion that the listed configurations are every one the target builds, and a configuration the maintainer builds by hand belongs in that list.",
+            precondition: 'Reported only when the configuration declares the build matrix complete, and never for a file the toolchain ignored solely because it imports "C" under a build with cgo disabled; such a file is recorded as excluded by cgo rather than as never built.',
+        },
+    ],
+    [
+        "DS1502",
+        {
+            rule: "A source file that no import reaches, that no root names, and in which no declared cross-language edge names a declaration. An edge's side names a declaration as a root names one, so a file holding a declaration an edge names is evaluated with the edge rather than reported: whether that declaration is dead is the edge evaluation's to say, and the merge resolves it against the paired side.",
+        },
+    ],
+    [
+        "DS1601",
+        {
+            rule: "A directly declared dependency that no import in the target needs. On the Go side, a direct require whose module provides no package any target package or test variant imports. On the TypeScript side, a manifest dependency, development dependency or peer dependency the project's import closure does not need. A deletion finding whose fix would remove the last use of a dependency names that dependency.",
+            precondition: "On the Go side the rule is the semantics of `go mod tidy -diff` exactly: a requirement marked indirect is never reported, because it exists to pin a transitive version and removing it changes the build list.",
+        },
+    ],
+    [
+        "DS1701",
+        {
+            rule: "A suppression that carries no reason, in any of the three documents: an inline directive, an ignore-file entry or a baseline row. For the ignore file and the baseline, an entry or a row whose reason field is absent, empty or whitespace only is refused and reported rather than matched.",
+        },
+    ],
+    [
+        "DS1702",
+        {
+            rule: "An ignore-file entry or a baseline row that names a symbol and no file path. The entry is reported rather than matched, so a bare name cannot mask a match anywhere else in the project; the inline directive is scoped by its position and cannot be unscoped.",
+        },
+    ],
+    [
+        "DS1703",
+        {
+            rule: "A suppression that matches no current finding, at either mechanism and in the baseline alike. The run exits with the findings code when at least one is reported. The kind is fixed on at deny: no flag, no severity setting and no per-mechanism exception reduces it below a finding, and a configuration naming this code under a severity key is an unimplemented key.",
+        },
+    ],
+    [
+        "DS1704",
+        {
+            rule: "A configured root that matches no symbol, or a configured root pattern that matches no symbol. A root set nobody checks silently changes every result, so a stale one is a finding. The kind is fixed on at deny: no flag, no severity setting and no exception reduces it below a finding, and a configuration naming this code under a severity key is an unimplemented key.",
+        },
+    ],
+    [
+        "DS1705",
+        {
+            rule: "A declared cross-language edge with a side that at least one analyzer evaluated and every evaluation of that side reports absent, so no analyzer that ran enumerates that side's symbol. Emitted by the merge, once per edge, never by an analyzer, so a stale edge is visible rather than silently inert. A dead side paired with an absent side drops its pending finding, and the edge is the reported defect: a misspelled reference must not turn a live pairing into a deletion.",
+        },
+    ],
+    [
+        "DS1801",
+        {
+            rule: "A parameter with no reference inside its function body, on a function whose signature is free to change.",
+            precondition: "The signature must be free, defined as follows: the function is not a method retained by interface satisfaction, is not used as a value, is not a go:linkname or cgo target, and is not a stub whose body is empty or only panics. A parameter its body never names is dead whatever the callers, so a published declaration of a library is reported too, with the fixability the vocabulary gives the kind: the signature change is a breaking change.",
+        },
+    ],
+    [
+        "DS1803",
+        {
+            rule: "A result value that no call site of the function uses, on a function whose signature is free to change.",
+            precondition: "The same free-signature rule as unused-parameter, plus a closed-world condition: every call site of the function must be in the loaded graph, because an unknown caller may consume the result, so the kind reports only for a function whose callers are all visible.",
+        },
+    ],
+    [
+        "DS1805",
+        {
+            rule: "A statement that control flow cannot reach, at the precision the language's compiler applies to the same construct.",
+        },
+    ],
+    [
+        "DS1807",
+        {
+            rule: "A write to a local variable with no read before the next write to it or the end of its scope, computed on the same read-and-write classification the write-only-symbol kind uses. The finding names the write position.",
+        },
+    ],
+    [
+        "DS1809",
+        {
+            rule: "A switch case whose type or value an earlier case in the same switch already covers.",
+        },
+    ],
+]);