@intentius/chant 0.59.0 → 0.60.0

package/src/op/gate-summary.test.ts

@@ -0,0 +1,62 @@
+/**
+ * The pending-gate block a CI run leaves where people actually look (#2243),
+ * and the second surface GitLab needs for it (#2256).
+ *
+ * GitHub Actions, Forgejo Actions and Gitea all hand a step a markdown
+ * scratchpad through `GITHUB_STEP_SUMMARY`. GitLab CI has no equivalent at
+ * all — a job's surfaces are its log and its artifacts — so `CHANT_GATE_SUMMARY`
+ * names a path the generated GitLab job also declares under `artifacts:`. One
+ * more environment variable, the same block, still no API call and no token.
+ */
+
+import { mkdtempSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, test, expect } from "vitest";
+import { gatedRunSummaryMarkdown, writeGatedRunSummary } from "./gate-summary";
+
+const summary = { op: "app-apply", gate: "approve-app-apply", expiresAt: "2026-09-08T00:00:00Z" };
+
+function tempPath(name: string): string {
+  return join(mkdtempSync(join(tmpdir(), "chant-gate-")), name);
+}
+
+describe("gatedRunSummaryMarkdown (#2243)", () => {
+  test("names the gate, the exact approve command and the ledger path", () => {
+    const md = gatedRunSummaryMarkdown(summary);
+    expect(md).toContain("Waiting on gate `approve-app-apply`");
+    expect(md).toContain("chant approve app-apply approve-app-apply --approver <you>");
+    expect(md).toContain("_gates/app-apply.jsonl");
+  });
+});
+
+describe("writeGatedRunSummary surfaces (#2243, #2256)", () => {
+  test("writes to GITHUB_STEP_SUMMARY where the forge sets one", () => {
+    const path = tempPath("step-summary.md");
+    expect(writeGatedRunSummary(summary, { GITHUB_STEP_SUMMARY: path })).toBe(path);
+    expect(readFileSync(path, "utf8")).toContain("approve-app-apply");
+  });
+
+  test("writes to CHANT_GATE_SUMMARY where the forge sets none — GitLab's artifact path", () => {
+    const path = tempPath("chant-gate-app-apply.md");
+    expect(writeGatedRunSummary(summary, { CHANT_GATE_SUMMARY: path })).toBe(path);
+    expect(readFileSync(path, "utf8")).toContain("chant approve app-apply approve-app-apply");
+  });
+
+  test("the forge's own variable wins when both are set", () => {
+    const forge = tempPath("step-summary.md");
+    const artifact = tempPath("chant-gate-app-apply.md");
+    expect(
+      writeGatedRunSummary(summary, { GITHUB_STEP_SUMMARY: forge, CHANT_GATE_SUMMARY: artifact }),
+    ).toBe(forge);
+    expect(existsSync(artifact)).toBe(false);
+  });
+
+  test("a run with neither variable writes nothing and reports nothing", () => {
+    expect(writeGatedRunSummary(summary, {})).toBeUndefined();
+  });
+
+  test("an unwritable path is swallowed: a decided run does not change outcome over a scratchpad", () => {
+    expect(writeGatedRunSummary(summary, { CHANT_GATE_SUMMARY: "/no/such/dir/gate.md" })).toBeUndefined();
+  });
+});

package/src/op/gate-summary.ts

@@ -8,9 +8,14 @@
  * markdown scratchpad through `GITHUB_STEP_SUMMARY`, rendered at the top of
  * the run page; anything else that sets the variable gets the same block.
  *
- * That is the whole forge coupling: one environment variable, appended to
- * when it is set, and nothing at all when it is not. No API call, no token,
- * no flag to turn it on.
+ * GitLab CI sets no such variable and has no step summary at all: a job's
+ * surfaces are its log and its artifacts (#2256). So `CHANT_GATE_SUMMARY`
+ * names a second path, which the generated GitLab job sets to a file it also
+ * declares under `artifacts:`. Same block, same rule, one more variable.
+ *
+ * That is the whole forge coupling: two environment variables, appended to
+ * whichever is set, and nothing at all when neither is. No API call, no
+ * token, no flag to turn it on.
  */
 
 import { appendFileSync } from "node:fs";
@@ -63,7 +68,14 @@ export function gatedRunSummaryMarkdown(summary: GatedRunSummary): string {
 
 /**
  * Append {@link gatedRunSummaryMarkdown} to the file `GITHUB_STEP_SUMMARY`
- * names, when the variable is set and the file can be written.
+ * names, or, where the forge sets no such variable, the one
+ * `CHANT_GATE_SUMMARY` names (#2256) — when it is set and the file can be
+ * written.
+ *
+ * The forge's own variable wins where both are set: a step summary is
+ * rendered on the run page, an artifact has to be downloaded, and writing
+ * both would put the same block in two places on a forge that already shows
+ * one of them.
  *
  * Returns the path written, or `undefined` when there was nothing to write to.
  * A write that fails is swallowed: a run that already decided its outcome must
@@ -73,7 +85,7 @@ export function writeGatedRunSummary(
   summary: GatedRunSummary,
   env: NodeJS.ProcessEnv = process.env,
 ): string | undefined {
-  const path = env.GITHUB_STEP_SUMMARY;
+  const path = env.GITHUB_STEP_SUMMARY || env.CHANT_GATE_SUMMARY;
   if (!path) return undefined;
   try {
     appendFileSync(path, gatedRunSummaryMarkdown(summary));

package/src/params.ts

@@ -6,7 +6,7 @@
  * is a deploy-time CloudFormation parameter: it emits a `Parameters:` block and
  * resolves when the STACK deploys. A build-time parameter resolves before the
  * template is even synthesized — its value can change WHICH resources are
- * produced at all (loomster's `LOOM_TIER` selecting `light` vs `production` vs
+ * produced at all (a `tier` parameter selecting `light` vs `production` vs
  * `production-ha`), which a deploy-time `Parameter` structurally cannot do.
  *
  * Project source never reads `process.env` directly to vary a build — that

package/src/project-root.ts

@@ -12,8 +12,8 @@ import { dirname, join, resolve } from "path";
  * `src/<stack>` layout — `chant build src/<stack>` two or more levels below
  * the project root — silently never found the root config: `buildParams`'
  * declared `env:` mappings went inert, `ownership`/`lint.policies`/etc quietly
- * fell back to defaults, and nothing warned (loomster#162: `LOOM_TIER`/
- * `LOOM_ENV` inert under every `npm run synth:*` for two releases).
+ * fell back to defaults, and nothing warned. That failure ran under every
+ * `npm run synth:*` of one project for two releases before anyone noticed it.
  *
  * `findProjectConfig` is the one walk every config-discovery call site now
  * shares. It stops at the first of: