@intentius/chant 0.124.60 → 0.124.61

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