@cplieger/deadset-ts 4.0.0 → 5.0.0

package/src/findings/completion.ts

@@ -8,7 +8,7 @@ import type { RunSweep } from "../analysis.ts";
 import { componentId, type Component } from "../components.ts";
 import type { Cascade, Confidence, Severity } from "../config.ts";
 import type { CompletedFinding, Finding, FindingComponent, PositionedSymbol } from "../finding.ts";
-import { OUTSIDE } from "../graph.ts";
+import { OUTSIDE, type Graph } from "../graph.ts";
 import { KINDS, type KindRow } from "../kinds.ts";
 import { byPosition } from "../position.ts";
 import { FAMILY_KEY_LENGTH } from "../resolve.ts";
@@ -24,56 +24,47 @@ function capped(found: Confidence, ceiling: Confidence): Confidence {
   return RANK[found] <= RANK[ceiling] ? found : ceiling;
 }
 
-/** The kind whose default turns on what the run knows about the target's consumers. */
-const UNUSED_EXPORTED = "DS1001";
-
 /** Whether the run loaded every consumer the scope declared, which holds of a scope declaring none. */
 function everyDeclaredLoaded(boundary: Boundary): boolean {
   const { declared, loaded } = boundary.consumers;
   return declared.every((id) => loaded.includes(id));
 }
 
-/**
- * Whether a library's published API may have a caller the run cannot see: the target is
- * a library, and the run either holds no consumer information or did not load a consumer
- * the scope declared. A configuration declaring the consumer set complete holds consumer
- * information whether or not it declares a consumer, because it says no other exists.
- */
-function openWorld(input: EmitterInput): boolean {
-  const known = input.config.consumersComplete || input.boundary.consumers.declared.length > 0;
-  return input.config.targetKind === "library" && !(known && everyDeclaredLoaded(input.boundary));
-}
-
 /**
  * The severity the configuration gives one code: the key naming the code, else the key
- * naming its family, else the code's default. The unused-exported kind defaults to
- * `allow` while a library's published API is open to callers the run cannot see.
+ * naming its family, else the code's default.
  */
 function severityOf(input: EmitterInput, code: string, fallback: Severity): Severity {
   const { config } = input;
-  const named = config.severity.get(code) ?? config.severity.get(code.slice(0, FAMILY_KEY_LENGTH));
-  if (named !== undefined) {
-    return named;
-  }
-  return code === UNUSED_EXPORTED && openWorld(input) ? "allow" : fallback;
+  return (
+    config.severity.get(code) ?? config.severity.get(code.slice(0, FAMILY_KEY_LENGTH)) ?? fallback
+  );
 }
 
 /**
- * The reachability class of one declaration of the run. A declaration of a library's
- * published API has callers outside the target: it is `certain` where the run loaded
- * every consumer the scope declared and declared at least one, `probable` where it
- * declared consumers and did not load them all, and `possible` where it declared none.
- * Whether the configuration declares the consumer set complete decides nothing here.
- * Every other declaration has every reference in the loaded program, a private member
- * and a `#private` name among them, and is `certain`.
+ * The declarations the roots name as a library's published API, each public member of a
+ * published type included.
  */
-function reachabilityClasses(input: EmitterInput): (id: string) => Confidence {
-  const union = input.swept.matrix.union;
-  const published = new Set(
+function publishedIds(union: Graph): ReadonlySet<string> {
+  return new Set(
     union.rooted
       .filter((root) => root.kind === "published-api")
-      .map((root) => union.symbols[root.at]?.id),
+      .flatMap((root) => union.symbols[root.at]?.id ?? []),
   );
+}
+
+/**
+ * The reachability class of one declaration of the run. A declaration of a library's
+ * published API, a public member of a published type included, has callers outside the
+ * target: it is `certain` where the run loaded every consumer the scope declared and
+ * declared at least one, `probable` where it declared consumers and did not load them
+ * all, and `possible` where it declared none. Whether the configuration declares the
+ * consumer set complete decides nothing here. Every other declaration has every reference
+ * in the loaded program, a private member and a `#private` name among them, and is
+ * `certain`.
+ */
+function reachabilityClasses(input: EmitterInput): (id: string) => Confidence {
+  const published = publishedIds(input.swept.matrix.union);
   const { declared } = input.boundary.consumers;
   const outside: Confidence =
     declared.length === 0

package/src/findings/emitters.ts

@@ -1,6 +1,8 @@
 import { evaluateEdges, type EdgeEvaluation } from "../edges.ts";
 import type { CompletedFinding } from "../finding.ts";
+import { liveFilesAt } from "../matrix.ts";
 import { ledgerOf, type Dials, type Ledger, type SuppressionRecord } from "../suppress.ts";
+import { insideSkipped } from "../type-errors.ts";
 import { completed, dialsOf, reportable } from "./completion.ts";
 import { dependenciesAndModuleMachinery } from "./dependencies-and-module-machinery.ts";
 import type { Emitter, EmitterInput, Emitters } from "./emitter.ts";
@@ -40,6 +42,28 @@ function heldRefs(input: EmitterInput): ReadonlySet<string> {
   );
 }
 
+/**
+ * The references of every top-level declaration of a live component file. The file's
+ * markup may use each of them, which no analysis of the markup can rule out, so the run
+ * reports nothing about one while the file is live.
+ */
+function markupRefs(input: EmitterInput): ReadonlySet<string> {
+  const { swept } = input;
+  if (swept.componentFiles.length === 0) {
+    return new Set();
+  }
+  const live = new Set(
+    liveFilesAt(swept.matrix, swept.sweep, new Set(swept.componentFiles)).map(
+      (symbol) => symbol.id,
+    ),
+  );
+  return new Set(
+    swept.matrix.union.symbols
+      .filter((symbol) => live.has(symbol.parent))
+      .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. */
@@ -109,9 +133,16 @@ export function decidedFindings(
   const would = [...unmarked, ...found];
   const ledger = ledgerOf(suppressed.records, would, dialsOver(input, found, suppressed, unmarked));
   const unanswered = heldRefs(input);
+  const markup = markupRefs(input);
   const kept = reportable(
     input,
-    found.filter((finding) => !ledger.withheld(finding) && !unanswered.has(finding.symbol.ref)),
+    found.filter(
+      (finding) =>
+        !ledger.withheld(finding) &&
+        !unanswered.has(finding.symbol.ref) &&
+        !markup.has(finding.symbol.ref) &&
+        !insideSkipped(input.swept.skipped, finding.position),
+    ),
   );
   const evaluated = evaluateEdges(kept, input.boundary.edges, input.swept.matrix.union.symbols);
   return {

package/src/findings/unused-declarations.ts

@@ -52,6 +52,8 @@ interface Judged {
   readonly symbol: InventorySymbol;
   /** Whether a test file declares it. */
   readonly test: boolean;
+  /** Whether a test-support file declares it, which test code keeps live. */
+  readonly support: boolean;
   /** Whether its container is itself dead, so it falls with the container. */
   readonly containerDead: boolean;
   readonly deprecated: boolean;
@@ -62,8 +64,9 @@ interface Judged {
 /**
  * The code one candidate is reported under, or none, each symbol once under the most
  * specific code: a test of dead code first; no other test-file declaration, member of a
- * dead container or enum member nothing names; then deprecation, a test reference, and
- * the unreferenced codes, an unimportable unused export being the unreachable kind's.
+ * dead container or enum member nothing names, nor a test-support declaration test code
+ * references; then deprecation, a test reference, and the unreferenced codes, an
+ * unimportable unused export being the unreachable kind's.
  */
 function codeOf(judged: Judged): string | undefined {
   const { candidate, symbol } = judged;
@@ -77,6 +80,9 @@ function codeOf(judged: Judged): string | undefined {
   if (symbol.kind === "enum-member" && !referenced) {
     return undefined;
   }
+  if (judged.support && candidate.testRefs > 0) {
+    return undefined;
+  }
   if (candidate.productionRefs === 0 && judged.deprecated) {
     return "DS1006";
   }
@@ -167,6 +173,7 @@ function familyFindings(input: EmitterInput, fallen: boolean): Finding[] {
       candidate,
       symbol,
       test: union.test[at] === true,
+      support: union.support[at] === true,
       containerDead: containerDead && !fallen,
       deprecated: input.deprecated.has(symbol.id),
       unreachable: unreachable.has(symbol.id),

package/src/graph.ts

@@ -39,20 +39,26 @@ 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, 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
+ * tool reads the configuration it loads and the files its strings name, a runtime runs a
+ * test file, a setup file, a worker, a command and a script, the manifest names what
+ * enters the package, an alias global stands for the export it names, 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": true,
+  convention: true,
   "manifest-entry": true,
   "manifest-binary": true,
+  script: true,
   "published-api": false,
   configured: true,
   pattern: true,
+  "type-error": true,
+  "type-query-alias": true,
+  "configuration-file": true,
+  "configuration-string": true,
   "test-runner": true,
-  "lint-configuration": true,
   "mutation-testing": true,
   "browser-tests": true,
   worker: true,
@@ -103,6 +109,8 @@ export interface Graph {
   readonly parent: readonly number[];
   /** Per declaration, whether a test file holds it. */
   readonly test: readonly boolean[];
+  /** Per declaration, whether a test-support file holds it. */
+  readonly support: readonly boolean[];
   /** Per declaration, whether the sweep judges its liveness. */
   readonly subject: readonly boolean[];
   /**
@@ -135,7 +143,9 @@ export function graphOf(
   references: readonly Reference[],
   roots: readonly Root[],
   testFiles: readonly string[],
+  supportFiles: readonly string[] = [],
 ): Graph {
+  const supports = new Set(supportFiles);
   const index = new Map(symbols.map((symbol, at) => [symbol.id, at]));
   const at = (id: string): number => index.get(id) ?? OUTSIDE;
   const tests = new Set(testFiles);
@@ -187,6 +197,7 @@ export function graphOf(
     made,
     parent,
     test: symbols.map((symbol) => tests.has(symbol.position.path)),
+    support: symbols.map((symbol) => supports.has(symbol.position.path)),
     subject: symbols.map((symbol) => swept(symbol.kind)),
     exportsOf,
     rooted,

package/src/host.ts

@@ -27,6 +27,12 @@ export interface Host {
   readDirectory(path: string): readonly DirectoryEntry[];
   /** What one path names, `"absent"` where nothing is there. */
   kindOf(path: string): PathKind;
+  /**
+   * The path one path names once every symbolic link along it is followed, or a throw
+   * naming why it cannot be: a package manager links an installed workspace package
+   * into `node_modules`, and the link's target is what says which package it is.
+   */
+  realPath(path: string): string;
   /**
    * The version of the package this analyzer was installed from, or a throw
    * naming why it cannot be known. It is a method rather than a value because
@@ -41,4 +47,21 @@ export interface Host {
    * never a part of it.
    */
   writeDocument(path: string, pieces: Iterable<string>): void;
+  /**
+   * A new empty directory of its own, outside every tree the run reads, or a throw naming
+   * why it cannot be made. The run removes it before it ends.
+   */
+  temporaryDirectory(): TemporaryDirectory;
+  /**
+   * The command that runs this analyzer's mapper for component files, under the runtime
+   * the analyzer itself runs under. The compiler starts it to read a component file.
+   */
+  componentMapperCommand(): readonly string[];
+}
+
+/** One directory a run made for itself. */
+export interface TemporaryDirectory {
+  readonly path: string;
+  /** Removes the directory and everything in it; removing it twice removes it once. */
+  remove(): void;
 }

package/src/index.ts

@@ -1,5 +1,5 @@
 export { run, SETTING_OPTIONS, type Writer } from "./run.ts";
-export type { DirectoryEntry, Host, PathKind } from "./host.ts";
+export type { DirectoryEntry, Host, PathKind, TemporaryDirectory } from "./host.ts";
 export { DECLINED_CONVENTIONS, type DeclinedConvention } from "./entry-point-gaps.ts";
 export {
   byPosition,

package/src/inventory.ts

@@ -31,7 +31,13 @@ import {
 import type { Symbol as TSSymbol } from "@typescript/native/unstable/sync";
 import type { Host } from "./host.ts";
 import { dirnamePath, joinPath, relativePath } from "./paths.ts";
-import { byPosition, positionKey, renderPosition, type Position } from "./position.ts";
+import {
+  byPosition,
+  positionKey,
+  renderPosition,
+  writtenLength,
+  type Position,
+} from "./position.ts";
 import { computedComponent, nameComponent, renderRef, type Component, type Module } from "./ref.ts";
 import { isAnswered, UNANSWERED } from "./query.ts";
 import type { Handle, ProjectView } from "./session.ts";
@@ -534,7 +540,12 @@ export function inventory<Brand>(
       typeParameter: undefined,
     });
     exportScopes.push({ owner: fileRecord, nameNode: file });
-    walkStatements(file.statements, fileRecord);
+    // A statement a component file's module appends is not written in the file.
+    const written = writtenLength(file);
+    walkStatements(
+      file.statements.filter((statement) => statement.end <= written),
+      fileRecord,
+    );
   }
 
   /** One declaration of a module, a namespace or a container body. */

package/src/kinds.ts

@@ -69,7 +69,7 @@ const ROWS: readonly KindRow[] = [
     code: "DS1004",
     name: "test-only-use",
     languages: ["go", "ts"],
-    rule: "A symbol with zero production references and at least one test reference: an unused-exported, unused-unexported or unused-member candidate whose test reference count is not zero, reported once under this code. A reference from a consumer's test files is a test reference unless the configuration counts consumer tests as production.",
+    rule: "A symbol with zero production references and at least one test reference: an unused-exported, unused-unexported or unused-member candidate whose test reference count is not zero, reported once under this code. A reference from a consumer's test files is a test reference unless the configuration counts consumer tests as production. A reference from test-support code, a package or file that only test code imports, is a test reference, and a declaration of test-support code is never reported under this code.",
     defaultSeverity: "deny",
     maxClass: "certain",
     fixability: "deletable",
@@ -317,7 +317,7 @@ const ROWS: readonly KindRow[] = [
     languages: ["go", "ts"],
     rule: "A parameter with no reference inside its function body, on a function whose signature is free to change.",
     precondition:
-      "The signature must be free, defined as follows: the function is not a method retained by interface satisfaction, is not used as a value, is not a go:linkname or cgo target, and is not a stub whose body is empty or only panics. A parameter its body never names is dead whatever the callers, so a published declaration of a library is reported too, with the fixability the vocabulary gives the kind: the signature change is a breaking change.",
+      "The signature must be free, defined as follows: the function is not a method retained by interface satisfaction, is not used as a value, is not a go:linkname or cgo target, is not a function the Go test driver runs (a test, benchmark or fuzz test of a test file, or TestMain), and is not a stub whose body is empty or only panics. A parameter its body never names is dead whatever the callers, so a published declaration of a library is reported too, with the fixability the vocabulary gives the kind: the signature change is a breaking change.",
     defaultSeverity: "warn",
     maxClass: "certain",
     fixability: "manual",

package/src/manifest.ts

@@ -1,11 +1,9 @@
 /**
  * The entry points a package manifest names, which are roots because something
  * outside the analyzed program reaches them: a consumer importing the package, or a
- * shell running its command.
+ * shell running its command or one of its scripts.
  *
- * Only the target's own manifest is read. A manifest below the target root belongs
- * to another package, whose entry points are that package's roots and not this
- * target's.
+ * One call reads one manifest, the one in the directory it is given.
  */
 
 import type { Host } from "./host.ts";
@@ -22,7 +20,9 @@ export type EntryRole =
   /** A consumer importing the package, which is a caller the analysis cannot see. */
   | "import"
   /** A shell running the package's command, which is a caller that exists. */
-  | "run";
+  | "run"
+  /** A token of one of the package's scripts, which the package manager runs. */
+  | "script";
 
 /** One entry point the manifest names. */
 export interface ManifestEntry {
@@ -59,6 +59,24 @@ function isTarget(value: string, requireDot: boolean): boolean {
   return !requireDot || value.startsWith("./");
 }
 
+/** Where a script's command line splits into tokens: white space and the shell's operators. */
+const SCRIPT_SEPARATORS = /\s+|&&|\|\||;|\|/u;
+
+/** A token written inside one pair of quotes. */
+const QUOTED = /^(["'])(.*)\1$/su;
+
+/**
+ * Every token one script's command line holds, each with one pair of enclosing quotes
+ * removed. A token holding a wildcard is a pattern rather than a path, and names no
+ * entry point.
+ */
+export function scriptTokens(command: string): readonly string[] {
+  return command
+    .split(SCRIPT_SEPARATORS)
+    .map((token) => token.replace(QUOTED, "$2"))
+    .filter((token) => token !== "" && !token.includes("*"));
+}
+
 /** One member's spelling below another: `exports` then `exports["."]`. */
 function below(member: string, key: string): string {
   return `${member}[${JSON.stringify(key)}]`;
@@ -67,12 +85,9 @@ function below(member: string, key: string): string {
 /**
  * Every target one `exports` value carries, at the member each is written under.
  *
- * The value is a string, an object whose keys are subpaths or conditions, or an
- * array of alternatives, nested to any depth, and a `null` blocks a subpath rather
- * than naming a target. Every level is walked because a condition names a different
- * file of the same package and each is an entry point of its own; a key's meaning
- * is not read, because a subpath and a condition both lead to a target and the
- * walk needs no more than that.
+ * The value nests strings, subpath or condition objects and alternative arrays to
+ * any depth; a `null` blocks a subpath. Every level is walked, because each
+ * condition names its own entry file, and a key's meaning is never read.
  */
 function exportTargets(value: unknown, member: string, found: ManifestEntry[]): void {
   if (typeof value === "string") {
@@ -116,11 +131,12 @@ function manifestOf(host: Host, targetRoot: string): Record<string, unknown> | u
   return isRecord(value) ? value : undefined;
 }
 
-/** What the target's own manifest declares about where the package is entered. */
+/** What one manifest declares about where its package is entered. */
 export interface Manifest {
   /**
    * Every entry point the manifest names, in the order the members are read: `main`,
-   * `module`, `types`, then each `bin` command, then every target of `exports`. Each
+   * `module`, `types`, then each `bin` command, then every target of `exports`, then
+   * every token of each script, which names a file only where one is at its path. Each
    * path is absolute.
    */
   readonly entries: readonly ManifestEntry[];
@@ -134,7 +150,7 @@ export interface Manifest {
 }
 
 /**
- * What the target's own manifest declares about where the package is entered.
+ * What the manifest in `targetRoot` declares about where its package is entered.
  *
  * A target is taken as written. It is not resolved to a source file here, because
  * which file a target names is a fact about the compiler configuration that emits
@@ -167,6 +183,23 @@ export function readManifest(host: Host, targetRoot: string): Manifest {
 
   exportTargets(manifest["exports"], "exports", found);
 
+  const scripts = manifest["scripts"];
+  if (isRecord(scripts)) {
+    for (const [name, command] of Object.entries(scripts)) {
+      if (typeof command !== "string") {
+        continue;
+      }
+      for (const token of new Set(scriptTokens(command))) {
+        found.push({
+          member: below("scripts", name),
+          path: token,
+          role: "script",
+          published: false,
+        });
+      }
+    }
+  }
+
   return {
     entries: found.map((entry) => ({ ...entry, path: resolvePath(targetRoot, entry.path) })),
     declaresExports: manifest["exports"] !== undefined,

package/src/matrix.ts

@@ -21,6 +21,14 @@ export interface Configured {
   readonly roots: readonly Root[];
   /** The paths the reference pass classified as test files. */
   readonly testFiles: readonly string[];
+  /** The paths of the test-support files, which only test code imports. */
+  readonly supportFiles?: readonly string[] | undefined;
+  /**
+   * The paths of the workspace-package files the configuration holds but does not
+   * compile itself. Their declarations count in its graph and its verdict on them is no
+   * finding.
+   */
+  readonly referenceOnly?: readonly string[] | undefined;
 }
 
 /** The run's configurations, indexed for the sweep. */
@@ -30,9 +38,10 @@ export interface Matrix {
   /** Per configuration, in the same order, the graph of what that configuration holds. */
   readonly graphs: readonly Graph[];
   /**
-   * The graph over every configuration at once: every declaration any configuration
-   * holds, once per position and in site order, and every reference any configuration
-   * makes, a reference several configurations make at one position counted once.
+   * The graph over every configuration at once: every declaration a configuration
+   * holds in a file it does not hold only for its references, once per position and in
+   * site order, and every reference any configuration makes, a reference several
+   * configurations make at one position counted once.
    */
   readonly union: Graph;
   /**
@@ -88,31 +97,30 @@ export function referenceKey(reference: Reference): string {
 
 /**
  * Indexes what the passes answered for each configuration of one run, in the run's order.
- *
- * A declaration is keyed across configurations by its identifier, which is its rendered
- * position and so is the same in every configuration that compiles its file; the fields
- * of the first configuration that holds it are the ones kept. A declaration one
- * configuration alone holds is in the union with that one configuration, so it is
- * judged where it exists rather than skipped.
- *
- * One reference written at one position of a file several configurations compile is seen
- * once per configuration and is one reference, so the union holds it once; two references
- * one configuration makes at one position are two.
+ * A declaration is keyed by its rendered position, with the fields of the first
+ * configuration that judges it; one in a file every holder holds only for its references
+ * is judged by none and is not in the union. One reference at one position of a file
+ * several configurations compile is one reference; two one configuration makes are two.
  */
 export function matrixOf(per: readonly Configured[]): Matrix {
   const symbols: InventorySymbol[] = [];
   const holders = new Map<string, string[]>();
   const references: Reference[] = [];
   const firstSeen = new Map<string, number>();
+  const judged = new Set<string>();
   per.forEach((one, index) => {
+    const referenceOnly = new Set(one.referenceOnly);
     for (const symbol of one.symbols) {
       const held = holders.get(symbol.id);
       if (held === undefined) {
         holders.set(symbol.id, [one.configuration]);
-        symbols.push(symbol);
       } else if (!held.includes(one.configuration)) {
         held.push(one.configuration);
       }
+      if (!referenceOnly.has(symbol.position.path) && !judged.has(symbol.id)) {
+        judged.add(symbol.id);
+        symbols.push(symbol);
+      }
     }
     for (const reference of one.references) {
       const key = referenceKey(reference);
@@ -129,12 +137,15 @@ export function matrixOf(per: readonly Configured[]): Matrix {
 
   return {
     configurations: per.map((one) => one.configuration),
-    graphs: per.map((one) => graphOf(one.symbols, one.references, one.roots, one.testFiles)),
+    graphs: per.map((one) =>
+      graphOf(one.symbols, one.references, one.roots, one.testFiles, one.supportFiles),
+    ),
     union: graphOf(
       symbols,
       references,
       per.flatMap((one) => one.roots),
       [...new Set(per.flatMap((one) => one.testFiles))],
+      [...new Set(per.flatMap((one) => one.supportFiles ?? []))],
     ),
     heldIn: symbols.map((symbol) => holders.get(symbol.id) ?? []),
   };
@@ -197,6 +208,23 @@ export function sweepMatrix(matrix: Matrix, input: SweepInput): SweepResult {
   };
 }
 
+/**
+ * The file declarations at `paths`, below the target root, that one sweep holds live
+ * under both relations, the rule a judged declaration is live by.
+ */
+export function liveFilesAt(
+  matrix: Matrix,
+  result: SweepResult,
+  paths: ReadonlySet<string>,
+): readonly InventorySymbol[] {
+  return matrix.union.symbols.filter(
+    (symbol) =>
+      symbol.kind === "file" &&
+      paths.has(symbol.position.path) &&
+      (result.liveUnder.get(symbol.id)?.length ?? 0) === RELATIONS.length,
+  );
+}
+
 /** The relations in the order a declaration's entry lists them. */
 const RELATIONS: readonly Relation[] = ["reference-counting", "reachability"];
 

package/src/partial.ts

@@ -1,4 +1,5 @@
 import type { NotBuilt } from "./discover.ts";
+import { relativePath } from "./paths.ts";
 import type { UnansweredQuestion } from "./query.ts";
 
 /** What a run read only in part. */
@@ -7,6 +8,8 @@ interface Partial {
   readonly notBuilt: readonly NotBuilt[];
   /** Every question the checker could not answer, each once. */
   readonly unanswered: readonly UnansweredQuestion[];
+  /** The target root, absolute, which every configuration file is named below. */
+  readonly targetRoot: string;
 }
 
 /** A count with its noun, so a line reads for one as well as for several. */
@@ -29,7 +32,9 @@ export function partialNotes(partial: Partial): readonly string[] {
   if (partial.unanswered.length > 0) {
     const byProject = new Map<string, number>();
     for (const question of partial.unanswered) {
-      byProject.set(question.configFile, (byProject.get(question.configFile) ?? 0) + 1);
+      const configFile =
+        relativePath(partial.targetRoot, question.configFile) ?? question.configFile;
+      byProject.set(configFile, (byProject.get(configFile) ?? 0) + 1);
     }
     const where = [...byProject].map(([configFile, n]) => `${configFile}: ${String(n)}`).join(", ");
     notes.push(