@cplieger/deadset-ts 3.9.1 → 3.10.0

package/dist/src/conformance-record.js

@@ -0,0 +1,26 @@
+// 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.",
+        },
+    ],
+};

package/dist/src/conformance.js

@@ -1,22 +1,10 @@
 /**
- * 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.
  */
-/** 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 };
-}
+import { RECORD } from "./conformance-record.js";
+/** The conformance run this analyzer records. */
+export const CONFORMANCE = RECORD.conformance;
+/** Every capability this analyzer declines, in the order `conformance.json` declares them. */
+export const DECLARED_GAPS = RECORD.gaps;

package/dist/src/report.js

@@ -133,6 +133,15 @@ function canonicalStale(a, b) {
         compare(a.code, b.code) ||
         compare(a.symbol, b.symbol));
 }
+/** One declared gap as a report carries it, its members in the schema's order. */
+function wireGap(gap) {
+    return {
+        fixture: gap.fixture,
+        ...(gap.symbol === undefined ? {} : { symbol: gap.symbol }),
+        capability: gap.capability,
+        reason: gap.reason,
+    };
+}
 /** Edge evaluations by edge, then side, then their compact encodings. */
 function byEdge(a, b) {
     return (compare(a.edge, b.edge) ||
@@ -202,7 +211,11 @@ export function buildReport(input) {
         findings,
         edge_evaluations: input.result.edgeEvaluations.map(wireEvaluation).sort(byEdge),
         stale_suppressions: input.result.staleSuppressions.map(wireStale).sort(canonicalStale),
-        declared_gaps: [],
+        // Every gap shares the one component of the canonical key a gap supplies, the analyzer's
+        // name, so the compact encodings alone order them.
+        declared_gaps: input.declaredGaps
+            .map(wireGap)
+            .sort((a, b) => compare(JSON.stringify(a), JSON.stringify(b))),
         excluded_by_cgo: [],
         test_file_rules: [...input.testFileRules]
             .sort((a, b) => compare(a.rule, b.rule) || a.matched - b.matched)

package/dist/src/verbs/analyze.js

@@ -1,6 +1,6 @@
 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";
@@ -129,7 +129,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) => ({

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/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/deadset-ts",
-  "version": "3.9.1",
+  "version": "3.10.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.10.0",
   "type": "module",
   "sideEffects": false,
   "description": "Deterministic dead-code analysis for TypeScript, class and type members included",

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;

package/src/report.ts

@@ -5,7 +5,7 @@
  */
 
 import type { Severity, Sort, TargetKind } from "./config.ts";
-import type { Conformance } from "./conformance.ts";
+import type { Conformance, DeclaredGap } from "./conformance.ts";
 import type { EdgeEvaluation } from "./edges.ts";
 import type {
   CompletedFinding,
@@ -105,6 +105,13 @@ export interface WireStaleSuppression {
   readonly message: string;
 }
 
+interface WireDeclaredGap {
+  readonly fixture: string;
+  readonly symbol?: string;
+  readonly capability: string;
+  readonly reason: string;
+}
+
 export interface WireTotals {
   readonly findings: number;
   readonly by_severity: { readonly allow: number; readonly warn: number; readonly deny: number };
@@ -159,7 +166,7 @@ export interface Report {
   readonly findings: readonly WireFinding[];
   readonly edge_evaluations: readonly WireEdgeEvaluation[];
   readonly stale_suppressions: readonly WireStaleSuppression[];
-  readonly declared_gaps: readonly never[];
+  readonly declared_gaps: readonly WireDeclaredGap[];
   readonly excluded_by_cgo: readonly never[];
   readonly test_file_rules: readonly TestFileRule[];
   readonly totals: WireTotals;
@@ -170,6 +177,7 @@ export interface ReportInput {
   readonly contractVersion: string;
   readonly version: string;
   readonly conformance: Conformance;
+  readonly declaredGaps: readonly DeclaredGap[];
   readonly target: { readonly kind: TargetKind; readonly root: string; readonly identity: string };
   readonly configurations: readonly ReportConfiguration[];
   readonly unavailable: readonly UnavailableConsumer[];
@@ -318,6 +326,16 @@ function canonicalStale(a: WireStaleSuppression, b: WireStaleSuppression): numbe
   );
 }
 
+/** One declared gap as a report carries it, its members in the schema's order. */
+function wireGap(gap: DeclaredGap): WireDeclaredGap {
+  return {
+    fixture: gap.fixture,
+    ...(gap.symbol === undefined ? {} : { symbol: gap.symbol }),
+    capability: gap.capability,
+    reason: gap.reason,
+  };
+}
+
 /** Edge evaluations by edge, then side, then their compact encodings. */
 function byEdge(a: WireEdgeEvaluation, b: WireEdgeEvaluation): number {
   return (
@@ -392,7 +410,11 @@ export function buildReport(input: ReportInput): Report {
     findings,
     edge_evaluations: input.result.edgeEvaluations.map(wireEvaluation).sort(byEdge),
     stale_suppressions: input.result.staleSuppressions.map(wireStale).sort(canonicalStale),
-    declared_gaps: [],
+    // Every gap shares the one component of the canonical key a gap supplies, the analyzer's
+    // name, so the compact encodings alone order them.
+    declared_gaps: input.declaredGaps
+      .map(wireGap)
+      .sort((a, b) => compare(JSON.stringify(a), JSON.stringify(b))),
     excluded_by_cgo: [],
     test_file_rules: [...input.testFileRules]
       .sort((a, b) => compare(a.rule, b.rule) || a.matched - b.matched)

package/src/verbs/analyze.ts

@@ -1,6 +1,6 @@
 import { runAnalysis, type RunProject } from "../analysis.ts";
 import { ConfigError, type Format } from "../config.ts";
-import { RECORDED_CONFORMANCE, reportedConformance } from "../conformance.ts";
+import { CONFORMANCE, DECLARED_GAPS } from "../conformance.ts";
 import { analyzerProvenance, recordedFindings, verdictOf } from "../findings-pass.ts";
 import { packageScope } from "../inventory.ts";
 import { normalizePath, relativePath, resolvePath } from "../paths.ts";
@@ -175,7 +175,8 @@ export const analyzeVerb: Verb = ({ err, host, inputs, scope, openClient, option
     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) => ({

package/src/verbs/describe.ts

@@ -1,4 +1,4 @@
-import { RECORDED_CONFORMANCE, type Conformance } from "../conformance.ts";
+import { CONFORMANCE, type Conformance } from "../conformance.ts";
 import { ANALYZER_NAME, LANGUAGE, SCHEMA_VERSION } from "../report.ts";
 import { CONTRACT_VERSION } from "../version.ts";
 import { EXIT_CLEAN, EXIT_FAILURE, EXIT_USAGE, type Verb } from "./verb.ts";
@@ -6,24 +6,20 @@ import { EXIT_CLEAN, EXIT_FAILURE, EXIT_USAGE, type Verb } from "./verb.ts";
 /**
  * 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: string, recorded: Conformance | undefined): string {
+export function describeDocument(version: string, recorded: Conformance): string {
   const document = {
     name: ANALYZER_NAME,
     version,
     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`;
 }
@@ -41,6 +37,6 @@ export const describeVerb: Verb = ({ 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;
 };