@cplieger/deadset-ts 8.0.0-dev.4 → 8.0.0-dev.6

package/src/findings/self-check.ts

@@ -1,3 +1,4 @@
+import { CODE } from "../contract/contract.generated.ts";
 import { REPOSITORY_DOCUMENT } from "../config.ts";
 import type { Finding, FindingDetails, SuppressionEntry } from "../finding.ts";
 import type { InventorySymbol } from "../inventory.ts";
@@ -6,20 +7,12 @@ import type { Position } from "../position.ts";
 import {
   isDependencyCode,
   isUnsuppressibleCode,
-  STALE_SUPPRESSION,
-  SUPPRESSION_WITHOUT_REASON,
   type Mechanism,
   type Refusal,
   type SuppressionRecord,
 } from "../suppress.ts";
 import type { Emitter } from "./emitter.ts";
 
-/** The code a configured root that matches nothing is reported under. */
-const UNMATCHED_ROOT = "DS1704";
-
-/** The code a configured declaration that names nothing is reported under. */
-const UNMATCHED_DECLARATION = "DS1706";
-
 /** The subject kind of a finding about a configured declaration. */
 const DECLARATION_SUBJECT = "configured-declaration";
 
@@ -39,7 +32,7 @@ export interface StaleRecord {
   readonly reports: readonly string[];
 }
 
-/** What the self-check family reads: the run's refused suppressions and its configured roots. */
+/** What the configuration family reads: the run's refused suppressions and its configured roots. */
 export interface SelfCheckFacts {
   /** The suppressions the grammar refused with a finding, in reading order. */
   readonly refusals: readonly Refusal[];
@@ -135,7 +128,7 @@ function refusedSuppressions(refusals: readonly Refusal[], files: FileRefs): rea
       suppressionRef(refused.symbol, refused.path, files),
       refused.site,
       `${WRITTEN[refused.mechanism]} for ${refused.code} ${
-        refused.reported === SUPPRESSION_WITHOUT_REASON
+        refused.reported === CODE.suppressionWithoutReason
           ? "carries no reason"
           : "names a symbol and no path"
       }`,
@@ -146,7 +139,7 @@ function refusedSuppressions(refusals: readonly Refusal[], files: FileRefs): rea
 
 /** One stale suppression as the report's stale-suppression record carries it. */
 export interface StaleSuppression {
-  readonly code: typeof STALE_SUPPRESSION;
+  readonly code: typeof CODE.staleSuppression;
   readonly mechanism: Mechanism;
   readonly entry: {
     readonly code: string;
@@ -209,7 +202,7 @@ export function staleSuppressions(
           ? ""
           : `, and ${declared}`;
     return {
-      code: STALE_SUPPRESSION,
+      code: CODE.staleSuppression,
       mechanism: first.mechanism,
       entry: {
         code: first.code,
@@ -242,7 +235,7 @@ function unmatchedDeclarationFindings(
   unmatched: readonly UnmatchedDeclaration[],
 ): readonly Finding[] {
   return unmatched.map((one) => ({
-    code: UNMATCHED_DECLARATION,
+    code: CODE.unmatchedConfiguredDeclaration,
     position: documentPosition(one.document),
     symbol: { ref: one.ref, kind: DECLARATION_SUBJECT, name: one.ref, sizeLines: 1 },
     message: `${one.key} entry names no declaration in any project`,
@@ -262,7 +255,7 @@ export function unmatchedRootFindings(
 ): readonly Finding[] {
   const position = documentPosition(document);
   return sources.map((source) => ({
-    code: UNMATCHED_ROOT,
+    code: CODE.unmatchedRoot,
     position,
     symbol: { ref: source, kind: ROOT_SUBJECT, name: source, sizeLines: 1 },
     message:
@@ -273,7 +266,7 @@ export function unmatchedRootFindings(
 }
 
 /**
- * The findings of the self-check family, `DS1700` to `DS1799`: a suppression refused for
+ * The findings of the configuration family, `DS9000` to `DS9099`: a suppression refused for
  * carrying no reason or naming no path, and a configured root or declaration that named
  * nothing. A
  * suppression that matched nothing is a record of the report's stale suppressions, which

package/src/findings/unused-declarations.ts

@@ -1,3 +1,4 @@
+import { CODE } from "../contract/contract.generated.ts";
 import type { Finding } from "../finding.ts";
 import type { InventorySymbol, SymbolKind } from "../inventory.ts";
 import type { MatrixCandidate } from "../matrix.ts";
@@ -14,18 +15,18 @@ const MEMBERS: ReadonlySet<SymbolKind> = new Set([
 ]);
 
 /**
- * The kinds of declaration no code of this family reports: an interface and a method an
+ * The kinds of declaration no code of this emitter reports: an interface and a method an
  * interface declares are the interface kinds' subjects, and a type parameter is the
  * subject of the unused-type-parameter kind or of none.
  */
-const NOT_THIS_FAMILY: ReadonlySet<SymbolKind> = new Set([
+const NOT_REPORTED_HERE: ReadonlySet<SymbolKind> = new Set([
   "file",
   "interface",
   "interface-method",
   "type-parameter",
 ]);
 
-/** The reader's word for each kind of declaration a finding of the family names. */
+/** The reader's word for each kind of declaration a finding of this emitter names. */
 const WORDS: Readonly<Record<SymbolKind, string>> = {
   file: "file",
   function: "function",
@@ -71,9 +72,9 @@ interface Judged {
 function codeOf(judged: Judged): string | undefined {
   const { candidate, symbol } = judged;
   if (candidate.testOfDeadCode) {
-    return judged.testsUnseenAPI ? undefined : "DS1005";
+    return judged.testsUnseenAPI ? undefined : CODE.testOfDeadCode;
   }
-  if ((judged.test && !candidate.unreferencedTest) || NOT_THIS_FAMILY.has(symbol.kind)) {
+  if ((judged.test && !candidate.unreferencedTest) || NOT_REPORTED_HERE.has(symbol.kind)) {
     return undefined;
   }
   const referenced = candidate.productionRefs + candidate.testRefs > 0;
@@ -84,33 +85,33 @@ function codeOf(judged: Judged): string | undefined {
     return unreferencedCode(symbol);
   }
   if (candidate.heldByTests === candidate.id) {
-    return "DS1004";
+    return CODE.testOnlyUse;
   }
   if (candidate.productionRefs === 0 && judged.deprecated) {
-    return "DS1006";
+    return CODE.deprecatedUnused;
   }
   if (
     candidate.testRefs > 0 &&
     (candidate.productionRefs === 0 ||
       (candidate.relation === "reachability" && candidate.keptByTests))
   ) {
-    return "DS1004";
+    return CODE.testOnlyUse;
   }
   if (MEMBERS.has(symbol.kind)) {
-    return "DS1003";
+    return CODE.unusedMember;
   }
   if (!symbol.exported) {
-    return "DS1002";
+    return CODE.unusedUnexported;
   }
-  return judged.unreachable ? undefined : "DS1001";
+  return judged.unreachable ? undefined : CODE.unusedExported;
 }
 
 /** The code a declaration nothing references carries, by its shape and its visibility. */
 function unreferencedCode(symbol: InventorySymbol): string {
   if (MEMBERS.has(symbol.kind)) {
-    return "DS1003";
+    return CODE.unusedMember;
   }
-  return symbol.exported ? "DS1001" : "DS1002";
+  return symbol.exported ? CODE.unusedExported : CODE.unusedUnexported;
 }
 
 /** The visibility a member's message names, where it narrows the member's reach. */
@@ -135,17 +136,17 @@ function messageOf(code: string, judged: Judged): string {
   const { candidate, symbol } = judged;
   const word = WORDS[symbol.kind];
   switch (code) {
-    case "DS1005":
+    case CODE.testOfDeadCode:
       return TEST_OF_DEAD_CODE;
-    case "DS1006":
+    case CODE.deprecatedUnused:
       return `deprecated ${word} has no production reference`;
-    case "DS1004":
+    case CODE.testOnlyUse:
       return candidate.productionRefs === 0
         ? `${word} is referenced only from test files and never from production code`
         : `${word} is referenced only from test files and from declarations that are themselves dead`;
   }
   const subject =
-    code === "DS1003"
+    code === CODE.unusedMember
       ? `${visibilityWord(symbol)}${word}`
       : symbol.kind === "export-alias"
         ? word
@@ -153,7 +154,7 @@ function messageOf(code: string, judged: Judged): string {
   if (candidate.relation === "reachability") {
     return `${subject} is referenced only from declarations that are themselves dead`;
   }
-  if (code === "DS1001") {
+  if (code === CODE.unusedExported) {
     return `${subject} has no reference in the target and none from any loaded consumer`;
   }
   return `${subject} has no reference in the target`;
@@ -205,15 +206,15 @@ function brandMembers(input: EmitterInput): ReadonlySet<string> {
 /** The kinds of member a brand is: a data member of a type or of a class. */
 const BRANDS: ReadonlySet<SymbolKind> = new Set(["type-member", "class-member"]);
 
-/** The findings of the unused-declarations family, `DS1000` to `DS1099`. */
+/** The findings of the unused-declaration kinds, `DS1001` to `DS1004` and `DS1102` to `DS1104`. */
 export const unusedDeclarations: Emitter = (input) => [
-  ...familyFindings(input, false),
+  ...emitterFindings(input, false),
   ...unusedImports(input),
 ];
 
 /**
- * The import bindings their file never reads, under the unexported code. A generated
- * file's are the generator's to remove unless the run includes generated files.
+ * The import bindings their file never reads. A generated file's are the generator's to
+ * remove unless the run includes generated files.
  */
 function unusedImports(input: EmitterInput): Finding[] {
   const generated =
@@ -223,7 +224,7 @@ function unusedImports(input: EmitterInput): Finding[] {
       ? []
       : [
           {
-            code: "DS1002",
+            code: CODE.unusedImport,
             position: binding.position,
             symbol: { ref: binding.ref, kind: "import", name: binding.name, sizeLines: 1 },
             message: `import binding ${binding.name} is never read in its file`,
@@ -237,10 +238,10 @@ function unusedImports(input: EmitterInput): Finding[] {
  * a record on such a member is matched against, since the report carries the container's
  * finding rather than one of the member's own.
  */
-export const fallenMembers: Emitter = (input) => familyFindings(input, true);
+export const fallenMembers: Emitter = (input) => emitterFindings(input, true);
 
-/** The family's findings, or, where `fallen` is set, its dead containers' members' alone. */
-function familyFindings(input: EmitterInput, fallen: boolean): Finding[] {
+/** This emitter's findings, or, where `fallen` is set, its dead containers' members' alone. */
+function emitterFindings(input: EmitterInput, fallen: boolean): Finding[] {
   const union = input.swept.matrix.union;
   const dead = new Set(input.swept.sweep.candidates.map((candidate) => candidate.id));
   const unreachable = unreachableExports(input);
@@ -269,7 +270,7 @@ function familyFindings(input: EmitterInput, fallen: boolean): Finding[] {
     const code = codeOf(judged);
     if (
       code === undefined ||
-      (code === "DS1003" && (brands ??= brandMembers(input)).has(symbol.id))
+      (code === CODE.unusedMember && (brands ??= brandMembers(input)).has(symbol.id))
     ) {
       continue;
     }

package/src/findings/visibility-narrowing.ts

@@ -1,3 +1,4 @@
+import { CODE } from "../contract/contract.generated.ts";
 import type { Finding } from "../finding.ts";
 import { OUTSIDE, type Graph } from "../graph.ts";
 import type { InventorySymbol, SymbolKind } from "../inventory.ts";
@@ -8,10 +9,6 @@ import { runnerCalls } from "../sweep.ts";
 import type { Emitter, EmitterInput } from "./emitter.ts";
 import { writeOnlyDeclarations } from "./reads-and-writes.ts";
 
-const UNNECESSARY_EXPORT = "DS1101";
-const UNREACHABLE_EXPORT = "DS1103";
-const REDUNDANT_EXPORT_KEYWORD = "DS1104";
-
 /** How far the references to one declaration reach, from the narrowest. */
 type Reach = "file" | "package" | "outside";
 
@@ -22,7 +19,7 @@ type Reach = "file" | "package" | "outside";
  */
 const PUBLISHING: ReadonlySet<RootKind> = new Set<RootKind>(["manifest-entry", "published-api"]);
 
-/** The reader's word for each kind of declaration this family reports. */
+/** The reader's word for each kind of declaration this emitter reports. */
 const WORDS: Partial<Readonly<Record<SymbolKind, string>>> = {
   function: "function",
   class: "class",
@@ -151,8 +148,8 @@ function wordOf(symbol: InventorySymbol): string {
 
 /** The visibility each narrowing code names, which only the narrowing codes carry. */
 const NARROWER: Readonly<Record<string, "file" | "package">> = {
-  [REDUNDANT_EXPORT_KEYWORD]: "file",
-  [UNNECESSARY_EXPORT]: "package",
+  [CODE.redundantExportKeyword]: "file",
+  [CODE.unnecessaryExport]: "package",
 };
 
 function findingOf(symbol: InventorySymbol, code: string, message: string): Finding {
@@ -206,7 +203,7 @@ function narrowing(
       }
       return findingOf(
         symbol,
-        REDUNDANT_EXPORT_KEYWORD,
+        CODE.redundantExportKeyword,
         `exported ${word} is referenced only inside the file that declares it`,
       );
     case "package":
@@ -215,7 +212,7 @@ function narrowing(
       }
       return findingOf(
         symbol,
-        UNNECESSARY_EXPORT,
+        CODE.unnecessaryExport,
         `exported ${word} is referenced only inside the package that declares it`,
       );
     default:
@@ -254,13 +251,13 @@ function unreachable(
       : "has no reference in the target";
   return findingOf(
     symbol,
-    UNREACHABLE_EXPORT,
+    CODE.unreachableExport,
     `exported ${wordOf(symbol)} ${found}, and nothing outside can import the file that declares it`,
   );
 }
 
 /**
- * The visibility-narrowing family over one run: `DS1101`, `DS1103` and `DS1104`. A finding
+ * The visibility-narrowing kinds over one run: `DS1501`, `DS1101` and `DS1503`. A finding
  * about a symbol a declared cross-language edge names is reported here like any other, and
  * the edge's evaluation then holds it pending, because the edge stands for a reference from
  * outside the file and the package whose use is decided in the other language. A
@@ -316,5 +313,5 @@ export function unreachableExports(input: EmitterInput): ReadonlySet<string> {
   return found;
 }
 
-/** The findings of the visibility-narrowing family, `DS1100` to `DS1199`. */
+/** The findings of the visibility-narrowing kinds, `DS1501`, `DS1101` and `DS1503`. */
 export const visibilityNarrowing: Emitter = narrowings;

package/src/findings-pass.ts

@@ -4,6 +4,7 @@
  * verdict a report carries beside them.
  */
 
+import { EXIT_CLEAN, EXIT_FINDINGS, EXIT_PENDING } from "./contract/contract.generated.ts";
 import type { AnalysisInputs } from "./analysis.ts";
 import { fails, type Config } from "./config.ts";
 import type { EdgeEvaluation } from "./edges.ts";
@@ -23,7 +24,6 @@ import {
   type Ledger,
 } from "./suppress.ts";
 import type { Provenance, Recorded } from "./suppress-file.ts";
-import { EXIT_CLEAN, EXIT_FINDINGS } from "./verbs/verb.ts";
 
 /** The counts a report's totals carry beside its findings. */
 interface PassTotals {
@@ -49,9 +49,6 @@ export interface PassResult {
   readonly ledger: Ledger;
 }
 
-/** The exit code of a report holding at least one pending finding. */
-export const EXIT_PENDING = 4;
-
 /** Two strings ordered bytewise. */
 function compare(a: string, b: string): number {
   if (a === b) {

package/src/index.ts

@@ -19,4 +19,4 @@ export {
   type Fragment,
   type Module,
 } from "./ref.ts";
-export { CONTRACT_VERSION } from "./version.ts";
+export { CONTRACT_VERSION } from "./contract/contract.generated.ts";

package/src/intra-function-parts.ts

@@ -5,6 +5,7 @@
  * write to a local that no read reaches, and each case an earlier case covers.
  */
 
+import { CODE } from "./contract/contract.generated.ts";
 import {
   isArrowFunction,
   isAwaitExpression,
@@ -179,13 +180,6 @@ export interface ProjectParts {
   readonly constructions: ReadonlySet<string>;
 }
 
-/** The codes of the parts this module reads. */
-export const UNUSED_PARAMETER = "DS1801";
-export const UNUSED_RESULT = "DS1803";
-const UNREACHABLE_STATEMENT = "DS1805";
-const DEAD_STORE = "DS1807";
-const UNREACHABLE_CASE = "DS1809";
-
 /** The result types that carry no value, as the checker spells them. */
 const NO_VALUE: ReadonlySet<string> = new Set([
   "void",
@@ -869,7 +863,7 @@ export function projectParts<Brand>(
     }
     walk.catches.forEach(({ name, holder }, at) => {
       parts.push({
-        code: DEAD_STORE,
+        code: CODE.deadStore,
         declaration: holder,
         kind: "store",
         name: name.text,
@@ -881,7 +875,7 @@ export function projectParts<Brand>(
     for (const { names, uses, holder } of loopVariables) {
       for (const name of names) {
         parts.push({
-          code: DEAD_STORE,
+          code: CODE.deadStore,
           declaration: holder,
           kind: "store",
           name: name.text,
@@ -899,7 +893,7 @@ export function projectParts<Brand>(
     });
     for (const { statement, holder } of walk.unreachable) {
       parts.push({
-        code: UNREACHABLE_STATEMENT,
+        code: CODE.unreachableStatement,
         declaration: holder,
         kind: "statement",
         name: "statement",
@@ -910,7 +904,7 @@ export function projectParts<Brand>(
     }
     for (const { clause, text, holder } of walk.cases) {
       parts.push({
-        code: UNREACHABLE_CASE,
+        code: CODE.unreachableCase,
         declaration: holder,
         kind: "case",
         name: text,
@@ -1176,7 +1170,7 @@ function parameterParts(
       return;
     }
     const part: PartFact = {
-      code: UNUSED_PARAMETER,
+      code: CODE.unusedParameter,
       declaration,
       kind: "parameter",
       name: name.text,
@@ -1353,7 +1347,7 @@ function deadStores(
 ): PartFact[] {
   const found: PartFact[] = [];
   const deadAt = (local: Local, target: Identifier): PartFact => ({
-    code: DEAD_STORE,
+    code: CODE.deadStore,
     declaration: holder,
     kind: "store",
     name: local.name.text,
@@ -1482,7 +1476,7 @@ function resultParts<Brand>(
     const valued = project.queries.nonNullable(result);
     const members = isAnswered(valued) ? project.queries.propertiesOf(valued) : UNANSWERED;
     found.push({
-      code: UNUSED_RESULT,
+      code: CODE.unusedResult,
       declaration: id,
       kind: "result",
       name: "result",