@intentius/chant 0.124.75 → 0.124.77

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (147) hide show
  1. package/dist/__fixtures__/agent-guard/plywood.d.ts +8 -0
  2. package/dist/__fixtures__/agent-guard/plywood.d.ts.map +1 -0
  3. package/dist/__fixtures__/agent-guard/plywood.js +19 -0
  4. package/dist/__fixtures__/agent-guard/terragucci.d.ts +8 -0
  5. package/dist/__fixtures__/agent-guard/terragucci.d.ts.map +1 -0
  6. package/dist/__fixtures__/agent-guard/terragucci.js +30 -0
  7. package/dist/__fixtures__/gated-ledger.d.ts +10 -0
  8. package/dist/__fixtures__/gated-ledger.d.ts.map +1 -0
  9. package/dist/__fixtures__/gated-ledger.js +51 -0
  10. package/dist/agent-guard.d.ts +143 -0
  11. package/dist/agent-guard.d.ts.map +1 -0
  12. package/dist/agent-guard.js +456 -0
  13. package/dist/ci-commit.d.ts +54 -3
  14. package/dist/ci-commit.d.ts.map +1 -1
  15. package/dist/ci-commit.js +69 -7
  16. package/dist/ci-own-jobs.d.ts +81 -0
  17. package/dist/ci-own-jobs.d.ts.map +1 -0
  18. package/dist/ci-own-jobs.js +234 -0
  19. package/dist/ci-product.d.ts +39 -0
  20. package/dist/ci-product.d.ts.map +1 -1
  21. package/dist/ci-product.js +40 -0
  22. package/dist/cli/handlers/approve.d.ts +5 -1
  23. package/dist/cli/handlers/approve.d.ts.map +1 -1
  24. package/dist/cli/handlers/approve.js +17 -11
  25. package/dist/cli/handlers/build.d.ts +1 -1
  26. package/dist/cli/handlers/build.d.ts.map +1 -1
  27. package/dist/cli/handlers/build.js +88 -2
  28. package/dist/cli/handlers/commit.d.ts.map +1 -1
  29. package/dist/cli/handlers/commit.js +3 -1
  30. package/dist/cli/handlers/notify-relay.d.ts +18 -1
  31. package/dist/cli/handlers/notify-relay.d.ts.map +1 -1
  32. package/dist/cli/handlers/notify-relay.js +90 -14
  33. package/dist/cli/handlers/pr.d.ts.map +1 -1
  34. package/dist/cli/handlers/pr.js +3 -1
  35. package/dist/cli/handlers/release.d.ts +9 -1
  36. package/dist/cli/handlers/release.d.ts.map +1 -1
  37. package/dist/cli/handlers/release.js +34 -6
  38. package/dist/cli/handlers/run-generate.d.ts.map +1 -1
  39. package/dist/cli/handlers/run-generate.js +2 -1
  40. package/dist/cli/main.d.ts.map +1 -1
  41. package/dist/cli/main.js +21 -1
  42. package/dist/cli/parse-args.d.ts.map +1 -1
  43. package/dist/cli/parse-args.js +60 -4
  44. package/dist/cli/registry.d.ts +16 -0
  45. package/dist/cli/registry.d.ts.map +1 -1
  46. package/dist/components/pr-env-components.d.ts +65 -0
  47. package/dist/components/pr-env-components.d.ts.map +1 -0
  48. package/dist/components/pr-env-components.js +163 -0
  49. package/dist/components/pr-policy.d.ts +15 -0
  50. package/dist/components/pr-policy.d.ts.map +1 -1
  51. package/dist/components/pr-policy.js +24 -1
  52. package/dist/components/release-compile.d.ts +15 -3
  53. package/dist/components/release-compile.d.ts.map +1 -1
  54. package/dist/components/release-compile.js +66 -15
  55. package/dist/gate-policy.d.ts +14 -1
  56. package/dist/gate-policy.d.ts.map +1 -1
  57. package/dist/gate-policy.js +16 -6
  58. package/dist/lexicon.d.ts +17 -1
  59. package/dist/lexicon.d.ts.map +1 -1
  60. package/dist/lexicon.js +1 -0
  61. package/dist/lifecycle/gated-op.d.ts +95 -0
  62. package/dist/lifecycle/gated-op.d.ts.map +1 -0
  63. package/dist/lifecycle/gated-op.js +96 -0
  64. package/dist/lifecycle/git.d.ts.map +1 -1
  65. package/dist/lifecycle/git.js +83 -2
  66. package/dist/notify-relay-repo.d.ts +131 -0
  67. package/dist/notify-relay-repo.d.ts.map +1 -0
  68. package/dist/notify-relay-repo.js +202 -0
  69. package/dist/notify-relay.d.ts +25 -1
  70. package/dist/notify-relay.d.ts.map +1 -1
  71. package/dist/notify-relay.js +28 -2
  72. package/dist/op/op-waves-capability.js +2 -2
  73. package/dist/policy-engine.d.ts +95 -0
  74. package/dist/policy-engine.d.ts.map +1 -0
  75. package/dist/policy-engine.js +158 -0
  76. package/dist/release-floors.d.ts +1 -1
  77. package/dist/release-floors.js +1 -1
  78. package/dist/state-export.d.ts +126 -0
  79. package/dist/state-export.d.ts.map +1 -0
  80. package/dist/state-export.js +157 -0
  81. package/dist/state-migration.d.ts +148 -0
  82. package/dist/state-migration.d.ts.map +1 -0
  83. package/dist/state-migration.js +147 -0
  84. package/dist/state-unlock.d.ts +167 -0
  85. package/dist/state-unlock.d.ts.map +1 -0
  86. package/dist/state-unlock.js +197 -0
  87. package/dist/wave-runtime.mjs +329 -329
  88. package/dist/workspace/declaration.schema.json +1 -1
  89. package/dist/workspace/release-workflow.d.ts +10 -0
  90. package/dist/workspace/release-workflow.d.ts.map +1 -1
  91. package/dist/workspace/release-workflow.js +8 -3
  92. package/package.json +1 -1
  93. package/src/__fixtures__/agent-guard/plywood.ts +27 -0
  94. package/src/__fixtures__/agent-guard/terragucci.ts +39 -0
  95. package/src/__fixtures__/gated-ledger.ts +58 -0
  96. package/src/agent-guard.test.ts +320 -0
  97. package/src/agent-guard.ts +548 -0
  98. package/src/ci-commit.test.ts +50 -2
  99. package/src/ci-commit.ts +93 -9
  100. package/src/ci-own-jobs.test.ts +109 -0
  101. package/src/ci-own-jobs.ts +253 -0
  102. package/src/ci-product.ts +81 -0
  103. package/src/cli/handlers/approve-cwd.test.ts +112 -0
  104. package/src/cli/handlers/approve.ts +22 -11
  105. package/src/cli/handlers/build-own-jobs.test.ts +80 -0
  106. package/src/cli/handlers/build-pr-loop-control.test.ts +88 -0
  107. package/src/cli/handlers/build-run-group.test.ts +60 -0
  108. package/src/cli/handlers/build.ts +83 -3
  109. package/src/cli/handlers/commit.ts +3 -0
  110. package/src/cli/handlers/notify-relay.ts +99 -17
  111. package/src/cli/handlers/pr.ts +3 -1
  112. package/src/cli/handlers/release-cut-archives.test.ts +21 -0
  113. package/src/cli/handlers/release.ts +31 -6
  114. package/src/cli/handlers/run-generate.ts +2 -1
  115. package/src/cli/main.ts +21 -1
  116. package/src/cli/parse-args.ts +45 -3
  117. package/src/cli/registry.ts +16 -0
  118. package/src/components/pr-env-components.test.ts +138 -0
  119. package/src/components/pr-env-components.ts +214 -0
  120. package/src/components/pr-policy.test.ts +41 -1
  121. package/src/components/pr-policy.ts +25 -1
  122. package/src/components/release-compile.test.ts +47 -0
  123. package/src/components/release-compile.ts +70 -13
  124. package/src/gate-policy-bundle.test.ts +14 -0
  125. package/src/gate-policy.test.ts +7 -0
  126. package/src/gate-policy.ts +22 -7
  127. package/src/lexicon.ts +18 -1
  128. package/src/lifecycle/gated-op.ts +158 -0
  129. package/src/lifecycle/git.test.ts +92 -0
  130. package/src/lifecycle/git.ts +71 -2
  131. package/src/notify-relay-repo.test.ts +284 -0
  132. package/src/notify-relay-repo.ts +234 -0
  133. package/src/notify-relay.test.ts +12 -0
  134. package/src/notify-relay.ts +30 -3
  135. package/src/op/op-waves-capability.ts +2 -2
  136. package/src/policy-engine.test.ts +163 -0
  137. package/src/policy-engine.ts +201 -0
  138. package/src/release-floors.ts +1 -1
  139. package/src/state-export.test.ts +125 -0
  140. package/src/state-export.ts +228 -0
  141. package/src/state-migration.test.ts +134 -0
  142. package/src/state-migration.ts +237 -0
  143. package/src/state-unlock.test.ts +166 -0
  144. package/src/state-unlock.ts +294 -0
  145. package/src/workspace/declaration.schema.json +1 -1
  146. package/src/workspace/release-workflow.test.ts +34 -0
  147. package/src/workspace/release-workflow.ts +17 -3
package/src/ci-commit.ts CHANGED
@@ -29,6 +29,8 @@ import { spawn } from "node:child_process";
29
29
  import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
30
30
  import { join } from "node:path";
31
31
  import { CHANT_EXIT } from "./exit-codes";
32
+ import { FORGE_TOKEN_VARS } from "./ci-handover";
33
+ import { NEXT_RELEASE } from "./release-floors";
32
34
  import { agentForbiddenPaths, AgentError, branchOk, errText, LOGIN, readSmall, SHA, type AgentGit } from "./ci-agent";
33
35
  import { parseProductComment, type CiProductWords } from "./ci-product-words";
34
36
  import type { OpRunRecord, OpRunRecordInput } from "./op/runtime";
@@ -42,6 +44,12 @@ export const CI_COMMIT_FLOOR = "0.124.71";
42
44
  export const CI_COMMIT_PUSH_FLOOR = "0.124.72";
43
45
  /** The first chant whose commit job takes `allowedFiles` (#4758). */
44
46
  export const CI_COMMIT_FILES_FLOOR = "0.124.73";
47
+ /**
48
+ * The first chant whose commit job takes `commandEnv`, gives the command
49
+ * `CHANT_COMMIT_PR`, keeps the tail of its standard error and replies with a
50
+ * product's refusal text ({@link setCommitRefusalReply}) (#4724).
51
+ */
52
+ export const CI_COMMIT_REPLY_FLOOR = NEXT_RELEASE;
45
53
 
46
54
  /** What starts a commit run: a person's comment, or a check job's finding. */
47
55
  export type CommitTrigger = "comment" | "check";
@@ -103,6 +111,14 @@ export interface OpCommitSpec {
103
111
  * the new head. Not run when nothing was pushed.
104
112
  */
105
113
  after?: string[];
114
+ /**
115
+ * Variables of the commit job the command sees, by name (#4724), such as a
116
+ * database reader's user and password. Every other variable is left out,
117
+ * as before. A forge token's name is refused. GitHub and Forgejo pass each
118
+ * one from the secret of the same name to the step that runs the command;
119
+ * on GitLab they are the project's CI/CD variables.
120
+ */
121
+ commandEnv?: string[];
106
122
  }
107
123
 
108
124
  /** A commit job's settings, every default filled and checked. */
@@ -123,6 +139,8 @@ export interface CommitSettings {
123
139
  jobToken: boolean;
124
140
  /** Lines the push job runs after a push (#4749). */
125
141
  after: string[];
142
+ /** The job variables the command sees (#4724). */
143
+ commandEnv: string[];
126
144
  }
127
145
 
128
146
  export const COMMIT_MAX_RUNS = 3;
@@ -146,8 +164,12 @@ export const COMMIT_ENV = {
146
164
  timeout: "CHANT_COMMIT_TIMEOUT",
147
165
  env: "CHANT_COMMIT_ENV",
148
166
  mergeBase: "CHANT_COMMIT_MERGE_BASE",
167
+ commandEnv: "CHANT_COMMIT_COMMAND_ENV",
149
168
  } as const;
150
169
 
170
+ /** The variable the command reads the pull request's number from (#4724), such as for a default name. */
171
+ export const COMMIT_PR_ENV = "CHANT_COMMIT_PR";
172
+
151
173
  /** GitLab starts no pipeline on a note: a pipeline of the default branch started with these runs a comment commit job. */
152
174
  export const GITLAB_COMMIT_PR_VAR = "CHANT_COMMIT_PR";
153
175
  export const GITLAB_COMMIT_WORD_VAR = "CHANT_COMMIT";
@@ -161,6 +183,10 @@ export const COMMIT_BASE_REF = "refs/chant/commit-base";
161
183
  export const COMMIT_DECISION_FILE = "decision.json";
162
184
  export const COMMIT_PATCH_FILE = "change.patch";
163
185
  export const COMMIT_RC_FILE = "rc";
186
+ /** The tail of the command's standard error (#4724), which a product's refusal reply reads. */
187
+ export const COMMIT_OUTPUT_FILE = "output";
188
+ /** How much of the command's standard error {@link COMMIT_OUTPUT_FILE} keeps, from the end. */
189
+ export const COMMIT_OUTPUT_LIMIT = 8192;
164
190
  /** What `chant commit land` leaves when it pushed (#4749): the pushed commit, which the push job's `after` lines read. */
165
191
  export const COMMIT_PUSHED_FILE = "pushed";
166
192
 
@@ -229,6 +255,10 @@ export function resolveCommitSpec(name: string, spec: OpCommitSpec, product = "c
229
255
  if (spec.jobToken && spec.tokenEnv !== undefined) throw new AgentError(`${where}: jobToken pushes with the job's own token, so leave tokenEnv out`);
230
256
  const after = spec.after ?? [];
231
257
  if (!Array.isArray(after) || !after.every((l) => typeof l === "string" && l.trim() !== "" && !l.includes("\n"))) throw new AgentError(`${where}: after is a list of shell lines, one command each`);
258
+ const commandEnv = spec.commandEnv ?? [];
259
+ if (!Array.isArray(commandEnv) || !commandEnv.every((v) => typeof v === "string" && VAR.test(v))) throw new AgentError(`${where}: commandEnv is a list of variable names`);
260
+ const tokens = commandEnv.filter((v) => (FORGE_TOKEN_VARS as readonly string[]).includes(v) || v === spec.tokenEnv || v.startsWith("CHANT_COMMIT_"));
261
+ if (tokens.length > 0) throw new AgentError(`${where}: commandEnv may not pass ${tokens.join(", ")}: the command never sees a forge token or the job's own settings`);
232
262
  return {
233
263
  name,
234
264
  on: spec.on,
@@ -244,6 +274,7 @@ export function resolveCommitSpec(name: string, spec: OpCommitSpec, product = "c
244
274
  mergeBase: spec.mergeBase === true,
245
275
  jobToken: spec.jobToken === true,
246
276
  after: [...after],
277
+ commandEnv: [...new Set(commandEnv)],
247
278
  };
248
279
  }
249
280
 
@@ -262,6 +293,7 @@ export function commitSettingsEnv(s: CommitSettings): Record<string, string> {
262
293
  [COMMIT_ENV.timeout]: String(s.timeout),
263
294
  [COMMIT_ENV.env]: s.env,
264
295
  ...(s.mergeBase ? { [COMMIT_ENV.mergeBase]: "1" } : {}),
296
+ ...(s.commandEnv.length > 0 ? { [COMMIT_ENV.commandEnv]: JSON.stringify(s.commandEnv) } : {}),
265
297
  };
266
298
  }
267
299
 
@@ -303,6 +335,7 @@ export function commitSettingsFromEnv(env: Record<string, string | undefined>, p
303
335
  ...(guarded ? { guarded } : {}),
304
336
  ...(env[COMMIT_ENV.env] ? { env: env[COMMIT_ENV.env] } : {}),
305
337
  ...(env[COMMIT_ENV.mergeBase] === "1" ? { mergeBase: true } : {}),
338
+ ...(list(COMMIT_ENV.commandEnv) ? { commandEnv: list(COMMIT_ENV.commandEnv)! } : {}),
306
339
  };
307
340
  return resolveCommitSpec(name, spec, product);
308
341
  }
@@ -641,13 +674,25 @@ export async function prepareCommitRun(i: CommitPrepareInput): Promise<CommitDec
641
674
 
642
675
  // ── commit run ─────────────────────────────────────────────────────────────
643
676
 
644
- /** Run an argv in `cwd`, with no shell. A failure or a timeout is an outcome. */
645
- export type CommitRunCommand = (argv: readonly string[], o: { cwd: string; env: Record<string, string>; timeoutMs: number }) => Promise<{ exitCode: number | null; timedOut: boolean }>;
677
+ /**
678
+ * Run an argv in `cwd`, with no shell. A failure or a timeout is an outcome.
679
+ * `output` is the tail of its standard error (#4724), at most
680
+ * {@link COMMIT_OUTPUT_LIMIT} bytes.
681
+ */
682
+ export type CommitRunCommand = (argv: readonly string[], o: { cwd: string; env: Record<string, string>; timeoutMs: number }) => Promise<{ exitCode: number | null; timedOut: boolean; output?: string }>;
646
683
 
647
684
  export const runCommitArgv: CommitRunCommand = (argv, o) =>
648
685
  new Promise((done) => {
649
686
  let timedOut = false;
650
- const child = spawn(argv[0]!, argv.slice(1), { cwd: o.cwd, env: o.env, stdio: ["ignore", "inherit", "inherit"] });
687
+ let tail = Buffer.alloc(0);
688
+ const child = spawn(argv[0]!, argv.slice(1), { cwd: o.cwd, env: o.env, stdio: ["ignore", "inherit", "pipe"] });
689
+ // The job's log still gets all of it; the tail is kept for the reply.
690
+ child.stderr?.on("data", (chunk: Buffer) => {
691
+ process.stderr.write(chunk);
692
+ tail = Buffer.concat([tail, chunk]);
693
+ if (tail.length > COMMIT_OUTPUT_LIMIT) tail = tail.subarray(tail.length - COMMIT_OUTPUT_LIMIT);
694
+ });
695
+ const output = (): string => tail.toString("utf8");
651
696
  const timer = setTimeout(() => {
652
697
  timedOut = true;
653
698
  child.kill("SIGTERM");
@@ -655,25 +700,28 @@ export const runCommitArgv: CommitRunCommand = (argv, o) =>
655
700
  }, o.timeoutMs);
656
701
  child.on("error", () => {
657
702
  clearTimeout(timer);
658
- done({ exitCode: null, timedOut });
703
+ done({ exitCode: null, timedOut, output: output() });
659
704
  });
660
705
  child.on("close", (code) => {
661
706
  clearTimeout(timer);
662
- done({ exitCode: code, timedOut });
707
+ done({ exitCode: code, timedOut, output: output() });
663
708
  });
664
709
  });
665
710
 
666
711
  /**
667
712
  * The variables the command sees: process basics, with the checkout's
668
713
  * `node_modules/.bin` first on `PATH` so a product's bin installed on the
669
- * target branch runs on the head's files. Never a forge or cloud token.
714
+ * target branch runs on the head's files. Never a forge or cloud token. Also
715
+ * the variables the spec's `commandEnv` names, and {@link COMMIT_PR_ENV}, the
716
+ * pull request's number (#4724).
670
717
  */
671
- export function commitCommandEnv(env: Record<string, string | undefined>, checkout: string): Record<string, string> {
718
+ export function commitCommandEnv(env: Record<string, string | undefined>, checkout: string, o: { names?: readonly string[]; pr?: number } = {}): Record<string, string> {
672
719
  const out: Record<string, string> = {};
673
- for (const name of ["PATH", "HOME", "TMPDIR", "LANG", "LC_ALL", "TERM", "SystemRoot", "npm_config_cache"]) {
720
+ for (const name of ["PATH", "HOME", "TMPDIR", "LANG", "LC_ALL", "TERM", "SystemRoot", "npm_config_cache", ...(o.names ?? [])]) {
674
721
  const v = env[name];
675
722
  if (v !== undefined) out[name] = v;
676
723
  }
724
+ if (o.pr !== undefined) out[COMMIT_PR_ENV] = String(o.pr);
677
725
  const bin = join(checkout, "node_modules", ".bin");
678
726
  if (existsSync(bin)) out.PATH = out.PATH ? `${bin}:${out.PATH}` : bin;
679
727
  return out;
@@ -713,9 +761,11 @@ export async function runCommit(i: CommitRunInput): Promise<{ rc: string; change
713
761
  return { rc: "conflict", changed: false };
714
762
  }
715
763
  }
716
- const out = await i.runCommand(i.settings.command, { cwd: i.workDir, env: commitCommandEnv(i.env, i.checkout), timeoutMs: i.settings.timeout * 60_000 });
764
+ const env = commitCommandEnv(i.env, i.checkout, { names: i.settings.commandEnv, ...(decision.pr !== undefined ? { pr: decision.pr } : {}) });
765
+ const out = await i.runCommand(i.settings.command, { cwd: i.workDir, env, timeoutMs: i.settings.timeout * 60_000 });
717
766
  const rc = out.timedOut ? "timeout" : out.exitCode === null ? "no-exit" : String(out.exitCode);
718
767
  writeFileSync(rcFile, `${rc}\n`);
768
+ if (out.output) writeFileSync(join(i.dir, COMMIT_OUTPUT_FILE), out.output.slice(-COMMIT_OUTPUT_LIMIT));
719
769
  i.git(["add", "-A"], { cwd: i.workDir });
720
770
  const patch = i.git(["diff", "--cached", "--binary", "--no-renames", "HEAD"], { cwd: i.workDir });
721
771
  writeFileSync(join(i.dir, COMMIT_PATCH_FILE), patch);
@@ -724,6 +774,29 @@ export async function runCommit(i: CommitRunInput): Promise<{ rc: string; change
724
774
 
725
775
  // ── commit land ────────────────────────────────────────────────────────────
726
776
 
777
+ /**
778
+ * A product's reply to a command that exited non-zero (#4724): the text that
779
+ * says why, from the command's exit code and the tail of its standard error,
780
+ * or undefined for chant's own reply. The output comes from a command run on
781
+ * the pull request's files, so a reply quotes from it only what it checked.
782
+ * A reply makes the run `refused`, not `failed`.
783
+ */
784
+ export type CommitRefusalReply = (o: { settings: CommitSettings; rc: string; output: string }) => string | undefined;
785
+
786
+ let activeRefusalReply: CommitRefusalReply | undefined;
787
+
788
+ /** Set the refusal reply for this process (a product's bin, once, as it sets its words). Returns the one it replaced. */
789
+ export function setCommitRefusalReply(reply: CommitRefusalReply | undefined): CommitRefusalReply | undefined {
790
+ const was = activeRefusalReply;
791
+ activeRefusalReply = reply;
792
+ return was;
793
+ }
794
+
795
+ /** The refusal reply {@link setCommitRefusalReply} set, if any. */
796
+ export function activeCommitRefusalReply(): CommitRefusalReply | undefined {
797
+ return activeRefusalReply;
798
+ }
799
+
727
800
  export interface CommitLandOutcome {
728
801
  result: CommitResult;
729
802
  reason: string;
@@ -753,6 +826,8 @@ export interface CommitLandInput {
753
826
  record: (input: OpRunRecordInput) => Promise<void>;
754
827
  now: () => Date;
755
828
  runOrigin?: RunOrigin;
829
+ /** The product's reply to a command that exited non-zero (#4724). */
830
+ refusalReply?: CommitRefusalReply;
756
831
  }
757
832
 
758
833
  const code = (s: string): string => "`" + s.replaceAll("`", "'") + "`";
@@ -823,6 +898,15 @@ export async function landCommitChange(i: CommitLandInput): Promise<CommitLandOu
823
898
  return finish({ result: "refused", reason: `merging ${decision.base ?? "the base"} into the head conflicts` }, `merging ${code(decision.base ?? "the base")} into the ${what} conflicts, so ${s.name} did not run and nothing was pushed. Resolve the conflict on the branch.`);
824
899
  }
825
900
  if (rc === "timeout") return finish({ result: "stopped", reason: `the command passed its ${s.timeout} minute limit` }, `${code(s.command.join(" "))} was stopped at its ${s.timeout} minute limit, so nothing was pushed.`);
901
+ if (rc !== "0" && /^[0-9]+$/.test(rc) && i.refusalReply) {
902
+ let said: string | undefined;
903
+ try {
904
+ said = i.refusalReply({ settings: s, rc, output: readSmall(join(i.dir, COMMIT_OUTPUT_FILE), COMMIT_OUTPUT_LIMIT * 2) ?? "" });
905
+ } catch {
906
+ said = undefined;
907
+ }
908
+ if (said) return finish({ result: "refused", reason: `the command refused, exiting ${rc}` }, `${said.trim()} Nothing was pushed.`);
909
+ }
826
910
  if (rc !== "0") return finish({ result: "failed", reason: `the command exited ${rc || "with no code"}` }, `${code(s.command.join(" "))} stopped with ${rc ? `exit code ${rc}` : "no exit code"}, so nothing was pushed. The commit job's log has its output.`);
827
911
 
828
912
  const head = await i.forge.pullRequestHead?.(pr!).catch(() => undefined);
@@ -0,0 +1,109 @@
1
+ /**
2
+ * A repository's own jobs in the pipeline file chant generates (#4769): a
3
+ * jobs file merged after chant's jobs, and the old file's hand-added jobs
4
+ * kept across regeneration.
5
+ */
6
+ import { mkdtempSync, writeFileSync } from "node:fs";
7
+ import { tmpdir } from "node:os";
8
+ import { join } from "node:path";
9
+ import { describe, expect, test } from "vitest";
10
+ import { isGeneratedJob, jobNames, keepOwnJobs, mergeOwnJobs, OWN_JOBS_LINE, OwnJobsError, readOwnJobsFile } from "./ci-own-jobs";
11
+ import * as ciProduct from "./ci-product";
12
+ import { NEXT_RELEASE } from "./release-floors";
13
+
14
+ const GITHUB = ["name: chant", "on:", " pull_request:", "jobs:", " plan:", " runs-on: ubuntu-latest", " steps:", " - run: chant components pr-plan prod", " plan-note:", " runs-on: ubuntu-latest", " steps:", " - run: chant components pr-post prod", ""].join("\n");
15
+ const GITLAB = ["stages:", " - plan", "variables:", " A: b", "plan:", " stage: plan", " script:", " - chant components pr-plan prod", ""].join("\n");
16
+
17
+ describe("mergeOwnJobs", () => {
18
+ test("puts the jobs after chant's, under the line, on GitHub and Forgejo", () => {
19
+ const out = mergeOwnJobs(GITHUB, "github", { lint: { "runs-on": "ubuntu-latest", steps: [{ run: "npm run lint" }] } });
20
+ expect(out).toBe(GITHUB + [" " + OWN_JOBS_LINE, " lint:", " runs-on: ubuntu-latest", " steps:", " - run: npm run lint", ""].join("\n"));
21
+ expect(jobNames(out, "forgejo")).toEqual(["plan", "plan-note", "lint"]);
22
+ });
23
+
24
+ test("puts them inside jobs: when a key follows it", () => {
25
+ const text = GITHUB.replace(/\n$/, "") + "\nenv:\n A: b\n";
26
+ const out = mergeOwnJobs(text, "github", { lint: { "runs-on": "x" } }, { line: "# mine" });
27
+ expect(out).toContain(" - run: chant components pr-post prod\n # mine\n lint:\n runs-on: x\nenv:\n A: b\n");
28
+ });
29
+
30
+ test("puts them at the top level on GitLab", () => {
31
+ expect(mergeOwnJobs(GITLAB, "gitlab", { lint: { script: ["npm run lint"] } })).toBe(GITLAB + [OWN_JOBS_LINE, "lint:", " script:", " - npm run lint", ""].join("\n"));
32
+ });
33
+
34
+ test("refuses a name chant's file has, and a GitLab keyword", () => {
35
+ expect(() => mergeOwnJobs(GITHUB, "github", { plan: { "runs-on": "x" } })).toThrow(OwnJobsError);
36
+ expect(() => mergeOwnJobs(GITHUB, "github", { plan: { "runs-on": "x" } }, { where: "own.yml" })).toThrow(/own\.yml\.plan: chant's file has a job of that name/);
37
+ for (const name of ["variables", "workflow", "default", "pages"]) {
38
+ expect(() => mergeOwnJobs(GITLAB, "gitlab", { [name]: { script: ["x"] } })).toThrow(/GitLab reads .* as a keyword/);
39
+ }
40
+ // On GitHub a top-level GitLab keyword is a name like any other.
41
+ expect(mergeOwnJobs(GITHUB, "github", { variables: { "runs-on": "x" } })).toContain(" variables:\n");
42
+ });
43
+
44
+ test("an empty map, or none, leaves the file byte for byte", () => {
45
+ expect(mergeOwnJobs(GITHUB, "github", {})).toBe(GITHUB);
46
+ expect(mergeOwnJobs(GITLAB, "gitlab", undefined)).toBe(GITLAB);
47
+ });
48
+ });
49
+
50
+ describe("readOwnJobsFile", () => {
51
+ const dir = mkdtempSync(join(tmpdir(), "chant-own-jobs-"));
52
+
53
+ test("reads a map of jobs", () => {
54
+ writeFileSync(join(dir, "ok.yml"), "lint:\n runs-on: x\n");
55
+ expect(readOwnJobsFile(join(dir, "ok.yml"))).toEqual({ lint: { "runs-on": "x" } });
56
+ });
57
+
58
+ test("refuses a missing file, a list and an empty job", () => {
59
+ expect(() => readOwnJobsFile(join(dir, "none.yml"), "none.yml")).toThrow(/none\.yml: no such file/);
60
+ writeFileSync(join(dir, "list.yml"), "- a\n");
61
+ expect(() => readOwnJobsFile(join(dir, "list.yml"), "list.yml")).toThrow(/must be a map of job name to job/);
62
+ writeFileSync(join(dir, "empty.yml"), "lint: {}\n");
63
+ expect(() => readOwnJobsFile(join(dir, "empty.yml"), "empty.yml")).toThrow(/empty\.yml\.lint must be a job/);
64
+ });
65
+ });
66
+
67
+ describe("keepOwnJobs", () => {
68
+ const own = [" # The team's own check.", " audit:", " runs-on: ubuntu-latest", " steps:", " - run: npm audit # as written"].join("\n");
69
+ const previous = GITHUB.replace(" plan-note:", own + "\n plan-note:");
70
+
71
+ test("keeps a hand-added job as written, after chant's, and keeps it again the next time", () => {
72
+ const first = keepOwnJobs(previous, GITHUB, "github");
73
+ expect(first.kept).toEqual(["audit"]);
74
+ expect(first.text).toBe(GITHUB + [" " + OWN_JOBS_LINE, " audit:", " runs-on: ubuntu-latest", " steps:", " - run: npm audit # as written", ""].join("\n"));
75
+ expect(keepOwnJobs(first.text, GITHUB, "github").text).toBe(first.text);
76
+ });
77
+
78
+ test("drops a job that runs chant or the product's bin, and one the new file has", () => {
79
+ const old = previous + [" old-plan:", " steps:", " - run: npx --no-install plywood ci run plan", " older:", " steps:", " - run: plywood components pr-plan", " gone:", " steps:", " - run: chant lock"].join("\n") + "\n";
80
+ expect(keepOwnJobs(old, GITHUB, "github", { bins: ["npx --no-install plywood"] }).kept).toEqual(["audit"]);
81
+ // Without the bin, plywood's lines are the team's own.
82
+ expect(keepOwnJobs(old, GITHUB, "github").kept).toEqual(["audit", "old-plan", "older"]);
83
+ });
84
+
85
+ test("on GitLab keeps top-level jobs and never a keyword", () => {
86
+ const old = GITLAB + "cache:\n key: x\nlint:\n script:\n - npm run lint\n";
87
+ const kept = keepOwnJobs(old, GITLAB, "gitlab");
88
+ expect(kept.kept).toEqual(["lint"]);
89
+ expect(kept.text).toBe(GITLAB + `${OWN_JOBS_LINE}\nlint:\n script:\n - npm run lint\n`);
90
+ });
91
+
92
+ test("no old file, or no own job in it, leaves the file byte for byte", () => {
93
+ expect(keepOwnJobs(undefined, GITHUB, "github")).toEqual({ text: GITHUB, kept: [] });
94
+ expect(keepOwnJobs(GITHUB, GITHUB, "github")).toEqual({ text: GITHUB, kept: [] });
95
+ });
96
+
97
+ test("a job counts as generated by its chant or bin line, not by a word in a path", () => {
98
+ expect(isGeneratedJob(" - run: npm i @intentius/chant\n")).toBe(false);
99
+ expect(isGeneratedJob(' - run: "chant components pr-plan"')).toBe(true);
100
+ expect(isGeneratedJob(" - run: $(npm bin)/yodel plan", ["npx yodel"])).toBe(false);
101
+ expect(isGeneratedJob(" - run: yodel plan", ["npx yodel"])).toBe(true);
102
+ });
103
+ });
104
+
105
+ test("the ci-product entry carries both, and OWN_JOBS_FLOOR marks them", () => {
106
+ expect(ciProduct.OWN_JOBS_FLOOR).toBe(NEXT_RELEASE);
107
+ expect(typeof ciProduct.mergeOwnJobs).toBe("function");
108
+ expect(typeof ciProduct.keepOwnJobs).toBe("function");
109
+ });
@@ -0,0 +1,253 @@
1
+ /**
2
+ * A repository's own jobs in a pipeline file chant generates (#4769).
3
+ *
4
+ * chant's generators write the whole file, so a job a repository adds by
5
+ * hand is gone at the next `chant build`. Two ways keep it:
6
+ *
7
+ * - a jobs file, or a map of jobs, merged after chant's jobs
8
+ * ({@link mergeOwnJobs}, `chant build --own-jobs <file>`). The file is in
9
+ * the forge's own syntax: a map of job name to job. A name chant's file
10
+ * already gives a job is refused, and on GitLab a top-level keyword too.
11
+ * terragucci's `own_jobs` works this way.
12
+ * - the jobs of the old file that the new one lacks, put back as they were
13
+ * written, comments and all ({@link keepOwnJobs}, `chant build
14
+ * --keep-own-jobs`). A job that runs `chant` or the product's bin counts as
15
+ * generated and is not kept. plywood's `init` and `ci` work this way.
16
+ *
17
+ * Either way the jobs go after chant's, under one comment line: inside
18
+ * `jobs:` at two spaces on GitHub and Forgejo, and at the top level on
19
+ * GitLab. The blocks are read as text by their indentation, so a kept job
20
+ * keeps its formatting. A file with no own jobs is returned unchanged.
21
+ */
22
+
23
+ import { readFileSync } from "node:fs";
24
+ import { emitYAMLEntry, parseYAMLDocument } from "./yaml";
25
+ import { NEXT_RELEASE } from "./release-floors";
26
+
27
+ /** The first chant with `mergeOwnJobs`, `keepOwnJobs` and `chant build --own-jobs` / `--keep-own-jobs` (#4769). Products feature-detect on it. */
28
+ export const OWN_JOBS_FLOOR = NEXT_RELEASE;
29
+
30
+ /** The forges whose pipeline files take own jobs. */
31
+ export type OwnJobsForge = "github" | "gitlab" | "forgejo";
32
+ export const OWN_JOBS_FORGES: readonly OwnJobsForge[] = ["github", "gitlab", "forgejo"];
33
+
34
+ /** The default line above the own jobs. A product passes its own as `line`. */
35
+ export const OWN_JOBS_LINE = "# Your own jobs, kept as they are when chant writes this file again.";
36
+
37
+ /** GitLab's top-level keys that are not jobs: never read as a job, never kept. */
38
+ export const GITLAB_TOP_KEYWORDS: readonly string[] = ["default", "include", "stages", "variables", "workflow", "image", "services", "cache", "before_script", "after_script", "spec"];
39
+
40
+ /** The names an own job may not take on GitLab: the keywords, and `pages`, which GitLab reads as its Pages job. */
41
+ export const GITLAB_RESERVED_JOB_NAMES: readonly string[] = [...GITLAB_TOP_KEYWORDS, "pages"];
42
+
43
+ /** A job name every forge's YAML reads as a plain key. */
44
+ export const OWN_JOB_NAME = /^[A-Za-z_][A-Za-z0-9_-]*$/;
45
+
46
+ /** An own job refused: a collision, a reserved name, or a file that is not a map of jobs. */
47
+ export class OwnJobsError extends Error {
48
+ constructor(message: string) {
49
+ super(message);
50
+ this.name = "OwnJobsError";
51
+ }
52
+ }
53
+
54
+ const KEY = /^([A-Za-z0-9_.-]+|"[^"]+"|'[^']+'):(\s|$)/;
55
+ const JOBS_LINE = /^jobs:\s*(#.*)?$/;
56
+
57
+ function indentOf(line: string): number {
58
+ return line.length - line.trimStart().length;
59
+ }
60
+
61
+ function isContent(line: string): boolean {
62
+ const t = line.trim();
63
+ return t !== "" && !t.startsWith("#");
64
+ }
65
+
66
+ function escapeRegExp(s: string): string {
67
+ return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
68
+ }
69
+
70
+ /** Each job's block of lines in `text`, by name, in file order. */
71
+ export function jobBlocks(text: string, forge: OwnJobsForge): Map<string, string> {
72
+ const lines = text.split("\n");
73
+ const out = new Map<string, string>();
74
+ let start = 0;
75
+ let end = lines.length;
76
+ let depth = 0;
77
+ if (forge !== "gitlab") {
78
+ const at = lines.findIndex((l) => JOBS_LINE.test(l));
79
+ if (at < 0) return out;
80
+ start = at + 1;
81
+ const next = lines.findIndex((l, i) => i > at && indentOf(l) === 0 && isContent(l));
82
+ end = next < 0 ? lines.length : next;
83
+ depth = 2;
84
+ }
85
+ let name: string | undefined;
86
+ let body: string[] = [];
87
+ const flush = (): void => {
88
+ if (name !== undefined) {
89
+ while (body.length > 0 && body[body.length - 1]!.trim() === "") body.pop();
90
+ out.set(name, body.join("\n"));
91
+ }
92
+ name = undefined;
93
+ body = [];
94
+ };
95
+ for (let i = start; i < end; i++) {
96
+ const line = lines[i]!;
97
+ if (isContent(line) && indentOf(line) === depth) {
98
+ const m = KEY.exec(line.slice(depth));
99
+ flush();
100
+ if (m) {
101
+ name = m[1]!.replace(/^["']|["']$/g, "");
102
+ body = [line];
103
+ }
104
+ continue;
105
+ }
106
+ if (isContent(line) && indentOf(line) < depth) {
107
+ flush();
108
+ continue;
109
+ }
110
+ if (name !== undefined) body.push(line);
111
+ }
112
+ flush();
113
+ if (forge === "gitlab") for (const k of [...out.keys()]) if (GITLAB_TOP_KEYWORDS.includes(k)) out.delete(k);
114
+ return out;
115
+ }
116
+
117
+ /** The job names of a pipeline file. */
118
+ export function jobNames(text: string, forge: OwnJobsForge): string[] {
119
+ return [...jobBlocks(text, forge).keys()];
120
+ }
121
+
122
+ /** `generated` with `blocks` after chant's jobs, under `line`. */
123
+ function withBlocks(generated: string, blocks: string[], forge: OwnJobsForge, line: string): string {
124
+ if (blocks.length === 0) return generated;
125
+ const indent = forge === "gitlab" ? "" : " ";
126
+ const block = [`${indent}${line}`, ...blocks].join("\n");
127
+ const lines = generated.replace(/\n+$/, "").split("\n");
128
+ if (forge !== "gitlab") {
129
+ const at = lines.findIndex((l) => JOBS_LINE.test(l));
130
+ if (at >= 0) {
131
+ const next = lines.findIndex((l, i) => i > at && indentOf(l) === 0 && isContent(l));
132
+ if (next >= 0) {
133
+ let cut = next;
134
+ while (cut > at + 1 && lines[cut - 1]!.trim() === "") cut--;
135
+ return [...lines.slice(0, cut), block, ...lines.slice(cut)].join("\n") + "\n";
136
+ }
137
+ }
138
+ }
139
+ return [...lines, block].join("\n") + "\n";
140
+ }
141
+
142
+ /** The problems with `own` as a map of job name to job; `where` names it in each. */
143
+ export function ownJobsProblems(own: unknown, where: string): string[] {
144
+ if (own === null || typeof own !== "object" || Array.isArray(own)) return [`${where} must be a map of job name to job`];
145
+ const problems: string[] = [];
146
+ for (const [name, job] of Object.entries(own as Record<string, unknown>)) {
147
+ if (!OWN_JOB_NAME.test(name)) problems.push(`${where}: ${JSON.stringify(name)} is not a job name; use letters, digits, "_" and "-"`);
148
+ else if (job === null || typeof job !== "object" || Array.isArray(job) || Object.keys(job).length === 0) problems.push(`${where}.${name} must be a job: a map of its keys, in the forge's own syntax`);
149
+ }
150
+ return problems;
151
+ }
152
+
153
+ /** The map of jobs a YAML file holds. Throws {@link OwnJobsError} when it is missing, not YAML, or not a map of jobs. */
154
+ export function readOwnJobsFile(path: string, where = path): Record<string, Record<string, unknown>> {
155
+ let text: string;
156
+ try {
157
+ text = readFileSync(path, "utf-8");
158
+ } catch {
159
+ throw new OwnJobsError(`${where}: no such file`);
160
+ }
161
+ let doc: unknown;
162
+ try {
163
+ doc = parseYAMLDocument(text);
164
+ } catch (e) {
165
+ throw new OwnJobsError(`${where} is not YAML (${(e as Error).message})`);
166
+ }
167
+ const problems = ownJobsProblems(doc, where);
168
+ if (problems.length > 0) throw new OwnJobsError(problems.join("; "));
169
+ return doc as Record<string, Record<string, unknown>>;
170
+ }
171
+
172
+ export interface MergeOwnJobsOptions {
173
+ /** The line above the jobs. Default {@link OWN_JOBS_LINE}. */
174
+ line?: string;
175
+ /** What the jobs are called in a refusal, such as `own_jobs` or the file's path. Default `own jobs`. */
176
+ where?: string;
177
+ /** Names the generated file's jobs take, when the caller knows them; default: read from `generated`. */
178
+ generatedJobs?: readonly string[];
179
+ }
180
+
181
+ /**
182
+ * The YAML of `own`, as it goes after chant's jobs: {@link OWN_JOBS_LINE} (or
183
+ * `line`), then each job as it is. Empty for no jobs. Throws
184
+ * {@link OwnJobsError} on a name in `ours` or, on GitLab, a reserved one.
185
+ */
186
+ export function ownJobsYAML(own: Record<string, unknown> | undefined, ours: readonly string[], forge: OwnJobsForge, options: Omit<MergeOwnJobsOptions, "generatedJobs"> = {}): string {
187
+ if (!own || Object.keys(own).length === 0) return "";
188
+ const where = options.where ?? "own jobs";
189
+ const problems = ownJobsProblems(own, where);
190
+ if (problems.length > 0) throw new OwnJobsError(problems.join("; "));
191
+ for (const name of Object.keys(own)) {
192
+ if (ours.includes(name)) throw new OwnJobsError(`${where}.${name}: chant's file has a job of that name; give yours another`);
193
+ if (forge === "gitlab" && GITLAB_RESERVED_JOB_NAMES.includes(name)) throw new OwnJobsError(`${where}.${name}: GitLab reads ${name} as a keyword, not a job; give yours another name`);
194
+ }
195
+ const indent = forge === "gitlab" ? 0 : 1;
196
+ return [`${forge === "gitlab" ? "" : " "}${options.line ?? OWN_JOBS_LINE}`, ...Object.entries(own).map(([name, job]) => emitYAMLEntry(name, job, indent))].join("\n") + "\n";
197
+ }
198
+
199
+ /** `generated` with `own` after chant's jobs (terragucci's `own_jobs` model). Unchanged for no jobs. */
200
+ export function mergeOwnJobs(generated: string, forge: OwnJobsForge, own: Record<string, unknown> | undefined, options: MergeOwnJobsOptions = {}): string {
201
+ if (!own || Object.keys(own).length === 0) return generated;
202
+ const ours = options.generatedJobs ?? jobNames(generated, forge);
203
+ const rendered = ownJobsYAML(own, ours, forge, options).replace(/\n$/, "");
204
+ const [line, ...rest] = rendered.split("\n");
205
+ // The rendered text starts with the indented line; withBlocks adds the indent itself.
206
+ return withBlocks(generated, [rest.join("\n")], forge, line!.trimStart());
207
+ }
208
+
209
+ /** The bins whose lines mark a job as generated: `chant`, and each of `bins` with its last word (`npx --no-install plywood` and `plywood`). */
210
+ function generatedLine(bins: readonly string[]): RegExp {
211
+ const names = new Set<string>(["chant"]);
212
+ for (const bin of bins) {
213
+ const b = bin.trim();
214
+ if (b === "") continue;
215
+ names.add(b);
216
+ names.add(b.split(/\s+/).pop()!.split("/").pop()!);
217
+ }
218
+ const alt = [...names].sort((a, b) => b.length - a.length).map(escapeRegExp).join("|");
219
+ return new RegExp(`(^|[\\s"'(]|\\$\\()(?:${alt}) (?=[a-z])`, "m");
220
+ }
221
+
222
+ /** Whether a job's block runs `chant` or one of `bins`: a job chant's generator wrote. */
223
+ export function isGeneratedJob(block: string, bins: readonly string[] = []): boolean {
224
+ return generatedLine(bins).test(block);
225
+ }
226
+
227
+ export interface KeepOwnJobsOptions {
228
+ /** The product's bin, such as `npx --no-install plywood`: a job that runs it is generated. `chant` always counts. */
229
+ bins?: readonly string[];
230
+ /** The line above the kept jobs. Default {@link OWN_JOBS_LINE}. */
231
+ line?: string;
232
+ }
233
+
234
+ /** The jobs of `previous` that `generated` lacks and that run neither `chant` nor a bin of `bins`. */
235
+ export function ownJobsOf(previous: string, generated: string, forge: OwnJobsForge, bins: readonly string[] = []): Map<string, string> {
236
+ const ours = jobBlocks(generated, forge);
237
+ const out = new Map<string, string>();
238
+ for (const [name, block] of jobBlocks(previous, forge)) {
239
+ if (ours.has(name) || isGeneratedJob(block, bins)) continue;
240
+ out.set(name, block);
241
+ }
242
+ return out;
243
+ }
244
+
245
+ /**
246
+ * The old file's own jobs carried into the new one (plywood's model):
247
+ * `previous` undefined means there was no file. `kept` names them.
248
+ */
249
+ export function keepOwnJobs(previous: string | undefined, generated: string, forge: OwnJobsForge, options: KeepOwnJobsOptions = {}): { text: string; kept: string[] } {
250
+ if (previous === undefined) return { text: generated, kept: [] };
251
+ const own = ownJobsOf(previous, generated, forge, options.bins ?? []);
252
+ return { text: withBlocks(generated, [...own.values()], forge, options.line ?? OWN_JOBS_LINE), kept: [...own.keys()] };
253
+ }