@intentius/chant 0.117.0 → 0.118.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.117.0",
+  "version": "0.118.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/build.ts

@@ -19,6 +19,7 @@ import { discover, type DiscoveryResult, type FoldDecision } from "./discovery/i
 import { decodeEntitySet, type DiscoveredEntitiesJson } from "./discovery/entity-wire";
 import { buildDependencyGraph } from "./discovery/graph";
 import { topologicalSort } from "./sort";
+import { statSync } from "node:fs";
 import { resolve } from "node:path";
 
 /**
@@ -641,6 +642,15 @@ function generateManifest(
   };
 }
 
+/** The directory a build discovered from, for build-root contributors; undefined when the build's path is not one (an entity-set JSON's label). */
+function sourceDirOf(path: string): string | undefined {
+  try {
+    return statSync(path).isDirectory() ? resolve(path) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /** What merging build-root contributions produced: non-fatal render notes and
  * fatal messages (a failed contributor, a name collision). */
 export interface BuildRootMergeResult {
@@ -667,6 +677,7 @@ export interface BuildRootMergeResult {
 export async function mergeBuildRootEntities(
   entities: Map<string, Declarable>,
   contributors: ReadonlyArray<BuildRootContributor>,
+  sourceDir?: string,
 ): Promise<BuildRootMergeResult> {
   const warnings: string[] = [];
   const errors: string[] = [];
@@ -677,7 +688,7 @@ export async function mergeBuildRootEntities(
       // ciphertext file to resolve). Contributors run in order, so this also
       // carries what earlier contributors added; the merge below is still the
       // only writer, which is what keeps the collision refusal meaningful.
-      const contribution = await contribute({ entities });
+      const contribution = await contribute({ entities, ...(sourceDir !== undefined ? { sourceDir } : {}) });
       warnings.push(...(contribution.warnings ?? []));
       for (const [name, entity] of contribution.entities) {
         if (entities.has(name)) {
@@ -809,7 +820,7 @@ async function buildFromDiscoveryResult(
   // object, and re-running the contributors there would duplicate every
   // contributed entity once per child.
   if (!parentBuildStack && options?.buildRoots) {
-    const merged = await mergeBuildRootEntities(discoveryResult.entities, options.buildRoots);
+    const merged = await mergeBuildRootEntities(discoveryResult.entities, options.buildRoots, sourceDirOf(resolvedPathForChildStack));
     warnings.push(...merged.warnings);
     for (const message of merged.errors) {
       errors.push(new BuildErrorClass("", message));

package/src/cli/commands/build.ts

@@ -922,7 +922,8 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
   const resourceCount = result.entities.size;
   const fileCount = result.sourceFileCount;
 
-  if (fileCount === 0 && errors.length === 0) {
+  // A build root (a lexicon's own source files, a rendered overlay) can declare everything without one .ts file.
+  if (fileCount === 0 && resourceCount === 0 && errors.length === 0) {
     console.error(formatInfo("No source files found — create .ts files in the target directory"));
   }
 

package/src/cli/handlers/run-wave.ts

@@ -5,13 +5,25 @@
 
 import { readFileSync } from "node:fs";
 import { relative, resolve } from "node:path";
-import { parseOpWavesSpec, runOpWave } from "../../op/op-waves-run";
+import { parseOpWavesSpec, recordOpWaveHeadPlans, runOpWave } from "../../op/op-waves-run";
 import { formatError } from "../format";
 import type { CommandContext } from "../registry";
 
 export async function runOpWaveCommand(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
   const specFile = args.opsSpec;
+  if (specFile && args.recordPlans) {
+    try {
+      const spec = parseOpWavesSpec(readFileSync(resolve(specFile), "utf-8"), `--spec ${specFile}`);
+      const plans = await recordOpWaveHeadPlans({ spec });
+      if (args.json) console.log(JSON.stringify(plans, null, 2));
+      else for (const w of plans.waves) console.error(`wave ${w.wave} (${w.name}) at ${plans.head.slice(0, 12)}: ${w.digest}`);
+      return 0;
+    } catch (err) {
+      console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+      return 1;
+    }
+  }
   if (!specFile || args.wave === undefined) {
     console.error(formatError({
       message: "`chant run wave` needs --spec <file> and --wave <k>",

package/src/cli/main.ts

@@ -108,6 +108,7 @@ const BOOLEAN_FLAGS = new Set([
   "--root-only",
   "--generated",
   "--decide",
+  "--record-plans",
 ]);
 
 /**
@@ -359,6 +360,8 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.wave = wave;
     } else if (arg === "--decide") {
       result.decide = true;
+    } else if (arg === "--record-plans") {
+      result.recordPlans = true;
     } else if (arg === "--share") {
       const raw = args[++i];
       const share = Number(raw);
@@ -925,7 +928,10 @@ Ops:
   run wave --spec <file> --wave <k>  Plan, gate and apply wave k of an Op
                         waves spec (#3679): the job a generated waves
                         pipeline runs. --decide plans and decides only;
-                        --share <i> applies one share of a decided wave
+                        --share <i> applies one share of a decided wave.
+                        --record-plans (no --wave), in a pull request's
+                        pipeline: plan every wave at its head and record the
+                        digests a pr-review approval mode compares
   run resume [--op <name>]  Start again each CI job that waits at a gate an
                         approval now answers, through the forge's API
                         (#3683); approves nothing. --dry-run lists them

package/src/cli/plugins.ts

@@ -211,7 +211,7 @@ export function collectBuildRootContributors(
     .filter((plugin) => typeof plugin.buildRoots === "function")
     // `entities` is not bindable here — discovery has not run — so the merge
     // hands it in when it calls the closure (#1828 / SOPS provenance).
-    .map((plugin): import("../lexicon").BuildRootContributor => (ctx) => plugin.buildRoots!({ projectRoot, config, entities: ctx?.entities }));
+    .map((plugin): import("../lexicon").BuildRootContributor => (ctx) => plugin.buildRoots!({ projectRoot, config, entities: ctx?.entities, ...(ctx?.sourceDir !== undefined ? { sourceDir: ctx.sourceDir } : {}) }));
   return [...codegen, ...roots];
 }
 

package/src/cli/registry.ts

@@ -252,6 +252,8 @@ export interface ParsedArgs {
   wave?: number;
   /** `chant run wave --decide` (#3679) — plan a wide wave and decide its gate, applying nothing. */
   decide?: boolean;
+  /** `chant run wave --record-plans` (#3684) — plan every wave at a pull request's head and record the digests for a `pr-review` gate. */
+  recordPlans?: boolean;
   /** `chant run wave --share <i>` (#3679) — apply share `i` of a decided wide wave. */
   share?: number;
   /** `chant components fan-out --canary <component>` (#3049), repeatable — components that form wave 1. */

package/src/discovery/files.ts

@@ -116,3 +116,21 @@ export async function findInfraFiles(path: string, options?: FindInfraFilesOptio
     accept: (name, full) => isSourceFileName(name) && !hasDiscoveryMarkerSync(full),
   });
 }
+
+/**
+ * Find the files under `path` that `accept` wants, through the same walk and
+ * the same project globs as {@link findInfraFiles}: a lexicon that reads
+ * source of its own beside the TypeScript (the sql lexicon's `.sql` files)
+ * sees exactly the tree source discovery sees, so `dist`, git-ignored paths,
+ * child projects and the project's `exclude` globs are left out for it too.
+ */
+export async function findSourceFiles(path: string, accept: (name: string, full: string) => boolean, options?: FindInfraFilesOptions): Promise<string[]> {
+  const globs = options?.globs === null ? undefined : (options?.globs ?? (await resolveDiscoveryGlobs(path)));
+  return walkDiscovery({
+    walker: "source",
+    root: path,
+    globs,
+    excludeDirs: await workspaceMemberDirs(path),
+    accept,
+  });
+}

package/src/lexicon.ts

@@ -984,6 +984,15 @@ export interface BuildRootContext {
    * treat an absent map as an empty one.
    */
   entities?: ReadonlyMap<string, Declarable>;
+  /**
+   * The directory this build discovered its source in (the path handed to
+   * `build()`, which `--src` or `sourceDir` chose), absolute. A contributor
+   * that reads files beside the typed source (the sql lexicon's `.sql`
+   * files) reads them here, so it sees the tree discovery saw. Optional: a
+   * caller that is not a build (the graph paths) omits it, and a hook then
+   * falls back to `sourceDir` in `config`, resolved against `projectRoot`.
+   */
+  sourceDir?: string;
 }
 
 /**
@@ -1003,7 +1012,7 @@ export interface BuildRootContribution {
  * the argument is still assignable, which is what every pre-#1828 hook does.
  */
 export type BuildRootContributor = (
-  ctx: Pick<BuildRootContext, "entities">,
+  ctx: Pick<BuildRootContext, "entities" | "sourceDir">,
 ) => Promise<BuildRootContribution>;
 
 /**

package/src/lifecycle/gate-ledger.ts

@@ -222,6 +222,13 @@ export interface GateResolutionRecord {
    * verifies. Absent on an unsigned approval.
    */
   seal?: GateApprovalSeal;
+  /**
+   * The forge review this approval came from (#3684): a wave whose approval
+   * mode is `pr-review` writes it when the merged pull request's head was
+   * approved by a writer other than its author and planned this digest.
+   * `resolvedBy` is the first of `approvers`.
+   */
+  review?: { pr: number; head: string; approvers: string[] };
   /**
    * The answer record that passed the gate, on a gate that asks a decision
    * point (#3170). The run writes this resolution itself when the point's

package/src/op/gate-review.test.ts

@@ -0,0 +1,225 @@
+import { afterAll, describe, expect, test } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { ForgeFetch } from "../pr-forge";
+import { waveSetDigest } from "../gated-waves";
+import { sealGateApproval } from "../workspace/trust/seal";
+import { TestRepo, hasSshKeygen } from "../workspace/trust/test-repo";
+import type { GateResolutionRecord } from "../lifecycle/gate-ledger";
+import { memoryGateLedgerPort } from "./gate";
+import { githubReviews, forgejoReviews, gitlabReviews, type MergedReview, type ReviewSource } from "./gate-review";
+import type { OpWavesSpec } from "./op-waves";
+import { recordOpWaveHeadPlans, runOpWave, type OpWaveExec, type OpWaveShowAtBase } from "./op-waves-run";
+
+const HEAD = "h".repeat(40);
+const MERGE = "m".repeat(40);
+const digest = (n: string) => `sha256:${n.repeat(64)}`;
+
+/** A fake forge answering GETs by path. */
+function forge(routes: Record<string, unknown>): ForgeFetch {
+  return async (url) => {
+    const { pathname } = new URL(url);
+    if (!(pathname in routes)) return { ok: false, status: 404, text: async () => "not found" };
+    return { ok: true, status: 200, text: async () => JSON.stringify(routes[pathname]) };
+  };
+}
+
+const opts = (fetch: ForgeFetch, apiBase = "https://api.github.com") => ({ apiBase, repo: "acme/db", token: "t", host: "github.com", fetch });
+
+describe("the merged pull request's review", () => {
+  const pr = { number: 7, user: { login: "carol" }, head: { sha: HEAD }, html_url: "https://github.com/acme/db/pull/7" };
+  const base = {
+    "/repos/acme/db/commits/mmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmm/pulls": [{ number: 7, merged_at: "x", merge_commit_sha: MERGE }],
+    "/repos/acme/db/pulls/7": pr,
+    "/repos/acme/db/collaborators/alice/permission": { permission: "write", role_name: "write" },
+    "/repos/acme/db/collaborators/dave/permission": { permission: "read", role_name: "read" },
+  };
+
+  test("GitHub: the author's own approval never counts", async () => {
+    const review = await githubReviews(opts(forge({ ...base, "/repos/acme/db/pulls/7/reviews": [{ user: { login: "carol" }, state: "APPROVED", commit_id: HEAD }] }))).mergedReview(MERGE);
+    expect(review).toMatchObject({ pr: 7, author: "github:carol", head: HEAD, approvers: [] });
+    expect(review!.refused[0]).toMatch(/github:carol is the author/);
+  });
+
+  test("GitHub: a writer's approval of the head counts; a reader's, or one of an older commit, does not", async () => {
+    const review = await githubReviews(
+      opts(
+        forge({
+          ...base,
+          "/repos/acme/db/pulls/7/reviews": [
+            { user: { login: "alice" }, state: "APPROVED", commit_id: "old" },
+            { user: { login: "alice" }, state: "APPROVED", commit_id: HEAD },
+            { user: { login: "dave" }, state: "APPROVED", commit_id: HEAD },
+          ],
+        }),
+      ),
+    ).mergedReview(MERGE);
+    expect(review!.approvers).toEqual(["github:alice"]);
+    expect(review!.refused).toEqual(["github:dave approved without write access"]);
+  });
+
+  test("GitHub: a writer who requests changes holds the review back", async () => {
+    const review = await githubReviews(
+      opts(
+        forge({
+          ...base,
+          "/repos/acme/db/collaborators/bob/permission": { permission: "write", role_name: "maintain" },
+          "/repos/acme/db/pulls/7/reviews": [
+            { user: { login: "alice" }, state: "APPROVED", commit_id: HEAD },
+            { user: { login: "bob" }, state: "CHANGES_REQUESTED", commit_id: HEAD },
+          ],
+        }),
+      ),
+    ).mergedReview(MERGE);
+    expect(review!.approvers).toEqual([]);
+  });
+
+  test("Forgejo: only an official review that is neither stale nor dismissed counts", async () => {
+    const review = await forgejoReviews(
+      opts(
+        forge({
+          "/api/v1/repos/acme/db/commits/mmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmm/pull": { number: 7 },
+          "/api/v1/repos/acme/db/pulls/7": pr,
+          "/api/v1/repos/acme/db/pulls/7/reviews": [
+            { user: { login: "alice" }, state: "APPROVED", commit_id: HEAD, official: true },
+            { user: { login: "dave" }, state: "APPROVED", commit_id: HEAD, official: false },
+            { user: { login: "erin" }, state: "APPROVED", commit_id: HEAD, official: true, stale: true },
+          ],
+        }),
+        "https://code.example.org/api/v1",
+      ),
+    ).mergedReview(MERGE);
+    expect(review!.approvers).toEqual(["forgejo@github.com:alice"]);
+    expect(review!.refused).toHaveLength(2);
+  });
+
+  test("GitLab: an approval counts only where a push removes approvals, and never the author's", async () => {
+    const routes = {
+      "/api/v4/projects/7/repository/commits/mmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmmm/merge_requests": [{ iid: 3, state: "merged", merge_commit_sha: MERGE, sha: HEAD, author: { username: "carol" } }],
+      "/api/v4/projects/7/merge_requests/3/approvals": { approved_by: [{ user: { id: 1, username: "carol" } }, { user: { id: 2, username: "alice" } }] },
+      "/api/v4/projects/7/members/all/2": { access_level: 30 },
+    };
+    const keeps = await gitlabReviews({ ...opts(forge({ ...routes, "/api/v4/projects/7/approvals": { reset_approvals_on_push: false } }), "https://gl/api/v4"), repo: "7", host: "gitlab.com" }).mergedReview(MERGE);
+    expect(keeps!.approvers).toEqual([]);
+    const resets = await gitlabReviews({ ...opts(forge({ ...routes, "/api/v4/projects/7/approvals": { reset_approvals_on_push: true } }), "https://gl/api/v4"), repo: "7", host: "gitlab.com" }).mergedReview(MERGE);
+    expect(resets).toMatchObject({ pr: 3, head: HEAD, approvers: ["gitlab:alice"] });
+    expect(resets!.refused[0]).toMatch(/gitlab:carol is the author/);
+  });
+});
+
+const spec = (approval: "pr-review" | "sealed"): OpWavesSpec => ({
+  name: "migrations",
+  op: "migrate",
+  plan: ["tool", "plan", "{target}", "--out", "{plan}"],
+  apply: ["tool", "apply", "{target}"],
+  waves: [{ name: "prod", runs: [{ target: "prod" }], approval }],
+});
+
+function harness(plan: string, dir?: string) {
+  const cwd = dir ?? mkdtempSync(join(tmpdir(), "gate-review-"));
+  const applied: string[] = [];
+  const exec: OpWaveExec = (argv, at) => {
+    if (argv[1] === "plan") {
+      mkdirSync(join(at, argv[4]!, ".."), { recursive: true });
+      writeFileSync(join(at, argv[4]!), JSON.stringify({ planDigest: plan }));
+    }
+    if (argv[1] === "apply") applied.push(argv[2]!);
+    return 0;
+  };
+  return { cwd, exec, applied };
+}
+
+describe("a pr-review wave (#3684)", () => {
+  const set = (plan: string) => waveSetDigest([{ member: "prod", planDigest: plan }]);
+  const show: OpWaveShowAtBase = () => ({ sha: "b".repeat(40), text: JSON.stringify(spec("pr-review")) });
+  const reviewed = (approvers: string[], refused: string[] = []): ReviewSource => ({
+    kind: "github",
+    async mergedReview(): Promise<MergedReview> {
+      return { pr: 7, author: "github:carol", head: HEAD, approvers, refused, url: "https://github.com/acme/db/pull/7" };
+    },
+  });
+  const plans = (d: string) => async () => ({ version: 1 as const, name: "migrations", head: HEAD, timestamp: "t", waves: [{ wave: 1, name: "prod", digest: d }] });
+
+  test("the author's own review applies nothing", async () => {
+    const h = harness(digest("a"));
+    const result = await runOpWave({
+      spec: spec("pr-review"), specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show, head: MERGE,
+      gates: memoryGateLedgerPort(), reviews: reviewed([], ["github:carol is the author, whose own review never counts"]), headPlans: plans(set(digest("a"))),
+    });
+    expect(result).toMatchObject({ exitCode: 3, applied: [], decision: { approval: "pr-review", status: "waiting" } });
+    expect(result.decision!.review!.reason).toMatch(/is the author/);
+    expect(h.applied).toEqual([]);
+  });
+
+  test("a writer's review of the head approves the digest the head planned, and the ledger records it", async () => {
+    const h = harness(digest("a"));
+    const gates = memoryGateLedgerPort();
+    const result = await runOpWave({
+      spec: spec("pr-review"), specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show, head: MERGE,
+      gates, reviews: reviewed(["github:alice"]), headPlans: plans(set(digest("a"))),
+    });
+    expect(result).toMatchObject({ exitCode: 0, applied: ["prod"], decision: { status: "approved", via: "pr-review", approvedBy: "github:alice" } });
+    expect(gates.resolved[0]).toMatchObject({ resolvedBy: "github:alice", planDigest: set(digest("a")), review: { pr: 7, head: HEAD, approvers: ["github:alice"] } });
+  });
+
+  test("a plan that moved after the review waits for a new approval", async () => {
+    const h = harness(digest("b"));
+    const result = await runOpWave({
+      spec: spec("pr-review"), specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show, head: MERGE,
+      gates: memoryGateLedgerPort(), reviews: reviewed(["github:alice"]), headPlans: plans(set(digest("a"))),
+    });
+    expect(result.exitCode).toBe(3);
+    expect(result.decision!.review!.reason).toMatch(/plan moved after the review/);
+  });
+
+  test("--record-plans records each wave's digest at the head", async () => {
+    const h = harness(digest("a"));
+    let written: unknown;
+    const recorded = await recordOpWaveHeadPlans({ spec: spec("pr-review"), cwd: h.cwd, exec: h.exec, head: HEAD, now: "t", write: async (p) => void (written = p) });
+    expect(recorded.waves).toEqual([{ wave: 1, name: "prod", digest: set(digest("a")) }]);
+    expect(written).toEqual(recorded);
+  });
+});
+
+describe.skipIf(!hasSshKeygen)("a sealed wave (#3684)", () => {
+  const repo = new TestRepo("3684-sealed");
+  const alice = repo.key("alice");
+  const mallory = repo.key("mallory");
+  afterAll(() => rmSync(join(repo.dir, ".."), { recursive: true, force: true }));
+
+  // Base: the spec and a signers file listing alice. The applied change adds mallory's key.
+  writeFileSync(join(repo.dir, "waves.json"), JSON.stringify(spec("sealed")));
+  mkdirSync(join(repo.dir, ".chant"), { recursive: true });
+  writeFileSync(join(repo.dir, ".chant/allowed_signers"), `alice ${alice.pub}\n`);
+  repo.git(["add", "-A"]);
+  repo.git(["commit", "-q", "-m", "base"]);
+  writeFileSync(join(repo.dir, ".chant/allowed_signers"), `alice ${alice.pub}\nmallory ${mallory.pub}\n`);
+  repo.git(["add", "-A"]);
+  repo.git(["commit", "-q", "-m", "the change adds a signer"]);
+
+  const plan = digest("a");
+  const set = waveSetDigest([{ member: "prod", planDigest: plan }]);
+  const approval = (by: string, keyFile?: string): GateResolutionRecord => {
+    const a = { op: "migrations", gate: "migrations-wave-1", resolvedBy: by, timestamp: "2026-10-10T00:00:00Z", planDigest: set };
+    return { version: 1, ...a, ...(keyFile ? { seal: sealGateApproval(keyFile, a) } : {}) };
+  };
+  const run = (resolutions: GateResolutionRecord[]) => {
+    const h = harness(plan, repo.dir);
+    return runOpWave({ spec: spec("sealed"), specFile: "waves.json", wave: 1, cwd: repo.dir, exec: h.exec, gates: memoryGateLedgerPort({ resolutions }), now: "2026-10-10T01:00:00Z" });
+  };
+
+  test("an unsigned approval applies nothing, and the hint asks for --sign", async () => {
+    const result = await run([approval("alice")]);
+    expect(result).toMatchObject({ exitCode: 3, decision: { approval: "sealed", status: "waiting" } });
+    expect(result.decision!.approve).toMatch(/--sign$/);
+  });
+
+  test("a seal by a key the change itself added applies nothing", async () => {
+    expect((await run([approval("mallory", mallory.file)])).exitCode).toBe(3);
+  });
+
+  test("a seal by a signer listed at base applies the wave", async () => {
+    expect(await run([approval("alice", alice.file)])).toMatchObject({ exitCode: 0, applied: ["prod"], decision: { status: "approved", approvedBy: "alice" } });
+  });
+});