@intentius/chant 0.124.60 → 0.124.62

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 (52) hide show
  1. package/dist/cli/main.d.ts.map +1 -1
  2. package/dist/cli/main.js +16 -2
  3. package/dist/cli/parse-args.d.ts.map +1 -1
  4. package/dist/cli/parse-args.js +12 -0
  5. package/dist/cli/registry.d.ts +6 -0
  6. package/dist/cli/registry.d.ts.map +1 -1
  7. package/dist/notify.d.ts +24 -2
  8. package/dist/notify.d.ts.map +1 -1
  9. package/dist/notify.js +16 -2
  10. package/dist/notify.schema.json +17 -1
  11. package/dist/release-floors.d.ts +1 -1
  12. package/dist/release-floors.js +1 -1
  13. package/dist/wave-runtime.mjs +310 -309
  14. package/dist/workspace/ci-builds.d.ts +16 -4
  15. package/dist/workspace/ci-builds.d.ts.map +1 -1
  16. package/dist/workspace/ci-builds.js +10 -7
  17. package/dist/workspace/ci-green-cli.d.ts +12 -0
  18. package/dist/workspace/ci-green-cli.d.ts.map +1 -1
  19. package/dist/workspace/ci-green-cli.js +80 -6
  20. package/dist/workspace/ci-green-workflow.d.ts +13 -0
  21. package/dist/workspace/ci-green-workflow.d.ts.map +1 -1
  22. package/dist/workspace/ci-green-workflow.js +72 -1
  23. package/dist/workspace/ci-green.d.ts +130 -6
  24. package/dist/workspace/ci-green.d.ts.map +1 -1
  25. package/dist/workspace/ci-green.js +250 -24
  26. package/dist/workspace/declaration.d.ts +37 -0
  27. package/dist/workspace/declaration.d.ts.map +1 -1
  28. package/dist/workspace/declaration.js +29 -1
  29. package/dist/workspace/declaration.schema.json +44 -0
  30. package/dist/workspace/trust/ci-tag-statement.d.ts +1 -0
  31. package/dist/workspace/trust/ci-tag-statement.d.ts.map +1 -1
  32. package/dist/workspace/trust/ci-tag-statement.js +5 -1
  33. package/package.json +1 -1
  34. package/src/cli/main.ts +16 -2
  35. package/src/cli/parse-args.ts +9 -0
  36. package/src/cli/registry.ts +6 -0
  37. package/src/notify.schema.json +17 -1
  38. package/src/notify.ts +30 -2
  39. package/src/release-floors.ts +1 -1
  40. package/src/workspace/ci-builds.ts +16 -7
  41. package/src/workspace/ci-green-builds.test.ts +83 -1
  42. package/src/workspace/ci-green-cli.ts +80 -6
  43. package/src/workspace/ci-green-lanes.test.ts +121 -0
  44. package/src/workspace/ci-green-merge-queue.test.ts +66 -0
  45. package/src/workspace/ci-green-notify.test.ts +166 -0
  46. package/src/workspace/ci-green-signed.test.ts +20 -0
  47. package/src/workspace/ci-green-workflow.test.ts +56 -1
  48. package/src/workspace/ci-green-workflow.ts +71 -1
  49. package/src/workspace/ci-green.ts +289 -26
  50. package/src/workspace/declaration.schema.json +44 -0
  51. package/src/workspace/declaration.ts +64 -2
  52. package/src/workspace/trust/ci-tag-statement.ts +5 -2
@@ -17,6 +17,7 @@
17
17
  */
18
18
  import { RETENTION_KINDS } from "../lifecycle/retention-policy.js";
19
19
  import { parseReportUrl } from "../pr-report-url.js";
20
+ import { notifyConfigProblem } from "../notify.js";
20
21
  import schema from "./declaration.schema.json" with { type: "json" };
21
22
  import { routeConflicts } from "./ci-branches.js";
22
23
  import { cloudIdentityProblems, IDENTITY_CLOUDS } from "../ci-identity.js";
@@ -84,6 +85,19 @@ export function greenBranches(green) {
84
85
  }
85
86
  /** The default `ci.green.window`. */
86
87
  export const DEFAULT_CI_WINDOW = "24h";
88
+ /** A lane's tag prefixes (#4662): `ci/green-<lane>/` and `ci/revoked-<lane>/`. */
89
+ export function laneTagPrefixes(lane) {
90
+ return { green: `ci/green-${lane}/`, revoked: `ci/revoked-${lane}/` };
91
+ }
92
+ /** The lane `name` of `green`, or a `declaration-invalid` error naming the lanes it declares. */
93
+ export function laneOf(green, name) {
94
+ const lane = green.lanes?.find((l) => l.name === name);
95
+ if (!lane) {
96
+ const declared = (green.lanes ?? []).map((l) => l.name);
97
+ throw new WorkspaceReadError("declaration-invalid", `ci.green declares no lane ${JSON.stringify(name)}${declared.length > 0 ? `; it declares ${declared.join(", ")}` : "; it declares none (ci.green.lanes)"}`);
98
+ }
99
+ return lane;
100
+ }
87
101
  /** The default `ci.prEnvironment.ttl`. */
88
102
  export const DEFAULT_PR_ENVIRONMENT_TTL = "72h";
89
103
  /** A renderer a diagram is pinned to (#2764): a closed list of tools chant does not run. */
@@ -668,8 +682,22 @@ function ciOf(raw, at) {
668
682
  continue;
669
683
  throw new WorkspaceReadError("declaration-invalid", `ci.green.preMerge names the phase ${JSON.stringify(name)}, which ci.green.phases does not declare; declared phases: ${phases.map((p) => p.name).join(", ")}`, at(`/ci/green/preMerge/${i}`));
670
684
  }
685
+ const lanes = Object.entries(g.lanes ?? {}).map(([name, l]) => {
686
+ const pointer = `/ci/green/lanes/${pointerToken(name)}`;
687
+ for (const [i, phase] of l.require.entries()) {
688
+ if (phases.some((p) => p.name === phase))
689
+ continue;
690
+ throw new WorkspaceReadError("declaration-invalid", `ci.green.lanes.${name}.require names the phase ${JSON.stringify(phase)}, which ci.green.phases does not declare; declared phases: ${phases.map((p) => p.name).join(", ")}`, at(`${pointer}/require/${i}`));
691
+ }
692
+ return { name, require: [...l.require], pointer };
693
+ });
694
+ if (g.notify !== undefined) {
695
+ const problem = notifyConfigProblem(g.notify, "ci.green.notify");
696
+ if (problem)
697
+ throw new WorkspaceReadError("declaration-invalid", problem, at("/ci/green/notify"));
698
+ }
671
699
  const judged = Array.isArray(g.branch) ? g.branch : [g.branch];
672
- return { green: { branch: judged[0], ...(judged.length > 1 ? { branches: [...judged] } : {}), window: g.window ?? DEFAULT_CI_WINDOW, phases, require: [...g.require], ...(g.preMerge !== undefined ? { preMerge: [...g.preMerge] } : {}), signedSince: g.signedSince ?? null, source: g.source ?? "checks", pointer: "/ci/green" }, ...workflow, reportUrl };
700
+ return { green: { branch: judged[0], ...(judged.length > 1 ? { branches: [...judged] } : {}), window: g.window ?? DEFAULT_CI_WINDOW, phases, require: [...g.require], ...(g.preMerge !== undefined ? { preMerge: [...g.preMerge] } : {}), signedSince: g.signedSince ?? null, source: g.source ?? "checks", ...(lanes.length > 0 ? { lanes } : {}), ...(g.notify !== undefined ? { notify: { ...g.notify, ...(g.notify.events ? { events: [...g.notify.events] } : {}) } } : {}), ...(g.mergeQueue === true ? { mergeQueue: true } : {}), pointer: "/ci/green" }, ...workflow, reportUrl };
673
701
  }
674
702
  function agentsOf(raw, members, at) {
675
703
  const agents = (raw ?? []).map((a, i) => {
@@ -1901,6 +1901,50 @@
1901
1901
  "pattern": "^[0-9a-f]{40}([0-9a-f]{24})?$",
1902
1902
  "description": "Added by #4031, read by chant 0.124.28 and newer. The full sha of the first commit on branch whose ci/green and ci/revoked tags must carry a DSSE statement in their annotation, signed by a key .chant/trust.json at base lists under runners for a principal holding the runner role. A tag on a strict first-parent ancestor of this commit counts unsigned, so existing tags keep working; a tag on any other commit, this one included, needs a statement. Position in history decides, never a date, which whoever makes a commit or a tag sets. A reader refuses a sha that names no commit in its clone with declaration-invalid. Absent, no tag needs a statement. Since chant 0.124.32 (#4156) it covers Op run records the same way, when ci.green.source is runs: an unsigned run counts on a strict first-parent ancestor of this commit and needs a statement on any other, ci serve refuses to start without a runner key trusted at the target's head, and ci run and chant run warn about a run they leave unsigned. Absent, an unsigned run counts and nothing asks for a key."
1903
1903
  },
1904
+ "mergeQueue": {
1905
+ "type": "boolean",
1906
+ "description": "The branch takes changes through GitHub's merge queue (#4644). chant ci workflow adds the merge_group trigger (checks_requested) to each workflow holding a phase that sets build, and writes .github/workflows/chant-merge-queue.yml, whose chant-verdict job runs chant ci verdict --wait on the group's commit: it passes when every required phase passed there, judged as the tick judges, so the queue's ruleset requires that one check. The queue lands the commit its group tested, so the group's runs count for it; a later push run's skipped or cancelled attempt of the same job never replaces the group's decided one. A workflow holding a phase without build gets no trigger: add merge_group to it by hand. Written by chant 0.124.61 and newer, so a declaration that sets it sets minReader to 0.124.61 or newer."
1907
+ },
1908
+ "notify": {
1909
+ "type": "object",
1910
+ "description": "Who chant ci tick tells (#4645), as an Op waves spec's notify: each value names an environment variable, never a URL or a key. webhook and key: a signed chant.notify/v1 webhook; slack and teams: incoming webhooks; events: which to send, of ci.red, ci.culprit and ci.green (all three by default). ci.red: the branch's newest decided commit is red after its one retry. ci.culprit: a bisect named the first red commit. ci.green: the branch is green again after a ci.red. Each is sent once: the tick marks it in the commit's _ci record, so it needs chant/lifecycle, and it sends nothing when it can't write the records. Read by chant 0.124.61 and newer, so a declaration that sets it sets minReader to 0.124.61 or newer.",
1911
+ "properties": {
1912
+ "webhook": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
1913
+ "key": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
1914
+ "slack": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
1915
+ "teams": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
1916
+ "events": { "type": "array", "uniqueItems": true, "items": { "enum": ["ci.red", "ci.culprit", "ci.green"] } }
1917
+ },
1918
+ "additionalProperties": false
1919
+ },
1920
+ "lanes": {
1921
+ "type": "object",
1922
+ "minProperties": 1,
1923
+ "description": "Green lanes (#4662): named subsets of the phases, each with tags of its own, for a deployable that needs only some of them. A commit that passes a lane's phases gets ci/green-<lane>/<sha>, and a lane-green commit that later fails one gets ci/revoked-<lane>/<sha>, judged by the same tick from the same runs as require, with no runs of their own; the bisect and the retry stay per phase. ci/green/<sha> still follows require. chant ci last-green --lane <name> and chant ci base --lane <name> read a lane. A signed lane tag's statement names its lane, so it never counts as another lane's tag or as ci/green. Added in schema 1 by chant 0.124.61, so a declaration that uses it sets minReader to 0.124.61 or newer.",
1924
+ "propertyNames": {
1925
+ "type": "string",
1926
+ "pattern": "^[a-z0-9][a-z0-9-]*$"
1927
+ },
1928
+ "additionalProperties": {
1929
+ "type": "object",
1930
+ "required": ["require"],
1931
+ "properties": {
1932
+ "require": {
1933
+ "type": "array",
1934
+ "minItems": 1,
1935
+ "uniqueItems": true,
1936
+ "description": "The phases a commit must pass to be green in this lane, by name. Each must be a declared phase.",
1937
+ "items": {
1938
+ "$ref": "#/$defs/ciPhaseName"
1939
+ }
1940
+ }
1941
+ },
1942
+ "patternProperties": {
1943
+ "^x-": true
1944
+ },
1945
+ "additionalProperties": false
1946
+ }
1947
+ },
1904
1948
  "source": {
1905
1949
  "enum": [
1906
1950
  "checks",
@@ -98,5 +98,6 @@ export declare function verifyCiTagStatement(record: Record<string, unknown> | n
98
98
  sha: string;
99
99
  kind: "green" | "revoked";
100
100
  branch: string;
101
+ lane?: string;
101
102
  }, runners: readonly RunnerKey[], roles: Readonly<Record<string, readonly string[]>>): CiTagVerdict;
102
103
  //# sourceMappingURL=ci-tag-statement.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"ci-tag-statement.d.ts","sourceRoot":"","sources":["../../../src/workspace/trust/ci-tag-statement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAsD,KAAK,YAAY,EAAE,MAAM,QAAQ,CAAC;AAE/F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,eAAO,MAAM,gBAAgB,yCAAyC,CAAC;AAEvE,iGAAiG;AACjG,eAAO,MAAM,kBAAkB,WAAW,CAAC;AAK3C,+GAA+G;AAC/G,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;kBAqBtB,CAAC;AACZ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,kDAAkD;AAClD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,GAAG,EAAE,OAAO,GAAG,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjH,4GAA4G;AAC5G,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,SAAS,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,CAOvF;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,GAAG,YAAY,CAGtF;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,CAAC;AAE7E,MAAM,MAAM,YAAY,GACpB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnE;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAI7C;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACtC,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,GAAG,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAClE,OAAO,EAAE,SAAS,SAAS,EAAE,EAC7B,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,GACjD,YAAY,CAgCd"}
1
+ {"version":3,"file":"ci-tag-statement.d.ts","sourceRoot":"","sources":["../../../src/workspace/trust/ci-tag-statement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAsD,KAAK,YAAY,EAAE,MAAM,QAAQ,CAAC;AAE/F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,eAAO,MAAM,gBAAgB,yCAAyC,CAAC;AAEvE,iGAAiG;AACjG,eAAO,MAAM,kBAAkB,WAAW,CAAC;AAK3C,+GAA+G;AAC/G,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;kBAqBtB,CAAC;AACZ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,kDAAkD;AAClD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,GAAG,EAAE,OAAO,GAAG,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjH,4GAA4G;AAC5G,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,SAAS,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,CAOvF;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,GAAG,YAAY,CAGtF;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,CAAC;AAE7E,MAAM,MAAM,YAAY,GACpB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnE;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAI7C;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACtC,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,GAAG,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EACjF,OAAO,EAAE,SAAS,SAAS,EAAE,EAC7B,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,GACjD,YAAY,CAmCd"}
@@ -77,7 +77,7 @@ const normalise = (name) => name.normalize("NFKC").trim().toLowerCase();
77
77
  * `runner` role in `roles`. Never throws.
78
78
  */
79
79
  export function verifyCiTagStatement(record, expect, runners, roles) {
80
- const tag = `ci/${expect.kind}/${expect.sha}`;
80
+ const tag = `ci/${expect.kind}${expect.lane !== undefined ? `-${expect.lane}` : ""}/${expect.sha}`;
81
81
  if (record === null)
82
82
  return { status: "unsigned", reason: `${tag} has no JSON record in its annotation, so it carries no statement (a lightweight tag, or one made by hand)` };
83
83
  const { statement: envelope, ...fields } = record;
@@ -115,6 +115,10 @@ export function verifyCiTagStatement(record, expect, runners, roles) {
115
115
  differs.push(`it signs a ${p.record.tag} tag`);
116
116
  if (p.record.branch !== expect.branch)
117
117
  differs.push(`it is for branch ${p.record.branch}, and ci.green names ${expect.branch}`);
118
+ // #4662: a lane's statement says its lane, so it never counts as ci/green or as another lane's tag.
119
+ const signedLane = typeof p.record.lane === "string" ? p.record.lane : undefined;
120
+ if (signedLane !== expect.lane)
121
+ differs.push(signedLane === undefined ? `it signs a ci/${p.record.tag} tag, not lane ${expect.lane}'s` : `it signs lane ${signedLane}'s tag${expect.lane !== undefined ? `, not lane ${expect.lane}'s` : ", not ci/" + p.record.tag}`);
118
122
  if (canonicalJson(p.record) !== canonicalJson(fields))
119
123
  differs.push("the annotation's record is not the one signed");
120
124
  if (differs.length > 0)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@intentius/chant",
3
- "version": "0.124.60",
3
+ "version": "0.124.62",
4
4
  "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
5
5
  "license": "Apache-2.0",
6
6
  "homepage": "https://intentius.io/chant",
package/src/cli/main.ts CHANGED
@@ -286,11 +286,23 @@ CI:
286
286
  statuses, and each identity trusted to its own jobs.
287
287
  Read-only; exits 1 on a mismatch, and with
288
288
  --require-clouds on a cloud it had no credentials for.
289
- ci last-green [--json] [--from <rev>] The newest first-parent commit of
289
+ ci last-green [--json] [--lane <name>] [--from <rev>] The newest first-parent commit of
290
290
  ci.green's branch, or of --from, with a ci/green tag
291
- and no ci/revoked tag. Reads local tags only; fetch
291
+ and no ci/revoked tag (with --lane, the lane's
292
+ ci/green-<lane> tags). Reads local tags only; fetch
292
293
  them first. With ci.green.signedSince, a tag without a
293
294
  valid runner statement is ignored and reported.
295
+ ci base [--json] [--phase <name> | --lane <name>] [--from <rev>] The commit a path filter
296
+ diffs against under build: newest: the newest
297
+ first-parent ancestor of --from (HEAD) whose record
298
+ shows the phase (or every required phase) built and
299
+ passed on it, else a green tag. Fetch the tags and
300
+ chant/lifecycle first.
301
+ ci verdict [--commit <sha>] [--wait] A merge queue's verdict: exits 0
302
+ when every required phase passed on the commit
303
+ (GITHUB_SHA, else HEAD), judged from its check runs
304
+ as the tick judges; 1 when one failed; 3 while one is
305
+ pending, unless --wait reads again until none is.
294
306
  ci list [--json] [--limit <n>] [--since <rev>] [--forge github] [--source checks|runs]
295
307
  The first-parent commits of ci.green's branch within
296
308
  its window, newest first, each green, revoked or
@@ -1779,6 +1791,8 @@ export const commandRegistry: CommandDef[] = [
1779
1791
  { name: "e2e safe-run", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/e2e-safe-run")).runE2eSafeRun(ctx) },
1780
1792
  { name: "e2e", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/e2e-safe-run")).runE2eUnknown(ctx) },
1781
1793
  { name: "ci last-green", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli")).runCiLastGreen(ctx) },
1794
+ { name: "ci verdict", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli")).runCiVerdict(ctx) },
1795
+ { name: "ci base", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli")).runCiBase(ctx) },
1782
1796
  { name: "ci list", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli")).runCiList(ctx) },
1783
1797
  { name: "ci tick", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli")).runCiTick(ctx) },
1784
1798
  { name: "ci workflow", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/ci-green-cli")).runCiWorkflow(ctx) },
@@ -1195,6 +1195,15 @@ export function parseArgs(args: string[]): ParsedArgs {
1195
1195
  result.resource = value;
1196
1196
  } else if (arg === "--since") {
1197
1197
  result.since = args[++i];
1198
+ } else if (arg === "--wait") {
1199
+ // `chant ci verdict --wait` (#4644): read the check runs again until no required phase is pending.
1200
+ result.ciWait = true;
1201
+ } else if (arg === "--lane") {
1202
+ // `chant ci last-green --lane <name>` and `chant ci base --lane <name>` (#4662): a green lane's tags and phases.
1203
+ result.lane = args[++i];
1204
+ } else if (arg === "--phase") {
1205
+ // `chant ci base --phase <name>` (#4643): the ci.green phase whose base to find.
1206
+ result.phase = args[++i];
1198
1207
  } else if (arg === "--audit-log") {
1199
1208
  // `chant audit-log attribute|unrecorded --audit-log aws[:<region>]` (#4632).
1200
1209
  const value = args[++i];
@@ -917,6 +917,12 @@ export interface ParsedArgs {
917
917
  op?: string;
918
918
  /** `chant operator log --since <iso>` (#2029) — only entries at or after this ISO-8601 instant. `chant workspace records --since <rev>` (#2673) — the revision to compare the records with. `chant workspace metrics --since <date>` (#4039) — the start of the window the metrics count. */
919
919
  since?: string;
920
+ /** `chant ci verdict --wait` (#4644) — read again until no required phase is pending. */
921
+ ciWait?: boolean;
922
+ /** `chant ci last-green --lane <name>` and `chant ci base --lane <name>` (#4662) — a ci.green lane. */
923
+ lane?: string;
924
+ /** `chant ci base --phase <name>` (#4643) — the ci.green phase whose base to find. */
925
+ phase?: string;
920
926
  /** `chant audit-log attribute|unrecorded --audit-log aws[:<region>]` (#4632): the cloud audit log to read. */
921
927
  auditLog?: string;
922
928
  /** `chant ledger`, `chant workspace records` and `chant workspace runs --where <field><op><value>` (#4363): typed filters, repeatable, all of which have to hold. */
@@ -8,7 +8,7 @@
8
8
  "properties": {
9
9
  "schema": { "const": "chant.notify/v1" },
10
10
  "id": { "type": "string", "minLength": 1, "description": "The same for every send of one event about one digest (else drift fingerprint, else commit), so a receiver can drop a repeat; random when there is none. The delivery header carries it too." },
11
- "event": { "enum": ["waiting", "refused", "failed", "drift"] },
11
+ "event": { "enum": ["waiting", "refused", "failed", "drift", "ci.red", "ci.culprit", "ci.green"], "description": "The ci. events come from chant ci tick (#4645) and carry ci." },
12
12
  "at": { "type": "string", "description": "When it was sent, ISO 8601 UTC." },
13
13
  "source": { "type": "string", "minLength": 1, "description": "The product that sent it: chant, terragucci, sql-yodeler." },
14
14
  "project": { "type": "string", "description": "What the run belongs to: the repository, or a name the product gives." },
@@ -63,6 +63,22 @@
63
63
  "pr": { "type": "integer" }
64
64
  }
65
65
  },
66
+ "ci": {
67
+ "type": "object",
68
+ "description": "On ci.red, ci.culprit and ci.green (#4645): the branch and commit. ci.red: the newest decided commit, red after its one retry, with phase and failedRun. ci.culprit: culprit, the first red commit a bisect found for the red commit. ci.green: red, the commit whose ci.red this answers.",
69
+ "required": ["branch", "commit"],
70
+ "properties": {
71
+ "branch": { "type": "string" },
72
+ "commit": { "type": "string" },
73
+ "phase": { "type": "string" },
74
+ "failedRun": {
75
+ "type": "object",
76
+ "properties": { "name": { "type": "string" }, "id": { "type": ["integer", "null"] }, "conclusion": { "type": ["string", "null"] }, "url": { "type": ["string", "null"] } }
77
+ },
78
+ "culprit": { "type": "string" },
79
+ "red": { "type": "string" }
80
+ }
81
+ },
66
82
  "reportUrl": { "type": "string" },
67
83
  "detail": { "type": "object", "description": "The product's own record of the outcome, carried whole (terragucci.outcome/v1)." }
68
84
  },
package/src/notify.ts CHANGED
@@ -39,8 +39,8 @@ export const NOTIFY_SCHEMA = "chant.notify/v1";
39
39
  /** The JSON Schema's `$id`. */
40
40
  export const NOTIFY_SCHEMA_ID = "https://intentius.io/chant/schemas/notify/v1/notify.schema.json";
41
41
 
42
- /** What happened. */
43
- export const NOTIFY_EVENTS = ["waiting", "refused", "failed", "drift"] as const;
42
+ /** What happened. The `ci.` events come from `chant ci tick` (#4645): a branch red after its retry, a bisect's culprit, the branch green again. */
43
+ export const NOTIFY_EVENTS = ["waiting", "refused", "failed", "drift", "ci.red", "ci.culprit", "ci.green"] as const;
44
44
  export type NotifyEventKind = (typeof NOTIFY_EVENTS)[number];
45
45
 
46
46
  /** Where the run is: the CI run's page, the forge, the repository and commit. */
@@ -93,6 +93,8 @@ export interface NotifyEvent {
93
93
  exitCode?: number;
94
94
  /** On `drift`: what moved. */
95
95
  drift?: { changed: string[]; missing?: string[]; failed?: string[]; fingerprint?: string };
96
+ /** On the `ci.` events (#4645): the branch and commit, and what failed or what was red. */
97
+ ci?: NotifyCi;
96
98
  run?: NotifyRun;
97
99
  /** A report page for the run. */
98
100
  reportUrl?: string;
@@ -100,6 +102,22 @@ export interface NotifyEvent {
100
102
  detail?: Record<string, unknown>;
101
103
  }
102
104
 
105
+ /**
106
+ * The tick's part of a `ci.` event (#4645). `ci.red`: `commit` is the
107
+ * branch's newest decided commit, red after its one retry, with the phase and
108
+ * run that failed. `ci.culprit`: `culprit` is the first red commit a bisect
109
+ * found, for the red `commit`. `ci.green`: `commit` is green, and `red` the
110
+ * commit whose `ci.red` this answers.
111
+ */
112
+ export interface NotifyCi {
113
+ branch: string;
114
+ commit: string;
115
+ phase?: string;
116
+ failedRun?: { name: string; id: number | null; conclusion: string | null; url: string | null };
117
+ culprit?: string;
118
+ red?: string;
119
+ }
120
+
103
121
  /** What a product fills in; {@link makeNotifyEvent} adds the rest. */
104
122
  export type NotifyFields = Omit<NotifyEvent, "schema" | "id" | "at" | "project" | "targets" | "run"> & {
105
123
  id?: string;
@@ -158,6 +176,9 @@ const HEADLINE: Record<NotifyEventKind, string> = {
158
176
  refused: "was refused",
159
177
  failed: "failed",
160
178
  drift: "drifted",
179
+ "ci.red": "is red",
180
+ "ci.culprit": "has a culprit",
181
+ "ci.green": "is green again",
161
182
  };
162
183
 
163
184
  /** The first line of every chat message: `<source>: <summary>`, or what happened to what when there is no summary. */
@@ -176,6 +197,13 @@ function facts(e: NotifyEvent): { title: string; value: string; link?: string }[
176
197
  if (e.drift.missing?.length) out.push({ title: "Missing", value: e.drift.missing.join(", ") });
177
198
  if (e.drift.failed?.length) out.push({ title: "Not refreshed", value: e.drift.failed.join(", ") });
178
199
  } else if (e.targets.length > 0) out.push({ title: "Targets", value: e.targets.join(", ") });
200
+ if (e.ci) {
201
+ out.push({ title: "Commit", value: `${e.ci.commit.slice(0, 12)} on ${e.ci.branch}` });
202
+ if (e.ci.phase) out.push({ title: "Phase", value: e.ci.failedRun ? `${e.ci.phase}: ${e.ci.failedRun.name} ${e.ci.failedRun.conclusion ?? ""}`.trimEnd() : e.ci.phase });
203
+ if (e.ci.failedRun?.url) out.push({ title: "Failed run", value: e.ci.failedRun.url, link: e.ci.failedRun.url });
204
+ if (e.ci.culprit) out.push({ title: "Culprit", value: e.ci.culprit.slice(0, 12) });
205
+ if (e.ci.red) out.push({ title: "Was red", value: e.ci.red.slice(0, 12) });
206
+ }
179
207
  if (e.digest) out.push({ title: "Digest", value: e.digest });
180
208
  if (e.approve) out.push({ title: e.approve.review ? "Or approve" : "Approve", value: e.approve.command });
181
209
  if (e.reason) out.push({ title: "Reason", value: e.reason });
@@ -19,4 +19,4 @@
19
19
  * this constant to the next patch (#4501). The check fails while a floor
20
20
  * still names this constant after its version shipped.
21
21
  */
22
- export const NEXT_RELEASE = "0.124.60";
22
+ export const NEXT_RELEASE = "0.124.62";
@@ -48,6 +48,8 @@ export const CI_BUILD_TAG_PREFIX = "ci/build/";
48
48
  /** The directory on `chant/lifecycle` holding one record per commit. */
49
49
  export const CI_RECORDS_DIR = "_ci";
50
50
  const LEDGER_REF = "refs/heads/chant/lifecycle";
51
+ /** The local branch the records are read from, for readers that fall back to its remote-tracking branch. */
52
+ export const CI_LEDGER_REF = LEDGER_REF;
51
53
 
52
54
  /** How long a build request may wait for a runner before its phases count as unbuilt. */
53
55
  export const BUILD_REQUEST_TTL_MS = 6 * 3_600_000;
@@ -92,6 +94,12 @@ export interface CiRecord {
92
94
  request?: { tag: string; reason: BuildRequestReason; phases: string[]; at: string; dispatched?: true };
93
95
  /** The `every` phases a `missing` request asked for, and when (#4216). A commit is asked for once. */
94
96
  missing?: { phases: string[]; at: string };
97
+ /**
98
+ * What the tick told people about this commit through `ci.green.notify`
99
+ * (#4645), so it tells them once: when it sent `ci.red`, the culprit it
100
+ * sent `ci.culprit` for, and the green commit whose `ci.green` answered it.
101
+ */
102
+ notified?: { red?: string; culprit?: string; green?: string };
95
103
  }
96
104
 
97
105
  export interface CiRecordRun {
@@ -290,6 +298,7 @@ export function recordOf(input: { green: CiGreen; commit: TickCommit; previous?:
290
298
  const missing = req?.reason === "missing" ? { phases: req.phases, at: req.at } : previous?.missing;
291
299
  const extras = {
292
300
  ...(Object.keys(retried).length > 0 ? { retried } : {}),
301
+ ...(previous?.notified ? { notified: previous.notified } : {}),
293
302
  ...(req ? { request: { tag: req.tag, reason: req.reason, phases: req.phases, at: req.at } } : {}),
294
303
  ...(missing ? { missing } : {}),
295
304
  };
@@ -358,20 +367,20 @@ function parseRecord(text: string | null): CiRecord | undefined {
358
367
  }
359
368
  }
360
369
 
361
- /** One commit's record, from the local `chant/lifecycle`. */
362
- export function readCiRecord(top: string, sha: string): CiRecord | undefined {
363
- return parseRecord(tryGit(top, ["show", `${LEDGER_REF}:${recordPath(sha)}`]));
370
+ /** One commit's record, from the local `chant/lifecycle` (or `ref`, such as its remote-tracking branch). */
371
+ export function readCiRecord(top: string, sha: string, ref: string = LEDGER_REF): CiRecord | undefined {
372
+ return parseRecord(tryGit(top, ["show", `${ref}:${recordPath(sha)}`]));
364
373
  }
365
374
 
366
- /** Every record on the local `chant/lifecycle`, by commit. Empty when the branch or the directory is missing. */
367
- export function readCiRecords(top: string): Map<string, CiRecord> {
375
+ /** Every record on the local `chant/lifecycle` (or `ref`), by commit. Empty when the branch or the directory is missing. */
376
+ export function readCiRecords(top: string, ref: string = LEDGER_REF): Map<string, CiRecord> {
368
377
  const out = new Map<string, CiRecord>();
369
- const names = tryGit(top, ["ls-tree", "--name-only", `${LEDGER_REF}:${CI_RECORDS_DIR}`]);
378
+ const names = tryGit(top, ["ls-tree", "--name-only", `${ref}:${CI_RECORDS_DIR}`]);
370
379
  if (!names) return out;
371
380
  for (const name of names.split("\n")) {
372
381
  const m = /^([0-9a-f]{40,64})\.json$/.exec(name);
373
382
  if (!m) continue;
374
- const r = readCiRecord(top, m[1]);
383
+ const r = readCiRecord(top, m[1], ref);
375
384
  if (r) out.set(m[1], r);
376
385
  }
377
386
  return out;
@@ -8,7 +8,7 @@
8
8
  import { execFileSync } from "node:child_process";
9
9
  import { afterAll, describe, expect, test } from "vitest";
10
10
  import { cleanScratch, declaration, git, scratchDir, writeFiles } from "./__fixtures__/contract-repo";
11
- import { ciList, ciTick, lastGreen, requestBuild } from "./ci-green";
11
+ import { ciBase, ciList, ciTick, lastGreen, requestBuild } from "./ci-green";
12
12
  import type { CheckRun, CiForge } from "./ci-green-forge";
13
13
  import { readBuildRequests, readCiRecord } from "./ci-builds";
14
14
 
@@ -204,3 +204,85 @@ describe("chant ci run --at (#4169)", () => {
204
204
  expect(readCiRecord(root, a)).toMatchObject({ state: "pending", request: { reason: "requested", dispatched: true } });
205
205
  });
206
206
  });
207
+
208
+ describe("chant ci base (#4643)", () => {
209
+ const baseOf = (cwd: string, from: string, phase?: string) => {
210
+ const doc = ciBase({ cwd, from, ...(phase ? { phase } : {}) });
211
+ if ("error" in doc) throw new Error(doc.error.message);
212
+ return doc.commit && { sha: doc.commit.sha, via: doc.commit.via };
213
+ };
214
+
215
+ test("a docs-only tip over a superseded commit diffs against the last commit the phase built, not its parent", async () => {
216
+ const { root } = workspace();
217
+ const base = commitAt(root, 4, "app/a.txt");
218
+ git(root, "push", "-q", "origin", "main");
219
+ // a changes the code and is superseded before its suites run; c changes only docs.
220
+ const a = commitAt(root, 3, "app/a.txt");
221
+ const c = commitAt(root, 2, "docs/readme.md");
222
+ git(root, "push", "-q", "origin", "main");
223
+ const runs = new Map([
224
+ [base, [run("check", "success"), run("suites", "success")]],
225
+ [a, [run("check", "success"), run("suites", "cancelled")]],
226
+ [c, [run("check", "success"), run("suites", null, "in_progress")]],
227
+ ]);
228
+ await ciTick({ cwd: root, forge: fakeForge(runs), now: NOW });
229
+
230
+ // c's filter, run while c builds: its base is base, so a's change to app/ is in the diff.
231
+ expect(baseOf(root, c, "suites")).toEqual({ sha: base, via: "record" });
232
+ expect(baseOf(root, c)).toEqual({ sha: base, via: "record" });
233
+
234
+ // Once c's suites pass, a commit above c diffs against c, and a stays passed over.
235
+ runs.set(c, [run("check", "success"), run("suites", "success")]);
236
+ await ciTick({ cwd: root, forge: fakeForge(runs), now: NOW });
237
+ const d = commitAt(root, 1, "docs/more.md");
238
+ expect(baseOf(root, d, "suites")).toEqual({ sha: c, via: "record" });
239
+ });
240
+
241
+ test("passes over a commit whose phase failed, so a change on top of the failure still runs it", async () => {
242
+ const { root } = workspace();
243
+ const base = commitAt(root, 4, "app/a.txt");
244
+ const red = commitAt(root, 3, "app/a.txt");
245
+ git(root, "push", "-q", "origin", "main");
246
+ const runs = new Map([
247
+ [base, [run("check", "success"), run("suites", "success")]],
248
+ [red, [run("check", "success"), run("suites", "failure"), run("suites", "failure")]],
249
+ ]);
250
+ await ciTick({ cwd: root, forge: fakeForge(runs), now: NOW });
251
+ const docs = commitAt(root, 2, "docs/readme.md");
252
+ expect(baseOf(root, docs, "suites")).toEqual({ sha: base, via: "record" });
253
+ // A phase that passed on the red commit has it as its base.
254
+ expect(baseOf(root, docs, "check")).toEqual({ sha: red, via: "record" });
255
+ });
256
+
257
+ test("a commit with no record counts by its green tag, and none at all is a null commit", () => {
258
+ const { root } = workspace();
259
+ const tagged = commitAt(root, 3, "app/a.txt");
260
+ const above = commitAt(root, 2, "app/a.txt");
261
+ expect(baseOf(root, above, "suites")).toBeNull();
262
+ git(root, "tag", `ci/green/${tagged}`, tagged);
263
+ expect(baseOf(root, above, "suites")).toEqual({ sha: tagged, via: "tag" });
264
+ // The commit asked about is never its own base.
265
+ expect(baseOf(root, tagged)).toBeNull();
266
+ });
267
+
268
+ test("reads origin/chant/lifecycle when there is no local branch, as in a CI checkout", async () => {
269
+ const { root, origin } = workspace();
270
+ const base = commitAt(root, 3, "app/a.txt");
271
+ git(root, "push", "-q", "origin", "main");
272
+ await ciTick({ cwd: root, forge: fakeForge(new Map([[base, [run("check", "success"), run("suites", "success")]]])), now: NOW });
273
+ const clone = scratchDir("chant-base-clone-");
274
+ git(clone, "clone", "-q", "-b", "main", origin, ".");
275
+ git(clone, "fetch", "-q", "origin", "--tags", "+refs/heads/chant/lifecycle:refs/remotes/origin/chant/lifecycle");
276
+ expect(git(clone, "branch", "--list", "chant/lifecycle")).toBe("");
277
+ writeFiles(clone, { "docs/readme.md": "docs\n" });
278
+ git(clone, "add", "-A");
279
+ git(clone, "-c", "user.name=t", "-c", "user.email=t@example.com", "commit", "-q", "-m", "docs");
280
+ expect(baseOf(clone, "HEAD", "suites")).toEqual({ sha: base, via: "record" });
281
+ });
282
+
283
+ test("refuses a phase the declaration doesn't name", () => {
284
+ const { root } = workspace();
285
+ commitAt(root, 2, "app/a.txt");
286
+ expect(() => ciBase({ cwd: root, phase: "lint" })).toThrow(/declares no phase "lint"; it declares check, suites/);
287
+ });
288
+ });
@@ -24,20 +24,22 @@
24
24
  * workflow print text.
25
25
  */
26
26
 
27
+ import { execFileSync } from "node:child_process";
27
28
  import { existsSync, readFileSync, realpathSync } from "node:fs";
29
+ import { CHANT_EXIT } from "../exit-codes";
28
30
  import { join, relative, resolve, sep } from "node:path";
29
31
  import { formatError } from "../cli/format";
30
32
  import type { CommandContext } from "../cli/registry";
31
33
  import { findWorkspaceRoot } from "../project-root";
32
- import { ciList, ciTick, CiGreenError, formatList, formatTick, lastGreen, RUNNER_KEY_ENV } from "./ci-green";
34
+ import { ciBase, ciList, ciTick, ciVerdict, CiGreenError, formatList, formatTick, lastGreen, RUNNER_KEY_ENV } from "./ci-green";
33
35
  import { ciForgeFromEnv } from "./ci-green-forge";
34
- import { ACTIONS_NAME, buildTriggerEdits, CI_GREEN_WORKFLOW_FILE, ciGreenHeader, type PushToken, readWorkflowSources, renderCiGreenWorkflow, workflowsHolding, writeWorkflowFile } from "./ci-green-workflow";
36
+ import { ACTIONS_NAME, buildTriggerEdits, CI_GREEN_WORKFLOW_FILE, ciGreenHeader, MERGE_QUEUE_VERDICT_JOB, MERGE_QUEUE_WORKFLOW_FILE, type PushToken, readWorkflowSources, renderCiGreenWorkflow, renderMergeQueueWorkflow, workflowsHolding, writeWorkflowFile } from "./ci-green-workflow";
35
37
  import { greenBranches, readDeclaration, readerVersion, WorkspaceReadError, type CiSource } from "./declaration";
36
38
  import { recordGeneratedFiles, resolveMemberContext, shellArg } from "./member-pipeline";
37
39
  import { gitTop, workingTree } from "./tree";
38
40
 
39
41
  const USAGE =
40
- "chant ci last-green [--json] [--from <rev>] [--branch <branch>] | ci list [--json] [--branch <branch>] [--limit <n>] [--since <rev>] [--forge github] [--source checks|runs] | ci tick [--dry-run] [--forge github] [--source checks|runs] [--key <runner key.pem>] | " +
42
+ "chant ci last-green [--json] [--lane <name>] [--from <rev>] [--branch <branch>] | ci base [--json] [--phase <name> | --lane <name>] [--from <rev>] [--branch <branch>] | ci verdict [--commit <sha>] [--wait] | ci list [--json] [--branch <branch>] [--limit <n>] [--since <rev>] [--forge github] [--source checks|runs] | ci tick [--dry-run] [--forge github] [--source checks|runs] [--key <runner key.pem>] | " +
41
43
  "ci workflow [--workflow <name>]... [--output <file>] [--chant <command>] [--install <command>] [--token-secret <NAME> | --app-id-var <VAR> --app-key-secret <NAME>] [--runner-key-secret <NAME>]";
42
44
 
43
45
  export { RUNNER_KEY_ENV };
@@ -56,7 +58,7 @@ function warnIgnored(ignored: readonly { tag: string; status: string; reason: st
56
58
  }
57
59
 
58
60
  export async function runCiLastGreen(ctx: CommandContext): Promise<number> {
59
- const doc = lastGreen({ cwd: process.cwd(), ...(ctx.args.branch !== undefined ? { branch: ctx.args.branch } : {}), ...(ctx.args.migrateFrom !== undefined ? { from: ctx.args.migrateFrom } : {}) });
61
+ const doc = lastGreen({ cwd: process.cwd(), ...(ctx.args.lane !== undefined ? { lane: ctx.args.lane } : {}), ...(ctx.args.branch !== undefined ? { branch: ctx.args.branch } : {}), ...(ctx.args.migrateFrom !== undefined ? { from: ctx.args.migrateFrom } : {}) });
60
62
  if (ctx.args.json) {
61
63
  console.log(JSON.stringify(doc, null, 2));
62
64
  return "error" in doc ? 1 : 0;
@@ -67,13 +69,78 @@ export async function runCiLastGreen(ctx: CommandContext): Promise<number> {
67
69
  }
68
70
  warnIgnored(doc.ignored);
69
71
  if (!doc.commit) {
70
- console.error(`No first-parent commit of ${doc.ref} has a ci/green tag without a ci/revoked one. Fetch the tags first: git fetch origin --tags`);
72
+ const lane = ctx.args.lane !== undefined ? `-${ctx.args.lane}` : "";
73
+ console.error(`No first-parent commit of ${doc.ref} has a ci/green${lane} tag without a ci/revoked${lane} one. Fetch the tags first: git fetch origin --tags`);
71
74
  return 1;
72
75
  }
73
76
  console.log(doc.commit.sha);
74
77
  return 0;
75
78
  }
76
79
 
80
+ /**
81
+ * `chant ci base` (#4643): prints the commit a path filter should diff
82
+ * against, or exits 1 with a message when none qualifies, so the caller can
83
+ * run everything.
84
+ */
85
+ export async function runCiBase(ctx: CommandContext): Promise<number> {
86
+ try {
87
+ const doc = ciBase({ cwd: process.cwd(), ...(ctx.args.phase !== undefined ? { phase: ctx.args.phase } : {}), ...(ctx.args.lane !== undefined ? { lane: ctx.args.lane } : {}), ...(ctx.args.branch !== undefined ? { branch: ctx.args.branch } : {}), ...(ctx.args.migrateFrom !== undefined ? { from: ctx.args.migrateFrom } : {}) });
88
+ if (ctx.args.json) {
89
+ console.log(JSON.stringify(doc, null, 2));
90
+ return "error" in doc ? 1 : 0;
91
+ }
92
+ if ("error" in doc) {
93
+ console.error(formatError({ message: doc.error.message, hint: USAGE }));
94
+ return 1;
95
+ }
96
+ warnIgnored(doc.ignored);
97
+ if (!doc.commit) {
98
+ console.error(`No first-parent ancestor of ${doc.ref} ${doc.phase ? `built and passed phase ${doc.phase}` : "built and passed every required phase"}, and none has a ci/green tag. Fetch the tags and the records first: git fetch origin --tags chant/lifecycle`);
99
+ return 1;
100
+ }
101
+ console.log(doc.commit.sha);
102
+ return 0;
103
+ } catch (err) {
104
+ console.error(formatError({ message: `chant ci base: ${describe(err)}`, hint: USAGE }));
105
+ return 1;
106
+ }
107
+ }
108
+
109
+ /**
110
+ * `chant ci verdict [--commit <sha>] [--wait]` (#4644): exits 0 when every
111
+ * required phase passed on the commit (GITHUB_SHA, else HEAD), 1 when one
112
+ * failed or wasn't built, and 3 when one is still pending without --wait.
113
+ */
114
+ export async function runCiVerdict(ctx: CommandContext): Promise<number> {
115
+ try {
116
+ const sha = ctx.args.commit ?? process.env.GITHUB_SHA ?? execFileSync("git", ["rev-parse", "HEAD"], { encoding: "utf-8" }).trim();
117
+ const forge = ciForgeFromEnv("github");
118
+ const { verdict } = await ciVerdict({
119
+ cwd: process.cwd(),
120
+ sha,
121
+ forge,
122
+ ...(ctx.args.ciWait ? { wait: true } : {}),
123
+ ...(ctx.args.branch !== undefined ? { branch: ctx.args.branch } : {}),
124
+ onPending: (v) => console.error(`waiting on ${v.phases.filter((p) => p.verdict === "pending").map((p) => p.phase).join(", ")}`),
125
+ });
126
+ const short = sha.slice(0, 12);
127
+ if (verdict.verdict === "pass") {
128
+ console.log(`${short}: every required phase passed (${verdict.phases.map((p) => p.phase).join(", ")})`);
129
+ return 0;
130
+ }
131
+ if (verdict.verdict === "fail") {
132
+ console.error(`${short}: phase ${verdict.failure!.phase} failed in ${verdict.failure!.run.name} (${verdict.failure!.run.conclusion})`);
133
+ return 1;
134
+ }
135
+ const open = verdict.phases.filter((p) => p.verdict === verdict.verdict).map((p) => p.phase);
136
+ console.error(`${short}: ${verdict.verdict === "pending" ? "still waiting on" : "never built"} ${open.join(", ")}`);
137
+ return verdict.verdict === "pending" ? CHANT_EXIT.waiting : 1;
138
+ } catch (err) {
139
+ console.error(formatError({ message: `chant ci verdict: ${describe(err)}`, hint: USAGE }));
140
+ return 1;
141
+ }
142
+ }
143
+
77
144
  export async function runCiList(ctx: CommandContext): Promise<number> {
78
145
  try {
79
146
  const limit = ctx.args.limit;
@@ -151,7 +218,8 @@ export async function runCiWorkflow(ctx: CommandContext): Promise<number> {
151
218
  const target = ctx.args.output ? resolve(realpathSync(cwd), ctx.args.output) : join(repoRoot, CI_GREEN_WORKFLOW_FILE);
152
219
  const fromRepo = relative(repoRoot, target).split(sep).join("/");
153
220
 
154
- const sources = readWorkflowSources(repoRoot, fromRepo);
221
+ // The merge queue's verdict (#4644) is ours too, and holds no phase.
222
+ const sources = readWorkflowSources(repoRoot, fromRepo).filter((s) => s.path !== MERGE_QUEUE_WORKFLOW_FILE);
155
223
  const scan = workflowsHolding(green, sources);
156
224
  // #4169: the triggers and concurrency of the workflows holding a phase that sets build. Refused before anything is written.
157
225
  // #4220: under a ci.workflow, composed releases' branches run the phases and tick too.
@@ -186,6 +254,12 @@ export async function runCiWorkflow(ctx: CommandContext): Promise<number> {
186
254
  const written = writeWorkflowFile(target, ciGreenHeader(command, member ? "member" : "root") + yaml);
187
255
  if (member) recordGeneratedFiles(member.memberRoot, [{ path: fromRepo, command }]);
188
256
  console.log(`Wrote ${written}: ticks when ${workflows.join(", ")} complete${workflows.length === 1 ? "s" : ""} on ${greenBranches(green).join(", ")}${compose ? " or a chant/compose/ branch" : ""}, and every 15 minutes.`);
257
+ // #4644: the merge queue's verdict, beside the tick and from the same command.
258
+ if (green.mergeQueue && !member) {
259
+ const queue = renderMergeQueueWorkflow({ green, chantVersion: readerVersion(), workspaceRoot, chant: ctx.args.ciChant, install: ctx.args.ciInstall, npmLock });
260
+ const at = writeWorkflowFile(join(repoRoot, MERGE_QUEUE_WORKFLOW_FILE), ciGreenHeader(command, "root") + queue);
261
+ console.log(`Wrote ${at}: on each merge group, ${MERGE_QUEUE_VERDICT_JOB} passes when every required phase passed on the group's commit. Require ${MERGE_QUEUE_VERDICT_JOB} in the branch's ruleset.`);
262
+ }
189
263
  for (const e of edits) {
190
264
  if (!e.changed) continue;
191
265
  const path = writeWorkflowFile(join(repoRoot, e.path), e.text);