@intentius/chant-lexicon-gitlab 0.124.13 → 0.124.15

package/dist/components/ci-jobs.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The GitLab CI pieces the three generators share (#3765): the Op pipeline
+ * (`./generate-op-pipeline.ts`), the Op waves pipeline
+ * (`./generate-op-waves-pipeline.ts`) and the component pipeline
+ * (`./generate-pipeline.ts`). The `rules:` expressions, `id_tokens:`, setup
+ * and environment checks are core's, in `@intentius/chant/ci-jobs`.
+ */
+/**
+ * A `.gitlab-ci.yml` document: the comment header, when there is one, then
+ * each top-level entry in the order given, a blank line between each.
+ */
+export declare function emitGitlabFile(entries: ReadonlyArray<readonly [string, unknown]>, header?: readonly string[]): string;
+//# sourceMappingURL=ci-jobs.d.ts.map

package/dist/components/ci-jobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-jobs.d.ts","sourceRoot":"","sources":["../../src/components/ci-jobs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,GAAE,SAAS,MAAM,EAAO,GAAG,MAAM,CAGzH"}

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

@@ -61,7 +61,7 @@
  * option's lines in this same lexicon, and which concatenates identically at
  * run time. An additive `permissions` map has exactly one entry with a GitLab
  * meaning: `id-token: write` becomes an `id_tokens:` declaration ({@link
- * idTokensFor}), the OIDC surface the old refusal already named as the shape
+ * gitlabIdTokens}), the OIDC surface the old refusal already named as the shape
  * to reach for. Every other scope is still refused, because there is no
  * per-job token-scope mapping to put it in and a silently dropped scope emits
  * a job that reads as granted and runs with nothing.

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

@@ -1 +1 @@
-{"version":3,"file":"generate-op-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyGG;AAIH,OAAO,KAAK,EACV,wBAAwB,IAAI,uBAAuB,EAInD,gBAAgB,IAAI,sBAAsB,EAE1C,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAElC,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,CAAC;AAqShE;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CAgHxB"}
+{"version":3,"file":"generate-op-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyGG;AAeH,OAAO,KAAK,EACV,wBAAwB,IAAI,uBAAuB,EAInD,gBAAgB,IAAI,sBAAsB,EAE1C,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAIlC,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,CAAC;AAqHhE;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CAsGxB"}

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

@@ -1 +1 @@
-{"version":3,"file":"generate-op-waves-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-waves-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAoC,KAAK,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAClG,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAK9F,gHAAgH;AAChH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CA4EvH"}
+{"version":3,"file":"generate-op-waves-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-waves-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAeH,OAAO,EAAoC,KAAK,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAClG,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAG9F,gHAAgH;AAChH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAqEvH"}

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;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,CAqJtB"}
+{"version":3,"file":"generate-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAWH,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;AAIlC,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;AAE1E;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAkJtB"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "ba04bc04b196c88dec4304a7687eef1b01a9bc31939015560d129fd3decacff5",
+    "manifest.json": "d159b23db036b47dbf7b08997d690987e67ae767fdc7cfc974166e82a3e554e2",
     "meta.json": "db082fbf90c5941c498b2bee0f106103449c1a4c257716ca2220f0dd490450b2",
     "types/index.d.ts": "a048a66ebe20da0cb5fc889054cac69044d9bf882e2c56b5c5bf113d1f3ba57c",
     "rules/artifact-no-expiry.ts": "0ca5bb972d4a542126e8a0229d43b55658394cb7dd9b9923b2c590bec1c2ad7d",
@@ -55,5 +55,5 @@
     "skills/chant-gitlab-migrate.md": "4853d04980560b379e5b0f7267dcb0a1e5d5879cb9e9931681ce76b2a5fe69d8",
     "skills/chant-gitlab-patterns.md": "6d9a44e9e8de4c3820be9d65381b0d2ede4cb3626aaaf0011e21838a9fbf556e"
   },
-  "composite": "42f34e8e6caf92f82cfa7ff108f956ab161c497c50eb36613b05e39134453ac8"
+  "composite": "1024305a66cb4b31fdc78d78424aa9c84bff0c4161728ea2424591b895df6892"
 }

package/dist/manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-gitlab",
-  "version": "0.124.13",
+  "version": "0.124.15",
   "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.124.13",
-    "@intentius/chant-lexicon-github": "^0.124.13"
+    "@intentius/chant": "^0.124.15",
+    "@intentius/chant-lexicon-github": "^0.124.15"
   },
   "peerDependenciesMeta": {
     "@intentius/chant-lexicon-github": {

package/src/components/ci-jobs.ts

@@ -0,0 +1,18 @@
+/**
+ * The GitLab CI pieces the three generators share (#3765): the Op pipeline
+ * (`./generate-op-pipeline.ts`), the Op waves pipeline
+ * (`./generate-op-waves-pipeline.ts`) and the component pipeline
+ * (`./generate-pipeline.ts`). The `rules:` expressions, `id_tokens:`, setup
+ * and environment checks are core's, in `@intentius/chant/ci-jobs`.
+ */
+
+import { emitYAMLEntry } from "@intentius/chant/yaml";
+
+/**
+ * A `.gitlab-ci.yml` document: the comment header, when there is one, then
+ * each top-level entry in the order given, a blank line between each.
+ */
+export function emitGitlabFile(entries: ReadonlyArray<readonly [string, unknown]>, header: readonly string[] = []): string {
+  const body = entries.map(([key, value]) => emitYAMLEntry(key, value)).join("\n\n") + "\n";
+  return header.length > 0 ? header.join("\n") + "\n\n" + body : body;
+}

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

@@ -61,7 +61,7 @@
  * option's lines in this same lexicon, and which concatenates identically at
  * run time. An additive `permissions` map has exactly one entry with a GitLab
  * meaning: `id-token: write` becomes an `id_tokens:` declaration ({@link
- * idTokensFor}), the OIDC surface the old refusal already named as the shape
+ * gitlabIdTokens}), the OIDC surface the old refusal already named as the shape
  * to reach for. Every other scope is still refused, because there is no
  * per-job token-scope mapping to put it in and a silently dropped scope emits
  * a job that reads as granted and runs with nothing.
@@ -105,7 +105,18 @@
  * beside it does not also point.
  */
 
-import { emitYAMLEntry } from "@intentius/chant/yaml";
+import {
+  assertGitlabEnvironment,
+  CI_IMAGE,
+  ciJobName,
+  environmentDoc,
+  fillCommand,
+  gitlabIdTokens,
+  gitlabRules,
+  gitlabSetupScript,
+  nonEmpty,
+  pushBranches,
+} from "@intentius/chant/ci-jobs";
 import { memberGitlabChanges, memberRepoPath, memberShellDir, resolveOpTrigger } from "@intentius/chant/lexicon";
 import type {
   ComponentPipelineOptions as GenerateGitlabOpOptions,
@@ -117,14 +128,9 @@ import type {
   ScheduledOpSpec,
 } from "@intentius/chant/lexicon";
 
-export type { GenerateGitlabOpOptions, GenerateGitlabOpResult };
-
-/** GitLab CI job names must be safe YAML keys; Op names are already kebab-case in every fixture, but normalize defensively (mirrors `./generate-pipeline.ts`'s `toJobName`). */
-function toJobName(opName: string): string {
-  return opName.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
-}
+import { emitGitlabFile } from "./ci-jobs";
 
-const DEFAULT_IMAGE = "node:22";
+export type { GenerateGitlabOpOptions, GenerateGitlabOpResult };
 
 /**
  * Default stage every generated job runs in, and the default base of the
@@ -145,33 +151,6 @@ const DEFAULT_STAGE = "ops";
 /** The CI/CD variable a Pipeline Schedule sets to select which job it runs. */
 const SELECTOR_VAR = "CHANT_SCHEDULED_OP";
 
-/**
- * Default branch assumed for a `push` trigger with no `branches` override.
- * The same value github's generator documents, for the same reason: this
- * operates on a `ScheduledOpSpec` rather than a git checkout, so it cannot
- * read a downstream project's actual default branch. Set `trigger.branches`
- * explicitly on a project whose default branch is something else.
- */
-const DEFAULT_PUSH_BRANCH = "main";
-
-/** The pipeline source GitLab reports for a merge-request pipeline. */
-const MERGE_REQUEST_SOURCE = '$CI_PIPELINE_SOURCE == "merge_request_event"';
-
-/**
- * The `id_tokens:` entry an `id-token: write` spec gets. The name is the
- * environment variable the JWT lands in, which the job's own setup line reads
- * (`aws sts assume-role-with-web-identity --web-identity-token
- * "$CHANT_ID_TOKEN"`, or the provider's equivalent).
- *
- * `$CI_SERVER_URL` as the audience is GitLab's own documented default: an
- * identity provider federated to a GitLab instance is registered with that
- * instance's URL as its audience, and the variable expands to exactly that on
- * gitlab.com and on a self-managed instance alike. A project whose provider
- * was registered with some other audience edits the generated declaration.
- */
-const ID_TOKEN_NAME = "CHANT_ID_TOKEN";
-const ID_TOKEN_AUDIENCE = "$CI_SERVER_URL";
-
 /**
  * `chant run` returns 3 when a run stops at an unapproved gate; `--gated-exit
  * 0` maps that one outcome to success (#2243). `push` only — a cron watch or
@@ -185,28 +164,6 @@ const GATE_SUMMARY_VAR = "CHANT_GATE_SUMMARY";
 /** How long a pending-gate artifact is worth keeping: long enough to outlive the approval it is waiting for. */
 const GATE_ARTIFACT_EXPIRY = "30 days";
 
-/**
- * Refuse a branch name that cannot be interpolated into a `rules:`
- * if-expression. The expression is a string GitLab parses, so a `"` would end
- * it early and a `$` would expand as a variable — either one silently changes
- * which pipelines match the job, which is worse than not generating it.
- */
-function assertBranchName(specName: string, branch: string): void {
-  if (branch.trim() === "") {
-    throw new Error(
-      `Scheduled Op "${specName}" has an empty branch filter. Name a branch, or drop the filter.`,
-    );
-  }
-  if (/["$\\]/.test(branch)) {
-    throw new Error(
-      `Scheduled Op "${specName}" filters on branch "${branch}", which carries a character this generator ` +
-        `cannot put in a GitLab \`rules:\` expression: a quote would end the expression early and a "$" ` +
-        `would expand as a CI/CD variable, either of which silently changes which pipelines run the job. ` +
-        `Name a branch without \`"\`, \`$\` or \`\\\`.`,
-    );
-  }
-}
-
 /** Refuse a blank `opsStage` (#2293): every job's `stage:` and the top-level `stages:` entry would otherwise be an empty string. */
 function assertOpsStage(stage: string): void {
   if (stage.trim() === "") {
@@ -227,33 +184,6 @@ function assertOpsFileName(fileName: string): void {
   }
 }
 
-/**
- * This trigger's `rules:` entries. Two or more branches are two or more
- * entries: `rules:` is an OR over its list, which is how GitLab spells the
- * alternation github expresses as a `branches:` array.
- */
-function rulesFor(spec: ScheduledOpSpec, trigger: OpTrigger): Array<{ if: string }> {
-  switch (trigger.kind) {
-    case "cron":
-      return [{ if: `$CI_PIPELINE_SOURCE == "schedule" && $${SELECTOR_VAR} == "${spec.name}"` }];
-    case "pull_request": {
-      const branches = trigger.branches ?? [];
-      if (branches.length === 0) return [{ if: MERGE_REQUEST_SOURCE }];
-      return branches.map((branch) => {
-        assertBranchName(spec.name, branch);
-        return { if: `${MERGE_REQUEST_SOURCE} && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "${branch}"` };
-      });
-    }
-    case "push": {
-      const branches = trigger.branches?.length ? trigger.branches : [DEFAULT_PUSH_BRANCH];
-      return branches.map((branch) => {
-        assertBranchName(spec.name, branch);
-        return { if: `$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == "${branch}"` };
-      });
-    }
-  }
-}
-
 /**
  * Refuse `findingMode: "comment"` on a trigger that has no merge request
  * (#2231, #2256). The mode's activity reads the merge request out of the
@@ -272,99 +202,6 @@ function assertTriggerSupportsMode(name: string, mode: OpFindingMode, trigger: O
   );
 }
 
-/**
- * Turn a spec's additive `permissions` (#2242) into the one GitLab
- * declaration that carries the same meaning, refusing everything else by name.
- *
- * `id-token: write` is that one: GitLab's OIDC surface is `id_tokens:`, a
- * per-job declaration of a JWT the job exchanges for cloud credentials
- * itself. `id-token: read` is refused rather than mapped, because GitLab
- * either mints the token into the job or does not — there is no read-only
- * half of it, and emitting the declaration for a spec that asked for read
- * would hand the job more than it asked for.
- *
- * Every other scope is refused, unchanged from the pre-#2256 behaviour:
- * GitLab has no per-job token-scope mapping at all, and a scope quietly
- * dropped would emit a job that reads as granted and runs with nothing.
- */
-function idTokensFor(spec: ScheduledOpSpec): Record<string, unknown> | undefined {
-  let wantsIdToken = false;
-  for (const [rawScope, value] of Object.entries(spec.permissions ?? {})) {
-    const scope = rawScope.trim();
-    if (scope === "id-token") {
-      if (value !== "write") {
-        throw new Error(
-          `Scheduled Op "${spec.name}" adds permission "id-token: ${value}", but GitLab either mints an ` +
-            `OIDC token into a job or does not — there is no read-only half of an \`id_tokens:\` ` +
-            `declaration. Ask for { "id-token": "write" }, or drop the option.`,
-        );
-      }
-      wantsIdToken = true;
-      continue;
-    }
-    throw new Error(
-      `Scheduled Op "${spec.name}" adds permission "${scope}: ${value}", but GitLab CI has no per-job ` +
-        `token-scope mapping — there is no \`permissions:\` key to add it to (#2242). The one scope that ` +
-        `does cross over is "id-token": "write", which becomes an \`id_tokens:\` declaration. Drop the ` +
-        `option here, or generate this Op for github.`,
-    );
-  }
-  return wantsIdToken ? { [ID_TOKEN_NAME]: { aud: ID_TOKEN_AUDIENCE } } : undefined;
-}
-
-/**
- * Refuse a `uses` setup step by name and return the `run` lines that do
- * translate. See the module doc for why a marketplace action is a refusal
- * rather than a silent drop.
- */
-function gitlabSetupScript(spec: ScheduledOpSpec): string[] {
-  const lines: string[] = [];
-  (spec.setup ?? []).forEach((step, index) => {
-    if ("uses" in step) {
-      throw new Error(
-        `Scheduled Op "${spec.name}" setup step ${index + 1} is \`uses: "${step.uses}"\`, a GitHub Actions ` +
-          `marketplace action. GitLab CI jobs run \`script\` lines only, so there is nothing to translate it ` +
-          `into (#2242). Express the setup as a \`{ run }\` entry, or generate this Op for github/forgejo.`,
-      );
-    }
-    lines.push(step.run);
-  });
-  return lines;
-}
-
-/**
- * Validate a spec's `environment` (#2257) on GitLab's own terms. A GitLab job
- * naming an environment that does not exist creates an unprotected one on
- * first deploy rather than failing, so — as on github — the only shapes worth
- * refusing at build time are the ones that could never bind: a blank name,
- * and a `url` that is neither absolute nor a variable expression GitLab
- * expands, which would render as a dead "View deployment" link.
- */
-function assertGitlabEnvironment(name: string, environment: OpEnvironment): void {
-  const where = `Scheduled Op "${name}" environment`;
-  if (environment.name.trim() === "") {
-    throw new Error(
-      `${where} has an empty \`name\`. A GitLab environment is a project object, and its approval ` +
-        `rules live on that object rather than in this file, so a blank name resolves to nothing. ` +
-        `Give it the environment's name, or drop the option.`,
-    );
-  }
-  if (environment.url === undefined) return;
-  const url = environment.url.trim();
-  if (url === "") {
-    throw new Error(
-      `${where} "${environment.name}" has an empty \`url\`. Omit the field rather than setting it to "".`,
-    );
-  }
-  if (!/^https?:\/\//.test(url) && !url.includes("$")) {
-    throw new Error(
-      `${where} "${environment.name}" has \`url: "${environment.url}"\`, which is neither an absolute ` +
-        `http(s) URL nor a variable expression GitLab expands. It becomes the environment's own link, ` +
-        `so a relative path is a dead link on the environment page rather than an error anywhere.`,
-    );
-  }
-}
-
 /**
  * The follow-up line an Op with an `environment` adds under its own header
  * line (#2257). The `environment:` key on the job binds it to the
@@ -401,7 +238,7 @@ function headerLineFor(
       return `#   ${jobName}: merge_request_event onto ${onto}, finding-mode ${mode}${tokenNote}`;
     }
     case "push": {
-      const branches = trigger.branches?.length ? trigger.branches : [DEFAULT_PUSH_BRANCH];
+      const branches = pushBranches(trigger.branches);
       return (
         `#   ${jobName}: push to ${branches.join(", ")}, finding-mode ${mode}${tokenNote}` +
         ` — a gated apply stays green, its pending gate in the log and in ${gateSummaryPath(jobName)}`
@@ -419,7 +256,7 @@ export function generateGitlabOpPipeline(
   ops: ScheduledOpSpec[],
   options: GenerateGitlabOpOptions = {},
 ): GenerateGitlabOpResult {
-  const image = options.image ?? DEFAULT_IMAGE;
+  const image = options.image ?? CI_IMAGE;
   const runCommand = options.runCommand ?? ["chant", "run", "{name}"];
   const beforeScript = options.beforeScript ?? [];
   const extraScript = options.extraScript ?? [];
@@ -437,21 +274,21 @@ export function generateGitlabOpPipeline(
   const cdLine = member && member.dir !== "." && member.dir !== "" ? [`cd ${memberShellDir(member)}`] : [];
 
   const jobs: OpPipelineJob[] = [];
-  const doc: Record<string, unknown> = { stages: [stage] };
-  if (options.variables && Object.keys(options.variables).length > 0) doc.variables = options.variables;
+  const doc: Record<string, unknown> = { stages: [stage], ...nonEmpty("variables", options.variables) };
 
   const opLines: string[] = [];
   let anyCron = false;
 
   for (const spec of ops) {
-    const setupScript = gitlabSetupScript(spec);
-    const idTokens = idTokensFor(spec);
+    const subject = `Scheduled Op "${spec.name}"`;
+    const setupScript = gitlabSetupScript(subject, spec.setup);
+    const idTokens = gitlabIdTokens(spec.name, spec.permissions);
     const findingMode = spec.findingMode ?? "report";
     const trigger = resolveOpTrigger(spec);
     assertTriggerSupportsMode(spec.name, findingMode, trigger);
     if (trigger.kind === "cron") anyCron = true;
 
-    const jobName = jobPrefix + toJobName(spec.name);
+    const jobName = jobPrefix + ciJobName(spec.name);
     jobs.push({ jobName, op: spec.name, trigger, findingMode });
     opLines.push(headerLineFor(spec, trigger, jobName, findingMode));
     if (spec.environment) {
@@ -461,8 +298,9 @@ export function generateGitlabOpPipeline(
 
     // A push job is the one a gate would otherwise paint red on every merge
     // (#2243). Every other trigger keeps the plain one-line invocation.
+    const rules = gitlabRules(subject, trigger, { variable: SELECTOR_VAR, value: spec.name });
     const gated = trigger.kind === "push";
-    const runParts = runCommand.map((part) => part.replace("{name}", spec.name));
+    const runParts = fillCommand(runCommand, spec.name);
     const invocation = gated ? [...runParts, ...GATED_EXIT_FLAG] : runParts;
     const gateSummary = gateSummaryPath(jobName);
 
@@ -483,16 +321,9 @@ export function generateGitlabOpPipeline(
       // next run rather than cancel the current one.
       resource_group: jobName,
       ...(idTokens ? { id_tokens: idTokens } : {}),
-      ...(spec.environment
-        ? {
-            environment: {
-              name: spec.environment.name,
-              ...(spec.environment.url === undefined ? {} : { url: spec.environment.url }),
-            },
-          }
-        : {}),
-      ...(Object.keys(jobVariables).length > 0 ? { variables: jobVariables } : {}),
-      rules: changes && trigger.kind !== "cron" ? rulesFor(spec, trigger).map((r) => ({ ...r, changes })) : rulesFor(spec, trigger),
+      ...(spec.environment ? { environment: environmentDoc(spec.environment) } : {}),
+      ...nonEmpty("variables", jobVariables),
+      rules: changes && trigger.kind !== "cron" ? rules.map((r) => ({ ...r, changes })) : rules,
       script: [...cdLine, ...setupScript, ...beforeScript, invocation.join(" "), ...extraScript],
       // `when: always` because the run this publishes for is the green one: a
       // gated apply succeeds, and the block is the only thing that says a
@@ -520,14 +351,10 @@ export function generateGitlabOpPipeline(
   }
   headerLines.push("#", ...opLines);
 
-  const sections: string[] = [];
-  sections.push(emitYAMLEntry("stages", doc.stages));
-  if (doc.variables) sections.push(emitYAMLEntry("variables", doc.variables));
-  for (const { jobName } of jobs) {
-    sections.push(emitYAMLEntry(jobName, doc[jobName]));
-  }
-
-  const yaml = headerLines.join("\n") + "\n\n" + sections.join("\n\n") + "\n";
+  const yaml = emitGitlabFile(
+    [["stages", doc.stages], ...(doc.variables ? [["variables", doc.variables] as const] : []), ...jobs.map(({ jobName }) => [jobName, doc[jobName]] as const)],
+    headerLines,
+  );
 
   return { files: [{ name: fileName, yaml }], jobs };
 }

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

@@ -60,3 +60,12 @@ describe("generateGitlabOpWavesPipeline", () => {
     expect(() => generateGitlabOpWavesPipeline({ ...waveLevel, hooks: { after: { apply: [{ command: ["./bin/smoke"], onFailure: "approve" }] } } }, { specFile: "waves.json" })).toThrow(/nothing left to hold/);
   });
 });
+
+describe("a wave's environment is checked as an Op's is (#3765)", () => {
+  test("a blank name or a relative url is refused, and a $VARIABLE url passes", () => {
+    const one = (environment: { name: string; url?: string }): OpWavesSpec => ({ ...spec, waves: [{ name: "dev", runs: [{ target: "dev" }], environment }] });
+    expect(() => generateGitlabOpWavesPipeline(one({ name: " " }), { specFile: "waves.json" })).toThrow(/environment has an empty `name`/);
+    expect(() => generateGitlabOpWavesPipeline(one({ name: "dev", url: "dev/app" }), { specFile: "waves.json" })).toThrow(/neither an absolute/);
+    expect(generateGitlabOpWavesPipeline(one({ name: "dev", url: "$CI_ENVIRONMENT_URL" }), { specFile: "waves.json" }).files[0]!.yaml).toContain("url: '$CI_ENVIRONMENT_URL'");
+  });
+});

package/src/components/generate-op-waves-pipeline.ts

@@ -20,79 +20,82 @@
  * pipelines only, which records the digests the merge request's head plans.
  */
 
-import { emitYAMLEntry } from "@intentius/chant/yaml";
+import {
+  assertGitlabBranch,
+  assertGitlabEnvironment,
+  CI_IMAGE,
+  environmentDoc,
+  GITLAB_FULL_HISTORY,
+  GITLAB_MERGE_REQUEST_SOURCE,
+  GITLAB_SCHEDULE_SOURCE,
+  gitlabPushRule,
+  gitlabSetupScript,
+  nonEmpty,
+  pushBranches,
+} from "@intentius/chant/ci-jobs";
 import { opWaveJobs, opWavesResumeCommand, type OpWavesSpec } from "@intentius/chant/op/op-waves";
 import type { OpWavesPipelineOptions, OpWavesPipelineResult } from "@intentius/chant/lexicon";
-
-/** The default image: it carries git, which the runner needs to read the base commit. */
-const OP_WAVES_IMAGE = "node:22";
+import { emitGitlabFile } from "./ci-jobs";
 
 /** Render an Op waves spec as one GitLab CI file, `<name>.gitlab-ci.yml` unless `opsFileName` names another. */
 export function generateGitlabOpWavesPipeline(spec: OpWavesSpec, options: OpWavesPipelineOptions): OpWavesPipelineResult {
   const jobs = opWaveJobs(spec, options.specFile);
-  const image = options.image ?? OP_WAVES_IMAGE;
-  const branches = spec.branches?.length ? spec.branches : ["main"];
-  for (const branch of branches) {
-    if (/["$\\]/.test(branch) || branch.trim() === "") {
-      throw new Error(`Op waves "${spec.name}" filters on branch "${branch}", which cannot go in a GitLab rules: expression.`);
-    }
-  }
-  const rules = branches.map((branch) => ({ if: `$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == "${branch}"` }));
+  const image = options.image ?? CI_IMAGE;
+  const subject = `Op waves "${spec.name}"`;
+  const rules = pushBranches(spec.branches).map((branch) => {
+    assertGitlabBranch(subject, branch);
+    return { if: gitlabPushRule(JSON.stringify(branch)) };
+  });
+  // The setup and environment each wave's jobs carry, checked as an Op's are.
+  const setupOf = spec.waves.map((wave) => gitlabSetupScript(`${subject} wave "${wave.name}"`, wave.setup));
+  for (const wave of spec.waves) if (wave.environment) assertGitlabEnvironment(`${spec.name}/${wave.name}`, wave.environment);
 
   const byReview = spec.waves.some((w) => w.approval === "pr-review");
   const stages = [...(byReview ? ["plans"] : []), ...spec.waves.map((wave, i) => `wave-${i + 1}-${wave.name}`)];
   if (spec.resume) stages.push("resume");
-  const sections: string[] = [emitYAMLEntry("stages", stages)];
-  if (options.variables && Object.keys(options.variables).length > 0) sections.push(emitYAMLEntry("variables", options.variables));
+  const entries: Array<readonly [string, unknown]> = [["stages", stages]];
+  const variables = nonEmpty("variables", options.variables).variables;
+  if (variables) entries.push(["variables", variables]);
+  if (byReview) {
+    entries.push([
+      `${spec.name}-record-plans`,
+      {
+        stage: "plans",
+        image,
+        variables: { ...GITLAB_FULL_HISTORY },
+        rules: [{ if: GITLAB_MERGE_REQUEST_SOURCE }],
+        script: [...(options.beforeScript ?? []), ["chant", "run", "wave", "--spec", options.specFile, "--record-plans"].join(" ")],
+      },
+    ]);
+  }
   for (const job of jobs) {
     const wave = spec.waves[job.wave - 1]!;
-    const setup = (wave.setup ?? []).map((step, index) => {
-      if ("uses" in step) {
-        throw new Error(
-          `Op waves "${spec.name}" wave "${wave.name}" setup step ${index + 1} is \`uses: "${step.uses}"\`, a GitHub ` +
-            `Actions marketplace action. GitLab CI runs script lines only; express it as a { run } entry.`,
-        );
-      }
-      return step.run;
-    });
-    sections.push(
-      emitYAMLEntry(job.jobName, {
+    const setup = setupOf[job.wave - 1]!;
+    entries.push([
+      job.jobName,
+      {
         stage: stages[job.wave - 1 + (byReview ? 1 : 0)],
         image,
         resource_group: `${spec.name}-${wave.name}`,
-        ...(wave.environment
-          ? { environment: { name: wave.environment.name, ...(wave.environment.url ? { url: wave.environment.url } : {}) } }
-          : {}),
-        variables: { GIT_DEPTH: "0", ...(wave.variables ?? {}) },
+        ...(wave.environment ? { environment: environmentDoc(wave.environment) } : {}),
+        variables: { ...GITLAB_FULL_HISTORY, ...(wave.variables ?? {}) },
         rules,
         ...(job.needs.length > 0 ? { needs: job.needs } : {}),
         script: [...setup, ...(options.beforeScript ?? []), job.command.join(" "), ...(options.extraScript ?? [])],
         ...(job.kind === "decide" ? { artifacts: { when: "always", paths: [job.record!], expire_in: "30 days" } } : {}),
-      }),
-    );
+      },
+    ]);
   }
   if (spec.resume) {
-    sections.push(
-      emitYAMLEntry(`${spec.name}-resume`, {
+    entries.push([
+      `${spec.name}-resume`,
+      {
         stage: "resume",
         image,
-        rules: [{ if: '$CI_PIPELINE_SOURCE == "schedule"' }],
+        rules: [{ if: GITLAB_SCHEDULE_SOURCE }],
         script: [...(options.beforeScript ?? []), opWavesResumeCommand(spec).join(" ")],
-      }),
-    );
-  }
-  if (byReview) {
-    sections.splice(
-      options.variables && Object.keys(options.variables).length > 0 ? 2 : 1,
-      0,
-      emitYAMLEntry(`${spec.name}-record-plans`, {
-        stage: "plans",
-        image,
-        variables: { GIT_DEPTH: "0" },
-        rules: [{ if: '$CI_PIPELINE_SOURCE == "merge_request_event"' }],
-        script: [...(options.beforeScript ?? []), ["chant", "run", "wave", "--spec", options.specFile, "--record-plans"].join(" ")],
-      }),
-    );
+      },
+    ]);
   }
   const header = [
     `# chant Op waves "${spec.name}": one stage per wave, each needing the one before.`,
@@ -103,5 +106,5 @@ export function generateGitlabOpWavesPipeline(spec: OpWavesSpec, options: OpWave
       : []),
   ];
   const name = options.opsFileName ?? `${spec.name}.gitlab-ci.yml`;
-  return { files: [{ name, yaml: header.join("\n") + "\n\n" + sections.join("\n\n") + "\n" }], jobs };
+  return { files: [{ name, yaml: emitGitlabFile(entries, header) }], jobs };
 }

package/src/components/generate-pipeline.ts

@@ -32,11 +32,19 @@
  * touching the component declarations.
  */
 
-import { emitYAMLEntry } from "@intentius/chant/yaml";
+import {
+  assertGitlabBranch,
+  CI_IMAGE,
+  ciJobName,
+  fillCommand,
+  GITLAB_FULL_HISTORY,
+  GITLAB_MERGE_REQUEST_SOURCE,
+  gitlabPushRule,
+} from "@intentius/chant/ci-jobs";
 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_APPLY_RECORD, PR_LOOP_IMAGE, PR_LOOP_REPORT_DIR, prApplyGroup, prApplyRecordKey, prLoopJobs, prLoopSetup } from "@intentius/chant/components/pr-pipeline";
+import { PR_APPLY_RECORD, PR_LOOP_REPORT_DIR, prApplyGroup, prApplyRecordKey, prLoopJobs, prLoopSetup } from "@intentius/chant/components/pr-pipeline";
 import { memberGitlabChanges, memberRepoPath, memberShellDir } from "@intentius/chant/lexicon";
 import type {
   ComponentPipelineJob as GeneratedJob,
@@ -45,14 +53,9 @@ import type {
   PipelineMember,
 } from "@intentius/chant/lexicon";
 
-export type { GeneratedJob, GenerateGitlabOptions, GenerateGitlabResult };
-
-/** GitLab CI job names must be safe YAML keys; component names are already kebab-case in every fixture, but normalize defensively. */
-function toJobName(componentName: string): string {
-  return componentName.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
-}
+import { emitGitlabFile } from "./ci-jobs";
 
-const DEFAULT_IMAGE = "node:22";
+export type { GeneratedJob, GenerateGitlabOptions, GenerateGitlabResult };
 
 /**
  * Synthesize a `.gitlab-ci.yml` pipeline from a set of components: one stage
@@ -67,7 +70,7 @@ export function generateGitlabPipeline(
   options: GenerateGitlabOptions = {},
 ): GenerateGitlabResult {
   const env = options.env ?? "production";
-  const image = options.image ?? (options.prLoop || options.gatedWaves ? PR_LOOP_IMAGE : DEFAULT_IMAGE);
+  const image = options.image ?? CI_IMAGE;
   const runCommand = options.runCommand ?? ["chant", "run", "--components", "{name}", "--env", env];
   const beforeScript = options.beforeScript ?? [];
   const extraScript = options.extraScript ?? [];
@@ -126,7 +129,7 @@ export function generateGitlabPipeline(
   const jobs: GeneratedJob[] = [];
   const jobNameByComponent = new Map<string, string>();
   for (const wave of waves) {
-    for (const name of wave) jobNameByComponent.set(name, toJobName(name));
+    for (const name of wave) jobNameByComponent.set(name, ciJobName(name));
   }
 
   const doc: Record<string, unknown> = {};
@@ -152,7 +155,7 @@ export function generateGitlabPipeline(
       // Build the run invocation, then append output-threading flags: seed from
       // each dependency's dumped outputs, and dump this component's own outputs
       // if a dependent will need them.
-      const runParts = runCommand.map((part) => part.replace("{name}", name));
+      const runParts = fillCommand(runCommand, name);
       for (const dep of component.dependsOn ?? []) runParts.push("--seed-outputs", outputsFile(dep));
       if (dependedUpon.has(name)) runParts.push("--dump-outputs", outputsFile(name));
       if (pinned.has(name)) runParts.push("--digest-file", digestFile(name));
@@ -178,7 +181,7 @@ export function generateGitlabPipeline(
 
   let promoteJob: string | undefined;
   if (promoteTo !== undefined) {
-    promoteJob = `promote-${toJobName(promoteTo)}`;
+    promoteJob = `promote-${ciJobName(promoteTo)}`;
     if (promoteJob in doc) {
       throw new Error(`the promote job "${promoteJob}" has the same name as a component job; rename the component`);
     }
@@ -200,20 +203,17 @@ export function generateGitlabPipeline(
     promoteJob = scopeToMember(doc, jobs, promoteJob, options.member, env);
   }
 
-  const sections: string[] = [];
-  sections.push(emitYAMLEntry("workflow", doc.workflow));
   // The promote stage is YAML only: `stages` in the result stays one entry
   // per graph wave.
   const yamlStages = promoteJob ? [...stages, "promote"] : stages;
-  sections.push(emitYAMLEntry("stages", yamlStages));
-  if (doc.variables) sections.push(emitYAMLEntry("variables", doc.variables));
-  for (const job of jobs) {
-    const props = doc[job.jobName] as Record<string, unknown>;
-    sections.push(emitYAMLEntry(job.jobName, props));
-  }
-  if (promoteJob) sections.push(emitYAMLEntry(promoteJob, doc[promoteJob]));
-
-  return { yaml: sections.join("\n\n") + "\n", stages, jobs, env };
+  const yaml = emitGitlabFile([
+    ["workflow", doc.workflow],
+    ["stages", yamlStages],
+    ["variables", doc.variables],
+    ...jobs.map((job) => [job.jobName, doc[job.jobName]] as const),
+    ...(promoteJob ? [[promoteJob, doc[promoteJob]] as const] : []),
+  ]);
+  return { yaml, stages, jobs, env };
 }
 
 /**
@@ -244,20 +244,20 @@ function gatedWaveGitlabPipeline(
     doc[job.jobName] = {
       stage: job.jobName,
       image,
-      variables: { GIT_DEPTH: "0" },
+      variables: { ...GITLAB_FULL_HISTORY },
       script: [...prLoopSetup(image), ...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 };
+  const yaml = emitGitlabFile([
+    ["workflow", doc.workflow],
+    ["stages", stages],
+    ["variables", doc.variables],
+    ...jobs.map((job) => [job.jobName, doc[job.jobName]] as const),
+  ]);
+  return { yaml, stages, jobs, env };
 }
 
 /**
@@ -297,9 +297,9 @@ function prLoopGitlabPipeline(
   const reportPath = member ? memberRepoPath(member, PR_LOOP_REPORT_DIR) : PR_LOOP_REPORT_DIR;
   const planJob = member ? `${member.name}-plan` : "plan";
   const applyJob = member ? `${member.name}-apply` : "apply";
-  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 onMergeRequest = GITLAB_MERGE_REQUEST_SOURCE;
+  if (loop.branch !== undefined) assertGitlabBranch("The merge-request pipeline", loop.branch);
+  const onMerge = gitlabPushRule(loop.branch ? JSON.stringify(loop.branch) : "$CI_DEFAULT_BRANCH");
   // A member's jobs start in its directory, after the image's install lines.
   const enter = rooted ? [] : [`cd ${memberShellDir(member!)}`];
   const script = (job: typeof plan): string[] => [...prLoopSetup(image), ...enter, ...beforeScript, ...(job.setup ?? []), job.command, ...extraScript];
@@ -309,7 +309,7 @@ function prLoopGitlabPipeline(
     // the rules every member shares and no name: two names would collide.
     workflow: { ...(member ? {} : { name: `chant-pr-${env}` }), rules: [{ if: onMergeRequest }, { if: onMerge }] },
     stages,
-    variables: { ...options.variables, CHANT_ENV: env, GIT_DEPTH: "0" },
+    variables: { ...options.variables, CHANT_ENV: env, ...GITLAB_FULL_HISTORY },
     [planJob]: {
       stage: "plan",
       image,
@@ -339,8 +339,8 @@ function prLoopGitlabPipeline(
     { jobName: planJob, component: "merge request plan", stage: "plan", needs: [] },
     { jobName: applyJob, component: "merge request apply", stage: "apply", needs: [] },
   ];
-  const sections = ["workflow", "stages", "variables", planJob, applyJob].map((key) => emitYAMLEntry(key, doc[key]));
-  return { yaml: sections.join("\n\n") + "\n", stages, jobs, env };
+  const yaml = emitGitlabFile(["workflow", "stages", "variables", planJob, applyJob].map((key) => [key, doc[key]] as const));
+  return { yaml, stages, jobs, env };
 }
 
 /**

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

@@ -119,3 +119,9 @@ describe("the GitLab merge-request pipeline", () => {
     expect(apply.cache).toEqual({ key: "chant-apply.network.prod-$CI_COMMIT_SHA", paths: ["infra/network/.chant/pr-resume/pr-apply.json"], when: "always" });
   });
 });
+
+describe("the merge-request pipeline's branch (#3765)", () => {
+  test("a branch that would break the rules: expression is refused, as an Op's is", () => {
+    expect(() => generateGitlabPipeline(ESTATE, { env: "prod", prLoop: { branch: "re$lease" } })).toThrow(/filters on branch "re\$lease"/);
+  });
+});