@cplieger/deadset-ts 8.0.0-dev.2 → 8.0.0-dev.21

package/src/file-facts.ts

@@ -5,12 +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 { packageScope } from "./load/package-scope.ts";
 import { dirnamePath, joinPath, relativePath, resolvePath } from "./paths.ts";
 import { renderRef } from "./ref.ts";
 import type { ProjectView } from "./session.ts";
+import type { UnseenLoad } from "./roots/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;
@@ -51,6 +52,13 @@ export interface FileFacts {
   readonly generated?: ReadonlySet<string>;
   /** The property names an `in` expression of a production file tests by a literal. */
   readonly inOperands?: ReadonlySet<string>;
+  /** The loads of production files whose target the analysis cannot resolve. */
+  readonly unseenLoads?: readonly UnseenLoad[];
+  /**
+   * The directories below the target root, `.` for the root, of the packages a command of
+   * which may run a file whose path no word of it writes (`roots.13`).
+   */
+  readonly unwrittenRuns?: ReadonlySet<string>;
 }
 
 /** The line of the last character of one text, counted from one; an empty text is one line. */
@@ -71,29 +79,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 { Relation } from "./liveness/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/boundary.ts

@@ -1,3 +1,5 @@
+import type { Carriers } from "../exposure.ts";
+
 /** Which side of a declared cross-language edge, as the edges document spells it. */
 export type EdgeSideName = "provides" | "used_by";
 
@@ -25,4 +27,13 @@ export interface Boundary {
   readonly encapsulated: boolean;
   /** Every side of a declared cross-language edge that names a symbol of this language. */
   readonly edges: readonly EdgeSide[];
+  /** The members a function outside the analysis fills, which it may read unseen. */
+  readonly filledOutside?: ReadonlySet<string>;
+  /** The files and declarations only a bundler's retry of an import Node leaves unresolved names. */
+  readonly possiblyLoaded?: ReadonlySet<string>;
+  /**
+   * The types of the target each declaration hands to code that holds its values, which a
+   * reference from outside the package reaches through it.
+   */
+  readonly carriers?: Carriers;
 }

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 { componentId, type Component } from "../liveness/components.ts";
+import { deadComponents } from "../liveness/sweep.ts";
+import type { Cascade } from "../config.ts";
 import type { CompletedFinding, Finding, FindingComponent, PositionedSymbol } from "../finding.ts";
-import { OUTSIDE, type Graph } from "../graph.ts";
+import { OUTSIDE, type Graph } from "../liveness/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 { Candidate } from "../liveness/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. */
@@ -66,10 +65,9 @@ function everyDeclaredLoaded(boundary: Boundary): boolean {
  * naming its family, else the code's default.
  */
 function severityOf(input: EmitterInput, code: string, fallback: Severity): Severity {
-  const { config } = input;
-  return (
-    config.severity.get(code) ?? config.severity.get(code.slice(0, FAMILY_KEY_LENGTH)) ?? fallback
-  );
+  const { severity } = input.config;
+  const key = [code, code.slice(0, FAMILY_KEY_LENGTH)].find((one) => Object.hasOwn(severity, one));
+  return key === undefined ? fallback : (severity[key] ?? fallback);
 }
 
 /**
@@ -112,10 +110,13 @@ function testedByIn(input: EmitterInput): ReadonlySet<string> {
  * published API, a public member of a published type included, is `certain` where the
  * run loaded every consumer the scope declared and declared one, `probable` where one did
  * not load, and `possible` where it declared none, whatever the configuration says of the
- * consumer set. A member an `in` expression tests by name is `possible`.
+ * consumer set. A member an `in` expression tests by name, one a function outside the
+ * analysis fills, and one {@link possiblyLoaded} names, is `possible`.
  */
-function reachabilityClasses(input: EmitterInput): (id: string) => Confidence {
+export function reachabilityClasses(input: EmitterInput): (id: string) => Confidence {
   const tested = testedByIn(input);
+  const filled = input.boundary.filledOutside ?? new Set<string>();
+  const possible = possiblyLoaded(input);
   const published = publishedIds(input.swept.matrix.union);
   const { declared } = input.boundary.consumers;
   const outside: Confidence =
@@ -125,7 +126,7 @@ function reachabilityClasses(input: EmitterInput): (id: string) => Confidence {
         ? "certain"
         : "probable";
   return (id) => {
-    if (tested.has(id)) {
+    if (tested.has(id) || filled.has(id) || possible.has(id)) {
       return "possible";
     }
     return published.has(id) ? outside : "certain";
@@ -168,9 +169,39 @@ function testCeilings(
       : "certain";
 }
 
+/**
+ * What only a bundler's retry of an import Node leaves unresolved names (program.38), and each
+ * dead declaration that reaches through dead declarations, as confidence.20 reads what only
+ * tests reach: each is dead only while no loader the analysis does not see loads the file.
+ */
+function possiblyLoaded(input: EmitterInput): ReadonlySet<string> {
+  const seeds = input.boundary.possiblyLoaded ?? new Set<string>();
+  if (seeds.size === 0) {
+    return seeds;
+  }
+  const union = input.swept.matrix.union;
+  const dead = new Set(input.swept.sweep.candidates.map((one) => one.id));
+  const reached = new Set<string>();
+  const pending = union.symbols.flatMap((symbol, at) => (seeds.has(symbol.id) ? [at] : []));
+  for (let at = pending.pop(); at !== undefined; at = pending.pop()) {
+    const symbol = union.symbols[at];
+    if (symbol === undefined || reached.has(symbol.id)) {
+      continue;
+    }
+    reached.add(symbol.id);
+    for (const edge of union.out[at] ?? []) {
+      const to = union.symbols[edge.to];
+      if (to !== undefined && dead.has(to.id)) {
+        pending.push(edge.to);
+      }
+    }
+  }
+  return reached;
+}
+
 /**
  * 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.
  */
@@ -197,17 +228,21 @@ function testUsedSubjects(input: EmitterInput): {
 
 /**
  * The ceiling the roots the run found put on one dead subject: a subject other declarations
- * reference, found dead only because no root reaches them, is `probable` unless
- * the configuration declares the roots complete, because a root the analysis cannot see
- * would make it live; every other declaration has none below `certain`.
+ * reference, found dead only because no root reaches them, is `probable` unless the
+ * configuration declares the roots complete and no configuration holding the subject loads
+ * a module the analysis cannot resolve, because a root the analysis cannot see would make
+ * it live; every other declaration has none below `certain`.
  */
 function rootsCeiling(
   input: EmitterInput,
   finding: Finding,
   candidate: Candidate | undefined,
+  configurations: readonly string[],
 ): Confidence {
   const unreachable = candidate?.relation === "reachability" || finding.unreachableOnly === true;
-  return unreachable && !input.config.ts.rootsComplete ? "probable" : "certain";
+  const unseen = new Set((input.files.unseenLoads ?? []).map((load) => load.configuration));
+  const complete = input.config.ts.roots_complete && !configurations.some((one) => unseen.has(one));
+  return unreachable && !complete ? "probable" : "certain";
 }
 
 /**
@@ -225,9 +260,28 @@ function findingComponents(
       held.set(member, component);
     }
   }
+  const listed = membersListed(swept);
+  return (id) => {
+    const component = held.get(id);
+    return component === undefined
+      ? undefined
+      : {
+          id: component.id,
+          root: component.roots.includes(id),
+          symbolCount: component.members.length,
+          deletableLines: component.deletableLines,
+          ...(cascade === "full" ? { members: listed(component.members) } : {}),
+        };
+  };
+}
+
+/** The members of a component as the run lists them, positioned and in the canonical order. */
+function membersListed(
+  swept: RunSweep,
+): (members: readonly string[]) => readonly PositionedSymbol[] {
   const symbols = new Map(swept.matrix.union.symbols.map((symbol) => [symbol.id, symbol]));
-  const listed = (component: Component): readonly PositionedSymbol[] =>
-    component.members
+  return (members) =>
+    members
       .flatMap((member) => {
         const symbol = symbols.get(member);
         return symbol === undefined
@@ -244,22 +298,10 @@ function findingComponents(
             ];
       })
       .sort((a, b) => byPosition(a.position, b.position));
-  return (id) => {
-    const component = held.get(id);
-    return component === undefined
-      ? undefined
-      : {
-          id: component.id,
-          root: component.roots.includes(id),
-          symbolCount: component.members.length,
-          deletableLines: component.deletableLines,
-          ...(cascade === "full" ? { members: listed(component) } : {}),
-        };
-  };
 }
 
 /**
- * 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.
  */
@@ -273,7 +315,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) =>
@@ -348,6 +390,9 @@ export function completed(
     union.symbols.map((symbol, at) => [declarationKey(symbol.ref, symbol.position.path), at]),
   );
   const candidates = new Map(swept.sweep.candidates.map((candidate) => [candidate.id, candidate]));
+  const fileIds = new Map(
+    union.symbols.flatMap((one) => (one.kind === "file" ? [[one.position.path, one.id]] : [])),
+  );
   const classOf = reachabilityClasses(input);
   const ceilingOf = testCeilings(input, classOf);
   const testUsed = testUsedSubjects(input);
@@ -357,12 +402,13 @@ export function completed(
   // A join keeps its first component's identifier, so a minted one counts past every computed one.
   let minted = computed;
   const dead = new Set(components.map((component) => component.id));
-  const fallingWith = new Map<string, number>();
-  for (const { heldByTests } of swept.sweep.candidates) {
+  const fallingWith = new Map<string, string[]>();
+  for (const { id, heldByTests } of swept.sweep.candidates) {
     if (heldByTests !== undefined) {
-      fallingWith.set(heldByTests, (fallingWith.get(heldByTests) ?? 0) + 1);
+      fallingWith.set(heldByTests, [...(fallingWith.get(heldByTests) ?? []), id]);
     }
   }
+  const listed = membersListed(swept);
 
   const done = findings.map((finding): CompletedFinding => {
     const row = kinds.get(finding.code);
@@ -391,7 +437,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 }
@@ -413,11 +459,25 @@ export function completed(
     let component = found;
     if (component === undefined) {
       minted += 1;
+      const falling = symbol?.kind === "interface" ? fallingWith.get(symbol.id) : undefined;
       component = {
         id: componentId(minted),
         root: true,
-        symbolCount: symbol?.kind === "interface" ? (fallingWith.get(symbol.id) ?? 1) : 1,
+        symbolCount: falling?.length ?? 1,
         deletableLines: 0,
+        ...(input.config.reporters.cascade !== "full"
+          ? {}
+          : falling === undefined
+            ? {
+                members: [
+                  {
+                    ref: finding.symbol.ref,
+                    name: finding.symbol.name,
+                    position: finding.position,
+                  },
+                ],
+              }
+            : { members: listed(falling) }),
       };
     }
     const counts =
@@ -425,14 +485,27 @@ export function completed(
         ? union.made[at]
         : { production: candidate.productionRefs, test: candidate.testRefs };
     const ownClass =
-      judged === undefined ? (finding.reachabilityClass ?? "certain") : classOf(judged.id);
+      judged !== undefined
+        ? classOf(judged.id)
+        : (finding.reachabilityClass ??
+          (finding.code === CODE.fileNeverImported
+            ? classOf(fileIds.get(finding.position.path) ?? "")
+            : "certain"));
     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 ??
+      (judged === undefined && !part
+        ? swept.matrix.configurations
+        : (swept.matrix.heldIn[at] ?? swept.matrix.configurations));
     const untested = capped(
-      capped(capped(ownClass, row.maxClass), rootsCeiling(input, finding, candidate)),
+      capped(
+        capped(ownClass, row.maxClass),
+        rootsCeiling(input, finding, candidate, configurations),
+      ),
       judged === undefined ? "certain" : ceilingOf(judged.id),
     );
     const generated = input.files.generated?.has(finding.position.path) === true;
@@ -449,7 +522,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 {
@@ -466,11 +539,7 @@ export function completed(
       generated,
       component,
       retainedBy: [],
-      configurations:
-        candidate?.configurations ??
-        (judged === undefined && !part
-          ? swept.matrix.configurations
-          : (swept.matrix.heldIn[at] ?? swept.matrix.configurations)),
+      configurations,
       consumersLoaded: input.boundary.consumers.loaded,
       fixability,
       severity: severityOf(input, finding.code, row.defaultSeverity),
@@ -540,7 +609,7 @@ export function dialsOf(
   input: EmitterInput,
   findings: readonly CompletedFinding[],
 ): Dials<CompletedFinding> {
-  const minConfidence = input.config.analysis.minConfidence;
+  const minConfidence = input.config.analysis.min_confidence;
   const components = new Set(
     findings
       .filter(

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

@@ -1,9 +1,9 @@
 import type { RunSweep } from "../analysis.ts";
-import type { Config } from "../config.ts";
+import type { ResolvedConfig } from "../config.ts";
 import type { Dependencies } from "../dependencies.ts";
 import type { FileFacts } from "../file-facts.ts";
 import type { Finding } from "../finding.ts";
-import type { Implementations } from "../implementations.ts";
+import type { Implementations } from "./implementations.ts";
 import type { IntraFunctionFacts } from "../intra-function-parts.ts";
 import type { Stores } from "../stores.ts";
 import type { Boundary } from "./boundary.ts";
@@ -11,10 +11,10 @@ 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;
+  readonly config: ResolvedConfig;
   /** The production sweep a report is built from, beside the matrix it judged. */
   readonly swept: RunSweep;
   /** The declarations carrying the deprecation marker in any configuration of the run. */
@@ -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>;