@intentius/chant 0.124.59 → 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 (82) 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/components/capability.d.ts +11 -0
  8. package/dist/components/capability.d.ts.map +1 -1
  9. package/dist/lifecycle/wave-plans.d.ts +19 -0
  10. package/dist/lifecycle/wave-plans.d.ts.map +1 -1
  11. package/dist/lifecycle/wave-plans.js +25 -1
  12. package/dist/notify.d.ts +24 -2
  13. package/dist/notify.d.ts.map +1 -1
  14. package/dist/notify.js +16 -2
  15. package/dist/notify.schema.json +17 -1
  16. package/dist/op/gate-review.d.ts +1 -1
  17. package/dist/op/gate-review.d.ts.map +1 -1
  18. package/dist/op/index.d.ts +1 -0
  19. package/dist/op/index.d.ts.map +1 -1
  20. package/dist/op/index.js +1 -0
  21. package/dist/op/op-waves-capability.d.ts +2 -0
  22. package/dist/op/op-waves-capability.d.ts.map +1 -1
  23. package/dist/op/op-waves-capability.js +1 -0
  24. package/dist/op/op-waves-preview.d.ts +45 -0
  25. package/dist/op/op-waves-preview.d.ts.map +1 -0
  26. package/dist/op/op-waves-preview.js +37 -0
  27. package/dist/op/op-waves-run.d.ts +18 -0
  28. package/dist/op/op-waves-run.d.ts.map +1 -1
  29. package/dist/op/op-waves-run.js +40 -8
  30. package/dist/release-floors.d.ts +1 -1
  31. package/dist/release-floors.js +1 -1
  32. package/dist/wave-runtime.mjs +311 -310
  33. package/dist/workspace/ci-builds.d.ts +16 -4
  34. package/dist/workspace/ci-builds.d.ts.map +1 -1
  35. package/dist/workspace/ci-builds.js +10 -7
  36. package/dist/workspace/ci-green-cli.d.ts +12 -0
  37. package/dist/workspace/ci-green-cli.d.ts.map +1 -1
  38. package/dist/workspace/ci-green-cli.js +80 -6
  39. package/dist/workspace/ci-green-workflow.d.ts +11 -0
  40. package/dist/workspace/ci-green-workflow.d.ts.map +1 -1
  41. package/dist/workspace/ci-green-workflow.js +63 -1
  42. package/dist/workspace/ci-green.d.ts +130 -6
  43. package/dist/workspace/ci-green.d.ts.map +1 -1
  44. package/dist/workspace/ci-green.js +251 -24
  45. package/dist/workspace/declaration.d.ts +37 -0
  46. package/dist/workspace/declaration.d.ts.map +1 -1
  47. package/dist/workspace/declaration.js +29 -1
  48. package/dist/workspace/declaration.schema.json +44 -0
  49. package/dist/workspace/trust/ci-tag-statement.d.ts +1 -0
  50. package/dist/workspace/trust/ci-tag-statement.d.ts.map +1 -1
  51. package/dist/workspace/trust/ci-tag-statement.js +5 -1
  52. package/package.json +1 -1
  53. package/src/cli/main.ts +16 -2
  54. package/src/cli/parse-args.ts +9 -0
  55. package/src/cli/registry.ts +6 -0
  56. package/src/components/capability.ts +11 -0
  57. package/src/lifecycle/ledger-readers.test.ts +10 -0
  58. package/src/lifecycle/wave-plans.ts +41 -1
  59. package/src/notify.schema.json +17 -1
  60. package/src/notify.ts +30 -2
  61. package/src/op/gate-review.test.ts +1 -1
  62. package/src/op/gate-review.ts +1 -1
  63. package/src/op/index.ts +1 -0
  64. package/src/op/op-waves-capability.ts +3 -0
  65. package/src/op/op-waves-preview.test.ts +122 -5
  66. package/src/op/op-waves-preview.ts +70 -0
  67. package/src/op/op-waves-run.ts +58 -8
  68. package/src/op/op-waves.test.ts +11 -1
  69. package/src/release-floors.ts +1 -1
  70. package/src/workspace/ci-builds.ts +16 -7
  71. package/src/workspace/ci-green-builds.test.ts +83 -1
  72. package/src/workspace/ci-green-cli.ts +80 -6
  73. package/src/workspace/ci-green-lanes.test.ts +121 -0
  74. package/src/workspace/ci-green-merge-queue.test.ts +66 -0
  75. package/src/workspace/ci-green-notify.test.ts +166 -0
  76. package/src/workspace/ci-green-signed.test.ts +20 -0
  77. package/src/workspace/ci-green-workflow.test.ts +47 -1
  78. package/src/workspace/ci-green-workflow.ts +62 -1
  79. package/src/workspace/ci-green.ts +290 -26
  80. package/src/workspace/declaration.schema.json +44 -0
  81. package/src/workspace/declaration.ts +64 -2
  82. package/src/workspace/trust/ci-tag-statement.ts +5 -2
@@ -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",
@@ -18,6 +18,7 @@
18
18
 
19
19
  import { RETENTION_KINDS, type RetentionOverride } from "../lifecycle/retention-policy";
20
20
  import { parseReportUrl } from "../pr-report-url";
21
+ import { notifyConfigProblem, type NotifyConfig } from "../notify";
21
22
  import schema from "./declaration.schema.json" with { type: "json" };
22
23
  import { routeConflicts } from "./ci-branches";
23
24
  import { cloudIdentityProblems, IDENTITY_CLOUDS, type CloudIdentityDeclaration } from "../ci-identity";
@@ -274,9 +275,54 @@ export interface CiGreen {
274
275
  * a runner key.
275
276
  */
276
277
  source: CiSource;
278
+ /**
279
+ * Green lanes (#4662): named subsets of the phases, each with its own
280
+ * tags, so a deployable that needs only some phases is green without the
281
+ * rest. Absent when the declaration names none.
282
+ */
283
+ lanes?: CiLane[];
284
+ /**
285
+ * Who the tick tells (#4645): `ci.red`, `ci.culprit` and `ci.green`, sent
286
+ * through notify as Op waves send theirs. Absent when the declaration sets none.
287
+ */
288
+ notify?: NotifyConfig;
289
+ /**
290
+ * The branch takes changes through GitHub's merge queue (#4644): `ci
291
+ * workflow` adds the `merge_group` trigger to the workflows holding a
292
+ * phase that sets `build`, and writes `chant-merge-queue.yml`, whose
293
+ * `chant-verdict` job the queue's ruleset requires. Absent when unset.
294
+ */
295
+ mergeQueue?: true;
296
+ pointer: string;
297
+ }
298
+
299
+ /**
300
+ * One green lane (#4662): a commit that passes the lane's phases gets
301
+ * `ci/green-<name>/<sha>`, and one that later fails them `ci/revoked-<name>/<sha>`,
302
+ * judged from the same runs as `require`.
303
+ */
304
+ export interface CiLane {
305
+ name: string;
306
+ /** The phases the lane needs, by name, in file order. Each is a declared phase. */
307
+ require: string[];
277
308
  pointer: string;
278
309
  }
279
310
 
311
+ /** A lane's tag prefixes (#4662): `ci/green-<lane>/` and `ci/revoked-<lane>/`. */
312
+ export function laneTagPrefixes(lane: string): { green: string; revoked: string } {
313
+ return { green: `ci/green-${lane}/`, revoked: `ci/revoked-${lane}/` };
314
+ }
315
+
316
+ /** The lane `name` of `green`, or a `declaration-invalid` error naming the lanes it declares. */
317
+ export function laneOf(green: CiGreen, name: string): CiLane {
318
+ const lane = green.lanes?.find((l) => l.name === name);
319
+ if (!lane) {
320
+ const declared = (green.lanes ?? []).map((l) => l.name);
321
+ throw new WorkspaceReadError("declaration-invalid", `ci.green declares no lane ${JSON.stringify(name)}${declared.length > 0 ? `; it declares ${declared.join(", ")}` : "; it declares none (ci.green.lanes)"}`);
322
+ }
323
+ return lane;
324
+ }
325
+
280
326
  /** Where `ci tick` reads phase results (#4044): forge check runs, or chant Op runs. */
281
327
  export type CiSource = "checks" | "runs";
282
328
 
@@ -1366,7 +1412,7 @@ function cloudIdentityOf(raw: CloudIdentityDeclaration, at: (pointer: string, ke
1366
1412
 
1367
1413
  function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocation): CiDeclaration | null {
1368
1414
  if (raw === undefined) return null;
1369
- const block = raw as { reportUrl?: string; workflow?: CiWorkflow; hooks?: unknown; identity?: { cloud?: CloudIdentityDeclaration }; branches?: Record<string, string[]>; labels?: Record<string, string[]>; locks?: CiLocks; lockGrain?: CiLockGrain; policy?: unknown; prEnvironment?: { template: string; ttl?: string; teardown?: { name?: string; command: string[]; lexicons?: string[] } }; green?: { branch: string | string[]; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped; build?: CiBuild }>; require: string[]; preMerge?: string[]; signedSince?: string; source?: CiSource } };
1415
+ const block = raw as { reportUrl?: string; workflow?: CiWorkflow; hooks?: unknown; identity?: { cloud?: CloudIdentityDeclaration }; branches?: Record<string, string[]>; labels?: Record<string, string[]>; locks?: CiLocks; lockGrain?: CiLockGrain; policy?: unknown; prEnvironment?: { template: string; ttl?: string; teardown?: { name?: string; command: string[]; lexicons?: string[] } }; green?: { branch: string | string[]; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped; build?: CiBuild }>; require: string[]; preMerge?: string[]; signedSince?: string; source?: CiSource; lanes?: Record<string, { require: string[] }>; notify?: NotifyConfig; mergeQueue?: boolean } };
1370
1416
  const hooks = ciHooksOf(block.hooks, "/ci/hooks", at);
1371
1417
  const policy = ciPolicyOf(block.policy, at);
1372
1418
  const workflow = {
@@ -1428,8 +1474,24 @@ function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocatio
1428
1474
  at(`/ci/green/preMerge/${i}`),
1429
1475
  );
1430
1476
  }
1477
+ const lanes: CiLane[] = Object.entries(g.lanes ?? {}).map(([name, l]) => {
1478
+ const pointer = `/ci/green/lanes/${pointerToken(name)}`;
1479
+ for (const [i, phase] of l.require.entries()) {
1480
+ if (phases.some((p) => p.name === phase)) continue;
1481
+ throw new WorkspaceReadError(
1482
+ "declaration-invalid",
1483
+ `ci.green.lanes.${name}.require names the phase ${JSON.stringify(phase)}, which ci.green.phases does not declare; declared phases: ${phases.map((p) => p.name).join(", ")}`,
1484
+ at(`${pointer}/require/${i}`),
1485
+ );
1486
+ }
1487
+ return { name, require: [...l.require], pointer };
1488
+ });
1489
+ if (g.notify !== undefined) {
1490
+ const problem = notifyConfigProblem(g.notify, "ci.green.notify");
1491
+ if (problem) throw new WorkspaceReadError("declaration-invalid", problem, at("/ci/green/notify"));
1492
+ }
1431
1493
  const judged = Array.isArray(g.branch) ? g.branch : [g.branch];
1432
- return { green: { branch: judged[0]!, ...(judged.length > 1 ? { branches: [...judged] } : {}), window: g.window ?? DEFAULT_CI_WINDOW, phases, require: [...g.require], ...(g.preMerge !== undefined ? { preMerge: [...g.preMerge] } : {}), signedSince: g.signedSince ?? null, source: g.source ?? "checks", pointer: "/ci/green" }, ...workflow, reportUrl };
1494
+ return { green: { branch: judged[0]!, ...(judged.length > 1 ? { branches: [...judged] } : {}), window: g.window ?? DEFAULT_CI_WINDOW, phases, require: [...g.require], ...(g.preMerge !== undefined ? { preMerge: [...g.preMerge] } : {}), signedSince: g.signedSince ?? null, source: g.source ?? "checks", ...(lanes.length > 0 ? { lanes } : {}), ...(g.notify !== undefined ? { notify: { ...g.notify, ...(g.notify.events ? { events: [...g.notify.events] } : {}) } } : {}), ...(g.mergeQueue === true ? { mergeQueue: true as const } : {}), pointer: "/ci/green" }, ...workflow, reportUrl };
1433
1495
  }
1434
1496
 
1435
1497
  function agentsOf(raw: unknown, members: Member[], at: (pointer: string, key?: boolean) => ErrorLocation): AgentDeclaration[] {
@@ -113,11 +113,11 @@ const normalise = (name: string): string => name.normalize("NFKC").trim().toLowe
113
113
  */
114
114
  export function verifyCiTagStatement(
115
115
  record: Record<string, unknown> | null,
116
- expect: { sha: string; kind: "green" | "revoked"; branch: string },
116
+ expect: { sha: string; kind: "green" | "revoked"; branch: string; lane?: string },
117
117
  runners: readonly RunnerKey[],
118
118
  roles: Readonly<Record<string, readonly string[]>>,
119
119
  ): CiTagVerdict {
120
- const tag = `ci/${expect.kind}/${expect.sha}`;
120
+ const tag = `ci/${expect.kind}${expect.lane !== undefined ? `-${expect.lane}` : ""}/${expect.sha}`;
121
121
  if (record === null) return { status: "unsigned", reason: `${tag} has no JSON record in its annotation, so it carries no statement (a lightweight tag, or one made by hand)` };
122
122
  const { statement: envelope, ...fields } = record;
123
123
  if (envelope === undefined) return { status: "unsigned", reason: `${tag} carries no statement signed by a runner key` };
@@ -145,6 +145,9 @@ export function verifyCiTagStatement(
145
145
  if (p.record.commit !== expect.sha) differs.push(`its record names commit ${p.record.commit.slice(0, 12)}`);
146
146
  if (p.record.tag !== expect.kind) differs.push(`it signs a ${p.record.tag} tag`);
147
147
  if (p.record.branch !== expect.branch) differs.push(`it is for branch ${p.record.branch}, and ci.green names ${expect.branch}`);
148
+ // #4662: a lane's statement says its lane, so it never counts as ci/green or as another lane's tag.
149
+ const signedLane = typeof (p.record as { lane?: unknown }).lane === "string" ? ((p.record as { lane?: string }).lane as string) : undefined;
150
+ if (signedLane !== expect.lane) differs.push(signedLane === undefined ? `it signs a ci/${p.record.tag} tag, not lane ${expect.lane}'s` : `it signs lane ${signedLane}'s tag${expect.lane !== undefined ? `, not lane ${expect.lane}'s` : ", not ci/" + p.record.tag}`);
148
151
  if (canonicalJson(p.record) !== canonicalJson(fields)) differs.push("the annotation's record is not the one signed");
149
152
  if (differs.length > 0) return { status: "mismatch", reason: `${tag} is signed by ${v.principal}, but the statement does not match the tag: ${differs.join("; ")}` };
150
153
  return { status: "signed", signer: v.principal, keyid: v.keyid, reason: `signed by ${v.principal} (${CI_TAG_SIGNER_ROLE})` };