@cplieger/deadset-ts 3.8.0 → 3.9.0

package/README.md

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

package/dist/bin/node-host.js

@@ -1,5 +1,6 @@
-import { readdirSync, readFileSync, statSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { closeSync, fchmodSync, fsyncSync, openSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 /** The name the manifest of this package declares. */
 const PACKAGE_NAME = "@cplieger/deadset-ts";
@@ -43,6 +44,34 @@ function readVersion() {
         at = up;
     }
 }
+/** The mode every document the command writes carries. */
+const DOCUMENT_MODE = 0o644;
+/**
+ * Writes one document through a temporary file in the same directory, flushed and then
+ * renamed into place, so a run that dies partway leaves no truncated document at the path.
+ */
+function writeAtomically(path, text) {
+    const temporary = join(dirname(path), `.${basename(path)}.${randomBytes(6).toString("hex")}`);
+    const fd = openSync(temporary, "wx", DOCUMENT_MODE);
+    try {
+        try {
+            fchmodSync(fd, DOCUMENT_MODE);
+            const bytes = Buffer.from(text, "utf8");
+            for (let written = 0; written < bytes.length;) {
+                written += writeSync(fd, bytes, written);
+            }
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(temporary, path);
+    }
+    catch (error) {
+        rmSync(temporary, { force: true });
+        throw error;
+    }
+}
 /**
  * The filesystem of the platform the command runs on, and the version of the
  * package it was installed from.
@@ -70,5 +99,6 @@ export function nodeHost() {
             found ??= readVersion();
             return found;
         },
+        writeFile: writeAtomically,
     };
 }

package/dist/src/analysis.js

@@ -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/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

package/dist/src/references.js

@@ -272,6 +272,22 @@ function sitesOf(file, declarations, fileId) {
 function patternRule(index) {
     return `test-file-pattern-${String(index + 1)}`;
 }
+/**
+ * The rules over the test files of several projects at once, ordered by rule: a file two
+ * projects hold is one file, so each rule counts the distinct paths it matches.
+ */
+export function testFileRulesOf(testFiles, paths) {
+    const distinct = [...new Set(paths)];
+    return testFiles
+        .map((pattern, index) => {
+        const expression = globExpression(pattern);
+        return {
+            rule: patternRule(index),
+            matched: distinct.filter((path) => expression.test(path)).length,
+        };
+    })
+        .sort((a, b) => compare(a.rule, b.rule));
+}
 /** Two strings ordered bytewise, which is the order every set of a run is read in. */
 function compare(a, b) {
     if (a === b) {
@@ -281,7 +297,7 @@ function compare(a, b) {
 }
 /**
  * Every reference one project's own files make to the project's own declarations, in
- * position order, and the test-file rules that classified those files.
+ * position order, and the files the test-file rules classified.
  *
  * `held` is the inventory of the same project, whose declaration map is what a resolved
  * symbol is looked up in; `targetRoot` is the absolute path every position is rendered
@@ -297,7 +313,6 @@ export function references(project, held, targetRoot, options) {
     const cap = options.batchCap ?? DEFAULT_BATCH_CAP;
     const declarations = held.declarations;
     const patterns = options.testFiles.map(globExpression);
-    const matched = options.testFiles.map(() => 0);
     const found = [];
     const tests = [];
     const chains = aliasChains(project, held);
@@ -332,13 +347,7 @@ export function references(project, held, targetRoot, options) {
     };
     for (const file of files) {
         const path = renderPosition(file, targetRoot, 0).path;
-        const hits = patterns.map((pattern) => pattern.test(path));
-        hits.forEach((hit, index) => {
-            if (hit) {
-                matched[index] = (matched[index] ?? 0) + 1;
-            }
-        });
-        const test = hits.includes(true);
+        const test = patterns.some((pattern) => pattern.test(path));
         if (test) {
             tests.push(path);
         }
@@ -449,9 +458,6 @@ export function references(project, held, targetRoot, options) {
     return {
         configFile: project.configFile,
         references: found,
-        testFileRules: options.testFiles
-            .map((_pattern, index) => ({ rule: patternRule(index), matched: matched[index] ?? 0 }))
-            .sort((a, b) => compare(a.rule, b.rule)),
         testFilePaths: tests.sort(compare),
         cost: { batched, fileBatches, residueFallbacks, shorthandLookups, aliasSteps: chains.steps },
     };

package/dist/src/report.js

@@ -0,0 +1,237 @@
+/**
+ * The report one analysis writes: the Contract's report document, member for member and
+ * in the order its schema lists them, built from what one run answered. Every reporter
+ * renders this document, so no two renderings disagree about which findings exist.
+ */
+/** The version of the report schema this analyzer writes a report to. */
+export const SCHEMA_VERSION = "6.0.0";
+/** The name this analyzer writes every document under and mints every identifier with. */
+export const ANALYZER_NAME = "deadset-ts";
+/** The language this analyzer claims. */
+export const LANGUAGE = "ts";
+/** Two strings ordered bytewise. */
+function compare(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    return a < b ? -1 : 1;
+}
+function wirePosition(position) {
+    return {
+        path: position.path,
+        line: position.line,
+        column: position.column,
+        end_line: position.endLine,
+    };
+}
+function wireSymbol(symbol) {
+    return { ref: symbol.ref, name: symbol.name, position: wirePosition(symbol.position) };
+}
+/** The details one code carries, in the order the finding schema lists them. */
+function wireDetails(details) {
+    const { entry } = details;
+    return {
+        ...(details.narrowerVisibility === undefined
+            ? {}
+            : { narrower_visibility: details.narrowerVisibility }),
+        ...(details.implementations === undefined
+            ? {}
+            : { implementations: details.implementations.map(wireSymbol) }),
+        ...(details.writePositions === undefined
+            ? {}
+            : { write_positions: details.writePositions.map(wirePosition) }),
+        ...(details.dependencyClass === undefined ? {} : { dependency_class: details.dependencyClass }),
+        ...(details.mechanism === undefined ? {} : { mechanism: details.mechanism }),
+        ...(entry === undefined
+            ? {}
+            : {
+                entry: {
+                    code: entry.code,
+                    ...(entry.symbol === undefined ? {} : { symbol: entry.symbol }),
+                    ...(entry.path === undefined ? {} : { path: entry.path }),
+                    ...(entry.reason === undefined ? {} : { reason: entry.reason }),
+                },
+            }),
+    };
+}
+/** One finding as the finding schema spells it, member for member in its order. */
+export function wireFinding(finding) {
+    return {
+        code: finding.code,
+        kind: finding.kind,
+        language: finding.language,
+        position: wirePosition(finding.position),
+        symbol: {
+            ref: finding.symbol.ref,
+            kind: finding.symbol.kind,
+            name: finding.symbol.name,
+            size_lines: finding.symbol.sizeLines,
+        },
+        reachability_class: finding.reachabilityClass,
+        confidence: finding.confidence,
+        ...(finding.livenessRelation === undefined
+            ? {}
+            : { liveness_relation: finding.livenessRelation }),
+        test_only: finding.testOnly,
+        generated: finding.generated,
+        component: {
+            id: finding.component.id,
+            root: finding.component.root,
+            symbol_count: finding.component.symbolCount,
+            deletable_lines: finding.component.deletableLines,
+        },
+        retained_by: finding.retainedBy,
+        configurations: finding.configurations,
+        consumers_loaded: finding.consumersLoaded,
+        fixability: finding.fixability,
+        severity: finding.severity,
+        message: finding.message,
+        details: wireDetails(finding.details),
+    };
+}
+function wireEvaluation(evaluation) {
+    return {
+        edge: evaluation.edge,
+        side: evaluation.side,
+        symbol: evaluation.symbol,
+        state: evaluation.state,
+        ...(evaluation.finding === undefined ? {} : { finding: wireFinding(evaluation.finding) }),
+    };
+}
+function wireStale(stale) {
+    return {
+        code: stale.code,
+        mechanism: stale.mechanism,
+        entry: {
+            code: stale.entry.code,
+            ...(stale.entry.symbol === undefined ? {} : { symbol: stale.entry.symbol }),
+            path: stale.entry.path,
+            reason: stale.entry.reason,
+        },
+        position: {
+            path: stale.position.path,
+            line: stale.position.line,
+            column: stale.position.column,
+        },
+        symbol: stale.symbol,
+        message: stale.message,
+    };
+}
+/** The canonical key over two findings: path, line, column, code, then the symbol reference. */
+function canonical(a, b) {
+    return (compare(a.position.path, b.position.path) ||
+        a.position.line - b.position.line ||
+        a.position.column - b.position.column ||
+        compare(a.code, b.code) ||
+        compare(a.symbol.ref, b.symbol.ref));
+}
+/** The canonical key over two stale suppressions, each component from the record's own member. */
+function canonicalStale(a, b) {
+    return (compare(a.position.path, b.position.path) ||
+        a.position.line - b.position.line ||
+        a.position.column - b.position.column ||
+        compare(a.code, b.code) ||
+        compare(a.symbol, b.symbol));
+}
+/** Edge evaluations by edge, then side, then their compact encodings. */
+function byEdge(a, b) {
+    return (compare(a.edge, b.edge) ||
+        compare(a.side, b.side) ||
+        compare(JSON.stringify(a), JSON.stringify(b)));
+}
+/**
+ * The lines a reader deletes by acting on every finding: each distinct component a root
+ * finding names, counted once however many of its roots the findings hold.
+ */
+function deletableLines(findings) {
+    const counted = new Map();
+    for (const finding of findings) {
+        if (finding.component.root) {
+            counted.set(finding.component.id, finding.component.deletable_lines);
+        }
+    }
+    let total = 0;
+    for (const lines of counted.values()) {
+        total += lines;
+    }
+    return total;
+}
+/** The totals of one finding set, counted over the whole set. */
+function totalsOf(findings, result) {
+    const bySeverity = { allow: 0, warn: 0, deny: 0 };
+    for (const finding of findings) {
+        bySeverity[finding.severity] += 1;
+    }
+    return {
+        findings: findings.length,
+        by_severity: bySeverity,
+        deletable_lines: deletableLines(findings),
+        suppressions_in_effect: result.totals.suppressionsInEffect,
+        reasons_recorded: result.totals.reasonsRecorded,
+        stale_suppressions: result.staleSuppressions.length,
+        pending: result.totals.pending,
+        omitted: 0,
+    };
+}
+/** Builds the report of one run, every array in the order the Contract fixes for it. */
+export function buildReport(input) {
+    const findings = input.result.findings.map(wireFinding).sort(canonical);
+    const unavailable = [...new Map(input.unavailable.map((one) => [one.id, one])).values()]
+        .sort((a, b) => compare(a.id, b.id))
+        .map((one) => ({ id: one.id, role: "consumer", reason: one.reason }));
+    return {
+        schema_version: SCHEMA_VERSION,
+        contract_version: input.contractVersion,
+        analyzer: {
+            name: ANALYZER_NAME,
+            version: input.version,
+            languages: [LANGUAGE],
+            schema_versions_accepted: [SCHEMA_VERSION],
+            conformance: {
+                corpus_version: input.conformance.corpusVersion,
+                result: input.conformance.result,
+                digest: input.conformance.digest,
+            },
+        },
+        target: { kind: input.target.kind, root: input.target.root, identity: input.target.identity },
+        configurations: [...input.configurations]
+            .sort((a, b) => compare(a.id, b.id))
+            .map((one) => ({ id: one.id, project: one.project })),
+        configurations_not_built: [],
+        consumers: { declared: unavailable.length, loaded: [], unavailable },
+        findings,
+        edge_evaluations: input.result.edgeEvaluations.map(wireEvaluation).sort(byEdge),
+        stale_suppressions: input.result.staleSuppressions.map(wireStale).sort(canonicalStale),
+        declared_gaps: [],
+        excluded_by_cgo: [],
+        test_file_rules: [...input.testFileRules]
+            .sort((a, b) => compare(a.rule, b.rule) || a.matched - b.matched)
+            .map((one) => ({ rule: one.rule, matched: one.matched })),
+        totals: totalsOf(findings, input.result),
+    };
+}
+/**
+ * The report with its findings in the order a configuration asks for. By size, a finding
+ * whose component a deletion shrinks more comes first, then one whose subject is larger,
+ * then the canonical key, so the order stays total; by position it is the canonical key.
+ */
+export function sortFindings(report, by) {
+    const bySize = (a, b) => b.component.deletable_lines - a.component.deletable_lines ||
+        b.symbol.size_lines - a.symbol.size_lines ||
+        canonical(a, b);
+    return { ...report, findings: [...report.findings].sort(by === "size" ? bySize : canonical) };
+}
+/**
+ * The report holding the first `most` findings of its order, the rest counted as omitted.
+ * Every other total keeps describing the whole set. Zero keeps every finding.
+ */
+export function capFindings(report, most) {
+    if (most <= 0 || report.findings.length <= most) {
+        return report;
+    }
+    return {
+        ...report,
+        findings: report.findings.slice(0, most),
+        totals: { ...report.totals, omitted: report.findings.length - most },
+    };
+}

package/dist/src/reporters/json.js

@@ -0,0 +1,4 @@
+/** The indentation of the report document, which with the schema's member order fixes its bytes. */
+const INDENT = 2;
+/** The report document itself: the report, indented, with a closing newline. */
+export const json = (report) => `${JSON.stringify(report, null, INDENT)}\n`;

package/dist/src/reporters/reporter.js

@@ -0,0 +1 @@
+export {};

package/dist/src/reporters/reporters.js

@@ -0,0 +1,10 @@
+import { json } from "./json.js";
+import { text } from "./text.js";
+/**
+ * Every format this analyzer renders, each by its reporter and its file suffix. A format
+ * absent from the table is refused rather than silently not written.
+ */
+export const RENDERINGS = new Map([
+    ["text", { render: text, suffix: ".txt" }],
+    ["json", { render: json, suffix: ".json" }],
+]);

package/dist/src/reporters/text.js

@@ -0,0 +1,34 @@
+/** The kind token and the confidence a stale suppression is rendered with, both fixed. */
+const STALE_KIND = "suppression";
+const STALE_CONFIDENCE = "certain";
+/** A count with the word for it, so the summary reads as a sentence. */
+function counted(n, one, many) {
+    return `${String(n)} ${n === 1 ? one : many}`;
+}
+/** The report's totals in one line, in the order the report declares them. */
+function summary(totals) {
+    const { allow, warn, deny } = totals.by_severity;
+    return [
+        `summary: ${counted(totals.findings, "finding", "findings")} (${String(allow)} allow, ${String(warn)} warn, ${String(deny)} deny)`,
+        counted(totals.deletable_lines, "deletable line", "deletable lines"),
+        counted(totals.suppressions_in_effect, "suppression in effect", "suppressions in effect"),
+        counted(totals.reasons_recorded, "reason recorded", "reasons recorded"),
+        counted(totals.stale_suppressions, "stale suppression", "stale suppressions"),
+        `${String(totals.pending)} pending`,
+        `${String(totals.omitted)} omitted`,
+    ].join(", ");
+}
+/**
+ * One line per finding in the report's order, then one per stale suppression, then the
+ * summary. A finding line is `path:line:col: kind name: message [confidence] (CODE)`; the
+ * summary is deliberately not in that shape, so a filter for finding lines yields exactly
+ * them. Nothing else is written: no timestamp, duration or host detail.
+ */
+export const text = (report) => {
+    const lines = report.findings.map((found) => `${found.position.path}:${String(found.position.line)}:${String(found.position.column)}: ${found.symbol.kind} ${found.symbol.name}: ${found.message} [${found.confidence}] (${found.code})`);
+    for (const stale of report.stale_suppressions) {
+        lines.push(`${stale.position.path}:${String(stale.position.line)}:${String(stale.position.column)}: ${STALE_KIND} ${stale.symbol}: ${stale.message} [${STALE_CONFIDENCE}] (${stale.code})`);
+    }
+    lines.push(summary(report.totals));
+    return `${lines.join("\n")}\n`;
+};