@intentius/chant 0.124.32 → 0.124.34

package/src/workspace/declaration.ts

@@ -23,6 +23,7 @@ import { expandGlob } from "./glob";
 import { EXAMPLES_KIND, holdsChantProject } from "./kinds";
 import { parseJsonText, pointerToken, type TextLocation } from "./jsonc";
 import type { ReasonCode } from "./reason-codes";
+import type { SecurityGroup } from "./security";
 import { joinPath, type WorkspaceTree } from "./tree";
 import { loadAjv2020 } from "./ajv2020";
 import { readChantPackageVersion } from "../package-version";
@@ -184,6 +185,13 @@ export interface AgentDeclaration {
 /** What a check run that finished as skipped counts as in a CI phase (#3573). */
 export type CiSkipped = "pass" | "fail";
 
+/**
+ * Which commits a phase runs on (#4169): `every` first-parent commit of the
+ * branch, or only the `newest` one when a runner frees, the commits between
+ * left unbuilt and a red one bisected.
+ */
+export type CiBuild = "every" | "newest";
+
 /** One phase of `ci.green`: the check runs that make it up (#3573, ws-103). */
 export interface CiPhase {
   name: string;
@@ -191,6 +199,12 @@ export interface CiPhase {
   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;
+  /**
+   * Which commits the phase runs on (#4169), when the declaration says.
+   * Absent means `every`, and `ci workflow` then leaves the phase's
+   * workflows as they are.
+   */
+  build?: CiBuild;
   pointer: string;
 }
 
@@ -207,6 +221,12 @@ export interface CiGreen {
   phases: CiPhase[];
   /** The phases a commit must pass, by name, in file order. */
   require: string[];
+  /**
+   * The phases that must pass before the branch moves (#4168 4.4), by name,
+   * in file order: the quick checks a pull request, a merge queue or a local
+   * run gives before a change lands. Absent or empty when the declaration names none.
+   */
+  preMerge?: string[];
   /**
    * The full sha of the first commit on the branch whose ci tags need a
    * statement signed by a runner key (#4031). A tag on a strict
@@ -230,9 +250,20 @@ export interface CiGreen {
 /** Where `ci tick` reads phase results (#4044): forge check runs, or chant Op runs. */
 export type CiSource = "checks" | "runs";
 
+/**
+ * A prescribed delivery workflow (#4168 section 7). `trunk-curated`: a merge
+ * records the plan and deploys nothing, and releases are cut from green
+ * commits and promoted through the environments. `trunk-curated+apply-on-merge`
+ * adds the apply on merge as an opt-in. `chant workspace check` reports what a
+ * member under one still lacks (./checks/ci-workflow.ts, WSP151).
+ */
+export type CiWorkflow = "trunk-curated" | "trunk-curated+apply-on-merge";
+
 /** The declaration's `ci` block (#3573). */
 export interface CiDeclaration {
   green: CiGreen | null;
+  /** `ci.workflow` (#4168 step 6): the workflow every member follows unless it names its own; absent when the declaration sets none. */
+  workflow?: CiWorkflow;
   /**
    * `ci.reportUrl` (#4160): where the pull-request jobs copy their reports
    * and `chant ci run` keeps the run index, `<reportUrl>/runs/index.json`.
@@ -557,6 +588,10 @@ export interface Member {
   because: string | null;
   /** Whether `chant workspace export` takes the member (#2552, D10). False when the entry does not say. */
   travel: boolean;
+  /** The security groups this member adds to the declaration's top-level `security` (#4168 step 7), in file order; empty when it names none. */
+  security: SecurityGroup[];
+  /** The member's own `ci.workflow` (#4168 step 6), which wins over the top level's; null when it names none. */
+  ciWorkflow: CiWorkflow | null;
   suppress: Suppression[];
   /** The entry's JSON Pointer in the file, for messages. */
   pointer: string;
@@ -624,6 +659,8 @@ export interface Declaration {
    * then uses 7.
    */
   metrics: { failureWindowDays?: number } | null;
+  /** The security groups the workspace opts into (#4168 section 8, ./security.ts), in file order; empty when the declaration has no `security` key. */
+  security: SecurityGroup[];
   /** The file, relative to the workspace root's tree (`chant.workspace.json` or `.jsonc`). */
   file: string;
 }
@@ -850,6 +887,8 @@ export function parseDeclaration(text: string, file: string, reader: string = re
       upstream: (e.upstream as string | undefined) ?? null,
       because: (e.because as string | undefined) ?? null,
       travel: e.travel === true,
+      security: [...((e.security as SecurityGroup[] | undefined) ?? [])],
+      ciWorkflow: ((e.ci as { workflow?: CiWorkflow } | undefined)?.workflow) ?? null,
       suppress,
       pointer,
     };
@@ -1002,6 +1041,7 @@ export function parseDeclaration(text: string, file: string, reader: string = re
     ci,
     retention: retentionOf(obj.retention),
     metrics: metricsOf(obj.metrics),
+    security: [...((obj.security as SecurityGroup[] | undefined) ?? [])],
     file,
   };
   written.set(declaration, raw);
@@ -1096,7 +1136,8 @@ function retentionOf(raw: unknown): RetentionOverride | null {
 
 function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocation): CiDeclaration | null {
   if (raw === undefined) return null;
-  const block = raw as { reportUrl?: string; green?: { branch: string; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped }>; require: string[]; signedSince?: string; source?: CiSource } };
+  const block = raw as { reportUrl?: string; workflow?: CiWorkflow; green?: { branch: string; window?: string; phases: Record<string, string[] | { runs: string[]; skipped?: CiSkipped; build?: CiBuild }>; require: string[]; preMerge?: string[]; signedSince?: string; source?: CiSource } };
+  const workflow = block.workflow !== undefined ? { workflow: block.workflow } : {};
   let reportUrl: string | null = null;
   if (block.reportUrl !== undefined) {
     // #4160: refused here as pr-plan and ci run refuse the flag, so a reader never gets a URL no job can write to.
@@ -1104,12 +1145,13 @@ function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocatio
     if ("error" in target) throw new WorkspaceReadError("declaration-invalid", target.error, at("/ci/reportUrl"));
     reportUrl = target.url;
   }
-  if (block.green === undefined) return { green: null, reportUrl };
+  if (block.green === undefined) return { green: null, ...workflow, reportUrl };
   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"),
+    ...(!Array.isArray(p) && p.build !== undefined ? { build: p.build } : {}),
     pointer: `/ci/green/phases/${pointerToken(name)}`,
   }));
   for (const [i, name] of g.require.entries()) {
@@ -1120,7 +1162,15 @@ function ciOf(raw: unknown, at: (pointer: string, key?: boolean) => ErrorLocatio
       at(`/ci/green/require/${i}`),
     );
   }
-  return { green: { branch: g.branch, window: g.window ?? DEFAULT_CI_WINDOW, phases, require: [...g.require], signedSince: g.signedSince ?? null, source: g.source ?? "checks", pointer: "/ci/green" }, reportUrl };
+  for (const [i, name] of (g.preMerge ?? []).entries()) {
+    if (phases.some((p) => p.name === name)) continue;
+    throw new WorkspaceReadError(
+      "declaration-invalid",
+      `ci.green.preMerge names the phase ${JSON.stringify(name)}, which ci.green.phases does not declare; declared phases: ${phases.map((p) => p.name).join(", ")}`,
+      at(`/ci/green/preMerge/${i}`),
+    );
+  }
+  return { green: { branch: g.branch, 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 };
 }
 
 function agentsOf(raw: unknown, members: Member[], at: (pointer: string, key?: boolean) => ErrorLocation): AgentDeclaration[] {

package/src/workspace/init.ts

@@ -559,7 +559,7 @@ export async function runWorkspaceInit(ctx: CommandContext): Promise<number> {
     console.error(
       formatError({
         message: `${join(root, existing[0])} already exists`,
-        hint: "Edit it by hand, or run chant workspace ls to see what it declares.",
+        hint: "Edit it by hand, or run chant workspace ls to see what it declares. To set it up for a delivery workflow, run chant ci init --workflow trunk-curated.",
       }),
     );
     return 1;
@@ -612,7 +612,7 @@ export async function runWorkspaceInit(ctx: CommandContext): Promise<number> {
     return 0;
   }
   writeFileSync(target, text, { flag: "wx" });
-  console.log(formatSuccess(`Wrote ${target}. chant workspace ls lists what it declares.`));
+  console.log(formatSuccess(`Wrote ${target}. chant workspace ls lists what it declares, and chant ci init --workflow trunk-curated sets up merging and releases.`));
   return 0;
 }
 

package/src/workspace/ls.schema.json

@@ -21,7 +21,8 @@
             "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." }
+              "skipped": { "enum": ["pass", "fail"], "description": "What a run that finished as skipped counts as." },
+              "build": { "enum": ["every", "newest"], "description": "Added in contract 1 by #4169, written by chant 0.124.33 and newer, and only when the declaration sets it: whether the phase runs on every first-parent commit or only the newest one when a runner frees. Absent means every." }
             }
           }
         },

package/src/workspace/ls.ts

@@ -142,7 +142,8 @@ export interface LsDiagram {
 export interface LsCiGreen {
   branch: string;
   window: string;
-  phases: { name: string; runs: string[]; skipped: "pass" | "fail" }[];
+  /** `build` is present only when the declaration sets it (#4169). */
+  phases: { name: string; runs: string[]; skipped: "pass" | "fail"; build?: "every" | "newest" }[];
   require: string[];
   /** The first commit whose ci tags need a signed statement (#4031). Present only when the declaration sets it. */
   signedSince?: string;
@@ -328,7 +329,7 @@ function readListing(query: LsQuery): { doc: LsDocument; declaration?: Declarati
               ? {
                   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 })),
+                  phases: declaration.ci.green.phases.map((p) => ({ name: p.name, runs: p.runs, skipped: p.skipped, ...(p.build ? { build: p.build } : {}) })),
                   require: declaration.ci.green.require,
                   ...(declaration.ci.green.signedSince !== null ? { signedSince: declaration.ci.green.signedSince } : {}),
                   ...(declaration.ci.green.source === "runs" ? { source: "runs" as const } : {}),

package/src/workspace/member-pipeline.ts

@@ -212,7 +212,7 @@ export interface ComponentPlanInput {
   params?: string[];
   paramsFile?: string;
   /** `--pr-loop`, with its `--gate` and `--branch` (#3465). */
-  prLoop?: { gate?: string; branch?: string };
+  prLoop?: { gate?: string; branch?: string; applyOnMerge?: boolean };
   /** `--wave-gate` with its `--canary` and `--base` (#3049). */
   waveGate?: { gate: string; canary?: string[]; base?: string };
   /** `--image` (#4002). */
@@ -258,6 +258,7 @@ export function planMemberComponentPipeline(input: ComponentPlanInput): MemberCo
     parts.push("--pr-loop");
     if (input.prLoop.gate) parts.push("--gate", input.prLoop.gate);
     if (input.prLoop.branch) parts.push("--branch", input.prLoop.branch);
+    if (input.prLoop.applyOnMerge) parts.push("--apply-on-merge");
   }
   if (input.image) parts.push("--image", input.image);
   for (const line of input.beforeScript ?? []) parts.push("--before-script", line);

package/src/workspace/merge-record.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/merge-record/v1/merge-record.schema.json",
+  "title": "chant merge record",
+  "description": "What landed on the target branch, keyed by commit: _merges/<commit>.json on chant/lifecycle (#4168, chant 0.124.33 and newer). The record job writes it on merge. It applies nothing; a release that carries the commit deploys it.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["$schema", "contract", "commit", "base", "env", "source", "op", "gate", "digest", "plan", "approvedBy", "components", "recordedAt"],
+  "properties": {
+    "$schema": { "const": "https://intentius.io/chant/schemas/workspace/merge-record/v1/merge-record.schema.json" },
+    "contract": { "const": 1 },
+    "commit": { "type": "string", "pattern": "^[0-9a-f]{40,64}$", "description": "The merged commit." },
+    "base": { "type": "string", "pattern": "^[0-9a-f]{40,64}$", "description": "The commit the change is measured from." },
+    "env": { "type": "string", "minLength": 1 },
+    "member": { "type": "string", "minLength": 1, "description": "The workspace member whose pipeline wrote it." },
+    "source": {
+      "description": "Where the change came from: the pull request that merged it, else the work items its Chant-Record: work:<id> trailers name, else a direct push.",
+      "oneOf": [
+        { "type": "object", "additionalProperties": false, "required": ["kind", "pr"], "properties": { "kind": { "const": "pull-request" }, "pr": { "type": "integer", "minimum": 1 } } },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "records"],
+          "properties": {
+            "kind": { "const": "work-item" },
+            "records": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "type": "object", "additionalProperties": false, "required": ["kind", "id"], "properties": { "kind": { "const": "work" }, "id": { "type": "string", "minLength": 1 } } }
+            }
+          }
+        },
+        { "type": "object", "additionalProperties": false, "required": ["kind"], "properties": { "kind": { "const": "direct-push" } } }
+      ]
+    },
+    "op": { "type": ["string", "null"], "description": "The pull request's gate op, pr-<n> or pr-<n>-<member>; null without a pull request." },
+    "gate": { "type": "string", "minLength": 1 },
+    "digest": { "type": ["string", "null"], "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$", "description": "The change-set digest planned on the merged commit; null when nothing was planned. The change set is stored under _change-sets/." },
+    "plan": {
+      "enum": ["approved", "changed", "unapproved", "nothing", "plan-failed"],
+      "description": "approved: an approval stands for digest. changed: one stands for approvedDigest, so the plan moved after review; the record job's chant/record status fails. unapproved: none stands. nothing: no component deploys what the change touches. plan-failed: a member failed to plan."
+    },
+    "approvedDigest": { "type": "string", "pattern": "^(?:jcs1-)?sha256:[0-9a-f]{64}$" },
+    "approvedBy": { "type": "array", "items": { "type": "string" } },
+    "authorApproved": { "type": "array", "items": { "type": "string" }, "description": "Approvers who wrote the change (#4000), read with a forge." },
+    "components": { "type": "array", "items": { "type": "string" } },
+    "recordedAt": { "type": "string", "minLength": 1, "description": "ISO 8601." }
+  }
+}

package/src/workspace/pr-report.schema.json

@@ -8,7 +8,7 @@
   "properties": {
     "$schema": { "const": "https://intentius.io/chant/schemas/workspace/pr-report/v1/pr-report.schema.json" },
     "contract": { "const": 1 },
-    "stage": { "enum": ["plan", "apply"] },
+    "stage": { "enum": ["plan", "apply", "record"], "description": "plan: on the pull request. record (#4168, chant 0.124.33 and newer): on merge, the default; it plans the merged commit and writes the merge record, applying nothing. apply: on merge with --apply-on-merge." },
     "pr": {
       "type": ["integer", "null"],
       "minimum": 1,
@@ -33,8 +33,8 @@
       "description": "The change-set digest of what this stage planned: computePlanDigest(\"change-set\", ...) over every member's { member, planDigest }. What the gate binds."
     },
     "status": {
-      "enum": ["planned", "plan-failed", "nothing", "applied", "failed", "wave-applied", "refused", "waiting"],
-      "description": "planned: every member planned (plan stage). plan-failed: a member failed to plan, so nothing can apply. nothing: no component deploys what the change touches. applied: every member applied. failed: a member failed to apply and its dependents did not run. wave-applied (#4003, chant 0.124.32 and newer): with --wave-gate and --wave, the wave applied and a later wave is still to run. refused: nothing applied, see refusal. waiting (#3999): the approved plans applied except members held back after an upstream applied, which wait on an approval of the plan the last of rounds made."
+      "enum": ["planned", "recorded", "plan-failed", "nothing", "applied", "failed", "wave-applied", "refused", "waiting"],
+      "description": "planned: every member planned (plan stage). recorded (#4168, chant 0.124.33 and newer): every member planned on the merged commit and the merge record was written (record stage); approval says whether the plan is the approved one, and nothing applied. plan-failed: a member failed to plan, so nothing can apply. nothing: no component deploys what the change touches. applied: every member applied. failed: a member failed to apply and its dependents did not run. wave-applied (#4003, chant 0.124.32 and newer): with --wave-gate and --wave, the wave applied and a later wave is still to run. refused: nothing applied, see refusal. waiting (#3999): the approved plans applied except members held back after an upstream applied, which wait on an approval of the plan the last of rounds made."
     },
     "refusal": {
       "enum": ["not-approved", "plan-changed", "not-a-reviewer", "author-approved", "no-pull-request", "wave-not-approved", "wave-plan-changed", "earlier-wave"],

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

@@ -28,6 +28,8 @@ import { STATUS_ERROR_CODES, STATUS_GATE_REASON_CODES, STATUS_REASON_CODES, STAT
 import { WORK_WARNING_CODES } from "./work";
 import { BOX_FINDING_CODES } from "./checks/boxes";
 import { DIAGRAM_FINDING_CODES } from "./checks/diagrams";
+import { SECURITY_FINDING_CODES } from "./checks/security";
+import { CI_WORKFLOW_FINDING_CODES } from "./ci-workflow";
 import { WORK_ERROR_CODES, WORK_HISTORY_ERROR_CODES, WORK_LEASE_REFUSALS } from "./work-cli";
 import { RUN_STATEMENT_ERROR_CODES, RUNS_ERROR_CODES, RUNS_REASON_CODES, RUNS_WRITE_ERROR_CODES } from "./runs-cli";
 import { RUN_STATEMENT_FAILURE_CODES } from "./trust/run-statement";
@@ -66,6 +68,8 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   CHECK_ERROR_CODES,
   BOX_FINDING_CODES,
   DIAGRAM_FINDING_CODES,
+  SECURITY_FINDING_CODES,
+  CI_WORKFLOW_FINDING_CODES,
   STATUS_REASON_CODES,
   STATUS_ERROR_CODES,
   STATUS_GATE_REASON_CODES,

package/src/workspace/reason-codes.ts

@@ -229,6 +229,34 @@ export const REASONS = {
   "diagram-source-missing": "A declared diagram's source file does not exist in the tree read.",
   "diagram-render-missing": "A declared diagram's render file does not exist in the tree read.",
   "diagram-render-drift": "A declared diagram records a sourceHash, and the source's bytes now hash to something else: the render is stale for its source.",
+  // The security group checklists (check, #4168 step 7). Each is also a WSP finding.
+  "security-signers-missing": "The workspace opts into verified-releases, and there is no .chant/allowed_signers to verify a release's signature against.",
+  "security-release-gate-missing": "Under verified-releases, identity.gates has no release entry, or it names no class, so a cut is not held to a class of signers.",
+  "security-publish-allows-unsigned": "Under verified-releases, a pipeline file runs release publish with --allow-unsigned.",
+  "security-sbom-disabled": "Under supply-chain, a member's chant.config.ts sets sbom: false on a publish target.",
+  "security-sbom-unsourced": "Under supply-chain, a member publishes, names no sbom file and has no package-lock.json, pom.xml or Cargo.lock to write one from.",
+  "security-publish-no-provenance": "Under supply-chain, a pipeline file runs release publish without --require-provenance.",
+  "security-component-no-sbom": "Under supply-chain, a member's components have no generate-sbom step.",
+  "security-component-no-verify": "Under supply-chain, a member's components have no verify step.",
+  "security-signed-since-unset": "Under who-ran-it, ci.green sets no signedSince, or there is no ci.green block.",
+  "security-runner-untrusted": "Under who-ran-it, .chant/trust.json lists no runner key.",
+  "security-tick-no-key": "Under who-ran-it, a pipeline file runs ci tick with no runner key.",
+  "security-review-not-required": "Under review-rules, an apply job passes --no-require-review, which the group overrides.",
+  "security-attribution-any": "Under review-rules, identity.attribution is not identified.",
+  "security-gate-unsigned": "Under review-rules, an apply job names a gate identity.gates does not list, or identity.gates lists none.",
+  "security-runner-start-no-key": "Under isolated-runners, .chant/trust.json lists no key under runners for a provisioner to sign runner-start statements with.",
+  "security-runner-start-no-role": "Under isolated-runners, no principal under runners in .chant/trust.json holds the runner role.",
+  "security-trust-unreadable": "Under isolated-runners, .chant/trust.json can't be read, so no runner-start statement can be checked.",
+  // The ci.workflow requirements (check, #4168 step 6). Each is also a WSP151 finding.
+  "ci-workflow-green-undeclared": "Under ci.workflow, the declaration has no ci.green block, so no commit gets a verdict and no release can be cut.",
+  "ci-workflow-no-pre-merge": "Under ci.workflow, ci.green.preMerge names no phase, so nothing says which checks run before the branch moves.",
+  "ci-workflow-apply-in-green": "Under ci.workflow, a phase in ci.green.require matches an apply job, which would wait on its own verdict.",
+  "ci-workflow-no-components": "Under ci.workflow, a member declares no component, so nothing of it can be cut or promoted.",
+  "ci-workflow-no-environments": "Under ci.workflow, a member's chant.config.ts declares no environments, so a release has nowhere to be promoted to.",
+  "ci-workflow-ungated-env": "Under ci.workflow, a component has no gate, so a promote to the last environment waits on no approval.",
+  "ci-workflow-pipeline-missing": "Under ci.workflow, no pipeline file runs the plan job, the merge job or chant ci tick.",
+  "ci-workflow-pipeline-differs": "Under ci.workflow, the merge job does not match the workflow: it applies under trunk-curated, or records under trunk-curated+apply-on-merge.",
+  "ci-workflow-publish-missing": "Under ci.workflow, no pipeline file runs chant release publish.",
   // A box that holds a credential (check, #2726). Each is also a WSP finding.
   "box-credential-declared": "A file in a box member's directory carries a literal secret: a credential's shape, or a literal where a credential goes. A variable or secret-manager reference is not one.",
   "box-capability-unbrokered": "A capability in a member's box block names no broker, so the box would hold its credential.",