@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
@@ -55,14 +55,15 @@
55
55
 
56
56
  import { judgeCommits, mergeCommits, readWorkIndex, type CommitLink } from "./commit-links";
57
57
  import { execFileSync } from "node:child_process";
58
- import { greenBranches, readDeclaration, readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError, type CiGreen, type CiPhase, type CiSource } from "./declaration";
58
+ import { greenBranches, laneOf, laneTagPrefixes, readDeclaration, readerVersion, WORKSPACE_ERROR_CODES, WorkspaceReadError, type CiGreen, type CiPhase, type CiSource } from "./declaration";
59
+ import { makeNotifyEvent, sendNotify, type NotifyFields } from "../notify";
59
60
  import type { CheckRun, CiForge, OpRunRef } from "./ci-green-forge";
60
61
  import type { OpRunRecord } from "../op/runtime";
61
62
  import { readRunLedger } from "../lifecycle/run-ledger";
62
63
  import { fetchLifecycleStatus, listFilesInDir, listLedgerTrees, pushLifecycleStatus, writeLedgerFiles } from "../lifecycle/git";
63
64
  import { ledgerRecordingOff } from "../lifecycle/no-record";
64
- import { agedOut, buildRequestAnnotation, CI_BUILD_TAG_PREFIX, planBuilds, readBuildRequests, readCiRecords, recordOf, recordPath, requestedBuild, sameRecord, type BuildRequest, type CiRecord } from "./ci-builds";
65
- import { dispatchableWorkflows, readWorkflowSources } from "./ci-green-workflow";
65
+ import { agedOut, buildRequestAnnotation, CI_BUILD_TAG_PREFIX, CI_LEDGER_REF, planBuilds, readBuildRequests, readCiRecords, recordOf, recordPath, requestedBuild, sameRecord, type BuildRequest, type CiRecord } from "./ci-builds";
66
+ import { dispatchableWorkflows, MERGE_QUEUE_VERDICT_JOB, readWorkflowSources } from "./ci-green-workflow";
66
67
  import { signOpRunRecord, verifyOpRunStatement } from "./trust/op-run-statement";
67
68
  import type { ReasonCode } from "./reason-codes";
68
69
  import { gitTop } from "./tree";
@@ -78,6 +79,12 @@ export const RUNNER_KEY_ENV = "CHANT_RUNNER_KEY";
78
79
 
79
80
  export const CI_GREEN_TAG_PREFIX = "ci/green/";
80
81
  export const CI_REVOKED_TAG_PREFIX = "ci/revoked/";
82
+ /** The first chant that reads and writes green lanes, `ci.green.lanes` (#4662). */
83
+ export const CI_GREEN_LANES_FLOOR = "0.124.61";
84
+ /** The first chant whose tick sends `ci.red`, `ci.culprit` and `ci.green` through `ci.green.notify` (#4645). */
85
+ export const CI_TICK_NOTIFY_FLOOR = "0.124.61";
86
+ /** The first chant that writes a merge queue's trigger and verdict job, and reads `chant ci verdict` (#4644). */
87
+ export const CI_MERGE_QUEUE_FLOOR = "0.124.61";
81
88
 
82
89
  export const CI_LAST_GREEN_CONTRACT_VERSION = 1;
83
90
  export const CI_LAST_GREEN_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/ci-last-green/v1/ci-last-green.schema.json";
@@ -114,12 +121,21 @@ export function matchesCheckRun(pattern: string, name: string): boolean {
114
121
  return re.test(name);
115
122
  }
116
123
 
117
- /** Each check run's latest attempt, by name: the run with the largest id. */
124
+ /**
125
+ * Each check run's latest attempt, by name: the run with the largest id,
126
+ * except that a skipped or cancelled attempt never replaces a decided one
127
+ * (#4644). Under a merge queue the commit a group tested lands as it is, and
128
+ * the branch's push run on it reports the same jobs again, skipped by their
129
+ * path filters or cancelled by a newer push; the group's run still decides.
130
+ */
118
131
  export function latestAttempts(runs: readonly CheckRun[]): CheckRun[] {
119
132
  const byName = new Map<string, CheckRun>();
133
+ const undecided = (r: CheckRun) => r.status === "completed" && (r.conclusion === "skipped" || (r.conclusion !== null && UNBUILT_CONCLUSIONS.has(r.conclusion)));
134
+ const decided = (r: CheckRun) => r.status === "completed" && !undecided(r);
120
135
  for (const r of runs) {
121
136
  const seen = byName.get(r.name);
122
- if (!seen || r.id > seen.id) byName.set(r.name, r);
137
+ if (!seen) byName.set(r.name, r);
138
+ else if (r.id > seen.id ? !(undecided(r) && decided(seen)) : undecided(seen) && decided(r)) byName.set(r.name, r);
123
139
  }
124
140
  return [...byName.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
125
141
  }
@@ -262,6 +278,8 @@ export interface TickPlanInput {
262
278
  now: Date;
263
279
  /** Signs each tag's record (#4031). Without it the tags carry no statement. */
264
280
  signer?: CiTagSigner;
281
+ /** A lane (#4662): its tags, `ci/green-<lane>/` and `ci/revoked-<lane>/`, with the lane in each record. `green.require` is then the lane's. */
282
+ lane?: string;
265
283
  }
266
284
 
267
285
  /** A time as an annotation and a tick report write it: UTC, to the second. */
@@ -292,22 +310,23 @@ function recordJson(record: CiTagRecord, signer: CiTagSigner | undefined): strin
292
310
  }
293
311
 
294
312
  /** The annotation of a green tag: a subject line, then the record as JSON, signed when `signer` is given (#4031). */
295
- export function greenAnnotation(green: CiGreen, sha: string, verdict: CommitVerdict, at: Date, signer?: CiTagSigner): string {
313
+ export function greenAnnotation(green: CiGreen, sha: string, verdict: CommitVerdict, at: Date, signer?: CiTagSigner, lane?: string): string {
296
314
  const record: CiTagRecord = {
297
315
  schema: 1,
298
316
  tag: "green",
299
317
  commit: sha,
300
318
  branch: green.branch,
319
+ ...(lane !== undefined ? { lane } : {}),
301
320
  at: iso(at),
302
321
  ...sourceField(green),
303
322
  phases: Object.fromEntries(verdict.phases.map((p) => [p.phase, p.runs.map(runRecord)])),
304
323
  };
305
- return `ci: every required phase passed (${green.require.join(", ")})\n\n${recordJson(record, signer)}\n`;
324
+ return `ci: ${lane !== undefined ? `every phase of lane ${lane} passed` : "every required phase passed"} (${green.require.join(", ")})\n\n${recordJson(record, signer)}\n`;
306
325
  }
307
326
 
308
327
  /** The annotation of a revoked tag: the phase and the run that failed, and the time, signed when `signer` is given (#4031). */
309
- export function revokedAnnotation(green: CiGreen, sha: string, failure: NonNullable<CommitVerdict["failure"]>, at: Date, signer?: CiTagSigner): string {
310
- const record: CiTagRecord = { schema: 1, tag: "revoked", commit: sha, branch: green.branch, at: iso(at), ...sourceField(green), phase: failure.phase, run: runRecord(failure.run) };
328
+ export function revokedAnnotation(green: CiGreen, sha: string, failure: NonNullable<CommitVerdict["failure"]>, at: Date, signer?: CiTagSigner, lane?: string): string {
329
+ const record: CiTagRecord = { schema: 1, tag: "revoked", commit: sha, branch: green.branch, ...(lane !== undefined ? { lane } : {}), at: iso(at), ...sourceField(green), phase: failure.phase, run: runRecord(failure.run) };
311
330
  const code = failure.run.failureCode ? `, ${failure.run.failureCode}` : "";
312
331
  return `ci: phase ${failure.phase} failed in ${failure.run.name} (${failure.run.conclusion ?? failure.run.status}${code})\n\n${recordJson(record, signer)}\n`;
313
332
  }
@@ -329,10 +348,11 @@ export async function planTick(input: TickPlanInput): Promise<TickCommit[]> {
329
348
  }
330
349
  const verdict = evaluateCommit(input.green, await input.checkRuns(c.sha));
331
350
  let made: TickCommit["made"] = null;
351
+ const prefixes = input.lane !== undefined ? laneTagPrefixes(input.lane) : { green: CI_GREEN_TAG_PREFIX, revoked: CI_REVOKED_TAG_PREFIX };
332
352
  if (before === "none" && verdict.verdict === "pass") {
333
- made = { tag: `${CI_GREEN_TAG_PREFIX}${c.sha}`, message: greenAnnotation(input.green, c.sha, verdict, input.now, input.signer) };
353
+ made = { tag: `${prefixes.green}${c.sha}`, message: greenAnnotation(input.green, c.sha, verdict, input.now, input.signer, input.lane) };
334
354
  } else if (before === "green" && verdict.verdict === "fail") {
335
- made = { tag: `${CI_REVOKED_TAG_PREFIX}${c.sha}`, message: revokedAnnotation(input.green, c.sha, verdict.failure!, input.now, input.signer) };
355
+ made = { tag: `${prefixes.revoked}${c.sha}`, message: revokedAnnotation(input.green, c.sha, verdict.failure!, input.now, input.signer, input.lane) };
336
356
  }
337
357
  const ignored = input.ignored?.get(c.sha);
338
358
  // A tag is never moved or deleted by chant, so an ignored tag holding the name stops the tick making it.
@@ -374,11 +394,11 @@ interface CiTagRef {
374
394
  target: string;
375
395
  }
376
396
 
377
- /** Every ci tag in the repository, read from local refs. */
378
- function readCiTagRefs(top: string): CiTagRef[] {
397
+ /** Every ci tag in the repository, read from local refs: `ci/green/` and `ci/revoked/`, or a lane's (#4662). */
398
+ function readCiTagRefs(top: string, prefixes: { green: string; revoked: string } = { green: CI_GREEN_TAG_PREFIX, revoked: CI_REVOKED_TAG_PREFIX }): CiTagRef[] {
379
399
  const out: CiTagRef[] = [];
380
400
  const format = "%(refname:lstrip=2)%00%(objecttype)%00%(objectname)%00%(*objectname)%00%(taggerdate:iso-strict)%00%(contents)%01";
381
- const raw = git(top, ["for-each-ref", `--format=${format}`, `refs/tags/${CI_GREEN_TAG_PREFIX}`, `refs/tags/${CI_REVOKED_TAG_PREFIX}`]);
401
+ const raw = git(top, ["for-each-ref", `--format=${format}`, `refs/tags/${prefixes.green}`, `refs/tags/${prefixes.revoked}`]);
382
402
  for (const entry of raw.split("\u0001")) {
383
403
  const [tag, type, object, peeled, date, contents] = entry.replace(/^\n/, "").split("\u0000");
384
404
  if (!tag) continue;
@@ -393,10 +413,10 @@ function readCiTagRefs(top: string): CiTagRef[] {
393
413
  record = null;
394
414
  }
395
415
  }
396
- const green = tag.startsWith(CI_GREEN_TAG_PREFIX);
416
+ const green = tag.startsWith(prefixes.green);
397
417
  out.push({
398
418
  kind: green ? "green" : "revoked",
399
- sha: tag.slice((green ? CI_GREEN_TAG_PREFIX : CI_REVOKED_TAG_PREFIX).length),
419
+ sha: tag.slice((green ? prefixes.green : prefixes.revoked).length),
400
420
  tag,
401
421
  tagged: date || null,
402
422
  record,
@@ -458,12 +478,17 @@ export function unsignedHistory(top: string, signedSince: string): Set<string> {
458
478
  * `base`, the commit the caller reads the branch at. Throws
459
479
  * `declaration-invalid` when `signedSince` names no commit here.
460
480
  */
461
- export function readCiTags(top: string, green: CiGreen | null = null, base: string | null = null): CiTags {
481
+ /**
482
+ * The ci tags that count, by commit, and those that exist and don't. With
483
+ * `lane` (#4662), a lane's tags: `ci/green-<lane>/` and `ci/revoked-<lane>/`,
484
+ * whose signed statements must name that lane.
485
+ */
486
+ export function readCiTags(top: string, green: CiGreen | null = null, base: string | null = null, lane?: string): CiTags {
462
487
  const out: CiTags = { green: new Map(), revoked: new Map(), ignored: new Map() };
463
488
  const before = green?.signedSince ? unsignedHistory(top, green.signedSince) : null;
464
489
  let policy: ReturnType<typeof readTrustPolicy> | undefined;
465
490
  const policyAtBase = () => (policy ??= base ? readTrustPolicy(gitRevisionSource(top, base), base) : emptyPolicy(null));
466
- for (const t of readCiTagRefs(top)) {
491
+ for (const t of readCiTagRefs(top, lane !== undefined ? laneTagPrefixes(lane) : undefined)) {
467
492
  const counted = (signer: string | null) => (t.kind === "green" ? out.green : out.revoked).set(t.sha, { tagged: t.tagged, record: t.record, signer });
468
493
  if (before === null) {
469
494
  counted(null);
@@ -481,7 +506,7 @@ export function readCiTags(top: string, green: CiGreen | null = null, base: stri
481
506
  const p = policyAtBase();
482
507
  // A tag the tick made walking a compose branch (#4168 4.3) is checked against that branch.
483
508
  const walked = isComposeBranch(t.record?.branch) ? (t.record!.branch as string) : green!.branch;
484
- const v = verifyCiTagStatement(t.record, { sha: t.sha, kind: t.kind, branch: walked }, p.runners, p.roles);
509
+ const v = verifyCiTagStatement(t.record, { sha: t.sha, kind: t.kind, branch: walked, ...(lane !== undefined ? { lane } : {}) }, p.runners, p.roles);
485
510
  if (v.status === "signed") counted(v.signer);
486
511
  else ignore(v.status, `${v.reason}; ci.green.signedSince is ${green!.signedSince}, so a tag on a commit that is not a strict first-parent ancestor of it needs one`);
487
512
  }
@@ -553,6 +578,10 @@ export interface TickRequest {
553
578
  * `ci.green.signedSince` is set the tick needs one.
554
579
  */
555
580
  runnerKey?: string;
581
+ /** The environment `ci.green.notify`'s variables are read from (#4645). Default `process.env`. */
582
+ env?: NodeJS.ProcessEnv;
583
+ /** Delivers a `ci.` event (#4645). Default notify's own `sendNotify`; tests give a fake. */
584
+ sendNotify?: typeof sendNotify;
556
585
  }
557
586
 
558
587
  /** One compose branch a tick walked (#4168 4.3): its composed commits within the window. */
@@ -572,8 +601,15 @@ export interface TickResult {
572
601
  commits: TickCommit[];
573
602
  /** The compose branches walked (#4168 4.3), each with its composed commits judged. Their tags are in `made`. */
574
603
  composed: ComposedBranchTick[];
575
- /** The tags made and pushed, or that would be under `dryRun`. */
604
+ /** The tags made and pushed, or that would be under `dryRun`, lanes' included. */
576
605
  made: string[];
606
+ /** Each lane's commits, judged from the same runs (#4662). Absent when `ci.green` declares no lanes. */
607
+ lanes?: { lane: string; commits: TickCommit[] }[];
608
+ /**
609
+ * The `ci.` events told (#4645), or that would be under `dryRun` (`sent` false). `sent` is false too when
610
+ * `ci.green.notify` names no variable that is set, or filters the event out. Absent without `ci.green.notify`.
611
+ */
612
+ notified?: { event: string; commit: string; sent: boolean }[];
577
613
  /** The builds asked for (#4169), as `ci/build/<sha>` tags made and pushed, or that would be under `dryRun`. */
578
614
  requested: BuildRequest[];
579
615
  /** The failed runs asked to run again through the forge (#4169). */
@@ -725,11 +761,28 @@ export async function ciTick(req: TickRequest): Promise<TickResult> {
725
761
  if (ignored && ignored.length > 0) c.ignoredRuns = ignored;
726
762
  }
727
763
  }
764
+ // Lanes (#4662): each judged from the runs the branch's pass read, with tags of its own. They ask for no builds or retries.
765
+ const lanes: { lane: string; commits: TickCommit[] }[] = [];
766
+ for (const lane of green.lanes ?? []) {
767
+ const own = readCiTags(top, green, base, lane.name);
768
+ const judged = await planTick({
769
+ green: { ...green, require: lane.require },
770
+ commits,
771
+ greenTags: new Set(own.green.keys()),
772
+ revokedTags: new Set(own.revoked.keys()),
773
+ ignored: own.ignored,
774
+ checkRuns: async (sha) => runsBy.get(sha) ?? (runs ? runs.checkRuns(sha) : await forge!.checkRuns(sha)),
775
+ now,
776
+ signer,
777
+ lane: lane.name,
778
+ });
779
+ lanes.push({ lane: lane.name, commits: judged });
780
+ }
728
781
  const records = ledgerOk ? readCiRecords(top) : new Map<string, CiRecord>();
729
782
  const requests = readBuildRequests(top);
730
783
  const retryVia = green.source === "runs" ? "request" : forge?.rerun ? "forge" : null;
731
784
  const builds = planBuilds({ green, commits: planned, runs: runsBy, requests, records, now, retryVia });
732
- const due = [...planned, ...composed.flatMap((b) => b.commits)].filter((c) => c.made !== null);
785
+ const due = [...planned, ...composed.flatMap((b) => b.commits), ...lanes.flatMap((l) => l.commits)].filter((c) => c.made !== null);
733
786
  // Decision 4: revoking a trunk commit says which composed commits carry it; their own CI decides their releases.
734
787
  for (const c of planned) {
735
788
  if (!c.made?.tag.startsWith(CI_REVOKED_TAG_PREFIX)) continue;
@@ -750,10 +803,32 @@ export async function ciTick(req: TickRequest): Promise<TickResult> {
750
803
  }
751
804
  }
752
805
  const retried = builds.retries.map((r) => ({ sha: r.sha, run: r.run.name }));
806
+ // #4645: what to tell people, decided from the records this tick writes. Without records a tick can't
807
+ // remember what it sent, so it sends nothing rather than the same event every time.
808
+ const canRecord = ledgerOk && !ledgerRecordingOff();
809
+ const events = green.notify && canRecord ? tickEvents({ green, planned, records, builds, requests, now }) : [];
810
+ const notified: TickResult["notified"] = [];
811
+ const marks = new Map<string, NonNullable<CiRecord["notified"]>>();
812
+ for (const e of events) {
813
+ if (req.dryRun) {
814
+ notified.push({ event: e.fields.event, commit: e.fields.ci!.commit, sent: false });
815
+ continue;
816
+ }
817
+ const event = makeNotifyEvent(e.fields, { env: tickEventEnv(req.env ?? process.env), now });
818
+ const deliveries = await (req.sendNotify ?? sendNotify)(green.notify, event, { env: req.env ?? process.env, log: () => {} });
819
+ const failed = deliveries.filter((d) => !d.ok);
820
+ // Nothing configured or filtered out counts as told; every delivery failing is tried again next tick.
821
+ if (deliveries.length > 0 && failed.length === deliveries.length) {
822
+ warnings.push(`could not send ${e.fields.event} for ${e.fields.ci!.commit.slice(0, 12)}: ${failed.map((d) => `${d.target} ${d.detail}`).join(", ")}; the next tick tries again`);
823
+ continue;
824
+ }
825
+ notified.push({ event: e.fields.event, commit: e.fields.ci!.commit, sent: deliveries.length > 0 });
826
+ marks.set(e.mark.sha, { ...(marks.get(e.mark.sha) ?? {}), ...e.mark.notified });
827
+ }
753
828
  let recorded: string[] = [];
754
829
  if (!req.dryRun) {
755
830
  const asked = await askForBuilds({ top, remote, green, forge, builds, requests, records, planned, warnings });
756
- recorded = ledgerOk && !ledgerRecordingOff() ? await writeRecords({ top, green, planned, records, builds, requests: asked.live, dispatched: asked.dispatched, now, warnings }) : [];
831
+ recorded = canRecord ? await writeRecords({ top, green, planned, records, builds, requests: asked.live, dispatched: asked.dispatched, now, warnings, notified: marks }) : [];
757
832
  }
758
833
  return {
759
834
  branch: green.branch,
@@ -762,6 +837,8 @@ export async function ciTick(req: TickRequest): Promise<TickResult> {
762
837
  commits: planned,
763
838
  made: due.map((c) => c.made!.tag),
764
839
  composed,
840
+ ...(lanes.length > 0 ? { lanes } : {}),
841
+ ...(green.notify ? { notified } : {}),
765
842
  requested: builds.requests,
766
843
  retried,
767
844
  recorded,
@@ -771,6 +848,73 @@ export async function ciTick(req: TickRequest): Promise<TickResult> {
771
848
  };
772
849
  }
773
850
 
851
+ /**
852
+ * The `ci.` events a tick tells (#4645), from the records it is about to
853
+ * write: `ci.red` once for the branch's newest decided commit when it is
854
+ * red (a phase that is being retried is pending, not red, so this is red
855
+ * after the retry), `ci.culprit` once per culprit a bisect names below that
856
+ * commit, and `ci.green` when the newest decided commit is green and an
857
+ * older one in the window was told red and not yet answered. Each carries
858
+ * the record mark that keeps the next tick from telling it again.
859
+ */
860
+ export function tickEvents(input: {
861
+ green: CiGreen;
862
+ planned: readonly TickCommit[];
863
+ records: ReadonlyMap<string, CiRecord>;
864
+ builds: ReturnType<typeof planBuilds>;
865
+ requests: ReadonlyMap<string, BuildRequest>;
866
+ now: Date;
867
+ }): { fields: NotifyFields; mark: { sha: string; notified: NonNullable<CiRecord["notified"]> } }[] {
868
+ const { green, records, now } = input;
869
+ const next = input.planned.map((c) => ({ sha: c.sha, record: recordOf({ green, commit: c, previous: records.get(c.sha), retries: input.builds.retries, requests: input.requests, now }) }));
870
+ const at = next.findIndex((x) => x.record.state === "green" || x.record.state === "red");
871
+ if (at < 0) return [];
872
+ const { sha, record } = next[at]!;
873
+ const told = records.get(sha)?.notified ?? {};
874
+ const short = sha.slice(0, 12);
875
+ const out: ReturnType<typeof tickEvents> = [];
876
+ if (record.state === "red") {
877
+ const failure = record.failure;
878
+ if (!told.red) {
879
+ out.push({
880
+ fields: {
881
+ source: "chant",
882
+ event: "ci.red",
883
+ summary: `${green.branch} is red at ${short}${failure ? `: phase ${failure.phase}, ${failure.run.name} ${failure.run.conclusion ?? "failed"}` : record.revoked ? ": its green tag was revoked" : ""}`,
884
+ targets: failure ? [failure.phase] : [],
885
+ ci: { branch: green.branch, commit: sha, ...(failure ? { phase: failure.phase, failedRun: failure.run } : {}) },
886
+ run: { commit: sha },
887
+ },
888
+ mark: { sha, notified: { red: iso(now) } },
889
+ });
890
+ }
891
+ const culprit = Object.values(record.phases).find((p) => p.culprit)?.culprit;
892
+ // A tip that is its own culprit says nothing ci.red didn't.
893
+ if (culprit && culprit !== sha && told.culprit !== culprit) {
894
+ out.push({
895
+ fields: { source: "chant", event: "ci.culprit", summary: `${green.branch} went red at ${culprit.slice(0, 12)}, found by bisecting below ${short}`, targets: [], ci: { branch: green.branch, commit: sha, culprit }, run: { commit: culprit } },
896
+ mark: { sha, notified: { culprit } },
897
+ });
898
+ }
899
+ return out;
900
+ }
901
+ // Green: answer the newest commit below it that was told red and not yet answered.
902
+ const answered = next.slice(at + 1).find((x) => records.get(x.sha)?.notified?.red && !records.get(x.sha)?.notified?.green);
903
+ if (answered) {
904
+ out.push({
905
+ fields: { source: "chant", event: "ci.green", summary: `${green.branch} is green again at ${short}, after ${answered.sha.slice(0, 12)} was red`, targets: [], ci: { branch: green.branch, commit: sha, red: answered.sha }, run: { commit: sha } },
906
+ mark: { sha: answered.sha, notified: { green: sha } },
907
+ });
908
+ }
909
+ return out;
910
+ }
911
+
912
+ /** The tick's environment for an event's run fields: its repository and forge, without the tick's own run link, which says nothing about the commit. */
913
+ function tickEventEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
914
+ const { GITHUB_RUN_ID: _r, CI_JOB_URL: _j, CI_PIPELINE_URL: _p, GITHUB_SHA: _s, CI_COMMIT_SHA: _c, ...rest } = env;
915
+ return rest;
916
+ }
917
+
774
918
  /**
775
919
  * Make what the plan asks for (#4169): push each new request tag and start
776
920
  * the workflows holding its phases at it on GitHub, start any older request
@@ -869,13 +1013,18 @@ async function writeRecords(input: {
869
1013
  dispatched: Set<string>;
870
1014
  now: Date;
871
1015
  warnings: string[];
1016
+ /** What the tick told people this time (#4645), merged into each commit's `notified`. */
1017
+ notified?: ReadonlyMap<string, NonNullable<CiRecord["notified"]>>;
872
1018
  }): Promise<string[]> {
873
1019
  const { top, green, planned, records, builds, requests, now, warnings } = input;
874
1020
  const writes: { path: string; content: string }[] = [];
875
1021
  const inWindow = new Set(planned.map((c) => c.sha));
876
1022
  for (const c of planned) {
877
1023
  const previous = records.get(c.sha);
878
- let record = recordOf({ green, commit: c, previous, retries: builds.retries, requests, now });
1024
+ const mark = input.notified?.get(c.sha);
1025
+ // The marks go in through `previous`, so recordOf keeps its key order and the next tick finds the same record.
1026
+ const carried = mark ? ({ ...(previous ?? {}), notified: { ...(previous?.notified ?? {}), ...mark } } as CiRecord) : previous;
1027
+ let record = recordOf({ green, commit: c, previous: carried, retries: builds.retries, requests, now });
879
1028
  if (record.request) {
880
1029
  const started = input.dispatched.has(c.sha) || (previous?.request?.tag === record.request.tag && previous.request.dispatched === true);
881
1030
  if (started) record = { ...record, request: { ...record.request, dispatched: true } };
@@ -1162,6 +1311,14 @@ export function formatTick(r: TickResult, dryRun = false): string {
1162
1311
  for (const r of c.ignoredRuns ?? []) lines.push(` ignored run ${r.run} of ${r.op} in ${r.env} (${r.status}): ${r.reason}`);
1163
1312
  if (c.blocked) lines.push(` did not make ${c.blocked}: an ignored tag holds the name. Delete it to let the tick tag the commit: git push origin :refs/tags/${c.blocked}`);
1164
1313
  }
1314
+ // #4645: each ci. event told, or that would be.
1315
+ for (const n of r.notified ?? []) lines.push(` ${n.commit.slice(0, 12)} ${dryRun ? "would tell" : n.sent ? "told" : "noted (no notify variable set)"} ${n.event}`);
1316
+ // Lanes (#4662): only the commits a lane tags, so a quiet tick stays short.
1317
+ for (const l of r.lanes ?? []) {
1318
+ for (const c of l.commits.filter((x) => x.made)) {
1319
+ lines.push(` ${c.sha.slice(0, 12)} lane ${l.lane}: ${dryRun ? "would make" : "made"} ${c.made!.tag.slice(0, c.made!.tag.lastIndexOf("/"))}${c.verdict?.failure ? `: phase ${c.verdict.failure.phase}, ${c.verdict.failure.run.name} ${c.verdict.failure.run.conclusion}` : ""}`);
1320
+ }
1321
+ }
1165
1322
  for (const b of r.composed ?? []) {
1166
1323
  lines.push(`${b.branch}, composed commits within ${r.window}: ${b.commits.length}`);
1167
1324
  for (const c of b.commits) {
@@ -1218,7 +1375,7 @@ export const LAST_GREEN_NEWER = 50;
1218
1375
  * green tag and no revoked tag. It reads local refs and tags and never
1219
1376
  * fetches, so a reader fetches first (`git fetch origin --tags`).
1220
1377
  */
1221
- export function lastGreen(req: { cwd: string; remote?: string; from?: string; branch?: string }): LastGreenDocument {
1378
+ export function lastGreen(req: { cwd: string; remote?: string; from?: string; branch?: string; lane?: string }): LastGreenDocument {
1222
1379
  const head = { $schema: CI_LAST_GREEN_SCHEMA_ID, contract: CI_LAST_GREEN_CONTRACT_VERSION, chant: readerVersion() };
1223
1380
  try {
1224
1381
  const read = readGreen(req.cwd);
@@ -1232,8 +1389,11 @@ export function lastGreen(req: { cwd: string; remote?: string; from?: string; br
1232
1389
  }
1233
1390
  ref = req.from;
1234
1391
  }
1392
+ // #4662: a lane reads its own tags.
1393
+ const lane = req.lane !== undefined ? laneOf(green, req.lane).name : undefined;
1394
+ const prefix = lane !== undefined ? laneTagPrefixes(lane).green : CI_GREEN_TAG_PREFIX;
1235
1395
  // The runner keys are read where the branch is, whichever commit the walk starts from.
1236
- const tags = readCiTags(top, green, git(top, ["rev-parse", `${branchRef}^{commit}`]));
1396
+ const tags = readCiTags(top, green, git(top, ["rev-parse", `${branchRef}^{commit}`]), lane);
1237
1397
  let commit: Extract<LastGreenDocument, { branch: string }>["commit"] = null;
1238
1398
  const ignored: IgnoredCiTag[] = [];
1239
1399
  const newer: { sha: string; record: CiRecordSummary | null }[] = [];
@@ -1245,7 +1405,7 @@ export function lastGreen(req: { cwd: string; remote?: string; from?: string; br
1245
1405
  if (newer.length < LAST_GREEN_NEWER) newer.push({ sha, record: recordSummary(green, records.get(sha)) });
1246
1406
  continue;
1247
1407
  }
1248
- commit = { sha, tag: `${CI_GREEN_TAG_PREFIX}${sha}`, tagged: tags.green.get(sha)!.tagged, committed: git(top, ["show", "-s", "--format=%cI", sha]) };
1408
+ commit = { sha, tag: `${prefix}${sha}`, tagged: tags.green.get(sha)!.tagged, committed: git(top, ["show", "-s", "--format=%cI", sha]) };
1249
1409
  break;
1250
1410
  }
1251
1411
  }
@@ -1256,6 +1416,109 @@ export function lastGreen(req: { cwd: string; remote?: string; from?: string; br
1256
1416
  }
1257
1417
  }
1258
1418
 
1419
+ // ── verdict ──────────────────────────────────────────────────────────────────
1420
+
1421
+ /** How long `ci verdict --wait` waits between reads of the check runs. */
1422
+ export const CI_VERDICT_INTERVAL_MS = 30_000;
1423
+
1424
+ /**
1425
+ * `chant ci verdict` (#4644): judge one commit by ci.green's required phases
1426
+ * from its check runs, as the tick judges a commit, leaving out the
1427
+ * verdict's own check run (`chant-verdict`). With `wait`, read again until no
1428
+ * phase is pending. A merge queue's verdict job runs it on the group's commit.
1429
+ */
1430
+ export async function ciVerdict(req: { cwd: string; sha: string; forge: CiForge; wait?: boolean; branch?: string; sleep?: (ms: number) => Promise<void>; onPending?: (v: CommitVerdict) => void }): Promise<{ sha: string; verdict: CommitVerdict }> {
1431
+ const read = readGreen(req.cwd);
1432
+ const green = greenOn(read.green, req.branch);
1433
+ const sleep = req.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
1434
+ for (;;) {
1435
+ const runs = (await req.forge.checkRuns(req.sha)).filter((r) => r.name !== MERGE_QUEUE_VERDICT_JOB);
1436
+ const verdict = evaluateCommit(green, runs);
1437
+ if (!req.wait || verdict.verdict !== "pending") return { sha: req.sha, verdict };
1438
+ req.onPending?.(verdict);
1439
+ await sleep(CI_VERDICT_INTERVAL_MS);
1440
+ }
1441
+ }
1442
+
1443
+ // ── base ─────────────────────────────────────────────────────────────────────
1444
+
1445
+ /**
1446
+ * `ci base`'s document (#4643): `ci last-green`'s, with the phase asked about
1447
+ * and how the commit was found. `via` is `record` when the commit's record
1448
+ * shows the phase built and passed on it, `tag` when the commit has no record
1449
+ * and counts by its green tag alone.
1450
+ */
1451
+ export type CiBaseDocument =
1452
+ | (Omit<Extract<LastGreenDocument, { branch: string }>, "commit"> & {
1453
+ phase: string | null;
1454
+ /** `tag` is null for a commit whose record passed the phase asked about but which has no green tag. */
1455
+ commit: { sha: string; tag: string | null; tagged: string | null; committed: string; via: "record" | "tag" } | null;
1456
+ })
1457
+ | Extract<LastGreenDocument, { error: unknown }>;
1458
+
1459
+ /**
1460
+ * `chant ci base` (#4643): the commit a path filter should diff against
1461
+ * under `build: newest`. Walks the first-parent ancestors of `from` (HEAD by
1462
+ * default), leaving `from` itself out, and returns the newest one where
1463
+ * `phase` (or, without one, every required phase) ran on that very commit
1464
+ * and passed. A superseded commit is passed over: it was never built, and
1465
+ * a newer build that covers it is not the base of a commit above it. A red
1466
+ * one is passed over too, so a change on top of a failure doesn't skip the
1467
+ * job that failed. A commit with no record (outside the tick's window)
1468
+ * counts when it has a green tag and no revoked one, as `ci last-green`
1469
+ * reads them. Reads local refs only: the records on `chant/lifecycle`, or
1470
+ * on `origin/chant/lifecycle` when there is no local branch, and the tags.
1471
+ */
1472
+ export function ciBase(req: { cwd: string; from?: string; branch?: string; phase?: string; lane?: string; remote?: string }): CiBaseDocument {
1473
+ const head = { $schema: CI_LAST_GREEN_SCHEMA_ID, contract: CI_LAST_GREEN_CONTRACT_VERSION, chant: readerVersion() };
1474
+ try {
1475
+ const read = readGreen(req.cwd);
1476
+ const { top, workspace } = read;
1477
+ const green = greenOn(read.green, req.branch);
1478
+ if (req.phase !== undefined && !green.phases.some((p) => p.name === req.phase)) {
1479
+ throw new Error(`ci.green declares no phase ${JSON.stringify(req.phase)}; it declares ${green.phases.map((p) => p.name).join(", ")}`);
1480
+ }
1481
+ if (req.phase !== undefined && req.lane !== undefined) throw new Error("--phase and --lane each choose the phases to check; give one");
1482
+ // #4662: a lane's phases, and its tags for a commit with no record.
1483
+ const lane = req.lane !== undefined ? laneOf(green, req.lane) : undefined;
1484
+ const from = req.from ?? "HEAD";
1485
+ if (from.startsWith("-") || tryGit(top, ["rev-parse", "--verify", "--quiet", `${from}^{commit}`]) === null) {
1486
+ throw new WorkspaceReadError("revision-unknown", `--from ${from} names no commit in this repository`);
1487
+ }
1488
+ const branchRef = tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/remotes/${req.remote ?? "origin"}/${green.branch}^{commit}`]) ?? tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/heads/${green.branch}^{commit}`]);
1489
+ const tags = readCiTags(top, green, branchRef, lane?.name);
1490
+ const ledger = tryGit(top, ["rev-parse", "--verify", "--quiet", CI_LEDGER_REF]) !== null ? CI_LEDGER_REF : `refs/remotes/${req.remote ?? "origin"}/chant/lifecycle`;
1491
+ const records = readCiRecords(top, ledger);
1492
+ const phases = req.phase !== undefined ? [req.phase] : (lane?.require ?? green.require);
1493
+ const builtHere = (r: CiRecord) =>
1494
+ phases.every((name) => {
1495
+ const p = r.phases[name];
1496
+ return p !== undefined && p.verdict === "pass" && p.coveredBy === undefined && p.runs.some((run) => run.conclusion !== null);
1497
+ });
1498
+ let commit: Extract<CiBaseDocument, { branch: string }>["commit"] = null;
1499
+ const ignored: IgnoredCiTag[] = [];
1500
+ const newer: { sha: string; record: CiRecordSummary | null }[] = [];
1501
+ const parent = tryGit(top, ["rev-parse", "--verify", "--quiet", `${from}^1^{commit}`]);
1502
+ for (const sha of parent ? git(top, ["rev-list", "--first-parent", parent]).split("\n") : []) {
1503
+ ignored.push(...(tags.ignored.get(sha) ?? []));
1504
+ const record = records.get(sha);
1505
+ const revoked = tags.revoked.has(sha) || record?.revoked === true;
1506
+ const via = revoked ? null : record ? (builtHere(record) ? "record" : null) : tags.green.has(sha) ? "tag" : null;
1507
+ if (!via) {
1508
+ if (newer.length < LAST_GREEN_NEWER) newer.push({ sha, record: recordSummary(green, record) });
1509
+ continue;
1510
+ }
1511
+ const tag = tags.green.get(sha);
1512
+ commit = { sha, tag: tag ? `${lane !== undefined ? laneTagPrefixes(lane.name).green : CI_GREEN_TAG_PREFIX}${sha}` : null, tagged: tag?.tagged ?? null, committed: git(top, ["show", "-s", "--format=%cI", sha]), via };
1513
+ break;
1514
+ }
1515
+ return { ...head, workspace, branch: green.branch, ref: from, phase: req.phase ?? null, commit, ignored, newer: commit ? newer : [] };
1516
+ } catch (err) {
1517
+ if (err instanceof CiGreenError || err instanceof WorkspaceReadError) return { ...head, error: { code: err.code, message: err instanceof WorkspaceReadError ? err.describe() : err.message } };
1518
+ throw err;
1519
+ }
1520
+ }
1521
+
1259
1522
  // ── list ─────────────────────────────────────────────────────────────────────
1260
1523
 
1261
1524
  export const CI_LIST_CONTRACT_VERSION = 1;
@@ -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",