@intentius/chant 0.124.21 → 0.124.23

package/src/cli/handlers/graph.ts

@@ -2,7 +2,7 @@ import { dirname, resolve } from "node:path";
 import { discoverOps } from "../../op/discover";
 import { discover } from "../../discovery/index";
 import { partitionByLexicon, computeStackGraph, build, mergeBuildRootEntities } from "../../build";
-import { applyLexiconGraphEdges, buildGraphIr, buildLiveGraphIr, collectUnobserved, overlayGraphs, sourceOverlayGraphs, GRAPH_IR_VERSION, type GraphIR, type IRPipeline, type LexiconGraphEdges, type LiveObservation } from "../../graph-ir";
+import { applyLexiconGraphEdges, applyLexiconOutputs, buildGraphIr, buildLiveGraphIr, collectUnobserved, overlayGraphs, sourceOverlayGraphs, GRAPH_IR_VERSION, type GraphIR, type IRPipeline, type LexiconGraphEdges, type LexiconWorkspaceOutputs, type LiveObservation } from "../../graph-ir";
 import { behaviourOverlay } from "../../behaviour-overlay";
 import type { SerializerResult } from "../../serializer";
 import { applyBehaviourOverlay, behaviourRequestFromIr } from "../../behaviour-graph";
@@ -746,6 +746,26 @@ function withLexiconEdges(ir: GraphIR, plugins: LexiconPlugin[], entities: Map<s
   return reports.length === 0 ? ir : applyLexiconGraphEdges(ir, reports);
 }
 
+/**
+ * Add the outputs the lexicons' `workspaceOutputs` hooks report (#3931) to
+ * the IR's `exports`: a sql table and each of its columns, which `chant
+ * workspace graph` resolves member links against. A hook that throws costs
+ * its own outputs and a warning, not the graph.
+ */
+function withLexiconOutputs(ir: GraphIR, plugins: LexiconPlugin[], entities: Map<string, import("../../declarable").Declarable>): GraphIR {
+  const reports: LexiconWorkspaceOutputs[] = [];
+  for (const p of plugins) {
+    if (!p.workspaceOutputs) continue;
+    try {
+      const report = p.workspaceOutputs(entities);
+      if (report) reports.push(report);
+    } catch (err) {
+      console.error(formatWarning({ message: `the ${p.name} lexicon's workspaceOutputs failed (${err instanceof Error ? err.message : String(err)}); its outputs are left out` }));
+    }
+  }
+  return reports.length === 0 ? ir : applyLexiconOutputs(ir, reports);
+}
+
 /** Returned instead of a graph when the prediction cannot be attempted honestly. */
 const REFUSED = Symbol("behaviour-refused");
 
@@ -888,6 +908,7 @@ async function runGraphView(
       ? ctx.plugins
       : await loadPlugins(await projectLexiconsOrNone(projectPath));
     ir = withLexiconEdges(ir, plugins as LexiconPlugin[], result.entities);
+    ir = withLexiconOutputs(ir, plugins as LexiconPlugin[], result.entities);
     const predicted = await predictOntoIr(ir, plugins as LexiconPlugin[], ctx.args, {
       // No environment on the declared path: the file is not deployed anywhere
       // yet, and naming one would claim it was.

package/src/codegen/docs-pages.ts

@@ -16,6 +16,7 @@
  * - `group`: a nested subgroup label inside the quadrant (e.g. "Vendor Composites").
  * - `order`: number; lower sorts first within its group. Unordered pages follow, by label.
  * - `hidden`: `true` keeps the page out of the sidebar (reachable by URL only).
+ * - `prompt`: optional `|` block; the agent prompt shown under the title. Kept.
  *
  * `group` / `order` / `hidden` / `label` are stripped from the written copy so
  * Starlight's schema never sees them; `diataxis` stays, and the generated

package/src/codegen/docs-sections.ts

@@ -8,6 +8,13 @@ import { escapeMdx } from "./docs-file-markers";
 import { intrinsicFolds } from "../lexicon";
 import type { DocsConfig, ManifestJSON, MetaEntry, RuleMeta } from "./docs-types";
 
+/** A `prompt: |` block scalar for a page's front matter, or nothing. */
+export function promptFrontmatter(prompt: string | undefined): string[] {
+  const text = prompt?.trim();
+  if (!text) return [];
+  return ["prompt: |", ...text.split("\n").map((line) => (line ? `  ${line}` : ""))];
+}
+
 export function generateOverview(
   config: DocsConfig,
   manifest: ManifestJSON,
@@ -20,6 +27,7 @@ export function generateOverview(
     "---",
     `title: "${config.displayName}"`,
     `description: "${config.description}"`,
+    ...promptFrontmatter(config.prompt),
     "---",
     "",
     config.overview ?? `Reference documentation for the **${config.displayName}** lexicon.`,

package/src/codegen/docs-site/AgentPrompt.astro

@@ -0,0 +1,153 @@
+---
+// "Optional: hand this page to your coding agent": a card under the page title
+// with the first lines of the page's `prompt:` front matter showing, a button
+// that copies the whole prompt, one that copies a link to the card, and a
+// toggle that shows it all. The main docs site and every lexicon docs site
+// render it from their PageTitle override; lexicon sites get a copy of this
+// file from writeDocsSite (docs.ts). The content schema refuses a prompt with
+// no "Never" line. No Starlight import here, so the file works from any site.
+interface Props {
+	text?: string;
+}
+const prompt = (Astro.props.text ?? Astro.locals.starlightRoute?.entry.data.prompt)?.trim();
+---
+{prompt && (
+	<figure class="chant-prompt not-content" id="agent-prompt">
+		<figcaption>Optional: hand this page to your coding agent</figcaption>
+		<details>
+			<summary>
+				<pre class="peek" aria-hidden="true">{prompt}</pre>
+				<span class="more">Show the whole prompt</span>
+			</summary>
+			<pre class="full"><code>{prompt}</code></pre>
+		</details>
+		<div class="actions">
+			<button type="button" class="copy" data-copy={prompt} data-done="Copied">Copy prompt</button>
+			<button type="button" class="link" data-link data-done="Link copied">Copy link</button>
+		</div>
+	</figure>
+)}
+
+<script>
+	const flash = (button: HTMLButtonElement, text: string) => {
+		const was = button.textContent;
+		button.textContent = text;
+		setTimeout(() => (button.textContent = was), 1600);
+	};
+	for (const button of document.querySelectorAll<HTMLButtonElement>('.chant-prompt button')) {
+		button.addEventListener('click', async () => {
+			const card = button.closest('figure')!;
+			const text = button.dataset.link !== undefined ? `${location.origin}${location.pathname}#${card.id}` : (button.dataset.copy ?? '');
+			try {
+				await navigator.clipboard.writeText(text);
+				flash(button, button.dataset.done ?? 'Copied');
+			} catch {
+				// No clipboard (an insecure origin, a denied permission): open the
+				// prompt and select it so the reader can copy it by hand.
+				card.querySelector('details')?.setAttribute('open', '');
+				const code = card.querySelector('.full code');
+				if (code) window.getSelection()?.selectAllChildren(code);
+				flash(button, 'Selected');
+			}
+		});
+	}
+</script>
+
+<style>
+	/* Minimal: zinc greys from Starlight's scale and one blue. */
+	.chant-prompt {
+		--chant-prompt-blue: #2563eb;
+		margin: 1.25rem 0 0;
+		width: min(100%, 44rem);
+		border: 1px solid var(--sl-color-gray-5);
+		border-left: 2px solid var(--chant-prompt-blue);
+		border-radius: 0.5rem;
+		background: var(--sl-color-gray-7, var(--sl-color-black));
+		overflow: hidden;
+	}
+	:global([data-theme='dark']) .chant-prompt {
+		--chant-prompt-blue: #60a5fa;
+	}
+	figcaption {
+		padding: 0.7rem 1rem 0.4rem;
+		font-size: 0.85rem;
+		font-weight: 600;
+		color: var(--sl-color-white);
+	}
+	summary {
+		display: block;
+		list-style: none;
+		cursor: pointer;
+		padding: 0 1rem;
+	}
+	summary::-webkit-details-marker {
+		display: none;
+	}
+	pre {
+		margin: 0;
+		font-family: var(--sl-font-mono);
+		font-size: 0.75rem;
+		line-height: 1.55;
+		color: var(--sl-color-gray-2);
+		white-space: pre-wrap;
+		overflow-wrap: anywhere;
+		background: none;
+		border: 0;
+		padding: 0;
+	}
+	/* Two lines of the prompt, fading out, say it is there. */
+	.peek {
+		max-height: 2.4rem;
+		overflow: hidden;
+		mask-image: linear-gradient(to bottom, #000 40%, transparent);
+	}
+	.more,
+	details[open] summary::after {
+		display: inline-block;
+		margin-top: 0.2rem;
+		font-size: 0.72rem;
+		color: var(--chant-prompt-blue);
+	}
+	details[open] .peek,
+	details[open] .more {
+		display: none;
+	}
+	details[open] summary::after {
+		content: 'Hide the prompt';
+	}
+	.full {
+		padding: 0.25rem 1rem 0;
+	}
+	.actions {
+		display: flex;
+		gap: 0.5rem;
+		padding: 0.7rem 1rem 0.8rem;
+	}
+	button {
+		font: inherit;
+		font-size: 0.78rem;
+		font-weight: 600;
+		border-radius: 0.4rem;
+		padding: 0.35rem 0.85rem;
+		cursor: pointer;
+	}
+	.copy {
+		color: #fff;
+		background: var(--chant-prompt-blue);
+		border: 1px solid var(--chant-prompt-blue);
+	}
+	:global([data-theme='dark']) .copy {
+		color: #09090b;
+	}
+	.copy:hover {
+		filter: brightness(1.1);
+	}
+	.link {
+		color: var(--sl-color-white);
+		background: none;
+		border: 1px solid var(--sl-color-gray-5);
+	}
+	.link:hover {
+		border-color: var(--chant-prompt-blue);
+	}
+</style>

package/src/codegen/docs-types.ts

@@ -21,6 +21,13 @@ export interface DocsConfig {
   packageJsonPath?: string;
   /** Lexicon-specific overview content (markdown) */
   overview?: string;
+  /**
+   * The overview page's agent prompt: "Optional: hand this page to your coding
+   * agent", shown under the title (docs-site/AgentPrompt.astro). Imperative
+   * steps, what to report back, and a line starting "Never". An authored page
+   * under `pagesDir` carries its own as a `prompt:` front-matter field.
+   */
+  prompt?: string;
   /** Output format description (e.g. "CloudFormation JSON template") */
   outputFormat?: string;
   /** Custom service grouping from resource type (e.g. "AWS::S3::Bucket" → "S3") */

package/src/codegen/docs.ts

@@ -390,6 +390,13 @@ export const collections = {
       extend: z.object({
         // Diátaxis quadrant (https://diataxis.fr), chant #1731.
         diataxis: z.enum(['tutorial', 'how-to', 'reference', 'explanation']).optional(),
+        // "Optional: hand this page to your coding agent", shown under the
+        // title by src/components/AgentPrompt.astro. It has to say what the
+        // agent must never do.
+        prompt: z
+          .string()
+          .optional()
+          .refine((p) => !p || /^Never\\b/m.test(p), 'a prompt needs a line that starts with "Never" (what the agent must not do)'),
       }),
     }),
   }),
@@ -404,6 +411,25 @@ export const collections = {
   );
   copyFileSync(pluginSrcPath, join(outDir, "src", "rehype-base-url.mjs"));
 
+  // src/components/: the agent prompt card from chant core, and a PageTitle
+  // override that puts it under Starlight's title on every page with a `prompt:`.
+  mkdirSync(join(outDir, "src", "components"), { recursive: true });
+  copyFileSync(
+    fileURLToPath(new URL("./docs-site/AgentPrompt.astro", import.meta.url)),
+    join(outDir, "src", "components", "AgentPrompt.astro"),
+  );
+  writeFileSync(
+    join(outDir, "src", "components", "PageTitle.astro"),
+    `---
+// Generated by chant's writeDocsSite. Starlight's page title, then the page's agent prompt.
+import Default from '@astrojs/starlight/components/PageTitle.astro';
+import AgentPrompt from './AgentPrompt.astro';
+---
+<Default />
+<AgentPrompt />
+`,
+  );
+
   // astro.config.mjs
   const rehypeLine = config.basePath
     ? `\n  markdown: {\n    rehypePlugins: [[rehypeBaseUrl, { base: '${config.basePath}', projectBase: '/chant' }]],\n  },`
@@ -419,6 +445,7 @@ export default defineConfig({${config.basePath ? `\n  base: '${config.basePath}'
   integrations: [
     starlight({
       title: '${config.displayName}',
+      components: { PageTitle: './src/components/PageTitle.astro' },
       sidebar: ${JSON.stringify(sidebar, null, 6).replace(/\n/g, "\n      ")},
     }),
   ],

package/src/fold/subset.ts

@@ -141,7 +141,9 @@ import { intrinsicCallFolds, intrinsicCallFoldsEagerly, type IntrinsicDef } from
  *      (`{...n}`) is shape-valid (`n` is a plain identifier) but `fold()`
  *      rejects it once it discovers `n` folds to a number, not an object.
  *      Only real evaluation catches this; EVL004 independently narrows
- *      spread sources to a stricter "traceable to a const" shape, which
+ *      spread sources to a stricter "traceable to a const" shape (a const
+ *      declared in the file, or an imported binding, which fold() resolves
+ *      from the exporting module's folded value), which
  *      catches most real-world misuse without evaluating, but is not a
  *      full substitute.
  *

package/src/graph-ir.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from "vitest";
-import { buildGraphIr } from "./graph-ir";
+import { applyLexiconOutputs, buildGraphIr } from "./graph-ir";
 import { DECLARABLE_MARKER, type Declarable } from "./declarable";
 import { AttrRef } from "./attrref";
 import { LexiconOutput } from "./lexicon-output";
@@ -370,3 +370,25 @@ describe("whole declarables held in an entity's fields (#3257)", () => {
     expect(ir.edges).toEqual([{ from: "lb", to: "vpc", kind: "ref", viaAttr: "actions" }]);
   });
 });
+
+describe("applyLexiconOutputs (#3931)", () => {
+  test("adds each reported output to exports on the node that declares it, keeping a hand-written export", () => {
+    const orders = decl({ lexicon: "sql", entityType: "Postgres::Table", props: {} });
+    const ir = buildGraphIr(new Map<string, Declarable>([["orders", orders]]));
+    const withOutputs = applyLexiconOutputs({ ...ir, exports: [{ name: "public.orders", node: "orders", attr: "name" }] }, [
+      {
+        outputs: [
+          { name: "public.orders", entity: "orders" },
+          { name: "public.orders.buyer_id", entity: "orders", previously: ["public.orders.customer_id"] },
+          { name: "other.thing", entity: "notANode" },
+        ],
+      },
+    ]);
+    expect(withOutputs.exports).toEqual([
+      { name: "other.thing" },
+      { name: "public.orders", node: "orders", attr: "name" },
+      { name: "public.orders.buyer_id", node: "orders", previously: ["public.orders.customer_id"] },
+    ]);
+    expect(applyLexiconOutputs(ir, [{ outputs: [] }])).toBe(ir);
+  });
+});

package/src/graph-ir.ts

@@ -155,6 +155,43 @@ export interface LexiconGraphReference {
   dangling?: boolean;
 }
 
+/**
+ * One output a lexicon reports for its own declarations (#3931): a name a
+ * workspace link may target, such as a sql table's `public.orders` or a
+ * column's `public.orders.customer_id`.
+ */
+export interface LexiconWorkspaceOutput {
+  /** The output's name, as a link's `output` names it. */
+  name: string;
+  /** The entity key that declares it. */
+  entity: string;
+  /**
+   * Names the output had before, from a rename hint in source (a sql
+   * `-- previously:` comment). A link to one of them is told where it went.
+   */
+  previously?: string[];
+}
+
+/** One file the reader was handed but could not read without running it (#3931). */
+export interface LexiconUnreadSource {
+  /** The file's path, as the caller names it in messages. */
+  file: string;
+  text: string;
+  /** Why it was not read: the fold's located reason. */
+  reason: string;
+}
+
+/** What a lexicon's `workspaceOutputs` hook returns (#3931). */
+export interface LexiconWorkspaceOutputs {
+  outputs: LexiconWorkspaceOutput[];
+  /**
+   * Why the list may be incomplete, one line each: a declaration whose name
+   * can't be known statically, a file of this lexicon's that did not fold, a
+   * view whose columns can't be derived. Empty or absent when it is complete.
+   */
+  gaps?: string[];
+}
+
 /** What a lexicon's `graphEdges` hook returns (#3910). */
 export interface LexiconGraphEdges {
   references: LexiconGraphReference[];
@@ -304,6 +341,8 @@ export interface IRExport {
   value?: unknown;
   /** The deployed stack that publishes it, on an observed graph (#1279). */
   stack?: string;
+  /** Names the output had before, from a rename hint a lexicon read (#3931). */
+  previously?: string[];
 }
 
 /** A cross-stack import this stack consumes — a `Parameter` fed from another
@@ -834,6 +873,32 @@ export function applyLexiconGraphEdges(ir: GraphIR, reports: readonly LexiconGra
   return out;
 }
 
+/**
+ * Add the outputs the lexicons' `workspaceOutputs` hooks report (#3931) to a
+ * built IR's `exports`, each on the node that declares it. An output whose
+ * name is already exported (a hand-written `output()`) keeps the existing
+ * export. Pure. Returns `ir` itself when no report added anything.
+ */
+export function applyLexiconOutputs(ir: GraphIR, reports: readonly LexiconWorkspaceOutputs[]): GraphIR {
+  const nodeIds = new Set(ir.nodes.map((n) => n.id));
+  const names = new Set((ir.exports ?? []).map((e) => e.name));
+  const added: IRExport[] = [];
+  for (const report of reports) {
+    for (const o of report.outputs) {
+      if (names.has(o.name)) continue;
+      names.add(o.name);
+      added.push({
+        name: o.name,
+        ...(nodeIds.has(o.entity) ? { node: o.entity } : {}),
+        ...(o.previously && o.previously.length > 0 ? { previously: [...o.previously] } : {}),
+      });
+    }
+  }
+  if (added.length === 0) return ir;
+  const exports = [...(ir.exports ?? []), ...added].sort((a, b) => a.name.localeCompare(b.name));
+  return { ...ir, exports };
+}
+
 function danglingKey(d: IRDanglingRef): string {
   return `${d.from}\0${d.path}\0${d.value}`;
 }

package/src/lexicon.ts

@@ -23,7 +23,7 @@ import type { OwnershipChannel, OwnershipMarker } from "./ownership";
 import type { LexiconConfigSchema } from "./lexicon-config";
 import type { RuleMeta } from "./audit/catalog";
 import type { ReferenceCatalog } from "./graph-refs";
-import type { IREdge, LexiconGraphEdges } from "./graph-ir";
+import type { IREdge, LexiconGraphEdges, LexiconUnreadSource, LexiconWorkspaceOutputs } from "./graph-ir";
 import type { DescribeResourcesResult, UnobservedReason } from "./observation";
 import type { DescribeIdentityOptions, DescribeIdentityResult } from "./identity";
 import type { DeepNormalizationHooks, DeepObservationResult } from "./deep-observation";
@@ -1450,6 +1450,31 @@ export interface LexiconPlugin {
    */
   graphEdges?(entities: ReadonlyMap<string, Declarable>): LexiconGraphEdges | undefined;
 
+  /**
+   * The workspace outputs this lexicon's declarations expose (#3931): names
+   * another member's link may target, without anyone writing `output(...)`.
+   * The sql lexicon answers each table and view as `<schema>.<table>` and
+   * each column as `<schema>.<table>.<column>`.
+   *
+   * Called two ways, with the same answer expected from both:
+   *
+   * - by `chant workspace check`, offline, with the entities the member's
+   *   source folds to (`foldProject` under `sandbox`: no member code runs),
+   *   and `unread` listing the files that did not fold, with their text. A
+   *   file of this lexicon's among them is a gap: the list is then incomplete
+   *   and a link to a name not in it is unresolved rather than missing;
+   * - by `chant graph --format ir`, with the built entities and no `unread`.
+   *   The outputs land on the IR's `exports`, which `chant workspace graph`
+   *   resolves links against.
+   *
+   * Names come from the declarations as written in source, never from an
+   * environment's or profile's rendering, so they stay the same everywhere
+   * the member deploys. Pure: no I/O. Return `undefined` when the project
+   * declares nothing this lexicon reports. Omit for lexicons with no such
+   * declarations.
+   */
+  workspaceOutputs?(entities: ReadonlyMap<string, Declarable>, unread?: readonly LexiconUnreadSource[]): LexiconWorkspaceOutputs | undefined;
+
   // LSP
   /** Provide completions for LSP */
   completionProvider?(ctx: CompletionContext): CompletionItem[];

package/src/lint/rules/evl004-spread-non-const.test.ts

@@ -36,6 +36,24 @@ describe("EVL004: spread-non-const", () => {
     expect(evl004SpreadNonConstRule.check(ctx)).toHaveLength(0);
   });
 
+  test("allows spread from an imported binding (named, default, namespace member)", () => {
+    const ctx = createContext(`
+      import base, { steps } from "./shared";
+      import * as shared from "./shared";
+      const x = { ...base, ...shared.preset };
+      const y = [...steps, { run: "true" }];
+    `);
+    expect(evl004SpreadNonConstRule.check(ctx)).toHaveLength(0);
+  });
+
+  test("still flags a call on an imported function", () => {
+    const ctx = createContext(`
+      import { makeSteps } from "./shared";
+      const y = [...makeSteps("web")];
+    `);
+    expect(evl004SpreadNonConstRule.check(ctx)).toHaveLength(1);
+  });
+
   test("flags spread from let variable", () => {
     const ctx = createContext(`
       let base = { a: 1 };

package/src/lint/rules/evl004-spread-non-const.ts

@@ -8,6 +8,11 @@ import { isInsideCompositeFactory } from "./composite-scope";
  * Spread expressions ({...x} or [...x]) must reference a const-declared
  * variable, object literal, or property access chain from a const.
  * Spreading from function calls or non-traceable sources is blocked.
+ *
+ * A binding imported from another module counts as const: an import can't
+ * be reassigned, and sharing an exported const (a preset, a list of
+ * Dockerfile steps) across modules is the point of exporting it. Whether the
+ * exporting module declared it `const` is that module's own EVL concern.
  */
 
 function isTraceableToConst(node: ts.Node, sourceFile: ts.SourceFile): boolean {
@@ -40,8 +45,18 @@ function isTraceableToConst(node: ts.Node, sourceFile: ts.SourceFile): boolean {
 }
 
 function isConstIdentifier(id: ts.Identifier, sourceFile: ts.SourceFile): boolean {
-  // Walk all statements looking for a const declaration of this identifier
+  // Walk all statements looking for a const declaration or an import of this identifier
   for (const stmt of sourceFile.statements) {
+    if (ts.isImportDeclaration(stmt) && stmt.importClause && !stmt.importClause.isTypeOnly) {
+      const clause = stmt.importClause;
+      if (clause.name?.text === id.text) return true;
+      const bindings = clause.namedBindings;
+      if (bindings && ts.isNamedImports(bindings)) {
+        if (bindings.elements.some((el) => !el.isTypeOnly && el.name.text === id.text)) return true;
+      } else if (bindings && ts.isNamespaceImport(bindings) && bindings.name.text === id.text) {
+        return true;
+      }
+    }
     if (ts.isVariableStatement(stmt)) {
       if (stmt.declarationList.flags & ts.NodeFlags.Const) {
         for (const decl of stmt.declarationList.declarations) {

package/src/wave-loop-golden.test.ts

@@ -43,6 +43,9 @@ beforeEach(() => {
   // A CI job's locator would land on every pending fact.
   vi.stubEnv("GITHUB_ACTIONS", "");
   vi.stubEnv("GITLAB_CI", "");
+  // A pull request's address would land on every pending fact too.
+  vi.stubEnv("GITHUB_REF_NAME", "");
+  vi.stubEnv("CI_MERGE_REQUEST_IID", "");
 });
 afterEach(() => vi.unstubAllEnvs());
 

package/src/workspace/checks/links.ts

@@ -17,31 +17,58 @@
  * | WSP096 | a consumer states the same link twice |
  * | WSP097 | an entry lists `outputs` for a kind that doesn't take them from the entry |
  * | WSP098 | a link states a `protocol` and its kind is not `telemetry` (#2558) |
+ * | WSP099 | a kind's link reader could not read part of a member's files without guessing (#3932) |
+ *
+ * Links a kind's reader finds in a member's own files (#3932), such as a dbt
+ * project's sources, are checked by WSP093 to WSP095 like declared ones, and
+ * their findings name the member's file and line instead of the declaration.
  */
 
 import type { WorkspaceCheck, WorkspaceCheckContext, WorkspaceDiagnostic } from "../checks";
 import type { Member } from "../declaration";
 import { sourceMemberHandles } from "../member-handles";
+import { readKindLinks, type KindLinkRead } from "../kind-link-readers";
 import { DEFAULT_LINK_KIND, LINK_KINDS, TELEMETRY_LINK_KIND, linkTargetProblem, resolveLinks, type AmbiguousRow, type LinkRow, type LinkTableRow } from "../links";
 
 const tables = new WeakMap<WorkspaceCheckContext, LinkTableRow[]>();
+const reads = new WeakMap<WorkspaceCheckContext, Map<string, KindLinkRead>>();
+
+/** What each member's kind reader found (#3932), read once per check run. */
+function kindReads(ctx: WorkspaceCheckContext): Map<string, KindLinkRead> {
+  let read = reads.get(ctx);
+  if (!read) {
+    read = readKindLinks(ctx.declaration, ctx.tree, ctx.kinds);
+    reads.set(ctx, read);
+  }
+  return read;
+}
 
 /** The link rows for a check run, resolved once and shared by every link check. */
 export function linkTable(ctx: WorkspaceCheckContext): LinkTableRow[] {
   let rows = tables.get(ctx);
   if (!rows) {
-    rows = resolveLinks(ctx.declaration, sourceMemberHandles(ctx.declaration, ctx.tree, ctx.groups, ctx.kinds));
+    rows = resolveLinks(ctx.declaration, sourceMemberHandles(ctx.declaration, ctx.tree, ctx.groups, ctx.kinds, ctx.facts?.lexiconOutputs), undefined, kindReads(ctx));
     tables.set(ctx, rows);
   }
   return rows;
 }
 
-const declaredRows = (ctx: WorkspaceCheckContext) => linkTable(ctx).filter((r): r is LinkRow => r.status !== "ambiguous" && r.origin === "declared");
+/** The declared links, and the links a kind's reader found: the rows a member states. */
+const statedRows = (ctx: WorkspaceCheckContext) => linkTable(ctx).filter((r): r is LinkRow => r.status !== "ambiguous" && r.origin !== "inferred:joinKey");
 
-function linkFinding(check: WorkspaceCheck, row: LinkRow, field: string, message: string): WorkspaceDiagnostic {
-  return { checkId: check.id, severity: check.severity, message, entity: row.consumer, pointer: `${row.pointer}/${field}` };
+/** A finding at a declared link's field in the declaration, or at the file and line a reader's link came from. */
+function linkFinding(check: WorkspaceCheck, ctx: WorkspaceCheckContext, row: LinkTableRow, field: string, message: string): WorkspaceDiagnostic {
+  const base = { checkId: check.id, severity: check.severity, message, entity: row.consumer };
+  if (row.origin === "kind-reader" && row.file !== undefined) {
+    const member = ctx.declaration.members.find((m) => m.name === row.consumer);
+    return { ...base, pointer: member?.pointer ?? "", treeFile: row.file, line: row.line ?? 1, column: 1 };
+  }
+  return { ...base, pointer: `${(row as LinkRow).pointer}/${field}` };
 }
 
+/** Where a reader's link came from, for its message; empty for a declared link. */
+const statedAt = (row: LinkRow) => (row.origin === "kind-reader" ? ` (read by ${row.reader} from ${row.file}:${row.line})` : "");
+
 const describeLink = (row: LinkRow) => `${row.consumer}'s link to ${row.producer} output ${row.output}`;
 
 export const LINK_CHECKS: readonly WorkspaceCheck[] = [
@@ -87,9 +114,9 @@ export const LINK_CHECKS: readonly WorkspaceCheck[] = [
     severity: "error",
     configurable: true,
     check(ctx) {
-      return declaredRows(ctx)
+      return statedRows(ctx)
         .filter((r) => r.status === "missing")
-        .map((r) => linkFinding(this, r, "output", `${describeLink(r)} does not resolve: ${r.reason}`));
+        .map((r) => linkFinding(this, ctx, r, "output", `${describeLink(r)}${statedAt(r)} does not resolve: ${r.reason}`));
     },
   },
   {
@@ -99,9 +126,9 @@ export const LINK_CHECKS: readonly WorkspaceCheck[] = [
     severity: "info",
     configurable: true,
     check(ctx) {
-      return declaredRows(ctx)
+      return statedRows(ctx)
         .filter((r) => r.status === "unresolved")
-        .map((r) => linkFinding(this, r, "output", `${describeLink(r)} is kept unresolved: ${r.reason}`));
+        .map((r) => linkFinding(this, ctx, r, "output", `${describeLink(r)}${statedAt(r)} is kept unresolved: ${r.reason}`));
     },
   },
   {
@@ -115,6 +142,10 @@ export const LINK_CHECKS: readonly WorkspaceCheck[] = [
       return linkTable(ctx)
         .filter((r): r is AmbiguousRow => r.status === "ambiguous")
         .map((r) => {
+          if (r.origin === "kind-reader") {
+            const choices = r.candidates.map((c) => c.producer).join(", ");
+            return linkFinding(this, ctx, r, "", `${r.consumer}'s link to ${r.input} (read by ${r.reader}) has no single producer: ${r.reason}${choices ? `. Candidates: ${choices}` : ""}`);
+          }
           const choices = r.candidates.map((c) => `${c.producer} output ${c.output} (${c.label})`).join(", ");
           const first = r.candidates[0];
           return {
@@ -201,4 +232,22 @@ export const LINK_CHECKS: readonly WorkspaceCheck[] = [
       );
     },
   },
+  {
+    id: "WSP099",
+    name: "kind-reader-gap",
+    description:
+      "A kind's link reader read every link in a member's files that it could read without guessing (#3932). A value it would have to render, such as a Jinja template in a dbt source, is reported here with its file and line, and the links it would state are not checked.",
+    severity: "info",
+    configurable: true,
+    check(ctx) {
+      const out: WorkspaceDiagnostic[] = [];
+      for (const [member, read] of kindReads(ctx)) {
+        const pointer = ctx.declaration.members.find((m) => m.name === member)?.pointer ?? "";
+        for (const gap of read.gaps) {
+          out.push({ checkId: this.id, severity: this.severity, message: `${member} (read by ${read.reader}): ${gap.message}`, entity: member, pointer, treeFile: gap.file, line: gap.line, column: 1 });
+        }
+      }
+      return out;
+    },
+  },
 ];

package/src/workspace/checks.e2e.test.ts

@@ -75,7 +75,7 @@ describe("the WSP catalog", () => {
     expect(list.filter((id) => /^WSP(07|08|09|10)\d$/.test(id))).toEqual([
       "WSP071", "WSP072", "WSP073",
       "WSP081", "WSP082", "WSP083",
-      "WSP091", "WSP092", "WSP093", "WSP094", "WSP095", "WSP096", "WSP097", "WSP098",
+      "WSP091", "WSP092", "WSP093", "WSP094", "WSP095", "WSP096", "WSP097", "WSP098", "WSP099",
       "WSP101", "WSP102", "WSP103", "WSP104", "WSP105", "WSP106",
     ]);
   });