@intentius/chant-lexicon-gitlab 0.102.0 → 0.104.0

package/dist/components/generate-pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAGjG,OAAO,KAAK,EACV,oBAAoB,IAAI,YAAY,EACpC,wBAAwB,IAAI,qBAAqB,EACjD,uBAAuB,IAAI,oBAAoB,EAEhD,MAAM,0BAA0B,CAAC;AAElC,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;AAS1E;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAyItB"}
+{"version":3,"file":"generate-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAKjG,OAAO,KAAK,EACV,oBAAoB,IAAI,YAAY,EACpC,wBAAwB,IAAI,qBAAqB,EACjD,uBAAuB,IAAI,oBAAoB,EAEhD,MAAM,0BAA0B,CAAC;AAElC,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;AAS1E;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAsJtB"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "3fa255907266687335043666a68d07369be9edd2ca1526897a357c301cfae2e9",
+    "manifest.json": "ef6e7a167965f693557802a8211365e1dee13712ef42ac41e276e9b3528dc307",
     "meta.json": "931fc3246a55645b1493080bbeb160e5d205e42349e8bdca96ca243adb5f0da3",
     "types/index.d.ts": "5cd2e99f135a929b72bdd822d00d780d39b1cd407ba0cfb3d511c7ac9d667b58",
     "rules/artifact-no-expiry.ts": "3f3cabf9792cbf8207e53a25f506715466b19ec25e9c3b4d0d77fed6b2eb4542",
@@ -55,5 +55,5 @@
     "skills/chant-gitlab-migrate.md": "4853d04980560b379e5b0f7267dcb0a1e5d5879cb9e9931681ce76b2a5fe69d8",
     "skills/chant-gitlab-patterns.md": "6d9a44e9e8de4c3820be9d65381b0d2ede4cb3626aaaf0011e21838a9fbf556e"
   },
-  "composite": "54b426d41adbb3988bb2ca30ad774ead4b306821214f752bb5a56587232ae911"
+  "composite": "01362067b7c359f45f632c89c2532c2f24ae13c6ee1b01f1fc501524df6383c1"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "gitlab",
-  "version": "0.102.0",
+  "version": "0.104.0",
   "chantVersion": ">=0.1.0",
   "namespace": "GitLab",
   "intrinsics": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-gitlab",
-  "version": "0.102.0",
+  "version": "0.104.0",
   "description": "GitLab CI lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -67,8 +67,8 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.102.0",
-    "@intentius/chant-lexicon-github": "^0.102.0",
+    "@intentius/chant": "^0.104.0",
+    "@intentius/chant-lexicon-github": "^0.104.0",
     "typescript": "^5.9.3"
   },
   "peerDependenciesMeta": {

package/src/components/__fixtures__/pr-loop.gitlab.golden.yml

@@ -0,0 +1,43 @@
+workflow:
+  name: chant-pr-prod
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
+
+stages:
+  - plan
+  - apply
+
+variables:
+  CHANT_ENV: prod
+  GIT_DEPTH: '0'
+
+plan:
+  stage: plan
+  image: node:22-slim
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+  variables:
+    BASE_SHA: '$CI_MERGE_REQUEST_DIFF_BASE_SHA'
+    PR_NUMBER: '$CI_MERGE_REQUEST_IID'
+  script:
+    - chant components pr-plan --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --output .chant/pr --forge gitlab
+  artifacts:
+    when: always
+    paths:
+      - .chant/pr
+
+apply:
+  stage: apply
+  image: node:22-slim
+  resource_group: chant-apply-prod
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
+  variables:
+    BASE_SHA: '$CI_COMMIT_BEFORE_SHA'
+  script:
+    - chant components pr-apply --base "$BASE_SHA" --env prod --gate pr-apply --output .chant/pr --forge gitlab --require-review
+  artifacts:
+    when: always
+    paths:
+      - .chant/pr

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

@@ -327,3 +327,36 @@ describe("generateGitlabPipeline: a promote job (#2575)", () => {
     expect(() => generateGitlabPipeline(infraOnly)).not.toThrow();
   });
 });
+
+describe("generateGitlabPipeline: gated waves (#3049)", () => {
+  /** net -> a, b -> app: three waves, four with a canary in front. */
+  const roots: DriverComponent[] = [
+    { name: "net", deploy: [] },
+    { name: "a", dependsOn: ["net"], deploy: [] },
+    { name: "b", dependsOn: ["net"], deploy: [] },
+    { name: "app", dependsOn: ["a"], deploy: [] },
+  ];
+
+  test("one job per wave, in order, each running that wave of the gated fan-out", () => {
+    const result = generateGitlabPipeline(roots, { env: "prod", gatedWaves: { gate: "release" } });
+    const parsed = parseYAML(result.yaml) as Record<string, Record<string, unknown>>;
+    expect(result.stages).toEqual(["wave-1", "wave-2", "wave-3"]);
+    expect(parsed["wave-2"].needs).toEqual(["wave-1"]);
+    expect(parsed["wave-1"].needs).toBeUndefined();
+    expect(parsed["wave-3"].script).toEqual([
+      "chant components fan-out --base HEAD~1 --env prod --wave-gate release --wave 3 --resume .chant/fan-out.json",
+    ]);
+    // The record goes to the next job even when this one stops at a gate.
+    expect(parsed["wave-1"].artifacts).toEqual({ when: "always", paths: [".chant/fan-out.json"] });
+    expect(parsed["wave-1"].variables).toEqual({ GIT_DEPTH: "0" });
+    // No per-component jobs.
+    expect(parsed.net).toBeUndefined();
+  });
+
+  test("a canary list adds a wave in front and is passed to every job", () => {
+    const result = generateGitlabPipeline(roots, { env: "prod", gatedWaves: { gate: "release", canary: ["b"], base: "$CI_COMMIT_BEFORE_SHA" } });
+    expect(result.stages).toEqual(["wave-1", "wave-2", "wave-3", "wave-4"]);
+    const parsed = parseYAML(result.yaml) as Record<string, Record<string, unknown>>;
+    expect((parsed["wave-1"].script as string[])[0]).toContain("--base $CI_COMMIT_BEFORE_SHA --env prod --wave-gate release --canary b --wave 1");
+  });
+});

package/src/components/generate-pipeline.ts

@@ -35,6 +35,8 @@
 import { emitYAMLEntry } from "@intentius/chant/yaml";
 import { resolveComponentGraph, type DriverComponent } from "@intentius/chant/components/driver";
 import { hasPublishStep, promoteArchivePaths } from "@intentius/chant/components/promote";
+import { GATED_WAVE_RECORD, gatedWaveJobs } from "@intentius/chant/components/gated-wave-pipeline";
+import { PR_LOOP_REPORT_DIR, prApplyGroup, prLoopJobs } from "@intentius/chant/components/pr-pipeline";
 import { memberGitlabChanges, memberRepoPath, memberShellDir } from "@intentius/chant/lexicon";
 import type {
   ComponentPipelineJob as GeneratedJob,
@@ -73,6 +75,19 @@ export function generateGitlabPipeline(
   const { waves } = resolveComponentGraph(components);
   const byName = new Map(components.map((c) => [c.name, c]));
 
+  if (options.prLoop) {
+    if (options.gatedWaves || options.promoteTo !== undefined) {
+      throw new Error("a pull-request pipeline has no wave or promote jobs; drop --wave-gate and --promote-to, or --pr-loop");
+    }
+    if (options.member) throw new Error("a pull-request pipeline is not generated for a workspace member yet; generate it from the project outside the workspace");
+    return prLoopGitlabPipeline(env, image, beforeScript, extraScript, options);
+  }
+
+  if (options.gatedWaves) {
+    if (options.promoteTo !== undefined) throw new Error("a gated-wave pipeline has no promote job; drop --promote-to or --wave-gate");
+    return gatedWaveGitlabPipeline(components, env, image, beforeScript, extraScript, options);
+  }
+
   // Components that something else depends on must hand their resolved outputs
   // (stack outputs, published artifact refs) to their dependents, which run as
   // separate jobs/processes. Each such producer dumps its outputs to a file and
@@ -202,6 +217,102 @@ export function generateGitlabPipeline(
   return { yaml: sections.join("\n\n") + "\n", stages, jobs, env };
 }
 
+/**
+ * The gated-wave pipeline (#3049): one job per wave, each running one wave of
+ * `chant components fan-out --wave-gate`, in order through `needs:`. The
+ * attempt record is the artifact GitLab hands from job to job, kept even when
+ * a job stops at a gate (exit 3) so the re-run after `chant approve` reads it.
+ * `GIT_DEPTH: "0"` gives the job the history `--base` diffs against.
+ */
+function gatedWaveGitlabPipeline(
+  components: DriverComponent[],
+  env: string,
+  image: string,
+  beforeScript: string[],
+  extraScript: string[],
+  options: GenerateGitlabOptions,
+): GenerateGitlabResult {
+  const waveJobs = gatedWaveJobs(components, env, options.gatedWaves!);
+  const stages = waveJobs.map((j) => j.jobName);
+  const doc: Record<string, unknown> = {
+    workflow: { name: `chant-components-${env}` },
+    stages,
+    variables: { ...options.variables, CHANT_ENV: env },
+  };
+  const jobs: GeneratedJob[] = [];
+  for (const job of waveJobs) {
+    jobs.push({ jobName: job.jobName, component: `wave ${job.wave}`, stage: job.jobName, needs: job.needs });
+    doc[job.jobName] = {
+      stage: job.jobName,
+      image,
+      variables: { GIT_DEPTH: "0" },
+      script: [...beforeScript, job.command.join(" "), ...extraScript],
+      ...(job.needs.length > 0 ? { needs: job.needs } : {}),
+      artifacts: { when: "always", paths: [GATED_WAVE_RECORD] },
+    };
+  }
+  if (options.member) scopeToMember(doc, jobs, undefined, options.member, env);
+  const sections = [
+    emitYAMLEntry("workflow", doc.workflow),
+    emitYAMLEntry("stages", stages),
+    emitYAMLEntry("variables", doc.variables),
+    ...jobs.map((job) => emitYAMLEntry(job.jobName, doc[job.jobName])),
+  ];
+  return { yaml: sections.join("\n\n") + "\n", stages, jobs, env };
+}
+
+/**
+ * The merge-request pipeline (#3183): `plan` in each merge request pipeline,
+ * `apply` on each push to the target branch, one apply at a time per
+ * environment (`resource_group`). `GIT_DEPTH: "0"` gives both the history
+ * they measure the change with. The jobs talk to GitLab with
+ * `CHANT_FORGE_TOKEN`, a project or group access token with the `api` scope
+ * set as a masked CI/CD variable, since a job token cannot write notes.
+ */
+function prLoopGitlabPipeline(
+  env: string,
+  image: string,
+  beforeScript: string[],
+  extraScript: string[],
+  options: GenerateGitlabOptions,
+): GenerateGitlabResult {
+  const loop = options.prLoop!;
+  const [plan, apply] = prLoopJobs("gitlab", env, loop);
+  const onMergeRequest = '$CI_PIPELINE_SOURCE == "merge_request_event"';
+  const target = loop.branch ? JSON.stringify(loop.branch) : "$CI_DEFAULT_BRANCH";
+  const onMerge = `$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == ${target}`;
+  const script = (job: typeof plan): string[] => [...beforeScript, job.command, ...extraScript];
+  const stages = ["plan", "apply"];
+  const doc: Record<string, unknown> = {
+    workflow: { name: `chant-pr-${env}`, rules: [{ if: onMergeRequest }, { if: onMerge }] },
+    stages,
+    variables: { ...options.variables, CHANT_ENV: env, GIT_DEPTH: "0" },
+    plan: {
+      stage: "plan",
+      image,
+      rules: [{ if: onMergeRequest }],
+      variables: plan.env,
+      script: script(plan),
+      artifacts: { when: "always", paths: [PR_LOOP_REPORT_DIR] },
+    },
+    apply: {
+      stage: "apply",
+      image,
+      resource_group: prApplyGroup(env),
+      rules: [{ if: onMerge }],
+      variables: apply.env,
+      script: script(apply),
+      artifacts: { when: "always", paths: [PR_LOOP_REPORT_DIR] },
+    },
+  };
+  const jobs: GeneratedJob[] = [
+    { jobName: "plan", component: "merge request plan", stage: "plan", needs: [] },
+    { jobName: "apply", component: "merge request apply", stage: "apply", needs: [] },
+  ];
+  const sections = ["workflow", "stages", "variables", "plan", "apply"].map((key) => emitYAMLEntry(key, doc[key]));
+  return { yaml: sections.join("\n\n") + "\n", stages, jobs, env };
+}
+
 /**
  * Scope a pipeline to one workspace member (#2542, #2524 D19), in place on
  * `doc` and `jobs`. Returns the promote job's new name.

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

@@ -0,0 +1,70 @@
+/**
+ * The generated merge-request pipeline for GitLab CI (#3183): a plan job in
+ * each merge request pipeline, an apply job on each push to the default
+ * branch. The whole file has a golden, and it validates against the GitLab
+ * CI schema this lexicon vendors.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+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" }] }] },
+  { name: "app", dependsOn: ["net"], deploy: [{ phase: "Apply", steps: [{ kind: "terraform-apply", root: "app" }] }] },
+];
+
+const GOLDEN = join(import.meta.dirname, "__fixtures__", "pr-loop.gitlab.golden.yml");
+const SCHEMA = join(import.meta.dirname, "..", "codegen", "vendored", "gitlab-ci-schema.json");
+
+interface Job {
+  rules: Array<{ if: string }>;
+  variables: Record<string, string>;
+  script: string[];
+  resource_group?: string;
+  artifacts: Record<string, unknown>;
+}
+
+describe("the GitLab merge-request pipeline", () => {
+  const result = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: {} });
+  const doc = parseYAML(result.yaml) as { workflow: { rules: unknown[] }; variables: Record<string, string>; plan: Job; apply: Job };
+
+  test("matches its golden", () => {
+    if (process.env.UPDATE_GOLDEN) writeFileSync(GOLDEN, result.yaml);
+    expect(result.yaml).toBe(readFileSync(GOLDEN, "utf-8"));
+  });
+
+  test("validates against the vendored GitLab CI schema", () => {
+    const req = createRequire(import.meta.url);
+    const mod = req("ajv") as { default?: unknown };
+    const Ajv = (mod.default ?? mod) as new (opts: object) => { compile(s: object): ((d: unknown) => boolean) & { errors?: unknown } };
+    const validate = new Ajv({ strict: false, allErrors: true }).compile(JSON.parse(readFileSync(SCHEMA, "utf-8")));
+    const ok = validate(doc);
+    expect(ok, JSON.stringify(validate.errors, null, 2)).toBe(true);
+  });
+
+  test("plans in a merge request pipeline from its diff base, applies on a push to the default branch, one at a time", () => {
+    expect(doc.plan.rules).toEqual([{ if: '$CI_PIPELINE_SOURCE == "merge_request_event"' }]);
+    expect(doc.plan.variables).toEqual({ BASE_SHA: "$CI_MERGE_REQUEST_DIFF_BASE_SHA", PR_NUMBER: "$CI_MERGE_REQUEST_IID" });
+    expect(doc.plan.script).toEqual(['chant components pr-plan --base "$BASE_SHA" --pr "$PR_NUMBER" --env prod --gate pr-apply --output .chant/pr --forge gitlab']);
+    expect(doc.apply.rules).toEqual([{ if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' }]);
+    expect(doc.apply.variables).toEqual({ BASE_SHA: "$CI_COMMIT_BEFORE_SHA" });
+    expect(doc.apply.script[0]).toContain("--require-review");
+    expect(doc.apply.resource_group).toBe("chant-apply-prod");
+    expect(doc.variables.GIT_DEPTH).toBe("0");
+    expect(doc.apply.artifacts).toEqual({ when: "always", paths: [".chant/pr"] });
+  });
+
+  test("a named branch replaces the default branch in the apply rule", () => {
+    const yaml = generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { branch: "trunk" } }).yaml;
+    expect(yaml).toContain('$CI_COMMIT_BRANCH == "trunk"');
+  });
+
+  test("refuses a wave or promote job beside it", () => {
+    expect(() => generateGitlabPipeline(ESTATE, { prLoop: {}, gatedWaves: { gate: "g" } })).toThrow(/pull-request pipeline has no wave or promote jobs/);
+  });
+});