@intentius/chant 0.80.0 → 0.81.0

package/src/workspace/checks.ts

@@ -0,0 +1,461 @@
+/**
+ * Declaration checks (#2535; #2524 D16, ws-028).
+ *
+ * A {@link WorkspaceCheck} looks at the declaration, the tree it describes
+ * and the kinds the workspace can read, and returns findings in the
+ * post-synth diagnostic shape with a `WSP` id. `chant workspace check` runs
+ * them and prints the findings through lint's reporters, so `--format json`
+ * and `--format sarif` come for free. `chant lint` never loads this module.
+ *
+ * The declaration sets the severity of a check through `checks`, and
+ * suppresses a check for one entry through that entry's `suppress`. Some
+ * checks are fixed: an unknown kind, a tie between probes and a probe that
+ * claims an `other` directory always fail (#2524 D3), and a declaration that
+ * can't be read has no settings to apply.
+ *
+ * Checks that need more than the declaration and the tree read facts
+ * gathered before any check runs ({@link WorkspaceFacts}): member ledgers
+ * (./checks/ledgers.ts), recorded pipelines (./checks/pipelines.ts) and
+ * generated files (./checks/generated.ts). All of them share one id range
+ * (#2641):
+ *
+ * | Ids | Checks |
+ * |---|---|
+ * | WSP001 to WSP011 | the declaration and member kinds (this file) |
+ * | WSP071, WSP072 | member ledgers |
+ * | WSP081 to WSP083 | recorded pipelines |
+ * | WSP091 to WSP097 | member links (#2539) |
+ * | WSP101 to WSP106 | generated files |
+ */
+
+import { realpathSync } from "node:fs";
+import { relative, sep } from "node:path";
+import type { LintDiagnostic, LintRule, Severity } from "../lint/rule";
+import type { PostSynthDiagnostic } from "../lint/post-synth";
+import { readDeclaration, resolveGroups, WorkspaceReadError, type Declaration, type Entry, type ErrorLocation, type ResolvedGroup } from "./declaration";
+import type { ReasonCode } from "./reason-codes";
+import { parseJsonText, pointerToken, type TextLocation } from "./jsonc";
+import { loadKindRegistry, probeKind, resolveKind, type KindLoadProblem, type KindRegistry } from "./kinds";
+import { gitTop, workingTree, type WorkspaceTree } from "./tree";
+import { LINK_CHECKS, linkTable } from "./checks/links";
+import type { LinkTableRow } from "./links";
+import { gatherGeneratedFacts, GENERATED_CHECKS, type GeneratedFileFacts } from "./checks/generated";
+import { gatherLedgerFacts, LEDGER_CHECKS, type MemberLedgerFacts } from "./checks/ledgers";
+import { gatherPipelineFacts, PIPELINE_CHECKS, type MemberPipelineFacts } from "./checks/pipelines";
+
+/**
+ * What the checks beyond the declaration read, gathered from the checkout
+ * before any check runs. A field left out was not gathered, and the checks
+ * that read it find nothing.
+ */
+export interface WorkspaceFacts {
+  /** Each `chant` member's ownership stack, environments and chant version. */
+  ledgers?: readonly MemberLedgerFacts[];
+  /** Each member's recorded generated files and the environments they deploy. */
+  pipelines?: readonly MemberPipelineFacts[];
+  /** Each declared or implicit generated file, with what its generator produced. */
+  generated?: readonly GeneratedFileFacts[];
+}
+
+/** What every declaration check reads. */
+export interface WorkspaceCheckContext {
+  declaration: Declaration;
+  tree: WorkspaceTree;
+  groups: ResolvedGroup[];
+  kinds: KindRegistry;
+  /** Why some pinned kinds could not be read. */
+  kindProblems: KindLoadProblem[];
+  /** The facts gathered before the checks ran. */
+  facts?: WorkspaceFacts;
+}
+
+/**
+ * A finding from a declaration check: the post-synth diagnostic shape, with
+ * `entity` naming the entry it is about and `pointer` the place in the
+ * declaration to show.
+ */
+export interface WorkspaceDiagnostic extends PostSynthDiagnostic {
+  /** A JSON Pointer into the declaration. */
+  pointer: string;
+}
+
+export interface WorkspaceCheck {
+  /** `WSP` and three digits. Public once shipped. */
+  id: string;
+  /** A short name, for listings. */
+  name: string;
+  description: string;
+  severity: Severity;
+  /** False when the declaration may neither change the severity nor suppress it. */
+  configurable: boolean;
+  check(ctx: WorkspaceCheckContext): WorkspaceDiagnostic[];
+}
+
+/** A diagnostic ready for lint's reporters, with the entry it is about. */
+export interface WorkspaceFinding extends LintDiagnostic {
+  entity?: string;
+  /** The read contract's reason code, for a WSP001 finding: why the declaration can't be read (#2536). */
+  code?: ReasonCode;
+}
+
+export interface SuppressedFinding extends WorkspaceFinding {
+  reason: string;
+}
+
+export interface DeclarationCheckReport {
+  /** The declaration file, relative to the directory the report was made for. */
+  file: string;
+  diagnostics: WorkspaceFinding[];
+  suppressed: SuppressedFinding[];
+  /** The member links, declared and inferred, as resolved in source (#2539). */
+  links: LinkTableRow[];
+  /** Whether an error-severity finding is active. */
+  ok: boolean;
+}
+
+const HELP = "https://intentius.io/chant/cli/workspace-check/#declaration-checks";
+
+const memberDir = (dir: string) => (dir === "." ? "" : dir);
+
+function entryFinding(check: WorkspaceCheck, entry: Entry, field: string | null, message: string): WorkspaceDiagnostic {
+  return {
+    checkId: check.id,
+    severity: check.severity,
+    message,
+    entity: entry.name,
+    pointer: field ? `${entry.pointer}/${field}` : entry.pointer,
+  };
+}
+
+/** The dir exists and the kind is known: the members every probe check reads. */
+function readableMembers(ctx: WorkspaceCheckContext) {
+  return ctx.declaration.members.filter((m) => ctx.tree.stat(memberDir(m.dir)) === "dir" && ctx.kinds.get(m.kind) !== undefined);
+}
+
+/** The first id of the read failure, used by {@link runDeclarationChecks} when the declaration can't be read. */
+export const UNREADABLE_CHECK_ID = "WSP001";
+
+export const WORKSPACE_CHECKS: readonly WorkspaceCheck[] = [
+  {
+    id: "WSP001",
+    name: "declaration-unreadable",
+    description: "The declaration can be read: it parses, matches the schema and keeps the placement rules.",
+    severity: "error",
+    configurable: false,
+    // Reported by runDeclarationChecks, since a declaration that can't be read gives no context.
+    check: () => [],
+  },
+  {
+    id: "WSP002",
+    name: "kinds-unreadable",
+    description: "Every pinned package's kinds can be read: it is installed at the pinned version, and its ./workspace-kinds file is valid kind data.",
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      return ctx.kindProblems.map((p) => ({ checkId: this.id, severity: this.severity, message: p.message, pointer: `/pins/${p.pin}` }));
+    },
+  },
+  {
+    id: "WSP003",
+    name: "kind-unknown",
+    description: "Every member's kind is built in or supplied by a pinned package. Unknown kinds fail closed.",
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      return ctx.declaration.members
+        .filter((m) => ctx.kinds.get(m.kind) === undefined)
+        .map((m) => entryFinding(this, m, "kind", `member ${m.name} has kind ${m.kind}, which no built-in kind or pinned package supplies; known kinds: ${ctx.kinds.names().join(", ")}`));
+    },
+  },
+  {
+    id: "WSP004",
+    name: "member-dir-missing",
+    description: "Every member's directory exists.",
+    severity: "error",
+    configurable: true,
+    check(ctx) {
+      return ctx.declaration.members
+        .filter((m) => ctx.tree.stat(memberDir(m.dir)) !== "dir")
+        .map((m) => entryFinding(this, m, "dir", `member ${m.name}'s directory ${m.dir} does not exist${ctx.tree.label}`));
+    },
+  },
+  {
+    id: "WSP005",
+    name: "kind-probe-failed",
+    description: "Every member's directory is what its kind reads, such as a chant config for a chant member.",
+    severity: "error",
+    configurable: true,
+    check(ctx) {
+      return readableMembers(ctx)
+        .filter((m) => !probeKind(ctx.kinds.get(m.kind)!, ctx.tree, memberDir(m.dir)))
+        .map((m) => entryFinding(this, m, "kind", `member ${m.name} (${m.dir}) is not ${ctx.kinds.get(m.kind)!.description}`));
+    },
+  },
+  {
+    id: "WSP006",
+    name: "kind-probe-tie",
+    description: "No directory is claimed by two kinds of the same highest precedence. Ties fail.",
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      const out: WorkspaceDiagnostic[] = [];
+      for (const m of readableMembers(ctx)) {
+        const { tie } = resolveKind(ctx.kinds, ctx.tree, memberDir(m.dir), m.dir === "." ? ["workspace"] : []);
+        if (tie.length === 0) continue;
+        const names = tie.map((k) => `${k.name} (${k.source})`).join(" and ");
+        out.push(entryFinding(this, m, "kind", `the probes of ${names} all claim ${m.dir} with precedence ${tie[0].precedence}; a tie fails, so one of those kinds needs a different precedence`));
+      }
+      return out;
+    },
+  },
+  {
+    id: "WSP007",
+    name: "kind-outranked",
+    description: "When several kinds claim a member's directory, the declared kind is the one the precedence order picks.",
+    severity: "error",
+    configurable: true,
+    check(ctx) {
+      const out: WorkspaceDiagnostic[] = [];
+      for (const m of readableMembers(ctx)) {
+        if (m.kind === "other") continue;
+        const { winner } = resolveKind(ctx.kinds, ctx.tree, memberDir(m.dir), m.dir === "." ? ["workspace"] : []);
+        if (!winner || winner.name === m.kind) continue;
+        out.push(entryFinding(this, m, "kind", `member ${m.name} is declared ${m.kind}, and kind ${winner.name} (precedence ${winner.precedence}) claims ${m.dir} first; declare it as ${winner.name}`));
+      }
+      return out;
+    },
+  },
+  {
+    id: "WSP008",
+    name: "other-claimed",
+    description: "No other member's directory is claimed by a registered kind's probe.",
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      const out: WorkspaceDiagnostic[] = [];
+      for (const m of readableMembers(ctx)) {
+        if (m.kind !== "other") continue;
+        const { claims } = resolveKind(ctx.kinds, ctx.tree, memberDir(m.dir), m.dir === "." ? ["workspace"] : []);
+        if (claims.length === 0) continue;
+        out.push(entryFinding(this, m, "kind", `member ${m.name} is declared other, and kind ${claims[0].name} claims ${m.dir}: it is ${claims[0].description}; declare it as ${claims[0].name}`));
+      }
+      return out;
+    },
+  },
+  {
+    id: "WSP009",
+    name: "other-member",
+    description: "A member of kind other is one chant does not read. It is reported so that it stays a decision.",
+    severity: "warning",
+    configurable: true,
+    check(ctx) {
+      return ctx.declaration.members
+        .filter((m) => m.kind === "other")
+        .map((m) => entryFinding(this, m, null, `member ${m.name} (${m.dir}) is kind other, which chant does not read: ${m.because}`));
+    },
+  },
+  {
+    id: "WSP010",
+    name: "group-empty",
+    description: "Every example group matches at least one chant project.",
+    severity: "warning",
+    configurable: true,
+    check(ctx) {
+      return ctx.groups
+        .filter((g) => g.matches.length === 0)
+        .map((g) => entryFinding(this, g.group, "glob", `example group ${g.group.name} matches no chant project${ctx.tree.label}`));
+    },
+  },
+  {
+    id: "WSP011",
+    name: "check-settings-invalid",
+    description: "The declaration's checks and suppress settings name known, configurable WSP ids.",
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      const out: WorkspaceDiagnostic[] = [];
+      for (const id of Object.keys(ctx.declaration.checks)) {
+        const problem = settingProblem(id);
+        if (problem) out.push({ checkId: this.id, severity: this.severity, message: `checks sets ${id}, which ${problem}`, pointer: `/checks/${pointerToken(id)}` });
+      }
+      for (const e of ctx.declaration.entries) {
+        e.suppress.forEach((s, i) => {
+          const problem = settingProblem(s.check);
+          if (problem) out.push(entryFinding(this, e, `suppress/${i}/check`, `${e.name} suppresses ${s.check}, which ${problem}`));
+        });
+      }
+      return out;
+    },
+  },
+  // Member ledgers (#2538).
+  ...LEDGER_CHECKS,
+  // Recorded pipelines (#2542).
+  ...PIPELINE_CHECKS,
+  // Member links (#2539), WSP091 to WSP097.
+  ...LINK_CHECKS,
+  // Generated files (#2541).
+  ...GENERATED_CHECKS,
+];
+
+const BY_ID = new Map(WORKSPACE_CHECKS.map((c) => [c.id, c]));
+
+function settingProblem(id: string): string | undefined {
+  const check = BY_ID.get(id);
+  if (!check) return `is not a declaration check; known checks: ${WORKSPACE_CHECKS.map((c) => c.id).join(", ")}`;
+  if (!check.configurable) return `is fixed: it can't be turned down or suppressed`;
+  return undefined;
+}
+
+/**
+ * The checks' metadata as lint rules, for the SARIF reporter's rule list.
+ * They are never run as lint rules.
+ */
+export function workspaceCheckRules(): LintRule[] {
+  return WORKSPACE_CHECKS.map((c) => ({
+    id: c.id,
+    severity: c.severity,
+    category: "correctness",
+    description: `${c.name}: ${c.description}`,
+    helpUri: HELP,
+    check: () => [],
+  }));
+}
+
+/** Run every check over a readable declaration. The settings are not applied yet. */
+export function runWorkspaceChecks(ctx: WorkspaceCheckContext): WorkspaceDiagnostic[] {
+  return WORKSPACE_CHECKS.flatMap((c) => c.check(ctx));
+}
+
+/**
+ * Apply the declaration's `checks` severities and entries' `suppress` to the
+ * findings. Fixed checks keep their severity and can't be suppressed; a
+ * setting that tries is itself a WSP011 finding.
+ */
+export function applyCheckSettings(
+  declaration: Declaration,
+  findings: WorkspaceDiagnostic[],
+): { active: WorkspaceDiagnostic[]; suppressed: (WorkspaceDiagnostic & { reason: string })[] } {
+  const active: WorkspaceDiagnostic[] = [];
+  const suppressed: (WorkspaceDiagnostic & { reason: string })[] = [];
+  const byName = new Map(declaration.entries.map((e) => [e.name, e]));
+  for (const f of findings) {
+    const check = BY_ID.get(f.checkId);
+    if (!check?.configurable) {
+      active.push(f);
+      continue;
+    }
+    const setting = declaration.checks[f.checkId];
+    if (setting === "off") continue;
+    const finding = setting ? { ...f, severity: setting } : f;
+    const suppression = f.entity !== undefined ? byName.get(f.entity)?.suppress.find((s) => s.check === f.checkId) : undefined;
+    if (suppression) suppressed.push({ ...finding, reason: suppression.because });
+    else active.push(finding);
+  }
+  return { active, suppressed };
+}
+
+export interface DeclarationCheckOptions {
+  /**
+   * Gather the facts the ledger, pipeline and generated-file checks read.
+   * On by default. Off, only the declaration and kind checks find anything,
+   * and no member config is read.
+   */
+  gather?: boolean;
+  /** Run each declared generator and compare its output (`--generated`). Off by default: generators run member code. */
+  runGenerators?: boolean;
+  /**
+   * The files to check, such as a revision's (`chant workspace check --at`,
+   * #2536); the working tree under `root` by default. Kinds still come from
+   * the packages installed under `root`. With a tree, no facts are
+   * gathered: they describe the working tree, not the revision.
+   */
+  tree?: WorkspaceTree;
+}
+
+/**
+ * Gather {@link WorkspaceFacts} for the declaration in `root`. Member
+ * configs are read statically, never run: the ledger facts read `ownership`
+ * and `environments`, and the generated-file facts read `lexicons`. Declared
+ * generators run only when `runGenerators` says so, and they are the only
+ * member code this runs.
+ */
+export async function gatherWorkspaceFacts(root: string, declaration: Declaration, options: { runGenerators?: boolean } = {}): Promise<WorkspaceFacts> {
+  // Pipeline records hold paths relative to the repository root.
+  const top = gitTop(root);
+  const prefix = top ? relative(realpath(top), realpath(root)).split(sep).join("/") || "." : ".";
+  return {
+    ledgers: await gatherLedgerFacts(root, declaration),
+    pipelines: gatherPipelineFacts(root, declaration, prefix),
+    generated: await gatherGeneratedFacts(root, declaration, { runGenerators: options.runGenerators === true }),
+  };
+}
+
+function realpath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+/**
+ * Read the declaration in `root` (an absolute directory holding one, or the
+ * files of `options.tree` when given, such as a revision's), load the kinds
+ * its pins supply from `root`, gather the facts the member checks read, run
+ * every check and apply the declaration's settings. `file` in the findings
+ * is the declaration's path as `display` says, relative to where the
+ * command runs. Never throws a {@link WorkspaceReadError}: a declaration that
+ * can't be read is one WSP001 finding.
+ */
+export async function runDeclarationChecks(
+  root: string,
+  display: (file: string) => string = (f) => f,
+  options: DeclarationCheckOptions = {},
+): Promise<DeclarationCheckReport> {
+  const tree = options.tree ?? workingTree(root);
+  let declaration: Declaration;
+  let groups: ResolvedGroup[];
+  try {
+    declaration = readDeclaration(tree, "", { rootChant: true });
+    groups = resolveGroups(declaration, tree);
+  } catch (err) {
+    if (!(err instanceof WorkspaceReadError)) throw err;
+    const location: ErrorLocation = err.location ?? { file: "chant.workspace.json", line: 1, column: 1 };
+    const diagnostic: WorkspaceFinding = {
+      file: display(location.file),
+      line: location.line,
+      column: location.column,
+      ruleId: UNREADABLE_CHECK_ID,
+      severity: "error",
+      message: `${err.code}: ${err.message}`,
+      code: err.code,
+    };
+    return { file: display(location.file), diagnostics: [diagnostic], suppressed: [], links: [], ok: false };
+  }
+  const { registry, problems } = loadKindRegistry(declaration.pins, root);
+  const facts = options.gather === false || options.tree ? {} : await gatherWorkspaceFacts(root, declaration, options);
+  const ctx: WorkspaceCheckContext = { declaration, tree, groups, kinds: registry, kindProblems: problems, facts };
+  const findings = runWorkspaceChecks(ctx);
+  const { active, suppressed } = applyCheckSettings(declaration, findings);
+
+  const parsed = parseJsonText(tree.read(declaration.file), { jsonc: declaration.file.endsWith(".jsonc") });
+  const locate = (pointer: string): TextLocation => (parsed.ok ? parsed.locate(pointer) : { line: 1, column: 1 });
+  const file = display(declaration.file);
+  const toFinding = (d: WorkspaceDiagnostic): WorkspaceFinding => ({
+    file,
+    ...locate(d.pointer),
+    ruleId: d.checkId,
+    severity: d.severity,
+    message: d.message,
+    ...(d.entity !== undefined ? { entity: d.entity } : {}),
+  });
+  const order = (a: LintDiagnostic, b: LintDiagnostic) => a.line - b.line || a.column - b.column || (a.ruleId < b.ruleId ? -1 : a.ruleId > b.ruleId ? 1 : 0);
+  const diagnostics = active.map(toFinding).sort(order);
+  return {
+    file,
+    diagnostics,
+    suppressed: suppressed.map((s) => ({ ...toFinding(s), reason: s.reason })).sort(order),
+    links: linkTable(ctx),
+    ok: !diagnostics.some((d) => d.severity === "error"),
+  };
+}

package/src/workspace/compose-graph.test.ts

@@ -0,0 +1,146 @@
+/**
+ * The composed workspace IR (#2537, #2524 D8): `<member>/<id>` ids,
+ * `groups.byMember`, and v1 output from old chants upgraded in place.
+ */
+
+import { describe, expect, test } from "vitest";
+import { GRAPH_IR_VERSION, type GraphIR } from "../graph-ir";
+import { parseDeclaration } from "./declaration";
+import { composeWorkspaceGraph, readMemberIr, WORKSPACE_GRAPH_VERSION, type ComposedMember } from "./compose-graph";
+
+const member = (name: string, dir: string): ComposedMember => ({
+  name,
+  dir,
+  kind: "chant",
+  status: "composed",
+  reason: null,
+  chant: "0.80.0",
+  irVersion: 1,
+});
+
+const web: GraphIR = {
+  version: 1,
+  nodes: [
+    { id: "Bucket", kind: "S3Bucket", lexicon: "aws", attrs: { name: "b" } },
+    { id: "web::Fn", kind: "LambdaFunction", lexicon: "aws", compositeInstance: "api", attrs: { env: { BUCKET: { $ref: "Bucket.Arn" } } } },
+  ],
+  edges: [{ from: "web::Fn", to: "Bucket", kind: "ref", viaAttr: "env" }],
+  groups: { byLexicon: { aws: ["Bucket", "web::Fn"] }, byStack: { web: ["web::Fn"], aws: ["Bucket"] }, byComposite: { Api: ["web::Fn"] } },
+  exports: [{ name: "BucketArn", node: "Bucket", attr: "Arn" }],
+};
+
+const db: GraphIR = {
+  nodes: [{ id: "Bucket", kind: "GcsBucket", lexicon: "gcp", attrs: {} }],
+  edges: [],
+  groups: { byLexicon: { gcp: ["Bucket"] }, byStack: { gcp: ["Bucket"] } },
+};
+
+describe("readMemberIr", () => {
+  test("stamps version 1 on output from a chant older than the version field", () => {
+    const read = readMemberIr(JSON.stringify(db));
+    expect("ir" in read && read.ir.version).toBe(1);
+    expect("ir" in read && read.irVersion).toBe(null);
+  });
+
+  test("keeps a versioned IR as it is", () => {
+    const read = readMemberIr(JSON.stringify(web));
+    expect("ir" in read && read.irVersion).toBe(GRAPH_IR_VERSION);
+  });
+
+  test("refuses an IR newer than this chant reads, with a reason code", () => {
+    const read = readMemberIr(JSON.stringify({ ...web, version: GRAPH_IR_VERSION + 1 }));
+    expect("reason" in read && read.reason.code).toBe("ir-version-unsupported");
+  });
+
+  test("gives output-unreadable for anything that is not an IR", () => {
+    for (const text of ["not json", "{}", '{"nodes": []}', "null"]) {
+      const read = readMemberIr(text);
+      expect("reason" in read && read.reason.code, text).toBe("output-unreadable");
+    }
+  });
+});
+
+describe("composeWorkspaceGraph", () => {
+  const doc = composeWorkspaceGraph({ name: "acme", root: "/w" }, [
+    { member: member("web", "apps/web"), ir: web },
+    { member: member("db", "db"), ir: (readMemberIr(JSON.stringify(db)) as { ir: GraphIR }).ir },
+    { member: { ...member("docs", "docs"), kind: "other", status: "skipped", reason: { code: "kind-not-run", message: "other" }, chant: null, irVersion: null } },
+  ]);
+
+  test("prefixes every id with its member, keeping :: for stacks", () => {
+    expect(doc.version).toBe(WORKSPACE_GRAPH_VERSION);
+    expect(doc.nodes.map((n) => n.id)).toEqual(["db/Bucket", "web/Bucket", "web/web::Fn"]);
+    expect(doc.nodes.find((n) => n.id === "web/web::Fn")).toMatchObject({
+      member: "web",
+      compositeInstance: "web/api",
+      attrs: { env: { BUCKET: { $ref: "web/Bucket.Arn" } } },
+    });
+    expect(doc.edges).toEqual([{ from: "web/web::Fn", to: "web/Bucket", kind: "ref", viaAttr: "env", member: "web" }]);
+    expect(doc.exports).toEqual([{ name: "BucketArn", node: "web/Bucket", attr: "Arn", member: "web" }]);
+  });
+
+  test("groups nodes by member, merges shared groups and prefixes member-scoped ones", () => {
+    expect(doc.groups.byMember).toEqual({ web: ["web/Bucket", "web/web::Fn"], db: ["db/Bucket"] });
+    expect(doc.groups.byLexicon).toEqual({ aws: ["web/Bucket", "web/web::Fn"], gcp: ["db/Bucket"] });
+    expect(doc.groups.byComposite).toEqual({ Api: ["web/web::Fn"] });
+    expect(doc.groups.byStack).toEqual({ "db/gcp": ["db/Bucket"], "web/aws": ["web/Bucket"], "web/web": ["web/web::Fn"] });
+  });
+
+  test("lists every member with its status, and leaves the link and record sections empty", () => {
+    expect(doc.members.map((m) => [m.name, m.status])).toEqual([
+      ["web", "composed"],
+      ["db", "composed"],
+      ["docs", "skipped"],
+    ]);
+    expect(doc.links).toEqual([]);
+    expect(doc.records).toEqual([]);
+  });
+
+  test("does not change the members' own IRs", () => {
+    expect(web.nodes[0].id).toBe("Bucket");
+    expect(web.edges[0].from).toBe("web::Fn");
+  });
+});
+
+describe("the links section (#2539)", () => {
+  test("inferred joins carry their label, and a declared link suppresses the inferred edge it covers", () => {
+    const consumer: GraphIR = {
+      version: 1,
+      nodes: [
+        { id: "bucketArn", kind: "Parameter", lexicon: "aws", attrs: {} },
+        { id: "BUCKET_ARN", kind: "Parameter", lexicon: "aws", attrs: {} },
+      ],
+      edges: [],
+      groups: {},
+      imports: [
+        { name: "bucketArn", node: "bucketArn" },
+        { name: "BUCKET_ARN", node: "BUCKET_ARN" },
+      ],
+    };
+    const declaration = parseDeclaration(
+      JSON.stringify({
+        name: "acme",
+        schema: 1,
+        members: [
+          { name: "web", dir: "web", kind: "chant" },
+          { name: "jobs", dir: "jobs", kind: "chant" },
+          { name: "app", dir: "app", kind: "chant", links: [{ member: "web", output: "BucketArn" }] },
+        ],
+      }),
+      "chant.workspace.json",
+    );
+    const inputs = [
+      { member: member("web", "web"), ir: structuredClone(web) },
+      { member: member("jobs", "jobs"), ir: structuredClone(consumer) },
+      { member: member("app", "app"), ir: structuredClone(consumer) },
+    ];
+    const doc = composeWorkspaceGraph({ name: "acme", root: "/w" }, inputs, { declaration });
+    expect(
+      doc.links.map((r) => (r.status === "ambiguous" ? "" : `${r.origin} ${r.label} ${r.from ?? r.consumer} -> ${r.to}`)),
+    ).toEqual([
+      "declared exact app -> web/Bucket",
+      "inferred:joinKey folded jobs/BUCKET_ARN -> web/Bucket",
+      "inferred:joinKey folded jobs/bucketArn -> web/Bucket",
+    ]);
+  });
+});