@cplieger/deadset-ts 3.11.0 → 3.12.1

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,
@@ -113,6 +113,12 @@ export interface Graph {
   readonly exportsOf: readonly (readonly number[])[];
   /** Every root naming a declaration the inventory holds, in the order the root set gives them. */
   readonly rooted: readonly Rooted[];
+  /**
+   * Every reference a loaded consumer makes to a declaration the inventory holds, in the
+   * order given. A consumer is a caller the analysis read, so the sweep holds what it
+   * names live under both relations and reaches on from there.
+   */
+  readonly consumed: readonly Edge[];
   /** The position of the declaration one identifier names, or {@link OUTSIDE}. */
   at(id: string): number;
 }
@@ -136,6 +142,7 @@ export function graphOf(
 
   const out: Edge[][] = symbols.map(() => []);
   const made = symbols.map(() => ({ production: 0, test: 0 }));
+  const consumed: Edge[] = [];
   for (const reference of references) {
     const to = at(reference.to);
     if (to === OUTSIDE) {
@@ -149,11 +156,12 @@ export function graphOf(
         counts.production += 1;
       }
     }
-    out[at(reference.from)]?.push({
-      to,
-      test: reference.test,
-      evaluation: reference.use === "evaluation",
-    });
+    const edge = { to, test: reference.test, evaluation: reference.use === "evaluation" };
+    if (reference.consumer !== undefined) {
+      consumed.push(edge);
+      continue;
+    }
+    out[at(reference.from)]?.push(edge);
   }
 
   const parent = symbols.map((symbol) => at(symbol.parent));
@@ -182,6 +190,7 @@ export function graphOf(
     subject: symbols.map((symbol) => swept(symbol.kind)),
     exportsOf,
     rooted,
+    consumed,
     at,
   };
 }

package/src/matrix.ts

@@ -69,12 +69,21 @@ function compare(a: string, b: string): number {
   return a < b ? -1 : 1;
 }
 
-/** What makes one reference one reference, whichever configuration made it. */
-function referenceKey(reference: Reference): string {
+/**
+ * What makes one reference one reference, whichever configuration made it. A consumer's
+ * position is rendered against its own root, so the consumer is part of what it names.
+ */
+export function referenceKey(reference: Reference): string {
   const { path, line, column } = reference.position;
-  return [reference.from, reference.to, path, String(line), String(column), reference.use].join(
-    "\u0000",
-  );
+  return [
+    reference.consumer ?? "",
+    reference.from,
+    reference.to,
+    path,
+    String(line),
+    String(column),
+    reference.use,
+  ].join("\u0000");
 }
 
 /**

package/src/references.ts

@@ -32,6 +32,7 @@ import { aliasChains } from "./alias-chain.ts";
 import { destructuring, propertyReadsOf, type PropertyRead } from "./destructuring.ts";
 import { globExpression } from "./glob.ts";
 import { nodeKey, type Inventory } from "./inventory.ts";
+import { relativePath } from "./paths.ts";
 import { byPosition, renderPosition, type Position } from "./position.ts";
 import type { ProjectView } from "./session.ts";
 
@@ -95,6 +96,21 @@ export interface Reference {
   readonly resolution: Resolution;
   /** Whether the file that made the reference is classified as a test file. */
   readonly test: boolean;
+  /**
+   * The identifier of the consumer whose file made the reference, absent for one the
+   * target made. A consumer's declarations are no declarations of the run, so such a
+   * reference comes from outside the inventory, and its position is rendered against
+   * the consumer's root.
+   */
+  readonly consumer?: string;
+}
+
+/** The consumer one reference pass reads the files of, beside the target it names. */
+export interface ConsumerSide {
+  /** The name the consumer publishes itself under. */
+  readonly id: string;
+  /** The consumer's directory, absolute: the files below it are its own. */
+  readonly root: string;
 }
 
 /** One rule that classified files as test files, and how many files it matched. */
@@ -162,6 +178,13 @@ export interface ReferenceOptions {
    * Each pattern is a rule of its own, which {@link testFileRulesOf} counts.
    */
   readonly testFiles: readonly string[];
+  /**
+   * The consumer whose files the pass walks instead of the target's. Its files are the
+   * program's own files below its root and not below the target root, each position is
+   * rendered against its root and the test patterns read the path below it, and only a
+   * reference to a declaration of `held`, the target's, is recorded.
+   */
+  readonly consumer?: ConsumerSide;
 }
 
 /**
@@ -555,7 +578,9 @@ function compare(a: string, b: string): number {
  *
  * `held` is the inventory of the same project, whose declaration map is what a resolved
  * symbol is looked up in; `targetRoot` is the absolute path every position is rendered
- * against, which is the root the inventory was read against.
+ * against, which is the root the inventory was read against. A pass over a consumer
+ * walks the consumer's files instead and renders against its root, as
+ * {@link ReferenceOptions.consumer} states.
  *
  * The order is by the referencing position, then by the declaration named, the
  * declaration referencing it and the use. That is a total order because one name
@@ -581,7 +606,18 @@ export function references<Brand>(
   let residueFallbacks = 0;
   let shorthandLookups = 0;
 
-  const files = project.ownSourceFiles();
+  const consumer = options.consumer;
+  const root = consumer?.root ?? targetRoot;
+  const files =
+    consumer === undefined
+      ? project.ownSourceFiles()
+      : project
+          .ownSourceFiles()
+          .filter(
+            (file) =>
+              relativePath(consumer.root, file.fileName) !== undefined &&
+              relativePath(targetRoot, file.fileName) === undefined,
+          );
   const fileIds = new Set(
     held.symbols.filter((symbol) => symbol.kind === "file").map((symbol) => symbol.id),
   );
@@ -615,7 +651,7 @@ export function references<Brand>(
   };
 
   for (const file of files) {
-    const path = renderPosition(file, targetRoot, 0).path;
+    const path = renderPosition(file, root, 0).path;
     const test = patterns.some((pattern) => pattern.test(path));
     if (test) {
       tests.push(path);
@@ -633,7 +669,7 @@ export function references<Brand>(
       found.push({
         from: declaration,
         to: declaration,
-        position: renderPosition(file, targetRoot, decorator.getStart()),
+        position: renderPosition(file, root, decorator.getStart()),
         use: "decorator",
         resolution: "syntax",
         test,
@@ -671,7 +707,7 @@ export function references<Brand>(
       if (symbol === undefined) {
         continue;
       }
-      const position = renderPosition(file, targetRoot, link.at.getStart());
+      const position = renderPosition(file, root, link.at.getStart());
       for (const id of carriedBy(link, symbol)) {
         found.push({
           from: link.from,
@@ -689,7 +725,7 @@ export function references<Brand>(
       if (module === undefined) {
         continue;
       }
-      const position = renderPosition(file, targetRoot, evaluation.node.getStart());
+      const position = renderPosition(file, root, evaluation.node.getStart());
       for (const id of chains.declarationsOf(module)) {
         if (fileIds.has(id)) {
           found.push({
@@ -711,7 +747,7 @@ export function references<Brand>(
       if (symbol === undefined || read === undefined) {
         return;
       }
-      const position = renderPosition(file, targetRoot, read.key.getStart());
+      const position = renderPosition(file, root, read.key.getStart());
       for (const target of chains.chainOf(symbol)) {
         found.push({
           from: read.from,
@@ -735,7 +771,7 @@ export function references<Brand>(
       if (symbol === undefined) {
         continue;
       }
-      const position = renderPosition(file, targetRoot, site.node.getStart());
+      const position = renderPosition(file, root, site.node.getStart());
       // A re-export something imports is used and so is the declaration behind it, so
       // the use names every link of the chain its name stands at the head of.
       for (const target of chains.chainOf(symbol)) {
@@ -761,7 +797,10 @@ export function references<Brand>(
 
   return {
     configFile: project.configFile,
-    references: found,
+    references:
+      consumer === undefined
+        ? found
+        : found.map((reference) => ({ ...reference, consumer: consumer.id })),
     testFilePaths: tests.sort(compare),
     cost: {
       batched,

package/src/report.ts

@@ -130,6 +130,13 @@ export interface ReportConfiguration {
   readonly project: string;
 }
 
+/** One consumer the run loaded, at the directory a report names it by. */
+interface ReportConsumer {
+  readonly id: string;
+  /** The consumer's directory, as the report names its target's: below the run directory. */
+  readonly path: string;
+}
+
 /** One consumer the scope declared and the run did not load, with why. */
 export interface UnavailableConsumer {
   readonly id: string;
@@ -156,7 +163,11 @@ export interface Report {
   readonly configurations_not_built: readonly never[];
   readonly consumers: {
     readonly declared: number;
-    readonly loaded: readonly never[];
+    readonly loaded: readonly {
+      readonly id: string;
+      readonly role: "consumer";
+      readonly path: string;
+    }[];
     readonly unavailable: readonly {
       readonly id: string;
       readonly role: "consumer";
@@ -180,6 +191,7 @@ export interface ReportInput {
   readonly declaredGaps: readonly DeclaredGap[];
   readonly target: { readonly kind: TargetKind; readonly root: string; readonly identity: string };
   readonly configurations: readonly ReportConfiguration[];
+  readonly loaded: readonly ReportConsumer[];
   readonly unavailable: readonly UnavailableConsumer[];
   readonly result: PassResult;
   readonly testFileRules: readonly TestFileRule[];
@@ -387,6 +399,9 @@ export function buildReport(input: ReportInput): Report {
   const unavailable = [...new Map(input.unavailable.map((one) => [one.id, one])).values()]
     .sort((a, b) => compare(a.id, b.id))
     .map((one) => ({ id: one.id, role: "consumer" as const, reason: one.reason }));
+  const loaded = [...input.loaded]
+    .sort((a, b) => compare(a.id, b.id) || compare(a.path, b.path))
+    .map((one) => ({ id: one.id, role: "consumer" as const, path: one.path }));
   return {
     schema_version: SCHEMA_VERSION,
     contract_version: input.contractVersion,
@@ -406,7 +421,7 @@ export function buildReport(input: ReportInput): Report {
       .sort((a, b) => compare(a.id, b.id))
       .map((one) => ({ id: one.id, project: one.project })),
     configurations_not_built: [],
-    consumers: { declared: unavailable.length, loaded: [], unavailable },
+    consumers: { declared: loaded.length + unavailable.length, loaded, unavailable },
     findings,
     edge_evaluations: input.result.edgeEvaluations.map(wireEvaluation).sort(byEdge),
     stale_suppressions: input.result.staleSuppressions.map(wireStale).sort(canonicalStale),

package/src/roots.ts

@@ -4,9 +4,8 @@
  *
  * Every root seeds REACHABILITY, and no root counts as a reference. A root of a kind
  * that names a caller is live under reference counting as well, which the sweep
- * decides; a root that only supposes a consumer is not, so an exported declaration
- * something outside the program reaches is live under reachability and still a
- * candidate under reference counting.
+ * decides; the published API only supposes a consumer, so a published export is live
+ * under reachability and still a candidate under reference counting.
  */
 
 import type { SourceFile } from "@typescript/native/unstable/ast";
@@ -23,9 +22,9 @@ import { sourceFilesOf } from "./source-files.ts";
 export type RootKind =
   /** A file `ts.entry_files` names, and what it exports. */
   | "entry-file"
-  /** A file the manifest names as an importable entry point, and what it exports. */
+  /** A file the manifest names as an importable entry point, and what it exports outside the published API. */
   | "manifest-entry"
-  /** A file the manifest names as a command, and what it exports. */
+  /** A file the manifest names as a command, and what it exports outside the published API. */
   | "manifest-binary"
   /** A declaration a consumer of a library target can name. */
   | "published-api"
@@ -168,6 +167,7 @@ function childrenOf(held: Inventory): ReadonlyMap<string, readonly InventorySymb
  * is a root with everything its module exports: each name of the module's export
  * table, and where a name is a re-export, every link of the chain to the declaration
  * it carries, so a re-exported declaration is a root of the file that publishes it.
+ * In a library, what a published file exports is rooted by the published API alone.
  * A file a runtime executes without reading its exports, a test file or a worker, is
  * a root by itself.
  */
@@ -198,14 +198,19 @@ export function roots<Brand>(
 
   const published: SourceFile[] = [];
   const publishes = (entry: ManifestEntry): boolean =>
+    options.publishedAPI &&
     entry.published &&
     (options.manifest.declaresExports ? entry.member.startsWith("exports") : true);
+  for (const entry of options.manifest.entries) {
+    if (publishes(entry)) {
+      published.push(...files.named(entry.path));
+    }
+  }
+  const publishedNames = new Set(published.map((file) => file.fileName));
   for (const entry of options.manifest.entries) {
     for (const file of files.named(entry.path)) {
-      enter(file, entry.role === "run" ? "manifest-binary" : "manifest-entry", entry.member, true);
-      if (options.publishedAPI && publishes(entry)) {
-        published.push(file);
-      }
+      const kind = entry.role === "run" ? "manifest-binary" : "manifest-entry";
+      enter(file, kind, entry.member, !publishedNames.has(file.fileName));
     }
   }
   for (const pattern of options.entryFiles) {

package/src/session.ts

@@ -193,6 +193,25 @@ function viewOf<Brand>(project: Project): ProjectView<Brand> {
   };
 }
 
+/**
+ * The same project, its own source files narrowed to the ones `keep` admits. A consumer's
+ * program holds the target's files it imports beside its own, and a pass that enumerates
+ * the target's declarations in that program reads those files alone.
+ */
+export function narrowedTo<Brand>(
+  project: ProjectView<Brand>,
+  keep: (file: SourceFile) => boolean,
+): ProjectView<Brand> {
+  let kept: readonly SourceFile[] | undefined;
+  return {
+    ...project,
+    ownSourceFiles: () => {
+      kept ??= project.ownSourceFiles().filter(keep);
+      return kept;
+    },
+  };
+}
+
 /** Every diagnostic set a project is refused for carrying an error in. */
 export interface ProjectDiagnostics {
   readonly configFile: string;

package/src/sweep.ts

@@ -7,7 +7,7 @@
  */
 
 import type { TSExemptionClass } from "./exempt-classes.ts";
-import { namesACaller, OUTSIDE, type Graph } from "./graph.ts";
+import { namesACaller, OUTSIDE, type Edge, type Graph } from "./graph.ts";
 import type { Position } from "./position.ts";
 
 /** The liveness relation that decided a declaration, as a finding spells it. */
@@ -156,6 +156,14 @@ export function sweep(graph: Graph, input: SweepInput): Liveness {
   return { liveUnder: live, candidates };
 }
 
+/**
+ * The references a loaded consumer makes that the mode counts. A production mode counts
+ * none a consumer's test file made, as it counts none of the target's.
+ */
+function callsOf(graph: Graph, mode: Mode): readonly Edge[] {
+  return graph.consumed.filter((edge) => !mode.production || !edge.test);
+}
+
 /** Per declaration of the graph, whether one of the identifiers names it. */
 function flagged(graph: Graph, ids: readonly string[]): boolean[] {
   const flags = graph.symbols.map(() => false);
@@ -218,6 +226,10 @@ function reachable(graph: Graph, held: readonly boolean[], mode: Mode): readonly
   for (const root of graph.rooted) {
     enter(root.at, false);
   }
+  // A consumer's reference reaches what it names as one of the target's own does.
+  for (const edge of callsOf(graph, mode)) {
+    enter(edge.to, !edge.evaluation);
+  }
   walk(false);
   return reached;
 }

package/src/verbs/analyze.ts

@@ -1,8 +1,8 @@
 import { runAnalysis, type RunProject } from "../analysis.ts";
 import { ConfigError, type Format } from "../config.ts";
 import { CONFORMANCE, DECLARED_GAPS } from "../conformance.ts";
+import { moduleIdentity } from "../consumers.ts";
 import { analyzerProvenance, recordedFindings, verdictOf } from "../findings-pass.ts";
-import { packageScope } from "../inventory.ts";
 import { joinPath, normalizePath, relativePath, resolvePath } from "../paths.ts";
 import type { Host } from "../host.ts";
 import {
@@ -16,7 +16,6 @@ import { json } from "../reporters/json.ts";
 import { RENDERINGS } from "../reporters/reporters.ts";
 import { parseTemplate, TemplateError, type Template } from "../reporters/template.ts";
 import { resolve } from "../resolve.ts";
-import type { Module } from "../scope.ts";
 import { writeBaseline, type Recorded } from "../suppress-file.ts";
 import { CONTRACT_VERSION } from "../version.ts";
 import { EXIT_CLEAN, EXIT_FAILURE, type Verb, type VerbOptions } from "./verb.ts";
@@ -31,9 +30,6 @@ export const ANALYZE_OPTIONS: VerbOptions = {
 const EXIT_CODE_ON = "on";
 const EXIT_CODE_OFF = "off";
 
-/** Why a declared consumer is not loaded, which every report names it with. */
-const NOT_LOADED = "this analyzer loads no consumer beside the target";
-
 /** A path of the run no report can name, which ends the run with the failure code. */
 class ReportPathError extends Error {
   constructor(message: string) {
@@ -101,11 +97,6 @@ function configurationsOf(
   });
 }
 
-/** The name one module publishes itself under: the scope's, else its manifest's. */
-function identityOf(module: Module, host: Host): string {
-  return module.id === "" ? packageScope(host, module.path)("index.ts").package : module.id;
-}
-
 /** A count with its noun, so a message reads for one record as well as for several. */
 function counted(n: number, noun: string): string {
   return `${String(n)} ${noun}${n === 1 ? "" : "s"}`;
@@ -221,12 +212,13 @@ export const analyzeVerb: Verb = ({ err, host, inputs, scope, openClient, option
       version,
       conformance: CONFORMANCE,
       declaredGaps: DECLARED_GAPS,
-      target: { kind, root, identity: identityOf(scoped.target, host) },
+      target: { kind, root, identity: moduleIdentity(host, scoped.target) },
       configurations: configurationsOf(run.projects, targetRoot),
-      unavailable: scoped.consumers.map((consumer) => ({
-        id: identityOf(consumer, host),
-        reason: NOT_LOADED,
+      loaded: run.consumers.map((consumer) => ({
+        id: consumer.id,
+        path: runRelative(invoked, consumer.path),
       })),
+      unavailable: [],
       result,
       testFileRules: run.testFileRules,
     });

package/src/verbs/explain.ts

@@ -5,7 +5,7 @@ import { ConfigError } from "../config.ts";
 import type { CompletedFinding } from "../finding.ts";
 import { OUTSIDE, swept as judged } from "../graph.ts";
 import type { InventorySymbol } from "../inventory.ts";
-import type { Configured } from "../matrix.ts";
+import { referenceKey, type Configured } from "../matrix.ts";
 import { positionKey } from "../position.ts";
 import type { Reference } from "../references.ts";
 import { resolve } from "../resolve.ts";
@@ -108,9 +108,7 @@ function referencesOf(configured: readonly Configured[]): readonly Reference[] {
   const seen = new Set<string>();
   const held: Reference[] = [];
   for (const reference of configured.flatMap((one) => one.references)) {
-    const key = [reference.from, reference.to, positionKey(reference.position), reference.use].join(
-      "\u0000",
-    );
+    const key = referenceKey(reference);
     if (!seen.has(key)) {
       seen.add(key);
       held.push(reference);
@@ -142,9 +140,15 @@ type Hop =
   | { readonly k: "reference"; readonly reference: Reference }
   | { readonly k: "export"; readonly reference: Reference; readonly to: string };
 
+/** Where a path starts: a root of the run, or a reference a loaded consumer makes. */
+type Origin =
+  | { readonly k: "root"; readonly root: Root }
+  | { readonly k: "consumer"; readonly consumer: string };
+
 /**
- * The shortest path from a root to one declaration, walked breadth first from every root at
- * once in the order the run names them, following the references the sweep follows: a
+ * The shortest path from a root or a loaded consumer to one declaration, walked breadth first
+ * from every root at once in the order the run names them, a consumer's reference being the
+ * first hop of a path of its own, and following the references the sweep follows: a
  * reference that reads a module reaches what the module exports, and an evaluation or a root
  * reaches the module alone. Under `production` no reference a test file made is followed,
  * which is the set the report's sweep counts.
@@ -153,13 +157,19 @@ function shortestPath(
   analysis: RunAnalysis,
   to: string,
   production: boolean,
-): { readonly root: Root; readonly path: readonly Hop[] } | undefined {
+): { readonly origin: Origin; readonly path: readonly Hop[] } | undefined {
   const graph = analysis.swept.matrix.union;
   const out = new Map<string, Reference[]>();
+  const consumed: (Reference & { readonly consumer: string })[] = [];
   for (const reference of referencesOf(analysis.configured)) {
     if (production && reference.test) {
       continue;
     }
+    const { consumer } = reference;
+    if (consumer !== undefined) {
+      consumed.push({ ...reference, consumer });
+      continue;
+    }
     const held = out.get(reference.from);
     if (held === undefined) {
       out.set(reference.from, [reference]);
@@ -171,7 +181,7 @@ function shortestPath(
     readonly at: string;
     readonly hop: Hop | undefined;
     readonly previous: number;
-    readonly root: Root;
+    readonly origin: Origin;
   }
   const steps: Step[] = [];
   const seen = new Set<string>();
@@ -182,10 +192,32 @@ function shortestPath(
       steps.push(step);
     }
   };
+  const follow = (reference: Reference, previous: number, origin: Origin): void => {
+    enter({ at: reference.to, hop: { k: "reference", reference }, previous, origin });
+    const target = graph.at(reference.to);
+    if (reference.use === "evaluation" || target === OUTSIDE || expanded.has(reference.to)) {
+      return;
+    }
+    expanded.add(reference.to);
+    for (const exported of graph.exportsOf[target] ?? []) {
+      const id = graph.symbols[exported]?.id;
+      if (id !== undefined) {
+        enter({ at: id, hop: { k: "export", reference, to: id }, previous, origin });
+      }
+    }
+  };
   for (const root of rootsOf(analysis.configured)) {
-    enter({ at: root.id, hop: undefined, previous: -1, root });
+    enter({ at: root.id, hop: undefined, previous: -1, origin: { k: "root", root } });
   }
-  for (let head = 0; head < steps.length; head += 1) {
+  // A consumer's reference is one hop long, so it joins the walk where the roots' first
+  // hops do.
+  const firstHops = steps.length;
+  for (let head = 0; ; head += 1) {
+    if (head === firstHops) {
+      for (const reference of consumed) {
+        follow(reference, -1, { k: "consumer", consumer: reference.consumer });
+      }
+    }
     const step = steps[head];
     if (step === undefined) {
       break;
@@ -195,36 +227,20 @@ function shortestPath(
       for (let at: Step | undefined = step; at?.hop !== undefined; at = steps[at.previous]) {
         path.unshift(at.hop);
       }
-      return { root: step.root, path };
+      return { origin: step.origin, path };
     }
     for (const reference of out.get(step.at) ?? []) {
-      enter({
-        at: reference.to,
-        hop: { k: "reference", reference },
-        previous: head,
-        root: step.root,
-      });
-      const target = graph.at(reference.to);
-      if (reference.use === "evaluation" || target === OUTSIDE || expanded.has(reference.to)) {
-        continue;
-      }
-      expanded.add(reference.to);
-      for (const exported of graph.exportsOf[target] ?? []) {
-        const id = graph.symbols[exported]?.id;
-        if (id !== undefined) {
-          enter({
-            at: id,
-            hop: { k: "export", reference, to: id },
-            previous: head,
-            root: step.root,
-          });
-        }
-      }
+      follow(reference, head, step.origin);
     }
   }
   return undefined;
 }
 
+/** What made a reference: a declaration of the target, or a loaded consumer. */
+function madeBy(reference: Reference): string {
+  return reference.consumer === undefined ? reference.from : `consumer ${reference.consumer}`;
+}
+
 function referenceLine(reference: Reference, tail: string): string {
   return `  reference: ${positionKey(reference.position)}\t${reference.use}\t${tail}${reference.test ? "\tfrom a test file" : ""}\n`;
 }
@@ -244,19 +260,20 @@ function liveness(analysis: RunAnalysis, subject: InventorySymbol, cascade: Casc
   const found =
     shortestPath(analysis, subject.id, true) ?? shortestPath(analysis, subject.id, false);
   if (found !== undefined && found.path.length > 0) {
-    text += `  reached from: root ${found.root.kind} ${found.root.id}\n`;
+    const { origin } = found;
+    text += `  reached from: ${origin.k === "root" ? `root ${origin.root.kind} ${origin.root.id}` : `consumer ${origin.consumer}`}\n`;
     for (const hop of found.path) {
-      text += referenceLine(hop.reference, `${hop.reference.from} -> ${hop.reference.to}`);
+      text += referenceLine(hop.reference, `${madeBy(hop.reference)} -> ${hop.reference.to}`);
       if (hop.k === "export") {
         text += `  export: ${hop.reference.to} -> ${hop.to}\n`;
       }
     }
   } else if (found === undefined) {
     const references = referencesOf(analysis.configured).filter((one) => one.to === subject.id);
-    text += "  unreachable: no path of references reaches it from a root\n";
+    text += "  unreachable: no path of references reaches it from a root or a loaded consumer\n";
     text += `  references: ${String(references.length)}\n`;
     for (const reference of references) {
-      text += referenceLine(reference, `from ${reference.from}`);
+      text += referenceLine(reference, `from ${madeBy(reference)}`);
     }
   }
   if (candidate !== undefined) {
@@ -337,9 +354,9 @@ function explanation(analysis: RunAnalysis, subject: InventorySymbol, cascade: C
  * Explains one symbol from the analysis the report is built from, so an explanation cannot
  * disagree with a finding: why a reported symbol is reported, which exemption classes held a
  * retained one back, and for any other declaration the relations that hold it live and the
- * shortest path of references from a root, or the references it has where no path reaches it.
- * A request naming no one declaration exits with the usage code and names what partially
- * matches it.
+ * shortest path of references from a root or a loaded consumer, or the references it has where
+ * no path reaches it. A request naming no one declaration exits with the usage code and names
+ * what partially matches it.
  */
 export const explainVerb: Verb = ({ out, err, host, inputs, scope, openClient, option }) => {
   const named = namedSymbol(option);