@intentius/chant 0.124.45 → 0.124.48

package/src/workspace/kinds.ts

@@ -25,6 +25,7 @@ import { joinPath, skippedDir } from "./tree";
 import { checkPinIntegrity } from "./pin-integrity";
 import { dataExportTarget, findInstalledPackage } from "./class-data";
 import { loadAjv2020 } from "./ajv2020";
+import yaml from "js-yaml";
 
 export const KINDS_SCHEMA_ID = schema.$id;
 
@@ -34,7 +35,9 @@ export const KINDS_SUBPATH = "./workspace-kinds";
 /**
  * The probe a package's kind carries (#2535, #2545). It passes when any of
  * its clauses does. A name in either clause may use `*`, which matches any
- * run of characters in one file name, so `*.tf` is every Terraform file.
+ * run of characters in one file name, so `*.tf` is every Terraform file, and
+ * `[0-9]` matches one digit (#4400), so `[0-9]*_*.sql` is a file that opens
+ * with a version number.
  */
 export interface FileProbe {
   /** A file matching one of these names sits directly in the directory. */
@@ -53,6 +56,13 @@ export interface FileProbe {
    * without claiming every Node package (#3151).
    */
   anyJsonKey?: { in: string[]; pointers: string[] };
+  /**
+   * A file directly in the directory whose name matches one of `in` has a
+   * line that starts, after leading space and ignoring case, with one of
+   * `starts` (#4400). This is how a goose directory is told from any other
+   * directory of `.sql` files: its files carry `-- +goose Up`.
+   */
+  anyLine?: { in: string[]; starts: string[] };
 }
 
 /** A string, integer or boolean field a kind declares for its members (#3151). */
@@ -81,7 +91,9 @@ export type KindProbe =
   /** The directory exists; nothing else is checked (`other`). */
   | { directory: true }
   /** The directory holds a chant project, as {@link holdsChantProject} says (`examples`). */
-  | { chantProject: true };
+  | { chantProject: true }
+  /** Nothing local: the member names another repository's workspace (`repo`, #3168). */
+  | { repo: true };
 
 /**
  * Which outputs a member of a kind exposes as link targets (#2524 D6,
@@ -135,15 +147,38 @@ export interface MemberKind {
    * entry states.
    */
   reader?: KindLinkReaderName;
+  /** A file every member of the kind has, and the JSON Schema it must pass (#3672); unset, the kind checks no member file. */
+  memberFile?: KindMemberFile;
+}
+
+/**
+ * A kind's member file (#3672): `path` in each member's directory must pass
+ * the JSON Schema at `schema` in the supplying package. `chant workspace
+ * check` reads and validates it (WSP012). The schema is read as data when the
+ * package's kinds are read, so a schema that is missing or doesn't compile is
+ * a load problem (WSP002), and `validate` is unset.
+ */
+export interface KindMemberFile {
+  /** The file, relative to the member's directory. */
+  path: string;
+  /** The schema, as the kinds file names it, relative to the package. */
+  schema: string;
+  /** The schema, absolute; unset until the package directory is known. */
+  schemaFile?: string;
+  /** The compiled schema; unset when it could not be read or compiled. */
+  validate?: MemberFileValidate;
 }
 
+/** A compiled member-file schema, in Ajv's shape. */
+export type MemberFileValidate = ((data: unknown) => boolean) & { errors?: { instancePath: string; message?: string; params?: Record<string, unknown> }[] | null };
+
 /**
  * The link readers chant ships (#3932). A kind names one in its kinds file as
  * `reader`. The readers are chant's own code, not the package's: a kinds file
  * stays data, and chant never imports the package that supplies it. Closed:
  * a kind naming another reader is kept without one, and the load reports it.
  */
-export const KIND_LINK_READERS = ["dbt-project"] as const;
+export const KIND_LINK_READERS = ["dbt-project", "goose-dir", "golang-migrate-dir", "clickhouse-migrations-dir", "flyway-dir"] as const;
 export type KindLinkReaderName = (typeof KIND_LINK_READERS)[number];
 
 export interface KindRegistry {
@@ -157,6 +192,9 @@ export interface KindRegistry {
 /** The group kind (ws-051). An entry of this kind is a group, not a member. */
 export const EXAMPLES_KIND = "examples";
 
+/** The member kind that names another repository's workspace by URL and pinned revision (#3168). */
+export const REPO_KIND = "repo";
+
 /** The data member kind that holds design artifacts (#2549, ws-062). */
 export const DESIGN_KIND = "design";
 
@@ -179,6 +217,15 @@ export const BUILTIN_KINDS: readonly MemberKind[] = [
     outputs: { from: "none" },
     source: "builtin",
   },
+  {
+    name: REPO_KIND,
+    description: "another repository's workspace, named by URL and pinned revision; chant reads it through that repository's own chant workspace graph and never writes there",
+    probe: { repo: true },
+    precedence: 0,
+    shape: "member",
+    outputs: { from: "none" },
+    source: "builtin",
+  },
   {
     name: "other",
     description: "a directory chant does not read; the entry says why in `because`",
@@ -232,7 +279,8 @@ export function builtinKindRegistry(): KindRegistry {
 export function probeKind(kind: MemberKind, tree: WorkspaceTree, dir: string): boolean {
   if ("directory" in kind.probe) return true;
   if ("chantProject" in kind.probe) return holdsChantProject(tree, dir);
-  const { anyFile, anyBlock, anyJsonKey } = kind.probe;
+  if ("repo" in kind.probe) return true;
+  const { anyFile, anyBlock, anyJsonKey, anyLine } = kind.probe;
   if (anyFile && filesMatching(tree, dir, anyFile).length > 0) return true;
   if (anyJsonKey) {
     for (const file of filesMatching(tree, dir, anyJsonKey.in)) {
@@ -244,6 +292,16 @@ export function probeKind(kind: MemberKind, tree: WorkspaceTree, dir: string): b
       }
     }
   }
+  if (anyLine) {
+    const starts = anyLine.starts.map((t) => t.toLowerCase());
+    for (const file of filesMatching(tree, dir, anyLine.in)) {
+      try {
+        if (tree.read(file).split(/\r?\n/).some((l) => starts.some((t) => l.trimStart().toLowerCase().startsWith(t)))) return true;
+      } catch {
+        // An unreadable file is no evidence either way.
+      }
+    }
+  }
   if (anyBlock) {
     const opener = new RegExp(`^\\s*(?:${anyBlock.blocks.map(escapeRegExp).join("|")})\\s*\\{`, "m");
     for (const file of filesMatching(tree, dir, anyBlock.in)) {
@@ -259,7 +317,7 @@ export function probeKind(kind: MemberKind, tree: WorkspaceTree, dir: string): b
 
 /** Whether a probe looks at the directory's files, and so can claim it. */
 function isFileProbe(probe: KindProbe): probe is FileProbe {
-  return !("directory" in probe) && !("chantProject" in probe);
+  return !("directory" in probe) && !("chantProject" in probe) && !("repo" in probe);
 }
 
 /**
@@ -274,7 +332,7 @@ function filesMatching(tree: WorkspaceTree, dir: string, names: readonly string[
     if (!name.includes("*") && tree.stat(joinPath(dir, name)) === "file") out.push(joinPath(dir, name));
   }
   if (globs.length > 0) {
-    const patterns = globs.map((g) => new RegExp(`^${g.split("*").map(escapeRegExp).join("[^/]*")}$`));
+    const patterns = globs.map((g) => new RegExp(`^${g.split("*").map((part) => escapeRegExp(part).replace(/\\\[0-9\\\]/g, "[0-9]")).join("[^/]*")}$`));
     for (const e of tree.list(dir) ?? []) {
       if (e.type === "file" && patterns.some((p) => p.test(e.name))) out.push(joinPath(dir, e.name));
     }
@@ -400,7 +458,7 @@ export function parseKindData(text: string, source: string): KindData {
   const problems: string[] = [];
   const kinds: MemberKind[] = [];
   const seen = new Set<string>();
-  for (const k of (raw as { kinds: { name: string; description: string; precedence: number; probe: FileProbe; outputs?: string[]; graph?: KindGraph; fields?: Record<string, KindField>; reader?: string }[] }).kinds) {
+  for (const k of (raw as { kinds: { name: string; description: string; precedence: number; probe: FileProbe; outputs?: string[]; graph?: KindGraph; fields?: Record<string, KindField>; reader?: string; memberFile?: { path: string; schema: string } }[] }).kinds) {
     if (BUILTIN_KIND_NAMES.includes(k.name)) {
       problems.push(`${source}: kind ${k.name} is built in and can't be supplied by a package`);
       continue;
@@ -417,6 +475,7 @@ export function parseKindData(text: string, source: string): KindData {
         ...(k.probe.anyFile ? { anyFile: [...k.probe.anyFile] } : {}),
         ...(k.probe.anyBlock ? { anyBlock: { in: [...k.probe.anyBlock.in], blocks: [...k.probe.anyBlock.blocks] } } : {}),
         ...(k.probe.anyJsonKey ? { anyJsonKey: { in: [...k.probe.anyJsonKey.in], pointers: [...k.probe.anyJsonKey.pointers] } } : {}),
+        ...(k.probe.anyLine ? { anyLine: { in: [...k.probe.anyLine.in], starts: [...k.probe.anyLine.starts] } } : {}),
       },
       precedence: k.precedence,
       shape: "member",
@@ -425,6 +484,7 @@ export function parseKindData(text: string, source: string): KindData {
       ...(k.graph ? { graph: { lexicon: k.graph.lexicon, config: structuredClone(k.graph.config) } } : {}),
       ...(k.fields ? { fields: structuredClone(k.fields) } : {}),
       ...(k.reader && (KIND_LINK_READERS as readonly string[]).includes(k.reader) ? { reader: k.reader as KindLinkReaderName } : {}),
+      ...(k.memberFile ? { memberFile: { path: k.memberFile.path, schema: k.memberFile.schema } } : {}),
     });
     if (k.reader && !(KIND_LINK_READERS as readonly string[]).includes(k.reader)) {
       problems.push(`${source}: kind ${k.name} names link reader ${k.reader}, which this chant does not have (it has ${KIND_LINK_READERS.join(", ")}); the kind is kept, and its members' links are only those their entries state`);
@@ -477,6 +537,10 @@ export function readPackageKinds(packageDir: string, source?: string): PackageKi
   const packageName = typeof pkg.name === "string" ? pkg.name : undefined;
   for (const k of data.kinds) {
     k.packageDir = packageDir;
+    if (k.memberFile) {
+      const problem = loadMemberFileSchema(k.memberFile, packageDir);
+      if (problem) data.problems.push(`${name}: kind ${k.name} ${problem}; members of the kind fail WSP012 until it is fixed`);
+    }
     if (k.graph && packageName !== lexiconPackageName(k.graph.lexicon)) {
       data.problems.push(
         `${name}: kind ${k.name} reads its members with lexicon ${k.graph.lexicon}, which is ${lexiconPackageName(k.graph.lexicon)}, ` +
@@ -488,6 +552,67 @@ export function readPackageKinds(packageDir: string, source?: string): PackageKi
   return { ...data, file };
 }
 
+/**
+ * Read and compile a kind's member-file schema from `packageDir` (#3672),
+ * setting `schemaFile` and `validate`. Returns why it can't be used, or
+ * undefined. The schema is a JSON file inside the package; it is data, so
+ * nothing is imported, and a `$ref` outside the file is not followed.
+ */
+export function loadMemberFileSchema(memberFile: KindMemberFile, packageDir: string): string | undefined {
+  const file = resolve(packageDir, ...memberFile.schema.split("/"));
+  memberFile.schemaFile = file;
+  const inside = relative(packageDir, file);
+  if (inside.startsWith("..") || isAbsolute(inside)) return `names member-file schema ${memberFile.schema}, which is outside the package`;
+  let doc: unknown;
+  try {
+    doc = JSON.parse(readFileSync(file, "utf-8"));
+  } catch (err) {
+    const missing = (err as NodeJS.ErrnoException).code === "ENOENT";
+    return missing ? `names member-file schema ${memberFile.schema}, which does not exist` : `names member-file schema ${memberFile.schema}, which is not JSON (${(err as Error).message})`;
+  }
+  if (doc === null || typeof doc !== "object" || Array.isArray(doc)) return `names member-file schema ${memberFile.schema}, which is not a JSON Schema object`;
+  try {
+    const Ajv = loadAjv2020() as new (opts: object) => { compile(s: object): MemberFileValidate };
+    memberFile.validate = new Ajv({ allErrors: true, strict: false }).compile(doc);
+  } catch (err) {
+    return `names member-file schema ${memberFile.schema}, which does not compile as a draft 2020-12 schema (${(err as Error).message})`;
+  }
+  return undefined;
+}
+
+/** One reason a member's file fails its kind's schema (#3672): a JSON Pointer into the file, and why. */
+export interface MemberFileProblem {
+  pointer: string;
+  message: string;
+}
+
+/**
+ * Check a member's file text against its kind's schema (#3672). `file` is the
+ * file's name, which picks the parser: YAML for `.yml` and `.yaml`, JSON
+ * otherwise. The kind's schema must have loaded; when it didn't, WSP002 has
+ * already said why, and this returns nothing.
+ */
+export function checkMemberFile(memberFile: KindMemberFile, file: string, text: string): MemberFileProblem[] {
+  if (!memberFile.validate) return [];
+  let data: unknown;
+  try {
+    data = /\.ya?ml$/i.test(file) ? yaml.load(text) : JSON.parse(text);
+  } catch (err) {
+    return [{ pointer: "", message: `is not ${/\.ya?ml$/i.test(file) ? "YAML" : "JSON"} (${(err as Error).message.split("\n")[0]})` }];
+  }
+  if (memberFile.validate(data)) return [];
+  const seen = new Set<string>();
+  const out: MemberFileProblem[] = [];
+  for (const e of memberFile.validate.errors ?? []) {
+    const extra = e.params && typeof e.params.additionalProperty === "string" ? ` (${e.params.additionalProperty})` : "";
+    const message = `${e.instancePath || "the file"} ${e.message ?? "is invalid"}${extra}`;
+    if (seen.has(message)) continue;
+    seen.add(message);
+    out.push({ pointer: e.instancePath, message });
+  }
+  return out;
+}
+
 /** The package a lexicon name resolves to. */
 export function lexiconPackageName(lexicon: string): string {
   return `@intentius/chant-lexicon-${lexicon}`;

package/src/workspace/ledger.schema.json

@@ -0,0 +1,158 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/ledger/v1/ledger.schema.json",
+  "title": "chant ledger output",
+  "description": "What `chant ledger <table> --json` prints (#4363): the rows of one ledger on the local chant/lifecycle branch, filtered with typed filters instead of SQL. The tables and columns are the ones `chant query` loads (schema version 1 of its tables); a column chant query keeps as JSON text is an object or array here, and `signed` and `empty` are booleans. It reads the local branch and never fetches. Version 1 of the read contract. Readers ignore fields they do not know; a field is only ever added within a version. The codes are a closed list, each in the one closed list of `reason-codes.ts`.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "type": "object",
+      "description": "The rows that every filter matched. Exit code 0.",
+      "required": [
+        "$schema",
+        "contract",
+        "table",
+        "columns",
+        "at",
+        "filter",
+        "total",
+        "rows",
+        "malformed"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/ledger/v1/ledger.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "table": {
+          "enum": [
+            "resources",
+            "snapshots",
+            "runs",
+            "gates",
+            "deploys",
+            "releases",
+            "cuts"
+          ],
+          "description": "The table read: resources and snapshots from each lexicon's snapshots, runs from the Op run ledgers, gates from _gates/, deploys from <env>/releases.jsonl, releases and cuts from _releases/."
+        },
+        "columns": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The table's columns, in order. Every row has each of them."
+        },
+        "at": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The revision of chant/lifecycle read (--at), as given, or null for the branch tip."
+        },
+        "filter": {
+          "type": "object",
+          "required": [
+            "where",
+            "since"
+          ],
+          "properties": {
+            "where": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Each --where clause, <field><op><value>, as given. Every one held for each row listed."
+            },
+            "since": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "--since as the ISO instant it was read as, or null. The rows whose time column (observed_at, started or timestamp) is at or after it are listed."
+            }
+          }
+        },
+        "total": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Rows in the table before the filter."
+        },
+        "rows": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/row"
+          }
+        },
+        "malformed": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Lines and files of this table that could not be read as their kind, left out of total and rows."
+        }
+      }
+    },
+    "row": {
+      "type": "object",
+      "description": "One row, keyed by column. Every row starts with member: the workspace member whose ledger it came from, or null outside a workspace. A value is a string, a number, a boolean, an object or array (a JSON column), or null.",
+      "required": [
+        "member"
+      ],
+      "additionalProperties": {
+        "type": [
+          "string",
+          "number",
+          "boolean",
+          "object",
+          "array",
+          "null"
+        ]
+      }
+    },
+    "failure": {
+      "type": "object",
+      "description": "Nothing was read. Exit code 1.",
+      "required": [
+        "$schema",
+        "contract",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/ledger/v1/ledger.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "filter-invalid",
+                "table-unknown",
+                "revision-unknown",
+                "ledger-unreadable"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/src/workspace/lexicon-outputs.ts

@@ -24,17 +24,24 @@
  *
  * Under `--at` the revision's files are not on disk to fold, so a member
  * whose lexicons report outputs gets a gap instead.
+ *
+ * The consumer side works the same way (#4397): a lexicon's `workspaceLinks`
+ * hook names the outputs of other members its declarations read, such as
+ * the tables an otel `clickhouse` exporter writes. {@link gatherLexiconLinks}
+ * folds every member whose lexicons have the hook and hands back what they
+ * report, in the shape a kind's link reader returns (`./kind-link-readers.ts`),
+ * so `resolveLinks` checks those links like a dbt project's sources.
  */
 
 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 { LexiconUnreadSource, LexiconWorkspaceLinks, 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 { readKindLinks, type KindLinkRead } from "./kind-link-readers";
 import { memberExcludes, sourceFiles } from "./member-handles";
 import { memberDirOnDisk } from "./lexicon-symbols";
 import type { WorkspaceTree } from "./tree";
@@ -51,6 +58,7 @@ export interface OutputsPlugin {
   intrinsics?: () => IntrinsicDef[];
   buildRoots?: (ctx: BuildRootContext) => Promise<BuildRootContribution>;
   workspaceOutputs?: (entities: ReadonlyMap<string, Declarable>, unread?: readonly LexiconUnreadSource[]) => { outputs: LexiconWorkspaceOutput[]; gaps?: string[] } | undefined;
+  workspaceLinks?: (entities: ReadonlyMap<string, Declarable>, unread?: readonly LexiconUnreadSource[]) => LexiconWorkspaceLinks | undefined;
 }
 
 /** Loads a lexicon plugin by name; `loadPlugin` from the CLI unless a test swaps it. */
@@ -60,6 +68,8 @@ 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;
+  /** Links the members' lexicons read (#4397), from {@link gatherLexiconLinks}: the members they target are read too. */
+  lexiconLinks?: ReadonlyMap<string, KindLinkRead>;
 }
 
 const firstLine = (err: unknown): string => (err instanceof Error ? err.message : String(err)).split("\n")[0];
@@ -134,7 +144,7 @@ export async function gatherLexiconOutputs(
   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 [consumer, read] of [...readKindLinks(declaration, tree, kinds), ...(options.lexiconLinks ?? new Map<string, KindLinkRead>())]) {
     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);
@@ -165,14 +175,36 @@ function importedLexicons(tree: WorkspaceTree, files: readonly string[]): string
   return [...names].sort();
 }
 
-async function readMemberLexiconOutputs(
+type Hook = "workspaceOutputs" | "workspaceLinks";
+
+/** A member's source folded for the lexicons that have `hook`, or why it wasn't. */
+type FoldedMember =
+  | { status: "none" }
+  | { status: "gaps"; gaps: string[] }
+  | {
+      status: "folded";
+      reporting: { name: string; plugin: OutputsPlugin }[];
+      entities: Map<string, Declarable>;
+      unread: LexiconUnreadSource[];
+      gaps: string[];
+      /** The tree-relative file that exports each entity, and that file's text. */
+      sourceOf: (entity: Declarable) => { file: string; text: string } | undefined;
+    };
+
+/**
+ * Fold one member's source for the lexicons that implement `hook`, never
+ * running it. "none" when no lexicon of the member's has the hook.
+ */
+async function foldMember(
   root: string,
   declaration: Declaration,
   tree: WorkspaceTree,
   groups: readonly ResolvedGroup[],
   m: Declaration["members"][number],
   options: GatherLexiconOutputsOptions,
-): Promise<MemberLexiconOutputs | undefined> {
+  hook: Hook,
+): Promise<FoldedMember> {
+  const what = hook === "workspaceOutputs" ? "outputs" : "links";
   const dir = memberDirOnDisk(root, m.dir);
   const { readConfigFieldsStatically } = await import("../config-static");
   const files = withinSourceDir(
@@ -188,7 +220,7 @@ async function readMemberLexiconOutputs(
     // source imports stand in for the ones it names.
     names = importedLexicons(tree, files);
   }
-  if (names.length === 0) return undefined;
+  if (names.length === 0) return { status: "none" };
   const load = options.load ?? ((await import("../cli/plugins")).loadPlugin as unknown as OutputsPluginLoader);
   const plugins: { name: string; plugin: OutputsPlugin }[] = [];
   const gaps: string[] = [];
@@ -196,13 +228,13 @@ async function readMemberLexiconOutputs(
     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)})`);
+      gaps.push(`lexicon "${name}" could not be loaded, so the ${what} 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;
+  const reporting = plugins.filter((p) => typeof p.plugin[hook] === "function");
+  if (reporting.length === 0) return gaps.length && hook === "workspaceOutputs" ? { status: "gaps", gaps } : { status: "none" };
   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`] };
+    return { status: "gaps", gaps: [`the ${what} 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.
@@ -216,15 +248,15 @@ async function readMemberLexiconOutputs(
   });
   let entities: Map<string, Declarable> = new Map();
   const unread: LexiconUnreadSource[] = [];
+  const folded: { file: string; rel: string; exports: Record<string, unknown> }[] = [];
   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) });
+        folded.push({ file: abs(file), rel: file, exports: ownExports(v.exports, names) });
         continue;
       }
       let text = "";
@@ -238,7 +270,7 @@ async function readMemberLexiconOutputs(
     }
     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)})`] };
+    return { status: "gaps", gaps: [...gaps, `${m.dir}: its source could not be folded, so its lexicons' ${what} were not read (${firstLine(err)})`] };
   }
 
   // A reporting lexicon's own build roots (the sql lexicon's `.sql` files) join
@@ -257,6 +289,32 @@ async function readMemberLexiconOutputs(
     }
   }
 
+  const sourceOf = (entity: Declarable) => {
+    const f = folded.find((x) => Object.values(x.exports).includes(entity));
+    if (!f) return undefined;
+    let text = "";
+    try {
+      text = tree.read(f.rel);
+    } catch {
+      // The line falls back to 1.
+    }
+    return { file: f.rel, text };
+  };
+  return { status: "folded", reporting, entities, unread, gaps, sourceOf };
+}
+
+async function readMemberLexiconOutputs(
+  root: string,
+  declaration: Declaration,
+  tree: WorkspaceTree,
+  groups: readonly ResolvedGroup[],
+  m: Declaration["members"][number],
+  options: GatherLexiconOutputsOptions,
+): Promise<MemberLexiconOutputs | undefined> {
+  const member = await foldMember(root, declaration, tree, groups, m, options, "workspaceOutputs");
+  if (member.status === "none") return undefined;
+  if (member.status === "gaps") return { outputs: [], gaps: member.gaps };
+  const { reporting, entities, unread, gaps } = member;
   const outputs: MemberLexiconOutputs["outputs"] = [];
   for (const { name, plugin } of reporting) {
     try {
@@ -270,3 +328,64 @@ async function readMemberLexiconOutputs(
   }
   return { outputs, gaps };
 }
+
+/** The line of `export const <name>` (or any declaration of it) in `text`, from 1; 1 when not found. */
+function declarationLine(text: string, name: string): number {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const at = text.search(new RegExp(`\\b(?:const|let|var|function|class)\\s+${escaped}\\b`));
+  return at < 0 ? 1 : text.slice(0, at).split("\n").length;
+}
+
+/**
+ * The links each `chant` member's lexicons read from its declarations
+ * (#4397), keyed by member name, in the shape a kind's link reader returns.
+ * Only members with a lexicon that has a `workspaceLinks` hook are folded. A
+ * link carries the file and line of the declaration that states it, and the
+ * reader is named `lexicon <name>`.
+ */
+export async function gatherLexiconLinks(
+  root: string,
+  declaration: Declaration,
+  tree: WorkspaceTree,
+  groups: readonly ResolvedGroup[],
+  kinds: KindRegistry,
+  options: GatherLexiconOutputsOptions = {},
+): Promise<Map<string, KindLinkRead>> {
+  const out = new Map<string, KindLinkRead>();
+  for (const m of declaration.members) {
+    const kind = kinds.get(m.kind);
+    if (!kind || kindHandles(m, kind) || tree.stat(memberDir(m.dir)) !== "dir") continue;
+    const member = await foldMember(root, declaration, tree, groups, m, options, "workspaceLinks");
+    if (member.status === "none") continue;
+    const where = memberDir(m.dir) || ".";
+    if (member.status === "gaps") {
+      out.set(m.name, { reader: "lexicon", links: [], gaps: member.gaps.map((message) => ({ file: where, line: 1, message })) });
+      continue;
+    }
+    for (const { name, plugin } of member.reporting) {
+      const read: KindLinkRead = { reader: `lexicon ${name}`, links: [], gaps: member.gaps.map((message) => ({ file: where, line: 1, message })) };
+      try {
+        const report = plugin.workspaceLinks!(member.entities, member.unread);
+        if (!report) continue;
+        for (const l of report.links) {
+          const entity = member.entities.get(l.entity);
+          const src = entity ? member.sourceOf(entity) : undefined;
+          read.links.push({
+            member: l.member ?? null,
+            output: l.output,
+            ...(l.anchor ? { anchor: l.anchor } : {}),
+            file: src?.file ?? where,
+            line: src ? declarationLine(src.text, l.entity.split(".").pop() ?? l.entity) : 1,
+          });
+        }
+        for (const g of report.gaps ?? []) read.gaps.push({ file: where, line: 1, message: g });
+      } catch (err) {
+        read.gaps.push({ file: where, line: 1, message: `lexicon "${name}" workspaceLinks threw, so its links were not read (${firstLine(err)})` });
+      }
+      if (read.links.length === 0 && read.gaps.length === 0) continue;
+      const prev = out.get(m.name);
+      out.set(m.name, prev ? { reader: prev.reader, links: [...prev.links, ...read.links], gaps: [...prev.gaps, ...read.gaps] } : read);
+    }
+  }
+  return out;
+}