@cplieger/deadset-ts 8.0.0-dev.5 → 8.0.0-dev.7

package/src/enum-group.ts

@@ -18,7 +18,6 @@ import {
   isIdentifier,
   isMethodDeclaration,
   isNoSubstitutionTemplateLiteral,
-  isParenthesizedExpression,
   isParenthesizedTypeNode,
   isPropertyAccessExpression,
   isReturnStatement,
@@ -28,6 +27,7 @@ import {
   type Node,
   type SourceFile,
 } from "@typescript/native/ast";
+import { parenthesesRemoved } from "./unwrap.ts";
 import { TypeFlags, type Type } from "@typescript/native/sync";
 import { aliasChains } from "./alias-chain.ts";
 import type { DetectorInput, Evidence } from "./exempt.ts";
@@ -55,15 +55,6 @@ interface Site {
   readonly at: Node;
 }
 
-/** The expression one node is, through however many parentheses are written around it. */
-function unparenthesized(node: Node): Node {
-  let held = node;
-  while (isParenthesizedExpression(held)) {
-    held = held.expression;
-  }
-  return held;
-}
-
 /**
  * The name node a type node names its declaration by: the identifier of a type
  * reference, the right side of a qualified one, through parentheses. A type that is no
@@ -86,7 +77,7 @@ function typeName(type: Node | undefined): Node | undefined {
 
 /** The name node an expression names an object by: an identifier, or a property access's name. */
 function objectName(expression: Node): Node | undefined {
-  const held = unparenthesized(expression);
+  const held = parenthesesRemoved(expression);
   if (isIdentifier(held)) {
     return held;
   }

package/src/erased-stores.ts

@@ -16,7 +16,6 @@ import {
   isNoSubstitutionTemplateLiteral,
   isNumericLiteral,
   isObjectLiteralExpression,
-  isParenthesizedExpression,
   isPropertyAccessExpression,
   isPropertyAssignment,
   isShorthandPropertyAssignment,
@@ -31,6 +30,7 @@ import { SymbolFlags, TypeFlags, type Type } from "@typescript/native/sync";
 import { must } from "./query.ts";
 import type { ProjectView } from "./session.ts";
 import { checkedTypes } from "./value-reach.ts";
+import { parenthesesRemoved } from "./unwrap.ts";
 
 /** The types that keep nothing of the value they are given. */
 const ERASED = TypeFlags.Any | TypeFlags.Unknown;
@@ -81,10 +81,6 @@ function literalKey(node: Expression): string | undefined {
     : undefined;
 }
 
-function unwrapped(node: Expression): Expression {
-  return isParenthesizedExpression(node) ? unwrapped(node.expression) : node;
-}
-
 /**
  * Whether a variable declaration's type can differ from what is stored in it: it carries an
  * annotation, or it has neither an annotation nor an initializer, so its type evolves.
@@ -150,8 +146,8 @@ function propertyAt(source: Expression, name: string): Expression | undefined {
  * here, and a default value is stored in its target too.
  */
 function patternTargets(pattern: Expression, from: Stored, out: Target[]): void {
-  const target = unwrapped(pattern);
-  const source = from.path.length === 0 ? unwrapped(from.value) : from.value;
+  const target = parenthesesRemoved(pattern);
+  const source = from.path.length === 0 ? parenthesesRemoved(from.value) : from.value;
   const into = (element: Expression, step: Step, literal: Expression | undefined): void => {
     patternTargets(
       element,

package/src/exempt-classes.ts

@@ -1,12 +1,4 @@
-/**
- * The exemption classes of the Contract's vocabulary, in its order: each class's name, its
- * languages and, for a TypeScript class, which private members it may retain. The rows are
- * written out, as the fixed severity codes are, and a test holds them equal to the Contract.
- * A class name is a type, so a table or a record naming a class outside the vocabulary, or
- * one of another language only, does not compile.
- */
-
-import type { Language } from "./config.ts";
+import { EXEMPTION_CLASSES, type Language } from "./contract/contract.generated.ts";
 
 /**
  * Whether a class may retain a member declared with the `private` modifier, and one
@@ -19,67 +11,6 @@ export interface TypeScriptVisibility {
   readonly privateName: boolean;
 }
 
-/** One class of the vocabulary. */
-interface ExemptionClassRow {
-  readonly class: string;
-  readonly languages: readonly Language[];
-  /** Present exactly on a class that runs on TypeScript. */
-  readonly typescriptVisibility?: TypeScriptVisibility;
-}
-
-/** Every class of the vocabulary, in the order the Contract lists them. */
-export const EXEMPTION_CLASSES = [
-  {
-    class: "interface-satisfaction",
-    languages: ["go", "ts"],
-    typescriptVisibility: { private: false, privateName: false },
-  },
-  { class: "encoding-reflection", languages: ["go"] },
-  { class: "format-verb-contract", languages: ["go"] },
-  { class: "errors-duck-typing", languages: ["go"] },
-  {
-    class: "enum-group",
-    languages: ["go", "ts"],
-    typescriptVisibility: { private: false, privateName: false },
-  },
-  {
-    class: "generated-file",
-    languages: ["go", "ts"],
-    typescriptVisibility: { private: true, privateName: false },
-  },
-  { class: "linkname-cgo-asm-plugin", languages: ["go"] },
-  {
-    class: "template-field",
-    languages: ["go", "ts"],
-    typescriptVisibility: { private: true, privateName: false },
-  },
-  {
-    class: "reflective-lookup",
-    languages: ["go", "ts"],
-    typescriptVisibility: { private: true, privateName: false },
-  },
-  {
-    class: "decorator",
-    languages: ["ts"],
-    typescriptVisibility: { private: true, privateName: false },
-  },
-  {
-    class: "injection-container",
-    languages: ["ts"],
-    typescriptVisibility: { private: true, privateName: false },
-  },
-  {
-    class: "framework-lifecycle",
-    languages: ["ts"],
-    typescriptVisibility: { private: true, privateName: false },
-  },
-  {
-    class: "serialization-contract",
-    languages: ["ts"],
-    typescriptVisibility: { private: true, privateName: false },
-  },
-] as const satisfies readonly ExemptionClassRow[];
-
 type Row = (typeof EXEMPTION_CLASSES)[number];
 
 /** The name of a class of the vocabulary. */
@@ -117,7 +48,7 @@ export function typescriptVisibilityOf(exemptionClass: TSExemptionClass): TypeSc
   return VISIBILITY.get(exemptionClass) ?? { private: false, privateName: false };
 }
 
-/** 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);
-}
+/** Every class of the vocabulary, whichever language it runs on, in the vocabulary's order. */
+export const EXEMPTION_CLASS_NAMES: readonly ExemptionClass[] = EXEMPTION_CLASSES.map(
+  (row) => row.class,
+);

package/src/exempt.ts

@@ -7,24 +7,23 @@
  * hands it the table of the classes it has.
  */
 
+import { EXEMPTION_CLASSES } from "./contract/contract.generated.ts";
 import type { Config, TSSection } from "./config.ts";
-import { ConfigError } from "./config.ts";
 import {
-  EXEMPTION_CLASSES,
-  isExemptionClass,
   TS_EXEMPTION_CLASSES,
   typescriptVisibilityOf,
   type ExemptionClass,
   type TSExemptionClass,
   type TypeScriptVisibility,
 } from "./exempt-classes.ts";
-import type { Inventory, InventorySymbol, SymbolKind, Visibility } from "./inventory.ts";
+import type { Inventory, InventorySymbol, Visibility } from "./inventory.ts";
 import type { Matrix } from "./matrix.ts";
 import { byPosition, positionKey, type Position } from "./position.ts";
 import { Unanswerable } from "./query.ts";
 import type { ProjectView } from "./session.ts";
 import type { Templates } from "./template-field.ts";
 import { sweep, type Exemption, type Implementing, type Mode, type SweepInput } from "./sweep.ts";
+import { bytewise } from "./text/compare.ts";
 
 /** One declaration a detector holds back, and where and why. */
 export interface Evidence {
@@ -73,24 +72,11 @@ interface Holding {
 }
 
 /**
- * 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.
+ * The classes `exemptions.disabled` switches off. A class that runs on another language
+ * only 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;
+  return new Set(config.exemptionsDisabled);
 }
 
 /**
@@ -107,20 +93,12 @@ function retainable(allowed: TypeScriptVisibility, visibility: Visibility | unde
   return true;
 }
 
-/**
- * The kinds of declaration each class can hold back, which a detector that stops holds
- * back whole. A class with no row here holds back every declaration but a file.
- */
-const RETAINABLE: ReadonlyMap<TSExemptionClass, ReadonlySet<SymbolKind>> = new Map([
-  ["interface-satisfaction", new Set<SymbolKind>(["method", "class-member"])],
-  ["enum-group", new Set<SymbolKind>(["enum-member"])],
-  ["injection-container", new Set<SymbolKind>(["method", "class-member"])],
-  ["framework-lifecycle", new Set<SymbolKind>(["method", "class-member"])],
-  [
-    "serialization-contract",
-    new Set<SymbolKind>(["method", "class-member", "interface-method", "type-member"]),
-  ],
-]);
+/** The kinds of declaration each class can hold back, which a detector that stops holds back whole. */
+const RETAINABLE: ReadonlyMap<string, ReadonlySet<string>> = new Map(
+  EXEMPTION_CLASSES.flatMap((row) =>
+    "ts" in row.retainsKinds ? [[row.class, new Set<string>(row.retainsKinds.ts)] as const] : [],
+  ),
+);
 
 /** The detail of a record a detector that could not finish holds. */
 const UNANSWERED_DETAIL = "kept live by a question the checker did not answer";
@@ -149,7 +127,7 @@ function detected<Brand>(
     }
     const kinds = RETAINABLE.get(exemptionClass);
     return input.held.symbols
-      .filter((symbol) => (kinds === undefined ? symbol.kind !== "file" : kinds.has(symbol.kind)))
+      .filter((symbol) => kinds?.has(symbol.kind) === true)
       .map((symbol) => ({ id: symbol.id, detail: UNANSWERED_DETAIL, site: symbol.position }));
   }
 }
@@ -229,14 +207,6 @@ export function heldRecords(records: readonly Exemption[], holding: Holding): De
   return { records: exemptionsOf(found), inTestFiles };
 }
 
-/** 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, detail and file it holds while live, the one at the first
@@ -244,7 +214,7 @@ function compare(a: string, b: string): number {
  */
 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),
+    (a, b) => byPosition(a.site, b.site) || bytewise(a.class, b.class) || bytewise(a.id, b.id),
   );
   const seen = new Set<string>();
   return ordered.filter((record) => {
@@ -316,8 +286,8 @@ export function retainedIn(
 }
 
 /**
- * One line per held-back declaration, in site order: its reference, then each record's
- * class, site and detail, all separated by tabs.
+ * One line per held-back declaration, in site order: its reference and position, then
+ * each record's class, site and detail, all separated by tabs.
  */
 export function retainedLines(
   symbols: readonly InventorySymbol[],
@@ -334,6 +304,6 @@ export function retainedLines(
       positionKey(record.site),
       record.detail,
     ]);
-    return [[symbol.ref, ...fields].join("\t")];
+    return [[symbol.ref, positionKey(symbol.position), ...fields].join("\t")];
   });
 }

package/src/file-facts.ts

@@ -5,13 +5,13 @@
  */
 
 import type { SourceFile } from "@typescript/native/ast";
-import { IGNORED_DIRECTORIES } from "./discover.ts";
 import type { Host } from "./host.ts";
 import { packageScope } from "./inventory.ts";
 import { dirnamePath, joinPath, relativePath, resolvePath } from "./paths.ts";
 import { renderRef } from "./ref.ts";
 import type { ProjectView } from "./session.ts";
 import type { UnseenLoad } from "./unseen-loads.ts";
+import { filesBelow } from "./fs/tree.ts";
 
 /** A file name the compiler reads as a source file. */
 const SOURCE_FILE = /\.(?:ts|tsx|mts|cts)$/u;
@@ -74,29 +74,11 @@ function lastLine(text: string): number {
  * that cannot be read is skipped, as discovery skips it.
  */
 export function sourcePaths(host: Host, targetRoot: string): readonly string[] {
-  const found: string[] = [];
-  const pending = [""];
-  for (let dir = pending.pop(); dir !== undefined; dir = pending.pop()) {
-    let entries: readonly { readonly name: string; readonly directory: boolean }[];
-    try {
-      entries = host.readDirectory(joinPath(targetRoot, dir));
-    } catch {
-      continue;
-    }
-    for (const entry of entries) {
-      const path = dir === "" ? entry.name : `${dir}/${entry.name}`;
-      if (entry.directory) {
-        if (!IGNORED_DIRECTORIES.has(entry.name)) {
-          pending.push(path);
-        }
-        continue;
-      }
-      if (SOURCE_FILE.test(entry.name) && !DECLARATION_FILE.test(entry.name)) {
-        found.push(path);
-      }
-    }
-  }
-  return found.sort((a, b) => (a < b ? -1 : 1));
+  return filesBelow(
+    host,
+    targetRoot,
+    (name) => SOURCE_FILE.test(name) && !DECLARATION_FILE.test(name),
+  );
 }
 
 /**

package/src/finding.ts

@@ -1,8 +1,8 @@
-import type { Confidence, Severity } from "./config.ts";
-import type { Fixability } from "./kinds.ts";
+import type { Fixability, Confidence, Severity } from "./contract/contract.generated.ts";
 import type { DependencySection } from "./ref.ts";
 import type { Mechanism } from "./suppress.ts";
 import type { Relation } from "./sweep.ts";
+import type { FindingSymbol } from "./contract/report.generated.ts";
 
 /**
  * The finding: what an emitter decides about one subject, and every member the
@@ -29,7 +29,7 @@ interface FindingSubject {
   /** The stable symbol reference, or for a configured root the root as written. */
   readonly ref: string;
   /** The subject kind, from the closed vocabulary of the finding schema. */
-  readonly kind: string;
+  readonly kind: FindingSymbol["kind"];
   /** The display name a text line renders. */
   readonly name: string;
   /** The number of source lines the subject spans. */
@@ -55,19 +55,19 @@ export interface PositionedSymbol {
  */
 export interface FindingDetails {
   /**
-   * On `DS1101` and `DS1104`: the widest scope that holds every reference to the
+   * On `DS1501` and `DS1503`: the widest scope that holds every reference to the
    * subject, which is the visibility its references support.
    */
   readonly narrowerVisibility?: "file" | "package";
-  /** On `DS1201` and `DS1203`: the classes implementing the interface, in site order. */
+  /** On `DS1201` and `DS1202`: the classes implementing the interface, in site order. */
   readonly implementations?: readonly PositionedSymbol[];
-  /** On `DS1301` and `DS1807`: every position the subject is written at, in site order. */
+  /** On `DS1301` and `DS1404`: every position the subject is written at, in site order. */
   readonly writePositions?: readonly FindingPosition[];
-  /** On `DS1601`: the manifest section that declares the dependency. */
+  /** On `DS1701`: the manifest section that declares the dependency. */
   readonly dependencyClass?: DependencySection;
-  /** On `DS1701` and `DS1702`: the document that holds the refused suppression. */
+  /** On `DS9001` and `DS9002`: the document that holds the refused suppression. */
   readonly mechanism?: Mechanism;
-  /** On `DS1701` and `DS1702`: the refused suppression as written, a member absent where it lacks one. */
+  /** On `DS9001` and `DS9002`: the refused suppression as written, a member absent where it lacks one. */
   readonly entry?: SuppressionEntry;
   /** On the intra-function kinds: the external rules that report the same kind, as the vocabulary lists them. */
   readonly overlap?: readonly string[];

package/src/findings/completion.ts

@@ -4,39 +4,38 @@
  * together with every finding that falls with a root they withhold.
  */
 
+import {
+  CODE,
+  FAMILY_KEY_LENGTH,
+  type Confidence,
+  type Severity,
+  KIND_ROWS,
+  type KindRow,
+} from "../contract/contract.generated.ts";
 import type { RunSweep } from "../analysis.ts";
 import { componentId, type Component } from "../components.ts";
 import { deadComponents } from "../matrix.ts";
-import type { Cascade, Confidence, Severity } from "../config.ts";
+import type { Cascade } from "../config.ts";
 import type { CompletedFinding, Finding, FindingComponent, PositionedSymbol } from "../finding.ts";
 import { OUTSIDE, type Graph } from "../graph.ts";
 import type { SymbolKind } from "../inventory.ts";
-import { KINDS, type KindRow } from "../kinds.ts";
+import { KINDS } from "../kinds.ts";
 import { byPosition, positionKey } from "../position.ts";
 import { declarationKey } from "../ref.ts";
-import { FAMILY_KEY_LENGTH } from "../resolve.ts";
 import { isPartSubject, isRowSubject, type Dials } from "../suppress.ts";
 import type { Candidate } from "../sweep.ts";
 import type { Boundary } from "./boundary.ts";
 import type { EmitterInput } from "./emitter.ts";
 
-/** The unused-file code, whose deletion removes every use its file writes. */
-const FILE_NEVER_IMPORTED = "DS1502";
-
 /**
- * The codes whose subject the run that counts test references holds live, as
- * finding.schema.json lists them, so a test file's candidate reported under one carries
- * none of a dead declaration's sweep facts.
+ * The codes whose subject the run that counts test references holds live, so a test
+ * file's candidate reported under one carries none of a dead declaration's sweep facts.
  */
-const LIVE_SUBJECT: ReadonlySet<string> = new Set([
-  "DS1101",
-  "DS1102",
-  "DS1104",
-  "DS1204",
-  "DS1301",
-]);
+const LIVE_SUBJECT: ReadonlySet<string> = new Set(
+  KIND_ROWS.filter((row) => row.holdsLive).map((row) => row.code),
+);
 
-/** The fixability grammar/analysis.md "Fixability" gives a finding about a held declaration. */
+/** The fixability grammar/analysis/fixability.md gives a finding about a held declaration. */
 const MANUAL = "manual";
 
 /** The member kinds an object property can declare, which an `in` expression tests by name. */
@@ -186,7 +185,7 @@ function testCeilings(
 
 /**
  * The subjects dead only because production code only tests use is: each declaration the
- * sweep marks test-used, each `DS1502` file of such code, and each test of dead code every
+ * sweep marks test-used, each `DS1602` file of such code, and each test of dead code every
  * target of which is one. Nothing they hold references a dead declaration outside them, so
  * the rest of a component they share is reported without them.
  */
@@ -286,7 +285,7 @@ function membersListed(
 }
 
 /**
- * The run's dead components with each file a `DS1502` finding reports dead among them, so
+ * The run's dead components with each file a `DS1602` finding reports dead among them, so
  * the file's declarations fall with it, and with the components each subject that is no
  * declaration falls with joined into one.
  */
@@ -300,7 +299,7 @@ function runComponents(
 } {
   const union = swept.matrix.union;
   const reported = new Set(
-    findings.filter((one) => one.code === FILE_NEVER_IMPORTED).map((one) => one.position.path),
+    findings.filter((one) => one.code === CODE.fileNeverImported).map((one) => one.position.path),
   );
   const files = new Map(
     union.symbols.flatMap((symbol, at) =>
@@ -419,7 +418,7 @@ export function completed(
     const fallsWith = finding.fallsWith?.[0];
     const joined = fallsWith === undefined ? undefined : componentOf(fallsWith);
     const file =
-      finding.code === FILE_NEVER_IMPORTED ? files.get(finding.position.path) : undefined;
+      finding.code === CODE.fileNeverImported ? files.get(finding.position.path) : undefined;
     const found =
       joined !== undefined
         ? { ...joined, root: false }
@@ -471,7 +470,7 @@ export function completed(
     const used =
       judged !== undefined
         ? candidate !== undefined && testUsed.declarations.has(judged.id)
-        : finding.code === FILE_NEVER_IMPORTED && testUsed.files.has(finding.position.path);
+        : finding.code === CODE.fileNeverImported && testUsed.files.has(finding.position.path);
     const reachabilityClass = used && candidate?.testOfDeadCode !== true ? "possible" : ownClass;
     const configurations =
       candidate?.configurations ??
@@ -499,7 +498,7 @@ export function completed(
         ? undefined
         : candidate !== undefined
           ? input.dependencies.lastUses.get(candidate.id)
-          : finding.code === FILE_NEVER_IMPORTED
+          : finding.code === CODE.fileNeverImported
             ? input.dependencies.fileLastUses.get(finding.position.path)
             : undefined;
     return {

package/src/findings/dependencies-and-module-machinery.ts

@@ -1,13 +1,10 @@
+import { CODE } from "../contract/contract.generated.ts";
 import { declarationKey, type Dependencies } from "../dependencies.ts";
 import type { Finding } from "../finding.ts";
 import { renderRef, type DependencySection } from "../ref.ts";
 import type { Emitter, EmitterInput } from "./emitter.ts";
 import { nonCodeArtifacts } from "./non-code-artifacts.ts";
 
-const UNUSED_DEPENDENCY = "DS1601";
-
-const FILE_NEVER_IMPORTED = "DS1502";
-
 const MESSAGES: Readonly<Record<DependencySection, string>> = {
   dependency: "no import in the target needs the declared dependency",
   "dev-dependency": "no import in the target needs the declared development dependency",
@@ -46,7 +43,7 @@ function deadCode(input: EmitterInput): DeadCode {
   );
   for (const finding of nonCodeArtifacts(input)) {
     const id = files.get(finding.position.path);
-    if (finding.code === FILE_NEVER_IMPORTED && id !== undefined) {
+    if (finding.code === CODE.fileNeverImported && id !== undefined) {
       dead.add(id);
       if (finding.unreachableOnly === true) {
         reachedOnly.add(id);
@@ -81,7 +78,7 @@ function unusedDependencies(input: EmitterInput, dependencies: Dependencies): Fi
     const atPossible = unbuilt || users?.some((id) => published.has(id)) === true;
     return [
       {
-        code: UNUSED_DEPENDENCY,
+        code: CODE.unusedDependency,
         position: dependency.position,
         symbol: {
           ref: renderRef(dependency.manifest, {
@@ -105,6 +102,6 @@ function unusedDependencies(input: EmitterInput, dependencies: Dependencies): Fi
   });
 }
 
-/** The findings of the dependencies-and-module-machinery family, `DS1600` to `DS1699`. */
+/** The findings of the dependencies family, `DS1700` to `DS1799`. */
 export const dependenciesAndModuleMachinery: Emitter = (input) =>
   unusedDependencies(input, input.dependencies);

package/src/findings/emitter.ts

@@ -11,7 +11,7 @@ import type { SelfCheckFacts } from "./self-check.ts";
 
 /**
  * What every emitter reads: the configuration the run resolved, the run's sweep, and
- * the facts about the run each kind family reads beside the sweep.
+ * the facts about the run each emitter reads beside the sweep.
  */
 export interface EmitterInput {
   readonly config: Config;
@@ -29,18 +29,17 @@ export interface EmitterInput {
   readonly files: FileFacts;
   /** What can reach the target from outside it: consumers, declared edges, and `exports`. */
   readonly boundary: Boundary;
-  /** The run's suppression outcomes and configured roots, which the self-check family reports. */
+  /** The run's suppression outcomes and configured roots, which the configuration family reports. */
   readonly selfCheck: SelfCheckFacts;
-  /** The parts of the run's declarations, which the intra-function family reports. */
+  /** The parts of the run's declarations, which the inside-functions family reports. */
   readonly intraFunction: IntraFunctionFacts;
 }
 
 /**
- * One kind family's rule over one run: every finding of the codes in its family's range
- * of the Contract's code space, whatever severity and minimum confidence the
- * configuration sets, in no particular order.
+ * One emitter's rule over one run: every finding of the codes it reports, whatever
+ * severity and minimum confidence the configuration sets, in no particular order.
  */
 export type Emitter = (input: EmitterInput) => readonly Finding[];
 
-/** The emitter of each kind family, by the family's name in the Contract, in code order. */
+/** Every emitter this analyzer runs, by the name its tests select it by. */
 export type Emitters = ReadonlyMap<string, Emitter>;

package/src/findings/emitters.ts

@@ -1,4 +1,4 @@
-import type { Confidence } from "../config.ts";
+import type { Confidence } from "../contract/contract.generated.ts";
 import { evaluateEdges, type EdgeEvaluation } from "../edges.ts";
 import type { CompletedFinding } from "../finding.ts";
 import { liveFilesAt } from "../matrix.ts";
@@ -16,7 +16,7 @@ import { selfCheck } from "./self-check.ts";
 import { fallenMembers, unusedDeclarations } from "./unused-declarations.ts";
 import { visibilityNarrowing } from "./visibility-narrowing.ts";
 
-/** Every kind family this analyzer reports, each by its emitter, in code order. */
+/** Every emitter this analyzer runs, by the name its tests select it by. */
 export const EMITTERS: Emitters = new Map<string, Emitter>([
   ["unused-declarations", unusedDeclarations],
   ["visibility-narrowing", visibilityNarrowing],
@@ -76,7 +76,7 @@ interface Suppressed {
 
 /** What the emitter table answers about one run. */
 interface DecidedFindings {
-  /** Every finding the run reports, each family's in table order. */
+  /** Every finding the run reports, each emitter's in table order. */
   readonly findings: readonly CompletedFinding[];
   /** One evaluation per declared edge side of this language, ordered by edge, then by side. */
   readonly evaluations: readonly EdgeEvaluation<CompletedFinding>[];
@@ -91,7 +91,7 @@ interface DecidedFindings {
 /** How many findings the minimum confidence withheld at each confidence. */
 export type Withheld = Readonly<Record<Confidence, number>>;
 
-/** Every family's findings over one sweep, and those of any further emitter, completed by one step. */
+/** Every emitter's findings over one sweep, and those of any further emitter, completed by one step. */
 function completedOver(
   input: EmitterInput,
   ...more: readonly Emitter[]
@@ -124,8 +124,8 @@ function dialsOver(
 
 /**
  * Every finding of one run swept under its suppressions' marks, decided in one pass: each
- * family's findings completed by one step, so every component number is minted once, the
- * finding each record claims withheld, the rest withheld by the dials, so a root one family
+ * emitter's findings completed by one step, so every component number is minted once, the
+ * finding each record claims withheld, the rest withheld by the dials, so a root one emitter
  * reports withholds what another reports in its component, and every declared edge
  * evaluated over what remains, so a pending finding is in its evaluation alone.
  */