@cplieger/deadset-ts 3.12.0 → 3.13.0

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),
 ];

package/src/findings/unused-declarations.ts

@@ -1,7 +1,7 @@
 import type { Finding } from "../finding.ts";
 import type { InventorySymbol, SymbolKind } from "../inventory.ts";
 import type { MatrixCandidate } from "../matrix.ts";
-import type { Emitter } from "./emitter.ts";
+import type { Emitter, EmitterInput } from "./emitter.ts";
 import { unreachableExports } from "./visibility-narrowing.ts";
 
 /** The kinds of declaration that are members of a class, an interface, a type or an enum. */
@@ -137,7 +137,17 @@ function messageOf(code: string, judged: Judged): string {
 }
 
 /** The findings of the unused-declarations family, `DS1000` to `DS1099`. */
-export const unusedDeclarations: Emitter = (input) => {
+export const unusedDeclarations: Emitter = (input) => familyFindings(input, false);
+
+/**
+ * The finding each member of a dead container would carry were its container live: what
+ * 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);
+
+/** The family's findings, or, where `fallen` is set, its dead containers' members' alone. */
+function familyFindings(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);
@@ -149,11 +159,15 @@ export const unusedDeclarations: Emitter = (input) => {
     if (symbol === undefined) {
       continue;
     }
+    const containerDead = dead.has(symbol.parent);
+    if (fallen !== containerDead) {
+      continue;
+    }
     const judged: Judged = {
       candidate,
       symbol,
       test: union.test[at] === true,
-      containerDead: dead.has(symbol.parent),
+      containerDead: containerDead && !fallen,
       deprecated: input.deprecated.has(symbol.id),
       unreachable: unreachable.has(symbol.id),
     };
@@ -175,4 +189,4 @@ export const unusedDeclarations: Emitter = (input) => {
     });
   }
   return found;
-};
+}

package/src/findings-pass.ts

@@ -122,19 +122,34 @@ export function verdictOf(result: PassResult, config: Config): number {
   return failing ? EXIT_FINDINGS : EXIT_CLEAN;
 }
 
+/** What a baseline row is recorded from: a finding's code, subject and file. */
+export interface RecordableFinding {
+  readonly code: string;
+  readonly symbol: { readonly ref: string; readonly kind: string };
+  readonly position: { readonly path: string };
+}
+
 /**
- * The findings of a report as a baseline records them, in report order. A finding about a
- * row of a document is not recorded: no record withholds one, so a row recording it would
- * be stale on the first read back.
+ * The rows one round of a baseline write records from its findings, in their order. A
+ * finding about a row of a document is not recorded: no record withholds one, so a row
+ * recording it would be stale on the first read back. Two findings that would record the
+ * same row, two parts of one declaration under one code, record it once.
  */
-export function recordedFindings(result: PassResult): readonly Recorded[] {
-  return result.findings
-    .filter((finding) => !isRowSubject(finding.symbol.kind))
-    .map((finding) => ({
-      code: finding.code,
-      symbol: finding.symbol.ref,
-      path: finding.position.path,
-    }));
+export function recordedFindings(findings: readonly RecordableFinding[]): readonly Recorded[] {
+  const rows = new Map<string, Recorded>();
+  for (const finding of findings) {
+    if (isRowSubject(finding.symbol.kind)) {
+      continue;
+    }
+    const row = { code: finding.code, symbol: finding.symbol.ref, path: finding.position.path };
+    rows.set(rowKey(row), rows.get(rowKey(row)) ?? row);
+  }
+  return [...rows.values()];
+}
+
+/** One row's identity: its code, its symbol and its path. */
+export function rowKey(row: Recorded): string {
+  return `${row.code}\u0000${row.symbol}\u0000${row.path}`;
 }
 
 /** The analyzer identity a baseline this analyzer writes names as its rows' provenance. */

package/src/graph.ts

@@ -39,15 +39,15 @@ const SWEPT: Readonly<Record<SymbolKind, boolean>> = {
 
 /**
  * Whether a root of each kind names a caller, which holds it live under both relations: a
- * tool reads the configuration it loads, a runtime runs a test file, a setup file and a
- * worker, and a configured root asserts a caller. The other kinds only suppose a consumer
- * that imports what a manifest entry, a binary or an entry file exports, or names a
- * library's published API, so such a root is live under reachability alone.
+ * tool reads the configuration it loads, a runtime runs a test file, a setup file, a
+ * worker and a command, the manifest names what enters the package, and an entry file, a
+ * configured root and a pattern assert a caller. A library's published API only supposes
+ * a consumer the run may not see, so it is live under reachability alone.
  */
 const NAMES_A_CALLER: Readonly<Record<RootKind, boolean>> = {
-  "entry-file": false,
-  "manifest-entry": false,
-  "manifest-binary": false,
+  "entry-file": true,
+  "manifest-entry": true,
+  "manifest-binary": true,
   "published-api": false,
   configured: true,
   pattern: true,