@cplieger/deadset-ts 3.9.1 → 3.11.0

package/dist/src/run.js

@@ -10,15 +10,13 @@ import { printRetainedVerb } from "./verbs/print-retained.js";
 import { printRootsVerb } from "./verbs/print-roots.js";
 import { ANALYZE_OPTIONS, analyzeVerb } from "./verbs/analyze.js";
 import { describeVerb } from "./verbs/describe.js";
+import { EXPLAIN_OPTIONS, explainVerb } from "./verbs/explain.js";
 import { EXIT_FAILURE, EXIT_USAGE } from "./verbs/verb.js";
 import { versionVerb } from "./verbs/version.js";
-/**
- * Every verb this command answers, in the order the usage text lists them. A verb
- * with no `run` is listed, and invoking it is a usage error.
- */
+/** Every verb this command answers, in the order the usage text lists them. */
 const VERBS = [
     { name: "analyze", run: analyzeVerb, options: ANALYZE_OPTIONS },
-    { name: "explain" },
+    { name: "explain", run: explainVerb, options: EXPLAIN_OPTIONS },
     { name: "print-config", run: printConfigVerb },
     { name: "print-projects", run: printProjectsVerb },
     { name: "print-roots", run: printRootsVerb },
@@ -169,12 +167,8 @@ export function run(args, out, err, host, openClient = (collectTiming) => openEn
     }
     const name = args[0];
     const verb = VERBS.find((listed) => listed.name === name);
-    if (verb?.run !== undefined) {
-        return invoke(verb.run, verb.options ?? NO_OPTIONS, args.slice(1), { out, err, host }, openClient);
-    }
     if (verb !== undefined) {
-        err.write(`deadset-ts: ${verb.name} is not implemented\n`);
-        return EXIT_USAGE;
+        return invoke(verb.run, verb.options ?? NO_OPTIONS, args.slice(1), { out, err, host }, openClient);
     }
     if (name !== undefined) {
         err.write(`deadset-ts: unknown verb ${JSON.stringify(name)}\n`);

package/dist/src/verbs/analyze.js

@@ -1,19 +1,20 @@
 import { runAnalysis } from "../analysis.js";
 import { ConfigError } from "../config.js";
-import { RECORDED_CONFORMANCE, reportedConformance } from "../conformance.js";
+import { CONFORMANCE, DECLARED_GAPS } from "../conformance.js";
 import { analyzerProvenance, recordedFindings, verdictOf } from "../findings-pass.js";
 import { packageScope } from "../inventory.js";
-import { normalizePath, relativePath, resolvePath } from "../paths.js";
+import { joinPath, normalizePath, relativePath, resolvePath } from "../paths.js";
 import { buildReport, capFindings, sortFindings, } from "../report.js";
 import { json } from "../reporters/json.js";
 import { RENDERINGS } from "../reporters/reporters.js";
+import { parseTemplate, TemplateError } from "../reporters/template.js";
 import { resolve } from "../resolve.js";
 import { writeBaseline } from "../suppress-file.js";
 import { CONTRACT_VERSION } from "../version.js";
 import { EXIT_CLEAN, EXIT_FAILURE } from "./verb.js";
 /** The options `analyze` takes beside the ones every verb takes. */
 export const ANALYZE_OPTIONS = {
-    plain: ["report", "baseline-write", "exit-code"],
+    plain: ["report", "baseline-write", "exit-code", "template"],
     repeatable: ["format"],
 };
 /** The two values `--exit-code` takes; on, the default, puts the run's verdict in the exit code. */
@@ -80,12 +81,42 @@ function identityOf(module, host) {
 function counted(n, noun) {
     return `${String(n)} ${noun}${n === 1 ? "" : "s"}`;
 }
+/**
+ * The template `--template` names, read and parsed before any analysis, so a template that
+ * cannot be read or does not parse refuses the invocation. The template format with no
+ * template named is refused the same way.
+ */
+function templateOf(host, invoked, named, formats) {
+    if (named === undefined || named === "") {
+        if (formats.includes("template")) {
+            throw new ConfigError("malformed", "", "the template format renders the template --template names, and none was named");
+        }
+        return undefined;
+    }
+    let source;
+    try {
+        source = host.readFile(resolvePath(invoked, named));
+    }
+    catch (error) {
+        throw new ConfigError("malformed", "", `--template=${named}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+        return parseTemplate(source);
+    }
+    catch (error) {
+        if (!(error instanceof TemplateError)) {
+            throw error;
+        }
+        throw new ConfigError("malformed", "", `--template=${named}: ${error.message}`);
+    }
+}
 /**
  * Analyzes the scope under the configuration and writes the JSON report to the path
  * `--report` names, each rendering `--format` names beside it at the report's path with the
  * format's suffix appended, and a baseline of every finding where `--baseline-write` names a
- * path. Nothing is written to the output stream; diagnostics go to the error stream and the
- * verdict is the exit code, or 0 under `--exit-code=off`.
+ * path. The template format renders the template `--template` names. Nothing is written to
+ * the output stream; diagnostics go to the error stream and the verdict is the exit code, or 0
+ * under `--exit-code=off`, and a rendering that cannot be written ends the run with 3.
  */
 export const analyzeVerb = ({ err, host, inputs, scope, openClient, option, repeated }) => {
     const reportPath = option("report");
@@ -108,6 +139,7 @@ export const analyzeVerb = ({ err, host, inputs, scope, openClient, option, repe
         formats: formatsOf(repeated("format"), config.reporters.formats),
         baseline: baseline === undefined ? undefined : resolvePath(invoked, baseline),
     };
+    const template = templateOf(host, invoked, option("template"), documents.formats);
     const scoped = scope();
     const targetRoot = scoped.target.path;
     let version;
@@ -129,7 +161,8 @@ export const analyzeVerb = ({ err, host, inputs, scope, openClient, option, repe
         const built = buildReport({
             contractVersion: CONTRACT_VERSION,
             version,
-            conformance: reportedConformance(RECORDED_CONFORMANCE),
+            conformance: CONFORMANCE,
+            declaredGaps: DECLARED_GAPS,
             target: { kind, root, identity: identityOf(scoped.target, host) },
             configurations: configurationsOf(run.projects, targetRoot),
             unavailable: scoped.consumers.map((consumer) => ({
@@ -154,10 +187,15 @@ export const analyzeVerb = ({ err, host, inputs, scope, openClient, option, repe
     }
     try {
         host.writeFile(documents.report, json(report));
+        const options = {
+            failOn: config.reporters.failOn,
+            readSource: (path) => host.readFile(joinPath(targetRoot, path)),
+            template,
+        };
         for (const format of documents.formats) {
             const rendering = RENDERINGS.get(format);
             if (rendering !== undefined) {
-                host.writeFile(documents.report + rendering.suffix, rendering.render(report));
+                host.writeFile(documents.report + rendering.suffix, rendering.render(report, options));
             }
         }
         if (documents.baseline !== undefined) {

package/dist/src/verbs/describe.js

@@ -1,11 +1,11 @@
-import { RECORDED_CONFORMANCE } from "../conformance.js";
+import { CONFORMANCE } from "../conformance.js";
 import { ANALYZER_NAME, LANGUAGE, SCHEMA_VERSION } from "../report.js";
 import { CONTRACT_VERSION } from "../version.js";
 import { EXIT_CLEAN, EXIT_FAILURE, EXIT_USAGE } from "./verb.js";
 /**
  * The document `describe` writes: the analyzer, the Contract version it implements, the
  * report schema versions it reads, the languages it claims, and its recorded result over
- * the conformance corpus, absent where it records none.
+ * the conformance corpus.
  */
 export function describeDocument(version, recorded) {
     const document = {
@@ -14,15 +14,11 @@ export function describeDocument(version, recorded) {
         contract_version: CONTRACT_VERSION,
         schema_versions_accepted: [SCHEMA_VERSION],
         languages: [LANGUAGE],
-        ...(recorded === undefined
-            ? {}
-            : {
-                conformance: {
-                    corpus_version: recorded.corpusVersion,
-                    result: recorded.result,
-                    digest: recorded.digest,
-                },
-            }),
+        conformance: {
+            corpus_version: recorded.corpusVersion,
+            result: recorded.result,
+            digest: recorded.digest,
+        },
     };
     return `${JSON.stringify(document, null, 2)}\n`;
 }
@@ -40,6 +36,6 @@ export const describeVerb = ({ out, err, host, args }) => {
         err.write(`deadset-ts: describe: ${error instanceof Error ? error.message : String(error)}\n`);
         return EXIT_FAILURE;
     }
-    out.write(describeDocument(version, RECORDED_CONFORMANCE));
+    out.write(describeDocument(version, CONFORMANCE));
     return EXIT_CLEAN;
 };

package/dist/src/verbs/explain.js

@@ -0,0 +1,303 @@
+import { runAnalysis } from "../analysis.js";
+import { listing } from "../components.js";
+import { ConfigError } from "../config.js";
+import { OUTSIDE, swept as judged } from "../graph.js";
+import { positionKey } from "../position.js";
+import { resolve } from "../resolve.js";
+import { EXIT_CLEAN, EXIT_USAGE } from "./verb.js";
+/**
+ * The three spellings of an explanation request, each naming the symbol to explain. They are
+ * one request, because exactly one state holds for a symbol and the answer is that state.
+ */
+const WHY_OPTIONS = ["why", "why-live", "why-not"];
+/** The options `explain` takes beside the ones every verb takes. */
+export const EXPLAIN_OPTIONS = { plain: [...WHY_OPTIONS], repeatable: [] };
+/** The most partial matches a refused request prints. */
+const MAX_PARTIAL_MATCHES = 20;
+/** A count with its noun, so a line reads for one as well as for several. */
+function counted(n, noun) {
+    return `${String(n)} ${noun}${n === 1 ? "" : "s"}`;
+}
+/** A list for a line a maintainer reads, which says none rather than leaving the field blank. */
+function listed(items) {
+    return items.length === 0 ? "none" : items.join(" ");
+}
+/** The one symbol a request names, from whichever of the three options names it. */
+function namedSymbol(option) {
+    const named = WHY_OPTIONS.flatMap((name) => {
+        const value = option(name);
+        return value === undefined || value === "" ? [] : [{ name, value }];
+    });
+    const [only, ...more] = named;
+    if (only === undefined) {
+        throw new ConfigError("malformed", "", "explain explains the symbol --why, --why-live or --why-not names, and none was named");
+    }
+    if (more.length > 0) {
+        throw new ConfigError("malformed", "", `explain explains one symbol, and ${named.map((one) => `--${one.name}`).join(", ")} each name one`);
+    }
+    return only.value;
+}
+/** The part of a reference after its separator: the `Type.member` or bare name a maintainer types. */
+function fragmentOf(symbol) {
+    const at = symbol.ref.indexOf("#");
+    return at < 0 ? "" : symbol.ref.slice(at + 1);
+}
+function described(symbol) {
+    return `${symbol.ref}\t${positionKey(symbol.position)}`;
+}
+/**
+ * The one declaration a request names, or the candidates where it names none or several.
+ * The reference, the fragment of it a maintainer types and the display name are tried in
+ * order, each an exact match; a key several declarations answer is no answer.
+ */
+function subjectOf(symbols, named) {
+    const keys = [
+        (symbol) => symbol.ref,
+        fragmentOf,
+        (symbol) => symbol.name,
+    ];
+    for (const key of keys) {
+        const matched = symbols.filter((symbol) => key(symbol) === named);
+        const [only] = matched;
+        if (only !== undefined && matched.length === 1) {
+            return { subject: only, candidates: [] };
+        }
+        if (matched.length > 1) {
+            return { candidates: matched.map(described) };
+        }
+    }
+    const folded = named.toLowerCase();
+    const partial = symbols
+        .filter((symbol) => symbol.ref.toLowerCase().includes(folded) || symbol.name.toLowerCase().includes(folded))
+        .map(described)
+        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    return { candidates: partial.slice(0, MAX_PARTIAL_MATCHES) };
+}
+/** Every reference of the run once, a reference several configurations make counted once. */
+function referencesOf(configured) {
+    const seen = new Set();
+    const held = [];
+    for (const reference of configured.flatMap((one) => one.references)) {
+        const key = [reference.from, reference.to, positionKey(reference.position), reference.use].join("\u0000");
+        if (!seen.has(key)) {
+            seen.add(key);
+            held.push(reference);
+        }
+    }
+    return held;
+}
+/** Every root of the run once per reason, in the order the projects name them. */
+function rootsOf(configured) {
+    const seen = new Set();
+    return configured
+        .flatMap((one) => one.roots)
+        .filter((root) => {
+        const key = [root.id, root.kind, root.source].join("\u0000");
+        if (seen.has(key)) {
+            return false;
+        }
+        seen.add(key);
+        return true;
+    });
+}
+/**
+ * The shortest path from a root to one declaration, walked breadth first from every root at
+ * once in the order the run names them, following the references the sweep follows: a
+ * reference that reads a module reaches what the module exports, and an evaluation or a root
+ * reaches the module alone. Under `production` no reference a test file made is followed,
+ * which is the set the report's sweep counts.
+ */
+function shortestPath(analysis, to, production) {
+    const graph = analysis.swept.matrix.union;
+    const out = new Map();
+    for (const reference of referencesOf(analysis.configured)) {
+        if (production && reference.test) {
+            continue;
+        }
+        const held = out.get(reference.from);
+        if (held === undefined) {
+            out.set(reference.from, [reference]);
+        }
+        else {
+            held.push(reference);
+        }
+    }
+    const steps = [];
+    const seen = new Set();
+    const expanded = new Set();
+    const enter = (step) => {
+        if (!seen.has(step.at)) {
+            seen.add(step.at);
+            steps.push(step);
+        }
+    };
+    for (const root of rootsOf(analysis.configured)) {
+        enter({ at: root.id, hop: undefined, previous: -1, root });
+    }
+    for (let head = 0; head < steps.length; head += 1) {
+        const step = steps[head];
+        if (step === undefined) {
+            break;
+        }
+        if (step.at === to) {
+            const path = [];
+            for (let at = step; at?.hop !== undefined; at = steps[at.previous]) {
+                path.unshift(at.hop);
+            }
+            return { root: step.root, path };
+        }
+        for (const reference of out.get(step.at) ?? []) {
+            enter({
+                at: reference.to,
+                hop: { k: "reference", reference },
+                previous: head,
+                root: step.root,
+            });
+            const target = graph.at(reference.to);
+            if (reference.use === "evaluation" || target === OUTSIDE || expanded.has(reference.to)) {
+                continue;
+            }
+            expanded.add(reference.to);
+            for (const exported of graph.exportsOf[target] ?? []) {
+                const id = graph.symbols[exported]?.id;
+                if (id !== undefined) {
+                    enter({
+                        at: id,
+                        hop: { k: "export", reference, to: id },
+                        previous: head,
+                        root: step.root,
+                    });
+                }
+            }
+        }
+    }
+    return undefined;
+}
+function referenceLine(reference, tail) {
+    return `  reference: ${positionKey(reference.position)}\t${reference.use}\t${tail}${reference.test ? "\tfrom a test file" : ""}\n`;
+}
+/** Why a declaration no finding names and no exemption held back is live, or how it fell. */
+function liveness(analysis, subject, cascade) {
+    const { sweep } = analysis.swept;
+    const candidate = sweep.candidates.find((one) => one.id === subject.id);
+    if (candidate === undefined && !judged(subject.kind)) {
+        return `answer: unjudged\n  unjudged: neither liveness relation judges a ${subject.kind}\n`;
+    }
+    let text = `answer: ${candidate === undefined ? "live" : "dead"}\n`;
+    text += `  live under: ${listed(sweep.liveUnder.get(subject.id) ?? [])}\n`;
+    for (const root of rootsOf(analysis.configured).filter((one) => one.id === subject.id)) {
+        text += `  root: ${root.kind}${root.source === "" ? "" : `\tnamed by ${root.source}`}\n`;
+    }
+    const found = shortestPath(analysis, subject.id, true) ?? shortestPath(analysis, subject.id, false);
+    if (found !== undefined && found.path.length > 0) {
+        text += `  reached from: root ${found.root.kind} ${found.root.id}\n`;
+        for (const hop of found.path) {
+            text += referenceLine(hop.reference, `${hop.reference.from} -> ${hop.reference.to}`);
+            if (hop.k === "export") {
+                text += `  export: ${hop.reference.to} -> ${hop.to}\n`;
+            }
+        }
+    }
+    else if (found === undefined) {
+        const references = referencesOf(analysis.configured).filter((one) => one.to === subject.id);
+        text += "  unreachable: no path of references reaches it from a root\n";
+        text += `  references: ${String(references.length)}\n`;
+        for (const reference of references) {
+            text += referenceLine(reference, `from ${reference.from}`);
+        }
+    }
+    if (candidate !== undefined) {
+        const component = sweep.components.find((one) => one.members.includes(subject.id));
+        if (component !== undefined) {
+            const listed = listing(component, cascade);
+            text += `  component: ${component.id}, ${counted(listed.symbolCount, "symbol")} and ${counted(listed.deletableLines, "deletable line")} fall with it, listed at cascade ${cascade}\n`;
+            for (const root of listed.roots) {
+                text += `  component root: ${root}\n`;
+            }
+            for (const member of listed.members) {
+                text += `  component member: ${member}\n`;
+            }
+        }
+        text += `  candidate: dead under ${candidate.relation}, with ${String(candidate.productionRefs)} production and ${String(candidate.testRefs)} test references\n`;
+    }
+    return text;
+}
+function reported(found) {
+    return [
+        `answer: reported`,
+        `  code: ${found.code} ${found.kind}`,
+        `  message: ${found.message}`,
+        `  class: ${found.reachabilityClass}`,
+        `  confidence: ${found.confidence}`,
+        ...(found.livenessRelation === undefined
+            ? []
+            : [`  liveness relation: ${found.livenessRelation}`]),
+        `  configurations: ${listed(found.configurations)}`,
+        `  loaded consumers: ${listed(found.consumersLoaded)}`,
+        ...found.retainedBy.map((one) => `  retained by: ${one}`),
+        "",
+    ].join("\n");
+}
+/**
+ * Every finding of the run that names the declaration by its reference and reports at
+ * another position: a part of it, or a suppression record naming it. Each is published under
+ * the reference asked about, so an explanation leaving it out would disagree with the report.
+ */
+function namedElsewhere(findings, subject) {
+    return findings
+        .filter((found) => found.symbol.ref === subject.ref && positionKey(found.position) !== subject.id)
+        .map((found) => `also reported: ${found.code} ${found.kind}\t${positionKey(found.position)}\t${found.symbol.kind} ${found.symbol.name}\n`)
+        .join("");
+}
+/** The one explanation that applies to a declaration, built whole before it is written. */
+function explanation(analysis, subject, cascade) {
+    const graph = analysis.swept.matrix.union;
+    const at = graph.at(subject.id);
+    let text = `symbol: ${subject.ref}\n`;
+    text += `declaration: ${subject.kind} ${subject.name}\n`;
+    text += `position: ${subject.id}\n`;
+    text += `configurations: ${listed(analysis.swept.matrix.heldIn[at] ?? [])}\n`;
+    const found = analysis.result.findings.find((one) => positionKey(one.position) === subject.id);
+    const retained = analysis.swept.retained.filter((one) => one.id === subject.id);
+    if (found !== undefined) {
+        text += reported(found);
+    }
+    else if (retained.length > 0) {
+        text += `answer: retained\n  held back by: ${counted(retained.length, "exemption class")}\n`;
+        for (const one of retained) {
+            text += `  class: ${one.class}\t${positionKey(one.site)}\t${one.detail}\n`;
+        }
+    }
+    else {
+        text += liveness(analysis, subject, cascade);
+    }
+    return text + namedElsewhere(analysis.result.findings, subject);
+}
+/**
+ * Explains one symbol from the analysis the report is built from, so an explanation cannot
+ * disagree with a finding: why a reported symbol is reported, which exemption classes held a
+ * retained one back, and for any other declaration the relations that hold it live and the
+ * shortest path of references from a root, or the references it has where no path reaches it.
+ * A request naming no one declaration exits with the usage code and names what partially
+ * matches it.
+ */
+export const explainVerb = ({ out, err, host, inputs, scope, openClient, option }) => {
+    const named = namedSymbol(option);
+    const { config, provenance } = resolve(inputs());
+    const analysis = runAnalysis(openClient(false), host, scope(), config, provenance, {
+        production: true,
+    });
+    const { subject, candidates } = subjectOf(analysis.swept.matrix.union.symbols, named);
+    if (subject === undefined) {
+        err.write(`deadset-ts: ${JSON.stringify(named)} names no one symbol of the target\n`);
+        for (const candidate of candidates) {
+            err.write(`  ${candidate}\n`);
+        }
+        if (candidates.length === 0) {
+            err.write("  no symbol of the target partially matches it either\n");
+        }
+        return EXIT_USAGE;
+    }
+    out.write(explanation(analysis, subject, config.reporters.cascade));
+    return EXIT_CLEAN;
+};

package/jsr.json

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

package/package.json

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

package/src/analysis.ts

@@ -483,7 +483,11 @@ function runAnalysisInputs(
   provenance: Provenance,
   mode: Mode,
   detectors: Detectors,
-): { readonly inputs: AnalysisInputs; readonly run: RunFacts } {
+): {
+  readonly inputs: AnalysisInputs;
+  readonly run: RunFacts;
+  readonly configured: readonly Configured[];
+} {
   const targetRoot = scope.target.path;
   const read = readEmitterRun(engine, host, scope, config, mode, detectors);
   const symbols = read.matrix.union.symbols;
@@ -523,6 +527,7 @@ function runAnalysisInputs(
         read.projects.flatMap((one) => one.configured.testFiles),
       ),
     },
+    configured: read.projects.map((one) => one.configured),
   };
 }
 
@@ -545,12 +550,17 @@ export interface RunFacts {
 export interface RunAnalysis {
   readonly result: PassResult;
   readonly run: RunFacts;
+  /** The sweep the findings were decided over, under the mark of every bound record. */
+  readonly swept: RunSweep;
+  /** What each project answered, in the run's order, which the sweep was built from. */
+  readonly configured: readonly 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: Engine,
@@ -561,7 +571,7 @@ export function runAnalysis(
   mode: Mode,
   detectors: Detectors = DETECTORS,
 ): RunAnalysis {
-  const { inputs, run } = runAnalysisInputs(
+  const { inputs, run, configured } = runAnalysisInputs(
     engine,
     host,
     scope,
@@ -570,5 +580,5 @@ export function runAnalysis(
     mode,
     detectors,
   );
-  return { result: findingsPass(inputs), run };
+  return { result: findingsPass(inputs), run, swept: inputs.marked.swept, configured };
 }

package/src/config.ts

@@ -28,6 +28,14 @@ export type Language = "go" | "ts";
 /** What a finding of one issue kind does to a run. */
 export type Severity = "allow" | "warn" | "deny";
 
+/** The severities ranked, the strongest highest. */
+const SEVERITY_RANK: Readonly<Record<Severity, number>> = { allow: 0, warn: 1, deny: 2 };
+
+/** Whether a finding at one severity fails a run under the failing severity. */
+export function fails(severity: Severity, failOn: Severity): boolean {
+  return SEVERITY_RANK[severity] >= SEVERITY_RANK[failOn];
+}
+
 /** One rendering of the finding list. */
 export type Format = "text" | "json" | "github" | "sarif" | "template";
 

package/src/conformance-record.ts

@@ -0,0 +1,29 @@
+// Written by the conformance run from conformance.json and conformance-results.json.
+// Regenerate it with `UPDATE_GOLDEN=1 npx vitest --run src/conformance.corpus.test.ts`.
+export const RECORD = {
+  conformance: {
+    corpusVersion: "1.9.0",
+    result: "fail",
+    digest: "sha256:8c29f19fc189f4f5d9ea210d556b62d12c3701c221eb7a8adde499b7060bec0d",
+  },
+  gaps: [
+    {
+      fixture: "private-member-unread",
+      capability: "reflective-lookup",
+      reason:
+        "The reference pass resolves a string-literal element access to the member it names, so the member is live by that reference and the retained listing names no class for it.",
+    },
+    {
+      fixture: "redundant-export-keyword",
+      capability: "DS1104",
+      reason:
+        "No consumer is loaded beside the target, so the published surface is unknown and no export is narrowed; review an export only the target uses by hand.",
+    },
+    {
+      fixture: "unused-exported-consumer",
+      capability: "DS1001",
+      reason:
+        "No consumer is loaded beside the target, so an export nothing in the target references is reported at the possible class rather than the certain one.",
+    },
+  ],
+} as const;

package/src/conformance.ts

@@ -1,34 +1,32 @@
 /**
- * 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.
+ * What this analyzer states about its own conformance: its recorded result over the
+ * conformance corpus and every capability it declines, which `describe` and every report
+ * name.
  */
+import { RECORD } from "./conformance-record.ts";
 
-/** The result one product reached over the conformance corpus. */
+/**
+ * The result one product reached over the conformance corpus. A declared gap never lowers
+ * it: the result is `pass` when no fixture fails, gaps or not, and `fail` otherwise.
+ */
 export interface Conformance {
   readonly corpusVersion: string;
   readonly result: "pass" | "fail";
-  /** `sha256:` and the lowercase hexadecimal SHA-256 of the results document the runner wrote. */
+  /** `sha256:` and the lowercase hexadecimal SHA-256 of the results document the run wrote. */
   readonly digest: string;
 }
 
-/** The version of the conformance corpus this analyzer is written against. */
-const CORPUS_VERSION = "1.9.0";
+/** One capability this analyzer declines, as `conformance.json` declares it. */
+export interface DeclaredGap {
+  readonly fixture: string;
+  /** The one expectation the gap covers, where it is narrower than the fixture. */
+  readonly symbol?: string;
+  readonly capability: string;
+  readonly reason: string;
+}
 
-/** 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. */
+export const CONFORMANCE: Conformance = RECORD.conformance;
 
-/**
- * The conformance run this analyzer records, or undefined where it records none. A
- * description states exactly this, so a reader that requires a pass refuses an analyzer
- * that has not answered the corpus.
- */
-export const RECORDED_CONFORMANCE: Conformance | undefined = undefined;
-
-/**
- * The conformance a report states. A report requires the block, so an analyzer that
- * records no run states a failed one over the results document no run wrote, which a merge
- * refuses as it refuses any result other than a pass.
- */
-export function reportedConformance(recorded: Conformance | undefined): Conformance {
-  return recorded ?? { corpusVersion: CORPUS_VERSION, result: "fail", digest: EMPTY_DIGEST };
-}
+/** Every capability this analyzer declines, in the order `conformance.json` declares them. */
+export const DECLARED_GAPS: readonly DeclaredGap[] = RECORD.gaps;