@intentius/chant 0.124.45 → 0.124.48

package/src/workspace/capabilities-contract.ts

@@ -0,0 +1,132 @@
+/**
+ * The `capabilities` document of the read contract (#4375, ws-017): the
+ * capability catalog `chant search` answers `cap:` terms with, described by
+ * `capabilities.schema.json` beside this file.
+ *
+ * `chant search --capabilities --json` prints it for one project, with a
+ * support statement for each lexicon the project loads. `chant workspace
+ * search --capabilities --json` prints it from the workspace root's chant,
+ * for every lexicon a member loads (a terraform member's reader lexicon
+ * included, #4380): capability rules run once, under
+ * the workspace's chant, so the catalog is that chant's. chant's MCP
+ * `capabilities` tool returns whichever of the two applies where the server
+ * runs, unchanged.
+ */
+
+import { resolve } from "node:path";
+import type { ReasonCode } from "./reason-codes";
+import type { CapabilityEntry } from "../capabilities/catalog";
+
+/** The version of the `capabilities` document this chant writes. */
+export const CAPABILITIES_CONTRACT_VERSION = 1;
+
+/** `$id` of the JSON Schema for the document, shipped beside this file. */
+export const CAPABILITIES_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/capabilities/v1/capabilities.schema.json";
+
+/** Why no catalog was printed. */
+export const CAPABILITIES_ERROR_CODES = ["usage-invalid"] as const satisfies readonly ReasonCode[];
+export type CapabilitiesErrorCode = (typeof CAPABILITIES_ERROR_CODES)[number];
+
+/** Why a lexicon can't supply a capability. */
+export const CAPABILITY_SUPPORT_CODES = ["lexicon-has-no-mapping", "capability-not-derivable", "lexicon-not-loaded"] as const satisfies readonly ReasonCode[];
+
+interface CapabilitiesHead {
+  $schema: typeof CAPABILITIES_OUTPUT_SCHEMA_ID;
+  contract: typeof CAPABILITIES_CONTRACT_VERSION;
+  /** The chant that wrote the document. */
+  chant: string;
+}
+
+export interface CapabilitiesResult extends CapabilitiesHead {
+  capabilities: CapabilityEntry[];
+  helpers: { name: string; rule: string }[];
+}
+
+export interface CapabilitiesFailure extends CapabilitiesHead {
+  error: { code: CapabilitiesErrorCode; message: string; hint?: string };
+}
+
+export type CapabilitiesDocument = CapabilitiesResult | CapabilitiesFailure;
+
+async function head(): Promise<CapabilitiesHead> {
+  const { readChantPackageVersion } = await import("../package-version");
+  return { $schema: CAPABILITIES_OUTPUT_SCHEMA_ID, contract: CAPABILITIES_CONTRACT_VERSION, chant: readChantPackageVersion() };
+}
+
+/**
+ * The catalog, with a support statement for each lexicon named. Each is
+ * loaded on its own, so one that isn't installed is said to be, and the rest
+ * still read.
+ */
+export async function capabilitiesDocument(
+  lexicons: string[],
+  load?: (name: string) => Promise<{ capabilityPack?: { mapping: unknown } }>,
+): Promise<CapabilitiesResult> {
+  const loadPlugin = load ?? (await import("../cli/plugins")).loadPlugin;
+  const { capabilityCatalog } = await import("../capabilities/catalog");
+  const mappings: Record<string, Parameters<typeof capabilityCatalog>[0][string]> = {};
+  const notLoaded: string[] = [];
+  for (const name of [...new Set(lexicons)].sort()) {
+    try {
+      mappings[name] = (await loadPlugin(name)).capabilityPack?.mapping as (typeof mappings)[string];
+    } catch {
+      notLoaded.push(name);
+      mappings[name] = undefined;
+    }
+  }
+  const catalog = capabilityCatalog(mappings);
+  for (const c of catalog.capabilities) {
+    for (const name of notLoaded) {
+      c.lexicons[name] = { code: "lexicon-not-loaded", message: `the ${name} lexicon isn't installed where this chant runs, so its mapping wasn't read` };
+    }
+  }
+  return { ...(await head()), ...catalog };
+}
+
+export async function capabilitiesFailure(error: CapabilitiesFailure["error"]): Promise<CapabilitiesFailure> {
+  return { ...(await head()), error };
+}
+
+/**
+ * The lexicons the members of the workspace at `cwd` load, for its catalog:
+ * each chant member's own, and for a member of a package's kind, such as
+ * `terraform`, the lexicon its reader project declares (#4380).
+ */
+export async function workspaceLexicons(cwd: string): Promise<string[]> {
+  const { listWorkspace } = await import("./ls");
+  const { findWorkspaceRoot } = await import("../project-root");
+  const { resolveProjectLexicons } = await import("../cli/plugins");
+  const { loadKindRegistry } = await import("./kinds");
+  const located = findWorkspaceRoot(cwd);
+  const doc = listWorkspace({ cwd });
+  if (!located || "error" in doc) return [];
+  const out = new Set<string>();
+  const kinds = doc.members.some((m) => m.kind !== "chant" && m.readable) ? loadKindRegistry(doc.workspace.pins, located.dir).registry : undefined;
+  for (const m of doc.members) {
+    if (!m.readable) continue;
+    const reader = m.kind === "chant" ? undefined : kinds?.get(m.kind)?.graph?.lexicon;
+    if (reader) out.add(reader);
+    if (m.kind !== "chant") continue;
+    try {
+      for (const l of await resolveProjectLexicons(resolve(located.dir, m.dir))) out.add(l);
+    } catch {
+      // A member whose lexicons can't be resolved adds none; its own search says why.
+    }
+  }
+  return [...out];
+}
+
+/** The catalog as text: one capability per line, its search term and meaning, then its parameters. */
+export function formatCapabilities(doc: CapabilitiesResult): string[] {
+  const width = Math.max(...doc.capabilities.map((c) => c.search.length));
+  const lines: string[] = [];
+  for (const c of doc.capabilities) {
+    lines.push(`${c.search.padEnd(width)}  ${c.shape.padEnd(4)}  ${c.meaning}`);
+    for (const p of c.params) lines.push(`${"".padEnd(width)}        ${p.name}${p.optional ? "?" : ""}: ${p.meaning}`);
+    const unsupported = Object.entries(c.lexicons).filter(([, s]) => s !== "supported");
+    for (const [lex, s] of unsupported) lines.push(`${"".padEnd(width)}        not in ${lex}: ${(s as { message: string }).message}`);
+  }
+  const lexicons = Object.keys(doc.capabilities[0]?.lexicons ?? {});
+  lines.push(`— ${doc.capabilities.length} capabilities${lexicons.length ? ` · lexicons ${lexicons.join(", ")}` : ""} · --json prints each rule`);
+  return lines;
+}

package/src/workspace/capabilities.schema.json

@@ -0,0 +1,229 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/capabilities/v1/capabilities.schema.json",
+  "title": "chant capabilities catalog",
+  "description": "What `chant search --capabilities --json` prints (#4375): the capability catalog `chant search` answers `cap:` terms and `->[cap=...]` edges with, each capability's rule, and whether each lexicon the project loads can supply it. chant's MCP `capabilities` tool returns the same document. Version 1 of the read contract. Readers ignore fields they do not know; a field is only ever added within a version. The codes are a closed list, each in the one closed list of `reason-codes.ts`. Contract version 1 of this document is written by chant 0.124.46 and newer; the read contract as a whole by chant 0.81.0 and newer.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "type": "object",
+      "description": "Exit code 0.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "capabilities",
+        "helpers"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/capabilities/v1/capabilities.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": false,
+        "capabilities": {
+          "type": "array",
+          "description": "Every capability the catalog lists, in the order the rule file defines them.",
+          "items": {
+            "$ref": "#/$defs/capability"
+          }
+        },
+        "helpers": {
+          "type": "array",
+          "description": "Rules the capabilities use that the catalog does not list as capabilities of their own.",
+          "items": {
+            "type": "object",
+            "required": [
+              "name",
+              "rule"
+            ],
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "rule": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "capability": {
+      "type": "object",
+      "required": [
+        "name",
+        "meaning",
+        "shape",
+        "params",
+        "search",
+        "answers",
+        "depth",
+        "lexicons",
+        "notEvaluated",
+        "uses",
+        "rule"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "meaning": {
+          "type": "string",
+          "description": "What the capability says, in one line."
+        },
+        "shape": {
+          "enum": [
+            "set",
+            "edge"
+          ],
+          "description": "set: a set of nodes, tested with cap:<name>. edge: pairs of nodes, walked with ->[cap=<name>] or <-[cap=<name>]."
+        },
+        "params": {
+          "type": "array",
+          "description": "Arguments, in order: cap:<name>(<a>, <b>). An optional one left out drops the test that reads it.",
+          "items": {
+            "type": "object",
+            "required": [
+              "name",
+              "optional",
+              "meaning"
+            ],
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "optional": {
+                "type": "boolean"
+              },
+              "meaning": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "search": {
+          "type": "string",
+          "description": "The search term that asks for it: cap:<name> for a set, ->[cap=<name>] for an edge."
+        },
+        "answers": {
+          "type": "array",
+          "description": "Questions it serves, in people's words.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "depth": {
+          "enum": [
+            "declared",
+            "live",
+            "either"
+          ],
+          "description": "Which observation can supply its facts: declared source, a live read or snapshot, or either."
+        },
+        "lexicons": {
+          "type": "object",
+          "description": "Each lexicon the project loads: supported, or why it can't supply the capability.",
+          "additionalProperties": {
+            "oneOf": [
+              {
+                "const": "supported"
+              },
+              {
+                "type": "object",
+                "required": [
+                  "code",
+                  "message"
+                ],
+                "properties": {
+                  "code": {
+                    "enum": [
+                      "lexicon-has-no-mapping",
+                      "capability-not-derivable",
+                      "lexicon-not-loaded"
+                    ]
+                  },
+                  "message": {
+                    "type": "string"
+                  }
+                }
+              }
+            ]
+          }
+        },
+        "notEvaluated": {
+          "type": "array",
+          "description": "What the rule leaves out. chant search prints this under every answer that uses the capability.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "uses": {
+          "type": "array",
+          "description": "The capabilities and helpers its rule refers to.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "rule": {
+          "type": "string",
+          "description": "The rule as written, one alternative per line."
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "description": "Exit code 1.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/capabilities/v1/capabilities.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "usage-invalid"
+              ]
+            },
+            "message": {
+              "type": "string"
+            },
+            "hint": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

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)."
         },

package/src/workspace/checks/ci-branch.test.ts

@@ -0,0 +1,128 @@
+/**
+ * WSP152 (#4325): a member's generated pipeline targets the branch
+ * `ci.branches` routes the member to.
+ */
+
+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 { pipelineTargets, routeDifferences } from "./ci-branch";
+import { REASONS } from "../reason-codes";
+import { servedBranches } from "../ci-branches";
+
+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-ci-branch-")));
+  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;
+}
+
+/** A generated pull-request pipeline, as chant writes it for a target `branch` (`--branch` is on the record and apply commands only). */
+const pipeline = (branch: string | null, triggers: string[] = branch === null ? [] : [branch]): string =>
+  [
+    "on:",
+    "  pull_request:",
+    ...(triggers.length > 0 ? [`    branches: [${triggers.join(", ")}]`] : []),
+    "  push:",
+    ...(triggers.length > 0 ? [`    branches: [${triggers.join(", ")}]`] : []),
+    "jobs:",
+    "  plan:",
+    "    steps:",
+    "      - run: chant ci run plan --in-place --no-push --env prod --gate pr-apply --forge github",
+    "  record:",
+    "    steps:",
+    `      - run: chant ci run record --in-place --env prod --gate pr-apply --forge github${branch === null ? "" : ` --branch "${branch}"`}`,
+    "",
+  ].join("\n");
+
+const PIPELINE_PATH = ".github/workflows/chant-pr.app.prod.yml";
+const record = JSON.stringify({ schema: 1, files: [{ path: PIPELINE_PATH, command: "chant build" }] });
+const workspace = (branches: Record<string, string[]> | undefined, text: string, members = ["app"]): Record<string, string> => ({
+  "chant.workspace.json": JSON.stringify({ name: "acme", schema: 1, members: members.map((name) => ({ name, dir: name, kind: "other", because: name })), ...(branches ? { ci: { branches } } : {}) }),
+  ...Object.fromEntries(members.map((m) => [`${m}/.chant/generated.json`, record])),
+  [PIPELINE_PATH]: text,
+});
+
+const found = async (root: string) =>
+  (await runDeclarationChecks(root, (f) => f, { gather: false })).diagnostics.filter((d) => d.ruleId === "WSP152").map((d) => [d.code, d.entity ?? null, d.severity]);
+
+describe("what a pipeline targets", () => {
+  test("reads the --branch of each record and apply command, and the trigger branch lists", () => {
+    expect(pipelineTargets(pipeline("release"))).toEqual({
+      jobs: [{ line: 12, branch: "release" }],
+      triggers: [
+        { trigger: "push", branches: ["release"] },
+        { trigger: "pull_request", branches: ["release"] },
+      ],
+    });
+    expect(pipelineTargets(pipeline(null)).jobs).toEqual([{ line: 10, branch: null }]);
+    expect(pipelineTargets("not: [valid").triggers).toEqual([]);
+  });
+
+  test("a routed member's pipeline names its route in both places; an unrouted one does not name a reserved branch", () => {
+    const listed = ["release"];
+    expect(routeDifferences(pipelineTargets(pipeline("release")), "release", listed, "app")).toEqual([]);
+    expect(routeDifferences(pipelineTargets(pipeline("main")), "release", listed, "app")).toHaveLength(3);
+    expect(routeDifferences(pipelineTargets(pipeline(null)), "release", listed, "app")).toEqual([expect.stringContaining("the default branch")]);
+    expect(routeDifferences(pipelineTargets(pipeline("release", ["release", "main"])), "release", listed, "app")).toHaveLength(2);
+    expect(routeDifferences(pipelineTargets(pipeline("main")), null, listed, "app")).toEqual([]);
+    expect(routeDifferences(pipelineTargets(pipeline("release")), null, listed, "app")).toHaveLength(3);
+  });
+});
+
+describe("WSP152 over a workspace", () => {
+  test("a pipeline on the route passes, and a workspace with no ci.branches is not read", async () => {
+    expect(await found(repo(workspace({ release: ["app"] }, pipeline("release"))))).toEqual([]);
+    expect(await found(repo(workspace(undefined, pipeline("anything"))))).toEqual([]);
+  });
+
+  test("a pipeline generated before the route changed fails", async () => {
+    const root = repo(workspace({ release: ["app"] }, pipeline("main")));
+    expect(await found(root)).toEqual([
+      ["ci-branch-route-differs", "app", "error"],
+      ["ci-branch-route-differs", "app", "error"],
+      ["ci-branch-route-differs", "app", "error"],
+    ]);
+  });
+
+  test("an unrouted member's pipeline may not target a branch ci.branches reserves", async () => {
+    expect(await found(repo(workspace({ release: ["other"] }, pipeline("release"))))).toHaveLength(3);
+    expect(await found(repo(workspace({ release: ["other"] }, pipeline("main"))))).toEqual([]);
+  });
+
+  test("the code is a documented reason code", () => {
+    expect(REASONS["ci-branch-route-differs"]).toMatch(/targets a branch other than/);
+  });
+});
+
+describe("the branches ci serve polls (#4325)", () => {
+  const branches = { release: ["prod-*"], staging: ["stg-*"] };
+
+  test("a routed member polls its route alone, and a branch that disagrees is refused", () => {
+    expect(servedBranches(branches, "prod-eu", "main", false)).toEqual({ served: ["release"], routed: ["release"] });
+    expect(servedBranches(branches, "prod-eu", "release", true).served).toEqual(["release"]);
+    expect(() => servedBranches(branches, "prod-eu", "main", true)).toThrow(/routes member prod-eu to release/);
+  });
+
+  test("an unrouted member polls the default branch, and not one reserved for other members", () => {
+    expect(servedBranches(branches, "docs", "main", false)).toEqual({ served: ["main"], routed: [] });
+    expect(() => servedBranches(branches, "docs", "release", true)).toThrow(/member docs is not one/);
+  });
+
+  test("with no member, the default branch and then each routed branch", () => {
+    expect(servedBranches(branches, undefined, "main", false)).toEqual({ served: ["main", "release", "staging"], routed: ["release", "staging"] });
+    expect(servedBranches(undefined, undefined, "main", false)).toEqual({ served: ["main"], routed: [] });
+    expect(servedBranches(branches, undefined, "release", true).served).toEqual(["release", "staging"]);
+  });
+});