@intentius/chant 0.124.32 → 0.124.33

package/src/workspace/release-candidates.test.ts

@@ -0,0 +1,106 @@
+/**
+ * The `release-candidates` read (#4168 4.2): green commits of trunk, each
+ * with the commits since the previous one, held to
+ * `release-candidates.schema.json`.
+ */
+
+import { describe, test, expect } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { contract } from "./__fixtures__/contract-repo";
+import candidatesSchema from "./release-candidates.schema.json";
+import { prFromSubject, recordTrailers, releaseCandidatesDocument, RELEASE_CANDIDATES_SCHEMA_ID } from "./release-candidates";
+import { appendCut, makeRelease, persistRelease } from "../lifecycle/release-store";
+import { appendReleaseRecord } from "../lifecycle/release-ledger";
+import { writeLedgerFiles } from "../lifecycle/git";
+
+const { expectValid } = contract(candidatesSchema);
+
+function git(dir: string, ...args: string[]): string {
+  const r = spawnSync("git", args, { cwd: dir, encoding: "utf-8" });
+  if (r.status !== 0) throw new Error(`git ${args.join(" ")}: ${r.stderr}`);
+  return r.stdout.trim();
+}
+
+/** A repo on main with chant.config.ts declaring staging and prod, and one commit per subject. */
+function repo(dir: string, subjects: string[]): string[] {
+  for (const args of [["init", "-q", "-b", "main"], ["config", "user.email", "t@chant.dev"], ["config", "user.name", "T"]]) git(dir, ...args);
+  writeFileSync(join(dir, "chant.config.ts"), `export default { environments: ["staging", "prod"] };\n`);
+  git(dir, "add", ".");
+  git(dir, "commit", "-q", "-m", "init");
+  const shas = [git(dir, "rev-parse", "HEAD")];
+  for (const s of subjects) {
+    git(dir, "commit", "-q", "--allow-empty", "-m", s);
+    shas.push(git(dir, "rev-parse", "HEAD"));
+  }
+  return shas;
+}
+
+describe("recordTrailers and prFromSubject", () => {
+  test("read work ids, every record, and a squash subject's pull request", () => {
+    expect(recordTrailers({ "Chant-Record": ["work:w-1", "decision:d-2", "nonsense"] })).toEqual({ work: ["w-1"], records: ["work:w-1", "decision:d-2"] });
+    expect(prFromSubject("ci: a thing (#4168) (#4174)")).toBe(4174);
+    expect(prFromSubject("no number here")).toBeNull();
+  });
+});
+
+describe("releaseCandidatesDocument", () => {
+  test("partitions the walk at green commits, skips revoked ones, and says which environments each is new for", async () => {
+    await withTestDir(async (dir) => {
+      const [init, a, b, c, d, e] = repo(dir, ["a (#1)", "b\n\nChant-Record: work:w-7", "c", "d (#4)", "e"]);
+      for (const sha of [init, b, d]) git(dir, "tag", `ci/green/${sha}`);
+      git(dir, "tag", `ci/green/${c}`);
+      git(dir, "tag", `ci/revoked/${c}`);
+
+      // staging runs a release of init; prod runs nothing.
+      const r = makeRelease({ member: null, commit: init, artifactDigests: [], targets: [{ env: "staging", templates: [], params: [] }] });
+      await persistRelease(r, [], { cwd: dir });
+      await appendCut({ releaseDigest: r.releaseDigest, label: "v0", actor: "alice", timestamp: "2026-10-20T10:00:00.000Z", runOrigin: null }, { cwd: dir });
+      await appendReleaseRecord(
+        { component: "api", env: "staging", digest: `sha256:${"a".repeat(64)}`, gitSha: init, runId: "r", timestamp: "2026-10-20T11:00:00.000Z", actor: "ci", releaseDigest: r.releaseDigest },
+        { cwd: dir },
+      );
+      // A merge record for d names its pull request.
+      await writeLedgerFiles([{ path: `_merges/${d}.json`, content: JSON.stringify({ pr: 40, approvedDigest: "sha256:x" }) }], "merge record", { cwd: dir });
+
+      const doc = await releaseCandidatesDocument({ cwd: dir });
+      expectValid(doc);
+      if ("error" in doc) throw new Error(doc.error.message);
+      expect(doc).toMatchObject({ $schema: RELEASE_CANDIDATES_SCHEMA_ID, contract: 1, branch: "main", tip: e, member: null });
+      expect(doc.environments).toEqual([
+        { env: "staging", running: [{ releaseDigest: r.releaseDigest, label: "v0", commit: init, components: ["api"] }] },
+        { env: "prod", running: [] },
+      ]);
+      // prod runs nothing, so the walk is not bounded and reaches init.
+      expect(doc.since).toBeNull();
+      expect(doc.candidates.map((x) => x.commit)).toEqual([d, b, init]);
+      expect(doc.candidates[0]).toMatchObject({ newFor: ["staging", "prod"], cut: [] });
+      expect(doc.candidates[0].changes.map((x) => x.commit)).toEqual([d, c]);
+      expect(doc.candidates[0].changes[0]).toMatchObject({ pr: 40, merge: { pr: 40, approvedDigest: "sha256:x" } });
+      expect(doc.candidates[1].changes.map((x) => x.commit)).toEqual([b, a]);
+      expect(doc.candidates[1].changes[0].work).toEqual(["w-7"]);
+      expect(doc.candidates[1].changes[1].pr).toBe(1);
+      expect(doc.candidates[2]).toMatchObject({ commit: init, newFor: ["prod"], cut: ["v0"] });
+      expect(doc.skipped).toEqual([{ commit: c, subject: "c", reason: "revoked" }]);
+      expect(doc.pending.map((x) => x.commit)).toEqual([e]);
+
+      // --env staging stops at what staging runs.
+      const staging = await releaseCandidatesDocument({ cwd: dir, env: "staging" });
+      if ("error" in staging) throw new Error(staging.error.message);
+      expectValid(staging);
+      expect(staging.since).toBe(init);
+      expect(staging.candidates.map((x) => x.commit)).toEqual([d, b]);
+      expect(staging.candidates.every((x) => x.newFor.join() === "staging")).toBe(true);
+    });
+  });
+
+  test("outside git it is the failure not-a-git-repository", async () => {
+    await withTestDir(async (dir) => {
+      const doc = await releaseCandidatesDocument({ cwd: dir });
+      expectValid(doc);
+      expect(doc).toMatchObject({ error: { code: "not-a-git-repository" } });
+    });
+  });
+});

package/src/workspace/release-candidates.ts

@@ -0,0 +1,315 @@
+/**
+ * The `release-candidates` read (#4168 4.2): which green commits of trunk a
+ * person can cut a release from, and what each one would ship.
+ *
+ * `chant release candidates [--env <env>] [--json]` prints this document.
+ * It walks the first-parent line of the trunk (`ci.green.branch`, else what
+ * `origin/HEAD` names, as `release cut` resolves it) from its tip back to the
+ * oldest commit an environment of the member runs, or `limit` commits when an
+ * environment runs no release yet. An environment runs the releases its
+ * latest deploy records name in `releaseDigest`, as the `releases` read
+ * (./releases.ts) says.
+ *
+ * Every green commit that is not revoked is a candidate. Its `changes` are
+ * the first-parent commits after the previous candidate up to and including
+ * it, so the candidates partition the walk. A revoked commit is listed under
+ * `skipped`, and its changes carry on into the next candidate. Commits after
+ * the newest candidate are listed under `pending`: they are not green yet, or
+ * went red.
+ *
+ * For each change it names the work items and other records its
+ * `Chant-Record` trailers name, the pull request a forge's squash subject
+ * names (`... (#123)`), and the merge record `_merges/<sha>.json` on
+ * `chant/lifecycle` when one exists (#4168 4.1). Each candidate lists the
+ * flags whose record files changed in its range, from the declared flag kinds
+ * (#4024).
+ *
+ * It reads local refs and tags only and never fetches. Git is read through a
+ * local `git` subprocess.
+ */
+
+import { execFileSync } from "node:child_process";
+import { relative, resolve, sep } from "node:path";
+import { latestPerComponent, readReleaseLedger } from "../lifecycle/release-ledger";
+import { readAllReleases, readCuts } from "../lifecycle/release-store";
+import { resolveMemberLedger } from "../lifecycle/member-ledger";
+import { readBlobFromPath } from "../lifecycle/git";
+import { readerVersion } from "./declaration";
+
+export const RELEASE_CANDIDATES_CONTRACT_VERSION = 1;
+export const RELEASE_CANDIDATES_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/release-candidates/v1/release-candidates.schema.json";
+
+/** Why the read stopped. Closed; each code is in `reason-codes.ts`. */
+export const RELEASE_CANDIDATES_ERROR_CODES = ["not-a-git-repository", "ledger-unreadable"] as const;
+
+/** How many first-parent commits the walk reads when no environment bounds it. */
+export const DEFAULT_CANDIDATE_LIMIT = 50;
+
+/** A release an environment runs, by the components whose latest deploy names it. */
+export interface RunningRelease {
+  releaseDigest: string;
+  label: string | null;
+  /** The commit it was cut from, or null when its release file is not on this clone's branch. */
+  commit: string | null;
+  components: string[];
+}
+
+export interface CandidateEnvironment {
+  env: string;
+  /** Newest cut first. Empty when no deploy there names a release. */
+  running: RunningRelease[];
+}
+
+/** One first-parent commit in a candidate's range. */
+export interface CandidateChange {
+  commit: string;
+  subject: string;
+  /** Author date, ISO 8601. */
+  date: string;
+  /** The ids its `Chant-Record: work:<id>` trailers name. */
+  work: string[];
+  /** Every `Chant-Record` trailer, as `<kind>:<id>`. */
+  records: string[];
+  /** The pull request the subject names (`(#123)` at its end), the merge record's, or null. */
+  pr: number | null;
+  /** The merge record `_merges/<sha>.json` (#4168 4.1), as stored, or null when there is none. */
+  merge: Record<string, unknown> | null;
+}
+
+export interface CandidateFlag {
+  id: string;
+  member: string;
+  param: string;
+  /** The record file from the workspace root. */
+  path: string;
+  /** The value per environment, as the working tree's record writes it. */
+  values: Record<string, string | number | boolean>;
+}
+
+export interface Candidate {
+  commit: string;
+  subject: string;
+  date: string;
+  /** The environments that don't run this commit or a later one yet. */
+  newFor: string[];
+  /** The labels of releases already cut from it. */
+  cut: string[];
+  changes: CandidateChange[];
+  flags: CandidateFlag[];
+}
+
+export type ReleaseCandidatesDocument =
+  | {
+      $schema: string;
+      contract: number;
+      chant: string;
+      member: string | null;
+      branch: string;
+      /** The tip of the branch as this clone knows it. */
+      tip: string | null;
+      environments: CandidateEnvironment[];
+      /** The oldest commit an environment runs, where the walk stopped, or null when it read `limit` commits. */
+      since: string | null;
+      /** Newest first. */
+      candidates: Candidate[];
+      /** Revoked green commits, newest first. */
+      skipped: Array<{ commit: string; subject: string; reason: "revoked" }>;
+      /** Commits after the newest candidate, newest first. */
+      pending: CandidateChange[];
+    }
+  | { $schema: string; contract: number; chant: string; error: { code: (typeof RELEASE_CANDIDATES_ERROR_CODES)[number]; message: string } };
+
+export interface ReleaseCandidatesQuery {
+  cwd: string;
+  /** Only this environment's view: the walk stops at what it runs, and `newFor` names only it. */
+  env?: string;
+  limit?: number;
+}
+
+function git(top: string, args: string[]): string {
+  return execFileSync("git", args, { cwd: top, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 * 1024 * 1024 }).trim();
+}
+
+function tryGit(top: string, args: string[]): string | null {
+  try {
+    return git(top, args);
+  } catch {
+    return null;
+  }
+}
+
+const PR_IN_SUBJECT = /\(#(\d+)\)\s*$/;
+
+/** The work ids and `<kind>:<id>` records a commit's `Chant-Record` trailers name. */
+export function recordTrailers(trailers: Record<string, string[]>): { work: string[]; records: string[] } {
+  const values = Object.entries(trailers)
+    .filter(([k]) => k.toLowerCase() === "chant-record")
+    .flatMap(([, v]) => v);
+  const records = values.map((v) => v.trim()).filter((v) => /^[^:\s]+:\S+$/.test(v));
+  const work = records.filter((r) => r.startsWith("work:")).map((r) => r.slice("work:".length));
+  return { work, records };
+}
+
+/** The pull request number at the end of a squash subject, or null. */
+export function prFromSubject(subject: string): number | null {
+  const m = PR_IN_SUBJECT.exec(subject);
+  return m ? Number(m[1]) : null;
+}
+
+/** Read the release candidates of the member at `query.cwd`. */
+export async function releaseCandidatesDocument(query: ReleaseCandidatesQuery): Promise<ReleaseCandidatesDocument> {
+  const head = { $schema: RELEASE_CANDIDATES_SCHEMA_ID, contract: RELEASE_CANDIDATES_CONTRACT_VERSION, chant: readerVersion() };
+  const cwd = resolve(query.cwd);
+  const top = tryGit(cwd, ["rev-parse", "--show-toplevel"]);
+  if (!top) return { ...head, error: { code: "not-a-git-repository", message: "candidates are read from trunk's commits and tags, and this directory is not in a git repository" } };
+  try {
+    const { scopeSource } = await import("./write-scope");
+    const { resolveTrunk } = await import("../lifecycle/release-workstation");
+    const { judgedCiTags } = await import("../lifecycle/release-revocation");
+    const { commitDetails } = await import("./intent");
+    const source = scopeSource(cwd);
+    const green = source.declaration?.ci?.green ?? null;
+    const trunk = resolveTrunk(top, green?.branch ?? null);
+    const tip =
+      tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/remotes/${trunk.remote}/${trunk.branch}^{commit}`]) ??
+      tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/heads/${trunk.branch}^{commit}`]);
+    const ledger = await resolveMemberLedger(cwd);
+    const loc = { cwd };
+
+    // What each environment runs.
+    const { readMemberPromotionOrder } = await import("./promotion-order");
+    const order = ((await readMemberPromotionOrder(cwd)) ?? []).map((s) => s.name);
+    const envNames = query.env !== undefined ? [query.env] : order;
+    const { releases } = await readAllReleases(loc);
+    const { cuts } = await readCuts(loc);
+    const commitOf = new Map(releases.map((r) => [r.releaseDigest, r.commit]));
+    const labelOf = new Map<string, string>();
+    const cutAt = new Map<string, string>();
+    for (const c of cuts) {
+      if (c.label !== null && !labelOf.has(c.releaseDigest)) labelOf.set(c.releaseDigest, c.label);
+      if (!cutAt.has(c.releaseDigest) || c.timestamp > cutAt.get(c.releaseDigest)!) cutAt.set(c.releaseDigest, c.timestamp);
+    }
+    const environments: CandidateEnvironment[] = [];
+    for (const env of envNames) {
+      const { records } = await readReleaseLedger(env, loc);
+      const byDigest = new Map<string, string[]>();
+      for (const record of latestPerComponent(records).values()) {
+        const digest = (record as { releaseDigest?: unknown }).releaseDigest;
+        if (typeof digest !== "string") continue;
+        byDigest.set(digest, [...(byDigest.get(digest) ?? []), record.component].sort());
+      }
+      const running = [...byDigest]
+        .map(([releaseDigest, components]) => ({ releaseDigest, label: labelOf.get(releaseDigest) ?? null, commit: commitOf.get(releaseDigest) ?? null, components }))
+        .sort((a, b) => ((cutAt.get(b.releaseDigest) ?? "") < (cutAt.get(a.releaseDigest) ?? "") ? -1 : 1));
+      environments.push({ env, running });
+    }
+
+    const empty = { ...head, member: ledger.members.length > 0 ? ledger.members.join("/") : null, branch: trunk.branch, tip, environments, since: null, candidates: [], skipped: [], pending: [] };
+    if (!tip) return empty;
+
+    // The oldest commit any environment runs bounds the walk, when every environment runs one.
+    const limit = query.limit ?? DEFAULT_CANDIDATE_LIMIT;
+    const line = git(top, ["rev-list", "--first-parent", `--max-count=${Math.max(limit, 1) * 20}`, tip]).split("\n").filter(Boolean);
+    const position = new Map(line.map((sha, i) => [sha, i]));
+    const runningCommits = (e: CandidateEnvironment): string[] => e.running.map((r) => r.commit).filter((c): c is string => c !== null && position.has(c));
+    const bounded = environments.length > 0 && environments.every((e) => runningCommits(e).length > 0);
+    let since: string | null = null;
+    let walk = line.slice(0, limit);
+    if (bounded) {
+      const oldest = Math.max(...environments.flatMap((e) => runningCommits(e).map((c) => position.get(c)!)));
+      since = line[oldest];
+      walk = line.slice(0, oldest);
+    }
+    // An environment's newest running commit on the line, by position (smaller is newer).
+    const newestRun = new Map(environments.map((e) => [e.env, Math.min(...runningCommits(e).map((c) => position.get(c)!), Number.POSITIVE_INFINITY)]));
+
+    const tags = await judgedCiTags(top, green);
+    const details = commitDetails(top, walk);
+    const merges = new Map<string, Record<string, unknown>>();
+    for (const sha of walk) {
+      const text = (await readBlobFromPath("_merges", `${sha}.json`, loc)) ?? (ledger.prefix !== "" ? await readBlobFromPath("_merges", `${sha}.json`, { cwd, ledgerPrefix: "" }) : null);
+      if (text === null) continue;
+      try {
+        const parsed = JSON.parse(text) as unknown;
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) merges.set(sha, parsed as Record<string, unknown>);
+      } catch {
+        // A merge record that is not JSON is left out.
+      }
+    }
+    const change = (sha: string): CandidateChange => {
+      const d = details.get(sha);
+      const { work, records } = recordTrailers(d?.trailers ?? {});
+      const merge = merges.get(sha) ?? null;
+      const mergePr = merge && typeof merge.pr === "number" ? merge.pr : null;
+      const subject = d?.subject ?? "";
+      return { commit: sha, subject, date: d?.date ?? "", work, records, pr: mergePr ?? prFromSubject(subject), merge };
+    };
+
+    const flagReader = await flagsReader(top, source.rootOnDisk);
+    const cutLabels = new Map<string, string[]>();
+    for (const r of releases) {
+      const label = labelOf.get(r.releaseDigest);
+      if (label !== undefined) cutLabels.set(r.commit, [...(cutLabels.get(r.commit) ?? []), label].sort());
+    }
+
+    // Oldest first, so each candidate closes the commits since the previous one.
+    const candidates: Candidate[] = [];
+    const skipped: Array<{ commit: string; subject: string; reason: "revoked" }> = [];
+    let open: string[] = [];
+    for (let i = walk.length - 1; i >= 0; i--) {
+      const sha = walk[i];
+      open.push(sha);
+      if (tags.revoked.has(sha)) {
+        skipped.push({ commit: sha, subject: details.get(sha)?.subject ?? "", reason: "revoked" });
+        continue;
+      }
+      if (!tags.green.has(sha)) continue;
+      const own = change(sha);
+      candidates.push({
+        commit: sha,
+        subject: own.subject,
+        date: own.date,
+        newFor: environments.filter((e) => i < newestRun.get(e.env)!).map((e) => e.env),
+        cut: cutLabels.get(sha) ?? [],
+        changes: open.map(change).reverse(),
+        flags: flagReader(open),
+      });
+      open = [];
+    }
+    return {
+      ...empty,
+      since,
+      candidates: candidates.reverse(),
+      skipped: skipped.reverse(),
+      pending: open.map(change).reverse(),
+    };
+  } catch (err) {
+    return { ...head, error: { code: "ledger-unreadable", message: `reading the candidates failed: ${err instanceof Error ? err.message : String(err)}` } };
+  }
+}
+
+/** The flags whose record files the given commits change, or a reader that finds none when no flag kind can be read. */
+async function flagsReader(top: string, root: string | null): Promise<(shas: string[]) => CandidateFlag[]> {
+  if (!root) return () => [];
+  let flags: Awaited<ReturnType<typeof import("./flags-read").readWorkspaceFlags>>["flags"];
+  try {
+    const { readWorkspaceFlags } = await import("./flags-read");
+    flags = (await readWorkspaceFlags(root)).flags;
+  } catch {
+    return () => [];
+  }
+  if (flags.length === 0) return () => [];
+  const fromTop = (p: string): string => relative(top, resolve(root, p)).split(sep).join("/");
+  const byPath = new Map(flags.map((f) => [fromTop(f.path), f]));
+  return (shas) => {
+    const touched = new Set<string>();
+    for (const sha of shas) {
+      const names = tryGit(top, ["diff-tree", "--no-commit-id", "--name-only", "-r", "--root", sha]) ?? "";
+      for (const n of names.split("\n")) if (byPath.has(n)) touched.add(n);
+    }
+    return [...touched]
+      .sort()
+      .map((p) => byPath.get(p)!)
+      .map((f) => ({ id: f.id, member: f.member, param: f.param, path: f.path, values: f.values }));
+  };
+}

package/src/workspace/security.test.ts

@@ -0,0 +1,70 @@
+/**
+ * The security groups (#4168): which groups a member runs under, and the
+ * reference pages printed from the registries.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterAll, describe, expect, test } from "vitest";
+import { WORKSPACE_CHECKS } from "./checks";
+import { memberAtCwd, securityFeatureTable, securityGroupsAt, securityGroupsOf } from "./security";
+
+const DOCS = fileURLToPath(new URL("../../../../docs/src/content/docs/", import.meta.url));
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+
+describe("securityGroupsOf", () => {
+  const declaration = {
+    security: ["verified-releases" as const],
+    members: [
+      { name: "api", dir: "api", security: ["supply-chain" as const] },
+      { name: "web", dir: "web", security: [] },
+    ],
+  };
+
+  test("a member runs under the top-level groups and its own", () => {
+    expect([...securityGroupsOf(declaration as never, "api")]).toEqual(["verified-releases", "supply-chain"]);
+    expect([...securityGroupsOf(declaration as never, "web")]).toEqual(["verified-releases"]);
+    expect([...securityGroupsOf(declaration as never)]).toEqual(["verified-releases"]);
+  });
+
+  test("no declaration or no security key turns nothing on", () => {
+    expect(securityGroupsOf(null).size).toBe(0);
+    expect(securityGroupsOf({ security: [], members: [] } as never, "api").size).toBe(0);
+  });
+
+  test("securityGroupsAt reads the member holding the directory", () => {
+    const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-security-groups-")));
+    scratch.push(root);
+    execFileSync("git", ["init", "-q"], { cwd: root });
+    mkdirSync(join(root, "api", "src"), { recursive: true });
+    writeFileSync(
+      join(root, "chant.workspace.json"),
+      JSON.stringify({ name: "acme", schema: 1, security: ["review-rules"], members: [{ name: "api", dir: "api", kind: "other", because: "x", security: ["who-ran-it"] }] }),
+    );
+    expect(memberAtCwd({ declaration: { members: [{ name: "api", dir: "api" }] } as never, rootOnDisk: root }, join(root, "api", "src"))).toBe("api");
+    expect([...securityGroupsAt(join(root, "api", "src"))]).toEqual(["review-rules", "who-ran-it"]);
+    expect([...securityGroupsAt(root)]).toEqual(["review-rules"]);
+  });
+});
+
+describe("reference pages", () => {
+  test("the security features page carries the table SECURITY_FEATURES prints", () => {
+    const page = readFileSync(join(DOCS, "reference", "security-features.mdx"), "utf-8");
+    const table = /^\| Feature \| Default \|[^\n]*\n(?:\|[^\n]*\n)*/m.exec(page)?.[0].trimEnd();
+    expect(table, "regenerate the table under Features from securityFeatureTable()").toBe(securityFeatureTable());
+  });
+
+  test("the workspace check page lists every check with its name, default severity and whether it can be set", () => {
+    const page = readFileSync(join(DOCS, "cli", "workspace-check.mdx"), "utf-8");
+    for (const c of WORKSPACE_CHECKS) {
+      expect(page, c.id).toContain(`| \`${c.id}\` | ${c.name} | ${c.severity} | ${c.configurable ? "yes" : "no"} |`);
+    }
+  });
+});

package/src/workspace/security.ts

@@ -0,0 +1,118 @@
+/**
+ * The security groups a workspace opts into (#4168 section 8): the
+ * declaration's top-level `security`, such as `["verified-releases"]`, plus
+ * the `security` of the member a command runs in (#4168 step 7). With no
+ * `security` key none is on, and a security feature the workspace has not
+ * turned on never refuses, warns or hides anything (the rule #4156 set for
+ * runner signing).
+ *
+ * What each group turns on:
+ * - `verified-releases`: `chant release publish` refuses a release with no
+ *   verified signature, as the `release` gate in `identity.gates` does, and
+ *   `chant components promote --release` verifies the release first.
+ * - `supply-chain`: a publish without OIDC provenance warns, and a target
+ *   with no SBOM source is refused (`publish-sbom-missing`).
+ * - `who-ran-it`: `chant ci tick` refuses to tag without a runner key.
+ * - `review-rules`: `chant components pr-apply` counts an approval only from
+ *   someone who approved the pull request on the forge, as
+ *   `--require-review` does, and a generated pull-request pipeline passes
+ *   the flag.
+ * - `isolated-runners`: `chant ci run apply`, under `chant ci serve` too,
+ *   refuses to start without a provisioner's runner-start statement for the
+ *   job (#4147), as `--require-runner-start` does, and a generated
+ *   pull-request pipeline passes the flag. A `--local` run is exempt.
+ *
+ * Each feature still turns on alone: `identity.gates.release`,
+ * `--require-provenance`, `--require-review`, `ci.green.signedSince`.
+ * `chant workspace check` reports what a declared group still lacks
+ * (./checks/security.ts, WSP161 to WSP165). {@link SECURITY_FEATURES} is the
+ * table the reference page prints.
+ */
+import { realpathSync } from "node:fs";
+import { relative, sep } from "node:path";
+import type { Declaration } from "./declaration";
+import { memberHolding } from "./record-assets";
+import { scopeSource, type ScopeSource } from "./write-scope";
+
+export const SECURITY_GROUPS = ["verified-releases", "supply-chain", "who-ran-it", "review-rules", "isolated-runners"] as const;
+
+export type SecurityGroup = (typeof SECURITY_GROUPS)[number];
+
+/**
+ * The groups `declaration` turns on for `member` (a member name): the
+ * top-level list plus that member's own. Empty for no declaration or no
+ * `security` key anywhere.
+ */
+export function securityGroupsOf(declaration: Pick<Declaration, "security" | "members"> | null | undefined, member: string | null = null): ReadonlySet<SecurityGroup> {
+  const own = member === null ? [] : (declaration?.members?.find((m) => m.name === member)?.security ?? []);
+  return new Set([...(declaration?.security ?? []), ...own]);
+}
+
+/** The member of `source`'s declaration whose directory holds `cwd`, or null. */
+export function memberAtCwd(source: Pick<ScopeSource, "declaration" | "rootOnDisk">, cwd: string): string | null {
+  if (!source.declaration || source.rootOnDisk === null) return null;
+  let rel: string;
+  try {
+    rel = relative(realpathSync(source.rootOnDisk), realpathSync(cwd));
+  } catch {
+    rel = relative(source.rootOnDisk, cwd);
+  }
+  if (rel.startsWith("..")) return null;
+  const posix = sep === "/" ? rel : rel.split(sep).join("/");
+  return memberHolding(posix === "" ? "." : posix, source.declaration.members);
+}
+
+/** The groups `source` turns on for a command run in `cwd`: the top-level list and the list of the member holding `cwd`. */
+export function securityGroupsIn(source: Pick<ScopeSource, "declaration" | "rootOnDisk">, cwd: string): ReadonlySet<SecurityGroup> {
+  return securityGroupsOf(source.declaration, memberAtCwd(source, cwd));
+}
+
+/**
+ * The groups the workspace holding `cwd` turns on for the member holding
+ * `cwd`, read at base (the target branch tip) when there is one, else from
+ * the working tree, as the release gate is read. Empty outside a workspace.
+ */
+export function securityGroupsAt(cwd: string, at?: string): ReadonlySet<SecurityGroup> {
+  return securityGroupsIn(scopeSource(cwd, at), cwd);
+}
+
+/** One row of the security feature table (#4168 section 8). */
+export interface SecurityFeature {
+  feature: string;
+  /** What happens with no group and no setting. */
+  byDefault: string;
+  /** What turns it on alone. */
+  setting: string;
+  group: SecurityGroup | null;
+  /** The `workspace check` reason codes that report it missing under its group. */
+  codes: readonly string[];
+}
+
+/**
+ * Every security feature, the group that raises it and the setting that
+ * turns it on alone. The reference page's table is printed from this list
+ * (`securityFeatureTable`), and a test compares the two.
+ */
+export const SECURITY_FEATURES: readonly SecurityFeature[] = [
+  { feature: "Publish refuses an unsigned release", byDefault: "off: publishes and records `signature: unsigned`", setting: "`identity.gates.release`", group: "verified-releases", codes: ["security-signers-missing", "security-publish-allows-unsigned"] },
+  { feature: "Signed cut in the release gate's class", byDefault: "off", setting: "`identity.gates.release` with a `class`", group: "verified-releases", codes: ["security-release-gate-missing"] },
+  { feature: "Promote verifies the release", byDefault: "off: `chant release verify` on demand", setting: "`chant release verify`", group: "verified-releases", codes: [] },
+  { feature: "SBOM on every target", byDefault: "off: a target with no SBOM source publishes without one", setting: "`sbom` on the target", group: "supply-chain", codes: ["security-sbom-disabled", "security-sbom-unsourced"] },
+  { feature: "OIDC provenance", byDefault: "off: a plan field", setting: "`--require-provenance`", group: "supply-chain", codes: ["security-publish-no-provenance"] },
+  { feature: "SBOM and verify steps on components", byDefault: "off", setting: "a `generate-sbom` or `verify` step", group: "supply-chain", codes: ["security-component-no-sbom", "security-component-no-verify"] },
+  { feature: "Signed green tags and runs", byDefault: "off: every tag counts", setting: "`ci.green.signedSince`", group: "who-ran-it", codes: ["security-signed-since-unset"] },
+  { feature: "Trusted runner keys", byDefault: "off", setting: "`.chant/trust.json` with a runner role", group: "who-ran-it", codes: ["security-runner-untrusted"] },
+  { feature: "Tick signs its tags", byDefault: "off: unsigned tags", setting: "`--key` or `CHANT_RUNNER_KEY`", group: "who-ran-it", codes: ["security-tick-no-key"] },
+  { feature: "Forge review required, authors never count", byDefault: "off", setting: "`--require-review`, `requireReview: true`", group: "review-rules", codes: ["security-review-not-required"] },
+  { feature: "Identified attribution", byDefault: "off: `any`", setting: "`identity.attribution: \"identified\"`", group: "review-rules", codes: ["security-attribution-any"] },
+  { feature: "Signed approvals", byDefault: "off", setting: "`identity.gates.<gate>`", group: "review-rules", codes: ["security-gate-unsigned"] },
+  { feature: "Apply jobs require a runner-start statement", byDefault: "off", setting: "`--require-runner-start`", group: "isolated-runners", codes: ["security-runner-start-no-key", "security-runner-start-no-role", "security-trust-unreadable"] },
+  { feature: "Secrets file", byDefault: "off", setting: "`--secrets`", group: null, codes: [] },
+  { feature: "Env allowlist and log redaction", byDefault: "on: `ci run`'s contract, a listed exception", setting: "`--pass-env`", group: null, codes: [] },
+];
+
+/** The reference page's table of {@link SECURITY_FEATURES}, as markdown. */
+export function securityFeatureTable(): string {
+  const rows = SECURITY_FEATURES.map((f) => `| ${f.feature} | ${f.byDefault} | ${f.setting} | ${f.group ? `\`${f.group}\`` : "none"} | ${f.codes.map((c) => `\`${c}\``).join(", ") || "none"} |`);
+  return ["| Feature | Default | Turns it on alone | Group | Checked as |", "|---|---|---|---|---|", ...rows].join("\n");
+}