@intentius/chant 0.124.70 → 0.124.72

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 (169) hide show
  1. package/dist/ci-agent.d.ts +12 -1
  2. package/dist/ci-agent.d.ts.map +1 -1
  3. package/dist/ci-agent.js +13 -8
  4. package/dist/ci-commit.d.ts +326 -0
  5. package/dist/ci-commit.d.ts.map +1 -0
  6. package/dist/ci-commit.js +725 -0
  7. package/dist/ci-estate/delivery.d.ts +75 -2
  8. package/dist/ci-estate/delivery.d.ts.map +1 -1
  9. package/dist/ci-estate/delivery.js +129 -0
  10. package/dist/ci-estate.d.ts +3 -1
  11. package/dist/ci-estate.d.ts.map +1 -1
  12. package/dist/ci-estate.js +4 -1
  13. package/dist/ci-product-words.d.ts +6 -1
  14. package/dist/ci-product-words.d.ts.map +1 -1
  15. package/dist/ci-product-words.js +3 -1
  16. package/dist/ci-product.d.ts +1 -1
  17. package/dist/ci-product.d.ts.map +1 -1
  18. package/dist/ci-product.js +1 -1
  19. package/dist/cli/handlers/approve.d.ts.map +1 -1
  20. package/dist/cli/handlers/approve.js +7 -2
  21. package/dist/cli/handlers/commit.d.ts +26 -0
  22. package/dist/cli/handlers/commit.d.ts.map +1 -0
  23. package/dist/cli/handlers/commit.js +145 -0
  24. package/dist/cli/handlers/notify-relay.d.ts.map +1 -1
  25. package/dist/cli/handlers/notify-relay.js +22 -2
  26. package/dist/cli/handlers/pr.d.ts +6 -0
  27. package/dist/cli/handlers/pr.d.ts.map +1 -1
  28. package/dist/cli/handlers/pr.js +16 -7
  29. package/dist/cli/handlers/release.d.ts +9 -0
  30. package/dist/cli/handlers/release.d.ts.map +1 -1
  31. package/dist/cli/handlers/release.js +114 -5
  32. package/dist/cli/main.d.ts.map +1 -1
  33. package/dist/cli/main.js +17 -0
  34. package/dist/components/product-pipeline.d.ts +33 -0
  35. package/dist/components/product-pipeline.d.ts.map +1 -1
  36. package/dist/components/product-pipeline.js +34 -1
  37. package/dist/components/release-compile.d.ts +2 -0
  38. package/dist/components/release-compile.d.ts.map +1 -1
  39. package/dist/components/release-compile.js +8 -4
  40. package/dist/config.d.ts +60 -0
  41. package/dist/config.d.ts.map +1 -1
  42. package/dist/config.js +16 -0
  43. package/dist/lexicon.d.ts +54 -0
  44. package/dist/lexicon.d.ts.map +1 -1
  45. package/dist/lexicon.js +28 -0
  46. package/dist/lifecycle/__fixtures__/publish-fakes.d.ts +4 -0
  47. package/dist/lifecycle/__fixtures__/publish-fakes.d.ts.map +1 -1
  48. package/dist/lifecycle/__fixtures__/publish-fakes.js +6 -2
  49. package/dist/lifecycle/gated-request.d.ts +3 -1
  50. package/dist/lifecycle/gated-request.d.ts.map +1 -1
  51. package/dist/lifecycle/gated-request.js +5 -2
  52. package/dist/lifecycle/git.d.ts.map +1 -1
  53. package/dist/lifecycle/git.js +57 -0
  54. package/dist/lifecycle/publish-declaration.d.ts +16 -0
  55. package/dist/lifecycle/publish-declaration.d.ts.map +1 -1
  56. package/dist/lifecycle/publish-declaration.js +35 -3
  57. package/dist/lifecycle/publish-forge.d.ts +12 -0
  58. package/dist/lifecycle/publish-forge.d.ts.map +1 -1
  59. package/dist/lifecycle/publish-forge.js +102 -19
  60. package/dist/lifecycle/publish-npm.d.ts +15 -0
  61. package/dist/lifecycle/publish-npm.d.ts.map +1 -1
  62. package/dist/lifecycle/publish-npm.js +28 -1
  63. package/dist/lifecycle/publish-oci.d.ts +2 -0
  64. package/dist/lifecycle/publish-oci.d.ts.map +1 -1
  65. package/dist/lifecycle/publish-oci.js +10 -0
  66. package/dist/lifecycle/release-cut.d.ts +7 -1
  67. package/dist/lifecycle/release-cut.d.ts.map +1 -1
  68. package/dist/lifecycle/release-cut.js +8 -1
  69. package/dist/lifecycle/release-images.d.ts +87 -0
  70. package/dist/lifecycle/release-images.d.ts.map +1 -0
  71. package/dist/lifecycle/release-images.js +138 -0
  72. package/dist/lifecycle/release-publish.d.ts +2 -0
  73. package/dist/lifecycle/release-publish.d.ts.map +1 -1
  74. package/dist/notify-relay.d.ts +41 -1
  75. package/dist/notify-relay.d.ts.map +1 -1
  76. package/dist/notify-relay.js +40 -0
  77. package/dist/notify.d.ts +16 -3
  78. package/dist/notify.d.ts.map +1 -1
  79. package/dist/notify.js +16 -10
  80. package/dist/op/activities/review-agent.d.ts.map +1 -1
  81. package/dist/op/activities/review-agent.js +4 -2
  82. package/dist/op/gate.d.ts +5 -1
  83. package/dist/op/gate.d.ts.map +1 -1
  84. package/dist/op/gate.js +7 -2
  85. package/dist/op/op-waves-notify.d.ts +1 -1
  86. package/dist/op/op-waves-notify.d.ts.map +1 -1
  87. package/dist/op/op-waves-notify.js +2 -1
  88. package/dist/op/op-waves-run.d.ts.map +1 -1
  89. package/dist/op/op-waves-run.js +12 -8
  90. package/dist/op/op-waves.d.ts +9 -0
  91. package/dist/op/op-waves.d.ts.map +1 -1
  92. package/dist/op/op-waves.js +11 -0
  93. package/dist/pr-forge-base.d.ts +18 -0
  94. package/dist/pr-forge-base.d.ts.map +1 -0
  95. package/dist/pr-forge-base.js +29 -0
  96. package/dist/release-floors.d.ts +1 -1
  97. package/dist/release-floors.js +1 -1
  98. package/dist/wave-runtime.mjs +315 -315
  99. package/dist/workspace/ci-green.d.ts.map +1 -1
  100. package/dist/workspace/ci-green.js +1 -2
  101. package/dist/workspace/release-workflow.d.ts +47 -0
  102. package/dist/workspace/release-workflow.d.ts.map +1 -1
  103. package/dist/workspace/release-workflow.js +258 -14
  104. package/package.json +1 -1
  105. package/src/ci-agent.ts +13 -8
  106. package/src/ci-commit.test.ts +415 -0
  107. package/src/ci-commit.ts +901 -0
  108. package/src/ci-estate/__fixtures__/terragucci-dora.json +1305 -0
  109. package/src/ci-estate/delivery.ts +186 -2
  110. package/src/ci-estate/records-delivery.test.ts +55 -0
  111. package/src/ci-estate.ts +10 -0
  112. package/src/ci-product-words.ts +6 -2
  113. package/src/ci-product.ts +1 -0
  114. package/src/cli/handlers/approve.ts +6 -2
  115. package/src/cli/handlers/commit.ts +155 -0
  116. package/src/cli/handlers/notify-relay.ts +21 -2
  117. package/src/cli/handlers/operator.test.ts +2 -0
  118. package/src/cli/handlers/pr-wave-approve-lines.test.ts +32 -0
  119. package/src/cli/handlers/pr.ts +17 -7
  120. package/src/cli/handlers/release.ts +110 -5
  121. package/src/cli/main.ts +17 -0
  122. package/src/components/product-pipeline.test.ts +28 -1
  123. package/src/components/product-pipeline.ts +54 -1
  124. package/src/components/release-compile.ts +9 -3
  125. package/src/config.ts +31 -0
  126. package/src/lexicon.ts +72 -0
  127. package/src/lifecycle/__fixtures__/publish-fakes.ts +11 -5
  128. package/src/lifecycle/gated-request-spend.test.ts +115 -0
  129. package/src/lifecycle/gated-request.ts +5 -2
  130. package/src/lifecycle/git.ts +53 -0
  131. package/src/lifecycle/ledger-two-clones.test.ts +132 -0
  132. package/src/lifecycle/publish-declaration.ts +35 -3
  133. package/src/lifecycle/publish-forge-notes.test.ts +193 -0
  134. package/src/lifecycle/publish-forge.ts +100 -22
  135. package/src/lifecycle/publish-npm.ts +31 -2
  136. package/src/lifecycle/publish-oci.ts +10 -0
  137. package/src/lifecycle/publish-targets.test.ts +2 -1
  138. package/src/lifecycle/release-cut.ts +17 -1
  139. package/src/lifecycle/release-images.test.ts +242 -0
  140. package/src/lifecycle/release-images.ts +174 -0
  141. package/src/lifecycle/release-publish.ts +2 -0
  142. package/src/notify-relay.test.ts +55 -1
  143. package/src/notify-relay.ts +49 -1
  144. package/src/notify.ts +25 -12
  145. package/src/op/activities/review-agent.test.ts +20 -1
  146. package/src/op/activities/review-agent.ts +5 -2
  147. package/src/op/gate.ts +7 -2
  148. package/src/op/op-waves-approve-target.test.ts +108 -0
  149. package/src/op/op-waves-notify.ts +2 -2
  150. package/src/op/op-waves-run.ts +12 -7
  151. package/src/op/op-waves.ts +12 -0
  152. package/src/pr-forge-base.test.ts +37 -0
  153. package/src/pr-forge-base.ts +36 -0
  154. package/src/release-floors.ts +1 -1
  155. package/src/workspace/__fixtures__/release-workflow/forgejo-plain-member.yml +26 -0
  156. package/src/workspace/__fixtures__/release-workflow/forgejo-plain.yml +23 -0
  157. package/src/workspace/__fixtures__/release-workflow/forgejo-secure-member.yml +27 -0
  158. package/src/workspace/__fixtures__/release-workflow/forgejo-secure.yml +24 -0
  159. package/src/workspace/__fixtures__/release-workflow/github-plain-member.yml +26 -0
  160. package/src/workspace/__fixtures__/release-workflow/github-plain.yml +23 -0
  161. package/src/workspace/__fixtures__/release-workflow/github-secure-member.yml +27 -0
  162. package/src/workspace/__fixtures__/release-workflow/github-secure.yml +24 -0
  163. package/src/workspace/__fixtures__/release-workflow/gitlab-plain-member.yml +13 -0
  164. package/src/workspace/__fixtures__/release-workflow/gitlab-plain.yml +12 -0
  165. package/src/workspace/__fixtures__/release-workflow/gitlab-secure-member.yml +14 -0
  166. package/src/workspace/__fixtures__/release-workflow/gitlab-secure.yml +13 -0
  167. package/src/workspace/ci-green.ts +1 -2
  168. package/src/workspace/release-workflow.test.ts +199 -0
  169. package/src/workspace/release-workflow.ts +356 -14
@@ -107,8 +107,8 @@ export interface Dora {
107
107
  drift_window_seconds: number;
108
108
  /** Whether any apply record was on the ledger. Without one only drift counts. */
109
109
  audit: boolean;
110
- /** Where the numbers came from: always `ledger` here. terragucci's own file has no such field. */
111
- source: "ledger";
110
+ /** `ledger` from {@link buildDelivery}. Absent from {@link buildRecordDelivery}, whose file is terragucci's shape, which has no such field. */
111
+ source?: "ledger";
112
112
  estate: DoraMetrics;
113
113
  projects: DoraProject[];
114
114
  }
@@ -431,3 +431,187 @@ export function deliveryGauges(dora: Dora, words: Pick<CiProductWords, "product"
431
431
  for (const p of dora.projects) of(p.project, p);
432
432
  return out;
433
433
  }
434
+
435
+ // ── from a product's own records (#4612) ────────────────────────────────
436
+
437
+ /**
438
+ * One line of a product's audit trail, as terragucci's reports bucket keeps
439
+ * it (`audit.jsonl`). Three kinds are read: `apply` (an applied or failed
440
+ * wave: `detail.commit`, `detail.roots`, `detail.failed`, and the
441
+ * `detail.approval` entry it applied under), `approval-requested` (a wave
442
+ * reaching its gate) and `approval`. `what` is the gate. Other kinds and
443
+ * results are left alone: a waiting wave is not an apply yet, and a refused
444
+ * one is the gate working.
445
+ */
446
+ export interface DeliveryAuditEntry {
447
+ id: string;
448
+ kind: string;
449
+ project: string;
450
+ at: string;
451
+ what: string;
452
+ digest: string | null;
453
+ result: string;
454
+ detail?: Record<string, unknown>;
455
+ }
456
+
457
+ /**
458
+ * One row of a product's report index. A plan row (`stages.plan`) says when
459
+ * a change was planned, on which pull request, and the set digests its waves
460
+ * bind. A drift row (`stages.drift`) says whether the check found drift and
461
+ * on which roots, when the open drift was first found (`drift_since`), and
462
+ * which drift a clean check cleared (`drift_cleared`).
463
+ */
464
+ export interface DeliveryIndexRow {
465
+ project: string;
466
+ stage: string;
467
+ finished: string;
468
+ commit?: string;
469
+ pull_request?: string;
470
+ wave_digests?: string[];
471
+ changed?: number;
472
+ drifted_roots?: string[];
473
+ drift_since?: string;
474
+ drift_cleared?: { since: string; roots: string[] };
475
+ }
476
+
477
+ /** One project's index rows. A control repo passes one per project it reads. */
478
+ export interface DeliveryRecordSource {
479
+ project: string;
480
+ rows: readonly DeliveryIndexRow[];
481
+ }
482
+
483
+ export interface RecordDeliveryOptions {
484
+ words?: Pick<CiProductWords, "product">;
485
+ now?: Date;
486
+ /** The index's stage names: `tf-plan` and `tf-drift` for terragucci. */
487
+ stages: { plan: string; drift: string };
488
+ }
489
+
490
+ const strings = (v: unknown): string[] => (Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : []);
491
+
492
+ /** A records apply: the shared {@link Apply} with the gate it passed and the approval it applied under. */
493
+ type RecordApply = Apply & { gate: string; approval?: string };
494
+
495
+ function recordApplies(entries: readonly DeliveryAuditEntry[]): RecordApply[] {
496
+ const seen = new Set<string>();
497
+ const out: RecordApply[] = [];
498
+ for (const e of entries) {
499
+ if (e.kind !== "apply" || (e.result !== "applied" && e.result !== "failed") || seen.has(e.id)) continue;
500
+ seen.add(e.id);
501
+ const d = e.detail ?? {};
502
+ out.push({
503
+ project: e.project,
504
+ at: at(e.at),
505
+ applied: e.result === "applied",
506
+ spec: e.what,
507
+ gate: e.what,
508
+ ...(e.digest !== null ? { digest: e.digest } : {}),
509
+ ...(typeof d.commit === "string" ? { commit: d.commit } : {}),
510
+ roots: strings(d.roots),
511
+ failed: strings(d.failed),
512
+ ...(typeof d.approval === "string" ? { approval: d.approval } : {}),
513
+ });
514
+ }
515
+ return out.sort((a, b) => a.at - b.at);
516
+ }
517
+
518
+ /**
519
+ * The lead time of an applied wave. Its plan is the plan row of the same
520
+ * commit, or the one whose wave digests hold the wave's digest (a pull
521
+ * request's head, planned before the merge commit applied); the change
522
+ * starts at the first plan of that row's pull request.
523
+ */
524
+ function recordLead(a: RecordApply, plans: readonly DeliveryIndexRow[], requests: readonly DeliveryAuditEntry[], approvals: Map<string, DeliveryAuditEntry>): Lead | undefined {
525
+ const before = plans.filter((r) => at(r.finished) <= a.at);
526
+ const matched = before
527
+ .filter((r) => (a.commit !== undefined && r.commit === a.commit) || (a.digest !== undefined && (r.wave_digests ?? []).some((d) => samePlanDigest(d, a.digest!))))
528
+ .sort((x, y) => at(y.finished) - at(x.finished))[0];
529
+ if (!matched) return undefined;
530
+ const pr = matched.pull_request;
531
+ const first = pr ? Math.min(...before.filter((r) => r.pull_request === pr).map((r) => at(r.finished))) : at(matched.finished);
532
+ const asked = requests
533
+ .filter((q) => q.project === a.project && q.what === a.gate && a.digest !== undefined && q.digest !== null && samePlanDigest(q.digest, a.digest) && at(q.at) <= a.at)
534
+ .map((q) => at(q.at))
535
+ .sort((x, y) => x - y)[0];
536
+ const approved = a.approval ? approvals.get(a.approval) : undefined;
537
+ const ok = approved ? Math.min(Math.max(at(approved.at), asked ?? first), a.at) : undefined;
538
+ if (asked === undefined) return { project: a.project, at: a.at, total: secs(first, a.at), before: secs(first, a.at), gate: 0, after: 0 };
539
+ const gateEnd = ok ?? asked;
540
+ return { project: a.project, at: a.at, total: secs(first, a.at), before: secs(first, Math.max(first, asked)), gate: secs(asked, gateEnd), after: secs(gateEnd, a.at) };
541
+ }
542
+
543
+ /**
544
+ * A project's drift incidents from its drift rows, oldest first. A row that
545
+ * found drift opens one at its `drift_since` (or, for a row written before
546
+ * that field, at the open incident or its own time); a clean row names the
547
+ * drift it cleared, since a later check of the same commit replaces the row
548
+ * that found it; a clean row of the old kind closes the open incident.
549
+ */
550
+ export function recordDriftIncidents(drifts: readonly DeliveryIndexRow[]): DriftIncident[] {
551
+ const incidents = new Map<number, DriftIncident>();
552
+ const get = (since: number): DriftIncident => {
553
+ let i = incidents.get(since);
554
+ if (!i) incidents.set(since, (i = { since, roots: new Set() }));
555
+ return i;
556
+ };
557
+ let open: number | undefined;
558
+ for (const r of [...drifts].sort((x, y) => at(x.finished) - at(y.finished))) {
559
+ if ((r.changed ?? 0) > 0) {
560
+ const since = r.drift_since ? at(r.drift_since) : (open ?? at(r.finished));
561
+ for (const x of r.drifted_roots ?? []) get(since).roots.add(x);
562
+ open = since;
563
+ } else if (r.drift_cleared) {
564
+ const i = get(at(r.drift_cleared.since));
565
+ for (const x of r.drift_cleared.roots) i.roots.add(x);
566
+ i.closed = Math.min(i.closed ?? Infinity, at(r.finished));
567
+ if (open === i.since) open = undefined;
568
+ } else if (open !== undefined) {
569
+ const i = get(open);
570
+ i.closed ??= at(r.finished);
571
+ open = undefined;
572
+ }
573
+ }
574
+ return [...incidents.values()].sort((a, b) => a.since - b.since);
575
+ }
576
+
577
+ function recordEventsOf(source: DeliveryRecordSource, entries: readonly DeliveryAuditEntry[], stages: RecordDeliveryOptions["stages"]): Events {
578
+ const mine = entries.filter((e) => e.project === source.project);
579
+ const applies = recordApplies(mine);
580
+ const rows = source.rows.filter((r) => r.project === source.project);
581
+ const plans = rows.filter((r) => r.stage === stages.plan);
582
+ const incidents = recordDriftIncidents(rows.filter((r) => r.stage === stages.drift));
583
+ const requests = mine.filter((e) => e.kind === "approval-requested");
584
+ const approvals = new Map(mine.filter((e) => e.kind === "approval").map((e) => [e.id, e]));
585
+ const leads = applies.filter((a) => a.applied).flatMap((a) => recordLead(a, plans, requests, approvals) ?? []);
586
+ const drifted = driftedApplies(applies, incidents);
587
+ const failures = applies.filter((a) => !a.applied || drifted.has(a)).map((a) => ({ project: a.project, at: a.at }));
588
+ const ar = applyRestores(applies);
589
+ const dr = incidents.filter((i) => i.closed !== undefined).map((i) => ({ project: source.project, at: i.closed!, seconds: secs(i.since, i.closed!), kind: "drift" as const }));
590
+ return { applies, leads, failures, drifted, restores: [...ar.restored, ...dr], open: ar.open + incidents.filter((i) => i.closed === undefined).length };
591
+ }
592
+
593
+ /**
594
+ * The metrics of every project and of the estate from a product's own
595
+ * records (#4612): its report index and its audit trail, for a member whose
596
+ * ledger holds no wave records and for a control repo that reads each
597
+ * project's bucket. The same numbers {@link buildDelivery} computes from the
598
+ * ledger, and the same file, `dora.json` in terragucci's shape. `entries`
599
+ * is undefined when there is no audit trail; then no apply counts and only
600
+ * drift does.
601
+ */
602
+ export function buildRecordDelivery(sources: readonly DeliveryRecordSource[], entries: readonly DeliveryAuditEntry[] | undefined, options: RecordDeliveryOptions): Dora {
603
+ const now = options.now ?? new Date();
604
+ const end = now.getTime();
605
+ const from = weekStart(end) - (DORA_WEEKS - 1) * WEEK_MS;
606
+ const events = sources.map((s) => recordEventsOf(s, entries ?? [], options.stages));
607
+ return {
608
+ schema: doraSchema(options.words),
609
+ generated: now.toISOString(),
610
+ weeks: DORA_WEEKS,
611
+ window: { from: new Date(from).toISOString(), to: now.toISOString() },
612
+ drift_window_seconds: DRIFT_WINDOW_SECONDS,
613
+ audit: entries !== undefined,
614
+ estate: metricsOf(merge(events), from, end),
615
+ projects: sources.map((s, i) => ({ project: s.project, ...metricsOf(events[i]!, from, end) })),
616
+ };
617
+ }
@@ -0,0 +1,55 @@
1
+ /**
2
+ * #4612: delivery metrics from a product's own records, the report index and
3
+ * the audit trail. `__fixtures__/terragucci-dora.json` holds a fixture and
4
+ * the `dora.json` terragucci's own `buildDora` (report/dora.ts at terragucci
5
+ * main d8878e4) wrote for it, with and without the audit trail and with no
6
+ * sources. chant's numbers must be the same, byte for byte.
7
+ */
8
+ import { describe, expect, test } from "vitest";
9
+ import { readFileSync } from "node:fs";
10
+ import { join } from "node:path";
11
+ import { buildDelivery, buildRecordDelivery, type DeliveryAuditEntry, type DeliveryRecordSource, type Dora } from "./delivery";
12
+ import { assertProductWords } from "../ci-product-words";
13
+
14
+ const golden = JSON.parse(readFileSync(join(__dirname, "__fixtures__", "terragucci-dora.json"), "utf-8")) as {
15
+ now: string;
16
+ sources: DeliveryRecordSource[];
17
+ entries: DeliveryAuditEntry[];
18
+ dora: Dora;
19
+ noAudit: Dora;
20
+ empty: Dora;
21
+ };
22
+ const options = { words: assertProductWords({ product: "terragucci" }), now: new Date(golden.now), stages: { plan: "tf-plan", drift: "tf-drift" } };
23
+
24
+ describe("buildRecordDelivery (#4612)", () => {
25
+ test("gives terragucci's dora.json for its index and audit trail", () => {
26
+ expect(buildRecordDelivery(golden.sources, golden.entries, options)).toEqual(golden.dora);
27
+ expect(JSON.stringify(buildRecordDelivery(golden.sources, golden.entries, options))).toBe(JSON.stringify(golden.dora));
28
+ });
29
+
30
+ test("with no audit trail only drift counts, and with no sources the estate is empty, as terragucci's", () => {
31
+ expect(buildRecordDelivery(golden.sources, undefined, options)).toEqual(golden.noAudit);
32
+ expect(buildRecordDelivery([], [], options)).toEqual(golden.empty);
33
+ });
34
+
35
+ test("the fixture moves the numbers it is meant to: a gate split, a digest join, an open incident and a cleared one", () => {
36
+ const d = buildRecordDelivery(golden.sources, golden.entries, options);
37
+ const [p, q] = d.projects;
38
+ expect(p!.lead_time).toEqual({ changes: 2, median_seconds: 4500, before_gate_seconds: 3300, at_gate_seconds: 900, after_gate_seconds: 300 });
39
+ expect(q!.lead_time.changes).toBe(2);
40
+ expect(q!.restore).toMatchObject({ open: 2, drift_restored: 1 });
41
+ expect(d.schema).toBe("terragucci.dora/v1");
42
+ expect(d).not.toHaveProperty("source");
43
+ });
44
+
45
+ test("the stage names are the product's: other names read no plan and no drift", () => {
46
+ const other = buildRecordDelivery(golden.sources, golden.entries, { ...options, stages: { plan: "pulumi-preview", drift: "pulumi-drift" } });
47
+ expect(other.estate.lead_time.changes).toBe(0);
48
+ expect(other.estate.restore.drift_restored).toBe(0);
49
+ });
50
+
51
+ test("the ledger's file still says where it came from", () => {
52
+ const d = buildDelivery({ members: [], waves: [], gates: [], approved: [], drift: [], prEnvs: [] } as never, { now: new Date(golden.now) });
53
+ expect(d.source).toBe("ledger");
54
+ });
55
+ });
package/src/ci-estate.ts CHANGED
@@ -28,6 +28,7 @@ import type { ReportPut } from "./pr-report-url";
28
28
  import { sendOtlpGauges, type OtlpGaugesSent } from "./otlp-metrics";
29
29
  import type { OtlpFetch } from "./otlp";
30
30
  import { buildDelivery, deliveryGauges, type Dora } from "./ci-estate/delivery";
31
+ import { NEXT_RELEASE } from "./release-floors";
31
32
  import { ledgerOverdue, type DriftSchedule, type LedgerOverdue } from "./ci-estate/overdue";
32
33
  import { buildEstate, ESTATE_FILES, renderEstateHtml, type Estate, type EstateSections } from "./ci-estate/page";
33
34
  import { estateRows, type EstateRowOptions, type EstateRows, type EstateTables } from "./ci-estate/rows";
@@ -35,10 +36,15 @@ import { estateRows, type EstateRowOptions, type EstateRows, type EstateTables }
35
36
  /** The first chant with `@intentius/chant/ci-estate` (#4612). */
36
37
  export const CI_ESTATE_FLOOR = "0.124.55";
37
38
 
39
+ /** The first chant with `buildRecordDelivery`: delivery metrics from a product's report index and audit trail (#4612). Products feature-detect on it. */
40
+ export const CI_ESTATE_RECORDS_FLOOR = NEXT_RELEASE;
41
+
38
42
  export { estateRows, type ApprovedApply, type DriftRun, type EstateRowOptions, type EstateRows, type EstateTables, type GateLine, type PrEnvLine, type WaveJob } from "./ci-estate/rows";
39
43
  export {
40
44
  appliesOf,
41
45
  buildDelivery,
46
+ buildRecordDelivery,
47
+ recordDriftIncidents,
42
48
  deliveryGauges,
43
49
  doraMetricNames,
44
50
  doraSchema,
@@ -51,8 +57,12 @@ export {
51
57
  DORA_MIN_SPAN_SECONDS,
52
58
  DORA_WEEKS,
53
59
  DRIFT_WINDOW_SECONDS,
60
+ type DeliveryAuditEntry,
54
61
  type DeliveryGauge,
62
+ type DeliveryIndexRow,
55
63
  type DeliveryOptions,
64
+ type DeliveryRecordSource,
65
+ type RecordDeliveryOptions,
56
66
  type Dora,
57
67
  type DoraLeadTime,
58
68
  type DoraMetrics,
@@ -34,9 +34,9 @@ export const CI_PRODUCT_STAGES: readonly CiProductStage[] = ["plan", "apply", "r
34
34
  * answers it. `action` (#4653) asks for a day-2 action on one member, which
35
35
  * runs under a gated request.
36
36
  */
37
- export type CiProductCommand = "plan" | "apply" | "lock" | "unlock" | "agent" | "action";
37
+ export type CiProductCommand = "plan" | "apply" | "lock" | "unlock" | "agent" | "action" | "commit";
38
38
 
39
- export const CI_PRODUCT_COMMANDS: readonly CiProductCommand[] = ["plan", "apply", "lock", "unlock", "agent", "action"];
39
+ export const CI_PRODUCT_COMMANDS: readonly CiProductCommand[] = ["plan", "apply", "lock", "unlock", "agent", "action", "commit"];
40
40
 
41
41
  /**
42
42
  * What an approval of a product's waves binds to (ruling B, 2026-10-27).
@@ -464,6 +464,8 @@ export type ParsedProductComment =
464
464
  * The engine's lexicon checks the action against the member's plan.
465
465
  */
466
466
  | { kind: "action"; member: string; address: string }
467
+ /** A commit job's command (#4722), by the word typed: `/terragucci fmt`. Several words may each map onto `commit`. */
468
+ | { kind: "commit"; word: string }
467
469
  | { kind: "refused"; reason: string };
468
470
 
469
471
  /** A member as a comment may name it: path segments, no leading dash, no shell or glob syntax. */
@@ -539,6 +541,8 @@ export function parseProductComment(words: CiProductWords, body: unknown, env: R
539
541
  case "lock":
540
542
  case "unlock":
541
543
  return parts.length === 2 ? { kind: command } : { kind: "refused", reason: `${line} takes nothing after it` };
544
+ case "commit":
545
+ return parts.length === 2 ? { kind: "commit", word: typed } : { kind: "refused", reason: `${line} takes nothing after it` };
542
546
  case "agent": {
543
547
  const ask = text.slice(`${prefix} ${typed}`.length).trim();
544
548
  if (ask === "") return { kind: "refused", reason: `${line} needs an ask after it, on the same line` };
package/src/ci-product.ts CHANGED
@@ -79,6 +79,7 @@ export const PR_PREVIEW_FLOOR = "0.124.55";
79
79
  export {
80
80
  decideRelayClick,
81
81
  handleRelayRequest,
82
+ NOTIFY_RELAY_POINTS_FLOOR,
82
83
  relayPrincipalFor,
83
84
  RELAY_ENV,
84
85
  slackRelayClick,
@@ -24,7 +24,7 @@ import { approverOf, humanQuorumSince, tallyGateApprovals } from "../../op/gate"
24
24
  import { quorumRuleLine, quorumRules, trustQuorumJudge, UNPROVEN_JUDGE, type GateQuorumJudge } from "../../op/gate-quorum";
25
25
  import { FAN_OUT_GATE_OP, OVERRIDE_GATE_OP, RELEASE_GATE_OP, WORKSPACE_EXIT_GATE_OP, WORKSPACE_PROMOTE_GATE_OP, WORKSPACE_UPGRADE_GATE_OP } from "../../op/gate-name";
26
26
  import { PR_GATE_OP } from "../../pr-loop";
27
- import { pushLifecycleReport, requireLifecycleLedger } from "../../lifecycle/git";
27
+ import { LifecyclePushLostError, pushLifecycleRebasing, requireLifecycleLedger } from "../../lifecycle/git";
28
28
  import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../../lifecycle/local-note";
29
29
  import { ledgerRecordingOff, NO_RECORD_ENV } from "../../lifecycle/no-record";
30
30
  import { checkGateSignature, gateSealPayload, gateSealVersion, WEBAUTHN_SEAL_KIND, type SealedGateApproval } from "../../lifecycle/gate-seal";
@@ -74,7 +74,11 @@ const LIFECYCLE_BRANCH = "chant/lifecycle";
74
74
  * elsewhere to tell, so that case is a quiet suffix and no warning (#3677).
75
75
  */
76
76
  async function reportedPush(consequence: string): Promise<{ pushed: boolean; suffix: string }> {
77
- const { pushed, pushWarning } = await pushLifecycleReport();
77
+ // #4637: a push another writer beat is replayed onto the remote's tip and tried again; an approval line appends.
78
+ const { pushed, pushWarning } = await pushLifecycleRebasing().catch((err: unknown) => {
79
+ if (err instanceof LifecyclePushLostError) return { pushed: false, pushWarning: err.message };
80
+ throw err;
81
+ });
78
82
  if (pushed) return { pushed, suffix: "" };
79
83
  if (isLifecycleLocalNote(pushWarning)) return { pushed, suffix: ` (${LIFECYCLE_LOCAL_NOTE})` };
80
84
  console.error(formatWarning({
@@ -0,0 +1,155 @@
1
+ /**
2
+ * `chant commit prepare|run|land` (#4722): the three steps of the commit jobs
3
+ * the Op generator writes for a scheduled Op spec's `commit`
4
+ * (../../ci-commit.ts says what each does and which token each holds).
5
+ *
6
+ * ```
7
+ * chant commit prepare --forge <kind> [--output <dir>] the commit job, read token: decide
8
+ * chant commit run --forge <kind> [--output <dir>] the commit job, no forge token: run the command
9
+ * chant commit land --forge <kind> [--output <dir>] the push job, push token: commit, push, reply, record
10
+ * ```
11
+ *
12
+ * The settings come from the job's `CHANT_COMMIT_*` variables, which the
13
+ * generator wrote into the workflow file of the base branch.
14
+ */
15
+
16
+ import { execFileSync } from "node:child_process";
17
+ import { readFileSync, writeFileSync } from "node:fs";
18
+ import { tmpdir } from "node:os";
19
+ import { join, resolve } from "node:path";
20
+ import { AgentError, type AgentGit } from "../../ci-agent";
21
+ import {
22
+ COMMIT_DIR,
23
+ commitSettingsFromEnv,
24
+ landCommitChange,
25
+ prepareCommitRun,
26
+ runCommit,
27
+ runCommitArgv,
28
+ type HeadApproval,
29
+ COMMIT_PUSHED_FILE,
30
+ } from "../../ci-commit";
31
+ import { activeProductWords, type CiProductWords } from "../../ci-product-words";
32
+ import { CHANT_EXIT } from "../../exit-codes";
33
+ import { appendRunRecord, readRunLedger } from "../../lifecycle/run-ledger";
34
+ import { listFilesInDir, pushLifecycleRebasing, readBlobFromPath, type LedgerLocation } from "../../lifecycle/git";
35
+ import { parseGateLedger } from "../../lifecycle/gate-ledger";
36
+ import { resolveCiRun } from "../../lifecycle/release-ledger";
37
+ import { FORGE_KINDS, forgeFromEnv, type ForgeKind, type PrForge } from "../../pr-forge";
38
+ import { pullRequestBaseFromEnv } from "../../pr-forge-base";
39
+ import { formatError, formatInfo } from "../format";
40
+ import type { CommandContext } from "../registry";
41
+
42
+ const USAGE = "chant commit prepare|run|land --forge github|gitlab|forgejo [--output <dir>]";
43
+
44
+ function fail(message: string): number {
45
+ console.error(formatError({ message, hint: USAGE }));
46
+ return CHANT_EXIT.failed;
47
+ }
48
+
49
+ /** git with hooks and fsmonitor off: nothing here runs code from the repository. */
50
+ const git: AgentGit = (args, opts = {}) =>
51
+ execFileSync("git", ["-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false", ...args], {
52
+ cwd: opts.cwd,
53
+ input: opts.input,
54
+ encoding: "utf8",
55
+ stdio: ["pipe", "pipe", "pipe"],
56
+ env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
57
+ maxBuffer: 64 << 20,
58
+ });
59
+
60
+ function eventOf(): unknown {
61
+ const file = process.env.GITHUB_EVENT_PATH;
62
+ if (!file) return undefined;
63
+ try {
64
+ return JSON.parse(readFileSync(file, "utf8"));
65
+ } catch {
66
+ return undefined;
67
+ }
68
+ }
69
+
70
+ function workDir(name: string): string {
71
+ return join(process.env.RUNNER_TEMP || process.env.TMPDIR || tmpdir(), name);
72
+ }
73
+
74
+ /**
75
+ * Who approved the plan of pull request `pr` at `sha`, read from the gate
76
+ * ledger: a resolution of the pull request's gates (`pr-<n>`, `pr-<n>-<member>`)
77
+ * or the waves' op, made for that commit. Undefined when there is none.
78
+ */
79
+ export function ledgerHeadApproval(words: CiProductWords, location?: LedgerLocation): HeadApproval {
80
+ return async (pr, sha) => {
81
+ const own = new RegExp(`^pr-${pr}(-[a-z0-9][a-z0-9-]*)?\\.jsonl$`);
82
+ const files = (await listFilesInDir("_gates", location)).filter((f) => own.test(f) || (words.op !== undefined && f === `${words.op}.jsonl`));
83
+ for (const f of files) {
84
+ const text = await readBlobFromPath("_gates", f, location);
85
+ if (!text) continue;
86
+ const hit = parseGateLedger(text).resolutions.find((r) => r.gitSha === sha);
87
+ if (hit) return hit.resolvedBy;
88
+ }
89
+ return undefined;
90
+ };
91
+ }
92
+
93
+ export async function runCommitCommandLine(ctx: CommandContext): Promise<number> {
94
+ const action = ctx.args.path;
95
+ if (action !== "prepare" && action !== "run" && action !== "land") return fail(action ? `commit ${action} is not one of prepare, run or land` : "commit needs an action: prepare, run or land");
96
+ const kind = ctx.args.forge;
97
+ if (!kind || !(FORGE_KINDS as readonly string[]).includes(kind)) return fail(`--forge is one of ${FORGE_KINDS.join(", ")}`);
98
+ const words = activeProductWords();
99
+ const dir = resolve(ctx.args.output ?? COMMIT_DIR);
100
+ let settings;
101
+ try {
102
+ settings = commitSettingsFromEnv(process.env, words.product);
103
+ } catch (e) {
104
+ return fail((e as Error).message);
105
+ }
106
+ const readRuns = async () => (await readRunLedger(settings.env, settings.name)).records;
107
+ const forge = (): PrForge => forgeFromEnv(kind as ForgeKind);
108
+ const approval = ledgerHeadApproval(words);
109
+
110
+ try {
111
+ if (action === "prepare") {
112
+ const base = kind !== "gitlab" ? pullRequestBaseFromEnv(kind as ForgeKind) : undefined;
113
+ const d = await prepareCommitRun({ settings, words, dir, env: process.env, event: eventOf(), ...(kind !== "gitlab" ? { forge: forge() } : {}), ...(base ? { pullRequestBase: base } : {}), readRuns, approval, git, now: new Date() });
114
+ console.error(formatInfo(d.go ? `${settings.name}: runs on ${d.sha?.slice(0, 12)} for #${d.pr}` : `${settings.name}: does not run: ${d.reason}`));
115
+ return CHANT_EXIT.done;
116
+ }
117
+ if (action === "run") {
118
+ const r = await runCommit({ settings, dir, checkout: process.cwd(), workDir: workDir("chant-commit-work"), env: process.env, git, runCommand: runCommitArgv });
119
+ console.error(formatInfo(`${settings.name}: exited ${r.rc}${r.changed ? ", with a change" : ", changing nothing"}`));
120
+ // The push job says why on the pull request; this job stays green so it runs.
121
+ return CHANT_EXIT.done;
122
+ }
123
+ const ci = resolveCiRun(process.env);
124
+ const landBase = pullRequestBaseFromEnv(kind as ForgeKind);
125
+ const out = await landCommitChange({
126
+ ...(landBase ? { pullRequestBase: landBase } : {}),
127
+ settings,
128
+ words,
129
+ dir,
130
+ workDir: workDir("chant-commit-land"),
131
+ env: process.env,
132
+ event: eventOf(),
133
+ forge: forge(),
134
+ git,
135
+ push: ({ cwd, ref }) => {
136
+ git(["push", "-q", "origin", `HEAD:${ref}`], { cwd });
137
+ },
138
+ readRuns,
139
+ approval,
140
+ record: async (input) => {
141
+ await appendRunRecord(input);
142
+ await pushLifecycleRebasing();
143
+ },
144
+ now: () => new Date(),
145
+ ...(ci ? { runOrigin: ci.runOrigin } : {}),
146
+ });
147
+ // #4749: what was pushed, for the push job's `after` lines.
148
+ if (out.result === "pushed" && out.commit) writeFileSync(join(dir, COMMIT_PUSHED_FILE), `${out.commit}\n`);
149
+ console.error(formatInfo(`${settings.name}: ${out.result}: ${out.reason}`));
150
+ return out.code;
151
+ } catch (e) {
152
+ if (e instanceof AgentError) return fail(e.message);
153
+ return fail(`commit ${action}: ${(e as Error).message}`);
154
+ }
155
+ }
@@ -15,7 +15,8 @@
15
15
  *
16
16
  * Each click fetches `chant/lifecycle`, reads the signers file at base, and
17
17
  * records through `recordGateApproval`, one click at a time, so two clicks
18
- * never race on the ledger.
18
+ * never race on the ledger. A gate that asks a decision point gets its
19
+ * question answered through `answerPoint` instead (#4611).
19
20
  */
20
21
  import { activeProductWords } from "../../ci-product-words";
21
22
  import { CHANT_EXIT } from "../../exit-codes";
@@ -79,10 +80,28 @@ export function checkoutRelayDeps(cwd: string, principal: string): RelayDeps {
79
80
  const digestAsked = p.planDigest ?? p.changeSet;
80
81
  if (!digestAsked) continue;
81
82
  const fact = latestPendingGate((await readGateLedger(p.op, { cwd })).pending.filter((f) => f.environment === p.environment), p.gate);
82
- out.push({ op: p.op, gate: p.gate, digest: digestAsked, ...(p.environment !== undefined ? { environment: p.environment } : {}), ...(fact?.request ? { request: fact.request } : {}) });
83
+ const q = fact?.answer;
84
+ out.push({
85
+ op: p.op,
86
+ gate: p.gate,
87
+ digest: digestAsked,
88
+ ...(p.environment !== undefined ? { environment: p.environment } : {}),
89
+ ...(fact?.request ? { request: fact.request } : {}),
90
+ ...(q ? { question: { point: q.point, id: q.id, ...(q.pass ? { pass: q.pass } : {}) } } : {}),
91
+ });
83
92
  }
84
93
  return out;
85
94
  }),
95
+ answer: (input) =>
96
+ one(async () => {
97
+ const { answerPoint } = await import("../../workspace/decide");
98
+ const doc = await answerPoint({ cwd, id: input.id, answer: input.answer, by: [input.by], relayedBy: input.relayedBy });
99
+ if ("error" in doc) return { ok: false as const, error: `${doc.error.code}: ${doc.error.message}` };
100
+ if (doc.question.state !== "answered") return { ok: false as const, error: `the question is ${doc.question.state}: ${input.by}'s answer does not settle it on its own` };
101
+ const { pushLifecycleRebasing } = await import("../../lifecycle/git");
102
+ await pushLifecycleRebasing({ cwd }).catch(() => undefined);
103
+ return { ok: true as const };
104
+ }),
86
105
  approve: (input) =>
87
106
  one(async () => {
88
107
  const { recordGateApproval } = await import("./approve");
@@ -64,6 +64,8 @@ vi.mock("../../lifecycle/git", async () => {
64
64
  return {
65
65
  ...actual,
66
66
  pushLifecycleReport: (...args: unknown[]) => pushLifecycleMock(...args),
67
+ // #4637: chant approve pushes through the rebasing push.
68
+ pushLifecycleRebasing: (...args: unknown[]) => pushLifecycleMock(...args),
67
69
  // Mocked, not merely defaulted: the real one shells to `git fetch`, and
68
70
  // these tests run in the chant checkout itself (#2303).
69
71
  requireLifecycleLedger: (...args: unknown[]) => requireLifecycleLedgerMock(...args),
@@ -0,0 +1,32 @@
1
+ /**
2
+ * #4574: pr-apply's lines for a waiting component wave or round name one
3
+ * approve line per component under a product's words, as the note does
4
+ * (#4601). chant's own line is what it was.
5
+ */
6
+ import { afterEach, describe, expect, test } from "vitest";
7
+ import { assertProductWords, setActiveProductWords } from "../../ci-product-words";
8
+ import { waveApproveLines } from "./pr";
9
+
10
+ const digest = `sha256:${"d".repeat(64)}`;
11
+
12
+ afterEach(() => {
13
+ setActiveProductWords(undefined);
14
+ });
15
+
16
+ describe("waveApproveLines (#4574)", () => {
17
+ test("chant's words: one line, no target", () => {
18
+ expect(waveApproveLines("chant-pr", "dev", { gate: "wave-1", digest, components: ["a", "b"] })).toBe(`chant approve chant-pr wave-1 --plan ${digest} --approver <you> --sign`);
19
+ });
20
+
21
+ test("a product's {target}: one line per component, else the environment", () => {
22
+ setActiveProductWords(assertProductWords({ product: "yodel", approve: "yodel approve {target} --plan {digest}" }));
23
+ expect(waveApproveLines("op", "dev", { gate: "wave-1", digest, components: ["app"] })).toBe(`yodel approve app --plan ${digest}`);
24
+ expect(waveApproveLines("op", "dev", { gate: "wave-1", digest, components: ["a", "b"] })).toBe(`yodel approve a --plan ${digest}; yodel approve b --plan ${digest}`);
25
+ expect(waveApproveLines("op", "dev", { gate: "wave-1", digest, components: [] })).toBe(`yodel approve dev --plan ${digest}`);
26
+ });
27
+
28
+ test("a product's template with no {target}: one line", () => {
29
+ setActiveProductWords(assertProductWords({ product: "plywood", approve: "plywood approve {gate} --plan {digest} {sign}" }));
30
+ expect(waveApproveLines("op", "dev", { gate: "wave-1", digest, components: ["a", "b"] })).toBe(`plywood approve wave-1 --plan ${digest} --sign`);
31
+ });
32
+ });