@intentius/chant-lexicon-github 0.124.54 → 0.124.56

package/src/components/generate-pr-pipeline.comment-preview.test.ts

@@ -0,0 +1,64 @@
+/**
+ * `/<product> <plan word>` (#4620): with `previewComment` a job previews the
+ * pull request's head again with a read token, and the job after it posts
+ * the note from the target branch's commit, as plan and plan-note do.
+ */
+
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { generateGithubPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [
+  { name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] },
+];
+
+const WORDS = { product: "plywood", stages: { plan: "preview", apply: "up" }, commands: { preview: "plan" as const }, bin: "npx --no-install plywood" };
+
+interface Step { id?: string; name?: string; uses?: string; run?: string; env?: Record<string, string>; with?: Record<string, unknown> }
+interface Job { if?: string; needs?: string[]; permissions: Record<string, string>; outputs?: Record<string, string>; steps: Step[] }
+type Doc = { on: Record<string, unknown>; jobs: Record<string, Job> };
+
+const gen = (prLoop: Record<string, unknown>) => parseYAML(generateGithubPipeline(ESTATE, { env: "prod", prLoop }).yaml) as Doc;
+
+describe("the GitHub workflow's preview comment", () => {
+  const doc = gen({ previewComment: true, words: WORDS });
+  const preview = doc.jobs["comment-preview"]!;
+  const note = doc.jobs["comment-preview-note"]!;
+
+  test("started by issue_comment with the plan word, from a commenter who can write", () => {
+    expect(doc.on.issue_comment).toEqual({ types: ["created"] });
+    expect(preview.if).toContain("github.event_name == 'issue_comment'");
+    expect(preview.if).toContain("startsWith(github.event.comment.body, '/plywood preview')");
+    expect(preview.if).toContain("github.event.comment.author_association");
+  });
+
+  test("the preview job holds a read token only, and drops it before the change's code runs", () => {
+    expect(preview.permissions).toEqual({ contents: "read" });
+    const checkout = preview.steps[0]!;
+    expect(checkout.id).toBe("head");
+    expect(checkout.env!.CHANT_PREVIEW_REF).toBe("refs/pull/${{ github.event.issue.number }}/head");
+    expect(checkout.run).toContain('echo "head=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"');
+    const plan = preview.steps.at(-1)!;
+    expect(plan.run).toContain('BASE_SHA="$(git rev-parse --verify "refs/remotes/origin/main^{commit}")"');
+    expect(plan.run).toContain("npx --no-install plywood ci run plan");
+    expect(plan.env!.PR_NUMBER).toBe("${{ github.event.issue.number }}");
+    expect(plan.env!.GITHUB_TOKEN).toBeUndefined();
+    expect(preview.outputs!.head).toBe("${{ steps.head.outputs.head }}");
+  });
+
+  test("the note job posts from the target branch's commit, for the head the preview job read", () => {
+    expect(note.needs).toEqual(["comment-preview"]);
+    expect(note.permissions).toEqual({ actions: "read", contents: "read", "pull-requests": "write", statuses: "write" });
+    const post = note.steps.at(-1)!;
+    expect(post.run).toBe('npx --no-install plywood components pr-post --pr "$PR_NUMBER" --head "$HEAD_SHA" --env prod --output .chant/pr --forge github --result "$PLAN_RESULT"');
+    expect(post.env!.HEAD_SHA).toBe("${{ needs.comment-preview.outputs.head }}");
+    expect(note.steps.some((s) => s.run?.includes("needs.comment-preview.outputs"))).toBe(true);
+  });
+
+  test("no preview job without previewComment", () => {
+    const plain = gen({ words: WORDS });
+    expect(plain.jobs["comment-preview"]).toBeUndefined();
+    expect(plain.on.issue_comment).toBeUndefined();
+  });
+});

package/src/components/generate-pr-pipeline.comment-targets.test.ts

@@ -0,0 +1,24 @@
+/**
+ * The preview comment's --target on GitHub (#4626): the preview step runs
+ * `pr-plan --comment-targets` with the comment body in CHANT_PREVIEW_COMMENT,
+ * and the body never appears in the shell line. Written for the
+ * ci-products post-merge pass.
+ */
+import { expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { generateGithubPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [{ name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] }];
+const WORDS = { product: "plywood", stages: { plan: "preview", apply: "up" }, commands: { preview: "plan" as const }, bin: "npx --no-install plywood" };
+
+test("the preview step reads the comment from a variable (#4626)", () => {
+  const doc = parseYAML(generateGithubPipeline(ESTATE, { env: "prod", prLoop: { previewComment: true, words: WORDS } }).yaml) as { jobs: Record<string, { steps: Array<{ name?: string; run?: string; env?: Record<string, string> }> }> };
+  const step = doc.jobs["comment-preview"]!.steps.find((s) => s.name === "Preview the members this pull request reaches")!;
+  expect(step.run).toContain("npx --no-install plywood ci run plan");
+  expect(step.run).toContain("--comment-targets");
+  expect(step.env!.CHANT_PREVIEW_COMMENT).toBe("${{ github.event.comment.body }}");
+  expect(step.run).not.toContain("comment.body");
+  const plan = doc.jobs.plan!.steps.find((s) => s.name === "Plan the members this pull request reaches")!;
+  expect(plan.run).not.toContain("--comment-targets");
+});

package/src/components/generate-pr-pipeline.control.test.ts

@@ -0,0 +1,94 @@
+/**
+ * #4568: with a control repo, the GitHub and Forgejo pull-request workflows
+ * add a `control-dispatch` job after the last apply on merge, which maps the
+ * product's secret into CHANT_CONTROL_TOKEN for its one step. The control
+ * repo's own workflow runs the member's dependents. Generated YAML only;
+ * the request itself is tested against fake forges in
+ * packages/core/src/control/control.test.ts.
+ */
+
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { resolveControlTarget } from "@intentius/chant/control/dispatch";
+import { generateGithubPipeline } from "./generate-pipeline";
+import { generateControlPipeline } from "./control-pipeline";
+
+const root = (name: string, dependsOn: string[] = []): DriverComponent => ({ name, dependsOn, deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: name }] }] });
+const ESTATE: DriverComponent[] = [root("net"), root("app", ["net"])];
+const control = { target: resolveControlTarget({ repo: "github.com/acme/control", op: "deploy", tokenSecret: "PLYWOOD_CONTROL_TOKEN" }, "network") };
+
+interface Job {
+  needs?: string[];
+  if?: string;
+  permissions?: Record<string, string>;
+  steps: Array<{ name?: string; run?: string; env?: Record<string, string> }>;
+}
+
+for (const forge of ["github", "forgejo"] as const) {
+  describe(`the ${forge} workflow's control dispatch (#4568)`, () => {
+    test("one job after the apply, reading the dispatch token from the product's secret", () => {
+      const { yaml } = generateGithubPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true, forge, control, words: { product: "plywood" } } });
+      const doc = parseYAML(yaml) as { jobs: Record<string, Job> };
+      const job = doc.jobs["control-dispatch"]!;
+      expect(job.needs).toEqual(["apply"]);
+      expect(job.permissions).toEqual({ contents: "read" });
+      expect(job.steps[0]!.env!.CHANT_CONTROL_TOKEN).toBe("${{ secrets.PLYWOOD_CONTROL_TOKEN }}");
+      expect(job.steps[0]!.run).toContain(forge === "github" ? "plywood-applied" : "/dispatches");
+      // No other job holds the dispatch token.
+      for (const [name, other] of Object.entries(doc.jobs)) if (name !== "control-dispatch") expect(JSON.stringify(other)).not.toContain("PLYWOOD_CONTROL_TOKEN");
+    });
+
+    test("with a gate per wave, the job follows the last wave and reads the commit it applied", () => {
+      const { yaml } = generateGithubPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true, forge, control }, gatedWaves: { gate: "release" } });
+      const doc = parseYAML(yaml) as { jobs: Record<string, Job> };
+      const job = doc.jobs["control-dispatch"]!;
+      expect(job.needs).toEqual(["apply-wave-2"]);
+      expect(job.steps[0]!.env!.CHANT_CONTROL_SHA).toBe("${{ needs.apply-wave-2.outputs.green-sha }}");
+    });
+
+    test("no apply on merge, no dispatch", () => {
+      const { yaml } = generateGithubPipeline(ESTATE, { env: "prod", prLoop: { forge, control } });
+      expect((parseYAML(yaml) as { jobs: Record<string, Job> }).jobs["control-dispatch"]).toBeUndefined();
+    });
+  });
+}
+
+describe("the control repo's workflow on GitHub (#4568)", () => {
+  test("a repository_dispatch of the product's event and a manual dispatch run the dependents", () => {
+    const file = generateControlPipeline({ words: { product: "terragucci" } });
+    expect(file.path).toBe(".github/workflows/terragucci-dependents.yml");
+    const doc = parseYAML(file.content) as { on: Record<string, any>; jobs: Record<string, Job> };
+    expect(doc.on.repository_dispatch.types).toEqual(["terragucci-applied"]);
+    // #4617: the outcome an op waves dispatch carries is an input too.
+    expect(Object.keys(doc.on.workflow_dispatch.inputs)).toEqual(["member", "op", "sha", "outcome"]);
+    expect(doc.jobs.dependents!.steps[1]!.run).toContain("workspace run --dependents-of");
+  });
+});
+
+// #4619: the note job reads the control repo, read-only, so the note marks the cross-stack edges.
+for (const forge of ["github", "forgejo"] as const) {
+  describe(`the ${forge} plan-note job's read of the control repo (#4619)`, () => {
+    const withRead = { target: resolveControlTarget({ repo: "github.com/acme/control", op: "deploy", tokenSecret: "PLYWOOD_CONTROL_TOKEN", readTokenSecret: "PLYWOOD_CONTROL_READ" }, "network") };
+
+    test("fetches the control repo's chant/lifecycle with the read secret before it posts", () => {
+      const { yaml } = generateGithubPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true, forge, control: withRead, words: { product: "plywood" } } });
+      const doc = parseYAML(yaml) as { jobs: Record<string, Job> };
+      const steps = doc.jobs["plan-note"]!.steps;
+      const read = steps.findIndex((s) => s.run?.includes("refs/heads/chant/lifecycle"));
+      const post = steps.findIndex((s) => s.run?.includes("components pr-post"));
+      expect(read).toBeGreaterThan(-1);
+      expect(read).toBe(post - 1);
+      expect(steps[read]!.env).toEqual({ CHANT_CONTROL_READ_TOKEN: "${{ secrets.PLYWOOD_CONTROL_READ || github.token }}" });
+      expect(steps[read]!.run).toContain('echo "CHANT_CONTROL_DIR=$chant_control_dir" >>"$GITHUB_ENV"');
+      // The plan job runs the change's code and never holds the read secret; no job but the dispatch holds the dispatch token.
+      expect(JSON.stringify(doc.jobs.plan)).not.toContain("PLYWOOD_CONTROL_READ");
+      expect(JSON.stringify(doc.jobs["plan-note"])).not.toContain("PLYWOOD_CONTROL_TOKEN");
+    });
+
+    test("without a control repo the note job reads none", () => {
+      const { yaml } = generateGithubPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true, forge } });
+      expect(yaml).not.toContain("CHANT_CONTROL_DIR");
+    });
+  });
+}

package/src/components/generate-pr-pipeline.pulumi-identity.test.ts

@@ -0,0 +1,43 @@
+/**
+ * #4549: with a Pulumi Cloud identity, the GitHub and Forgejo pull-request
+ * workflows trade the job's OIDC token for a preview token in the plan and
+ * record jobs and an up token in the apply job. No job reads a Pulumi token
+ * from the forge's secrets, and the plan job names no up token. Generated
+ * YAML only; the trade itself is tested against the fake exchange in
+ * packages/core/src/ci-identity-pulumi.test.ts.
+ */
+
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { resolveCloudIdentity, TRADE_SPEC_ENV } from "@intentius/chant/ci-identity";
+import { generateGithubPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [{ name: "app", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "app" }] }] }];
+
+const IDENTITY = resolveCloudIdentity({ pulumi: { organization: "acme", rules: [{ plan: "team:preview", apply: "team:deploy" }] } }, "prod")!;
+
+interface Job {
+  permissions?: Record<string, string>;
+  steps: Array<{ name?: string; run?: string; env?: Record<string, string> }>;
+}
+
+for (const forge of ["github", "forgejo"] as const) {
+  describe(`the ${forge} workflow's Pulumi Cloud tokens (#4549)`, () => {
+    const { yaml } = generateGithubPipeline(ESTATE, { env: "prod", image: "example/ci:1", prLoop: { applyOnMerge: true, forge, identity: IDENTITY } });
+    const doc = parseYAML(yaml) as { jobs: Record<string, Job> };
+    const tradeOf = (job: Job) => JSON.parse(job.steps[0]!.env![TRADE_SPEC_ENV]!) as Record<string, unknown>;
+
+    test("the plan and record jobs trade for the preview token first, the apply job for the up token", () => {
+      expect(tradeOf(doc.jobs.plan!)).toEqual({ pulumi: { token: "team:preview", organization: "acme", audience: "urn:pulumi:org:acme" } });
+      expect(tradeOf(doc.jobs.record!)).toEqual(IDENTITY.plan);
+      expect(tradeOf(doc.jobs.apply!)).toEqual(IDENTITY.apply);
+      for (const name of ["plan", "record", "apply"]) expect(doc.jobs[name]!.permissions!["id-token"], name).toBe("write");
+    });
+
+    test("the plan job names no up token, and no job reads a Pulumi token from the forge's secrets", () => {
+      expect(JSON.stringify(doc.jobs.plan)).not.toContain("team:deploy");
+      expect(yaml).not.toMatch(/secrets\.PULUMI_ACCESS_TOKEN/);
+    });
+  });
+}

package/src/components/generate-pr-pipeline.respond.test.ts

@@ -0,0 +1,47 @@
+/**
+ * The pull request loop's responses, description check and merge on GitHub
+ * (#4629, #4636), as `chant build --pr-loop --respond --decide-backend
+ * --decide-model --merge auto` sets them: the note job asks the decide
+ * service, and the apply job carries CHANT_RESPOND and the merge.
+ */
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { generateGithubPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [{ name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] }];
+
+type Step = { name?: string; run?: string; env?: Record<string, string> };
+type Doc = { jobs: Record<string, { steps: Step[] }> };
+const gen = (prLoop: Record<string, unknown>) => parseYAML(generateGithubPipeline(ESTATE, { env: "prod", prLoop }).yaml) as Doc;
+
+describe("responses and the merge on GitHub (#4629, #4636)", () => {
+  const doc = gen({
+    applyBeforeMerge: true,
+    applyMerge: { tokenEnv: "CHANT_MERGE_TOKEN", method: "squash" },
+    respond: { "wave-refused": "off", description: "check" },
+    decide: { backend: "review", model: "m-1" },
+  });
+
+  test("the note job carries the responses and asks the decide service", () => {
+    const post = doc.jobs["plan-note"]!.steps.at(-1)!;
+    expect(post.run).toMatch(/--decide-backend "review" --decide-model "m-1"$/);
+    expect(post.env!.CHANT_RESPOND).toBe("wave-refused=off,description=check");
+  });
+
+  test("the apply job carries the responses and the merge", () => {
+    const steps = Object.values(doc.jobs).flatMap((j) => j.steps);
+    const apply = steps.find((s) => s.run?.includes("--apply-before-merge"))!;
+    expect(apply.run).toContain("--merge auto --merge-token-env CHANT_MERGE_TOKEN --merge-method squash");
+    expect(apply.env!.CHANT_RESPOND).toBe("wave-refused=off,description=check");
+    expect(apply.env!.CHANT_MERGE_TOKEN).toBe("${{ secrets.CHANT_MERGE_TOKEN }}");
+  });
+
+  test("without them, neither job changes", () => {
+    const plain = gen({ applyBeforeMerge: true });
+    const post = plain.jobs["plan-note"]!.steps.at(-1)!;
+    expect(post.run).not.toContain("--decide-backend");
+    expect(post.env!.CHANT_RESPOND).toBeUndefined();
+    expect(JSON.stringify(plain)).not.toContain("--merge auto");
+  });
+});

package/src/components/generate-pr-pipeline.runners.test.ts

@@ -0,0 +1,61 @@
+/**
+ * The pull request loop's runners, variables and passed secrets on GitHub
+ * (#4625): every job on its stage's runner, and the jobs that plan or apply
+ * with the variables and the secrets mapped from the repository's. Written
+ * for the ci-products post-merge pass.
+ */
+
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { generateGithubPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [{ name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] }];
+const WORDS = { product: "plywood", stages: { plan: "preview", apply: "up" }, commands: { preview: "plan" as const, lock: "lock" as const, unlock: "unlock" as const } };
+
+type Step = { name?: string; run?: string; env?: Record<string, string> };
+type Doc = { jobs: Record<string, { "runs-on": unknown; steps: Step[] }> };
+
+const doc = parseYAML(
+  generateGithubPipeline(ESTATE, {
+    env: "prod",
+    prLoop: {
+      words: WORDS,
+      previewComment: true,
+      locks: "plan",
+      applyOnMerge: true,
+      runners: { plan: ["self-hosted", "big"], apply: "deployer", default: "small" },
+      variables: { REGION: "eu-west-1" },
+      secrets: { DB_PASSWORD: "PROD_DB_PASSWORD" },
+      parallelism: 2,
+    },
+  }).yaml,
+) as Doc;
+
+describe("the GitHub pull request loop's runners and variables (#4625)", () => {
+  test("every job runs on its stage's runner", () => {
+    expect(doc.jobs.plan!["runs-on"]).toEqual(["self-hosted", "big"]);
+    expect(doc.jobs["comment-preview"]!["runs-on"]).toEqual(["self-hosted", "big"]);
+    expect(doc.jobs.apply!["runs-on"]).toBe("deployer");
+    expect(doc.jobs.record!["runs-on"]).toBe("deployer");
+    for (const name of ["plan-note", "comment-preview-note", "lock", "unlock", "comment-lock", "comment-unlock"]) expect(doc.jobs[name]!["runs-on"], name).toBe("small");
+  });
+
+  test("the plan step gets the variable and the secret, and still drops the forge tokens first", () => {
+    const step = doc.jobs.plan!.steps.find((s) => s.name === "Plan the members this pull request reaches")!;
+    expect(step.env).toMatchObject({ REGION: "eu-west-1", DB_PASSWORD: "${{ secrets.PROD_DB_PASSWORD }}" });
+    expect(step.env).not.toHaveProperty("GITHUB_TOKEN");
+    expect(step.run!.split("\n")[0]).toContain("unset");
+    expect(step.run).toContain("--parallelism 2");
+  });
+
+  test("the apply step gets them too", () => {
+    const step = doc.jobs.apply!.steps.find((s) => s.run?.includes("ci run apply"))!;
+    expect(step.env).toMatchObject({ REGION: "eu-west-1", DB_PASSWORD: "${{ secrets.PROD_DB_PASSWORD }}" });
+  });
+
+  test("without runners every job keeps the forge's default", () => {
+    const plain = parseYAML(generateGithubPipeline(ESTATE, { env: "prod", prLoop: {} }).yaml) as Doc;
+    expect(plain.jobs.plan!["runs-on"]).toBe("ubuntu-latest");
+  });
+});

package/src/components/generate-pr-pipeline.stale-notes.test.ts

@@ -0,0 +1,42 @@
+/**
+ * Stale marking on GitHub (#4628): with staleNotes the note job passes the
+ * target branch's commit, and a stale-notes job on a push to the branch
+ * runs `pr-post --stale` at the pushed commit with a token that may edit the
+ * notes and set the statuses. Written for the ci-products post-merge pass.
+ */
+import { describe, expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { generateGithubPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [{ name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] }];
+const WORDS = { product: "plywood", stages: { plan: "preview", apply: "up" }, commands: { preview: "plan" as const }, bin: "npx --no-install plywood" };
+
+type Step = { name?: string; run?: string; env?: Record<string, string>; uses?: string };
+type Doc = { jobs: Record<string, { if?: string; permissions?: Record<string, string>; steps: Step[] }> };
+const gen = (prLoop: Record<string, unknown>) => parseYAML(generateGithubPipeline(ESTATE, { env: "prod", prLoop }).yaml) as Doc;
+
+describe("stale notes on GitHub (#4628)", () => {
+  const doc = gen({ words: WORDS, staleNotes: true, previewComment: true });
+
+  test("the note job passes the target branch's commit", () => {
+    const post = doc.jobs["plan-note"]!.steps.at(-1)!;
+    expect(post.run).toContain('--tip "$TIP_SHA"');
+    expect(post.env!.TIP_SHA).toBe("${{ github.event.pull_request.base.sha }}");
+  });
+
+  test("a stale-notes job on a push marks the open notes stale, naming the preview comment", () => {
+    const job = doc.jobs["stale-notes"]!;
+    expect(job.if).toBe("github.event_name == 'push' && startsWith(github.ref, 'refs/heads/')");
+    expect(job.permissions).toEqual({ contents: "read", "pull-requests": "write", statuses: "write" });
+    const step = job.steps.at(-1)!;
+    expect(step.run).toBe('npx --no-install plywood components pr-post --stale --tip "$TIP_SHA" --env prod --forge github --preview-comment');
+    expect(step.env).toEqual({ TIP_SHA: "${{ github.sha }}", GITHUB_TOKEN: "${{ github.token }}" });
+  });
+
+  test("without staleNotes, no job and no tip", () => {
+    const plain = gen({ words: WORDS });
+    expect(plain.jobs["stale-notes"]).toBeUndefined();
+    expect(plain.jobs["plan-note"]!.steps.at(-1)!.run).not.toContain("--tip");
+  });
+});