@intentius/chant 0.124.32 → 0.124.34

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/release-workflow.ts

@@ -0,0 +1,167 @@
+/**
+ * `chant release workflow` (#4168 step 6): the publish workflow, generated
+ * the way `chant ci workflow` writes the tick, where the guides used to have
+ * one pasted (guide/release-from-workstation.mdx).
+ *
+ * The job runs on a `release/**` tag, checks the tag out, fetches the ci tags
+ * and `chant/lifecycle`, builds what the targets upload, and runs `chant
+ * release publish` for the label the tag names. The security groups decide
+ * the rest, and nothing is on without one (#4168 section 8):
+ *
+ * - `supply-chain` adds `--require-provenance`, so a run with no OIDC token
+ *   fails rather than publishing without provenance.
+ * - `verified-releases` adds a `chant release verify` step before the publish.
+ *
+ * The OIDC permission (`id-token: write`, or GitLab's `id_tokens`) is always
+ * there: it costs nothing, and with it what the job uploads carries
+ * provenance whether or not the group requires it.
+ */
+import { GENERATED_MARKER } from "../discovery/files";
+import type { SecurityGroup } from "./security";
+
+export const RELEASE_WORKFLOW_FORGES = ["github", "forgejo", "gitlab"] as const;
+export type ReleaseWorkflowForge = (typeof RELEASE_WORKFLOW_FORGES)[number];
+
+/** Where each forge's publish workflow is written, relative to the repository root. */
+export const RELEASE_WORKFLOW_FILES: Record<ReleaseWorkflowForge, string> = {
+  github: ".github/workflows/chant-release.yml",
+  forgejo: ".forgejo/workflows/chant-release.yml",
+  // GitLab reads one .gitlab-ci.yml, which includes this file: `include: { local: .gitlab/chant-release.yml }`.
+  gitlab: ".gitlab/chant-release.yml",
+};
+
+export interface ReleaseWorkflowInput {
+  forge: ReleaseWorkflowForge;
+  /** The security groups the workspace opts into at its root. */
+  groups: ReadonlySet<SecurityGroup>;
+  /** The command that installs what the build needs. Default `npm ci`. */
+  install?: string;
+  /** The command that builds what the targets upload, or none. Default `npm run build`. */
+  build?: string | null;
+  /** What runs chant. Default `npx chant`. */
+  chant?: string;
+  /** The workspace root relative to the repository root, `.` at the top. */
+  workspaceRoot?: string;
+}
+
+/** The flags `chant release publish` gets under the groups. */
+export function publishFlags(groups: ReadonlySet<SecurityGroup>): string[] {
+  return [...(groups.has("supply-chain") ? ["--require-provenance"] : []), "--yes"];
+}
+
+/** The workflow file's text, without the generated-by header. */
+export function renderReleaseWorkflow(input: ReleaseWorkflowInput): string {
+  const chant = input.chant ?? "npx chant";
+  const install = input.install ?? "npm ci";
+  const build = input.build === undefined ? "npm run build" : input.build;
+  const root = input.workspaceRoot && input.workspaceRoot !== "." ? input.workspaceRoot : null;
+  const verify = input.groups.has("verified-releases");
+  const flags = publishFlags(input.groups).join(" ");
+  if (input.forge === "gitlab") {
+    const label = '"${CI_COMMIT_TAG#release/}"';
+    const lines = [
+      "chant-release-publish:",
+      "  rules:",
+      "    - if: $CI_COMMIT_TAG =~ /^release\\//",
+      "  id_tokens:",
+      "    SIGSTORE_ID_TOKEN:",
+      "      aud: sigstore",
+      "  script:",
+      ...(root ? [`    - cd ${root}`] : []),
+      `    - ${install}`,
+      ...(build ? [`    - ${build}`] : []),
+      "    - git fetch origin 'refs/tags/ci/*:refs/tags/ci/*'",
+      "    - git fetch origin chant/lifecycle:chant/lifecycle",
+      ...(verify ? [`    - ${chant} release verify ${label}`] : []),
+      `    - ${chant} release publish ${label} ${flags}`,
+    ];
+    return `${lines.join("\n")}\n`;
+  }
+  const label = '"${GITHUB_REF_NAME#release/}"';
+  const lines = [
+    "name: chant release publish",
+    "on:",
+    "  push:",
+    '    tags: ["release/**"]',
+    "permissions:",
+    "  contents: write",
+    "  id-token: write",
+    "jobs:",
+    "  publish:",
+    "    runs-on: ubuntu-latest",
+    ...(root ? ["    defaults:", "      run:", `        working-directory: ${root}`] : []),
+    "    steps:",
+    "      - uses: actions/checkout@v4",
+    "        with:",
+    "          fetch-depth: 0",
+    "      - uses: actions/setup-node@v4",
+    "        with:",
+    "          node-version: 24",
+    "          registry-url: https://registry.npmjs.org",
+    `      - run: ${install}`,
+    ...(build ? [`      - run: ${build}`] : []),
+    "      - run: git fetch origin 'refs/tags/ci/*:refs/tags/ci/*'",
+    "      - run: git fetch origin chant/lifecycle:chant/lifecycle",
+    ...(verify ? [`      - run: ${chant} release verify ${label}`] : []),
+    `      - run: ${chant} release publish ${label} ${flags}`,
+  ];
+  return `${lines.join("\n")}\n`;
+}
+
+/** The header that marks the file generated, naming the command that regenerates it. */
+export function releaseWorkflowHeader(command: string): string {
+  return `# ${GENERATED_MARKER}. Regenerate with: ${command} (in the workspace root)\n`;
+}
+
+/**
+ * `chant release workflow [--forge github|gitlab|forgejo] [--install <command>]
+ * [--build <command>|--no-build] [--chant <command>] [--output <file>]`: write
+ * the publish workflow for the workspace's forge, under its security groups.
+ */
+export async function runReleaseWorkflow(ctx: import("../cli/registry").CommandContext): Promise<number> {
+  const { existsSync, mkdirSync, realpathSync, writeFileSync } = await import("node:fs");
+  const { dirname, join, relative, resolve, sep } = await import("node:path");
+  const { formatError, formatSuccess } = await import("../cli/format");
+  const { findWorkspaceRoot } = await import("../project-root");
+  const { gitTop } = await import("./tree");
+  const { securityGroupsAt } = await import("./security");
+  const { shellArg } = await import("./member-pipeline");
+  const usage = "chant release workflow [--forge github|gitlab|forgejo] [--install <command>] [--build <command>] [--chant <command>] [--output <file>]";
+  const { args } = ctx;
+  const found = findWorkspaceRoot(process.cwd());
+  if (!found) {
+    console.error(formatError({ message: "no chant.workspace.json between this directory and the git root", hint: usage }));
+    return 1;
+  }
+  const root = realpathSync(found.dir);
+  const repoRoot = gitTop(root) ?? root;
+  const forge = (args.forge ??
+    (existsSync(join(repoRoot, ".github", "workflows")) ? "github" : existsSync(join(repoRoot, ".forgejo", "workflows")) ? "forgejo" : existsSync(join(repoRoot, ".gitlab-ci.yml")) ? "gitlab" : "github")) as ReleaseWorkflowForge;
+  if (!(RELEASE_WORKFLOW_FORGES as readonly string[]).includes(forge)) {
+    console.error(formatError({ message: `--forge ${JSON.stringify(forge)} is not one of ${RELEASE_WORKFLOW_FORGES.join(", ")}`, hint: usage }));
+    return 1;
+  }
+  const groups = securityGroupsAt(root);
+  const workspaceRoot = relative(repoRoot, root).split(sep).join("/") || ".";
+  const text = renderReleaseWorkflow({
+    forge,
+    groups,
+    workspaceRoot,
+    ...(args.ciInstall ? { install: args.ciInstall } : {}),
+    ...(args.buildCommand ? { build: args.buildCommand } : {}),
+    ...(args.ciChant ? { chant: args.ciChant } : {}),
+  });
+  const target = args.output ? resolve(process.cwd(), args.output) : join(repoRoot, RELEASE_WORKFLOW_FILES[forge]);
+  const parts = ["chant", "release", "workflow", "--forge", forge];
+  if (args.ciInstall) parts.push("--install", args.ciInstall);
+  if (args.buildCommand) parts.push("--build", args.buildCommand);
+  if (args.ciChant) parts.push("--chant", args.ciChant);
+  if (args.output) parts.push("--output", relative(root, target).split(sep).join("/"));
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, releaseWorkflowHeader(parts.map(shellArg).join(" ")) + text);
+  const shown = relative(process.cwd(), target).split(sep).join("/") || target;
+  const extras = [groups.has("supply-chain") ? "requires OIDC provenance (supply-chain)" : null, groups.has("verified-releases") ? "verifies the release first (verified-releases)" : null].filter(Boolean);
+  console.log(formatSuccess(`Wrote ${shown}: publishes the release a release/** tag names${extras.length > 0 ? `, and ${extras.join(" and ")}` : ""}.`));
+  if (forge === "gitlab") console.log(`Include it from .gitlab-ci.yml: include: [{ local: ${RELEASE_WORKFLOW_FILES.gitlab} }]`);
+  return 0;
+}

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"} |`);
+    }
+  });
+});