@intentius/chant 0.80.0 → 0.81.0

package/src/workspace/checks/ledgers.ts

@@ -0,0 +1,246 @@
+/**
+ * The workspace checks behind member ledgers (#2538, #2524 D7, ws-036 and
+ * ws-037).
+ *
+ * - `WSP071`: every `chant` member that stamps ownership markers uses its own
+ *   `ownership.stack`. Markers carry no member key, so the stack is what tells
+ *   two members' resources and receipts apart.
+ * - `WSP072`: members that write the flat ledger layout never share an
+ *   environment name. A member whose own chant is older than
+ *   {@link MEMBER_LEDGER_FLOOR} still writes `<env>/...` at the top of
+ *   `chant/lifecycle`, and so does the root member `.`; two flat writers with
+ *   one environment name would write the same files.
+ * - `WSP073` (info): a member's ledger settings could not be read without
+ *   running its config, so the two checks above could not compare it.
+ *
+ * The checks are pure functions over {@link MemberLedgerFacts}.
+ * {@link gatherLedgerFacts} collects those facts from a checkout, and
+ * `chant workspace check` gathers them before it runs {@link LEDGER_CHECKS}
+ * (#2641). WSP071 and WSP072 are fixed: a member that ignores either one
+ * writes its records or marks its resources as another member's. Member
+ * configs are read statically and never run.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { MEMBER_LEDGER_FLOOR } from "../../lifecycle/member-ledger";
+import type { WorkspaceCheck, WorkspaceCheckContext, WorkspaceDiagnostic } from "../checks";
+import { compareVersions, type Declaration } from "../declaration";
+
+export const WSP_DISTINCT_STACKS = "WSP071";
+export const WSP_FLAT_LEDGER_ENVIRONMENTS = "WSP072";
+export const WSP_LEDGER_SETTINGS_UNREAD = "WSP073";
+
+export interface LedgerFinding {
+  id: typeof WSP_DISTINCT_STACKS | typeof WSP_FLAT_LEDGER_ENVIRONMENTS;
+  severity: "error";
+  /** The members the finding is about, in declaration order. */
+  members: string[];
+  message: string;
+}
+
+/** What the ledger checks need to know about one `chant` member. */
+export interface MemberLedgerFacts {
+  name: string;
+  /** Relative to the workspace root; `"."` is the root member. */
+  dir: string;
+  /** `ownership.stack` when marking is on, else null. */
+  stack: string | null;
+  /** The environment names the member declares (`environments`, and a literal `ownership.env`). */
+  environments: string[];
+  /** The chant the member's own toolchain resolves, or null when none is installed. */
+  chantVersion: string | null;
+  /**
+   * Why the member's ledger settings could not be read without running its
+   * config. Such a member has no stack and no environments here, so neither
+   * check compares it; `WSP073` reports it instead.
+   */
+  unread?: string;
+}
+
+/** `WSP071`: no two members share an `ownership.stack`. */
+export function checkDistinctStacks(facts: readonly MemberLedgerFacts[]): LedgerFinding[] {
+  const byStack = new Map<string, MemberLedgerFacts[]>();
+  for (const f of facts) {
+    if (f.stack === null) continue;
+    byStack.set(f.stack, [...(byStack.get(f.stack) ?? []), f]);
+  }
+  const findings: LedgerFinding[] = [];
+  for (const [stack, members] of byStack) {
+    if (members.length < 2) continue;
+    const names = members.map((m) => m.name);
+    findings.push({
+      id: WSP_DISTINCT_STACKS,
+      severity: "error",
+      members: names,
+      message:
+        `members ${names.join(", ")} all set ownership.stack to ${JSON.stringify(stack)}; ` +
+        `ownership markers carry no member name, so each member needs its own stack. ` +
+        `Rename all but one in their chant.config.ts (chant workspace init proposes names).`,
+    });
+  }
+  return findings;
+}
+
+/** Whether `f` writes the flat ledger layout: the root member, or a member on a chant below the floor. */
+export function writesFlatLedger(f: MemberLedgerFacts, floor: string = MEMBER_LEDGER_FLOOR): boolean {
+  if (f.dir === ".") return true;
+  if (f.chantVersion === null) return false;
+  try {
+    return compareVersions(f.chantVersion, floor) < 0;
+  } catch {
+    // A version chant cannot read says nothing about the layout.
+    return false;
+  }
+}
+
+/** `WSP072`: flat-layout writers never share an environment name. */
+export function checkFlatLedgerEnvironments(
+  facts: readonly MemberLedgerFacts[],
+  floor: string = MEMBER_LEDGER_FLOOR,
+): LedgerFinding[] {
+  const flat = facts.filter((f) => writesFlatLedger(f, floor));
+  const byEnv = new Map<string, MemberLedgerFacts[]>();
+  for (const f of flat) {
+    for (const env of new Set(f.environments)) byEnv.set(env, [...(byEnv.get(env) ?? []), f]);
+  }
+  const findings: LedgerFinding[] = [];
+  for (const [env, members] of byEnv) {
+    if (members.length < 2) continue;
+    const names = members.map((m) => m.name);
+    const why = members.map((m) => (m.dir === "." ? `${m.name} is the root member` : `${m.name} runs chant ${m.chantVersion}`));
+    findings.push({
+      id: WSP_FLAT_LEDGER_ENVIRONMENTS,
+      severity: "error",
+      members: names,
+      message:
+        `members ${names.join(", ")} ${names.length === 2 ? "both" : "all"} write the flat ledger layout and share the environment ${JSON.stringify(env)}, ` +
+        `so their releases, snapshots and runs land in the same files on chant/lifecycle (${why.join("; ")}). ` +
+        `Upgrade the members below chant ${floor}, which write under _members/<member>/, or rename the environment in one of them.`,
+    });
+  }
+  return findings;
+}
+
+/** Both ledger checks, stack findings first. */
+export function checkLedgers(facts: readonly MemberLedgerFacts[], floor: string = MEMBER_LEDGER_FLOOR): LedgerFinding[] {
+  return [...checkDistinctStacks(facts), ...checkFlatLedgerEnvironments(facts, floor)];
+}
+
+// ── As workspace checks ──────────────────────────────────────────────────────
+
+/**
+ * A finding as a workspace diagnostic. It sits at the first member it names,
+ * in declaration order, and that member's entry is the one that can carry a
+ * `suppress` for a settable check.
+ */
+function toDiagnostic(check: WorkspaceCheck, ctx: WorkspaceCheckContext, f: LedgerFinding): WorkspaceDiagnostic {
+  const member = ctx.declaration.members.find((m) => m.name === f.members[0]);
+  return { checkId: check.id, severity: check.severity, message: f.message, entity: f.members[0], pointer: member?.pointer ?? "" };
+}
+
+/** The ledger checks, which read `ctx.facts.ledgers`. They find nothing when the facts were not gathered. */
+export const LEDGER_CHECKS: readonly WorkspaceCheck[] = [
+  {
+    id: WSP_DISTINCT_STACKS,
+    name: "ownership-stack-shared",
+    description: "No two chant members set the same ownership.stack. Ownership markers carry no member name, so the stack tells members' resources and receipts apart.",
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      return checkDistinctStacks(ctx.facts?.ledgers ?? []).map((f) => toDiagnostic(this, ctx, f));
+    },
+  },
+  {
+    id: WSP_FLAT_LEDGER_ENVIRONMENTS,
+    name: "flat-ledger-environment-shared",
+    description: `No two members that write the flat ledger layout (the root member, and members on a chant older than ${MEMBER_LEDGER_FLOOR}) share an environment name.`,
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      return checkFlatLedgerEnvironments(ctx.facts?.ledgers ?? []).map((f) => toDiagnostic(this, ctx, f));
+    },
+  },
+  {
+    id: WSP_LEDGER_SETTINGS_UNREAD,
+    name: "ledger-settings-unread",
+    description: "A chant member's ownership and environments could not be read from its config without running it, so WSP071 and WSP072 could not compare it.",
+    severity: "info",
+    configurable: true,
+    check(ctx) {
+      return (ctx.facts?.ledgers ?? [])
+        .filter((f) => f.unread !== undefined)
+        .map((f) => ({
+          checkId: this.id,
+          severity: this.severity,
+          message: `member ${f.name}'s ownership and environments were not compared with other members': ${f.unread}`,
+          entity: f.name,
+          pointer: ctx.declaration.members.find((m) => m.name === f.name)?.pointer ?? "",
+        }));
+    },
+  },
+];
+
+// ── Facts from a checkout ────────────────────────────────────────────────────
+
+/**
+ * The version of `@intentius/chant` that `dir`'s own toolchain resolves: the
+ * nearest `node_modules/@intentius/chant/package.json` walking up from `dir`,
+ * as Node's resolution would find it. Null when there is none.
+ */
+export function memberChantVersion(dir: string): string | null {
+  for (let d = resolve(dir); ; d = dirname(d)) {
+    const pkg = join(d, "node_modules", "@intentius", "chant", "package.json");
+    if (existsSync(pkg)) {
+      try {
+        const version = (JSON.parse(readFileSync(pkg, "utf-8")) as { version?: unknown }).version;
+        return typeof version === "string" ? version : null;
+      } catch {
+        return null;
+      }
+    }
+    if (dirname(d) === d) return null;
+  }
+}
+
+/** The config fields the ledger checks read. */
+const LEDGER_FIELDS = ["ownership", "environments"] as const;
+
+/**
+ * Collect {@link MemberLedgerFacts} for every `chant` member of `declaration`,
+ * whose workspace root is `root`. `ownership` and `environments` are read
+ * from each member's config statically (../../config-static.ts), the way
+ * `chant audit` reads lexicons: the config is never run (#2641). A member
+ * whose settings can't be read that way gets {@link MemberLedgerFacts.unread}
+ * with the reason, and no stack or environments.
+ */
+export async function gatherLedgerFacts(root: string, declaration: Declaration): Promise<MemberLedgerFacts[]> {
+  const { readConfigFieldsStatically } = await import("../../config-static");
+  const { ChantConfigSchema, environmentNames, resolveOwnershipStack } = await import("../../config");
+  const facts: MemberLedgerFacts[] = [];
+  for (const m of declaration.members) {
+    if (m.kind !== "chant") continue;
+    const dir = join(root, m.dir);
+    const base = { name: m.name, dir: m.dir, chantVersion: memberChantVersion(dir) };
+    const read = readConfigFieldsStatically(dir, LEDGER_FIELDS);
+    // No config: the kind probe reports the member (WSP005).
+    if (read.status === "no-config") continue;
+    const file = relative(root, read.configPath).split(sep).join("/");
+    const unread = (reason: string) => facts.push({ ...base, stack: null, environments: [], unread: `${file} can't be read without running it (${reason})` });
+    if (read.status === "unknown") {
+      unread(read.reason);
+      continue;
+    }
+    const parsed = ChantConfigSchema.pick({ ownership: true, environments: true }).safeParse(read.fields);
+    if (!parsed.success) {
+      unread(`its ${String(parsed.error.issues[0]?.path[0] ?? "settings")} value is not what a chant config takes`);
+      continue;
+    }
+    const config = parsed.data;
+    const environments = [...(environmentNames(config.environments) ?? [])];
+    const literalEnv = config.ownership?.env;
+    if (typeof literalEnv === "string" && !environments.includes(literalEnv)) environments.push(literalEnv);
+    facts.push({ ...base, stack: resolveOwnershipStack(config) ?? null, environments });
+  }
+  return facts;
+}

package/src/workspace/checks/links.ts

@@ -0,0 +1,183 @@
+/**
+ * The member-link checks, WSP091 to WSP097 (#2539; #2524 D6, ws-008).
+ *
+ * `chant workspace check` resolves every declared link in source: the
+ * producer's outputs come from its kind, and a `chant` producer's are read
+ * from its TypeScript without running it (`../member-handles.ts`). Nothing
+ * here reaches the network or starts a process. The rows themselves come
+ * from `../links.ts`, which `chant workspace graph` shares.
+ *
+ * | Id | Fails when |
+ * |---|---|
+ * | WSP091 | a link names no member, an example group, or its own member (fixed) |
+ * | WSP092 | a link's kind is not a link kind chant knows (fixed) |
+ * | WSP093 | the producer exposes no output of that name, as when it was renamed |
+ * | WSP094 | the producer's outputs can't be read in source, so the link is kept unresolved |
+ * | WSP095 | an inferred join is ambiguous: a parameter matches two or more outputs |
+ * | WSP096 | a consumer states the same link twice |
+ * | WSP097 | an entry lists `outputs` for a kind that doesn't take them from the entry |
+ */
+
+import type { WorkspaceCheck, WorkspaceCheckContext, WorkspaceDiagnostic } from "../checks";
+import type { Member } from "../declaration";
+import { sourceMemberHandles } from "../member-handles";
+import { DEFAULT_LINK_KIND, LINK_KINDS, linkTargetProblem, resolveLinks, type AmbiguousRow, type LinkRow, type LinkTableRow } from "../links";
+
+const tables = new WeakMap<WorkspaceCheckContext, LinkTableRow[]>();
+
+/** 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));
+    tables.set(ctx, rows);
+  }
+  return rows;
+}
+
+const declaredRows = (ctx: WorkspaceCheckContext) => linkTable(ctx).filter((r): r is LinkRow => r.status !== "ambiguous" && r.origin === "declared");
+
+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}` };
+}
+
+const describeLink = (row: LinkRow) => `${row.consumer}'s link to ${row.producer} output ${row.output}`;
+
+export const LINK_CHECKS: readonly WorkspaceCheck[] = [
+  {
+    id: "WSP091",
+    name: "link-target-unknown",
+    description: "Every member link names another member of the workspace. A link to an unknown name, an example group or the consumer itself fails closed.",
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      return ctx.declaration.members.flatMap((m) =>
+        m.links.flatMap((l) => {
+          const problem = linkTargetProblem(ctx.declaration, m, l);
+          return problem ? [{ checkId: this.id, severity: this.severity, message: problem, entity: m.name, pointer: `${l.pointer}/member` }] : [];
+        }),
+      );
+    },
+  },
+  {
+    id: "WSP092",
+    name: "link-kind-unknown",
+    description: `Every member link's kind is one chant knows. Unknown link kinds fail closed; ${DEFAULT_LINK_KIND} is the default and the only one so far.`,
+    severity: "error",
+    configurable: false,
+    check(ctx) {
+      return ctx.declaration.members.flatMap((m) =>
+        m.links
+          .filter((l) => l.kind !== null && !(LINK_KINDS as readonly string[]).includes(l.kind))
+          .map((l) => ({
+            checkId: this.id,
+            severity: this.severity,
+            message: `member ${m.name}'s link to ${l.member} has kind ${l.kind}, which is not a link kind chant knows; known link kinds: ${LINK_KINDS.join(", ")}`,
+            entity: m.name,
+            pointer: `${l.pointer}/kind`,
+          })),
+      );
+    },
+  },
+  {
+    id: "WSP093",
+    name: "link-output-missing",
+    description: "Every member link names an output its producer exposes, matched exactly. A producer that renames an output fails this for every consumer that links to the old name.",
+    severity: "error",
+    configurable: true,
+    check(ctx) {
+      return declaredRows(ctx)
+        .filter((r) => r.status === "missing")
+        .map((r) => linkFinding(this, r, "output", `${describeLink(r)} does not resolve: ${r.reason}`));
+    },
+  },
+  {
+    id: "WSP094",
+    name: "link-unresolved",
+    description: "A member link whose producer's outputs can't be read in source is kept, unresolved, and reported.",
+    severity: "info",
+    configurable: true,
+    check(ctx) {
+      return declaredRows(ctx)
+        .filter((r) => r.status === "unresolved")
+        .map((r) => linkFinding(this, r, "output", `${describeLink(r)} is kept unresolved: ${r.reason}`));
+    },
+  },
+  {
+    id: "WSP095",
+    name: "join-ambiguous",
+    description: "No inferred join is ambiguous: a parameter that matches outputs of two producers (or two outputs of one) needs a declared link saying which.",
+    severity: "warning",
+    configurable: true,
+    check(ctx) {
+      const byName = new Map(ctx.declaration.members.map((m) => [m.name, m]));
+      return linkTable(ctx)
+        .filter((r): r is AmbiguousRow => r.status === "ambiguous")
+        .map((r) => {
+          const choices = r.candidates.map((c) => `${c.producer} output ${c.output} (${c.label})`).join(", ");
+          const first = r.candidates[0];
+          return {
+            checkId: this.id,
+            severity: this.severity,
+            message: `${r.reason}: ${choices}. Declare the one it reads, such as { "member": "${first.producer}", "output": "${first.output}" } in ${r.consumer}'s links`,
+            entity: r.consumer,
+            pointer: byName.get(r.consumer)!.pointer,
+          };
+        });
+    },
+  },
+  {
+    id: "WSP096",
+    name: "link-duplicate",
+    description: "A link is stated once: no consumer lists the same member and output twice.",
+    severity: "error",
+    configurable: true,
+    check(ctx) {
+      const out: WorkspaceDiagnostic[] = [];
+      for (const m of ctx.declaration.members) {
+        const seen = new Map<string, string>();
+        for (const l of m.links) {
+          const key = `${l.member}\0${l.output}\0${l.kind ?? DEFAULT_LINK_KIND}`;
+          const first = seen.get(key);
+          if (first) {
+            out.push({
+              checkId: this.id,
+              severity: this.severity,
+              message: `member ${m.name} links to ${l.member} output ${l.output} twice; the first is at ${first}`,
+              entity: m.name,
+              pointer: l.pointer,
+            });
+          } else {
+            seen.set(key, l.pointer);
+          }
+        }
+      }
+      return out;
+    },
+  },
+  {
+    id: "WSP097",
+    name: "outputs-not-listable",
+    description: "An entry lists outputs only when its kind takes them from the entry: other, or a kind from a package. A chant member's outputs are read from its source, and a nested workspace exposes none.",
+    severity: "error",
+    configurable: true,
+    check(ctx) {
+      return ctx.declaration.members
+        .filter((m): m is Member & { outputs: string[] } => m.outputs !== null)
+        .flatMap((m) => {
+          const kind = ctx.kinds.get(m.kind);
+          if (!kind || kind.outputs.from === "declared") return [];
+          const why = kind.outputs.from === "chant-source" ? "reads a member's outputs from its source" : "exposes no outputs";
+          return [
+            {
+              checkId: this.id,
+              severity: this.severity,
+              message: `member ${m.name} lists outputs, and kind ${m.kind} ${why}; remove the list`,
+              entity: m.name,
+              pointer: `${m.pointer}/outputs`,
+            },
+          ];
+        });
+    },
+  },
+];

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

@@ -0,0 +1,133 @@
+/**
+ * WSP081, WSP082 and WSP083 (#2542; ws-040, ws-042): one declarer per
+ * generated file, generated files inside their member or on a forge path,
+ * and linked members that share an environment name.
+ */
+
+import { afterEach, describe, expect, test } from "vitest";
+import { readFileSync, rmSync, writeFileSync } from "node:fs";
+import { runDeclarationChecks } from "../checks";
+import { join, resolve } from "node:path";
+import { readDeclaration } from "../declaration";
+import { recordGeneratedFiles } from "../member-pipeline";
+import { workingTree } from "../tree";
+import { twoMemberWorkspace } from "../__fixtures__/two-member-workspace";
+import {
+  checkGeneratedPlacement,
+  checkLinkedEnvironments,
+  checkOneDeclarer,
+  checkPipelines,
+  gatherPipelineFacts,
+  isForgePath,
+  type MemberPipelineFacts,
+} from "./pipelines";
+
+const facts = (name: string, dir: string, generated: string[] = [], environments: string[] = []): MemberPipelineFacts => ({
+  name,
+  dir,
+  generated,
+  environments,
+});
+
+describe("isForgePath: the narrow exemption", () => {
+  test.each([".github/workflows/a.yml", ".forgejo/workflows/a.yaml", ".gitea/workflows/a.yml", ".gitlab-ci.yml", ".gitlab/ci/api.gitlab-ci.yml"])("%s is a forge path", (p) => {
+    expect(isForgePath(p)).toBe(true);
+  });
+  test.each([".github/CODEOWNERS", ".github/workflows/nested/a.yml", "ci/a.yml", "docs/.gitlab-ci.yml", ".github/actions/x/action.yml"])("%s is not", (p) => {
+    expect(isForgePath(p)).toBe(false);
+  });
+});
+
+describe("WSP081: one declarer per generated file", () => {
+  test("two members declaring one file is an error naming both", () => {
+    const findings = checkOneDeclarer([
+      facts("api", "services/api", [".github/workflows/deploy.yml"]),
+      facts("web", "apps/web", [".github/workflows/deploy.yml", ".github/workflows/chant-web-prod.yml"]),
+    ]);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({ id: "WSP081", severity: "error", members: ["api", "web"], path: ".github/workflows/deploy.yml" });
+  });
+
+  test("each member with its own file is fine", () => {
+    expect(checkOneDeclarer([facts("api", "services/api", ["a.yml"]), facts("web", "apps/web", ["b.yml"])])).toEqual([]);
+  });
+});
+
+describe("WSP082: generated files sit in the member or on a forge path", () => {
+  test("a file in another member's directory is an error", () => {
+    const findings = checkGeneratedPlacement([facts("api", "services/api", ["services/api/gen.ts", ".github/workflows/x.yml", "apps/web/gen.ts"])]);
+    expect(findings).toEqual([expect.objectContaining({ id: "WSP082", members: ["api"], path: "apps/web/gen.ts" })]);
+  });
+
+  test("the root member may declare anything", () => {
+    expect(checkGeneratedPlacement([facts("platform", ".", ["anything/at/all.yml"])])).toEqual([]);
+  });
+});
+
+describe("WSP083: linked members share an environment name", () => {
+  const members = [facts("api", "services/api", [], ["staging", "prod"]), facts("web", "apps/web", [], ["stage", "production"]), facts("jobs", "jobs", [], ["prod"])];
+
+  test("a link between members with no common name is a warning", () => {
+    const findings = checkLinkedEnvironments(members, [{ consumer: "web", producer: "api" }]);
+    expect(findings).toEqual([
+      expect.objectContaining({ id: "WSP083", severity: "warning", members: ["api", "web"], message: expect.stringMatching(/api \(prod, staging\) and web \(production, stage\)/) }),
+    ]);
+  });
+
+  test("one shared name is enough, and a member with no environments is skipped", () => {
+    expect(checkLinkedEnvironments(members, [{ consumer: "jobs", producer: "api" }])).toEqual([]);
+    expect(checkLinkedEnvironments([...members, facts("docs", "docs")], [{ consumer: "docs", producer: "api" }])).toEqual([]);
+  });
+
+  test("members that aren't linked are never compared", () => {
+    expect(checkLinkedEnvironments(members, [])).toEqual([]);
+  });
+});
+
+describe("gathering from a checkout", () => {
+  let repo: string | undefined;
+  afterEach(() => {
+    if (repo) rmSync(repo, { recursive: true, force: true });
+    repo = undefined;
+  });
+
+  test("each member's generated-file record is read, with its environments", () => {
+    repo = twoMemberWorkspace();
+    recordGeneratedFiles(join(repo, "services/api"), [{ path: ".github/workflows/chant-api-staging.yml", command: "c", env: "staging" }]);
+    recordGeneratedFiles(join(repo, "apps/web"), [
+      { path: ".github/workflows/chant-api-staging.yml", command: "c", env: "staging" },
+      { path: ".github/workflows/chant-web-prod.yml", command: "c", env: "prod" },
+    ]);
+    const gathered = gatherPipelineFacts(repo, readDeclaration(workingTree(repo)));
+    expect(gathered).toEqual([
+      { name: "api", dir: "services/api", generated: [".github/workflows/chant-api-staging.yml"], environments: ["staging"] },
+      { name: "web", dir: "apps/web", generated: [".github/workflows/chant-api-staging.yml", ".github/workflows/chant-web-prod.yml"], environments: ["staging", "prod"] },
+    ]);
+    expect(checkPipelines(gathered).map((f) => `${f.id}:${f.path}`)).toEqual(["WSP081:.github/workflows/chant-api-staging.yml"]);
+  });
+
+  test("WSP083 reads the declared member links: two linked members with no shared environment name (#2539)", async () => {
+    repo = twoMemberWorkspace();
+    const file = join(repo, "chant.workspace.json");
+    const decl = JSON.parse(readFileSync(file, "utf-8")) as { members: Record<string, unknown>[] };
+    decl.members.find((m) => m.name === "web")!.links = [{ member: "api", output: "ApiUrl" }];
+    writeFileSync(file, JSON.stringify(decl, null, 2));
+    writeFileSync(join(repo, "services/api/src/infra.ts"), `import { output } from "@intentius/chant-lexicon-aws";\nexport const url = output("u", "ApiUrl");\n`);
+    recordGeneratedFiles(join(repo, "services/api"), [{ path: "services/api/ci/api-staging.yml", command: "c", env: "staging" }]);
+    recordGeneratedFiles(join(repo, "apps/web"), [{ path: "apps/web/ci/web-production.yml", command: "c", env: "production" }]);
+    const report = await runDeclarationChecks(repo);
+    expect(report.diagnostics.map((d) => `${d.ruleId}:${d.severity}`)).toEqual(["WSP083:warning"]);
+    expect(report.diagnostics[0].message).toMatch(/api \(staging\) and web \(production\)/);
+
+    // Without the link, the two are never compared.
+    delete decl.members.find((m) => m.name === "web")!.links;
+    writeFileSync(file, JSON.stringify(decl, null, 2));
+    expect((await runDeclarationChecks(repo)).diagnostics).toEqual([]);
+  });
+
+  test("the chant repository's own declaration has no findings (#2557)", () => {
+    const root = resolve(__dirname, "../../../../..");
+    const declaration = readDeclaration(workingTree(root));
+    expect(checkPipelines(gatherPipelineFacts(root, declaration))).toEqual([]);
+  });
+});