@intentius/chant 0.107.1 → 0.108.1

package/src/workspace/declaration.schema.json

@@ -166,6 +166,19 @@
           }
         }
       }
+    },
+    "ci": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^x-": true
+      },
+      "description": "What the workspace's CI decides about its commits (#3573, ws-103). Added in schema 1 by chant 0.108.0, so a declaration that uses it sets minReader to 0.108.0 or newer.",
+      "properties": {
+        "green": {
+          "$ref": "#/$defs/ciGreen"
+        }
+      }
     }
   },
   "patternProperties": {
@@ -1397,6 +1410,95 @@
         "^x-": true
       },
       "additionalProperties": false
+    },
+    "ciGreen": {
+      "type": "object",
+      "description": "Which commits passed CI (#3573, ws-103). chant ci tick tags each first-parent commit of branch, within window, whose required phases all passed with ci/green/<sha>, and a green commit that later fails a required phase with ci/revoked/<sha>. Both are annotated tags made once and never moved or deleted by chant. chant ci last-green prints the newest commit with a green tag and no revoked tag.",
+      "required": [
+        "branch",
+        "phases",
+        "require"
+      ],
+      "properties": {
+        "branch": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[^\\s~^:?*\\[\\\\]+$",
+          "description": "The branch whose commits are tagged, such as main. Only its first-parent commits count."
+        },
+        "window": {
+          "type": "string",
+          "pattern": "^[1-9][0-9]*(m|h|d)$",
+          "description": "How far back a tick looks, by committer time, such as 24h, 90m or 7d. 24h when absent."
+        },
+        "phases": {
+          "type": "object",
+          "minProperties": 1,
+          "description": "The phases, by name. Each is a list of check-run name patterns, or { runs, skipped }. A pattern matches a check run's whole name, with * standing for any run of characters. A phase passes when every check run its patterns match finished with success, judged by each run's latest attempt.",
+          "propertyNames": {
+            "$ref": "#/$defs/ciPhaseName"
+          },
+          "additionalProperties": {
+            "$ref": "#/$defs/ciPhase"
+          }
+        },
+        "require": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "description": "The phases a commit must pass to be tagged green, by name. Each must be a declared phase.",
+          "items": {
+            "$ref": "#/$defs/ciPhaseName"
+          }
+        }
+      },
+      "patternProperties": {
+        "^x-": true
+      },
+      "additionalProperties": false
+    },
+    "ciPhaseName": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$"
+    },
+    "ciPhase": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/ciRunPatterns"
+        },
+        {
+          "type": "object",
+          "required": [
+            "runs"
+          ],
+          "properties": {
+            "runs": {
+              "$ref": "#/$defs/ciRunPatterns"
+            },
+            "skipped": {
+              "enum": [
+                "pass",
+                "fail"
+              ],
+              "description": "What a check run that finished as skipped counts as. fail (the default): it never passes. pass: it passes, for a job a path filter runs only on some commits."
+            }
+          },
+          "patternProperties": {
+            "^x-": true
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+    "ciRunPatterns": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "description": "A check run's name, such as lint, or a pattern with *, such as e2e (*)."
+      }
     }
   }
 }

package/src/workspace/declaration.ts

@@ -180,6 +180,40 @@ export interface AgentDeclaration {
   pointer: string;
 }
 
+/** What a check run that finished as skipped counts as in a CI phase (#3573). */
+export type CiSkipped = "pass" | "fail";
+
+/** One phase of `ci.green`: the check runs that make it up (#3573, ws-103). */
+export interface CiPhase {
+  name: string;
+  /** Check-run name patterns, `*` standing for any run of characters. */
+  runs: string[];
+  /** `fail` (the default): a skipped run never passes. `pass`: it passes, for a job a path filter runs only on some commits. */
+  skipped: CiSkipped;
+  pointer: string;
+}
+
+/** The default `ci.green.window`. */
+export const DEFAULT_CI_WINDOW = "24h";
+
+/** The declaration's `ci.green` block (#3573, ws-103), with its defaults. */
+export interface CiGreen {
+  /** The branch whose first-parent commits are tagged. */
+  branch: string;
+  /** How far back a tick looks, such as `24h`. */
+  window: string;
+  /** The phases, in file order. */
+  phases: CiPhase[];
+  /** The phases a commit must pass, by name, in file order. */
+  require: string[];
+  pointer: string;
+}
+
+/** The declaration's `ci` block (#3573). */
+export interface CiDeclaration {
+  green: CiGreen | null;
+}
+
 export interface MemberRole {
   name: string;
   /** Relative to the member's directory, or null for the whole member. */
@@ -546,6 +580,8 @@ export interface Declaration {
   agents: AgentDeclaration[];
   /** Who a person-attributed write may name, and which gates need a signed approval (#3163), or null when the declaration has no `identity` block. */
   identity: IdentityPolicy | null;
+  /** What the workspace's CI decides about its commits (#3573), or null when the declaration has no `ci` block. */
+  ci: CiDeclaration | null;
   /** The file, relative to the workspace root's tree (`chant.workspace.json` or `.jsonc`). */
   file: string;
 }
@@ -900,6 +936,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
   const agents = agentsOf(obj.agents, members, at);
   const tierSession = factoryTierSessionProblem(members, agents);
   if (tierSession) throw new WorkspaceReadError("declaration-invalid", tierSession.message, at(tierSession.pointer));
+  const ci = ciOf(obj.ci, at);
 
   const pins = ((obj.pins as Record<string, string>[] | undefined) ?? []).map((p) => ({
     package: p.package ?? null,
@@ -925,6 +962,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
     writeScope,
     agents,
     identity: identityOf(obj.identity),
+    ci,
     file,
   };
 }
@@ -973,6 +1011,32 @@ function identityOf(raw: unknown): IdentityPolicy | null {
   return { attribution: block.attribution ?? "any", gates };
 }
 
+/**
+ * The `ci` block, already validated by the schema, with its defaults and the
+ * rule the schema can't say (#3573): every phase `require` names is declared.
+ */
+function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocation): CiDeclaration | null {
+  if (raw === undefined) return null;
+  const block = raw as { green?: { branch: string; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped }>; require: string[] } };
+  if (block.green === undefined) return { green: null };
+  const g = block.green;
+  const phases: CiPhase[] = Object.entries(g.phases).map(([name, p]) => ({
+    name,
+    runs: [...(Array.isArray(p) ? p : p.runs)],
+    skipped: Array.isArray(p) ? "fail" : (p.skipped ?? "fail"),
+    pointer: `/ci/green/phases/${pointerToken(name)}`,
+  }));
+  for (const [i, name] of g.require.entries()) {
+    if (phases.some((p) => p.name === name)) continue;
+    throw new WorkspaceReadError(
+      "declaration-invalid",
+      `ci.green.require names the phase ${JSON.stringify(name)}, which ci.green.phases does not declare; declared phases: ${phases.map((p) => p.name).join(", ")}`,
+      at(`/ci/green/require/${i}`),
+    );
+  }
+  return { green: { branch: g.branch, window: g.window ?? DEFAULT_CI_WINDOW, phases, require: [...g.require], pointer: "/ci/green" } };
+}
+
 function agentsOf(raw: unknown, members: Member[], at: (pointer: string, key?: boolean) => ErrorLocation): AgentDeclaration[] {
   const agents = ((raw as { name: string; member?: string; members?: string[]; principals?: string[] }[] | undefined) ?? []).map((a, i) => {
     // The schema requires exactly one of member and members (ws-101).

package/src/workspace/ls.schema.json

@@ -5,6 +5,29 @@
   "description": "What `chant workspace ls --json` prints, version 1 of the read contract for listing a workspace (#2524 D15, #2534). Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists: a new code is a new contract version. Contract version 1 is written by chant 0.81.0 and newer; a reader that needs it refuses output whose `contract` it doesn't know. Every code is in the one closed list of `reason-codes.ts`.",
   "oneOf": [{ "$ref": "#/$defs/result" }, { "$ref": "#/$defs/failure" }],
   "$defs": {
+    "ciGreen": {
+      "description": "Which commits chant ci tick tags green: the first-parent commits of branch within window whose required phases all passed.",
+      "type": "object",
+      "required": ["branch", "window", "phases", "require"],
+      "properties": {
+        "branch": { "type": "string" },
+        "window": { "type": "string", "description": "Such as 24h, the default." },
+        "phases": {
+          "description": "In file order.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "runs", "skipped"],
+            "properties": {
+              "name": { "type": "string" },
+              "runs": { "type": "array", "items": { "type": "string" }, "description": "Check-run name patterns, * standing for any run of characters." },
+              "skipped": { "enum": ["pass", "fail"], "description": "What a run that finished as skipped counts as." }
+            }
+          }
+        },
+        "require": { "type": "array", "items": { "type": "string" } }
+      }
+    },
     "result": {
       "description": "The declaration was read. Exit code 0, even when some members can't be read.",
       "type": "object",
@@ -66,6 +89,17 @@
           "type": "array",
           "items": { "$ref": "#/$defs/diagram" }
         },
+        "ci": {
+          "description": "Added in contract 1 by #3573 (ws-103), so absent from an older chant's output. The declaration's ci block with its defaults filled in, or null when it has none; green is null when the block declares no green.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["green"],
+              "properties": { "green": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/ciGreen" }] } }
+            }
+          ]
+        },
         "summary": {
           "type": "object",
           "required": ["members", "unreadable", "groups", "matches"],

package/src/workspace/ls.ts

@@ -134,6 +134,14 @@ export interface LsDiagram {
   member: string | null;
 }
 
+/** The declaration's `ci.green` (#3573, ws-103), with its defaults filled in. */
+export interface LsCiGreen {
+  branch: string;
+  window: string;
+  phases: { name: string; runs: string[]; skipped: "pass" | "fail" }[];
+  require: string[];
+}
+
 export interface LsGroup {
   name: string;
   kind: "examples";
@@ -164,6 +172,8 @@ export type LsDocument =
       groups: LsGroup[];
       /** Every declared diagram, the workspace's own first, then each member's, in file order (#2764). */
       diagrams: LsDiagram[];
+      /** What the workspace's CI decides about its commits (#3573), or null with no `ci` block. */
+      ci: { green: LsCiGreen | null } | null;
       summary: { members: number; unreadable: number; groups: number; matches: number };
     }
   | {
@@ -286,6 +296,18 @@ function readListing(query: LsQuery): { doc: LsDocument; declaration?: Declarati
       members,
       groups: lsGroups,
       diagrams,
+      ci: declaration.ci
+        ? {
+            green: declaration.ci.green
+              ? {
+                  branch: declaration.ci.green.branch,
+                  window: declaration.ci.green.window,
+                  phases: declaration.ci.green.phases.map((p) => ({ name: p.name, runs: p.runs, skipped: p.skipped })),
+                  require: declaration.ci.green.require,
+                }
+              : null,
+          }
+        : null,
       summary: {
         members: members.length,
         unreadable: members.filter((m) => !m.readable).length,

package/src/workspace/read-contract.test.ts

@@ -21,6 +21,7 @@ import { pathToFileURL } from "node:url";
 import { describe, expect, test } from "vitest";
 import { contract, git, REPO, validSchema } from "./__fixtures__/contract-repo";
 import checkSchema from "./check.schema.json";
+import ciLastGreenSchema from "./ci-last-green.schema.json";
 import { workspaceComposites } from "./composites";
 import compositesSchema from "./composites.schema.json";
 import { workspaceGraph } from "./graph-cli";
@@ -48,7 +49,7 @@ import statusSchema from "./status.schema.json";
 const FIXTURE = join(REPO, "reference-workspace");
 const TIMEOUT = 240_000;
 
-const SCHEMAS = { ls: lsSchema, graph: graphSchema, check: checkSchema, status: statusSchema, records: recordsSchema, "records-since": recordsSinceSchema, intent: intentSchema, "intent-record": intentRecordSchema, composites: compositesSchema, points: pointsSchema, patch: patchSchema };
+const SCHEMAS = { ls: lsSchema, graph: graphSchema, check: checkSchema, status: statusSchema, records: recordsSchema, "records-since": recordsSinceSchema, intent: intentSchema, "intent-record": intentRecordSchema, composites: compositesSchema, points: pointsSchema, patch: patchSchema, "ci-last-green": ciLastGreenSchema };
 
 /** This checkout's chant, started the way the CLI starts it, for members with no toolchain of their own. */
 const reader: Toolchain = {

package/src/workspace/reason-codes.test.ts

@@ -44,6 +44,7 @@ import { BOX_LISTING_ERROR_CODES } from "./box-listing";
 import { BOX_PUBLISH_ERROR_CODES } from "./box-publish";
 import { WRITE_LOCK_ERROR_CODES } from "./write-lock-cli";
 import { WIP_ERROR_CODES, WIP_WRITE_ERROR_CODES } from "./wip";
+import { CI_GREEN_ERROR_CODES } from "./ci-green";
 import { ROTATION_REFUSAL_CODES } from "./trust/rotation";
 import { SIGNERS_ERROR_CODES } from "./trust/signers-cli";
 import { EVIDENCE_ERROR_CODES } from "./trust/evidence";
@@ -111,6 +112,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   WRITE_LOCK_ERROR_CODES,
   WIP_ERROR_CODES,
   WIP_WRITE_ERROR_CODES,
+  CI_GREEN_ERROR_CODES,
   ROTATION_REFUSAL_CODES,
   SIGNERS_ERROR_CODES,
   EVIDENCE_ERROR_CODES,

package/src/workspace/reason-codes.ts

@@ -275,6 +275,9 @@ export const REASONS = {
   "wip-race": "Another writer moved refs/chant/wip/<branch> between this command's read and its write.",
   "wip-policy-none": "wip push or wip fetch was run, and no box block declares replicate, so there is no remote.",
   "wip-remote-unknown": "The replicate policy names a git remote the checkout does not have; the host adds it, with its credential, before chant pushes.",
+  // Which commits passed CI (ci last-green and ci tick, #3573): why nothing was read.
+  "ci-green-undeclared": "The declaration has no ci.green block, so chant does not know which check runs make a commit green.",
+  "ci-branch-unknown": "The checkout has no ref for the branch ci.green names: neither the remote-tracking branch nor a local one.",
   // A box whose isolation fails (check, #2727). Each is also a WSP finding.
   "box-isolation-collision": "Two boxes on one host resolve to the same port, state path or cookie name, or two ports in one box share an offset.",
   "box-isolation-literal": "A host's stateRoot or a box's state entry is a literal machine path instead of one derived from an environment reference and the box's name.",