@intentius/chant 0.124.46 → 0.124.48

package/src/terraform/reach.ts

@@ -0,0 +1,247 @@
+/**
+ * Transitive reachability over the carve graph (#2325).
+ *
+ * `inboundEdges`/`outboundEdges` in `graph.ts` answer one hop with a linear
+ * scan, which is right for the scorer's depth-1 counts and wrong as the step of
+ * a walk: calling it per node per step is O(V²E). This module builds one
+ * index per graph instead, and walks it with the same breadth-first walk
+ * `chant search` uses (`graph-walk.ts`).
+ *
+ * Four rules from the spike (docs/design/carve-dependency-blast-radius-spike.md)
+ * hold for every walk here and for the set functions in `cuts.ts` built on it:
+ *
+ *  - Folds contract first. A folded sub-resource is its parent for the walk, so
+ *    `aws_s3_bucket_versioning.assets` is never a dependent of
+ *    `aws_s3_bucket.assets`, and a node reading the child depends on the
+ *    parent.
+ *  - Outputs are terminal and counted apart. An `output.<name>` pseudo-address
+ *    has no inbound edges, so it never extends a path; it is reported in its
+ *    own list.
+ *  - Modules and unresolved `count`/`for_each` hide how much a node holds. A
+ *    `module.x` node is one node whatever it contains, and `count = 20` is one
+ *    node until `--state` resolves it. They are walked through and named, so a
+ *    caller can say `unknown` instead of a number.
+ *  - Cross-stack hops are told apart. On the CDK path an `Fn::ImportValue` edge
+ *    carries `crossStack: true`; what is reachable only through one is listed
+ *    separately.
+ *
+ * Pure, like the rest of the carve analysis. `src/cdk/graph.ts` emits the same
+ * `TfGraph`, so one implementation covers both sources.
+ */
+
+import { adjacencyOf, walkBreadthFirst, type Adjacency } from "../graph-walk";
+import { computeFolds } from "./folds";
+import type { TfEdge, TfGraph, TfNode } from "./types";
+
+/** An edge with both ends contracted to their fold parents. `edge` is the edge as the graph holds it. */
+export interface ContractedEdge extends TfEdge {
+  edge: TfEdge;
+}
+
+/** The index every walk over one graph shares. Built once per graph; see {@link carveIndex}. */
+export interface CarveIndex {
+  graph: TfGraph;
+  /** Every node by address, folded sub-resources included. */
+  nodes: Map<string, TfNode>;
+  /** The address a walk sees for `address`: its fold parent, or itself. */
+  rep(address: string): string;
+  /** A walked node's own blocks: itself first, then what folds into it, sorted. */
+  membersOf(address: string): string[];
+  /** Contracted edges by both ends. An edge internal to one fold is dropped. */
+  adj: Adjacency<ContractedEdge>;
+  /** The graph has at least one `crossStack` edge (a CDK assembly of several stacks). */
+  crossStack: boolean;
+}
+
+const indexes = new WeakMap<TfGraph, CarveIndex>();
+
+/**
+ * The fold-contracted adjacency index for a graph, built on first use and
+ * cached against the graph object. O(V+E) to build; every walk after that is
+ * O(V+E). A caller that mutates `graph.edges` after the first walk must pass a
+ * new graph object (`applyStateCounts` only touches node instance counts, which
+ * the index reads live).
+ */
+export function carveIndex(graph: TfGraph): CarveIndex {
+  const cached = indexes.get(graph);
+  if (cached) return cached;
+  const nodes = new Map(graph.nodes.map((n) => [n.address, n]));
+  const parentOf = new Map<string, string>();
+  const { childrenOf } = computeFolds(graph);
+  for (const [parent, children] of childrenOf) for (const child of children) parentOf.set(child, parent);
+  const rep = (address: string): string => parentOf.get(address) ?? address;
+  const contracted: ContractedEdge[] = [];
+  for (const e of graph.edges) {
+    const from = rep(e.from);
+    const to = rep(e.to);
+    if (from === to) continue; // a folded child reading its own parent is not an edge of the fold
+    contracted.push({ ...e, from, to, edge: e });
+  }
+  const index: CarveIndex = {
+    graph,
+    nodes,
+    rep,
+    membersOf: (address) => [address, ...[...(childrenOf.get(address) ?? [])].sort()],
+    adj: adjacencyOf(contracted),
+    crossStack: graph.edges.some((e) => e.crossStack),
+  };
+  indexes.set(graph, index);
+  return index;
+}
+
+/** `output.<name>`: a pseudo-address `buildGraph` gives an output block's edges (#1638). */
+export function isOutputAddress(address: string): boolean {
+  return address.startsWith("output.");
+}
+
+/**
+ * Whether a node stands for an amount of infrastructure the graph cannot see:
+ * a Terraform `module` block (one node, whatever it holds; state is not read
+ * inside modules), or a `count`/`for_each` block whose instance count no
+ * `.tfstate` resolved. A CDK L3 construct is also `kind: "module"`, but its
+ * members are listed and its address is a construct path, so it hides nothing.
+ */
+export function hidesContents(node: TfNode): boolean {
+  if (node.kind === "module" && node.address.startsWith("module.")) return true;
+  return node.expansion !== undefined && node.instancesFrom !== "state";
+}
+
+/**
+ * Which way a walk steps: `in` follows who reads a node (its dependents), `out`
+ * what it reads, `both` either (weak connectivity, #3909). An output is
+ * terminal every way: it is reached, never stepped from.
+ */
+export type WalkDirection = "in" | "out" | "both";
+
+/**
+ * Walk from `seeds` (already contracted) and return every node reached with its
+ * shortest depth, seeds excluded. `sameStack` refuses `crossStack` edges.
+ */
+export function walkFrom(
+  index: CarveIndex,
+  seeds: Iterable<string>,
+  direction: WalkDirection,
+  opts: { sameStack?: boolean } = {},
+): Map<string, number> {
+  const start = new Set(seeds);
+  const reached = new Map<string, number>();
+  const stepsAlong = (edges: ContractedEdge[] | undefined, far: "from" | "to"): { far: string; hops: never[] }[] =>
+    (edges ?? []).filter((e) => !(opts.sameStack && e.crossStack)).map((e) => ({ far: e[far], hops: [] }));
+  walkBreadthFirst<never>(start, {
+    steps: (id) => {
+      if (isOutputAddress(id) && !start.has(id)) return [];
+      const steps: { far: string; hops: never[] }[] = [];
+      if (direction !== "out") steps.push(...stepsAlong(index.adj.in.get(id), "from"));
+      if (direction !== "in") steps.push(...stepsAlong(index.adj.out.get(id), "to"));
+      return steps;
+    },
+    arrive: ({ id, depth }) => {
+      if (!start.has(id) && !reached.has(id)) reached.set(id, depth);
+      return false;
+    },
+  });
+  return reached;
+}
+
+/** What a walk from one node reached. Every list is sorted and holds contracted addresses. */
+export interface Reach {
+  /** The node the walk started from: the requested address, or its fold parent. */
+  address: string;
+  /** Resource and module nodes reached, the start excluded. */
+  resources: string[];
+  /** `output.<name>` pseudo-addresses reached; terminal, never in `resources`. */
+  outputs: string[];
+  /** The longest shortest path to anything reached, outputs included; 0 when nothing was. */
+  depth: number;
+  /** Of `resources`, those reached only through a `crossStack` edge. Empty off the CDK path. */
+  crossStack: string[];
+  /** Of `resources`, those that hide how much they hold (see {@link hidesContents}). */
+  hidden: string[];
+}
+
+/**
+ * Everything reachable from `address` (#2325). Direction `in` (the default)
+ * walks dependents: what a change to `address` reaches, its blast radius.
+ * Direction `out` walks dependencies: what `address` needs.
+ *
+ * Throws when `address` is not a node of the graph.
+ */
+export function reach(graph: TfGraph, address: string, opts: { direction?: WalkDirection } = {}): Reach {
+  const index = carveIndex(graph);
+  if (!index.nodes.has(address)) throw new Error(`reach: ${address} is not a resource or module in this graph`);
+  const start = index.rep(address);
+  const direction = opts.direction ?? "in";
+  const reached = walkFrom(index, [start], direction);
+  const sorted = [...reached.keys()].sort(cmp);
+  const resources = sorted.filter((a) => !isOutputAddress(a));
+  let crossStack: string[] = [];
+  if (index.crossStack) {
+    const inStack = walkFrom(index, [start], direction, { sameStack: true });
+    crossStack = resources.filter((a) => !inStack.has(a));
+  }
+  return {
+    address: start,
+    resources,
+    outputs: sorted.filter(isOutputAddress),
+    depth: Math.max(0, ...reached.values()),
+    crossStack,
+    hidden: resources.filter((a) => hidesContents(index.nodes.get(a)!)),
+  };
+}
+
+/** Code-point order, as `buildGraph` sorts: locale-independent. */
+export function cmp(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * How far a change to one node reaches, as `carve advise` reports it (#2326):
+ * its own axis beside the peelability score, never a penalty term. Every score
+ * term is a unit of work (an inbound edge is one data-source patch); a
+ * transitive dependent is not work, nobody patches it, and its count can run
+ * far past what a 0-100 score carries.
+ */
+export interface BlastRadius {
+  /**
+   * Resources and modules that depend on the node, directly or not, weighted by
+   * instance count when `--state` resolved it. `"unknown"` when one of them is
+   * a module or a `count`/`for_each` no state resolved: see `hiddenBy`.
+   */
+  resources: number | "unknown";
+  /** `output` blocks that read the node or one of its dependents. */
+  outputs: number;
+  /** Hops to the farthest dependent, outputs included; 0 when nothing depends on it. */
+  depth: number;
+  /**
+   * Of `resources`, those reachable only through a `crossStack` edge (a CDK
+   * `Fn::ImportValue`), weighted the same way. Present only when the graph has
+   * such an edge.
+   */
+  crossStack?: number | "unknown";
+  /** The dependents that make a count `"unknown"`. Present only when one does. */
+  hiddenBy?: string[];
+}
+
+/** The instances `addresses` stand for, or `"unknown"` when one of them hides its contents. */
+export function weigh(index: CarveIndex, addresses: readonly string[]): number | "unknown" {
+  let total = 0;
+  for (const address of addresses) {
+    const node = index.nodes.get(address)!;
+    if (hidesContents(node)) return "unknown";
+    total += node.instances;
+  }
+  return total;
+}
+
+/** The {@link BlastRadius} of `address`: its {@link reach} through dependents, counted. */
+export function blastRadius(graph: TfGraph, address: string): BlastRadius {
+  const index = carveIndex(graph);
+  const r = reach(graph, address);
+  return {
+    resources: weigh(index, r.resources),
+    outputs: r.outputs.length,
+    depth: r.depth,
+    ...(index.crossStack ? { crossStack: weigh(index, r.crossStack) } : {}),
+    ...(r.hidden.length ? { hiddenBy: r.hidden } : {}),
+  };
+}

package/src/terraform/score.ts

@@ -30,9 +30,11 @@
  * shared verbatim.
  */
 
-import { inboundEdges, outboundEdges } from "./graph";
-import { foldParentOf, resolveTier, type TierInfo } from "./tier-map";
-import type { TfGraph, TfNode } from "./types";
+import { adjacencyOf, type Adjacency } from "../graph-walk";
+import { computeFolds } from "./folds";
+import { blastRadius, type BlastRadius } from "./reach";
+import { resolveTier, type TierInfo } from "./tier-map";
+import type { TfEdge, TfGraph, TfNode } from "./types";
 
 export type PeelabilityBand = "clean leaf" | "carvable w/ edits" | "leave in Terraform";
 
@@ -96,6 +98,12 @@ export interface Peelability {
   notes?: string[];
   /** The source units folded into this node (#1056). */
   members?: CarveUnitMember[];
+  /**
+   * How far a change to this node reaches through its dependents (#2326). Its
+   * own axis: it never feeds `score`, so `100 + sum(breakdown.penalties)`
+   * still reproduces the score.
+   */
+  radius?: BlastRadius;
 }
 
 /**
@@ -125,6 +133,12 @@ export interface ScoreOptions {
    */
   tierOf?: (type: string) => TierInfo | null;
   signalsFor?: (node: TfNode) => ScoreSignals;
+  /**
+   * Compute each node's blast radius (#2326). Default true; a caller that only
+   * wants the score (`boundaryReport`) turns it off rather than walk the graph
+   * once per node for a field it drops.
+   */
+  radius?: boolean;
 }
 
 const clamp = (n: number): number => Math.max(0, Math.min(100, n));
@@ -144,40 +158,18 @@ export function bandFor(score: number): PeelabilityBand {
 /** Module tier: a module maps to a chant composite — reshaping, so tier 2 by default. */
 const MODULE_TIER = 2 as const;
 
-/**
- * Build the set of addresses that fold into a parent present in the estate, plus
- * the reverse lookup (parent → its folded children), so a parent can discount
- * inbound edges coming from its own folded sub-resources.
- */
-function computeFolds(graph: TfGraph): { folded: Set<string>; childrenOf: Map<string, Set<string>> } {
-  const byAddress = new Map(graph.nodes.map((n) => [n.address, n]));
-  const folded = new Set<string>();
-  const childrenOf = new Map<string, Set<string>>();
-  for (const node of graph.nodes) {
-    if (node.kind !== "resource" || !node.type) continue;
-    const parentType = foldParentOf(node.type);
-    if (!parentType) continue;
-    const parentAddress = `${parentType}.${node.name}`;
-    if (!byAddress.has(parentAddress)) continue; // sub-resource without its parent → score it on its own
-    folded.add(node.address);
-    if (!childrenOf.has(parentAddress)) childrenOf.set(parentAddress, new Set());
-    childrenOf.get(parentAddress)!.add(node.address);
-  }
-  return { folded, childrenOf };
-}
-
 function scoreNode(
   node: TfNode,
-  graph: TfGraph,
+  adj: Adjacency<TfEdge>,
   foldedChildren: Set<string>,
   opts: ScoreOptions,
 ): Peelability {
   // Inbound excludes edges from this node's own folded sub-resources, and
   // counts output blocks separately — they cost less to bridge (#1638).
-  const inboundAll = inboundEdges(graph, node.address).filter((e) => !foldedChildren.has(e.from));
+  const inboundAll = (adj.in.get(node.address) ?? []).filter((e) => !foldedChildren.has(e.from));
   const inbound = inboundAll.filter((e) => e.fromKind !== "output").length;
   const outputs = inboundAll.length - inbound;
-  const outbound = outboundEdges(graph, node.address).length;
+  const outbound = (adj.out.get(node.address) ?? []).length;
 
   const signals = opts.signalsFor?.(node) ?? {};
   const extra = { ...(signals.penalties ?? {}) };
@@ -247,11 +239,17 @@ function scoreNode(
 /**
  * Score every carvable node in the estate, ranked most-peelable first. Folded
  * sub-resources are omitted (they carve with their parent, not on their own).
+ * Each carries its blast radius (#2326) beside the score, not in it.
  */
 export function scoreEstate(graph: TfGraph, opts: ScoreOptions = {}): Peelability[] {
   const { folded, childrenOf } = computeFolds(graph);
+  // One edge index for the whole pass: a per-node edge filter is O(E) each, O(V·E) in all (#4391).
+  const adj = adjacencyOf(graph.edges);
   return graph.nodes
     .filter((n) => !folded.has(n.address))
-    .map((n) => scoreNode(n, graph, childrenOf.get(n.address) ?? new Set(), opts))
+    .map((n) => {
+      const scored = scoreNode(n, adj, childrenOf.get(n.address) ?? new Set(), opts);
+      return opts.radius === false ? scored : { ...scored, radius: blastRadius(graph, n.address) };
+    })
     .sort((a, b) => b.score - a.score || (a.address < b.address ? -1 : a.address > b.address ? 1 : 0));
 }

package/src/terraform/state.ts

@@ -81,7 +81,9 @@ export function readStateInstanceCounts(statePath: string): Map<string, number>
 export function applyStateCounts(graph: TfGraph, counts: Map<string, number>): TfGraph {
   for (const node of graph.nodes) {
     const n = counts.get(node.address);
-    if (n !== undefined) node.instances = Math.max(1, n);
+    if (n === undefined) continue;
+    node.instances = Math.max(1, n);
+    node.instancesFrom = "state";
   }
   return graph;
 }

package/src/terraform/types.ts

@@ -28,6 +28,14 @@ export interface TfNode {
   instances: number;
   /** `count`, `for_each`, a `data` source, or an unresolved interpolation is present. */
   hasDynamic: boolean;
+  /**
+   * The block's own expansion meta-argument, when it has one (#2325). Unlike
+   * `hasDynamic`, which a `data` read also sets, this says the node stands for
+   * an unknown number of instances until state resolves it.
+   */
+  expansion?: "count" | "for_each";
+  /** `"state"` once `applyStateCounts` read this node's instance count from a `.tfstate` (#2325). */
+  instancesFrom?: "state";
   /**
    * The resource's physical name, when it is a plain literal in the HCL (e.g.
    * `bucket = "myapp-assets-prod"`). Used to build the live-import selector on

package/src/wave-blocked.ts

@@ -44,7 +44,7 @@
  * later member is blocked by `wave-<k>`.
  */
 import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 
 export const WAVE_OUTCOME_VERSION = 1;
 
@@ -239,7 +239,8 @@ function outcomeFiles(dirs: readonly string[]): string[] {
  * The outcome of each member of the waves before `wave`, as their jobs wrote
  * them under `dirs`, and the earliest such wave that holds every later
  * member, if any. For a member more than one job wrote (a re-run, or a split
- * wave's deciding job and the share that applied it), the newest. A file
+ * wave's deciding job and the share that applied it), the newest, and on a
+ * tie the share's rather than the deciding job's `decided`. A file
  * that does not parse, or is of another version, is skipped.
  */
 export function earlierWaveOutcomes(
@@ -260,7 +261,8 @@ export function earlierWaveOutcomes(
     if (typeof members !== "object" || members === null) continue;
     for (const [member, o] of Object.entries(members)) {
       const had = out.get(member);
-      if (had && had.at > f.at) continue;
+      // #4322: at the same time, what a share reported wins over its deciding job's `decided`.
+      if (had && (had.at > f.at || (had.at === f.at && o.status === "decided" && had.status !== "decided"))) continue;
       out.set(member, { ...o, wave: f.wave!, at: f.at });
     }
     const n = newest.get(f.wave!);
@@ -269,3 +271,26 @@ export function earlierWaveOutcomes(
   const holding = [...newest].filter(([, n]) => n.holdsAll).map(([k]) => k).sort((a, b) => a - b);
   return { members: out, ...(holding.length ? { holdsAll: holding[0] } : {}) };
 }
+
+/**
+ * The newest outcome file named `name` under `dirs` (#4322), as
+ * {@link waveOutcomeFileName} names one job's: a split wave's share job
+ * reads its deciding job's, `outcome-wave-<k>.json`, to learn which runs that
+ * job decided and which it blocked. Undefined when there is none, or none
+ * that parses at this version.
+ */
+export function readWaveOutcomeFile(dirs: readonly string[], name: string): WaveOutcomeFile | undefined {
+  let newest: WaveOutcomeFile | undefined;
+  for (const file of outcomeFiles(dirs)) {
+    if (basename(file) !== name) continue;
+    let f: Partial<WaveOutcomeFile>;
+    try {
+      f = JSON.parse(readFileSync(file, "utf-8"));
+    } catch {
+      continue;
+    }
+    if (f?.version !== WAVE_OUTCOME_VERSION || typeof f.at !== "string" || typeof f.members !== "object" || f.members === null) continue;
+    if (!newest || newest.at <= f.at) newest = f as WaveOutcomeFile;
+  }
+  return newest;
+}

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

@@ -262,9 +262,10 @@ describe("Op waves golden transcripts (#3766)", () => {
       { wave: 1, label: "waits" },
       { wave: 1, label: "approved", gates: memoryGateLedgerPort({ resolutions: [resolution("tf-apply", "wave-1", set)] }) },
       { wave: 1, label: "another digest approved", gates: memoryGateLedgerPort({ resolutions: [resolution("tf-apply", "wave-1", digest("9"))] }) },
-      { wave: 2, decide: true, label: "decide a wide never wave" },
-      { wave: 2, share: 1, label: "share 1" },
-      { wave: 2, share: 2, label: "share 2" },
+      // #4322: wave 1's last job here waits, which would stop wave 2; the wide wave keeps its outcomes apart to show its own jobs.
+      { wave: 2, decide: true, label: "decide a wide never wave", outcomeDir: "wide-outcomes" },
+      { wave: 2, share: 1, label: "share 1", outcomeDir: "wide-outcomes" },
+      { wave: 2, share: 2, label: "share 2", outcomeDir: "wide-outcomes" },
     ]);
   });
 

package/src/workspace/behold-kinds.test.ts

@@ -153,6 +153,6 @@ describe("behold's member kinds from their packages (#2545)", () => {
     await runWorkspaceLs({ args: parseArgs(["workspace", "ls", root, "--json"]), plugins: [] } as never);
     const doc = JSON.parse(out.join("\n")) as Extract<LsDocument, { members: unknown }>;
     expect(doc.members.map((m) => m.reason?.code ?? null)).toEqual(["unknown-kind", "unknown-kind", "unknown-kind", null]);
-    expect(doc.members[0].reason?.message).toMatch(/known kinds: chant, design, other, workspace$/);
+    expect(doc.members[0].reason?.message).toMatch(/known kinds: chant, design, other, repo, workspace$/);
   });
 });

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

@@ -15,6 +15,7 @@ import { RECORD_FINDING_CODES } from "./checks/records";
 import { DIAGRAM_FINDING_CODES } from "./checks/diagrams";
 import { SECURITY_FINDING_CODES } from "./checks/security";
 import { CI_WORKFLOW_FINDING_CODES } from "./ci-workflow";
+import { CI_BRANCH_FINDING_CODES } from "./checks/ci-branch";
 import { WORKSPACE_ERROR_CODES } from "./declaration";
 import { CHECK_CODES, CHECK_CONTRACT_VERSION, CHECK_ERROR_CODES, CHECK_OUTPUT_SCHEMA_ID, runChecks, type CheckDocument } from "./lineage-check";
 
@@ -40,8 +41,8 @@ describe("check output schema", () => {
   test("lists exactly the codes the code can return", () => {
     expect(schema.$defs.lockFinding.properties.code.enum).toEqual([...CHECK_CODES]);
     expect(schema.$defs.failure.properties.error.properties.code.enum).toEqual([...CHECK_ERROR_CODES]);
-    expect(schema.$defs.diagnostic.properties.code.enum).toEqual([...WORKSPACE_ERROR_CODES, ...BOX_FINDING_CODES, ...RECORD_FINDING_CODES, ...DIAGRAM_FINDING_CODES, ...SECURITY_FINDING_CODES, ...CI_WORKFLOW_FINDING_CODES]);
-    expect(schema.$defs.suppressed.properties.code.enum).toEqual([...WORKSPACE_ERROR_CODES, ...BOX_FINDING_CODES, ...RECORD_FINDING_CODES, ...DIAGRAM_FINDING_CODES, ...SECURITY_FINDING_CODES, ...CI_WORKFLOW_FINDING_CODES]);
+    expect(schema.$defs.diagnostic.properties.code.enum).toEqual([...WORKSPACE_ERROR_CODES, ...BOX_FINDING_CODES, ...RECORD_FINDING_CODES, ...DIAGRAM_FINDING_CODES, ...SECURITY_FINDING_CODES, ...CI_WORKFLOW_FINDING_CODES, ...CI_BRANCH_FINDING_CODES]);
+    expect(schema.$defs.suppressed.properties.code.enum).toEqual([...WORKSPACE_ERROR_CODES, ...BOX_FINDING_CODES, ...RECORD_FINDING_CODES, ...DIAGRAM_FINDING_CODES, ...SECURITY_FINDING_CODES, ...CI_WORKFLOW_FINDING_CODES, ...CI_BRANCH_FINDING_CODES]);
   });
 });
 
@@ -49,13 +50,13 @@ describe("chant workspace check on the chant repo (#2557)", () => {
   test("validates in the working tree and at HEAD", async () => {
     const now = result(await runChecks(REPO));
     expectValid(now);
-    expect(now.workspace).toEqual({ name: "chant", root: "." });
+    expect(now.workspace).toMatchObject({ name: "chant", root: "." });
     expect(now.declaration?.file).toBe("chant.workspace.json");
 
     const head = result(await runChecks(join(REPO, "packages", "core"), "HEAD"));
     expectValid(head);
     expect(head.at).toBe(git(REPO, "rev-parse", "HEAD"));
-    expect(head.workspace).toEqual({ name: "chant", root: "." });
+    expect(head.workspace).toMatchObject({ name: "chant", root: "." });
     expect(head.declaration?.file).toBe("../../chant.workspace.json");
   });
 });
@@ -82,7 +83,7 @@ describe("chant workspace check on built workspaces", () => {
     const doc = result(await runChecks(root));
     expectValid(doc);
     expect(doc.ok).toBe(false);
-    expect(doc.workspace).toEqual({ name: "acme", root: "." });
+    expect(doc.workspace).toEqual({ name: "acme", root: ".", repo: null });
     expect(ruleIds(doc)).toEqual(["WSP004", "WSP003"]);
 
     const tooOld = repo({ "chant.workspace.json": declaration([], { minReader: "999.0.0" }) });
@@ -93,7 +94,7 @@ describe("chant workspace check on built workspaces", () => {
     ] as const) {
       const d = result(await runChecks(dir));
       expectValid(d);
-      expect(d.workspace).toEqual({ name: null, root: "." });
+      expect(d.workspace).toEqual({ name: null, root: ".", repo: null });
       expect(d.declaration?.diagnostics.map((x) => [x.ruleId, x.code])).toEqual([["WSP001", code]]);
     }
   });

package/src/workspace/check.schema.json

@@ -65,6 +65,13 @@
                   ],
                   "description": "The declared name, or null when the declaration can't be read."
                 },
+                "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."
@@ -341,7 +348,8 @@
             "ci-workflow-ungated-env",
             "ci-workflow-pipeline-missing",
             "ci-workflow-pipeline-differs",
-            "ci-workflow-publish-missing"
+            "ci-workflow-publish-missing",
+            "ci-branch-route-differs"
           ],
           "description": "For WSP001: why the declaration can't be read. For WSP121 to WSP127, the box finding (#2726, #2727, #2780, #2850). For WSP117, work-acceptance-unmet (#2772). For WSP118, flag-stale (#4024). For WSP131 to WSP133, the diagram finding (#2764)."
         }
@@ -463,7 +471,8 @@
             "ci-workflow-ungated-env",
             "ci-workflow-pipeline-missing",
             "ci-workflow-pipeline-differs",
-            "ci-workflow-publish-missing"
+            "ci-workflow-publish-missing",
+            "ci-branch-route-differs"
           ],
           "description": "For WSP001: why the declaration can't be read. For WSP121 to WSP127, the box finding (#2726, #2727, #2780, #2850). For WSP117, work-acceptance-unmet (#2772). For WSP118, flag-stale (#4024). For WSP131 to WSP133, the diagram finding (#2764)."
         },