@intentius/chant 0.80.0 → 0.81.0

package/src/workspace/links.test.ts

@@ -0,0 +1,344 @@
+/**
+ * Member links (#2539): declared links resolved in source, inferred joins
+ * labelled by the core joinKey(), ambiguity rows, and the WSP091 to WSP097
+ * checks.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { runDeclarationChecks } from "./checks";
+import { parseDeclaration, WorkspaceReadError } from "./declaration";
+import { declaredMemberLinks, graphLinks, resolveLinks, type LinkTableRow, type MemberHandles } from "./links";
+import { builtinKindRegistry } from "./kinds";
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+function repo(files: Record<string, string>): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-links-")));
+  scratch.push(root);
+  execFileSync("git", ["init", "-q"], { cwd: root });
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  return root;
+}
+
+const declaration = (members: unknown[], extra: Record<string, unknown> = {}) =>
+  JSON.stringify({ name: "acme", schema: 1, members, ...extra }, null, 2);
+
+const producerSource = (outputs: Record<string, string>) =>
+  [
+    `import { output } from "@intentius/chant-lexicon-aws";`,
+    `import { cluster, listener } from "./alb";`,
+    ...Object.entries(outputs).map(([binding, name]) => `export const ${binding} = output(cluster.Arn, ${JSON.stringify(name)});`),
+    `void listener;`,
+  ].join("\n");
+
+const consumerSource = (params: string[]) =>
+  [`import { Parameter } from "@intentius/chant-lexicon-aws";`, ...params.map((p) => `export const ${p} = new Parameter("String");`)].join("\n");
+
+/** A producer and two consumers, the shape the issue asks for. */
+function threeMembers(opts: { outputs?: Record<string, string>; webLinks?: unknown[]; jobsLinks?: unknown[] } = {}) {
+  return repo({
+    "chant.workspace.json": declaration([
+      { name: "shared", dir: "infra/shared", kind: "chant" },
+      { name: "web", dir: "services/web", kind: "chant", ...(opts.webLinks ? { links: opts.webLinks } : {}) },
+      { name: "jobs", dir: "services/jobs", kind: "chant", ...(opts.jobsLinks ? { links: opts.jobsLinks } : {}) },
+    ]),
+    "infra/shared/chant.config.ts": "",
+    "infra/shared/src/outputs.ts": producerSource(opts.outputs ?? { clusterArn: "ClusterArn", listenerArn: "ListenerArn" }),
+    "services/web/chant.config.ts": "",
+    "services/web/src/params.ts": consumerSource(["clusterArn", "listenerArn"]),
+    "services/jobs/chant.config.ts": "",
+    "services/jobs/src/params.ts": consumerSource(["clusterArn"]),
+  });
+}
+
+const ids = async (root: string) => (await runDeclarationChecks(root)).diagnostics.map((d) => `${d.ruleId}:${d.entity ?? ""}`);
+const summary = (rows: LinkTableRow[]) =>
+  rows.map((r) =>
+    r.status === "ambiguous"
+      ? `${r.consumer}.${r.input} ambiguous ${r.candidates.map((c) => `${c.producer}.${c.output}`).join("|")}`
+      : `${r.consumer}${r.input ? `.${r.input}` : ""} -> ${r.producer}.${r.output} ${r.origin} ${r.label} ${r.status}`,
+  );
+
+describe("declared links, resolved in source", () => {
+  test("a link to an output the producer's source declares resolves, and suppresses the inferred edge", async () => {
+    const root = threeMembers({ webLinks: [{ member: "shared", output: "ClusterArn" }] });
+    const report = await runDeclarationChecks(root);
+    expect(report.ok).toBe(true);
+    expect(report.diagnostics).toEqual([]);
+    expect(summary(report.links)).toEqual([
+      "web -> shared.ClusterArn declared exact resolved",
+      "jobs.clusterArn -> shared.ClusterArn inferred:joinKey folded resolved",
+      "web.listenerArn -> shared.ListenerArn inferred:joinKey folded resolved",
+    ]);
+    expect(report.links[0]).toMatchObject({ resolves: "source", kind: "output", pointer: "/members/1/links/0" });
+  });
+
+  test("a renamed producer output fails check for every declared consumer", async () => {
+    const link = [{ member: "shared", output: "ClusterArn" }];
+    const root = threeMembers({ outputs: { clusterArn: "EcsClusterArn", listenerArn: "ListenerArn" }, webLinks: link, jobsLinks: link });
+    const report = await runDeclarationChecks(root);
+    expect(report.ok).toBe(false);
+    expect(report.diagnostics.map((d) => `${d.ruleId}:${d.entity}`)).toEqual(["WSP093:web", "WSP093:jobs"]);
+    expect(report.diagnostics[0].message).toBe(
+      "web's link to shared output ClusterArn does not resolve: shared has no output ClusterArn; its outputs: EcsClusterArn, ListenerArn",
+    );
+    // The finding points at the link's output in the file.
+    expect(report.diagnostics[0]).toMatchObject({ file: "chant.workspace.json", line: 17, column: 21 });
+  });
+
+  test("a near miss in case is named, since declared links match exactly", async () => {
+    const root = threeMembers({ webLinks: [{ member: "shared", output: "clusterArn" }] });
+    const [d] = (await runDeclarationChecks(root)).diagnostics;
+    expect(d.ruleId).toBe("WSP093");
+    expect(d.message).toMatch(/did you mean ClusterArn\? Links match exactly/);
+  });
+
+  test("an output name that can't be read without running code keeps the link unresolved, as info", async () => {
+    const root = threeMembers({ webLinks: [{ member: "shared", output: "Missing" }] });
+    writeFileSync(join(root, "infra/shared/src/more.ts"), `import { output } from "@intentius/chant-lexicon-aws";\nexport const x = output(1, process.env.NAME!);\n`);
+    const report = await runDeclarationChecks(root);
+    expect(report.ok).toBe(true);
+    expect(report.diagnostics.map((d) => `${d.ruleId}:${d.severity}`)).toEqual(["WSP094:info"]);
+    expect(report.diagnostics[0].message).toMatch(/kept unresolved: Missing was not found in shared.*infra\/shared\/src\/more\.ts:2: an output whose name is not a string literal/);
+    expect(report.links[0]).toMatchObject({ status: "unresolved" });
+  });
+
+  test("other members expose what the entry lists, and a nested workspace exposes nothing", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([
+        { name: "legacy", dir: "legacy", kind: "other", because: "a hand-run stack", outputs: ["QueueUrl"], suppress: [{ check: "WSP009", because: "known" }] },
+        { name: "nested", dir: "nested", kind: "workspace" },
+        {
+          name: "app",
+          dir: "app",
+          kind: "chant",
+          links: [
+            { member: "legacy", output: "QueueUrl" },
+            { member: "legacy", output: "TopicArn" },
+            { member: "nested", output: "Anything" },
+          ],
+        },
+      ]),
+      "legacy/README": "",
+      "nested/chant.workspace.json": declaration([]),
+      "app/chant.config.ts": "",
+    });
+    const report = await runDeclarationChecks(root);
+    expect(summary(report.links)).toEqual([
+      "app -> legacy.QueueUrl declared exact resolved",
+      "app -> legacy.TopicArn declared exact missing",
+      "app -> nested.Anything declared exact missing",
+    ]);
+    expect(report.diagnostics.map((d) => d.message)).toEqual([
+      "app's link to legacy output TopicArn does not resolve: legacy has no output TopicArn; its outputs: QueueUrl",
+      "app's link to nested output Anything does not resolve: nested is kind workspace, which exposes no outputs as link targets",
+    ]);
+  });
+
+  test("an unknown member, a group, the consumer itself, an unknown link kind and a repeat each fail", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([
+        { name: "api", dir: "api", kind: "chant", outputs: ["Url"] },
+        {
+          name: "web",
+          dir: "web",
+          kind: "chant",
+          links: [
+            { member: "ghost", output: "Url" },
+            { member: "examples", output: "Url" },
+            { member: "web", output: "Url" },
+            { member: "api", output: "Url", kind: "depends-on" },
+            { member: "api", output: "Url" },
+            { member: "api", output: "Url" },
+          ],
+        },
+        { name: "examples", kind: "examples", glob: "examples/*" },
+      ]),
+      "api/chant.config.ts": "",
+      "api/src/out.ts": `import * as aws from "@intentius/chant-lexicon-aws";\nconst NAME = "Url";\nexport const url = aws.output(1, NAME);\n`,
+      "web/chant.config.ts": "",
+      "examples/one/chant.config.ts": "",
+    });
+    expect(await ids(root)).toEqual(["WSP097:api", "WSP091:web", "WSP091:web", "WSP091:web", "WSP092:web", "WSP096:web"]);
+    const messages = (await runDeclarationChecks(root)).diagnostics.map((d) => d.message);
+    expect(messages).toContain("member web links to ghost, which is not a member of this workspace");
+    expect(messages).toContain("member web links to examples, which is an example group; a group has no links");
+    expect(messages).toContain("member web links to itself; a link joins two members");
+    expect(messages).toContain("member api lists outputs, and kind chant reads a member's outputs from its source; remove the list");
+  });
+
+  test("WSP091 and WSP092 can't be suppressed, and WSP093 can", async () => {
+    const root = repo({
+      "chant.workspace.json": declaration([
+        { name: "api", dir: "api", kind: "chant" },
+        {
+          name: "web",
+          dir: "web",
+          kind: "chant",
+          links: [{ member: "api", output: "Gone" }],
+          suppress: [{ check: "WSP093", because: "api is being rebuilt" }],
+        },
+      ]),
+      "api/chant.config.ts": "",
+      "web/chant.config.ts": "",
+    });
+    const report = await runDeclarationChecks(root);
+    expect(report.ok).toBe(true);
+    expect(report.suppressed.map((s) => `${s.ruleId}:${s.reason}`)).toEqual(["WSP093:api is being rebuilt"]);
+  });
+});
+
+describe("inferred joins", () => {
+  function twoProducers(webLinks?: unknown[]) {
+    return repo({
+      "chant.workspace.json": declaration([
+        { name: "net-a", dir: "net-a", kind: "chant" },
+        { name: "net-b", dir: "net-b", kind: "chant" },
+        { name: "web", dir: "web", kind: "chant", ...(webLinks ? { links: webLinks } : {}) },
+      ]),
+      "net-a/chant.config.ts": "",
+      "net-a/src/o.ts": producerSource({ vpc: "VpcId" }),
+      "net-b/chant.config.ts": "",
+      "net-b/src/o.ts": producerSource({ vpc: "vpc_id" }),
+      "web/chant.config.ts": "",
+      "web/src/p.ts": consumerSource(["vpcId"]),
+    });
+  }
+
+  test("two producers of one handle is an ambiguity row and a warning", async () => {
+    const report = await runDeclarationChecks(twoProducers());
+    expect(summary(report.links)).toEqual(["web.vpcId ambiguous net-a.VpcId|net-b.vpc_id"]);
+    expect(report.ok).toBe(true);
+    expect(report.diagnostics.map((d) => `${d.ruleId}:${d.severity}:${d.entity}`)).toEqual(["WSP095:warning:web"]);
+    expect(report.diagnostics[0].message).toBe(
+      'parameter vpcId of web matches outputs of net-a and net-b: net-a output VpcId (folded), net-b output vpc_id (folded). Declare the one it reads, such as { "member": "net-a", "output": "VpcId" } in web\'s links',
+    );
+  });
+
+  test("declaring one of the matches settles the ambiguity", async () => {
+    const report = await runDeclarationChecks(twoProducers([{ member: "net-b", output: "vpc_id" }]));
+    expect(report.diagnostics).toEqual([]);
+    expect(summary(report.links)).toEqual(["web -> net-b.vpc_id declared exact resolved"]);
+  });
+
+  test("equal names are labelled exact, and a member never joins itself", async () => {
+    const decl = parseDeclaration(declaration([{ name: "a", dir: "a", kind: "chant" }, { name: "b", dir: "b", kind: "chant" }]), "chant.workspace.json");
+    const h = (member: string, outputs: string[], inputs: string[]): MemberHandles => ({
+      member,
+      outputs: outputs.map((name) => ({ name })),
+      inputs: inputs.map((name) => ({ name })),
+      complete: true,
+      why: null,
+      exposesNone: false,
+    });
+    const rows = resolveLinks(decl, new Map([["a", h("a", ["Url"], ["Url"])], ["b", h("b", [], ["Url"])]]));
+    expect(summary(rows)).toEqual(["b.Url -> a.Url inferred:joinKey exact resolved"]);
+  });
+});
+
+describe("the graph's links section", () => {
+  const decl = parseDeclaration(
+    declaration([
+      { name: "shared", dir: "shared", kind: "chant" },
+      { name: "web", dir: "web", kind: "chant", links: [{ member: "shared", output: "ClusterArn" }] },
+      { name: "legacy", dir: "legacy", kind: "other", because: "x", outputs: ["QueueUrl"] },
+    ]),
+    "chant.workspace.json",
+  );
+  const graph = {
+    composed: ["shared", "web"],
+    exports: [
+      { member: "shared", name: "ClusterArn", node: "shared/Cluster" },
+      { member: "shared", name: "ListenerArn", node: "shared/Listener" },
+    ],
+    imports: [
+      { member: "web", name: "clusterArn", node: "web/clusterArn" },
+      { member: "web", name: "listenerArn", node: "web/listenerArn" },
+      { member: "web", name: "queueUrl", node: "web/queueUrl" },
+    ],
+  };
+
+  test("inferred joins carry their label and composed node ids, and a declared link suppresses its inferred edge", async () => {
+    const rows = graphLinks(decl, graph, builtinKindRegistry());
+    expect(rows).toEqual([
+      { consumer: "web", producer: "shared", output: "ClusterArn", kind: "output", origin: "declared", label: "exact", input: null, resolves: "source", status: "resolved", reason: null, to: "shared/Cluster" },
+      {
+        consumer: "web",
+        producer: "shared",
+        output: "ListenerArn",
+        kind: "output",
+        origin: "inferred:joinKey",
+        label: "folded",
+        input: "listenerArn",
+        resolves: "source",
+        status: "resolved",
+        reason: null,
+        from: "web/listenerArn",
+        to: "shared/Listener",
+      },
+      {
+        consumer: "web",
+        producer: "legacy",
+        output: "QueueUrl",
+        kind: "output",
+        origin: "inferred:joinKey",
+        label: "folded",
+        input: "queueUrl",
+        resolves: "source",
+        status: "resolved",
+        reason: null,
+        from: "web/queueUrl",
+      },
+    ]);
+  });
+
+  test("without kinds, only composed members are link targets", async () => {
+    expect(graphLinks(decl, graph).map((r) => r.status === "ambiguous" ? "" : r.producer)).toEqual(["shared", "shared"]);
+  });
+
+  test("the linked member pairs, for the pipeline checks' environment rule", async () => {
+    expect(declaredMemberLinks(decl)).toEqual([{ consumer: "web", producer: "shared" }]);
+  });
+});
+
+describe("the declaration's link fields", () => {
+  const read = (members: unknown[]) => parseDeclaration(declaration(members), "chant.workspace.json");
+
+  test("links and outputs are read in file order, with pointers", async () => {
+    const d = read([
+      { name: "a", dir: "a", kind: "other", because: "x", outputs: ["One", "Two"] },
+      { name: "b", dir: "b", kind: "chant", links: [{ member: "a", output: "One" }, { member: "a", output: "Two", kind: "output" }] },
+    ]);
+    expect(d.members[0].outputs).toEqual(["One", "Two"]);
+    expect(d.members[1].outputs).toBeNull();
+    expect(d.members[1].links).toEqual([
+      { member: "a", output: "One", kind: null, pointer: "/members/1/links/0" },
+      { member: "a", output: "Two", kind: "output", pointer: "/members/1/links/1" },
+    ]);
+  });
+
+  test("a group has no links, and a link has only member, output, kind and x- fields", async () => {
+    expect(() => read([{ name: "ex", kind: "examples", glob: "examples/*", links: [] }])).toThrow(WorkspaceReadError);
+    expect(() => read([{ name: "b", dir: "b", kind: "chant", links: [{ member: "a", output: "One", hash: "x" }] }])).toThrow(/unknown field "hash"/);
+    expect(() => read([{ name: "b", dir: "b", kind: "chant", links: [{ member: "a" }] }])).toThrow(/missing required field "output"/);
+    expect(() => read([{ name: "b", dir: "b", kind: "chant", links: [{ member: "a", output: "" }] }])).toThrow(WorkspaceReadError);
+    expect(read([{ name: "b", dir: "b", kind: "chant", links: [{ member: "a", output: "One", "x-note": "hi" }] }]).members[0].links).toHaveLength(1);
+  });
+});
+
+describe("the chant repository's own declaration (#2557)", () => {
+  test("has no link finding", async () => {
+    const report = await runDeclarationChecks(resolve(import.meta.dirname, "../../../.."));
+    expect(report.diagnostics.filter((d) => /^WSP09\d$/.test(d.ruleId))).toEqual([]);
+    expect(report.links.filter((r) => r.status !== "resolved")).toEqual([]);
+  });
+});

package/src/workspace/links.ts

@@ -0,0 +1,331 @@
+/**
+ * Member links (#2524 D6, #2539; ws-008).
+ *
+ * A member link is stated once, on the consumer, as `{member, output}`, and it
+ * is matched exactly against the outputs the producer exposes. Which outputs
+ * a member exposes is up to its kind ({@link KindOutputs}): a `chant` member's
+ * are read from its source, a nested workspace exposes none, and `other` and
+ * kinds from a package expose what the kind and the entry list.
+ *
+ * A join nobody wrote down is inferred: a `chant` consumer's parameter is
+ * matched to other members' outputs with the core {@link joinKey}, and the
+ * join is labelled `exact` or `folded`. A parameter that matches two or more
+ * outputs is an ambiguity row, not an edge. A declared link from the same
+ * consumer to one of the matched outputs settles it: the inferred rows for
+ * 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
+ * resolved (`source`; `check --live` comes later) and its status. A link that
+ * can't be resolved is kept, with the reason.
+ *
+ * {@link resolveLinks} takes the members' handles as plain data, so the same
+ * rules serve `chant workspace check`, which reads the handles from source
+ * (`sourceMemberHandles` in `./member-handles.ts`, which loads the TypeScript
+ * parser), and `chant workspace graph`, which reads
+ * them from each member's graph IR ({@link irMemberHandles}).
+ */
+
+import { joinKey, joinLabel, type JoinLabel } from "../join-key";
+import type { Declaration, LinkDeclaration, Member } from "./declaration";
+import type { KindRegistry, MemberKind } from "./kinds";
+
+/** The link kinds chant knows. Closed: a link of any other kind fails closed. */
+export const LINK_KINDS = ["output"] as const;
+export const DEFAULT_LINK_KIND = "output";
+
+/** How a row was found: written down, or inferred by the named rule. */
+export type LinkOrigin = "declared" | "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;
+}
+
+/** What a member offers links, and what it reads. */
+export interface MemberHandles {
+  member: string;
+  outputs: JoinHandle[];
+  /** Parameters a join may feed. Only `chant` members have them. */
+  inputs: JoinHandle[];
+  /**
+   * Whether `outputs` is every output the member exposes. When it isn't, a
+   * link to a name not in the list is unresolved, not missing.
+   */
+  complete: boolean;
+  /** Why the list is incomplete, or why the member exposes none. */
+  why: string | null;
+  /** True when the member's kind exposes no outputs at all. */
+  exposesNone: boolean;
+}
+
+interface RowBase {
+  consumer: string;
+  kind: string;
+  origin: LinkOrigin;
+  resolves: "source";
+  /** Why the row is not `resolved`, or null. */
+  reason: string | null;
+}
+
+/** A declared link, or an inferred join with one producer. */
+export interface LinkRow extends RowBase {
+  status: "resolved" | "missing" | "unresolved" | "invalid";
+  producer: string;
+  output: string;
+  /** `exact` for every declared link; `exact` or `folded` for an inferred one. */
+  label: JoinLabel;
+  /** The consumer's parameter an inferred join feeds; null for a declared link. */
+  input: string | null;
+  /** The consumer's parameter node and the producer's output node, when known. */
+  from?: string;
+  to?: string;
+  /** The declared link's JSON Pointer in the declaration. */
+  pointer?: string;
+}
+
+/** A parameter that joins outputs of two or more producers (or two outputs of one). */
+export interface AmbiguousRow extends RowBase {
+  status: "ambiguous";
+  input: string;
+  from?: string;
+  candidates: { producer: string; output: string; label: JoinLabel; to?: string }[];
+}
+
+export type LinkTableRow = LinkRow | AmbiguousRow;
+
+/** A link between two members, in the shape the pipeline checks read (#2542). */
+export interface MemberLinkPair {
+  consumer: string;
+  producer: string;
+}
+
+/**
+ * The member pairs the declaration links, consumer first, once each, in
+ * declaration order. Only links to a declared member other than the consumer
+ * count.
+ */
+export function declaredMemberLinks(declaration: Declaration): MemberLinkPair[] {
+  const names = new Set(declaration.members.map((m) => m.name));
+  const seen = new Set<string>();
+  const out: MemberLinkPair[] = [];
+  for (const m of declaration.members) {
+    for (const l of m.links) {
+      const key = `${m.name}\0${l.member}`;
+      if (l.member === m.name || !names.has(l.member) || seen.has(key)) continue;
+      seen.add(key);
+      out.push({ consumer: m.name, producer: l.member });
+    }
+  }
+  return out;
+}
+
+const cmp = (a: string, b: string) => (a < b ? -1 : a > b ? 1 : 0);
+
+/** Why a declared link's target is not a member it may name, or undefined. */
+export function linkTargetProblem(declaration: Declaration, consumer: Member, link: LinkDeclaration): string | undefined {
+  if (link.member === consumer.name) return `member ${consumer.name} links to itself; a link joins two members`;
+  const entry = declaration.entries.find((e) => e.name === link.member);
+  if (!entry) return `member ${consumer.name} links to ${link.member}, which is not a member of this workspace`;
+  if (entry.type === "group") return `member ${consumer.name} links to ${link.member}, which is an example group; a group has no links`;
+  return undefined;
+}
+
+/** Output names that fold to the same key as `name`, for a "did you mean" hint. */
+function nearNames(name: string, outputs: JoinHandle[]): string[] {
+  const key = joinKey(name);
+  return [...new Set(outputs.filter((o) => o.name !== name && joinKey(o.name) === key).map((o) => o.name))].sort(cmp);
+}
+
+/**
+ * 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.
+ */
+export function resolveLinks(declaration: Declaration, handles: ReadonlyMap<string, MemberHandles>): LinkTableRow[] {
+  const rows: LinkTableRow[] = [];
+  const declaredTargets = new Map<string, Set<string>>();
+
+  for (const consumer of declaration.members) {
+    for (const link of consumer.links) {
+      const kind = link.kind ?? DEFAULT_LINK_KIND;
+      const row: LinkRow = {
+        consumer: consumer.name,
+        producer: link.member,
+        output: link.output,
+        kind,
+        origin: "declared",
+        label: "exact",
+        input: null,
+        resolves: "source",
+        status: "resolved",
+        reason: null,
+        pointer: link.pointer,
+      };
+      rows.push(row);
+      const targetProblem = linkTargetProblem(declaration, consumer, link);
+      if (targetProblem) {
+        row.status = "invalid";
+        row.reason = targetProblem;
+        continue;
+      }
+      (declaredTargets.get(consumer.name) ?? declaredTargets.set(consumer.name, new Set()).get(consumer.name)!).add(`${link.member}\0${link.output}`);
+      if (!(LINK_KINDS as readonly string[]).includes(kind)) {
+        row.status = "invalid";
+        row.reason = `the link kind ${kind} is not one chant knows; known link kinds: ${LINK_KINDS.join(", ")}`;
+        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");
+      }
+    }
+  }
+
+  // Inferred joins: a consumer's parameter against every other member's outputs.
+  const inferred: LinkTableRow[] = [];
+  for (const consumer of declaration.members) {
+    const mine = handles.get(consumer.name);
+    if (!mine) continue;
+    const declared = declaredTargets.get(consumer.name) ?? new Set<string>();
+    for (const input of mine.inputs) {
+      const candidates: { producer: string; output: string; label: JoinLabel; to?: string }[] = [];
+      for (const producer of declaration.members) {
+        if (producer.name === consumer.name) continue;
+        for (const o of handles.get(producer.name)?.outputs ?? []) {
+          const label = joinLabel(input.name, o.name);
+          if (!label) continue;
+          if (candidates.some((c) => c.producer === producer.name && c.output === o.name)) continue;
+          candidates.push({ producer: producer.name, output: o.name, label, ...(o.node ? { to: o.node } : {}) });
+        }
+      }
+      if (candidates.length === 0) continue;
+      // A declared link to one of the matches settles the parameter.
+      if (candidates.some((c) => declared.has(`${c.producer}\0${c.output}`))) continue;
+      const base = { consumer: consumer.name, kind: DEFAULT_LINK_KIND, origin: "inferred:joinKey" as const, resolves: "source" as const };
+      if (candidates.length === 1) {
+        const c = candidates[0];
+        inferred.push({
+          ...base,
+          status: "resolved",
+          reason: null,
+          producer: c.producer,
+          output: c.output,
+          label: c.label,
+          input: input.name,
+          ...(input.node ? { from: input.node } : {}),
+          ...(c.to ? { to: c.to } : {}),
+        });
+      } else {
+        candidates.sort((a, b) => cmp(a.producer, b.producer) || cmp(a.output, b.output));
+        const producers = new Set(candidates.map((c) => c.producer));
+        inferred.push({
+          ...base,
+          status: "ambiguous",
+          reason:
+            producers.size > 1
+              ? `parameter ${input.name} of ${consumer.name} matches outputs of ${[...producers].join(" and ")}`
+              : `parameter ${input.name} of ${consumer.name} matches ${candidates.map((c) => c.output).join(" and ")} of ${candidates[0].producer}`,
+          input: input.name,
+          ...(input.node ? { from: input.node } : {}),
+          candidates,
+        });
+      }
+    }
+  }
+  inferred.sort((a, b) => cmp(a.consumer, b.consumer) || cmp(a.input ?? "", b.input ?? ""));
+  return [...rows, ...inferred];
+}
+
+// ── Where the handles come from ──────────────────────────────────────────────
+
+/**
+ * The handles of a member whose kind lists its outputs, or exposes none.
+ * Undefined for a kind whose outputs are read from the member (`chant`).
+ */
+export function kindHandles(m: Member, kind: MemberKind): MemberHandles | undefined {
+  const outputs = kind.outputs;
+  if (outputs.from === "none") {
+    return { member: m.name, outputs: [], inputs: [], complete: true, why: `${m.name} is kind ${m.kind}, which exposes no outputs as link targets`, exposesNone: true };
+  }
+  if (outputs.from === "declared") {
+    const names = [...new Set([...outputs.names, ...(m.outputs ?? [])])];
+    return { member: m.name, outputs: names.map((name) => ({ name })), inputs: [], complete: true, why: null, exposesNone: false };
+  }
+  return undefined;
+}
+
+/** The part of a composed workspace graph (#2537) the links read. */
+export interface ComposedHandles {
+  /** Members whose IR was composed. */
+  composed: readonly string[];
+  exports: readonly { member: string; name: string; node?: string }[];
+  imports: readonly { member: string; name: string; node: string }[];
+}
+
+/**
+ * Every composed member's handles, from the `exports` and `imports` of the
+ * composed workspace graph, for its `links` section. Node ids are the
+ * composed ones (`<member>/<id>`). A member's IR lists all its outputs, so
+ * its list is complete.
+ */
+export function irMemberHandles(graph: ComposedHandles): Map<string, MemberHandles> {
+  const out = new Map<string, MemberHandles>();
+  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 } : {}) })),
+      inputs: graph.imports.filter((i) => i.member === member).map((i) => ({ name: i.name, node: i.node })),
+      complete: true,
+      why: null,
+      exposesNone: false,
+    });
+  }
+  return out;
+}
+
+/**
+ * The `links` section of the composed workspace graph (#2537, #2524 D8):
+ * the declared links and inferred joins, with composed node ids on the ends
+ * that have one. Declared links suppress the inferred edges they cover.
+ * 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[] {
+  const handles = irMemberHandles(graph);
+  for (const m of declaration.members) {
+    const kind = kinds?.get(m.kind);
+    if (handles.has(m.name) || !kind) continue;
+    const listed = kindHandles(m, kind);
+    if (listed) handles.set(m.name, listed);
+  }
+  return resolveLinks(declaration, handles).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;
+    return rest;
+  });
+}