@intentius/chant-lexicon-gitlab 0.124.54 → 0.124.56

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

@@ -0,0 +1,81 @@
+/**
+ * #4568: with a control repo, the GitLab merge-request pipeline adds a
+ * `control-dispatch` job after the last apply on merge, and the plan job
+ * unsets the control repo's token variables with the forge tokens, since a
+ * CI/CD variable reaches every job. The control repo's own pipeline runs on
+ * a trigger. Generated YAML only; the request 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 { generateGitlabPipeline } 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: "gitlab.com/acme/control", op: "deploy", tokenSecret: "TERRAGUCCI_CONTROL_TOKEN" }, "network") };
+
+interface Job {
+  stage: string;
+  needs?: string[];
+  rules: Array<{ if: string }>;
+  script: string[];
+  resource_group?: string;
+}
+
+describe("the GitLab pipeline's control dispatch (#4568)", () => {
+  test("one job after the apply, and the plan job drops the token variables", () => {
+    const { yaml } = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true, control, words: { product: "terragucci" } } });
+    const doc = parseYAML(yaml) as Record<string, Job> & { stages: string[] };
+    const job = doc["control-dispatch"]!;
+    expect(job.needs).toEqual(["apply"]);
+    expect(doc.stages.at(-1)).toBe("control-dispatch");
+    expect(job.script[0]).toBe('export CHANT_CONTROL_SHA="$CI_COMMIT_SHA"');
+    expect(job.script[1]).toContain('CHANT_CONTROL_TOKEN="${TERRAGUCCI_CONTROL_TOKEN:-}"');
+    expect(job.script[1]).toContain("/trigger/pipeline");
+    expect(doc.plan!.script.some((l) => l.startsWith("unset ") && l.includes("TERRAGUCCI_CONTROL_TOKEN") && l.includes("CHANT_CONTROL_TOKEN"))).toBe(true);
+  });
+
+  test("with a gate per wave, the job follows the last wave and reads its GREEN_SHA", () => {
+    const { yaml } = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true, control }, gatedWaves: { gate: "release" } });
+    const doc = parseYAML(yaml) as Record<string, Job>;
+    expect(doc["control-dispatch"]!.needs).toEqual(["apply-wave-2"]);
+    expect(doc["control-dispatch"]!.script[0]).toBe('export CHANT_CONTROL_SHA="$GREEN_SHA"');
+  });
+});
+
+describe("the control repo's pipeline on GitLab (#4568)", () => {
+  test("a trigger with the member and Op runs the dependents, one member at a time", () => {
+    const file = generateControlPipeline({ words: { product: "terragucci" } });
+    expect(file.path).toBe(".gitlab/terragucci-dependents.yml");
+    const doc = parseYAML(file.content) as Record<string, Job>;
+    expect(doc.dependents!.rules[0]!.if).toBe('$CI_PIPELINE_SOURCE == "trigger" && $CHANT_CONTROL_MEMBER && $CHANT_CONTROL_OP');
+    expect(doc.dependents!.resource_group).toBe("terragucci-dependents-$CHANT_CONTROL_MEMBER");
+    expect(doc.dependents!.script[0]).toContain("workspace run --dependents-of");
+  });
+});
+
+// #4619: the note job reads the control repo, read-only, so the note marks the cross-stack edges.
+describe("the GitLab plan-note job's read of the control repo (#4619)", () => {
+  test("fetches the control repo's chant/lifecycle before it posts, and exports CHANT_CONTROL_DIR", () => {
+    const { yaml } = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true, control, words: { product: "terragucci" } } });
+    const doc = parseYAML(yaml) as Record<string, Job>;
+    const script = doc["plan-note"]!.script;
+    const read = script.findIndex((l) => l.includes("refs/heads/chant/lifecycle"));
+    expect(read).toBeGreaterThan(-1);
+    expect(script[read + 1]).toContain("components pr-post");
+    expect(script[read]).toContain('CHANT_CONTROL_READ_TOKEN="${CHANT_CONTROL_READ_TOKEN:-}"');
+    expect(script[read]).toContain('export CHANT_CONTROL_DIR="$chant_control_dir"');
+    expect(script[read]).toContain("'https://gitlab.com/acme/control.git'");
+    // The dispatch token is not the note job's.
+    expect(script[read]).not.toContain("TERRAGUCCI_CONTROL_TOKEN");
+  });
+
+  test("without a control repo the note job reads none", () => {
+    const { yaml } = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { applyOnMerge: true } });
+    expect(yaml).not.toContain("CHANT_CONTROL_DIR");
+  });
+});

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

@@ -0,0 +1,46 @@
+/**
+ * #4549: with a Pulumi Cloud identity, the merge-request pipeline's plan and
+ * record jobs trade their `id_tokens` for a preview token and the apply job
+ * for an up token. No job reads a Pulumi token from a CI/CD variable, 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 { gitlabTradeLines, resolveCloudIdentity, TRADE_SPEC_ENV } from "@intentius/chant/ci-identity";
+import { FORGE_TOKEN_VARS } from "@intentius/chant/ci-handover";
+import { generateGitlabPipeline } 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 GitlabJob {
+  id_tokens?: Record<string, { aud: string }>;
+  variables?: Record<string, string>;
+  script: string[];
+}
+
+describe("the GitLab pipeline's Pulumi Cloud tokens (#4549)", () => {
+  const { yaml } = generateGitlabPipeline(ESTATE, { env: "prod", image: "example/ci:1", prLoop: { applyOnMerge: true, identity: IDENTITY } });
+  const doc = parseYAML(yaml) as Record<string, GitlabJob>;
+
+  test("the plan job asks for the Pulumi id token and trades for the preview token before anything else", () => {
+    expect(doc.plan!.id_tokens).toEqual({ CHANT_ID_TOKEN_PULUMI: { aud: "urn:pulumi:org:acme" } });
+    expect(doc.plan!.script.slice(0, 3)).toEqual(gitlabTradeLines(FORGE_TOKEN_VARS));
+    expect(JSON.parse(doc.plan!.variables![TRADE_SPEC_ENV]!)).toEqual(IDENTITY.plan);
+  });
+
+  test("the record job takes the preview token and the apply job the up token", () => {
+    expect(JSON.parse(doc.record!.variables![TRADE_SPEC_ENV]!)).toEqual(IDENTITY.plan);
+    expect(JSON.parse(doc.apply!.variables![TRADE_SPEC_ENV]!)).toEqual(IDENTITY.apply);
+    expect(doc.apply!.id_tokens).toEqual(doc.plan!.id_tokens);
+  });
+
+  test("the plan job names no up token, and nothing reads PULUMI_ACCESS_TOKEN from a CI/CD variable", () => {
+    expect(JSON.stringify(doc.plan)).not.toContain("team:deploy");
+    expect(yaml).not.toContain("$PULUMI_ACCESS_TOKEN");
+  });
+});

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

@@ -0,0 +1,27 @@
+/**
+ * The pull request loop's responses and description check on GitLab
+ * (#4629), as `chant build --pr-loop --respond --decide-backend
+ * --decide-model` sets them: `pr-post --open` asks the decide service, and
+ * the apply before merge carries CHANT_RESPOND and the merge (#4636).
+ */
+import { expect, test } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import type { DriverComponent } from "@intentius/chant/components/driver";
+import { generateGitlabPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [{ name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] }];
+
+type Job = { variables?: Record<string, string>; script?: string[] };
+
+test("the note and apply jobs carry the responses, the decide service and the merge (#4629, #4636)", () => {
+  const doc = parseYAML(generateGitlabPipeline(ESTATE, {
+    env: "prod",
+    prLoop: { applyBeforeMerge: true, applyMerge: { tokenEnv: "CHANT_MERGE_TOKEN" }, respond: { description: "check" }, decide: { backend: "review", model: "m-1" } },
+  }).yaml) as Record<string, Job>;
+  const note = doc["plan-note"]!;
+  expect(note.script!.at(-1)).toMatch(/pr-post --open .* --decide-backend "review" --decide-model "m-1"$/);
+  expect(note.variables!.CHANT_RESPOND).toBe("description=check");
+  const apply = Object.values(doc).find((j) => typeof j === "object" && j?.script?.some((l) => l.includes("--apply-before-merge")))!;
+  expect(apply.script!.join("\n")).toContain("--merge auto --merge-token-env CHANT_MERGE_TOKEN");
+  expect(apply.variables!.CHANT_RESPOND).toBe("description=check");
+});

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

@@ -0,0 +1,41 @@
+/**
+ * The merge request pipeline's runners, variables and passed secrets on
+ * GitLab (#4625): each job's `tags` from its stage's runner, and a passed
+ * secret mapped from the CI/CD variable when the names differ. 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 { generateGitlabPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [{ name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] }];
+
+type Job = { tags?: string[]; variables: Record<string, string>; script: string[] };
+type Doc = Record<string, Job>;
+
+describe("the GitLab merge request pipeline's runners and variables (#4625)", () => {
+  const doc = parseYAML(
+    generateGitlabPipeline(ESTATE, {
+      env: "prod",
+      prLoop: { applyOnMerge: true, runners: { plan: "planner", apply: ["deploy", "eu"], default: "small" }, variables: { REGION: "eu" }, secrets: { DB_PASSWORD: "PROD_DB", SAME: "SAME" } },
+    }).yaml,
+  ) as Doc;
+
+  test("each job's tags come from its stage", () => {
+    expect(doc.plan!.tags).toEqual(["planner"]);
+    expect(doc.apply!.tags).toEqual(["deploy", "eu"]);
+    expect(doc.record!.tags).toEqual(["deploy", "eu"]);
+    expect(doc["plan-note"]!.tags).toEqual(["small"]);
+  });
+
+  test("the plan's variables carry the variable and the renamed secret; a same-named one needs no line", () => {
+    expect(doc.plan!.variables).toMatchObject({ REGION: "eu", DB_PASSWORD: "$PROD_DB" });
+    expect(doc.plan!.variables).not.toHaveProperty("SAME");
+  });
+
+  test("a runner group is refused", () => {
+    expect(() => generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { runners: { plan: { group: "g" } } } })).toThrow(/runner group/);
+  });
+});

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

@@ -0,0 +1,24 @@
+/**
+ * Stale marking on GitLab (#4628): the note job's `pr-post --open` passes
+ * the target branch pipeline's commit, and a stale-notes job in the push
+ * pipeline of the target branch runs `pr-post --stale`. 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 { generateGitlabPipeline } from "./generate-pipeline";
+
+const ESTATE: DriverComponent[] = [{ name: "net", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "net" }] }] }];
+
+test("the note job carries the tip and a push job marks the notes stale (#4628)", () => {
+  const doc = parseYAML(generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { staleNotes: true } }).yaml) as Record<string, unknown> & { stages: string[] };
+  const note = doc["plan-note"] as { variables: Record<string, string>; script: string[] };
+  expect(note.variables.TIP_SHA).toBe("$CI_COMMIT_SHA");
+  expect(note.script.at(-1)).toContain('--tip "$TIP_SHA"');
+  const stale = doc["stale-notes"] as { stage: string; rules: Array<{ if: string }>; variables: Record<string, string>; script: string[] };
+  expect(doc.stages).toContain("stale-notes");
+  expect(stale.rules[0]!.if).toContain("$CI_PIPELINE_SOURCE == \"push\"");
+  expect(stale.variables).toEqual({ TIP_SHA: "$CI_COMMIT_SHA" });
+  expect(stale.script.at(-1)).toBe('chant components pr-post --stale --tip "$TIP_SHA" --env prod --forge gitlab');
+});

package/src/components/review-jobs.ts

@@ -0,0 +1,163 @@
+/**
+ * The two jobs of a split review on GitLab (#4544): `ScheduledOpSpec.reviewAgent`.
+ *
+ * An Op that runs a `reviewAgent` step in `handoff` mode runs the change's
+ * code (`chant run` loads the merge request's Op files) beside a model.
+ * GitHub and Forgejo keep the write token out of that job with per-job
+ * permissions (`lexicons/github/src/components/review-jobs.ts`). GitLab has
+ * none: a merge request pipeline is built from the merge request's own files
+ * and every job in it gets the project's unprotected variables. So the token
+ * stays out of that pipeline altogether, the way the plan note does (#4328):
+ *
+ * - the review job runs in the merge request pipeline. Its script starts by
+ *   unsetting every forge token variable (`GITLAB_DROP_FORGE_TOKENS`), and it
+ *   keeps the review directory as its artifact. `CHANT_FORGE_TOKEN` is a
+ *   protected variable, which a merge request pipeline never gets.
+ * - the note job runs in a pipeline of the default branch, built from that
+ *   branch's files, that a pipeline schedule (or a person, the API or a
+ *   trigger) starts with `CHANT_REVIEW_NOTES` set to `1`. It checks nothing
+ *   out (`GIT_STRATEGY: none`), installs the chant release this lexicon
+ *   belongs to, and runs `postOpenReviewNotes` with the protected token: for
+ *   each open merge request whose newest pipeline's review job succeeded it
+ *   reads `review.json` from that job's artifacts as data and posts the note.
+ *   The Op's name, the review job's name and the branches come from this
+ *   file, never from the artifact.
+ */
+
+import { readFileSync } from "node:fs";
+import { GITLAB_DROP_FORGE_TOKENS } from "@intentius/chant/ci-handover";
+import type { OpTrigger } from "@intentius/chant/lexicon";
+
+/** The variable `reviewAgent` reads its handoff directory from (`REVIEW_DIR_ENV`, review-agent.ts). */
+export const REVIEW_DIR_ENV = "CHANT_REVIEW_DIR";
+
+/** Where the review job writes the review, from the directory its script runs in. */
+export const REVIEW_DIR = ".chant/review";
+
+/** The variable a pipeline of the default branch is started with to run the note jobs. */
+export const GITLAB_REVIEW_NOTES_VAR = "CHANT_REVIEW_NOTES";
+
+/** How long a review artifact is kept: long enough for a schedule to come round and post it. */
+const REVIEW_ARTIFACT_EXPIRY = "7 days";
+
+/** The name of the note job beside the Op's own job. */
+export function reviewNoteJobName(jobName: string): string {
+  return `${jobName}-note`;
+}
+
+/**
+ * The note job's rule: a pipeline of the default branch that a pipeline
+ * schedule, a person, the API or a trigger started with `CHANT_REVIEW_NOTES`
+ * set to `1`. A merge request pipeline's own trigger job starts a pipeline
+ * whose source is `pipeline`, which this rule leaves out.
+ */
+export const GITLAB_REVIEW_NOTES_RULE = `$CI_PIPELINE_SOURCE =~ /^(schedule|web|api|trigger)$/ && $${GITLAB_REVIEW_NOTES_VAR} == "1" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH`;
+
+/**
+ * Refuse a spec whose review cannot be split the way this shape needs: a
+ * trigger with no merge request, a finding-mode that would post from the
+ * review job, or an additive scope other than `id-token: write`.
+ */
+export function assertReviewSplit(name: string, trigger: OpTrigger, findingMode: string, permissions: Record<string, string> | undefined): void {
+  if (trigger.kind !== "pull_request") {
+    throw new Error(
+      `Scheduled Op "${name}" sets reviewAgent, which posts the review as a note on the merge request that triggered the run, but its trigger is "${trigger.kind}". Give it a { kind: "pull_request" } trigger.`,
+    );
+  }
+  if (findingMode !== "report") {
+    throw new Error(
+      `Scheduled Op "${name}" sets reviewAgent with findingMode "${findingMode}". The review job holds no forge token, and the note job posts from a pipeline of the default branch instead, so the Op's own finding-mode must be "report".`,
+    );
+  }
+  for (const [scope, level] of Object.entries(permissions ?? {})) {
+    if (level === "write" && scope !== "id-token") {
+      throw new Error(
+        `Scheduled Op "${name}" sets reviewAgent and adds the permission "${scope}: write". The review job runs the change's code and may hold only "id-token: write".`,
+      );
+    }
+  }
+}
+
+/** The chant release the note job installs: this lexicon's own, which releases in lockstep with `@intentius/chant`. */
+function chantVersion(): string {
+  const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")) as { version?: unknown };
+  if (typeof pkg.version !== "string" || pkg.version === "") {
+    throw new Error("the gitlab lexicon's package.json has no version to pin the review note job's chant to");
+  }
+  return pkg.version;
+}
+
+/** What the note job runs under node. The inputs are JSON literals from this file; nothing comes from the merge request. */
+function noteModule(op: string, job: string, artifactDir: string, branches: readonly string[] | undefined): string {
+  return [
+    'import { forgeFromEnv } from "@intentius/chant/pr-forge";',
+    'import { postOpenReviewNotes } from "@intentius/chant/op/activities/review-agent";',
+    `const branches = ${JSON.stringify(branches ?? null)} ?? [process.env.CI_DEFAULT_BRANCH];`,
+    "const forge = forgeFromEnv(\"gitlab\");",
+    "let failed = false;",
+    "for (const branch of branches) {",
+    `  const { posts, warnings } = await postOpenReviewNotes({ forge, branch, job: ${JSON.stringify(job)}, artifactDir: ${JSON.stringify(artifactDir)}, op: ${JSON.stringify(op)} });`,
+    "  for (const p of posts) console.log(`!${p.pr} at ${p.head.slice(0, 12)}: ${p.skipped ?? `posted, risk ${p.risk}`}`);",
+    "  for (const w of warnings) { console.error(w); failed = true; }",
+    "}",
+    "if (failed) process.exitCode = 1;",
+  ].join("\n");
+}
+
+/** The note job's script: install the pinned chant outside any checkout and run {@link noteModule} with tsx. */
+function noteScript(version: string, module: string): string[] {
+  return [
+    'dir="${TMPDIR:-/tmp}/chant-review-note"',
+    'mkdir -p "$dir"',
+    'cd "$dir"',
+    "echo '{\"private\":true}' > package.json",
+    `npm install --omit=peer --no-audit --no-fund --loglevel=error @intentius/chant@${version}`,
+    ["cat > note.mjs <<'NOTE'", module, "NOTE"].join("\n"),
+    "node --import tsx note.mjs",
+  ];
+}
+
+export interface GitlabReviewJobsInput {
+  /** The Op's name: what `chant run` targets and what keys the note. */
+  name: string;
+  /** The review job's name: the Op's job name. */
+  jobName: string;
+  stage: string;
+  image: string;
+  /** The review job's `rules:`, the Op's merge request rules. */
+  rules: unknown[];
+  /** The review job's script after the token unset: cd, setup, before-script, the invocation and the extra script. */
+  script: string[];
+  /** The Op's own per-job environment (`ScheduledOpSpec.variables`). */
+  variables?: Record<string, string>;
+  idTokens?: Record<string, unknown>;
+  /** The review directory from the repository root: `.chant/review`, under a workspace member's directory for a member. */
+  artifactDir: string;
+  /** The branches the merge requests merge into, from the trigger; the default branch when absent. */
+  branches?: readonly string[];
+}
+
+/** The review job and the note job of one split review. */
+export function gitlabReviewJobs(i: GitlabReviewJobsInput): { review: Record<string, unknown>; note: Record<string, unknown> } {
+  const review = {
+    stage: i.stage,
+    image: i.image,
+    resource_group: i.jobName,
+    ...(i.idTokens ? { id_tokens: i.idTokens } : {}),
+    variables: { ...(i.variables ?? {}), [REVIEW_DIR_ENV]: REVIEW_DIR },
+    rules: i.rules,
+    // The merge request's code runs in this job, so its shell drops every forge token first.
+    script: [GITLAB_DROP_FORGE_TOKENS, ...i.script],
+    artifacts: { paths: [i.artifactDir], expire_in: REVIEW_ARTIFACT_EXPIRY },
+  };
+  const note = {
+    stage: i.stage,
+    image: i.image,
+    resource_group: reviewNoteJobName(i.jobName),
+    // Nothing of the repository is needed: the review is read from the review job's artifacts through the API.
+    variables: { GIT_STRATEGY: "none" },
+    rules: [{ if: GITLAB_REVIEW_NOTES_RULE }],
+    script: noteScript(chantVersion(), noteModule(i.name, i.jobName, i.artifactDir, i.branches)),
+  };
+  return { review, note };
+}