@cplieger/deadset-ts 3.1.0 → 3.2.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 2.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. 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`, `print-retained` 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.0.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. 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.
 
 ## Install
 
@@ -28,7 +28,7 @@ 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` and `print-roots` print what their row of the table says and exit 0, or 1 when `print-roots` reports a `DS1704`. `analyze`, `explain`, `print-retained`, `describe`, any other invocation and no arguments print the usage line and exit 2.
+`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. `analyze`, `explain`, `describe`, any other invocation and no arguments print the usage line and exit 2.
 
 | Verb             | Job                                                                             |
 | ---------------- | ------------------------------------------------------------------------------- |
@@ -37,7 +37,7 @@ npx deadset-ts version
 | `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 symbol an exemption class held back, with the class                 |
+| `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                                        |
 

package/dist/src/analysis.js

@@ -8,6 +8,7 @@
  * project's checker, and that holds only for views the session itself hands out.
  */
 import { diagnosticErrors, discoverProjects, DiscoveryError } from "./discover.js";
+import { computeExemptions, disabledClasses, exemptionsOf, retainedIn, } from "./exempt.js";
 import { inventory } from "./inventory.js";
 import { readManifest } from "./manifest.js";
 import { matrixOf, sweepMatrix } from "./matrix.js";
@@ -117,27 +118,40 @@ export function runRoots(engine, host, scope, config, provenance) {
         findings: unmatchedRoots(unmatched, documentOf(host, provenance, ROOTS_SETTING, targetRoot)),
     };
 }
+/** The exemption classes this analyzer detects, each by its detector; any other retains nothing. */
+const DETECTORS = new Map();
 /**
  * Sweeps the run the scope and the configuration describe. Each project's references
- * are read against its own inventory with the configured test-file patterns while its
- * view is open; the projects then merge into one matrix in discovery order, which is
- * swept under the input the caller decided once for the run. A project that carries
- * an error ends the run before any project is swept.
+ * and exemptions are read against its own inventory while its view is open; the
+ * projects then merge into one matrix in the run's order, which is swept under the
+ * caller's marks and mode with the exemptions every project found. A record found in
+ * one configuration holds in every configuration that holds its declaration, because
+ * an exemption is evidence of a use the analysis cannot see and a use in one
+ * configuration is a use. A project that carries an error ends the run before any
+ * project is swept.
  */
-export function runSweep(engine, host, scope, config, input) {
+export function runSweep(engine, host, scope, config, input, detectors = DETECTORS) {
     const targetRoot = scope.target.path;
-    const configured = readProjects(engine, host, scope, config, (project, read) => {
-        const resolved = references(project, read.held, targetRoot, {
+    const disabled = disabledClasses(config);
+    const read = readProjects(engine, host, scope, config, (project, projectRead) => {
+        const resolved = references(project, projectRead.held, targetRoot, {
             testFiles: config.ts.testFiles,
         });
-        return {
-            configuration: read.configuration,
-            symbols: read.held.symbols,
+        const configured = {
+            configuration: projectRead.configuration,
+            symbols: projectRead.held.symbols,
             references: resolved.references,
-            roots: read.rooted.liveUnderReachability,
+            roots: projectRead.rooted.liveUnderReachability,
             testFiles: resolved.testFilePaths,
         };
+        const exempt = computeExemptions({ project, held: projectRead.held, targetRoot }, detectors, {
+            disabled,
+            mode: input.mode,
+            testFiles: new Set(resolved.testFilePaths),
+        });
+        return { configured, exempt };
     });
-    const matrix = matrixOf(configured);
-    return { matrix, sweep: sweepMatrix(matrix, input) };
+    const matrix = matrixOf(read.map((one) => one.configured));
+    const swept = { ...input, exempt: exemptionsOf(read.flatMap((one) => one.exempt)) };
+    return { matrix, sweep: sweepMatrix(matrix, swept), retained: retainedIn(matrix, swept) };
 }

package/dist/src/exempt-classes.js

@@ -0,0 +1,36 @@
+/**
+ * The exemption classes of the Contract's vocabulary, in its order: each class's name,
+ * the languages it runs on and the confidence it is recorded at.
+ *
+ * The rows are written out rather than read from the Contract at run time, for the
+ * reason the fixed severity codes are, and a test holds them equal to the Contract
+ * release this analyzer implements. A class name is a type, so a detector table or a
+ * record naming a class the vocabulary does not hold, or one that runs on another
+ * language only, does not compile.
+ */
+/** Every class of the vocabulary, in the order the Contract lists them. */
+export const EXEMPTION_CLASSES = [
+    { class: "interface-satisfaction", languages: ["go", "ts"], confidence: "certain" },
+    { class: "encoding-reflection", languages: ["go"], confidence: "certain" },
+    { class: "format-verb-contract", languages: ["go"], confidence: "certain" },
+    { class: "errors-duck-typing", languages: ["go"], confidence: "certain" },
+    { class: "enum-group", languages: ["go", "ts"], confidence: "certain" },
+    { class: "generated-file", languages: ["go"], confidence: "certain" },
+    { class: "linkname-cgo-asm-plugin", languages: ["go"], confidence: "certain" },
+    { class: "template-field", languages: ["go", "ts"], confidence: "possible" },
+    { class: "reflective-lookup", languages: ["go", "ts"], confidence: "possible" },
+    { class: "decorator", languages: ["ts"], confidence: "certain" },
+    { class: "injection-container", languages: ["ts"], confidence: "certain" },
+    { class: "framework-lifecycle", languages: ["ts"], confidence: "certain" },
+    { class: "serialization-contract", languages: ["ts"], confidence: "certain" },
+];
+function runsOnTS(row) {
+    const languages = row.languages;
+    return languages.includes("ts");
+}
+/** The classes that run on TypeScript, in the vocabulary's order. */
+export const TS_EXEMPTION_CLASSES = EXEMPTION_CLASSES.filter(runsOnTS).map((row) => row.class);
+/** Whether one name is a class of the vocabulary, whichever language it runs on. */
+export function isExemptionClass(name) {
+    return EXEMPTION_CLASSES.some((row) => row.class === name);
+}

package/dist/src/exempt.js

@@ -0,0 +1,132 @@
+/**
+ * The exemption framework: the classes of reason for which a declaration the reference
+ * graph alone would report is live all the same. A class is policy over what one
+ * project's checker answers, and its detector names the declarations it holds back;
+ * this module runs the detectors, decides which of their records stand, and answers
+ * which records held something back. It names no class's detector: the composition
+ * hands it the table of the classes it has.
+ */
+import { ConfigError } from "./config.js";
+import { EXEMPTION_CLASSES, isExemptionClass, TS_EXEMPTION_CLASSES, } from "./exempt-classes.js";
+import { byPosition, positionKey } from "./position.js";
+import { sweep } from "./sweep.js";
+/**
+ * The classes `exemptions.disabled` switches off. A name is refused unless the
+ * vocabulary holds it; a class that runs on another language only is admitted and
+ * switches nothing off here, so one configuration serves every analyzer.
+ */
+export function disabledClasses(config) {
+    const disabled = new Set();
+    for (const name of config.exemptionsDisabled) {
+        if (!isExemptionClass(name)) {
+            const known = EXEMPTION_CLASSES.map((row) => row.class).join(", ");
+            throw new ConfigError("malformed", "exemptions.disabled", `exemptions.disabled: ${JSON.stringify(name)} is not an exemption class: the classes are ${known}`);
+        }
+        disabled.add(name);
+    }
+    return disabled;
+}
+/**
+ * The records one project's detectors found, each class in the vocabulary's order and
+ * none of a switched-off class. Under a production mode a record whose evidence is
+ * written in a test file holds nothing, as a reference a test file makes is none there.
+ */
+export function computeExemptions(input, detectors, holding) {
+    const found = [];
+    for (const exemptionClass of TS_EXEMPTION_CLASSES) {
+        const detect = detectors.get(exemptionClass);
+        if (detect === undefined || holding.disabled.has(exemptionClass)) {
+            continue;
+        }
+        for (const evidence of detect(input)) {
+            if (holding.mode.production && holding.testFiles.has(evidence.site.path)) {
+                continue;
+            }
+            found.push({
+                id: evidence.id,
+                class: exemptionClass,
+                detail: evidence.detail,
+                site: evidence.site,
+            });
+        }
+    }
+    return exemptionsOf(found);
+}
+/** Two strings ordered bytewise. */
+function compare(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    return a < b ? -1 : 1;
+}
+/**
+ * Records as a run holds them: ordered by site, then class, then declaration, and one
+ * per declaration, class and detail, the one at the first site. A fact found at many
+ * sites, or by several projects, is one record.
+ */
+export function exemptionsOf(found) {
+    const ordered = [...found].sort((a, b) => byPosition(a.site, b.site) || compare(a.class, b.class) || compare(a.id, b.id));
+    const seen = new Set();
+    return ordered.filter((record) => {
+        const fact = [record.id, record.class, record.detail].join("\u0000");
+        if (seen.has(fact)) {
+            return false;
+        }
+        seen.add(fact);
+        return true;
+    });
+}
+/** The records per declaration, each declaration's in the order given. */
+function byDeclaration(records) {
+    const grouped = new Map();
+    for (const record of records) {
+        const held = grouped.get(record.id);
+        if (held === undefined) {
+            grouped.set(record.id, [record]);
+        }
+        else {
+            held.push(record);
+        }
+    }
+    return grouped;
+}
+/**
+ * The records that held back a declaration some configuration of the run would
+ * otherwise judge dead: each configuration's graph is swept once more with no
+ * exemption and the marks it was given, and a record is retained when one of those
+ * sweeps judged its declaration a candidate. A record that holds a declaration back in
+ * one configuration is retained whatever another configuration answers about it, as a
+ * run of that configuration alone would report the declaration without it. A record
+ * on a declaration that a relation or a mark holds live in every configuration held
+ * nothing back. The order is the declarations' site order, and for one declaration
+ * the input's.
+ */
+export function retainedIn(matrix, input) {
+    const exempt = input.exempt ?? [];
+    if (exempt.length === 0) {
+        return [];
+    }
+    const bare = { marked: input.marked, mode: input.mode };
+    const dead = new Set(matrix.graphs.flatMap((graph) => sweep(graph, bare).candidates.map((candidate) => candidate.id)));
+    const held = byDeclaration(exempt.filter((record) => dead.has(record.id)));
+    return matrix.union.symbols.flatMap((symbol) => held.get(symbol.id) ?? []);
+}
+/**
+ * One line per held-back declaration, in site order: its reference, then each record's
+ * class, site and detail, all separated by tabs.
+ */
+export function retainedLines(symbols, retained) {
+    const held = byDeclaration(retained);
+    return symbols.flatMap((symbol) => {
+        const records = held.get(symbol.id);
+        if (records === undefined) {
+            return [];
+        }
+        const fields = records.flatMap((record) => [
+            record.class,
+            positionKey(record.site),
+            record.detail,
+        ]);
+        return [[symbol.ref, ...fields].join("\t")];
+    });
+}

package/dist/src/run.js

@@ -1,6 +1,7 @@
-import { runRoots } from "./analysis.js";
+import { runRoots, runSweep } from "./analysis.js";
 import { ConfigError, REPOSITORY_DOCUMENT } from "./config.js";
 import { diagnosticErrors, discoverProjects, DiscoveryError, renderDiagnostic, } from "./discover.js";
+import { retainedLines } from "./exempt.js";
 import { joinPath, resolvePath } from "./paths.js";
 import { printConfig } from "./print.js";
 import { resolve, resolveMatrix } from "./resolve.js";
@@ -174,6 +175,9 @@ export function run(args, out, err, host, openClient = (collectTiming) => openEn
     if (verb === "print-roots") {
         return printRootsVerb(args.slice(1), out, err, host, openClient);
     }
+    if (verb === "print-retained") {
+        return printRetainedVerb(args.slice(1), out, err, host, openClient);
+    }
     if (verb !== undefined && VERBS.includes(verb)) {
         err.write(`deadset-ts: ${verb} is not implemented\n`);
         return EXIT_USAGE;
@@ -276,6 +280,34 @@ function printRootsVerb(args, out, err, host, openClient) {
         return refuse(error, err);
     }
 }
+/**
+ * Writes every declaration an exemption held back in the production sweep a report is
+ * built from, one per line, and nothing where no exemption held one back. One fact
+ * several configurations found is one record, so the line names no configuration. The
+ * line shape is this command's own rather than a Contract format, so that sort and cut
+ * read it.
+ */
+function printRetainedVerb(args, out, err, host, openClient) {
+    let engine;
+    try {
+        const options = readOptions(args);
+        const { config } = resolve(inputsOf(host, options));
+        const scope = scopeOf(host, options);
+        engine = openClient(false);
+        const swept = runSweep(engine, host, scope, config, {
+            marked: [],
+            mode: { production: true },
+        });
+        for (const line of retainedLines(swept.matrix.union.symbols, swept.retained)) {
+            out.write(`${line}\n`);
+        }
+        return EXIT_CLEAN;
+    }
+    catch (error) {
+        engine?.close();
+        return refuse(error, err);
+    }
+}
 /** Turns one refusal into the exit code the Contract's table gives it. */
 function refuse(error, err) {
     if (error instanceof ConfigError) {

package/dist/src/sweep.js

@@ -11,19 +11,16 @@ import { namesACaller, OUTSIDE } from "./graph.js";
  *
  * The order is the order the answers depend on: the callers and the marks are live
  * before either relation runs, the candidate set is every judged declaration at least
- * one relation does not hold live, and the tests of dead code join it.
+ * one relation does not hold live and no exemption holds back, and the tests of dead
+ * code join it.
  */
 export function sweep(graph, input) {
-    const marked = graph.symbols.map(() => false);
-    for (const id of input.marked) {
-        const at = graph.at(id);
-        if (at !== OUTSIDE) {
-            marked[at] = true;
-        }
-    }
-    // Every root and every mark seeds reachability. A root of a kind that names a caller,
-    // and a mark, are live under reference counting as well; a root that only supposes a
-    // caller is not.
+    const marked = flagged(graph, input.marked);
+    const exempt = flagged(graph, (input.exempt ?? []).map((record) => record.id));
+    const held = marked.map((mark, at) => mark || exempt[at] === true);
+    // Every root, every mark and every exemption seeds reachability. A root of a kind that
+    // names a caller, and a mark, are live under reference counting as well; a root that
+    // only supposes a caller is not, and neither is an exemption.
     const called = graph.symbols.map(() => false);
     for (const root of graph.rooted) {
         if (namesACaller(root.kind)) {
@@ -37,7 +34,7 @@ export function sweep(graph, input) {
         }
         return input.mode.production ? made.production : made.production + made.test;
     };
-    const reached = reachable(graph, marked, input.mode);
+    const reached = reachable(graph, held, input.mode);
     const liveUnder = graph.symbols.map((_symbol, at) => {
         const relations = [];
         if (marked[at] === true || called[at] === true || counted(at) > 0) {
@@ -48,8 +45,8 @@ export function sweep(graph, input) {
         }
         return relations;
     });
-    const dead = graph.symbols.map((_symbol, at) => graph.subject[at] === true && (liveUnder[at]?.length ?? 0) < 2);
-    const testOfDeadCode = admitTestsOfDeadCode(graph, dead, marked);
+    const dead = graph.symbols.map((_symbol, at) => graph.subject[at] === true && exempt[at] !== true && (liveUnder[at]?.length ?? 0) < 2);
+    const testOfDeadCode = admitTestsOfDeadCode(graph, dead, held);
     const candidates = [];
     const live = new Map();
     graph.symbols.forEach((symbol, at) => {
@@ -70,13 +67,25 @@ export function sweep(graph, input) {
     });
     return { liveUnder: live, candidates };
 }
+/** Per declaration of the graph, whether one of the identifiers names it. */
+function flagged(graph, ids) {
+    const flags = graph.symbols.map(() => false);
+    for (const id of ids) {
+        const at = graph.at(id);
+        if (at !== OUTSIDE) {
+            flags[at] = true;
+        }
+    }
+    return flags;
+}
 /**
  * Per declaration, whether a seed reaches it. The two seeds reach through different
- * reference sets: a marked declaration is live by a mechanism the analysis cannot see, so
- * no mode withholds a reference it makes, while a root reaches through the references the
- * mode counts. The marks run first, so what they reach is expanded under the wider rule.
+ * reference sets: a held declaration, marked or exempt, is live by a mechanism the
+ * analysis cannot see, so no mode withholds a reference it makes, a test declaration's
+ * included, while a root reaches through the references the mode counts. The held seed
+ * runs first, so what it reaches is expanded under the wider rule.
  */
-function reachable(graph, marked, mode) {
+function reachable(graph, held, mode) {
     const reached = graph.symbols.map(() => false);
     const expanded = graph.symbols.map(() => false);
     const queue = [];
@@ -98,18 +107,18 @@ function reachable(graph, marked, mode) {
             enter(exported, false);
         }
     };
-    const walk = (held) => {
+    const walk = (holding) => {
         for (let at = queue.pop(); at !== undefined; at = queue.pop()) {
             for (const edge of graph.out[at] ?? []) {
-                if (!held && mode.production && edge.test) {
+                if (!holding && mode.production && edge.test) {
                     continue;
                 }
                 enter(edge.to, !edge.evaluation);
             }
         }
     };
-    marked.forEach((mark, at) => {
-        if (mark) {
+    held.forEach((hold, at) => {
+        if (hold) {
             enter(at, false);
         }
     });
@@ -124,12 +133,13 @@ function reachable(graph, marked, mode) {
  * Admits every test declaration whose set of referenced production declarations is
  * non-empty and wholly dead, and returns which it admitted. The set is read from every
  * reference the test makes, not the ones the mode counts: a production sweep counts none,
- * which is what makes the targets dead. A test referencing one live target is never admitted.
+ * which is what makes the targets dead. A test referencing one live target is never
+ * admitted, and neither is a marked or exempt test.
  */
-function admitTestsOfDeadCode(graph, dead, marked) {
+function admitTestsOfDeadCode(graph, dead, held) {
     const admitted = graph.symbols.map(() => false);
     graph.symbols.forEach((_symbol, at) => {
-        if (graph.test[at] !== true || graph.subject[at] !== true || marked[at] === true) {
+        if (graph.test[at] !== true || graph.subject[at] !== true || held[at] === true) {
             return;
         }
         let targets = 0;

package/dist/src/version.js

@@ -4,4 +4,4 @@
  * independently of the analyzer's own version, which is the one the host answers
  * from the package the analyzer was installed from.
  */
-export const CONTRACT_VERSION = "2.2.0";
+export const CONTRACT_VERSION = "3.0.0";

package/jsr.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "type": "module",
   "sideEffects": false,
   "description": "Deterministic dead-code analysis for TypeScript, class and type members included",
@@ -32,13 +32,13 @@
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
-    "@types/node": "24.13.5",
+    "@types/node": "24.19.0",
     "eslint": "10.11.0",
-    "fast-check": "4.10.1",
-    "prettier": "3.9.8",
+    "fast-check": "4.10.2",
+    "prettier": "3.9.9",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.70.0",
-    "vitest": "5.0.1"
+    "typescript-eslint": "8.70.1",
+    "vitest": "5.0.2"
   },
   "publishConfig": {
     "access": "public"

package/src/analysis.ts

@@ -11,6 +11,13 @@
 import type { Diagnostic } from "@typescript/native/unstable/sync";
 import type { Config, Provenance } from "./config.ts";
 import { diagnosticErrors, discoverProjects, DiscoveryError } from "./discover.ts";
+import {
+  computeExemptions,
+  disabledClasses,
+  exemptionsOf,
+  retainedIn,
+  type Detectors,
+} from "./exempt.ts";
 import type { Finding } from "./finding.ts";
 import type { Host } from "./host.ts";
 import { inventory, type Inventory } from "./inventory.ts";
@@ -22,7 +29,7 @@ import { references } from "./references.ts";
 import { roots, unmatchedEverywhere, unmatchedRoots, type RootKind, type Roots } from "./roots.ts";
 import type { Scope } from "./scope.ts";
 import { diagnosticsOf, runSession, type Engine, type ProjectView } from "./session.ts";
-import type { SweepInput } from "./sweep.ts";
+import type { Exemption, SweepInput } from "./sweep.ts";
 
 /** The setting whose source decides where a finding about a configured root sits. */
 const ROOTS_SETTING = "roots.patterns";
@@ -196,35 +203,55 @@ export function runRoots(
 export interface RunSweep {
   readonly matrix: Matrix;
   readonly sweep: SweepResult;
+  /**
+   * The exemption records that held back a declaration some configuration of the run
+   * would otherwise judge dead, in the declarations' site order.
+   */
+  readonly retained: readonly Exemption[];
 }
 
+/** The exemption classes this analyzer detects, each by its detector; any other retains nothing. */
+const DETECTORS: Detectors = new Map();
+
 /**
  * Sweeps the run the scope and the configuration describe. Each project's references
- * are read against its own inventory with the configured test-file patterns while its
- * view is open; the projects then merge into one matrix in discovery order, which is
- * swept under the input the caller decided once for the run. A project that carries
- * an error ends the run before any project is swept.
+ * and exemptions are read against its own inventory while its view is open; the
+ * projects then merge into one matrix in the run's order, which is swept under the
+ * caller's marks and mode with the exemptions every project found. A record found in
+ * one configuration holds in every configuration that holds its declaration, because
+ * an exemption is evidence of a use the analysis cannot see and a use in one
+ * configuration is a use. A project that carries an error ends the run before any
+ * project is swept.
  */
 export function runSweep(
   engine: Engine,
   host: Host,
   scope: Scope,
   config: Config,
-  input: SweepInput,
+  input: Pick<SweepInput, "marked" | "mode">,
+  detectors: Detectors = DETECTORS,
 ): RunSweep {
   const targetRoot = scope.target.path;
-  const configured = readProjects(engine, host, scope, config, (project, read): Configured => {
-    const resolved = references(project, read.held, targetRoot, {
+  const disabled = disabledClasses(config);
+  const read = readProjects(engine, host, scope, config, (project, projectRead) => {
+    const resolved = references(project, projectRead.held, targetRoot, {
       testFiles: config.ts.testFiles,
     });
-    return {
-      configuration: read.configuration,
-      symbols: read.held.symbols,
+    const configured: Configured = {
+      configuration: projectRead.configuration,
+      symbols: projectRead.held.symbols,
       references: resolved.references,
-      roots: read.rooted.liveUnderReachability,
+      roots: projectRead.rooted.liveUnderReachability,
       testFiles: resolved.testFilePaths,
     };
+    const exempt = computeExemptions({ project, held: projectRead.held, targetRoot }, detectors, {
+      disabled,
+      mode: input.mode,
+      testFiles: new Set(resolved.testFilePaths),
+    });
+    return { configured, exempt };
   });
-  const matrix = matrixOf(configured);
-  return { matrix, sweep: sweepMatrix(matrix, input) };
+  const matrix = matrixOf(read.map((one) => one.configured));
+  const swept: SweepInput = { ...input, exempt: exemptionsOf(read.flatMap((one) => one.exempt)) };
+  return { matrix, sweep: sweepMatrix(matrix, swept), retained: retainedIn(matrix, swept) };
 }

package/src/exempt-classes.ts

@@ -0,0 +1,69 @@
+/**
+ * The exemption classes of the Contract's vocabulary, in its order: each class's name,
+ * the languages it runs on and the confidence it is recorded at.
+ *
+ * The rows are written out rather than read from the Contract at run time, for the
+ * reason the fixed severity codes are, and a test holds them equal to the Contract
+ * release this analyzer implements. A class name is a type, so a detector table or a
+ * record naming a class the vocabulary does not hold, or one that runs on another
+ * language only, does not compile.
+ */
+
+import type { Confidence, Language } from "./config.ts";
+
+/** One class of the vocabulary. */
+interface ExemptionClassRow {
+  readonly class: string;
+  readonly languages: readonly Language[];
+  readonly confidence: Confidence;
+}
+
+/** Every class of the vocabulary, in the order the Contract lists them. */
+export const EXEMPTION_CLASSES = [
+  { class: "interface-satisfaction", languages: ["go", "ts"], confidence: "certain" },
+  { class: "encoding-reflection", languages: ["go"], confidence: "certain" },
+  { class: "format-verb-contract", languages: ["go"], confidence: "certain" },
+  { class: "errors-duck-typing", languages: ["go"], confidence: "certain" },
+  { class: "enum-group", languages: ["go", "ts"], confidence: "certain" },
+  { class: "generated-file", languages: ["go"], confidence: "certain" },
+  { class: "linkname-cgo-asm-plugin", languages: ["go"], confidence: "certain" },
+  { class: "template-field", languages: ["go", "ts"], confidence: "possible" },
+  { class: "reflective-lookup", languages: ["go", "ts"], confidence: "possible" },
+  { class: "decorator", languages: ["ts"], confidence: "certain" },
+  { class: "injection-container", languages: ["ts"], confidence: "certain" },
+  { class: "framework-lifecycle", languages: ["ts"], confidence: "certain" },
+  { class: "serialization-contract", languages: ["ts"], confidence: "certain" },
+] as const satisfies readonly ExemptionClassRow[];
+
+type Row = (typeof EXEMPTION_CLASSES)[number];
+
+/** The name of a class of the vocabulary. */
+export type ExemptionClass = Row["class"];
+
+/** The classes of the rows that list one language. */
+type ClassesOf<R, L extends Language> = R extends {
+  readonly class: infer C;
+  readonly languages: readonly (infer Listed)[];
+}
+  ? L extends Listed
+    ? C
+    : never
+  : never;
+
+/** The name of a class that runs on TypeScript, the only classes this analyzer records. */
+export type TSExemptionClass = ClassesOf<Row, "ts">;
+
+function runsOnTS(row: Row): row is Extract<Row, { readonly class: TSExemptionClass }> {
+  const languages: readonly Language[] = row.languages;
+  return languages.includes("ts");
+}
+
+/** The classes that run on TypeScript, in the vocabulary's order. */
+export const TS_EXEMPTION_CLASSES: readonly TSExemptionClass[] = EXEMPTION_CLASSES.filter(
+  runsOnTS,
+).map((row) => row.class);
+
+/** Whether one name is a class of the vocabulary, whichever language it runs on. */
+export function isExemptionClass(name: string): name is ExemptionClass {
+  return EXEMPTION_CLASSES.some((row) => row.class === name);
+}

package/src/exempt.ts

@@ -0,0 +1,200 @@
+/**
+ * The exemption framework: the classes of reason for which a declaration the reference
+ * graph alone would report is live all the same. A class is policy over what one
+ * project's checker answers, and its detector names the declarations it holds back;
+ * this module runs the detectors, decides which of their records stand, and answers
+ * which records held something back. It names no class's detector: the composition
+ * hands it the table of the classes it has.
+ */
+
+import type { Config } from "./config.ts";
+import { ConfigError } from "./config.ts";
+import {
+  EXEMPTION_CLASSES,
+  isExemptionClass,
+  TS_EXEMPTION_CLASSES,
+  type ExemptionClass,
+  type TSExemptionClass,
+} from "./exempt-classes.ts";
+import type { Inventory, InventorySymbol } from "./inventory.ts";
+import type { Matrix } from "./matrix.ts";
+import { byPosition, positionKey, type Position } from "./position.ts";
+import type { ProjectView } from "./session.ts";
+import { sweep, type Exemption, type Mode, type SweepInput } from "./sweep.ts";
+
+/** One declaration a detector holds back, and where and why. */
+export interface Evidence {
+  /** The identifier of the declaration held back. */
+  readonly id: string;
+  /** One clause naming the relation, then the thing it relates to. */
+  readonly detail: string;
+  readonly site: Position;
+}
+
+/** What a detector reads of one project, while the project's view is open. */
+export interface DetectorInput<Brand> {
+  readonly project: ProjectView<Brand>;
+  readonly held: Inventory;
+  readonly targetRoot: string;
+}
+
+/**
+ * One class's detection over one project. The framework records each piece of evidence
+ * under the class the table names the detector by, so a detector names no class.
+ */
+export type Detector = <Brand>(input: DetectorInput<Brand>) => readonly Evidence[];
+
+/** The detector of each class one composition implements. */
+export type Detectors = ReadonlyMap<TSExemptionClass, Detector>;
+
+/** What decides which records of one project stand. */
+export interface Holding {
+  /** The classes the configuration switches off, whose detectors do not run. */
+  readonly disabled: ReadonlySet<ExemptionClass>;
+  readonly mode: Mode;
+  /** The paths the reference pass classified as test files. */
+  readonly testFiles: ReadonlySet<string>;
+}
+
+/**
+ * The classes `exemptions.disabled` switches off. A name is refused unless the
+ * vocabulary holds it; a class that runs on another language only is admitted and
+ * switches nothing off here, so one configuration serves every analyzer.
+ */
+export function disabledClasses(config: Config): ReadonlySet<ExemptionClass> {
+  const disabled = new Set<ExemptionClass>();
+  for (const name of config.exemptionsDisabled) {
+    if (!isExemptionClass(name)) {
+      const known = EXEMPTION_CLASSES.map((row) => row.class).join(", ");
+      throw new ConfigError(
+        "malformed",
+        "exemptions.disabled",
+        `exemptions.disabled: ${JSON.stringify(name)} is not an exemption class: the classes are ${known}`,
+      );
+    }
+    disabled.add(name);
+  }
+  return disabled;
+}
+
+/**
+ * The records one project's detectors found, each class in the vocabulary's order and
+ * none of a switched-off class. Under a production mode a record whose evidence is
+ * written in a test file holds nothing, as a reference a test file makes is none there.
+ */
+export function computeExemptions<Brand>(
+  input: DetectorInput<Brand>,
+  detectors: Detectors,
+  holding: Holding,
+): readonly Exemption[] {
+  const found: Exemption[] = [];
+  for (const exemptionClass of TS_EXEMPTION_CLASSES) {
+    const detect = detectors.get(exemptionClass);
+    if (detect === undefined || holding.disabled.has(exemptionClass)) {
+      continue;
+    }
+    for (const evidence of detect(input)) {
+      if (holding.mode.production && holding.testFiles.has(evidence.site.path)) {
+        continue;
+      }
+      found.push({
+        id: evidence.id,
+        class: exemptionClass,
+        detail: evidence.detail,
+        site: evidence.site,
+      });
+    }
+  }
+  return exemptionsOf(found);
+}
+
+/** Two strings ordered bytewise. */
+function compare(a: string, b: string): number {
+  if (a === b) {
+    return 0;
+  }
+  return a < b ? -1 : 1;
+}
+
+/**
+ * Records as a run holds them: ordered by site, then class, then declaration, and one
+ * per declaration, class and detail, the one at the first site. A fact found at many
+ * sites, or by several projects, is one record.
+ */
+export function exemptionsOf(found: readonly Exemption[]): readonly Exemption[] {
+  const ordered = [...found].sort(
+    (a, b) => byPosition(a.site, b.site) || compare(a.class, b.class) || compare(a.id, b.id),
+  );
+  const seen = new Set<string>();
+  return ordered.filter((record) => {
+    const fact = [record.id, record.class, record.detail].join("\u0000");
+    if (seen.has(fact)) {
+      return false;
+    }
+    seen.add(fact);
+    return true;
+  });
+}
+
+/** The records per declaration, each declaration's in the order given. */
+function byDeclaration(records: readonly Exemption[]): ReadonlyMap<string, readonly Exemption[]> {
+  const grouped = new Map<string, Exemption[]>();
+  for (const record of records) {
+    const held = grouped.get(record.id);
+    if (held === undefined) {
+      grouped.set(record.id, [record]);
+    } else {
+      held.push(record);
+    }
+  }
+  return grouped;
+}
+
+/**
+ * The records that held back a declaration some configuration of the run would
+ * otherwise judge dead: each configuration's graph is swept once more with no
+ * exemption and the marks it was given, and a record is retained when one of those
+ * sweeps judged its declaration a candidate. A record that holds a declaration back in
+ * one configuration is retained whatever another configuration answers about it, as a
+ * run of that configuration alone would report the declaration without it. A record
+ * on a declaration that a relation or a mark holds live in every configuration held
+ * nothing back. The order is the declarations' site order, and for one declaration
+ * the input's.
+ */
+export function retainedIn(matrix: Matrix, input: SweepInput): readonly Exemption[] {
+  const exempt = input.exempt ?? [];
+  if (exempt.length === 0) {
+    return [];
+  }
+  const bare: SweepInput = { marked: input.marked, mode: input.mode };
+  const dead = new Set(
+    matrix.graphs.flatMap((graph) =>
+      sweep(graph, bare).candidates.map((candidate) => candidate.id),
+    ),
+  );
+  const held = byDeclaration(exempt.filter((record) => dead.has(record.id)));
+  return matrix.union.symbols.flatMap((symbol) => held.get(symbol.id) ?? []);
+}
+
+/**
+ * One line per held-back declaration, in site order: its reference, then each record's
+ * class, site and detail, all separated by tabs.
+ */
+export function retainedLines(
+  symbols: readonly InventorySymbol[],
+  retained: readonly Exemption[],
+): readonly string[] {
+  const held = byDeclaration(retained);
+  return symbols.flatMap((symbol) => {
+    const records = held.get(symbol.id);
+    if (records === undefined) {
+      return [];
+    }
+    const fields = records.flatMap((record) => [
+      record.class,
+      positionKey(record.site),
+      record.detail,
+    ]);
+    return [[symbol.ref, ...fields].join("\t")];
+  });
+}

package/src/run.ts

@@ -1,4 +1,4 @@
-import { runRoots, type RunRoot } from "./analysis.ts";
+import { runRoots, runSweep, type RunRoot } from "./analysis.ts";
 import { ConfigError, REPOSITORY_DOCUMENT, type Inputs } from "./config.ts";
 import {
   diagnosticErrors,
@@ -6,6 +6,7 @@ import {
   DiscoveryError,
   renderDiagnostic,
 } from "./discover.ts";
+import { retainedLines } from "./exempt.ts";
 import type { Host } from "./host.ts";
 import { joinPath, resolvePath } from "./paths.ts";
 import { printConfig } from "./print.ts";
@@ -221,6 +222,9 @@ export function run(
   if (verb === "print-roots") {
     return printRootsVerb(args.slice(1), out, err, host, openClient);
   }
+  if (verb === "print-retained") {
+    return printRetainedVerb(args.slice(1), out, err, host, openClient);
+  }
   if (verb !== undefined && (VERBS as readonly string[]).includes(verb)) {
     err.write(`deadset-ts: ${verb} is not implemented\n`);
     return EXIT_USAGE;
@@ -337,6 +341,40 @@ function printRootsVerb(
   }
 }
 
+/**
+ * Writes every declaration an exemption held back in the production sweep a report is
+ * built from, one per line, and nothing where no exemption held one back. One fact
+ * several configurations found is one record, so the line names no configuration. The
+ * line shape is this command's own rather than a Contract format, so that sort and cut
+ * read it.
+ */
+function printRetainedVerb(
+  args: readonly string[],
+  out: Writer,
+  err: Writer,
+  host: Host,
+  openClient: (collectTiming: boolean) => Engine,
+): number {
+  let engine: Engine | undefined;
+  try {
+    const options = readOptions(args);
+    const { config } = resolve(inputsOf(host, options));
+    const scope = scopeOf(host, options);
+    engine = openClient(false);
+    const swept = runSweep(engine, host, scope, config, {
+      marked: [],
+      mode: { production: true },
+    });
+    for (const line of retainedLines(swept.matrix.union.symbols, swept.retained)) {
+      out.write(`${line}\n`);
+    }
+    return EXIT_CLEAN;
+  } catch (error: unknown) {
+    engine?.close();
+    return refuse(error, err);
+  }
+}
+
 /** Turns one refusal into the exit code the Contract's table gives it. */
 function refuse(error: unknown, err: Writer): number {
   if (error instanceof ConfigError) {

package/src/sweep.ts

@@ -6,11 +6,24 @@
  * declaration only unreachable ones reference is live under the first, dead under the second.
  */
 
+import type { TSExemptionClass } from "./exempt-classes.ts";
 import { namesACaller, OUTSIDE, type Graph } from "./graph.ts";
+import type { Position } from "./position.ts";
 
 /** The liveness relation that decided a declaration, as a finding spells it. */
 export type Relation = "reference-counting" | "reachability";
 
+/** One declaration an exemption class holds back, and the evidence it was found by. */
+export interface Exemption {
+  /** The identifier of the declaration held back. */
+  readonly id: string;
+  readonly class: TSExemptionClass;
+  /** One clause naming the relation, then the thing it relates to: `passed to JSON.stringify`. */
+  readonly detail: string;
+  /** Where the evidence is written. */
+  readonly site: Position;
+}
+
 /**
  * The run's reference mode, decided once by the composition and read by every stage
  * that counts references.
@@ -31,6 +44,13 @@ export interface SweepInput {
    * nothing only a marked declaration references is dead.
    */
   readonly marked: readonly string[];
+  /**
+   * The exemptions the run computed. An exempt declaration is never a candidate, and it
+   * seeds reachability as a mark does, so nothing it references is dead; it is live
+   * under reference counting only where something references it. Absent, the sweep
+   * holds nothing back.
+   */
+  readonly exempt?: readonly Exemption[];
   readonly mode: Mode;
 }
 
@@ -69,19 +89,19 @@ export interface Liveness {
  *
  * The order is the order the answers depend on: the callers and the marks are live
  * before either relation runs, the candidate set is every judged declaration at least
- * one relation does not hold live, and the tests of dead code join it.
+ * one relation does not hold live and no exemption holds back, and the tests of dead
+ * code join it.
  */
 export function sweep(graph: Graph, input: SweepInput): Liveness {
-  const marked = graph.symbols.map(() => false);
-  for (const id of input.marked) {
-    const at = graph.at(id);
-    if (at !== OUTSIDE) {
-      marked[at] = true;
-    }
-  }
-  // Every root and every mark seeds reachability. A root of a kind that names a caller,
-  // and a mark, are live under reference counting as well; a root that only supposes a
-  // caller is not.
+  const marked = flagged(graph, input.marked);
+  const exempt = flagged(
+    graph,
+    (input.exempt ?? []).map((record) => record.id),
+  );
+  const held = marked.map((mark, at) => mark || exempt[at] === true);
+  // Every root, every mark and every exemption seeds reachability. A root of a kind that
+  // names a caller, and a mark, are live under reference counting as well; a root that
+  // only supposes a caller is not, and neither is an exemption.
   const called = graph.symbols.map(() => false);
   for (const root of graph.rooted) {
     if (namesACaller(root.kind)) {
@@ -96,7 +116,7 @@ export function sweep(graph: Graph, input: SweepInput): Liveness {
     }
     return input.mode.production ? made.production : made.production + made.test;
   };
-  const reached = reachable(graph, marked, input.mode);
+  const reached = reachable(graph, held, input.mode);
   const liveUnder = graph.symbols.map((_symbol, at): readonly Relation[] => {
     const relations: Relation[] = [];
     if (marked[at] === true || called[at] === true || counted(at) > 0) {
@@ -109,9 +129,10 @@ export function sweep(graph: Graph, input: SweepInput): Liveness {
   });
 
   const dead = graph.symbols.map(
-    (_symbol, at) => graph.subject[at] === true && (liveUnder[at]?.length ?? 0) < 2,
+    (_symbol, at) =>
+      graph.subject[at] === true && exempt[at] !== true && (liveUnder[at]?.length ?? 0) < 2,
   );
-  const testOfDeadCode = admitTestsOfDeadCode(graph, dead, marked);
+  const testOfDeadCode = admitTestsOfDeadCode(graph, dead, held);
 
   const candidates: Candidate[] = [];
   const live = new Map<string, readonly Relation[]>();
@@ -135,13 +156,26 @@ export function sweep(graph: Graph, input: SweepInput): Liveness {
   return { liveUnder: live, candidates };
 }
 
+/** Per declaration of the graph, whether one of the identifiers names it. */
+function flagged(graph: Graph, ids: readonly string[]): boolean[] {
+  const flags = graph.symbols.map(() => false);
+  for (const id of ids) {
+    const at = graph.at(id);
+    if (at !== OUTSIDE) {
+      flags[at] = true;
+    }
+  }
+  return flags;
+}
+
 /**
  * Per declaration, whether a seed reaches it. The two seeds reach through different
- * reference sets: a marked declaration is live by a mechanism the analysis cannot see, so
- * no mode withholds a reference it makes, while a root reaches through the references the
- * mode counts. The marks run first, so what they reach is expanded under the wider rule.
+ * reference sets: a held declaration, marked or exempt, is live by a mechanism the
+ * analysis cannot see, so no mode withholds a reference it makes, a test declaration's
+ * included, while a root reaches through the references the mode counts. The held seed
+ * runs first, so what it reaches is expanded under the wider rule.
  */
-function reachable(graph: Graph, marked: readonly boolean[], mode: Mode): readonly boolean[] {
+function reachable(graph: Graph, held: readonly boolean[], mode: Mode): readonly boolean[] {
   const reached = graph.symbols.map(() => false);
   const expanded = graph.symbols.map(() => false);
   const queue: number[] = [];
@@ -164,10 +198,10 @@ function reachable(graph: Graph, marked: readonly boolean[], mode: Mode): readon
       enter(exported, false);
     }
   };
-  const walk = (held: boolean): void => {
+  const walk = (holding: boolean): void => {
     for (let at = queue.pop(); at !== undefined; at = queue.pop()) {
       for (const edge of graph.out[at] ?? []) {
-        if (!held && mode.production && edge.test) {
+        if (!holding && mode.production && edge.test) {
           continue;
         }
         enter(edge.to, !edge.evaluation);
@@ -175,8 +209,8 @@ function reachable(graph: Graph, marked: readonly boolean[], mode: Mode): readon
     }
   };
 
-  marked.forEach((mark, at) => {
-    if (mark) {
+  held.forEach((hold, at) => {
+    if (hold) {
       enter(at, false);
     }
   });
@@ -192,16 +226,17 @@ function reachable(graph: Graph, marked: readonly boolean[], mode: Mode): readon
  * Admits every test declaration whose set of referenced production declarations is
  * non-empty and wholly dead, and returns which it admitted. The set is read from every
  * reference the test makes, not the ones the mode counts: a production sweep counts none,
- * which is what makes the targets dead. A test referencing one live target is never admitted.
+ * which is what makes the targets dead. A test referencing one live target is never
+ * admitted, and neither is a marked or exempt test.
  */
 function admitTestsOfDeadCode(
   graph: Graph,
   dead: boolean[],
-  marked: readonly boolean[],
+  held: readonly boolean[],
 ): readonly boolean[] {
   const admitted = graph.symbols.map(() => false);
   graph.symbols.forEach((_symbol, at) => {
-    if (graph.test[at] !== true || graph.subject[at] !== true || marked[at] === true) {
+    if (graph.test[at] !== true || graph.subject[at] !== true || held[at] === true) {
       return;
     }
     let targets = 0;

package/src/version.ts

@@ -4,4 +4,4 @@
  * independently of the analyzer's own version, which is the one the host answers
  * from the package the analyzer was installed from.
  */
-export const CONTRACT_VERSION = "2.2.0";
+export const CONTRACT_VERSION = "3.0.0";