@intentius/chant 0.124.21 → 0.124.23

package/src/workspace/dbt-project-reader.ts

@@ -0,0 +1,291 @@
+/**
+ * The `dbt-project` link reader (#3932): a dbt project's sources, as links to
+ * the tables and columns a sql member exposes (#3931).
+ *
+ * The reader parses YAML and nothing else. It never runs dbt, never renders
+ * Jinja and never reads `profiles.yml` or a target, so the links it derives
+ * are the same in every environment.
+ *
+ * - The project is `dbt_project.yml`. Sources are read from every `.yml` and
+ *   `.yaml` file under its `model-paths` (`source-paths` in older projects;
+ *   `models` when it names neither), as dbt reads them.
+ * - Each enabled source table links to `<schema>.<table>`, and each of its
+ *   `columns` to `<schema>.<table>.<column>`. The schema is the source's
+ *   `schema`, or the source's `name` when it sets none, which is dbt's own
+ *   fallback. The table is its `identifier`, or its `name`. `database` is not
+ *   part of the name: a Postgres output has none, and dbt-clickhouse reads a
+ *   source's `schema` as the ClickHouse database.
+ * - Case follows the member's `dialect` field. For `postgres`, an unquoted
+ *   name folds to lowercase and a quoted one keeps its case. dbt quotes a
+ *   source's schema and identifier on Postgres unless `quoting:` (in
+ *   `dbt_project.yml`, on the source, or on the table) turns it off, and a
+ *   column is quoted only with `quote: true`. For `clickhouse`, names are
+ *   kept as written.
+ * - A value that is a Jinja template (`{{ ... }}` or `{% ... %}`) is not
+ *   resolved: the reader records a gap and leaves that source, table or
+ *   column out, rather than guess what a target would render.
+ * - The producer is the member the `sqlMember` field names. Unset, each link
+ *   leaves the producer to `resolveLinks`, which picks the one member that
+ *   exposes the table.
+ */
+
+import { posix } from "node:path";
+import { parseYAMLDocument, YAMLParseError } from "../yaml";
+import type { KindLinkRead, KindReadGap, KindReadLink, KindReaderInput } from "./kind-link-readers";
+import { joinPath, skippedDir, type WorkspaceTree } from "./tree";
+
+export const DBT_PROJECT_FILE = "dbt_project.yml";
+const DEFAULT_MODEL_PATHS = ["models"];
+
+/** The dialects whose naming the reader follows; the member's `dialect` field picks one. */
+export const DBT_DIALECTS = ["postgres", "clickhouse"] as const;
+type Dialect = (typeof DBT_DIALECTS)[number];
+
+interface Quoting {
+  schema: boolean;
+  identifier: boolean;
+}
+
+const isTemplated = (v: string) => /\{\{|\{%/.test(v);
+const isObject = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === "object" && !Array.isArray(v);
+
+export function readDbtProject(input: KindReaderInput): KindLinkRead {
+  const { dir, tree, fields } = input;
+  const links: KindReadLink[] = [];
+  const gaps: KindReadGap[] = [];
+  const result: KindLinkRead = { reader: "dbt-project", links, gaps, producerField: "sqlMember" };
+  const projectFile = joinPath(dir, DBT_PROJECT_FILE);
+
+  const producer = typeof fields?.sqlMember === "string" && fields.sqlMember !== "" ? fields.sqlMember : null;
+  const dialect: Dialect = fields?.dialect === "clickhouse" ? "clickhouse" : "postgres";
+
+  let project: unknown;
+  try {
+    project = parseYAMLDocument(tree.read(projectFile));
+  } catch (err) {
+    gaps.push({ file: projectFile, line: err instanceof YAMLParseError ? err.line : 1, message: `${DBT_PROJECT_FILE} could not be read (${(err as Error).message}), so no source was read` });
+    return result;
+  }
+  if (!isObject(project)) {
+    gaps.push({ file: projectFile, line: 1, message: `${DBT_PROJECT_FILE} is not a mapping, so no source was read` });
+    return result;
+  }
+  const projectLines = lines(tree.read(projectFile));
+
+  // Where sources live: model-paths, or the older source-paths.
+  const key = project["model-paths"] !== undefined ? "model-paths" : project["source-paths"] !== undefined ? "source-paths" : null;
+  const rawPaths = key ? project[key] : DEFAULT_MODEL_PATHS;
+  const paths: string[] = [];
+  if (!Array.isArray(rawPaths)) {
+    gaps.push({ file: projectFile, line: keyLine(projectLines, key ?? ""), message: `${key} is not a list, so no source was read` });
+    return result;
+  }
+  for (const p of rawPaths) {
+    if (typeof p !== "string" || isTemplated(p)) {
+      gaps.push({ file: projectFile, line: keyLine(projectLines, key ?? ""), message: `${key} entry ${JSON.stringify(p)} is not a plain path; its sources were not read` });
+      continue;
+    }
+    const at = posix.normalize(joinPath(dir, p));
+    if (at.startsWith("../") || at === ".." || posix.isAbsolute(p)) {
+      gaps.push({ file: projectFile, line: keyLine(projectLines, key ?? ""), message: `${key} entry ${p} lies outside the workspace; its sources were not read` });
+      continue;
+    }
+    paths.push(at === "." ? "" : at);
+  }
+
+  const quoting = readQuoting({ schema: true, identifier: true }, project.quoting, projectFile, keyLine(projectLines, "quoting"), "dbt_project.yml quoting", gaps);
+
+  const files = new Set<string>();
+  for (const p of paths) for (const f of yamlFiles(tree, p)) files.add(f);
+  const name = (v: string, quoted: boolean) => (dialect === "postgres" && !quoted ? v.toLowerCase() : v);
+
+  for (const file of [...files].sort()) {
+    let text: string;
+    let doc: unknown;
+    try {
+      text = tree.read(file);
+      doc = parseYAMLDocument(text);
+    } catch (err) {
+      gaps.push({ file, line: err instanceof YAMLParseError ? err.line : 1, message: `the file could not be read as YAML (${(err as Error).message}); any sources in it were not read` });
+      continue;
+    }
+    if (!isObject(doc) || doc.sources === undefined || doc.sources === null) continue;
+    const fileLines = lines(text);
+    const sourcesLine = keyLine(fileLines, "sources");
+    if (!Array.isArray(doc.sources)) {
+      gaps.push({ file, line: sourcesLine, message: "sources is not a list; its sources were not read" });
+      continue;
+    }
+    let cursor = sourcesLine;
+    for (const source of doc.sources) {
+      if (!isObject(source)) continue;
+      const sourceName = scalar(source.name);
+      const sourceLine = nameLine(fileLines, sourceName, cursor);
+      cursor = sourceLine;
+      if (sourceName === undefined) {
+        gaps.push({ file, line: sourceLine, message: "a source has no name; its tables were not read" });
+        continue;
+      }
+      const where = `source ${sourceName}`;
+      if (isTemplated(sourceName)) {
+        gaps.push({ file, line: sourceLine, message: `${where}: its name is a Jinja template, which chant does not render; its tables were not read` });
+        continue;
+      }
+      const enabled = readEnabled(source, file, sourceLine, where, gaps);
+      if (enabled !== true) continue;
+      const schema = source.schema === undefined || source.schema === null ? sourceName : scalar(source.schema);
+      if (schema === undefined || isTemplated(schema)) {
+        gaps.push({
+          file,
+          line: valueLine(fileLines, "schema", sourceLine),
+          message: `${where}: schema ${JSON.stringify(source.schema)} is a Jinja template or not a name; chant reads names as declared and never renders them for a target, so its tables were not read`,
+        });
+        continue;
+      }
+      const sourceQuoting = readQuoting(quoting, source.quoting, file, sourceLine, `${where} quoting`, gaps);
+      if (source.tables === undefined || source.tables === null) continue;
+      if (!Array.isArray(source.tables)) {
+        gaps.push({ file, line: sourceLine, message: `${where}: tables is not a list; its tables were not read` });
+        continue;
+      }
+      let tableCursor = sourceLine;
+      for (const table of source.tables) {
+        if (!isObject(table)) continue;
+        const tableName = scalar(table.name);
+        const tableLine = nameLine(fileLines, tableName, tableCursor);
+        tableCursor = tableLine;
+        if (tableName === undefined) {
+          gaps.push({ file, line: tableLine, message: `${where}: a table has no name; it was not read` });
+          continue;
+        }
+        const tableWhere = `${where} table ${tableName}`;
+        if (isTemplated(tableName)) {
+          gaps.push({ file, line: tableLine, message: `${tableWhere}: its name is a Jinja template, which chant does not render; it was not read` });
+          continue;
+        }
+        if (readEnabled(table, file, tableLine, tableWhere, gaps) !== true) continue;
+        const identifier = table.identifier === undefined || table.identifier === null ? tableName : scalar(table.identifier);
+        if (identifier === undefined || isTemplated(identifier)) {
+          gaps.push({
+            file,
+            line: valueLine(fileLines, "identifier", tableLine),
+            message: `${tableWhere}: identifier ${JSON.stringify(table.identifier)} is a Jinja template or not a name, which chant does not render; it was not read`,
+          });
+          continue;
+        }
+        const q = readQuoting(sourceQuoting, table.quoting, file, tableLine, `${tableWhere} quoting`, gaps);
+        const tableOutput = `${name(schema, q.schema)}.${name(identifier, q.identifier)}`;
+        links.push({ member: producer, output: tableOutput, file, line: tableLine });
+        if (table.columns === undefined || table.columns === null) continue;
+        if (!Array.isArray(table.columns)) {
+          gaps.push({ file, line: tableLine, message: `${tableWhere}: columns is not a list; its columns were not read` });
+          continue;
+        }
+        let columnCursor = tableLine;
+        for (const column of table.columns) {
+          if (!isObject(column)) continue;
+          const columnName = scalar(column.name);
+          const columnLine = nameLine(fileLines, columnName, columnCursor);
+          columnCursor = columnLine;
+          if (columnName === undefined || isTemplated(columnName)) {
+            gaps.push({ file, line: columnLine, message: `${tableWhere}: column ${JSON.stringify(column.name)} is a Jinja template or not a name, which chant does not render; it was not read` });
+            continue;
+          }
+          const quoted = column.quote === true;
+          links.push({ member: producer, output: `${tableOutput}.${name(columnName, quoted)}`, anchor: tableOutput, file, line: columnLine });
+        }
+      }
+    }
+  }
+  return result;
+}
+
+/** A name as text: a string, or a number or boolean YAML read as one. */
+function scalar(v: unknown): string | undefined {
+  if (typeof v === "string") return v;
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  return undefined;
+}
+
+/** Whether an entry is enabled: `enabled`, or `config.enabled`. A templated value is a gap, and the entry is left out. */
+function readEnabled(entry: Record<string, unknown>, file: string, line: number, where: string, gaps: KindReadGap[]): boolean {
+  const config = isObject(entry.config) ? entry.config : {};
+  const raw = entry.enabled ?? config.enabled;
+  if (raw === undefined || raw === null || raw === true) return true;
+  if (raw === false) return false;
+  gaps.push({ file, line, message: `${where}: enabled is ${JSON.stringify(raw)}, which chant does not render; it was not read` });
+  return false;
+}
+
+/** `base` with a `quoting:` block's schema and identifier applied. A value that isn't a boolean is a gap and keeps the base. */
+function readQuoting(base: Quoting, raw: unknown, file: string, line: number, where: string, gaps: KindReadGap[]): Quoting {
+  if (raw === undefined || raw === null) return base;
+  if (!isObject(raw)) {
+    gaps.push({ file, line, message: `${where} is not a mapping; the quoting above it applies` });
+    return base;
+  }
+  const out = { ...base };
+  for (const key of ["schema", "identifier"] as const) {
+    const v = raw[key];
+    if (v === undefined) continue;
+    if (typeof v === "boolean") out[key] = v;
+    else gaps.push({ file, line, message: `${where}.${key} is ${JSON.stringify(v)}, not true or false; the quoting above it applies` });
+  }
+  return out;
+}
+
+/** Every `.yml` and `.yaml` file under tree-relative directory `dir`, skipping dot directories and node_modules. */
+function yamlFiles(tree: WorkspaceTree, dir: string): string[] {
+  if (dir !== "" && tree.stat(dir) !== "dir") return [];
+  const out: string[] = [];
+  const walk = (at: string) => {
+    for (const e of tree.list(at) ?? []) {
+      const path = joinPath(at, e.name);
+      if (e.type === "dir") {
+        if (!skippedDir(e.name)) walk(path);
+      } else if (/\.ya?ml$/.test(e.name)) {
+        out.push(path);
+      }
+    }
+  };
+  walk(dir);
+  return out;
+}
+
+function lines(text: string): string[] {
+  return text.replace(/\r\n/g, "\n").split("\n");
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** The line (from 1) of top-level key `key`, or 1. */
+function keyLine(fileLines: string[], key: string): number {
+  const re = new RegExp(`^${escapeRegExp(key)}\\s*:`);
+  const i = fileLines.findIndex((l) => re.test(l));
+  return i < 0 ? 1 : i + 1;
+}
+
+/**
+ * The line of the first `name: <value>` entry after line `from`, or `from`
+ * itself. Sources, tables and columns are listed in file order, so
+ * searching on from the parent's line finds each one's own line. A file in
+ * flow style has no such lines, and its entries are reported at the parent.
+ */
+function nameLine(fileLines: string[], value: string | undefined, from: number): number {
+  return value === undefined ? from : valueLineOf(fileLines, "name", value, from);
+}
+
+/** The line of the first `<key>:` after line `from`, or `from`. */
+function valueLine(fileLines: string[], key: string, from: number): number {
+  const re = new RegExp(`^\\s*(?:-\\s+)?${escapeRegExp(key)}\\s*:`);
+  for (let i = Math.max(from, 0); i < fileLines.length; i++) if (re.test(fileLines[i])) return i + 1;
+  return from;
+}
+
+function valueLineOf(fileLines: string[], key: string, value: string, from: number): number {
+  const re = new RegExp(`^\\s*(?:-\\s+)?${escapeRegExp(key)}\\s*:\\s*(["']?)${escapeRegExp(value)}\\1\\s*(?:#.*)?$`);
+  for (let i = Math.max(from, 0); i < fileLines.length; i++) if (re.test(fileLines[i])) return i + 1;
+  return from;
+}

package/src/workspace/graph-cli.ts

@@ -36,6 +36,7 @@ import { openGraphCache, splitCached, storeReads, withoutUnits } from "./graph-c
 import { readDeclaration, readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError, type ErrorLocation } from "./declaration";
 import { describePlan, emitDocument, executePlan, memberStatus, planJson, planMembers, type MemberPlan, type Toolchain, type UnitResult } from "./member-commands";
 import { loadKindRegistry } from "./kinds";
+import { readKindLinks } from "./kind-link-readers";
 import { prepareKindReaders, type PreparedReaders } from "./kind-readers";
 import { recordLinkRows } from "./record-assets";
 import { RecordReadError } from "./records";
@@ -258,7 +259,8 @@ export async function workspaceGraph(query: GraphQuery): Promise<GraphResult> {
       member.stamp = split?.stamps.get(member.name) ?? null;
     }
     // Links (#2539) resolve against the declaration that was read, the revision's for --at, and the kinds installed now.
-    const graph = composeWorkspaceGraph({ name: declaration.name, root: located.root }, inputs, { declaration, kinds });
+    // A kind's link reader (#3932) reads the member's files in the tree read, as check does.
+    const graph = composeWorkspaceGraph({ name: declaration.name, root: located.root }, inputs, { declaration, kinds, read: readKindLinks(declaration, located.tree, kinds) });
     // The box's factory and listing (#3146), from the declaration read, so --at gives them at that revision.
     for (const member of graph.members) member.box = graphBox(declaration.members.find((m) => m.name === member.name)?.box ?? null, located.tree, declaration.members);
     // Nested workspaces (#2551, ws-071): read-only, through their own chant workspace graph.

package/src/workspace/graph.schema.json

@@ -181,6 +181,13 @@
               },
               "member": {
                 "type": "string"
+              },
+              "previously": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Names this output had before, from a rename hint a lexicon read in the member's source (a sql `-- previously:` comment). A link to one of them is told the new name."
               }
             }
           }
@@ -636,8 +643,23 @@
             "origin": {
               "enum": [
                 "declared",
+                "kind-reader",
                 "inferred:joinKey"
-              ]
+              ],
+              "description": "How the row was found: declared in chant.workspace.json, read from the member's own files by its kind's link reader (#3932), or inferred by joinKey()."
+            },
+            "reader": {
+              "type": "string",
+              "description": "A kind-reader row (#3932): the link reader that found it, such as dbt-project."
+            },
+            "file": {
+              "type": "string",
+              "description": "A kind-reader row (#3932): the file that states the link, from the workspace root."
+            },
+            "line": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "A kind-reader row (#3932): the line of file that states the link."
             },
             "resolves": {
               "const": "source"
@@ -728,8 +750,23 @@
             "origin": {
               "enum": [
                 "declared",
+                "kind-reader",
                 "inferred:joinKey"
-              ]
+              ],
+              "description": "How the row was found: declared in chant.workspace.json, read from the member's own files by its kind's link reader (#3932), or inferred by joinKey()."
+            },
+            "reader": {
+              "type": "string",
+              "description": "A kind-reader row (#3932): the link reader that found it, such as dbt-project."
+            },
+            "file": {
+              "type": "string",
+              "description": "A kind-reader row (#3932): the file that states the link, from the workspace root."
+            },
+            "line": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "A kind-reader row (#3932): the line of file that states the link."
             },
             "resolves": {
               "const": "source"
@@ -746,7 +783,8 @@
               "description": "The consumer's parameter node, when known."
             },
             "input": {
-              "type": "string"
+              "type": "string",
+              "description": "The consumer's parameter the join would feed; for a kind-reader row (#3932), the output its file reads, which no single member was found to produce."
             },
             "status": {
               "const": "ambiguous"

package/src/workspace/intent.ts

@@ -77,7 +77,7 @@ import { followSquashes, squashLineOrigins, type Forge, type SquashFollow } from
 import { memberDirOnDisk, memberSymbolResolvers, type SymbolPluginLoader } from "./lexicon-symbols";
 import { resolveSymbol, symbolResolverFor, type SymbolResolver } from "./symbols";
 import { readTrailerJoins, type CommitTrailerJoins } from "./trailer-joins";
-import { joinPath, skippedDir, type WorkspaceTree } from "./tree";
+import { joinPath, skippedDir, workingTree, type WorkspaceTree } from "./tree";
 import { activeAttestors, type ProvenanceLevel } from "./trust/attestor";
 import { commitProvenance, policyAtBase, resolveBase } from "./trust/provenance";
 import { locateWorkspace, type LocatedWorkspace } from "./which-chant";
@@ -1722,7 +1722,12 @@ async function walk(query: IntentQuery, head: Head): Promise<IntentResult> {
     try {
       const groups = resolveGroups(declaration, located.tree);
       const kindsRegistry = loadKindRegistry(declaration.pins, located.rootOnDisk).registry;
-      rows = resolveLinks(declaration, sourceMemberHandles(declaration, located.tree, groups, kindsRegistry)).filter((r) => r.origin === "declared");
+      const { gatherLexiconOutputs } = await import("./lexicon-outputs");
+      const lexiconOutputs = await gatherLexiconOutputs(located.rootOnDisk, declaration, located.at ? workingTree(located.rootOnDisk) : located.tree, groups, kindsRegistry, {
+        atRevision: located.at !== null,
+        ...(query.loadLexicon ? { load: query.loadLexicon as unknown as import("./lexicon-outputs").OutputsPluginLoader } : {}),
+      });
+      rows = resolveLinks(declaration, sourceMemberHandles(declaration, located.tree, groups, kindsRegistry, lexiconOutputs)).filter((r) => r.origin === "declared");
     } catch (err) {
       if (!(err instanceof WorkspaceReadError)) throw err;
     }

package/src/workspace/kind-link-readers.ts

@@ -0,0 +1,109 @@
+/**
+ * Links a kind reads from its member's own files (#3932).
+ *
+ * A member's links usually come from its entry in `chant.workspace.json`, or
+ * are inferred from a chant member's parameters by `joinKey()`. Some members
+ * already say what they read in files of their own: a dbt project names the
+ * tables it reads in its `sources:` YAML. A kind can name a link reader in its
+ * kinds file (`reader`), and chant runs that reader over the member's
+ * directory to derive the member's links.
+ *
+ * The readers are chant's code, listed in {@link KIND_LINK_READERS}: a kinds
+ * file stays data, and chant never imports the package that supplies it. A
+ * reader runs offline and parses files as data. It never invokes the tool
+ * whose files it reads, so `chant workspace check` keeps its promise of no
+ * network and no member code.
+ *
+ * A reader returns links with the file and line that state them, and gaps:
+ * the places it could not read without guessing, such as a templated value.
+ * `resolveLinks` (`./links.ts`) resolves the links beside the declared ones,
+ * with origin `kind-reader`; WSP093 and WSP094 name the reader's file and line,
+ * and WSP099 reports the gaps.
+ */
+
+import type { Declaration, Member } from "./declaration";
+import { resolveMemberFields, type FieldValue, type KindLinkReaderName, type KindRegistry } from "./kinds";
+import type { WorkspaceTree } from "./tree";
+import { readDbtProject } from "./dbt-project-reader";
+
+/** One link a reader found in the member's files. */
+export interface KindReadLink {
+  /**
+   * The producer the link names, or null when the member's files don't say
+   * which member produces it. A null producer is found among the members
+   * whose outputs include {@link anchor}; see `resolveLinks`.
+   */
+  member: string | null;
+  /** The producer's output the link reads. */
+  output: string;
+  /**
+   * The output that picks the producer when `member` is null; unset, the
+   * output itself. A dbt source column is anchored on its table, so a dropped
+   * column is missing from the member that still has the table.
+   */
+  anchor?: string;
+  /** The file that states the link, relative to the workspace root. */
+  file: string;
+  /** Its line, from 1. */
+  line: number;
+}
+
+/** A place the reader could not read without guessing. The links it would have stated are left out. */
+export interface KindReadGap {
+  /** Relative to the workspace root. */
+  file: string;
+  line: number;
+  message: string;
+}
+
+export interface KindLinkRead {
+  /** The reader that ran. */
+  reader: KindLinkReaderName;
+  links: KindReadLink[];
+  gaps: KindReadGap[];
+  /**
+   * The member field that names the producer, for messages that ask the
+   * author to set it when the files don't say (`sqlMember` for dbt).
+   */
+  producerField?: string;
+}
+
+/** What a reader gets: the member, its directory and resolved fields, and the tree read. */
+export interface KindReaderInput {
+  member: Member;
+  /** The member's directory, tree-relative; "" for the workspace root. */
+  dir: string;
+  /** The member's fields, defaults filled in (#3151); null when its kind declares none. */
+  fields: Record<string, FieldValue | null | Record<string, FieldValue | null>> | null;
+  tree: WorkspaceTree;
+}
+
+export type KindLinkReader = (input: KindReaderInput) => KindLinkRead;
+
+/** Every reader chant ships, by the name a kinds file uses. */
+export const LINK_READERS: Record<KindLinkReaderName, KindLinkReader> = {
+  "dbt-project": readDbtProject,
+};
+
+/**
+ * Run the link reader of every member whose kind has one. A member whose
+ * directory is missing is left out. A reader that throws is reported as a
+ * gap on the member's directory, so one unreadable project never stops
+ * the check.
+ */
+export function readKindLinks(declaration: Declaration, tree: WorkspaceTree, kinds: KindRegistry): Map<string, KindLinkRead> {
+  const out = new Map<string, KindLinkRead>();
+  for (const m of declaration.members) {
+    const kind = kinds.get(m.kind);
+    if (!kind?.reader) continue;
+    const dir = m.dir === "." ? "" : m.dir;
+    if (tree.stat(dir) !== "dir") continue;
+    const { fields } = resolveMemberFields(kind, m.fields);
+    try {
+      out.set(m.name, LINK_READERS[kind.reader]({ member: m, dir, fields, tree }));
+    } catch (err) {
+      out.set(m.name, { reader: kind.reader, links: [], gaps: [{ file: dir || ".", line: 1, message: `the ${kind.reader} reader failed: ${(err as Error).message}` }] });
+    }
+  }
+  return out;
+}

package/src/workspace/kinds.ts

@@ -128,8 +128,24 @@ export interface MemberKind {
   graph?: KindGraph;
   /** The fields a member entry of this kind may set, with their defaults (#3151); unset, the kind declares none. */
   fields?: Record<string, KindField>;
+  /**
+   * The link reader chant runs over a member's own files (#3932), by name, from
+   * {@link KIND_LINK_READERS}. It derives the member's links offline, from
+   * files it parses as data; unset, the member's links are only those its
+   * entry states.
+   */
+  reader?: KindLinkReaderName;
 }
 
+/**
+ * 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 type KindLinkReaderName = (typeof KIND_LINK_READERS)[number];
+
 export interface KindRegistry {
   get(name: string): MemberKind | undefined;
   /** Every member kind's name, sorted, for "unknown kind" messages. */
@@ -384,7 +400,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> }[] }).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 }[] }).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;
@@ -408,7 +424,11 @@ export function parseKindData(text: string, source: string): KindData {
       source,
       ...(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 } : {}),
     });
+    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`);
+    }
     for (const problem of fieldDefaultProblems(k.fields ?? {})) problems.push(`${source}: kind ${k.name} ${problem}`);
   }
   return { kinds, problems };