@cplieger/deadset-ts 3.12.1 → 4.0.0

package/src/enum-group.ts

@@ -33,7 +33,8 @@ import { aliasChains } from "./alias-chain.ts";
 import type { DetectorInput, Evidence } from "./exempt.ts";
 import { nodeKey } from "./inventory.ts";
 import { renderPosition } from "./position.ts";
-import { DEFAULT_BATCH_CAP } from "./references.ts";
+import { isAnswered, UNANSWERED, type Answer } from "./query.ts";
+import type { ProjectView } from "./session.ts";
 
 /** The operand types a conversion produces an enum value from. */
 const NUMBER = TypeFlags.NumberLike;
@@ -146,25 +147,38 @@ function sitesOf(file: SourceFile): readonly Site[] {
  * union, and itself otherwise. An enum's own value, or one of its members, is a value the
  * source names, whichever number or string it also is.
  */
-function partsOf(type: Type): readonly Type[] {
-  const parts = type.isUnionType() ? type.getTypes() : [type];
-  return parts.filter((part) => (part.flags & TypeFlags.EnumLike) === 0);
+function partsOf<Brand>(project: ProjectView<Brand>, type: Type): Answer<readonly Type[]> {
+  const parts = type.isUnionType() ? project.queries.constituents(type) : [type];
+  return isAnswered(parts)
+    ? parts.filter((part) => (part.flags & TypeFlags.EnumLike) === 0)
+    : parts;
 }
 
+/** The detail a site records whose operand's type the checker could not answer. */
+const UNTYPED_DETAIL = "converted from a value of unanswered type";
+
 /**
  * The detail one site records about the enum it produces, or undefined where the
  * operand's type converts nothing: a number, or a string an assertion converts, is
  * converted, a value of type `any` or `unknown` is decoded, and a value of an enum is one
  * the source names.
  */
-function detailOf(site: Site, enumName: string, operand: Type | undefined): string | undefined {
+function detailOf<Brand>(
+  project: ProjectView<Brand>,
+  site: Site,
+  enumName: string,
+  operand: Answer<Type> | undefined,
+): string | undefined {
   if (site.form === "lookup") {
     return `looked up by an element access on ${enumName}`;
   }
   if (operand === undefined) {
     return undefined;
   }
-  const parts = partsOf(operand);
+  const parts = operand === UNANSWERED ? UNANSWERED : partsOf(project, operand);
+  if (parts === UNANSWERED) {
+    return UNTYPED_DETAIL;
+  }
   if (parts.some((part) => (part.flags & NUMBER) !== 0)) {
     return "converted from number";
   }
@@ -204,35 +218,37 @@ export function enumGroup<Brand>(input: DetectorInput<Brand>): readonly Evidence
   }
 
   const sites = files.flatMap(sitesOf);
-  const named = new Map<Site, string>();
+  const named = new Map<Site, readonly string[]>();
   const chains = aliasChains(project, held);
-  for (let from = 0; from < sites.length; from += DEFAULT_BATCH_CAP) {
-    const run = sites.slice(from, from + DEFAULT_BATCH_CAP);
-    project.symbolsAt(run.map((site) => project.handle(site.name))).forEach((symbol, index) => {
-      const site = run[index];
-      if (symbol === undefined || site === undefined) {
-        return;
-      }
-      const target = chains.chainOf(symbol).find((link) => enums.has(link.id));
-      if (target !== undefined) {
-        named.set(site, target.id);
+  // A name the checker could not resolve may stand for any enum of the target it spells.
+  const enumsNamed = (text: string): readonly string[] =>
+    [...enums].flatMap(([id, name]) => (name === text ? [id] : []));
+  project.symbolsAt(sites.map((site) => project.handle(site.name))).forEach((symbol, index) => {
+    const site = sites[index];
+    if (symbol === undefined || site === undefined) {
+      return;
+    }
+    if (symbol === UNANSWERED) {
+      const ids = enumsNamed(site.name.getText());
+      if (ids.length > 0) {
+        named.set(site, ids);
       }
-    });
-  }
+      return;
+    }
+    const target = chains.chainOf(symbol).find((link) => enums.has(link.id));
+    if (target !== undefined) {
+      named.set(site, [target.id]);
+    }
+  });
 
   const typed = sites.filter((site) => named.has(site) && site.operand !== undefined);
-  const operandType = new Map<Site, Type>();
-  for (let from = 0; from < typed.length; from += DEFAULT_BATCH_CAP) {
-    const run = typed.slice(from, from + DEFAULT_BATCH_CAP);
-    project.checker
-      .getTypeAtLocation(run.map((site) => site.operand ?? site.at))
-      .forEach((type, index) => {
-        const site = run[index];
-        if (type !== undefined && site !== undefined) {
-          operandType.set(site, type);
-        }
-      });
-  }
+  const operandType = new Map<Site, Answer<Type>>();
+  project.queries.typesAt(typed.map((site) => site.operand ?? site.at)).forEach((type, index) => {
+    const site = typed[index];
+    if (type !== undefined && site !== undefined) {
+      operandType.set(site, type);
+    }
+  });
 
   const members = new Map<string, string[]>();
   for (const symbol of held.symbols) {
@@ -248,17 +264,15 @@ export function enumGroup<Brand>(input: DetectorInput<Brand>): readonly Evidence
 
   const found: Evidence[] = [];
   for (const site of sites) {
-    const enumId = named.get(site);
-    if (enumId === undefined) {
-      continue;
-    }
-    const detail = detailOf(site, enums.get(enumId) ?? "", operandType.get(site));
-    if (detail === undefined) {
-      continue;
-    }
-    const position = renderPosition(site.at.getSourceFile(), targetRoot, site.at.getStart());
-    for (const id of members.get(enumId) ?? []) {
-      found.push({ id, detail, site: position });
+    for (const enumId of named.get(site) ?? []) {
+      const detail = detailOf(project, site, enums.get(enumId) ?? "", operandType.get(site));
+      if (detail === undefined) {
+        continue;
+      }
+      const position = renderPosition(site.at.getSourceFile(), targetRoot, site.at.getStart());
+      for (const id of members.get(enumId) ?? []) {
+        found.push({ id, detail, site: position });
+      }
     }
   }
   return found;

package/src/exempt.ts

@@ -18,9 +18,10 @@ import {
   type TSExemptionClass,
   type TypeScriptVisibility,
 } from "./exempt-classes.ts";
-import type { Inventory, InventorySymbol, Visibility } from "./inventory.ts";
+import type { Inventory, InventorySymbol, SymbolKind, 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 Mode, type SweepInput } from "./sweep.ts";
@@ -100,6 +101,53 @@ 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 detail of a record a detector that could not finish holds. */
+const UNANSWERED_DETAIL = "kept live by a question the checker did not answer";
+
+/** Whether one record is held by a detector that could not finish. */
+export function isUnansweredRecord(record: Exemption): boolean {
+  return record.detail === UNANSWERED_DETAIL;
+}
+
+/**
+ * What one detector holds back over one project. A detector that stops because the
+ * checker left a question it needs unanswered holds back every declaration of the
+ * project its class could hold back, each recorded at its own position, so the gap
+ * never yields a finding.
+ */
+function detected<Brand>(
+  exemptionClass: TSExemptionClass,
+  detect: Detector,
+  input: DetectorInput<Brand>,
+): readonly Evidence[] {
+  try {
+    return detect(input);
+  } catch (error: unknown) {
+    if (!(error instanceof Unanswerable)) {
+      throw error;
+    }
+    const kinds = RETAINABLE.get(exemptionClass);
+    return input.held.symbols
+      .filter((symbol) => (kinds === undefined ? symbol.kind !== "file" : kinds.has(symbol.kind)))
+      .map((symbol) => ({ id: symbol.id, detail: UNANSWERED_DETAIL, site: symbol.position }));
+  }
+}
+
 /**
  * The records one project's detectors found, each class in the vocabulary's order and
  * none of a switched-off class. Evidence on a private member the class's row says it
@@ -120,7 +168,7 @@ export function computeExemptions<Brand>(
       continue;
     }
     const allowed = typescriptVisibilityOf(exemptionClass);
-    for (const evidence of detect(input)) {
+    for (const evidence of detected(exemptionClass, detect, input)) {
       if (!retainable(allowed, visibility.get(evidence.id))) {
         continue;
       }

package/src/finding.ts

@@ -55,7 +55,7 @@ export interface FindingDetails {
   readonly narrowerVisibility?: "file" | "package";
   /** On `DS1201` and `DS1203`: the classes implementing the interface, in site order. */
   readonly implementations?: readonly PositionedSymbol[];
-  /** On `DS1301`: every position the subject is written at, in site order. */
+  /** On `DS1301` and `DS1807`: every position the subject is written at, in site order. */
   readonly writePositions?: readonly FindingPosition[];
   /** On `DS1601`: the manifest section that declares the dependency. */
   readonly dependencyClass?: DependencySection;
@@ -63,6 +63,8 @@ export interface FindingDetails {
   readonly mechanism?: Mechanism;
   /** On `DS1701` and `DS1702`: 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[];
 }
 
 /** One suppression in the four-member form the ignore file and the baseline share. */
@@ -91,6 +93,8 @@ export interface FindingComponent {
   /** The number of the component's members. */
   readonly symbolCount: number;
   readonly deletableLines: number;
+  /** Every member, the subject included, where the run lists a component in full. */
+  readonly members?: readonly PositionedSymbol[];
 }
 
 /** One finding with every member the finding schema requires. */

package/src/findings/completion.ts

@@ -6,12 +6,13 @@
 
 import type { RunSweep } from "../analysis.ts";
 import { componentId, type Component } from "../components.ts";
-import type { Confidence, Severity } from "../config.ts";
-import type { CompletedFinding, Finding, FindingComponent } from "../finding.ts";
+import type { Cascade, Confidence, Severity } from "../config.ts";
+import type { CompletedFinding, Finding, FindingComponent, PositionedSymbol } from "../finding.ts";
 import { OUTSIDE } from "../graph.ts";
 import { KINDS, type KindRow } from "../kinds.ts";
+import { byPosition } from "../position.ts";
 import { FAMILY_KEY_LENGTH } from "../resolve.ts";
-import { isRowSubject, type Dials } from "../suppress.ts";
+import { isPartSubject, isRowSubject, type Dials } from "../suppress.ts";
 import type { Boundary } from "./boundary.ts";
 import type { EmitterInput } from "./emitter.ts";
 
@@ -83,14 +84,42 @@ function reachabilityClasses(input: EmitterInput): (id: string) => Confidence {
   return (id) => (published.has(id) ? outside : "certain");
 }
 
-/** The component each dead declaration of the run falls in, and none for a live one. */
-function findingComponents(swept: RunSweep): (id: string) => FindingComponent | undefined {
+/**
+ * The component each dead declaration of the run falls in, and none for a live one, with
+ * its members listed in the canonical order where the run lists a component in full.
+ */
+function findingComponents(
+  swept: RunSweep,
+  cascade: Cascade,
+): (id: string) => FindingComponent | undefined {
   const held = new Map<string, Component>();
   for (const component of swept.sweep.components) {
     for (const member of component.members) {
       held.set(member, component);
     }
   }
+  const symbols = new Map(swept.matrix.union.symbols.map((symbol) => [symbol.id, symbol]));
+  const listed = (component: Component): readonly PositionedSymbol[] =>
+    component.members
+      .flatMap((member) => {
+        const symbol = symbols.get(member);
+        return symbol === undefined
+          ? []
+          : [
+              {
+                ref: symbol.ref,
+                name: symbol.name,
+                position: {
+                  ...symbol.position,
+                  endLine: Math.max(symbol.position.line, symbol.endLine),
+                },
+              },
+            ];
+      })
+      .sort(
+        (a, b) =>
+          byPosition(a.position, b.position) || (a.ref === b.ref ? 0 : a.ref < b.ref ? -1 : 1),
+      );
   return (id) => {
     const component = held.get(id);
     return component === undefined
@@ -100,6 +129,7 @@ function findingComponents(swept: RunSweep): (id: string) => FindingComponent |
           root: component.roots.includes(id),
           symbolCount: component.members.length,
           deletableLines: component.deletableLines,
+          ...(cascade === "full" ? { members: listed(component) } : {}),
         };
   };
 }
@@ -123,7 +153,7 @@ export function completed(
   const positions = new Map(union.symbols.map((symbol, at) => [symbol.ref, at]));
   const candidates = new Map(swept.sweep.candidates.map((candidate) => [candidate.id, candidate]));
   const classOf = reachabilityClasses(input);
-  const componentOf = findingComponents(swept);
+  const componentOf = findingComponents(swept, input.config.reporters.cascade);
   let minted = swept.sweep.components.length;
 
   return findings.map((finding): CompletedFinding => {
@@ -136,11 +166,15 @@ export function completed(
     const at = isRowSubject(finding.symbol.kind)
       ? OUTSIDE
       : (positions.get(finding.symbol.ref) ?? OUTSIDE);
+    // A part names the declaration that holds it, and is decided inside it rather than by
+    // the declaration's liveness, so it carries none of the declaration's sweep facts.
+    const part = isPartSubject(finding.symbol.kind);
     const symbol = union.symbols[at];
-    const judged = union.subject[at] === true ? symbol : undefined;
+    const judged = !part && union.subject[at] === true ? symbol : undefined;
     const candidate = judged === undefined ? undefined : candidates.get(judged.id);
-    const found = symbol === undefined ? undefined : componentOf(symbol.id);
-    if (candidate !== undefined && found === undefined) {
+    const found = symbol === undefined || part ? undefined : componentOf(symbol.id);
+    // A test file's declaration is a component member only as a test of dead code.
+    if (candidate !== undefined && found === undefined && union.test[at] !== true) {
       throw new Error(`${candidate.id} is judged dead and falls in no dead component`);
     }
     let component = found;
@@ -173,7 +207,9 @@ export function completed(
       retainedBy: [],
       configurations:
         candidate?.configurations ??
-        (judged === undefined ? swept.matrix.configurations : (swept.matrix.heldIn[at] ?? [])),
+        (judged === undefined && !part
+          ? swept.matrix.configurations
+          : (swept.matrix.heldIn[at] ?? swept.matrix.configurations)),
       consumersLoaded: input.boundary.consumers.loaded,
       fixability: row.fixability,
       severity: severityOf(input, finding.code, row.defaultSeverity),

package/src/findings/emitter.ts

@@ -4,6 +4,7 @@ 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 { IntraFunctionFacts } from "../intra-function-parts.ts";
 import type { Stores } from "../stores.ts";
 import type { Boundary } from "./boundary.ts";
 import type { SelfCheckFacts } from "./self-check.ts";
@@ -30,6 +31,8 @@ export interface EmitterInput {
   readonly boundary: Boundary;
   /** The run's suppression outcomes and configured roots, which the self-check family reports. */
   readonly selfCheck: SelfCheckFacts;
+  /** The parts of the run's declarations, which the intra-function family reports. */
+  readonly intraFunction: IntraFunctionFacts;
 }
 
 /**

package/src/findings/emitters.ts

@@ -9,7 +9,7 @@ import { intraFunction } from "./intra-function.ts";
 import { nonCodeArtifacts } from "./non-code-artifacts.ts";
 import { readsAndWrites } from "./reads-and-writes.ts";
 import { selfCheck } from "./self-check.ts";
-import { unusedDeclarations } from "./unused-declarations.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. */
@@ -24,6 +24,22 @@ export const EMITTERS: Emitters = new Map<string, Emitter>([
   ["intra-function", intraFunction],
 ]);
 
+/**
+ * The references of every declaration an unanswered question could have kept live, which
+ * the run reports nothing about: a finding about one would be computed from the gap.
+ */
+function heldRefs(input: EmitterInput): ReadonlySet<string> {
+  const held = new Set(input.swept.heldByUnanswered);
+  if (held.size === 0) {
+    return held;
+  }
+  return new Set(
+    input.swept.matrix.union.symbols
+      .filter((symbol) => held.has(symbol.id))
+      .map((symbol) => symbol.ref),
+  );
+}
+
 /** What the suppressions of a run swept under their marks are decided against. */
 export interface Suppressed {
   /** The same run swept with no mark, which is where a kind about liveness reports a marked declaration. */
@@ -44,11 +60,14 @@ export interface DecidedFindings {
   readonly would: readonly CompletedFinding[];
 }
 
-/** Every family's findings over one sweep, completed by one step. */
-function completedOver(input: EmitterInput): readonly CompletedFinding[] {
+/** Every family's findings over one sweep, and those of any further emitter, completed by one step. */
+function completedOver(
+  input: EmitterInput,
+  ...more: readonly Emitter[]
+): readonly CompletedFinding[] {
   return completed(
     input,
-    [...EMITTERS.values()].flatMap((emit) => emit(input)),
+    [...EMITTERS.values(), ...more].flatMap((emit) => emit(input)),
   );
 }
 
@@ -85,12 +104,14 @@ export function decidedFindings(
   suppressed: Suppressed = { unmarked: input, records: [] },
 ): DecidedFindings {
   const found = completedOver(input);
-  const unmarked = suppressed.records.length === 0 ? [] : completedOver(suppressed.unmarked);
+  const unmarked =
+    suppressed.records.length === 0 ? [] : completedOver(suppressed.unmarked, fallenMembers);
   const would = [...unmarked, ...found];
   const ledger = ledgerOf(suppressed.records, would, dialsOver(input, found, suppressed, unmarked));
+  const unanswered = heldRefs(input);
   const kept = reportable(
     input,
-    found.filter((finding) => !ledger.withheld(finding)),
+    found.filter((finding) => !ledger.withheld(finding) && !unanswered.has(finding.symbol.ref)),
   );
   const evaluated = evaluateEdges(kept, input.boundary.edges, input.swept.matrix.union.symbols);
   return {

package/src/findings/interfaces.ts

@@ -131,8 +131,14 @@ function unusedMessage(candidate: Candidate): string {
     : UNUSED_MESSAGE;
 }
 
-/** Whether one interface method has implementations and every one has an empty body. */
+/**
+ * Whether one interface method has implementations and every one has an empty body, or
+ * is one whose implementations the run could not read in full.
+ */
 function marker(input: EmitterInput, method: string): boolean {
+  if (input.implementations.unknown.has(method)) {
+    return true;
+  }
   const bodies = [...(input.implementations.bodies.get(method)?.values() ?? [])];
   return bodies.length > 0 && bodies.every((empty) => empty);
 }

package/src/findings/intra-function.ts

@@ -1,4 +1,107 @@
-import type { Emitter } from "./emitter.ts";
+import type { Finding } from "../finding.ts";
+import { KINDS } from "../kinds.ts";
+import { UNUSED_PARAMETER, UNUSED_RESULT, type PartFact } from "../intra-function-parts.ts";
+import type { Emitter, EmitterInput } from "./emitter.ts";
 
-/** The findings of the intra-function family, `DS1800` to `DS1899`. */
-export const intraFunction: Emitter = () => [];
+/** A list of rules as a sentence names them. */
+function spelled(rules: readonly string[]): string {
+  if (rules.length < 2) {
+    return rules.join("");
+  }
+  return `${rules.slice(0, -1).join(", ")} and ${rules.at(-1) ?? ""}`;
+}
+
+/** The clause a message ends with: the other rules that report the kind, or that none is known. */
+function overlapClause(overlap: readonly string[]): string {
+  return overlap.length === 1 && overlap[0] === "none known"
+    ? "no other rule is known to report it"
+    : `also reported by ${spelled(overlap)}`;
+}
+
+/**
+ * Whether one part is reported. A parameter needs its function's signature free to
+ * change; a result needs that, every call in the loaded program to discard it, and every
+ * call site to be in the loaded program, so a function with a root or one a module
+ * exports to callers the run cannot see has no result to report. Every other part is
+ * reported wherever no project found it in use.
+ */
+function reported(
+  input: EmitterInput,
+  part: PartFact,
+  callersUnknown: ReadonlySet<string>,
+): boolean {
+  if (part.used) {
+    return false;
+  }
+  const { free, discardedEverywhere } = input.intraFunction;
+  switch (part.code) {
+    case UNUSED_PARAMETER:
+      return free.has(part.declaration);
+    case UNUSED_RESULT:
+      return (
+        free.has(part.declaration) &&
+        discardedEverywhere.has(part.declaration) &&
+        !callersUnknown.has(part.declaration)
+      );
+    default:
+      return true;
+  }
+}
+
+/**
+ * The findings of the intra-function family, `DS1800` to `DS1899`, each about a part of
+ * the declaration its reference names, at the part's own position, whatever the sweep
+ * decided about that declaration. Each message names the other rules that report the
+ * kind, as the vocabulary lists them, and so does the finding's details.
+ */
+export const intraFunction: Emitter = (input) => {
+  const union = input.swept.matrix.union;
+  const byId = new Map(union.symbols.map((symbol) => [symbol.id, symbol]));
+  const unknown = new Set(
+    union.rooted.flatMap((root) => {
+      const symbol = union.symbols[root.at];
+      return symbol === undefined ? [] : [symbol.id];
+    }),
+  );
+  const { declared, loaded } = input.boundary.consumers;
+  const closed = input.config.consumersComplete && declared.every((id) => loaded.includes(id));
+  const published = (id: string): boolean => {
+    const symbol = byId.get(id);
+    return (
+      symbol !== undefined &&
+      symbol.kind !== "file" &&
+      (symbol.exported || published(symbol.parent))
+    );
+  };
+  if (!closed) {
+    for (const part of input.intraFunction.parts) {
+      if (published(part.declaration)) {
+        unknown.add(part.declaration);
+      }
+    }
+  }
+  const found: Finding[] = [];
+  for (const part of input.intraFunction.parts) {
+    const declaration = byId.get(part.declaration);
+    const overlap = KINDS.get(part.code)?.overlap ?? [];
+    if (declaration === undefined || !reported(input, part, unknown)) {
+      continue;
+    }
+    found.push({
+      code: part.code,
+      position: part.position,
+      symbol: {
+        ref: declaration.ref,
+        kind: part.kind,
+        name: part.name,
+        sizeLines: part.position.endLine - part.position.line + 1,
+      },
+      message: `${part.message}; ${overlapClause(overlap)}`,
+      details: {
+        ...(part.kind === "store" ? { writePositions: [part.position] } : {}),
+        overlap,
+      },
+    });
+  }
+  return found;
+};

package/src/findings/self-check.ts

@@ -14,6 +14,12 @@ 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";
+
 /** The subject kind of a finding about a suppression record. */
 const SUPPRESSION_SUBJECT = "suppression";
 
@@ -38,6 +44,18 @@ export interface SelfCheckFacts {
   readonly unmatchedRoots: readonly string[];
   /** The document below the target root that declared the roots, empty where none did. */
   readonly rootsDocument: string;
+  /** Every configured declaration that named no declaration in any project, in reading order. */
+  readonly unmatchedDeclarations: readonly UnmatchedDeclaration[];
+}
+
+/** One configured declaration that named nothing, and the document that configured it. */
+interface UnmatchedDeclaration {
+  /** The entry as a finding's subject reference spells it. */
+  readonly ref: string;
+  /** The dotted path of the key that holds the entry. */
+  readonly key: string;
+  /** The document below the target root that declared the key, empty where none did. */
+  readonly document: string;
 }
 
 /** A run with nothing for the self-check family to report. */
@@ -45,6 +63,7 @@ export const NO_SELF_CHECK: SelfCheckFacts = {
   refusals: [],
   unmatchedRoots: [],
   rootsDocument: "",
+  unmatchedDeclarations: [],
 };
 
 /** The words a message names a mechanism by. */
@@ -188,6 +207,31 @@ export function staleSuppressions(
   });
 }
 
+/** The first position of the document that configured a setting, or of the conventional one. */
+function documentPosition(document: string): Finding["position"] {
+  return {
+    path: document === "" ? REPOSITORY_DOCUMENT : document,
+    line: DOCUMENT_POSITION,
+    column: DOCUMENT_POSITION,
+    endLine: DOCUMENT_POSITION,
+  };
+}
+
+/**
+ * One finding per configured declaration that named no declaration in any project, at the
+ * first position of the document that configured its key, as a configured root's is.
+ */
+function unmatchedDeclarationFindings(
+  unmatched: readonly UnmatchedDeclaration[],
+): readonly Finding[] {
+  return unmatched.map((one) => ({
+    code: UNMATCHED_DECLARATION,
+    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`,
+  }));
+}
+
 /**
  * One finding per configured root or pattern that named nothing in any project. A finding
  * names the document that declared the roots, or the conventional repository configuration
@@ -199,12 +243,7 @@ export function unmatchedRootFindings(
   sources: readonly string[],
   document: string,
 ): readonly Finding[] {
-  const position = {
-    path: document === "" ? REPOSITORY_DOCUMENT : document,
-    line: DOCUMENT_POSITION,
-    column: DOCUMENT_POSITION,
-    endLine: DOCUMENT_POSITION,
-  };
+  const position = documentPosition(document);
   return sources.map((source) => ({
     code: UNMATCHED_ROOT,
     position,
@@ -218,11 +257,13 @@ export function unmatchedRootFindings(
 
 /**
  * The findings of the self-check family, `DS1700` to `DS1799`: a suppression refused for
- * carrying no reason or naming no path, and a configured root that named nothing. A
+ * 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
  * {@link staleSuppressions} builds, and a stale cross-language edge is the merge's to report.
  */
 export const selfCheck: Emitter = ({ selfCheck: facts, swept }) => [
   ...refusedSuppressions(facts.refusals, fileRefsOf(swept.matrix.union.symbols)),
   ...unmatchedRootFindings(facts.unmatchedRoots, facts.rootsDocument),
+  ...unmatchedDeclarationFindings(facts.unmatchedDeclarations),
 ];