@intentius/chant 0.124.21 → 0.124.23

package/src/workspace/lexicon-outputs.ts

@@ -0,0 +1,272 @@
+/**
+ * The outputs a member's lexicons report about their own declarations
+ * (#3931), read offline for `chant workspace check`.
+ *
+ * A sql member exposes each table and each column as a workspace output
+ * (`public.orders`, `public.orders.customer_id`) without anyone writing
+ * `output(...)`. The names are the lexicon's to give, so the lexicon answers
+ * through its `workspaceOutputs` hook, the way a CI lexicon answers
+ * `graphEdges` (#3910).
+ *
+ * The check never runs member code. The member's source files are folded
+ * with `foldProject` under `sandbox`, which evaluates the fold subset and
+ * imports nothing from the project: a sql `table` template becomes the real
+ * entity because the tag is the lexicon's own function, called with the
+ * folded parts. A file that does not fold is not run either. It is handed to
+ * the hook as unread, and when it is one of that lexicon's files (it uses the
+ * lexicon's tags), the hook records a gap: the member's outputs are then
+ * incomplete, and a link to a name not in them is unresolved rather than
+ * missing.
+ *
+ * Folding is asynchronous and the checks are not, so the outputs are
+ * gathered before the checks run, only for the members some declared link
+ * targets, and only for the kinds whose outputs are read from source.
+ *
+ * Under `--at` the revision's files are not on disk to fold, so a member
+ * whose lexicons report outputs gets a gap instead.
+ */
+
+import { join, posix } from "node:path";
+import type { StaticFieldsRead } from "../config-static";
+import { isDeclarable, type Declarable } from "../declarable";
+import type { LexiconUnreadSource, LexiconWorkspaceOutput } from "../graph-ir";
+import type { BuildRootContext, BuildRootContribution, IntrinsicDef } from "../lexicon";
+import type { Declaration, ResolvedGroup } from "./declaration";
+import type { KindRegistry } from "./kinds";
+import { kindHandles } from "./links";
+import { readKindLinks } from "./kind-link-readers";
+import { memberExcludes, sourceFiles } from "./member-handles";
+import { memberDirOnDisk } from "./lexicon-symbols";
+import type { WorkspaceTree } from "./tree";
+
+/** What one member's lexicons report: its outputs, and why the list may be incomplete. */
+export interface MemberLexiconOutputs {
+  outputs: Pick<LexiconWorkspaceOutput, "name" | "previously">[];
+  gaps: string[];
+}
+
+/** The part of a lexicon plugin this reader uses. */
+export interface OutputsPlugin {
+  name?: string;
+  intrinsics?: () => IntrinsicDef[];
+  buildRoots?: (ctx: BuildRootContext) => Promise<BuildRootContribution>;
+  workspaceOutputs?: (entities: ReadonlyMap<string, Declarable>, unread?: readonly LexiconUnreadSource[]) => { outputs: LexiconWorkspaceOutput[]; gaps?: string[] } | undefined;
+}
+
+/** Loads a lexicon plugin by name; `loadPlugin` from the CLI unless a test swaps it. */
+export type OutputsPluginLoader = (name: string) => Promise<OutputsPlugin>;
+
+export interface GatherLexiconOutputsOptions {
+  /** Read under `--at`: the member's files are a revision's, not on disk, so nothing is folded. */
+  atRevision?: boolean;
+  load?: OutputsPluginLoader;
+}
+
+const firstLine = (err: unknown): string => (err instanceof Error ? err.message : String(err)).split("\n")[0];
+
+const memberDir = (dir: string) => (dir === "." ? "" : dir);
+
+/** The `sourceDir` a member's config sets, read without running it. */
+function staticSourceDir(read: StaticFieldsRead): string | undefined {
+  const value = read.status === "read" ? read.fields.sourceDir : undefined;
+  if (typeof value !== "string") return undefined;
+  const dir = posix.normalize(value.replace(/\\/g, "/")).replace(/\/+$/, "");
+  return dir === "." || dir === "" ? undefined : dir;
+}
+
+/**
+ * Only the files under the member's `sourceDir`, when its config sets one, as
+ * a build reads them (#3941). Without one, every source file of the member.
+ */
+function withinSourceDir(files: string[], member: string, sourceDir: string | undefined): string[] {
+  if (!sourceDir) return files;
+  const prefix = `${member ? `${member}/` : ""}${sourceDir}/`;
+  return files.filter((f) => f.startsWith(prefix));
+}
+
+/**
+ * A folded file's exports, less the entities of lexicons the member doesn't
+ * declare (#3941). An Op is a `chant` entity, and several files exporting
+ * `op` would otherwise collide and leave the whole member unread, though no
+ * hook reads Ops. Values that are not entities (a composite) are kept.
+ */
+function ownExports(exports: ReadonlyMap<string, unknown>, lexicons: readonly string[]): Record<string, unknown> {
+  const own = new Set(lexicons);
+  const out: Record<string, unknown> = {};
+  for (const [name, value] of exports) {
+    if (isDeclarable(value) && !own.has(value.lexicon)) continue;
+    out[name] = value;
+  }
+  return out;
+}
+
+/**
+ * The lexicon names a member's config declares, read without running it.
+ * Unlike the intent walk, a config that can't be read statically is not
+ * loaded: the check runs no member code, so it is a gap.
+ */
+async function staticMemberLexicons(dir: string): Promise<string[]> {
+  const { readLexiconDeclarationsStatically } = await import("../config-static");
+  const read = readLexiconDeclarationsStatically(dir);
+  if (read.status === "no-config") return [];
+  if (read.status !== "read") throw new Error(read.reason);
+  const { lexiconNames, registerLexiconDeclarations } = await import("../lexicon-module");
+  const { dirname } = await import("node:path");
+  registerLexiconDeclarations(read.entries, dirname(read.configPath));
+  return lexiconNames(read.entries);
+}
+
+/**
+ * The lexicon outputs of every member a declared link, or a link a kind's
+ * reader found (#3932), targets, keyed by
+ * member name. A member whose lexicons report nothing is left out.
+ * `tree` is the working tree under `root`.
+ */
+export async function gatherLexiconOutputs(
+  root: string,
+  declaration: Declaration,
+  tree: WorkspaceTree,
+  groups: readonly ResolvedGroup[],
+  kinds: KindRegistry,
+  options: GatherLexiconOutputsOptions = {},
+): Promise<Map<string, MemberLexiconOutputs>> {
+  const out = new Map<string, MemberLexiconOutputs>();
+  const targets = new Set(declaration.members.flatMap((m) => m.links.filter((l) => l.member !== m.name).map((l) => l.member)));
+  // Links a kind's reader finds in a member's files target members too (#3932). One that names no
+  // producer may be any other member's, so every other member is read.
+  for (const [consumer, read] of readKindLinks(declaration, tree, kinds)) {
+    for (const link of read.links) {
+      if (link.member !== null) targets.add(link.member);
+      else for (const m of declaration.members) if (m.name !== consumer) targets.add(m.name);
+    }
+  }
+  for (const m of declaration.members) {
+    if (!targets.has(m.name)) continue;
+    const kind = kinds.get(m.kind);
+    if (!kind || kindHandles(m, kind) || tree.stat(memberDir(m.dir)) !== "dir") continue;
+    const read = await readMemberLexiconOutputs(root, declaration, tree, groups, m, options);
+    if (read) out.set(m.name, read);
+  }
+  return out;
+}
+
+/** The lexicons the files import, by the package name chant gives a lexicon. */
+function importedLexicons(tree: WorkspaceTree, files: readonly string[]): string[] {
+  const names = new Set<string>();
+  for (const file of files) {
+    let text: string;
+    try {
+      text = tree.read(file);
+    } catch {
+      continue;
+    }
+    for (const m of text.matchAll(/from\s+["']@intentius\/chant-lexicon-([a-z0-9-]+)(?:\/[^"']*)?["']/g)) names.add(m[1]!);
+  }
+  return [...names].sort();
+}
+
+async function readMemberLexiconOutputs(
+  root: string,
+  declaration: Declaration,
+  tree: WorkspaceTree,
+  groups: readonly ResolvedGroup[],
+  m: Declaration["members"][number],
+  options: GatherLexiconOutputsOptions,
+): Promise<MemberLexiconOutputs | undefined> {
+  const dir = memberDirOnDisk(root, m.dir);
+  const { readConfigFieldsStatically } = await import("../config-static");
+  const files = withinSourceDir(
+    sourceFiles(tree, memberDir(m.dir), memberExcludes(declaration, groups, m)),
+    memberDir(m.dir),
+    staticSourceDir(readConfigFieldsStatically(dir, ["sourceDir"])),
+  );
+  let names: string[];
+  try {
+    names = await staticMemberLexicons(dir);
+  } catch {
+    // A config that can't be read statically is not run. The lexicons the
+    // source imports stand in for the ones it names.
+    names = importedLexicons(tree, files);
+  }
+  if (names.length === 0) return undefined;
+  const load = options.load ?? ((await import("../cli/plugins")).loadPlugin as unknown as OutputsPluginLoader);
+  const plugins: { name: string; plugin: OutputsPlugin }[] = [];
+  const gaps: string[] = [];
+  for (const name of names) {
+    try {
+      plugins.push({ name, plugin: await load(name) });
+    } catch (err) {
+      gaps.push(`lexicon "${name}" could not be loaded, so the outputs it reads were not (${firstLine(err)})`);
+    }
+  }
+  const reporting = plugins.filter((p) => typeof p.plugin.workspaceOutputs === "function");
+  if (reporting.length === 0) return gaps.length ? { outputs: [], gaps } : undefined;
+  if (options.atRevision) {
+    return { outputs: [], gaps: [`the outputs of lexicon ${reporting.map((p) => p.name).join(", ")} are read from the working tree's files, not a revision's`] };
+  }
+
+  // Fold the member's source, never run it.
+  const abs = (file: string) => join(root, ...file.split("/"));
+  const intrinsics = plugins.flatMap((p) => {
+    try {
+      return p.plugin.intrinsics?.() ?? [];
+    } catch {
+      return [];
+    }
+  });
+  let entities: Map<string, Declarable> = new Map();
+  const unread: LexiconUnreadSource[] = [];
+  try {
+    const { foldProject } = await import("../discovery/fold-import");
+    const { collectEntities } = await import("../discovery/collect");
+    const verdicts = await foldProject(files.map(abs), intrinsics, { lexicons: names, sandbox: true });
+    const folded: { file: string; exports: Record<string, unknown> }[] = [];
+    for (const file of files) {
+      const v = verdicts.get(abs(file));
+      if (v?.verdict === "fold" && v.exports) {
+        folded.push({ file: abs(file), exports: ownExports(v.exports, names) });
+        continue;
+      }
+      let text = "";
+      try {
+        text = tree.read(file);
+      } catch {
+        // An unreadable file is still unread; the hook decides whether it matters.
+      }
+      const reason = v?.reason ?? (v?.taintedBy ? `it imports ${v.taintedBy.from}, which does not fold` : "it does not fold");
+      unread.push({ file, text, reason });
+    }
+    entities = collectEntities(folded, dir);
+  } catch (err) {
+    return { outputs: [], gaps: [...gaps, `${m.dir}: its source could not be folded, so its lexicons' outputs were not read (${firstLine(err)})`] };
+  }
+
+  // A reporting lexicon's own build roots (the sql lexicon's `.sql` files) join
+  // the folded entities, as they join a build's. Only these lexicons' hooks
+  // run: they read files, and start nothing.
+  for (const { name, plugin } of reporting) {
+    if (typeof plugin.buildRoots !== "function") continue;
+    const read = readConfigFieldsStatically(dir, [name, "sourceDir"]);
+    const config = read.status === "read" ? read.fields : {};
+    const sourceDir = typeof config.sourceDir === "string" ? join(dir, config.sourceDir) : undefined;
+    try {
+      const contributed = await plugin.buildRoots({ projectRoot: dir, config, entities, ...(sourceDir ? { sourceDir } : {}) });
+      for (const [key, entity] of contributed.entities) if (!entities.has(key)) entities.set(key, entity);
+    } catch (err) {
+      gaps.push(`lexicon "${name}" could not read the member's other source files, so their declarations were not read (${firstLine(err)})`);
+    }
+  }
+
+  const outputs: MemberLexiconOutputs["outputs"] = [];
+  for (const { name, plugin } of reporting) {
+    try {
+      const report = plugin.workspaceOutputs!(entities, unread);
+      if (!report) continue;
+      for (const o of report.outputs) outputs.push({ name: o.name, ...(o.previously?.length ? { previously: o.previously } : {}) });
+      for (const g of report.gaps ?? []) gaps.push(g);
+    } catch (err) {
+      gaps.push(`lexicon "${name}" workspaceOutputs threw, so its outputs were not read (${firstLine(err)})`);
+    }
+  }
+  return { outputs, gaps };
+}

package/src/workspace/links.test.ts

@@ -308,6 +308,28 @@ describe("the graph's links section", () => {
   test("the linked member pairs, for the pipeline checks' environment rule", async () => {
     expect(declaredMemberLinks(decl)).toEqual([{ consumer: "web", producer: "shared" }]);
   });
+
+  test("a link to an output's previous name says what it was renamed to (#3931)", () => {
+    const d = parseDeclaration(
+      declaration([
+        { name: "db", dir: "db", kind: "chant" },
+        { name: "web", dir: "web", kind: "chant", links: [{ member: "db", output: "public.orders.customer_id" }] },
+      ]),
+      "chant.workspace.json",
+    );
+    const [row] = graphLinks(d, {
+      composed: ["db", "web"],
+      exports: [
+        { member: "db", name: "public.orders", node: "db/orders" },
+        { member: "db", name: "public.orders.buyer_id", node: "db/orders", previously: ["public.orders.customer_id"] },
+      ],
+      imports: [],
+    });
+    expect(row).toMatchObject({ status: "missing" });
+    expect(row!.reason).toBe(
+      "db has no output public.orders.customer_id; it was renamed to public.orders.buyer_id, so link to that instead; its outputs: public.orders, public.orders.buyer_id",
+    );
+  });
 });
 
 describe("the declaration's link fields", () => {

package/src/workspace/links.ts

@@ -15,7 +15,11 @@
  * that parameter give way to the declared one, which is how an inferred edge
  * is promoted.
  *
- * Every row says how it was found (`declared` or `inferred:joinKey`), where it
+ * A member whose kind has a link reader (#3932, `./kind-link-readers.ts`) also
+ * states links in its own files, such as a dbt project's sources. Those rows
+ * have origin `kind-reader` and carry the file and line that state them.
+ *
+ * Every row says how it was found (`declared`, `kind-reader` or `inferred:joinKey`), where it
  * resolved (`source`, or `live` for the rows of `check --live`, #2549) and its status. A link that
  * can't be resolved is kept, with the reason.
  *
@@ -30,6 +34,7 @@ import { joinKey, joinLabel, type JoinLabel } from "../join-key";
 import type { Declaration, LinkDeclaration, Member } from "./declaration";
 import type { KindRegistry, MemberKind } from "./kinds";
 import type { MemberCollector } from "./compose-graph";
+import type { KindLinkRead, KindReadLink } from "./kind-link-readers";
 
 /**
  * The link kinds chant knows. Closed: a link of any other kind fails closed.
@@ -46,14 +51,20 @@ export const TELEMETRY_LINK_KIND = "telemetry";
 /** The OTLP protocols a telemetry link may state, as `OTEL_EXPORTER_OTLP_PROTOCOL` names them. */
 export const TELEMETRY_PROTOCOLS = ["grpc", "http/protobuf", "http/json"] as const;
 
-/** How a row was found: written down, or inferred by the named rule. */
-export type LinkOrigin = "declared" | "inferred:joinKey";
+/**
+ * How a row was found: written down in the declaration, read from the
+ * member's own files by its kind's link reader (#3932), or inferred by the
+ * named rule.
+ */
+export type LinkOrigin = "declared" | "kind-reader" | "inferred:joinKey";
 
 /** One output or parameter of a member, as a join sees it. */
 export interface JoinHandle {
   name: string;
   /** The node that holds it, when the reader knows one (a graph IR id). */
   node?: string;
+  /** Names it had before, from a rename hint in the producer's source (#3931). */
+  previously?: readonly string[];
 }
 
 /** What a member offers links, and what it reads. */
@@ -80,6 +91,10 @@ interface RowBase {
   resolves: "source" | "live";
   /** Why the row is not `resolved`, or null. */
   reason: string | null;
+  /** A `kind-reader` row (#3932): the reader, and the file (from the workspace root) and line that state the link. */
+  reader?: string;
+  file?: string;
+  line?: number;
 }
 
 /** A declared link, or an inferred join with one producer. */
@@ -113,7 +128,11 @@ export interface TelemetryTargets {
   composed: ReadonlySet<string>;
 }
 
-/** A parameter that joins outputs of two or more producers (or two outputs of one). */
+/**
+ * A parameter that joins outputs of two or more producers (or two outputs of
+ * one). For a `kind-reader` row whose file names no producer, `input` is the
+ * output it reads, and the candidates are the members that could produce it.
+ */
 export interface AmbiguousRow extends RowBase {
   status: "ambiguous";
   input: string;
@@ -170,9 +189,16 @@ function nearNames(name: string, outputs: JoinHandle[]): string[] {
  * Resolve every declared link and infer the joins nobody wrote down.
  * `handles` holds one entry per member whose handles were read; a member
  * missing from it is unresolved. Declared rows come first, in declaration
- * order; inferred and ambiguous rows follow, sorted by consumer and parameter.
+ * order; then the rows each member's kind reader found (`readLinks`, #3932),
+ * in member and file order; inferred and ambiguous rows follow, sorted by
+ * consumer and parameter.
  */
-export function resolveLinks(declaration: Declaration, handles: ReadonlyMap<string, MemberHandles>, telemetry?: TelemetryTargets): LinkTableRow[] {
+export function resolveLinks(
+  declaration: Declaration,
+  handles: ReadonlyMap<string, MemberHandles>,
+  telemetry?: TelemetryTargets,
+  readLinks?: ReadonlyMap<string, KindLinkRead>,
+): LinkTableRow[] {
   const rows: LinkTableRow[] = [];
   const declaredTargets = new Map<string, Set<string>>();
 
@@ -215,30 +241,18 @@ export function resolveLinks(declaration: Declaration, handles: ReadonlyMap<stri
         row.reason = `protocol applies to telemetry links; this link has kind ${kind}`;
         continue;
       }
-      const producer = handles.get(link.member);
-      const found = producer?.outputs.find((o) => o.name === link.output);
-      if (found) {
-        if (found.node) row.to = found.node;
-        continue;
-      }
-      if (!producer) {
-        row.status = "unresolved";
-        row.reason = `the outputs of ${link.member} were not read`;
-      } else if (producer.exposesNone) {
-        row.status = "missing";
-        row.reason = producer.why ?? `${link.member} exposes no outputs`;
-      } else if (!producer.complete) {
-        row.status = "unresolved";
-        row.reason = `${link.output} was not found in ${link.member}, whose outputs could not all be read in source${producer.why ? ` (${producer.why})` : ""}`;
-      } else {
-        const near = nearNames(link.output, producer.outputs);
-        const known = producer.outputs.map((o) => o.name);
-        row.status = "missing";
-        row.reason =
-          `${link.member} has no output ${link.output}` +
-          (near.length ? `; did you mean ${near.join(" or ")}? Links match exactly` : "") +
-          (known.length ? `; its outputs: ${[...new Set(known)].sort(cmp).join(", ")}` : "; it exposes no outputs");
-      }
+      resolveOutput(row, handles);
+    }
+  }
+
+  // Links a kind's reader found in the member's own files (#3932).
+  for (const consumer of declaration.members) {
+    const read = readLinks?.get(consumer.name);
+    if (!read) continue;
+    for (const link of read.links) {
+      const row = readerRow(declaration, consumer, read, link, handles);
+      rows.push(row);
+      if (row.status !== "ambiguous") (declaredTargets.get(consumer.name) ?? declaredTargets.set(consumer.name, new Set()).get(consumer.name)!).add(`${row.producer}\0${row.output}`);
     }
   }
 
@@ -297,6 +311,85 @@ export function resolveLinks(declaration: Declaration, handles: ReadonlyMap<stri
   return [...rows, ...inferred];
 }
 
+/** Match a declared or reader's output row against its producer's handles, setting its status and reason. */
+function resolveOutput(row: LinkRow, handles: ReadonlyMap<string, MemberHandles>): void {
+  const producer = handles.get(row.producer);
+  const found = producer?.outputs.find((o) => o.name === row.output);
+  if (found) {
+    if (found.node) row.to = found.node;
+    return;
+  }
+  if (!producer) {
+    row.status = "unresolved";
+    row.reason = `the outputs of ${row.producer} were not read`;
+  } else if (producer.exposesNone) {
+    row.status = "missing";
+    row.reason = producer.why ?? `${row.producer} exposes no outputs`;
+  } else if (!producer.complete) {
+    row.status = "unresolved";
+    row.reason = `${row.output} was not found in ${row.producer}, whose outputs could not all be read in source${producer.why ? ` (${producer.why})` : ""}`;
+  } else {
+    const renamed = [...new Set(producer.outputs.filter((o) => o.previously?.includes(row.output)).map((o) => o.name))].sort(cmp);
+    const near = renamed.length ? [] : nearNames(row.output, producer.outputs);
+    const known = producer.outputs.map((o) => o.name);
+    row.status = "missing";
+    row.reason =
+      `${row.producer} has no output ${row.output}` +
+      (renamed.length ? `; it was renamed to ${renamed.join(" or ")}, so link to that instead` : "") +
+      (near.length ? `; did you mean ${near.join(" or ")}? Links match exactly` : "") +
+      (known.length ? `; its outputs: ${[...new Set(known)].sort(cmp).join(", ")}` : "; it exposes no outputs");
+  }
+}
+
+/**
+ * The row for one link a kind's reader found (#3932). A link whose file names
+ * its producer resolves like a declared one. One that doesn't is given the
+ * producer that exposes its anchor (a dbt column's table); when none does,
+ * and exactly one other member exposes outputs at all, that member, so a
+ * dropped table is missing from the only place it could be. Otherwise the
+ * row is ambiguous, and the message names the field that settles it.
+ */
+function readerRow(declaration: Declaration, consumer: Member, read: KindLinkRead, link: KindReadLink, handles: ReadonlyMap<string, MemberHandles>): LinkTableRow {
+  const base = { consumer: consumer.name, kind: DEFAULT_LINK_KIND, origin: "kind-reader" as const, resolves: "source" as const, reader: read.reader, file: link.file, line: link.line };
+  let producer = link.member;
+  if (producer === null) {
+    const anchor = link.anchor ?? link.output;
+    const others = declaration.members.filter((m) => m.name !== consumer.name);
+    const exposing = others.filter((m) => handles.get(m.name)?.outputs.some((o) => o.name === anchor));
+    const possible = others.filter((m) => {
+      const h = handles.get(m.name);
+      return h !== undefined && !h.exposesNone;
+    });
+    if (exposing.length === 1) producer = exposing[0].name;
+    else if (exposing.length === 0 && possible.length === 1) producer = possible[0].name;
+    else {
+      const candidates = (exposing.length > 0 ? exposing : possible).map((m) => ({ producer: m.name, output: link.output, label: "exact" as const }));
+      const field = read.producerField ? `; set fields.${read.producerField} on ${consumer.name} to name it` : "";
+      return {
+        ...base,
+        status: "ambiguous",
+        input: link.output,
+        candidates,
+        reason:
+          exposing.length > 1
+            ? `${link.file}:${link.line} reads ${anchor}, which ${exposing.map((m) => m.name).join(" and ")} all expose${field}`
+            : candidates.length > 0
+              ? `${link.file}:${link.line} reads ${anchor}, which no member exposes, and ${consumer.name} does not say which of ${candidates.map((c) => c.producer).join(", ")} produces it${field}`
+              : `${link.file}:${link.line} reads ${anchor}, and no other member exposes outputs`,
+      };
+    }
+  }
+  const row: LinkRow = { ...base, producer, output: link.output, label: "exact", input: null, status: "resolved", reason: null };
+  const problem = linkTargetProblem(declaration, consumer, { member: producer } as LinkDeclaration);
+  if (problem) {
+    row.status = "invalid";
+    row.reason = read.producerField ? `fields.${read.producerField}: ${problem}` : problem;
+    return row;
+  }
+  resolveOutput(row, handles);
+  return row;
+}
+
 /**
  * Resolve a telemetry link against the producer's collector (#2558): the
  * target exists (presence), and when the link states a protocol, the target
@@ -369,7 +462,7 @@ export interface ComposedHandles {
   composed: readonly string[];
   /** The collectors those members report (#2558); a telemetry link resolves against them. */
   collectors?: readonly MemberCollector[];
-  exports: readonly { member: string; name: string; node?: string }[];
+  exports: readonly { member: string; name: string; node?: string; previously?: readonly string[] }[];
   imports: readonly { member: string; name: string; node: string }[];
 }
 
@@ -384,7 +477,9 @@ export function irMemberHandles(graph: ComposedHandles): Map<string, MemberHandl
   for (const member of graph.composed) {
     out.set(member, {
       member,
-      outputs: graph.exports.filter((e) => e.member === member).map((e) => ({ name: e.name, ...(e.node ? { node: e.node } : {}) })),
+      outputs: graph.exports
+        .filter((e) => e.member === member)
+        .map((e) => ({ name: e.name, ...(e.node ? { node: e.node } : {}), ...(e.previously?.length ? { previously: e.previously } : {}) })),
       inputs: graph.imports.filter((i) => i.member === member).map((i) => ({ name: i.name, node: i.node })),
       complete: true,
       why: null,
@@ -401,7 +496,7 @@ export function irMemberHandles(graph: ComposedHandles): Map<string, MemberHandl
  * With `kinds`, a member that isn't composed but whose kind lists its outputs
  * (`other`, kinds from a package) is a link target too.
  */
-export function graphLinks(declaration: Declaration, graph: ComposedHandles, kinds?: KindRegistry): LinkTableRow[] {
+export function graphLinks(declaration: Declaration, graph: ComposedHandles, kinds?: KindRegistry, readLinks?: ReadonlyMap<string, KindLinkRead>): LinkTableRow[] {
   const handles = irMemberHandles(graph);
   for (const m of declaration.members) {
     const kind = kinds?.get(m.kind);
@@ -413,7 +508,7 @@ export function graphLinks(declaration: Declaration, graph: ComposedHandles, kin
     collectors: new Map((graph.collectors ?? []).map((c) => [c.member, c])),
     composed: new Set(graph.composed),
   };
-  return resolveLinks(declaration, handles, telemetry).map((row) => {
+  return resolveLinks(declaration, handles, telemetry, readLinks).map((row) => {
     if (row.status === "ambiguous" || row.origin !== "declared") return row;
     // The declaration's pointer means nothing to a graph reader.
     const { pointer: _pointer, ...rest } = row;

package/src/workspace/member-handles.ts

@@ -25,6 +25,7 @@ import { isInside, type Declaration, type ResolvedGroup } from "./declaration";
 import type { KindRegistry } from "./kinds";
 import { kindHandles, type MemberHandles } from "./links";
 import { joinPath, skippedDir, type WorkspaceTree } from "./tree";
+import type { MemberLexiconOutputs } from "./lexicon-outputs";
 
 const memberDir = (dir: string) => (dir === "." ? "" : dir);
 
@@ -60,7 +61,7 @@ function isSourceFile(name: string): boolean {
  * directories (other members, group matches), `node_modules`, dot
  * directories and build output.
  */
-function sourceFiles(tree: WorkspaceTree, dir: string, exclude: ReadonlySet<string>): string[] {
+export function sourceFiles(tree: WorkspaceTree, dir: string, exclude: ReadonlySet<string>): string[] {
   const out: string[] = [];
   const walk = (at: string) => {
     for (const e of tree.list(at) ?? []) {
@@ -188,18 +189,35 @@ export function readSourceHandles(tree: WorkspaceTree, dir: string, exclude: Rea
   return out;
 }
 
+/**
+ * The directories inside member `m` that are not its source: other members'
+ * directories and example-group matches nested in it.
+ */
+export function memberExcludes(declaration: Declaration, groups: readonly ResolvedGroup[], m: Declaration["members"][number]): Set<string> {
+  const exclude = new Set<string>();
+  for (const o of declaration.members) if (o !== m && o.dir !== "." && isInside(o.dir, m.dir)) exclude.add(o.dir);
+  for (const g of groups) for (const dir of g.matches) if (isInside(dir, m.dir)) exclude.add(dir);
+  return exclude;
+}
+
 /**
  * Every member's handles, read in source for `chant workspace check`. A
  * `chant` member's outputs and parameters are parsed from its TypeScript
  * without running it; other kinds expose what the kind and the entry list.
  * A member whose directory is missing or whose kind is unknown is left out,
  * so links to it are unresolved.
+ *
+ * `lexiconOutputs` adds what the member's lexicons report about their own
+ * declarations (#3931, `./lexicon-outputs.ts`), gathered beforehand because
+ * reading them folds the member's files, which is asynchronous. Its gaps
+ * count as the member's.
  */
 export function sourceMemberHandles(
   declaration: Declaration,
   tree: WorkspaceTree,
   groups: readonly ResolvedGroup[],
   kinds: KindRegistry,
+  lexiconOutputs?: ReadonlyMap<string, MemberLexiconOutputs>,
 ): Map<string, MemberHandles> {
   const out = new Map<string, MemberHandles>();
   for (const m of declaration.members) {
@@ -210,16 +228,18 @@ export function sourceMemberHandles(
       out.set(m.name, listed);
     } else {
       // Other members' directories and group matches inside this one are not its source.
-      const exclude = new Set<string>();
-      for (const o of declaration.members) if (o !== m && o.dir !== "." && isInside(o.dir, m.dir)) exclude.add(o.dir);
-      for (const g of groups) for (const dir of g.matches) if (isInside(dir, m.dir)) exclude.add(dir);
-      const read = readSourceHandles(tree, memberDir(m.dir), exclude);
+      const read = readSourceHandles(tree, memberDir(m.dir), memberExcludes(declaration, groups, m));
+      const lexicon = lexiconOutputs?.get(m.name);
+      const gaps = [...read.gaps, ...(lexicon?.gaps ?? [])];
       out.set(m.name, {
         member: m.name,
-        outputs: read.outputs.map((o) => ({ name: o.name })),
+        outputs: [
+          ...read.outputs.map((o) => ({ name: o.name })),
+          ...(lexicon?.outputs ?? []).map((o) => ({ name: o.name, ...(o.previously?.length ? { previously: o.previously } : {}) })),
+        ],
         inputs: read.inputs.map((i) => ({ name: i.name })),
-        complete: read.gaps.length === 0,
-        why: read.gaps.length === 0 ? null : read.gaps.length === 1 ? read.gaps[0] : `${read.gaps[0]}, and ${read.gaps.length - 1} more`,
+        complete: gaps.length === 0,
+        why: gaps.length === 0 ? null : gaps.length === 1 ? gaps[0] : `${gaps[0]}, and ${gaps.length - 1} more`,
         exposesNone: false,
       });
     }