@intentius/chant-lexicon-gitlab 0.61.0 → 0.62.0

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

@@ -90,6 +90,19 @@
  * job log, since the invocation carries no `--json`. There is no follow-up
  * notice job: it would need a forge API call and a token this generator does
  * not require of a `report`-mode Op.
+ *
+ * A spec's own `variables` (#2290) is the one per-Op option that is cheap
+ * here rather than merely possible: this generator already puts a job-level
+ * `variables:` block on a gated job (`CHANT_GATE_SUMMARY` above), so a spec's
+ * own entries merge into the same mapping instead of asking for a shape
+ * GitLab has no concept of. `options.variables` (forge-wide) is unaffected —
+ * it keeps landing on the file's own top-level `variables:`, read by every
+ * job the way a GitLab CI/CD variable always is — and a spec's own entry wins
+ * the job over a same-named top-level one, the ordinary variable-precedence
+ * GitLab already gives a job over the pipeline. `CHANT_GATE_SUMMARY` itself is
+ * internal and always wins at the job over a same-named spec entry, so a
+ * caller cannot point the gate block somewhere the `artifacts:` declaration
+ * beside it does not also point.
  */
 import type { ComponentPipelineOptions as GenerateGitlabOpOptions, OpPipelineResult as GenerateGitlabOpResult, ScheduledOpSpec } from "@intentius/chant/lexicon";
 export type { GenerateGitlabOpOptions, GenerateGitlabOpResult };

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4FG;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;AAkQhE;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CA0FxB"}
+{"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,CAwGxB"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "c68e008d70828d518ed8908e47729c0783c3b473fe4997f54d67366ae58be0b5",
+    "manifest.json": "019c4c5936e680b98f9f5e5916884cd68af6e7866d6be9522dc5d69068761197",
     "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": "40909e34fc71fe00e52febba2c3bd87e1287416e19c8ab58a5f769a24af7f34e"
+  "composite": "5961fea1f006be2aab006533a1d585287c35827438c487f5be8590685bc72a56"
 }

package/dist/manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-gitlab",
-  "version": "0.61.0",
+  "version": "0.62.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.61.0",
-    "@intentius/chant-lexicon-github": "^0.61.0",
+    "@intentius/chant": "^0.62.0",
+    "@intentius/chant-lexicon-github": "^0.62.0",
     "typescript": "^5.9.3"
   },
   "peerDependenciesMeta": {

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

@@ -26,10 +26,10 @@ describe("generateGitlabOpPipeline: one file, one job per scheduled Op", () => {
     const result = generateGitlabOpPipeline(specs);
 
     expect(result.files).toHaveLength(1);
-    expect(result.files[0].name).toBe("scheduled-ops.gitlab-ci.yml");
+    expect(result.files[0].name).toBe("ops.gitlab-ci.yml");
 
     const parsed = parseYAML(result.files[0].yaml);
-    expect(parsed.stages).toEqual(["scheduled-ops"]);
+    expect(parsed.stages).toEqual(["ops"]);
     expect(parsed["actions-audit"]).toBeDefined();
     expect(parsed["prod-reconcile"]).toBeDefined();
   });
@@ -39,7 +39,7 @@ describe("generateGitlabOpPipeline: one file, one job per scheduled Op", () => {
     const parsed = parseYAML(result.files[0].yaml);
     const job = parsed["actions-audit"] as Record<string, unknown>;
 
-    expect(job.stage).toBe("scheduled-ops");
+    expect(job.stage).toBe("ops");
     expect(job.rules).toEqual([
       { if: '$CI_PIPELINE_SOURCE == "schedule" && $CHANT_SCHEDULED_OP == "actions-audit"' },
     ]);
@@ -66,7 +66,72 @@ describe("generateGitlabOpPipeline: one file, one job per scheduled Op", () => {
     expect(result.files).toHaveLength(1);
     expect(result.jobs).toEqual([]);
     const parsed = parseYAML(result.files[0].yaml);
-    expect(parsed.stages).toEqual(["scheduled-ops"]);
+    expect(parsed.stages).toEqual(["ops"]);
+  });
+});
+
+/**
+ * #2293 — the stage and file name follow the pipeline's actual contents
+ * instead of the cron-only-era constant "scheduled-ops", and both are
+ * overridable via `ComponentPipelineOptions` the way every other generator
+ * knob is (`image`, `variables`, ...).
+ */
+describe("generateGitlabOpPipeline: the stage and file name (#2293)", () => {
+  test("a mixed-trigger project's stage and file no longer say 'scheduled'", () => {
+    // cron + merge_request + push in one project, exactly the shape that
+    // made "scheduled-ops" wrong: a GitLab UI would show live-check-style
+    // pull-request/push jobs grouped under a stage claiming they run on a
+    // schedule.
+    const result = generateGitlabOpPipeline([
+      { name: "nightly", schedule: "0 6 * * *" },
+      { name: "live-plan", trigger: { kind: "pull_request", branches: ["main"] } },
+      { name: "live-apply", trigger: { kind: "push", branches: ["main"] } },
+    ]);
+
+    expect(result.files[0].name).not.toMatch(/scheduled/);
+    expect(result.files[0].name).toBe("ops.gitlab-ci.yml");
+
+    const parsed = parseYAML(result.files[0].yaml);
+    expect(parsed.stages).toEqual(["ops"]);
+    expect((parsed["live-plan"] as Record<string, unknown>).stage).toBe("ops");
+    expect((parsed["live-apply"] as Record<string, unknown>).stage).toBe("ops");
+    expect((parsed.nightly as Record<string, unknown>).stage).toBe("ops");
+  });
+
+  test("the header names the stage every job runs in", () => {
+    const yaml = generateGitlabOpPipeline([{ name: "actions-audit", schedule: "0 6 * * *" }]).files[0]
+      .yaml;
+    expect(yaml).toContain('one job per Op under stage "ops"');
+  });
+
+  test("opsStage overrides the stage, and the file name follows it by default", () => {
+    const result = generateGitlabOpPipeline([{ name: "actions-audit", schedule: "0 6 * * *" }], {
+      opsStage: "deploy",
+    });
+    expect(result.files[0].name).toBe("deploy.gitlab-ci.yml");
+    const parsed = parseYAML(result.files[0].yaml);
+    expect(parsed.stages).toEqual(["deploy"]);
+    expect((parsed["actions-audit"] as Record<string, unknown>).stage).toBe("deploy");
+    expect(result.files[0].yaml).toContain('one job per Op under stage "deploy"');
+  });
+
+  test("opsFileName overrides the file name independently of opsStage", () => {
+    const result = generateGitlabOpPipeline([{ name: "actions-audit", schedule: "0 6 * * *" }], {
+      opsStage: "deploy",
+      opsFileName: "ci/deploy-ops.yml",
+    });
+    expect(result.files[0].name).toBe("ci/deploy-ops.yml");
+    const parsed = parseYAML(result.files[0].yaml);
+    expect(parsed.stages).toEqual(["deploy"]);
+  });
+
+  test("a blank opsStage or opsFileName is refused by name", () => {
+    expect(() =>
+      generateGitlabOpPipeline([{ name: "actions-audit", schedule: "0 6 * * *" }], { opsStage: "  " }),
+    ).toThrow(/opsStage.*empty/s);
+    expect(() =>
+      generateGitlabOpPipeline([{ name: "actions-audit", schedule: "0 6 * * *" }], { opsFileName: "" }),
+    ).toThrow(/opsFileName.*empty/s);
   });
 });
 
@@ -375,19 +440,23 @@ describe("generateGitlabOpPipeline: a deployment environment (#2257)", () => {
   /**
    * The document a cron spec with no `environment` emits. #2257 pinned this to
    * prove its option is additive; #2256 moved two lines of it and it is
-   * re-pinned rather than loosened, so it still proves the same thing.
+   * re-pinned rather than loosened, so it still proves the same thing. #2293
+   * re-pinned it again: the stage (and the header line naming it) moved from
+   * the constant "scheduled-ops" to the default "ops".
    *
    * What moved: the header's opening paragraph, because a merge_request_event
    * or push job needs no Pipeline Schedule and the cron instructions are now
-   * printed only for the Ops that do; and `resource_group`, which every job
-   * gains as GitLab's stand-in for github's per-Op concurrency group. The
-   * cron job's own rule, script and stage are byte-for-byte what they were.
+   * printed only for the Ops that do, and because the header now names the
+   * stage every job runs in (#2293); `resource_group`, which every job gains
+   * as GitLab's stand-in for github's per-Op concurrency group; and the
+   * `stage:`/`stages:` values themselves (#2293). The cron job's own rule and
+   * script are byte-for-byte what they were.
    */
   const YAML_BEFORE_2257 =
     [
-      "# chant Ops (#927, #2084) — one job per Op, each selected by its own",
-      "# rules:. A merge_request_event or push job needs no setup; its rule",
-      "# fires on the event itself.",
+      '# chant Ops (#927, #2084, #2293) — one job per Op under stage "ops", each',
+      "# selected by its own rules:. A merge_request_event or push job needs no",
+      "# setup; its rule fires on the event itself.",
       "#",
       "# GitLab has no in-file cron. Create one Pipeline Schedule per cron Op",
       "# below (Settings > CI/CD > Schedules): set its cron to the value noted",
@@ -398,10 +467,10 @@ describe("generateGitlabOpPipeline: a deployment environment (#2257)", () => {
         " — needs a GITLAB_TOKEN CI/CD variable (masked, scope: api)",
       "",
       "stages:",
-      "  - scheduled-ops",
+      "  - ops",
       "",
       "actions-audit:",
-      "  stage: scheduled-ops",
+      "  stage: ops",
       "  image: node:22-slim",
       "  resource_group: actions-audit",
       "  rules:",
@@ -456,3 +525,51 @@ describe("generateGitlabOpPipeline: a deployment environment (#2257)", () => {
     ).toThrow(/neither an absolute http\(s\) URL nor a variable expression/);
   });
 });
+
+/**
+ * chant #2290 — per-Op credentials. Cheap here because a gated job already
+ * carries a job-level `variables:` block (`CHANT_GATE_SUMMARY`); a spec's own
+ * `variables` merge into the same block rather than asking for a shape
+ * GitLab has no concept of.
+ */
+describe("generateGitlabOpPipeline: per-Op variables merge into the job's own variables: (#2290)", () => {
+  const CREDENTIAL = { AWS_ACCESS_KEY_ID: "${{ secrets.AWS_ACCESS_KEY_ID }}" };
+
+  test("a spec with no variables emits no job-level variables:, even when top-level variables: is set", () => {
+    const result = generateGitlabOpPipeline(
+      [{ name: "live-check", trigger: { kind: "pull_request", branches: ["main"] } }],
+      { variables: { CHANT_FORGE: "gitlab" } },
+    );
+    const job = parseYAML(result.files[0].yaml)["live-check"] as Record<string, unknown>;
+    expect(job.variables).toBeUndefined();
+  });
+
+  test("a spec's own variables land on the job's variables:, beside the top-level variables:", () => {
+    const result = generateGitlabOpPipeline(
+      [{ name: "live-apply", trigger: { kind: "pull_request" }, variables: CREDENTIAL }],
+      { variables: { CHANT_FORGE: "gitlab" } },
+    );
+    const job = parseYAML(result.files[0].yaml)["live-apply"] as { variables?: Record<string, string> };
+    expect(job.variables).toEqual(CREDENTIAL);
+  });
+
+  test("on a gated push job, a spec's own variables merge alongside CHANT_GATE_SUMMARY rather than replacing it", () => {
+    const result = generateGitlabOpPipeline([
+      { name: "live-apply", trigger: { kind: "push", branches: ["main"] }, variables: CREDENTIAL },
+    ]);
+    const job = parseYAML(result.files[0].yaml)["live-apply"] as { variables?: Record<string, string> };
+    expect(job.variables).toEqual({ ...CREDENTIAL, CHANT_GATE_SUMMARY: "chant-gate-live-apply.md" });
+  });
+
+  test("CHANT_GATE_SUMMARY always wins a name collision — a caller cannot repoint the gate artifact", () => {
+    const result = generateGitlabOpPipeline([
+      {
+        name: "live-apply",
+        trigger: { kind: "push", branches: ["main"] },
+        variables: { CHANT_GATE_SUMMARY: "somewhere-else.md" },
+      },
+    ]);
+    const job = parseYAML(result.files[0].yaml)["live-apply"] as { variables?: Record<string, string> };
+    expect(job.variables?.CHANT_GATE_SUMMARY).toBe("chant-gate-live-apply.md");
+  });
+});

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

@@ -90,6 +90,19 @@
  * job log, since the invocation carries no `--json`. There is no follow-up
  * notice job: it would need a forge API call and a token this generator does
  * not require of a `report`-mode Op.
+ *
+ * A spec's own `variables` (#2290) is the one per-Op option that is cheap
+ * here rather than merely possible: this generator already puts a job-level
+ * `variables:` block on a gated job (`CHANT_GATE_SUMMARY` above), so a spec's
+ * own entries merge into the same mapping instead of asking for a shape
+ * GitLab has no concept of. `options.variables` (forge-wide) is unaffected —
+ * it keeps landing on the file's own top-level `variables:`, read by every
+ * job the way a GitLab CI/CD variable always is — and a spec's own entry wins
+ * the job over a same-named top-level one, the ordinary variable-precedence
+ * GitLab already gives a job over the pipeline. `CHANT_GATE_SUMMARY` itself is
+ * internal and always wins at the job over a same-named spec entry, so a
+ * caller cannot point the gate block somewhere the `artifacts:` declaration
+ * beside it does not also point.
  */
 
 import { emitYAML } from "@intentius/chant/yaml";
@@ -112,7 +125,22 @@ function toJobName(opName: string): string {
 }
 
 const DEFAULT_IMAGE = "node:22-slim";
-const STAGE = "scheduled-ops";
+
+/**
+ * Default stage every generated job runs in, and the default base of the
+ * generated file's name (#2293). Overridable via `options.opsStage` (and the
+ * file name separately via `options.opsFileName`) — see
+ * {@link GenerateGitlabOpOptions} (`ComponentPipelineOptions` in
+ * `../../../../packages/core/src/lexicon.ts`).
+ *
+ * `"scheduled-ops"` before #2293: a constant from when this generator was
+ * cron-only, left in place through #2084/#2256 even after every
+ * merge-request and push job started sharing it, so a GitLab UI showed
+ * `live-check`/`live-plan`/`live-apply`/`live-adopt` grouped under a stage
+ * called "scheduled" and a consuming project's `include:` named a file that
+ * said the opposite of what it held.
+ */
+const DEFAULT_STAGE = "ops";
 
 /** The CI/CD variable a Pipeline Schedule sets to select which job it runs. */
 const SELECTOR_VAR = "CHANT_SCHEDULED_OP";
@@ -179,6 +207,26 @@ function assertBranchName(specName: string, branch: string): void {
   }
 }
 
+/** 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() === "") {
+    throw new Error(
+      `The gitlab Op generator's \`opsStage\` option is empty. Name the stage every generated job shares, ` +
+        `or drop the option to keep the default "${DEFAULT_STAGE}".`,
+    );
+  }
+}
+
+/** Refuse a blank `opsFileName` (#2293): `main.ts` in a consuming project writes `result.files[].name` straight to disk. */
+function assertOpsFileName(fileName: string): void {
+  if (fileName.trim() === "") {
+    throw new Error(
+      `The gitlab Op generator's \`opsFileName\` option is empty. Name the generated file, or drop the ` +
+        `option to derive it from \`opsStage\`.`,
+    );
+  }
+}
+
 /**
  * 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
@@ -375,9 +423,13 @@ export function generateGitlabOpPipeline(
   const runCommand = options.runCommand ?? ["chant", "run", "{name}"];
   const beforeScript = options.beforeScript ?? [];
   const extraScript = options.extraScript ?? [];
+  const stage = options.opsStage ?? DEFAULT_STAGE;
+  assertOpsStage(stage);
+  const fileName = options.opsFileName ?? `${stage}.gitlab-ci.yml`;
+  assertOpsFileName(fileName);
 
   const jobs: OpPipelineJob[] = [];
-  const doc: Record<string, unknown> = { stages: [STAGE] };
+  const doc: Record<string, unknown> = { stages: [stage] };
   if (options.variables && Object.keys(options.variables).length > 0) doc.variables = options.variables;
 
   const opLines: string[] = [];
@@ -406,8 +458,18 @@ export function generateGitlabOpPipeline(
     const invocation = gated ? [...runParts, ...GATED_EXIT_FLAG] : runParts;
     const gateSummary = gateSummaryPath(jobName);
 
+    // Per-Op credentials (#2290): a spec's own `variables` merge into this
+    // job's `variables:` block, the same block the gated apply's
+    // `CHANT_GATE_SUMMARY` already occupies below — GATE_SUMMARY_VAR is
+    // internal and listed last, so it always wins a name collision rather
+    // than a caller being able to repoint the gate block's own artifact path.
+    const jobVariables: Record<string, string> = {
+      ...(spec.variables ?? {}),
+      ...(gated ? { [GATE_SUMMARY_VAR]: gateSummary } : {}),
+    };
+
     doc[jobName] = {
-      stage: STAGE,
+      stage,
       image,
       // GitLab's stand-in for github's per-Op concurrency group: queue the
       // next run rather than cancel the current one.
@@ -421,7 +483,7 @@ export function generateGitlabOpPipeline(
             },
           }
         : {}),
-      ...(gated ? { variables: { [GATE_SUMMARY_VAR]: gateSummary } } : {}),
+      ...(Object.keys(jobVariables).length > 0 ? { variables: jobVariables } : {}),
       rules: rulesFor(spec, trigger),
       script: [...setupScript, ...beforeScript, invocation.join(" "), ...extraScript],
       // `when: always` because the run this publishes for is the green one: a
@@ -435,9 +497,9 @@ export function generateGitlabOpPipeline(
   }
 
   const headerLines = [
-    "# chant Ops (#927, #2084) — one job per Op, each selected by its own",
-    "# rules:. A merge_request_event or push job needs no setup; its rule",
-    "# fires on the event itself.",
+    `# chant Ops (#927, #2084, #2293) — one job per Op under stage "${stage}", each`,
+    "# selected by its own rules:. A merge_request_event or push job needs no",
+    "# setup; its rule fires on the event itself.",
   ];
   if (anyCron) {
     headerLines.push(
@@ -459,5 +521,5 @@ export function generateGitlabOpPipeline(
 
   const yaml = headerLines.join("\n") + "\n\n" + sections.join("\n\n") + "\n";
 
-  return { files: [{ name: "scheduled-ops.gitlab-ci.yml", yaml }], jobs };
+  return { files: [{ name: fileName, yaml }], jobs };
 }