@intentius/chant 0.124.45 → 0.124.48

package/src/workspace/lineage-check.ts

@@ -24,13 +24,14 @@
  * (`changes-cli.ts`, #2773), which prints a document of its own.
  */
 
-import { realpathSync } from "node:fs";
+import { readFileSync, realpathSync } from "node:fs";
 import { join, relative, resolve, sep } from "node:path";
 import { formatError, formatSuccess } from "../cli/format";
 import type { CommandContext } from "../cli/registry";
 import type { LintDiagnostic, LintRule } from "../lint/rule";
 import { findWorkspaceRoot } from "../project-root";
 import type { DeclarationCheckReport } from "./checks";
+import type { ForgeRepoList } from "./checks/org";
 import type { RecordFacts } from "./checks/records";
 import { LOCK_FILE, LockError, parseLock, readLock } from "./lineage-lock";
 import type { ReasonCode } from "./reason-codes";
@@ -91,7 +92,7 @@ export function findingKey(f: CheckFinding): string {
 }
 
 const USAGE =
-  "chant workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated] [--kind <kind file>] [--live --env <env>]\n       chant workspace check --changes <base>..<head> [--work <id>] [--severity off|warn|fail] [--kind <kind file>...] [--json]";
+  "chant workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated] [--kind <kind file>] [--live --env <env>] [--forge-repos <file>]\n       chant workspace check --changes <base>..<head> [--work <id>] [--severity off|warn|fail] [--kind <kind file>...] [--json]";
 const FORMATS = ["stylish", "json", "sarif"] as const;
 
 /** A lock finding as a lint diagnostic, for `--format json` and `--format sarif`. */
@@ -141,7 +142,7 @@ export type CheckDocument =
       chant: string;
       at: string | null;
       /** The declaration's workspace, or null when there is none; `name` is null when it can't be read. */
-      workspace: { name: string | null; root: string } | null;
+      workspace: { name: string | null; root: string; repo: string | null } | null;
       declaration?: DeclarationCheckReport;
     })
   | { $schema: string; contract: number; chant: string; error: { code: CheckErrorCode; message: string; location: null } };
@@ -152,7 +153,11 @@ export type CheckDocument =
  * to `cwd`. `runGenerators` is `--generated`; with `at` it does nothing,
  * since the member facts describe the working tree, not the revision.
  */
-export async function runChecks(cwd: string, at?: string, options: { runGenerators?: boolean; kind?: string; live?: { env: string; onStderr?: (text: string) => void } } = {}): Promise<CheckDocument> {
+export async function runChecks(
+  cwd: string,
+  at?: string,
+  options: { runGenerators?: boolean; kind?: string; live?: { env: string; onStderr?: (text: string) => void }; forgeRepos?: ForgeRepoList } = {},
+): Promise<CheckDocument> {
   // Loaded here, not at the top: `workspace upgrade` imports this module for checkLineage alone.
   const [{ findDeclarationDir, readDeclaration, readerVersion }, { gitTop, gitTree, resolveCommit, workingTree }] = await Promise.all([
     import("./declaration"),
@@ -190,7 +195,7 @@ export async function runChecks(cwd: string, at?: string, options: { runGenerato
   }
 
   let declaration: DeclarationCheckReport | undefined;
-  let workspace: { name: string | null; root: string } | null = null;
+  let workspace: { name: string | null; root: string; repo: string | null } | null = null;
   if (found) {
     const { runDeclarationChecks } = await import("./checks");
     const { dir, tree } = found;
@@ -200,6 +205,7 @@ export async function runChecks(cwd: string, at?: string, options: { runGenerato
       ...(commit !== null ? { tree } : {}),
       ...(records ? { records } : {}),
       ...(options.live ? { live: options.live } : {}),
+      ...(options.forgeRepos ? { forgeRepos: options.forgeRepos } : {}),
     });
     let name: string | null = null;
     try {
@@ -207,7 +213,8 @@ export async function runChecks(cwd: string, at?: string, options: { runGenerato
     } catch {
       // The WSP001 finding already says why.
     }
-    workspace = { name, root: found.root };
+    const { repoIdentity } = await import("./repo-ref");
+    workspace = { name, root: found.root, repo: repoIdentity(dir) };
   }
   const ok = report.ok && (declaration?.ok ?? true);
   return { ...head, at: commit, workspace, ...report, ok, ...(declaration ? { declaration } : {}) };
@@ -267,7 +274,23 @@ export async function runWorkspaceCheck(ctx: CommandContext): Promise<number> {
     const handed = await handToRootChant(root, ctx.args.at);
     if (handed !== undefined) return handed;
   }
-  const doc = await runChecks(root, ctx.args.at, { runGenerators: ctx.args.generated === true, ...(ctx.args.kind !== undefined ? { kind: ctx.args.kind } : {}), ...(ctx.args.live && ctx.args.env ? { live: { env: ctx.args.env, onStderr: (text: string) => process.stderr.write(text) } } : {}) });
+  // The forge's repository list (#3168) is input a warden writes; chant never asks the forge itself.
+  let forgeRepos: ForgeRepoList | undefined;
+  if (ctx.args.forgeRepos !== undefined) {
+    const { parseForgeRepos } = await import("./checks/org");
+    try {
+      forgeRepos = parseForgeRepos(readFileSync(resolve(ctx.args.forgeRepos), "utf-8"), ctx.args.forgeRepos);
+    } catch (err) {
+      console.error(formatError({ message: `--forge-repos: ${(err as Error).message}`, hint: USAGE }));
+      return 1;
+    }
+  }
+  const doc = await runChecks(root, ctx.args.at, {
+    runGenerators: ctx.args.generated === true,
+    ...(ctx.args.kind !== undefined ? { kind: ctx.args.kind } : {}),
+    ...(ctx.args.live && ctx.args.env ? { live: { env: ctx.args.env, onStderr: (text: string) => process.stderr.write(text) } } : {}),
+    ...(forgeRepos ? { forgeRepos } : {}),
+  });
   if ("error" in doc) {
     if (ctx.args.json || format === "json") console.log(JSON.stringify(doc, null, 2));
     else console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));

package/src/workspace/links.ts

@@ -195,10 +195,11 @@ function nearNames(name: string, outputs: JoinHandle[]): string[] {
  */
 export function resolveLinks(
   declaration: Declaration,
-  handles: ReadonlyMap<string, MemberHandles>,
+  sourceHandles: ReadonlyMap<string, MemberHandles>,
   telemetry?: TelemetryTargets,
   readLinks?: ReadonlyMap<string, KindLinkRead>,
 ): LinkTableRow[] {
+  const handles = withReaderOutputs(sourceHandles, readLinks);
   const rows: LinkTableRow[] = [];
   const declaredTargets = new Map<string, Set<string>>();
 
@@ -311,6 +312,28 @@ export function resolveLinks(
   return [...rows, ...inferred];
 }
 
+/**
+ * `handles` with the outputs each member's kind reader found in its files
+ * (#3935) added to the member's own. The member stays complete unless a gap
+ * the reader flagged `outputs` left a name out. A member with no handles
+ * (its directory is missing, or its kind unknown) gets none.
+ */
+export function withReaderOutputs(handles: ReadonlyMap<string, MemberHandles>, reads: ReadonlyMap<string, KindLinkRead> | undefined): ReadonlyMap<string, MemberHandles> {
+  if (!reads) return handles;
+  let out: Map<string, MemberHandles> | undefined;
+  for (const [member, read] of reads) {
+    const base = handles.get(member);
+    const gaps = read.gaps.filter((g) => g.outputs);
+    if (!base || (!read.outputs?.length && gaps.length === 0)) continue;
+    const have = new Set(base.outputs.map((o) => o.name));
+    const added = (read.outputs ?? []).filter((o) => !have.has(o.name) && have.add(o.name)).map((o) => ({ name: o.name }));
+    const complete = base.complete && gaps.length === 0;
+    const why = base.why ?? (gaps.length === 0 ? null : gaps.length === 1 ? gaps[0].message : `${gaps[0].message}, and ${gaps.length - 1} more`);
+    (out ??= new Map(handles)).set(member, { ...base, outputs: [...base.outputs, ...added], complete, why: complete ? base.why : why, exposesNone: false });
+  }
+  return out ?? handles;
+}
+
 /** Match a declared or reader's output row against its producer's handles, setting its status and reason. */
 function resolveOutput(row: LinkRow, handles: ReadonlyMap<string, MemberHandles>): void {
   const producer = handles.get(row.producer);

package/src/workspace/ls-contract.test.ts

@@ -129,7 +129,7 @@ describe("chant workspace ls on built workspaces", () => {
       ["tools", false, "kind-probe-failed"],
       ["vendor", true, null],
     ]);
-    expect(doc.members[2].reason?.message).toMatch(/known kinds: chant, design, other, workspace/);
+    expect(doc.members[2].reason?.message).toMatch(/known kinds: chant, design, other, repo, workspace/);
     expect(doc.members[0].roles).toEqual([{ name: "frontend", path: "src" }]);
     expect(doc.groups[0].reason?.code).toBe("no-matches");
     expect(doc.summary).toEqual({ members: 5, unreadable: 3, groups: 1, matches: 0 });

package/src/workspace/ls.schema.json

@@ -51,6 +51,7 @@
           "required": ["name", "root", "file", "schema", "minReader", "pins"],
           "properties": {
             "name": { "type": "string", "description": "The declared name. With the revision, it identifies the workspace." },
+            "repo": { "type": ["string", "null"], "description": "Added in contract 1 by #3168. The repository the document came from: the URL of the remote origin of the git repository that holds the workspace, with any user name or password removed, or null when there is no origin or the workspace is outside git. With name, root and the revision, it says which repository's workspace a document describes, so a reader that gathers several repositories' documents, such as an org workspace's repo members, tells them apart." },
             "root": {
               "type": "string",
               "description": "The workspace root relative to the git root, with / separators, \".\" for the git root itself. An absolute path outside a git repository."
@@ -158,6 +159,12 @@
           "type": "array",
           "items": { "$ref": "#/$defs/generatedFile" }
         },
+        "repo": {
+          "description": "Added in contract 1 by #3168. For a member of kind repo, the other repository's workspace it names: url, the pinned rev and the workspace root inside that repository. Absent for every other kind. A repo member's dir is @repo/<name>, a marker that names no directory of this repository.",
+          "type": "object",
+          "required": ["url", "rev", "workspace"],
+          "properties": { "url": { "type": "string" }, "rev": { "type": "string" }, "workspace": { "type": "string" } }
+        },
         "agents": {
           "description": "Added in contract 1 by #3615. The names of the agent sessions the declaration binds to the member (agents[].member or agents[].members), in declaration order, read where workspace.agentsFrom says. Empty when none is. A session bound to several members is listed on each.",
           "type": "array",

package/src/workspace/ls.ts

@@ -39,7 +39,8 @@ import {
 } from "./declaration";
 import type { ReasonCode } from "./reason-codes";
 import { memberGenerated, type LsGenerated } from "./ls-generated";
-import { loadKindRegistry, probeKind, type KindRegistry } from "./kinds";
+import { repoIdentity } from "./repo-ref";
+import { loadKindRegistry, probeKind, REPO_KIND, type KindRegistry } from "./kinds";
 import type { WorkspaceTree } from "./tree";
 import { handToRootChant, locateWorkspace } from "./which-chant";
 import { declaredSessions } from "./write-scope";
@@ -117,6 +118,8 @@ export interface LsMember {
   generated: LsGenerated[];
   /** The agent sessions bound to the member, in declaration order (#3615); empty when none is. */
   agents: string[];
+  /** For a member of kind repo, the other repository's workspace it names (#3168). Absent for every other kind. */
+  repo?: { url: string; rev: string; workspace: string };
 }
 
 /**
@@ -168,6 +171,8 @@ export type LsDocument =
       at: string | null;
       workspace: {
         name: string;
+        /** The repository the document came from (#3168): its origin URL, redacted, or null. */
+        repo: string | null;
         /** The workspace root relative to the git root, `"."` for the git root itself. Absolute outside git. */
         root: string;
         file: string;
@@ -211,6 +216,8 @@ export interface LsQuery {
 
 /** A member's reason code, or null when its kind can read it. */
 export function memberReason(member: Member, tree: WorkspaceTree, kinds: KindRegistry): LsMember["reason"] {
+  // A repo member has no directory here (#3168); it is read from its own repository.
+  if (member.kind === REPO_KIND) return null;
   if (tree.stat(member.dir === "." ? "" : member.dir) !== "dir") {
     return { code: "dir-missing", message: `${member.dir} is not a directory${tree.label}` };
   }
@@ -283,6 +290,7 @@ function readListing(query: LsQuery): { doc: LsDocument; declaration?: Declarati
         records: unloaded(m.records),
         generated: memberGenerated(m, tree, repoPrefix),
         agents: sessions.agents.filter((a) => a.members.includes(m.name)).map((a) => a.name),
+        ...(m.repo ? { repo: { ...m.repo } } : {}),
         // The member's x- keys, as declared (#3595).
         ...extensionsAt(declaration, m.pointer),
       };
@@ -311,6 +319,7 @@ function readListing(query: LsQuery): { doc: LsDocument; declaration?: Declarati
       at,
       workspace: {
         name: declaration.name,
+        repo: repoIdentity(rootOnDisk),
         root: located.root,
         file: declaration.file,
         schema: declaration.schema,

package/src/workspace/member-commands.ts

@@ -12,7 +12,10 @@
  * - For `graph` only, members of a pinned package's kind whose kinds file
  *   says how to read them (#2874, a `graph` block): each runs `chant graph`
  *   in a reader project chant writes for it (`kind-readers.ts`). Other
- *   package kinds are `kind-not-run`, as before.
+ *   package kinds are `kind-not-run`, as before. A kind no built-in or
+ *   pinned package supplies, such as `terraform` when the pinned lexicon is
+ *   missing or at another version, is `unknown-kind` and fails the read,
+ *   with the pin's problem in the message (#4380).
  * - For `build` and `lint` only, every project an example group matches
  *   (ws-051): groups are built and linted, and have no ledger, audit or place
  *   in the graph. On a large repository this is most of the run, so
@@ -155,6 +158,12 @@ export interface PlanOptions {
   reader?: Toolchain;
   /** The files to plan from, such as a revision's (`--at`); the working tree under `root` by default. */
   tree?: WorkspaceTree;
+  /**
+   * Why a pinned package's kinds couldn't be loaded (`loadKindRegistry`'s
+   * problems), such as a pin at one version with another installed. A graph
+   * read names them on a member whose kind is unknown (#4380).
+   */
+  kindProblems?: readonly string[];
 }
 
 /** Work out which projects run and under which chant. Throws a {@link WorkspaceReadError} for an unreadable declaration or an unknown `--member` name. */
@@ -218,10 +227,22 @@ export function planMembers(verb: WorkspaceVerb, root: string, options: PlanOpti
       });
       continue;
     }
+    // A kind no built-in or pinned package supplies is unknown, not a kind
+    // the read leaves out (#4380): a terraform member whose pinned lexicon is
+    // missing or at another version said kind-not-run before, as if the graph
+    // never read its kind. Say why, the pin's problem included.
+    if (verb === "graph" && !kinds.get(entry.kind)) {
+      const reason = memberReason(entry, tree, kinds) ?? { code: "unknown-kind", message: `no built-in kind or pinned package supplies kind ${entry.kind}` };
+      const problems = reason.code === "unknown-kind" ? (options.kindProblems ?? []) : [];
+      unreadable.push({ name: entry.name, dir: entry.dir, kind: entry.kind, reason: problems.length ? { ...reason, message: `${reason.message}; ${problems.join("; ")}` } : reason });
+      continue;
+    }
     if (entry.kind !== "chant") {
       const why =
         entry.kind === "workspace"
           ? "a nested workspace runs its own chant workspace commands"
+          : entry.kind === "repo"
+            ? "a repo member is another repository's workspace, which runs its own chant workspace commands; chant workspace graph reads it at its pinned revision"
           : entry.kind === "design"
             ? "a design member is data: chant reads its files for record pins and builds nothing"
             : `chant workspace ${verb} runs members of kind chant, and this one is kind ${entry.kind}`;
@@ -308,6 +329,8 @@ export function memberArgv(verb: WorkspaceVerb, unit: RunUnit, args: ParsedArgs)
     // The detail tier too, so `workspace graph --detail 1` composes collapsed
     // composites with their rolled-up status (#4228).
     if (args.detail !== undefined) argv.push("--detail", String(args.detail));
+    // Each member's chant maps its own capability view (#4378).
+    if (args.capabilityView) argv.push("--capability-view");
   }
   return argv;
 }
@@ -535,13 +558,17 @@ export async function runWorkspaceMembers(ctx: CommandContext, verb: WorkspaceVe
   }
 
   const results = await executePlan(plan, args);
-  const anyFailed = results.some((r) => r.exitCode !== 0) || plan.unreadable.length > 0;
+  // #2549: the disagreement lint, over every member's graph, when asked for.
+  const cross = verb === "lint" && args.crossRoot ? await runCrossRoot(found.dir, args) : undefined;
+  const anyFailed = results.some((r) => r.exitCode !== 0) || plan.unreadable.length > 0 || cross?.failed === true;
   const workspace = { name: plan.workspace.name, root: plan.workspace.root };
 
   if (verb === "lint" && args.format === "sarif") {
     for (const r of results) if (r.stderr.trim()) process.stderr.write(r.stderr.endsWith("\n") ? r.stderr : `${r.stderr}\n`);
     const unreadable: MemberOutput[] = plan.unreadable.map((s) => ({ id: s.name, member: s.name, dir: s.dir ?? ".", exitCode: 1, stdout: "", stderr: `${s.reason.code}: ${s.reason.message}` }));
-    emitDocument(mergeSarif([...results, ...unreadable], plan.workspace.root), args.output);
+    const sarif = mergeSarif([...results, ...unreadable], plan.workspace.root) as { runs?: unknown[] };
+    if (cross) (sarif.runs ??= []).push(crossRootSarifRun(cross));
+    emitDocument(sarif, args.output);
     console.error(summaryLine(plan, results));
     return anyFailed ? 1 : 0;
   }
@@ -577,6 +604,7 @@ export async function runWorkspaceMembers(ctx: CommandContext, verb: WorkspaceVe
           ...plan.unreadable.map((s) => ({ member: s.name, dir: s.dir, exitCode: 1, diagnostics: null, reason: s.reason })),
         ],
         skipped: plan.skipped,
+        ...(cross ? { crossRoot: crossRootJson(cross) } : {}),
       };
     }
     emitDocument(doc, args.output);
@@ -587,5 +615,56 @@ export async function runWorkspaceMembers(ctx: CommandContext, verb: WorkspaceVe
   // Text: each member's own output under a heading. A build without -o prints
   // no templates, since several members' templates can't share one stdout.
   printSections(plan, results, verb !== "build" || args.output !== undefined);
+  if (cross) printCrossRoot(cross);
   return anyFailed ? 1 : 0;
 }
+
+// ── The disagreement lint (#2549) ────────────────────────────────────────────
+
+interface CrossRootRun {
+  result?: import("./cross-root-lint").CrossRootLintResult;
+  /** Why the members' graphs could not be read. */
+  error?: string;
+  /** An error finding, or a graph that could not be read. */
+  failed: boolean;
+}
+
+async function runCrossRoot(root: string, args: ParsedArgs): Promise<CrossRootRun> {
+  const { workspaceGraph } = await import("./graph-cli");
+  const { crossRootLint } = await import("./cross-root-lint");
+  const { doc, failed } = await workspaceGraph({ cwd: root, ...(args.members?.length ? { members: args.members } : {}), onStderr: (t) => process.stderr.write(t) });
+  if ("error" in doc) return { error: `${doc.error.code}: ${doc.error.message}`, failed: true };
+  const result = await crossRootLint(doc, args.env ? { env: args.env } : {});
+  return { result, failed: failed || result.findings.some((f) => f.severity === "error") };
+}
+
+function crossRootJson(cross: CrossRootRun): unknown {
+  return cross.result ? { findings: cross.result.findings, checks: cross.result.checks, unloaded: cross.result.unloaded } : { error: cross.error };
+}
+
+function crossRootSarifRun(cross: CrossRootRun): unknown {
+  const findings = cross.result?.findings ?? [];
+  return {
+    tool: { driver: { name: "chant", rules: [...new Set(findings.map((f) => f.checkId))].sort().map((id) => ({ id })) } },
+    automationDetails: { id: "cross-root/" },
+    properties: { crossRoot: true, checks: cross.result?.checks ?? [], unloaded: cross.result?.unloaded ?? [] },
+    results: findings.map((f) => ({
+      ruleId: f.checkId,
+      level: f.severity === "error" ? "error" : f.severity === "warning" ? "warning" : "note",
+      message: { text: f.message },
+      ...(f.root ? { properties: { member: f.root } } : {}),
+    })),
+    ...(cross.error ? { invocations: [{ executionSuccessful: false, toolExecutionNotifications: [{ message: { text: cross.error } }] }] } : {}),
+  };
+}
+
+function printCrossRoot(cross: CrossRootRun): void {
+  if (!cross.result) {
+    console.log(`── cross-root  (the members' graphs could not be read: ${cross.error})`);
+    return;
+  }
+  const { findings, checks, unloaded } = cross.result;
+  console.log(`── cross-root  (${checks.join(", ")}; ${findings.length} finding${findings.length === 1 ? "" : "s"})`);
+  for (const f of findings) console.log(`  ${f.severity.padEnd(7)} ${f.checkId}${f.root ? ` [${f.root}]` : ""} ${f.message}`);
+  for (const u of unloaded) console.log(`  (lexicon ${u.lexicon}: its cross-root checks could not be loaded: ${u.reason})`);
+}

package/src/workspace/member-file-schema.test.ts

@@ -0,0 +1,124 @@
+/**
+ * A member kind names a JSON Schema its member's file must pass (#3672): the
+ * kinds file's memberFile block, the schema read as data from the package,
+ * and WSP012 from `chant workspace check`.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { runDeclarationChecks } from "./checks";
+import { checkMemberFile, parseKindData, readPackageKinds } 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-3672-")));
+  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 controlSchema = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  type: "object",
+  required: ["estates"],
+  properties: { estates: { type: "array", items: { type: "string" } } },
+  additionalProperties: false,
+};
+
+const controlKind = (memberFile: unknown = { path: "terragucci.yml", schema: "schemas/control.schema.json" }) => ({
+  name: "control",
+  description: "a terragucci control repo, with a terragucci.yml",
+  precedence: 300,
+  probe: { anyFile: ["terragucci.yml"] },
+  memberFile,
+});
+
+/** A kinds-only package at kinds/control, and a workspace that pins it. */
+function workspace(files: Record<string, string>, opts: { schema?: string | null; kind?: unknown } = {}): string {
+  const schemaText = opts.schema === undefined ? JSON.stringify(controlSchema) : opts.schema;
+  return repo({
+    "chant.workspace.json": JSON.stringify({ name: "acme", schema: 1, pins: [{ path: "kinds/control" }], members: [{ name: "ctl", dir: "ctl", kind: "control" }] }),
+    "kinds/control/package.json": JSON.stringify({ name: "control-kinds", exports: { "./workspace-kinds": "./workspace-kinds.json" } }),
+    "kinds/control/workspace-kinds.json": JSON.stringify({ schema: 1, kinds: [opts.kind ?? controlKind()] }),
+    ...(schemaText === null ? {} : { "kinds/control/schemas/control.schema.json": schemaText }),
+    ...files,
+  });
+}
+
+const wsp012 = async (root: string) =>
+  (await runDeclarationChecks(root)).diagnostics.filter((d) => d.ruleId === "WSP012" || d.ruleId === "WSP002").map((d) => `${d.ruleId}: ${d.message}`);
+
+describe("the kinds file's memberFile block", () => {
+  test("is kind data: a path in the member and a .json schema in the package", () => {
+    const ok = parseKindData(JSON.stringify({ schema: 1, kinds: [controlKind()] }), "p");
+    expect(ok.problems).toEqual([]);
+    expect(ok.kinds[0].memberFile).toEqual({ path: "terragucci.yml", schema: "schemas/control.schema.json" });
+    for (const bad of [{ path: "../x.yml", schema: "s.json" }, { path: "x.yml", schema: "s.yaml" }, { path: "x.yml", schema: "../s.json" }, { path: "x.yml" }]) {
+      expect(parseKindData(JSON.stringify({ schema: 1, kinds: [controlKind(bad)] }), "p").problems).not.toEqual([]);
+    }
+  });
+
+  test("reading the package compiles the schema as data, and reports one that is missing or not a schema", () => {
+    const good = workspace({});
+    const read = readPackageKinds(join(good, "kinds/control"));
+    expect(read.problems).toEqual([]);
+    expect(typeof read.kinds[0].memberFile?.validate).toBe("function");
+    expect(readPackageKinds(join(workspace({}, { schema: null }), "kinds/control")).problems[0]).toMatch(/does not exist/);
+    expect(readPackageKinds(join(workspace({}, { schema: "{ nope" }), "kinds/control")).problems[0]).toMatch(/is not JSON/);
+    expect(readPackageKinds(join(workspace({}, { schema: JSON.stringify({ type: 12 }) }), "kinds/control")).problems[0]).toMatch(/does not compile/);
+  });
+});
+
+describe("checkMemberFile", () => {
+  const mf = () => readPackageKinds(join(workspace({}), "kinds/control")).kinds[0].memberFile!;
+  test("parses YAML by extension and JSON otherwise, and names each failing place", () => {
+    expect(checkMemberFile(mf(), "terragucci.yml", "estates: [a, b]\n")).toEqual([]);
+    expect(checkMemberFile(mf(), "t.json", '{"estates":["a"]}')).toEqual([]);
+    expect(checkMemberFile(mf(), "terragucci.yml", "estates: [1]\nextra: true\n").map((p) => p.message).sort()).toEqual(["/estates/0 must be string", "the file must NOT have additional properties (extra)"]);
+    expect(checkMemberFile(mf(), "t.json", "estates: []")[0].message).toMatch(/^is not JSON/);
+  });
+});
+
+describe("WSP012: a member's file passes its kind's schema", () => {
+  test("a member whose file passes has no finding", async () => {
+    expect(await wsp012(workspace({ "ctl/terragucci.yml": "estates: [prod]\n" }))).toEqual([]);
+  });
+
+  test("a file that fails the schema fails the check, once per reason", async () => {
+    const report = await runDeclarationChecks(workspace({ "ctl/terragucci.yml": "estates: prod\n" }));
+    expect(report.ok).toBe(false);
+    const found = report.diagnostics.filter((d) => d.ruleId === "WSP012");
+    expect(found.map((d) => d.message)).toEqual(["member ctl's terragucci.yml fails kind control's schema schemas/control.schema.json: /estates must be array"]);
+    expect(found[0].file).toMatch(/ctl\/terragucci\.yml$/);
+  });
+
+  test("a member without the file fails it", async () => {
+    // The probe also wants the file; the declared kind still names the schema, so WSP012 says what is missing.
+    expect(await wsp012(workspace({ "ctl/README.md": "" }))).toEqual(["WSP012: member ctl (ctl) has no terragucci.yml, which kind control requires"]);
+  });
+
+  test("a schema that doesn't load is WSP002, and its members can't pass WSP012", async () => {
+    const found = await wsp012(workspace({ "ctl/terragucci.yml": "estates: []\n" }, { schema: null }));
+    expect(found).toHaveLength(2);
+    expect(found[0]).toMatch(/^WSP002: .*kind control names member-file schema schemas\/control.schema.json, which does not exist/);
+    expect(found[1]).toMatch(/^WSP012: .*did not load/);
+  });
+
+  test("the declaration can turn it down", async () => {
+    const root = workspace({ "ctl/terragucci.yml": "nope: 1\n" });
+    const decl = JSON.parse(execFileSync("cat", [join(root, "chant.workspace.json")], { encoding: "utf-8" }));
+    writeFileSync(join(root, "chant.workspace.json"), JSON.stringify({ ...decl, checks: { WSP012: "warning" } }));
+    const report = await runDeclarationChecks(root);
+    expect(report.ok).toBe(true);
+    expect(report.diagnostics.filter((d) => d.ruleId === "WSP012").every((d) => d.severity === "warning")).toBe(true);
+  });
+});

package/src/workspace/migrate-links.test.ts

@@ -0,0 +1,99 @@
+/**
+ * The links `chant migrate` writes into a workspace declaration (#4399):
+ * which members are the producer and the consumer, that the edit touches only
+ * the consumer's `links`, that a second run adds nothing, and that every case
+ * with nothing to link says why.
+ */
+import { afterAll, describe, expect, test } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { parseDeclaration } from "./declaration";
+import { planMigrateLinks } from "./migrate-links";
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+
+function repo(declaration: string, file = "chant.workspace.json"): string {
+  const root = mkdtempSync(join(tmpdir(), "chant-migrate-links-"));
+  scratch.push(root);
+  for (const [path, text] of Object.entries({ [file]: declaration, "db/schema.sql": "", "mirror/mirrors.ts": "", "other/x.ts": "" })) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  return root;
+}
+
+const decl = (members: unknown[]) => `${JSON.stringify({ name: "shop", schema: 1, members }, null, 2)}\n`;
+const MEMBERS = [
+  { name: "db", dir: "db", kind: "chant" },
+  { name: "mirror", dir: "mirror", kind: "chant" },
+];
+const outputs = ["public.users.id", "public.users.email"];
+
+describe("planMigrateLinks", () => {
+  test("adds one link per output to the member holding the output file, and changes nothing else", () => {
+    const root = repo(decl(MEMBERS));
+    const r = planMigrateLinks({ sourcePath: join(root, "db/schema.sql"), outputPath: join(root, "mirror/mirrors.ts"), outputs });
+    if (!r || !("plan" in r)) throw new Error(JSON.stringify(r));
+    expect(r.plan).toMatchObject({ producer: "db", consumer: "mirror", added: outputs });
+    const members = parseDeclaration(r.plan.text, "chant.workspace.json").members;
+    expect(members.find((m) => m.name === "mirror")!.links.map((l) => `${l.member} ${l.output}`)).toEqual(outputs.map((o) => `db ${o}`));
+    expect(members.find((m) => m.name === "db")!.links).toEqual([]);
+    expect(r.plan.text.startsWith('{\n  "name": "shop"')).toBe(true);
+  });
+
+  test("keeps the links already there and adds only the new ones; a second plan adds nothing", () => {
+    const root = repo(decl([MEMBERS[0], { ...MEMBERS[1], links: [{ member: "db", output: "public.users.id" }, { member: "other", output: "x" }] }, { name: "other", dir: "other", kind: "chant" }]));
+    const r = planMigrateLinks({ sourcePath: join(root, "db"), outputPath: join(root, "mirror/mirrors.ts"), outputs });
+    if (!r || !("plan" in r)) throw new Error(JSON.stringify(r));
+    expect(r.plan.added).toEqual(["public.users.email"]);
+    const links = parseDeclaration(r.plan.text, "x.json").members.find((m) => m.name === "mirror")!.links;
+    expect(links.map((l) => `${l.member} ${l.output}`)).toEqual(["db public.users.id", "other x", "db public.users.email"]);
+    writeFileSync(join(root, "chant.workspace.json"), r.plan.text);
+    const again = planMigrateLinks({ sourcePath: join(root, "db"), outputPath: join(root, "mirror/mirrors.ts"), outputs });
+    expect(again).toMatchObject({ plan: { added: [] } });
+  });
+
+  test("reads a jsonc declaration and keeps its comments", () => {
+    const text = `{\n  // the shop\n  "name": "shop", "schema": 1,\n  "members": [\n    { "name": "db", "dir": "db", "kind": "chant" },\n    { "name": "mirror", "dir": "mirror", "kind": "chant" } // the mirror\n  ]\n}\n`;
+    const root = repo(text, "chant.workspace.jsonc");
+    const r = planMigrateLinks({ sourcePath: join(root, "db/schema.sql"), outputPath: join(root, "mirror/mirrors.ts"), outputs });
+    if (!r || !("plan" in r)) throw new Error(JSON.stringify(r));
+    expect(r.plan.text).toContain("// the shop");
+    expect(r.plan.text).toContain("// the mirror");
+    expect(r.plan.added).toEqual(outputs);
+  });
+
+  test("the deepest member holds a path: a nested member is not its parent's", () => {
+    const root = repo(decl([{ name: "all", dir: ".", kind: "chant" }, { name: "db", dir: "db", kind: "chant" }, { name: "mirror", dir: "mirror", kind: "chant" }]));
+    const r = planMigrateLinks({ sourcePath: join(root, "db/schema.sql"), outputPath: join(root, "mirror/mirrors.ts"), outputs });
+    expect(r).toMatchObject({ plan: { producer: "db", consumer: "mirror" } });
+  });
+
+  test("no workspace above the source is no outcome at all", () => {
+    const root = mkdtempSync(join(tmpdir(), "chant-no-workspace-"));
+    scratch.push(root);
+    writeFileSync(join(root, "schema.sql"), "");
+    expect(planMigrateLinks({ sourcePath: join(root, "schema.sql"), outputPath: join(root, "out.ts"), outputs })).toBeUndefined();
+  });
+
+  test.each([
+    ["output to stdout", (root: string) => ({ sourcePath: join(root, "db/schema.sql"), outputPath: undefined }), "pass --output inside the ClickHouse member"],
+    ["a source in no member", (root: string) => ({ sourcePath: join(root, "elsewhere/schema.sql"), outputPath: join(root, "mirror/mirrors.ts") }), "is in no member"],
+    ["an output in no member", (root: string) => ({ sourcePath: join(root, "db/schema.sql"), outputPath: join(root, "elsewhere/out.ts") }), "is in no member"],
+    ["a source and output in one member", (root: string) => ({ sourcePath: join(root, "db/schema.sql"), outputPath: join(root, "db/out.ts") }), "does not link to itself"],
+  ])("%s is skipped with a reason", (_name, paths, reason) => {
+    const root = repo(decl(MEMBERS));
+    const r = planMigrateLinks({ ...paths(root), outputs });
+    expect(r && "skipped" in r ? r.skipped : r).toContain(reason);
+  });
+
+  test("a declaration that does not read is skipped with its error, never rewritten", () => {
+    const root = repo("{ not json");
+    const r = planMigrateLinks({ sourcePath: join(root, "db/schema.sql"), outputPath: join(root, "mirror/mirrors.ts"), outputs });
+    expect(r && "skipped" in r ? r.skipped : r).toContain("does not read, so no link was written");
+  });
+});