@intentius/chant 0.124.26 → 0.124.28

package/src/workspace/identity.ts

@@ -26,7 +26,7 @@
  */
 
 import type { Declaration, SignedGate } from "./declaration";
-import { admitApprover } from "./identity-gate-rule";
+import { admitApprover, RELEASE_GATE, type GateAdmissionRule } from "./identity-gate-rule";
 import { classesOf, coreClassRegistry, roleGrants, type ClassRegistry } from "./principal-classes";
 import type { ReasonCode } from "./reason-codes";
 import { normalisePrincipal } from "./records";
@@ -165,6 +165,19 @@ export function gateAdmissionFrom(source: GateRuleSource, gate: string): GateAdm
   return { requirement, refuses: (a) => admitApprover(rule, a) };
 }
 
+/**
+ * The rule a release cut is judged by (#4031): the declaration's
+ * `identity.gates.release` entry with its class, read at base, or, when the
+ * declaration names no `release` gate, a rule with no class, which checks a
+ * cut's signature alone. `requirement` is null in that case, and a cut may
+ * then be made unsigned.
+ */
+export function releaseRuleFrom(source: GateRuleSource): { requirement: SignedGate | null; rule: GateAdmissionRule } {
+  const requirement = source.declaration?.identity?.gates[RELEASE_GATE] ?? null;
+  const { policy, classes } = source;
+  return { requirement, rule: { gate: RELEASE_GATE, class: requirement?.class ?? null, signers: policy, roles: roleGrants(policy), classes: classes.all() } };
+}
+
 /**
  * The rule for `gate` in the workspace holding `cwd`, read at base (the
  * target branch tip), or null when there is no declaration or it names none.

package/src/workspace/intent.ts

@@ -772,9 +772,56 @@ export function windowOpening(top: string, rev: string, view: Pick<RecordView, "
   return view.decidedIn?.sha ?? addingCommit(top, rev, view.path);
 }
 
-/** `commit` and every commit between it and `rev` that has it as an ancestor. */
+/** A full commit id, as git prints it: lowercase hex, sha1 or sha256. */
+const FULL_COMMIT_ID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+
+/**
+ * The children of every commit `rev` reaches, from one `git rev-list
+ * --parents` walk (#4032). Kept in memory for the last repository and commit
+ * read, since a walk asks for the windows of many records at one revision. A
+ * commit id names the same history for good, so the entry never goes stale.
+ */
+let childIndex: { key: string; children: Map<string, string[]> } | undefined;
+
+function childrenWithin(top: string, rev: string): Map<string, string[]> | undefined {
+  const key = `${top}\0${rev}`;
+  if (childIndex?.key === key) return childIndex.children;
+  const text = tryGit(top, ["rev-list", "--parents", rev]);
+  if (text === undefined) return undefined;
+  const children = new Map<string, string[]>();
+  for (const row of text.split("\n")) {
+    const [commit, ...parents] = row.trim().split(" ");
+    if (!commit) continue;
+    for (const p of parents) {
+      const list = children.get(p);
+      if (list) list.push(commit);
+      else children.set(p, [commit]);
+    }
+  }
+  childIndex = { key, children };
+  return children;
+}
+
+/**
+ * `commit` and every commit between it and `rev` that has it as an ancestor:
+ * what `git rev-list --ancestry-path <commit>..<rev>` lists, plus `commit`.
+ * With full commit ids it is read from the children of what `rev` reaches,
+ * walked once per revision, instead of one `git rev-list` per record (#4032).
+ */
 export function descendants(top: string, commit: string, rev: string): Set<string> {
   const out = new Set<string>([commit]);
+  const children = FULL_COMMIT_ID.test(commit) && FULL_COMMIT_ID.test(rev) ? childrenWithin(top, rev) : undefined;
+  if (children) {
+    const stack = [commit];
+    while (stack.length > 0) {
+      for (const c of children.get(stack.pop()!) ?? []) {
+        if (out.has(c)) continue;
+        out.add(c);
+        stack.push(c);
+      }
+    }
+    return out;
+  }
   const text = tryGit(top, ["rev-list", "--ancestry-path", `${commit}..${rev}`]);
   for (const line of (text ?? "").split("\n")) if (line.trim()) out.add(line.trim());
   return out;

package/src/workspace/ls.schema.json

@@ -25,7 +25,9 @@
             }
           }
         },
-        "require": { "type": "array", "items": { "type": "string" } }
+        "require": { "type": "array", "items": { "type": "string" } },
+        "signedSince": { "type": "string", "description": "Added in contract 1 by #4031, written by chant 0.124.28 and newer, and only when the declaration sets it: the full sha of the first commit whose ci tags count only with a statement signed by a runner key. Tags on its strict first-parent ancestors count unsigned." },
+        "source": { "const": "runs", "description": "Added in contract 1 by #4044, written by chant 0.124.28 and newer, and only when the declaration sets ci.green.source to runs: ci tick reads each phase's results from chant's own Op runs on chant/lifecycle, each signed by a runner key, in place of the forge's check runs. Absent means check runs." }
       }
     },
     "result": {

package/src/workspace/ls.ts

@@ -144,6 +144,10 @@ export interface LsCiGreen {
   window: string;
   phases: { name: string; runs: string[]; skipped: "pass" | "fail" }[];
   require: string[];
+  /** The first commit whose ci tags need a signed statement (#4031). Present only when the declaration sets it. */
+  signedSince?: string;
+  /** Where the tick reads phase results (#4044). Present only when it is `runs`; absent means the forge's check runs. */
+  source?: "runs";
 }
 
 export interface LsGroup {
@@ -322,6 +326,8 @@ function readListing(query: LsQuery): { doc: LsDocument; declaration?: Declarati
                   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,
+                  ...(declaration.ci.green.signedSince !== null ? { signedSince: declaration.ci.green.signedSince } : {}),
+                  ...(declaration.ci.green.source === "runs" ? { source: "runs" as const } : {}),
                 }
               : null,
           }

package/src/workspace/member-pipeline.test.ts

@@ -95,6 +95,23 @@ describe("the component pipeline's file and command", () => {
     expect(plan.command).toBe("chant build --components --generate github --env staging --pr-loop --gate infra-apply --branch trunk");
   });
 
+  test("the recorded command keeps --image and each --before-script, in order (#4002)", () => {
+    const dir = join(repo, "services/api");
+    const plan = planMemberComponentPipeline({
+      projectDir: dir,
+      found: findWorkspaceRoot(dir)!,
+      lexicon: "forgejo",
+      env: "staging",
+      output: join(dir, "pr.yml"),
+      prLoop: {},
+      image: "node:22-bookworm",
+      beforeScript: ["npm ci", 'echo "$PWD/node_modules/.bin" >> "$GITHUB_PATH"'],
+    })!;
+    expect(plan.command).toBe(
+      `chant build --components --generate forgejo --env staging --pr-loop --image node:22-bookworm --before-script 'npm ci' --before-script 'echo "$PWD/node_modules/.bin" >> "$GITHUB_PATH"' --output pr.yml`,
+    );
+  });
+
   test("the recorded command keeps --wave-gate, --canary and --base (#3049)", () => {
     const dir = join(repo, "services/api");
     const plan = planMemberComponentPipeline({

package/src/workspace/member-pipeline.ts

@@ -205,6 +205,8 @@ export interface ComponentPlanInput {
   /** `--env`, or undefined for the generator's default. */
   env?: string;
   promoteTo?: string;
+  /** `--allow-skip` (#4030): the generated promote job may skip a step of the promotion order. */
+  allowSkip?: boolean;
   /** `--output`, relative to the current directory. */
   output?: string;
   params?: string[];
@@ -213,6 +215,10 @@ export interface ComponentPlanInput {
   prLoop?: { gate?: string; branch?: string };
   /** `--wave-gate` with its `--canary` and `--base` (#3049). */
   waveGate?: { gate: string; canary?: string[]; base?: string };
+  /** `--image` (#4002). */
+  image?: string;
+  /** `--before-script`, in order (#4002). */
+  beforeScript?: string[];
 }
 
 /** The generators' own default environment when `--env` is not given. */
@@ -242,6 +248,7 @@ export function planMemberComponentPipeline(input: ComponentPlanInput): MemberCo
 
   const parts = ["chant", "build", "--components", "--generate", input.lexicon, "--env", env];
   if (input.promoteTo) parts.push("--promote-to", input.promoteTo);
+  if (input.promoteTo && input.allowSkip) parts.push("--allow-skip");
   if (input.waveGate) {
     parts.push("--wave-gate", input.waveGate.gate);
     if (input.waveGate.canary?.length) parts.push("--canary", input.waveGate.canary.join(","));
@@ -252,6 +259,8 @@ export function planMemberComponentPipeline(input: ComponentPlanInput): MemberCo
     if (input.prLoop.gate) parts.push("--gate", input.prLoop.gate);
     if (input.prLoop.branch) parts.push("--branch", input.prLoop.branch);
   }
+  if (input.image) parts.push("--image", input.image);
+  for (const line of input.beforeScript ?? []) parts.push("--before-script", line);
   for (const p of input.params ?? []) parts.push("--param", p);
   if (input.paramsFile) parts.push("--params-file", relPath(ctx.memberRoot, resolve(input.paramsFile)));
   if (input.output) parts.push("--output", relPath(ctx.memberRoot, target));

package/src/workspace/promotion-order.ts

@@ -0,0 +1,97 @@
+/**
+ * A member's promotion order (#4030): the literal entries of the `environments`
+ * array in its `chant.config.ts`, in the order written. A release moves from
+ * each environment to the next, so `chant components promote --to <env>` can
+ * default `--from` to the step before, and `chant workspace status --json`
+ * lists the order for a reader such as behold's lane.
+ *
+ * A pattern entry such as `pr-*` names no environment, so it is not a step.
+ * A component's own `environments` (`component.schema.json`) say where its
+ * release is hosted in each environment and never set the order.
+ *
+ * `canary` marks a step as the canary step. It is declared and surfaced only:
+ * no chant command acts on it yet.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { environmentName, isEnvironmentPattern, type EnvironmentDeclaration } from "../config";
+
+/** One step of a member's promotion order. */
+export interface PromotionStep {
+  name: string;
+  /** True when the entry sets `canary: true`. */
+  canary: boolean;
+}
+
+/** The member's promotion order from its config's `environments`; `[]` when it declares none. A repeated name keeps its first place. */
+export function promotionOrder(declared: readonly EnvironmentDeclaration[] | null | undefined): PromotionStep[] {
+  const out: PromotionStep[] = [];
+  for (const entry of declared ?? []) {
+    const name = environmentName(entry);
+    if (isEnvironmentPattern(name) || out.some((s) => s.name === name)) continue;
+    out.push({ name, canary: typeof entry !== "string" && entry.canary === true });
+  }
+  return out;
+}
+
+const STRING = String.raw`(?:"[^"\\\n\[\]{}]*"|'[^'\\\n\[\]{}]*')`;
+const PROP = String.raw`(?:(?:name|endpoint)\s*:\s*${STRING}|canary\s*:\s*(?:true|false))`;
+const ENTRY = String.raw`(?:${STRING}|\{\s*(?:${PROP}\s*,?\s*)*\})`;
+const ARRAY = new RegExp(String.raw`^\[\s*(?:${ENTRY}\s*,?\s*)*\]$`);
+
+/**
+ * The promotion order a `chant.config.ts` writes as literals, read from its
+ * text without running it, or `undefined` when the text is not that simple.
+ * Evaluating a TypeScript config loads tsx, and `workspace status` reads every
+ * member without that cost (#3976), so the plain cases are read here and the
+ * rest fall back to loading the config. The plain cases are a config with no
+ * `environments` and no spread, and one whose only `environments` is an array
+ * of string entries and `{ name, endpoint, canary }` entries with literal values.
+ */
+export function staticPromotionOrder(source: string): PromotionStep[] | undefined {
+  const text = source.replace(/("(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'|`(?:[^`\\]|\\.)*`)|\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, "$1");
+  const mentions = text.match(/\benvironments\b/g)?.length ?? 0;
+  if (mentions === 0) return /export\s+default\s*\{/.test(text) && !text.includes("...") ? [] : undefined;
+  if (mentions > 1 || text.includes("...")) return undefined;
+  const start = text.match(/\benvironments\s*:\s*(\[)/);
+  if (!start || start.index === undefined) return undefined;
+  const open = start.index + start[0].length - 1;
+  const close = text.indexOf("]", open);
+  if (close < 0) return undefined;
+  const array = text.slice(open, close + 1);
+  if (!ARRAY.test(array)) return undefined;
+  const entries: EnvironmentDeclaration[] = [];
+  for (const m of array.matchAll(new RegExp(`${STRING}|\\{[^}]*\\}`, "g"))) {
+    const raw = m[0];
+    if (raw.startsWith("{")) {
+      const name = raw.match(/\bname\s*:\s*(?:"([^"]*)"|'([^']*)')/);
+      if (!name) return undefined;
+      entries.push({ name: name[1] ?? name[2], canary: /\bcanary\s*:\s*true\b/.test(raw) });
+    } else {
+      entries.push(raw.slice(1, -1));
+    }
+  }
+  return promotionOrder(entries);
+}
+
+/**
+ * One member's promotion order from its directory's config: `[]` when it has
+ * none or declares no environments, and null when the config can't be read.
+ * A TypeScript config is read as text when it is plain ({@link staticPromotionOrder}),
+ * and loaded otherwise.
+ */
+export async function readMemberPromotionOrder(dir: string): Promise<PromotionStep[] | null> {
+  try {
+    const ts = join(dir, "chant.config.ts");
+    if (existsSync(ts)) {
+      const plain = staticPromotionOrder(readFileSync(ts, "utf-8"));
+      if (plain) return plain;
+    }
+    const { loadChantConfig } = await import("../config");
+    const { config } = await loadChantConfig(dir);
+    return promotionOrder(config.environments);
+  } catch {
+    return null;
+  }
+}

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

@@ -22,6 +22,7 @@ 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 ciListSchema from "./ci-list.schema.json";
 import { workspaceComposites } from "./composites";
 import compositesSchema from "./composites.schema.json";
 import { workspaceGraph } from "./graph-cli";
@@ -43,13 +44,15 @@ import { queryRecordsSince } from "./records-since";
 import recordsSinceSchema from "./records-since.schema.json";
 import { workspacePoints } from "./points-cli";
 import pointsSchema from "./points.schema.json";
+import releasesSchema from "./releases.schema.json";
+import changeSetShowSchema from "./change-set-show.schema.json";
 import { workspaceStatus } from "./status";
 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, "ci-last-green": ciLastGreenSchema };
+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, "ci-list": ciListSchema, releases: releasesSchema, "change-set-show": changeSetShowSchema };
 
 /** 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

@@ -9,7 +9,7 @@ import { readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { describe, expect, test } from "vitest";
 import { REPO } from "./__fixtures__/contract-repo";
-import { CHANGES_ERROR_CODES, CHANGES_FINDING_CODES } from "./changes";
+import { CHANGES_ERROR_CODES, CHANGES_FINDING_CODES, COMMIT_LINK_FINDING_CODES } from "./changes";
 import { MEMBER_RUN_REASON_CODES } from "./compose-graph";
 import { COMPOSITES_ENVIRONMENT_REASON_CODES, COMPOSITES_ERROR_CODES, COMPOSITES_REASON_CODES, COMPOSITES_RUNTIME_REASON_CODES } from "./composites";
 import { WORKSPACE_ERROR_CODES } from "./declaration";
@@ -85,6 +85,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   INTENT_REASON_CODES,
   INTENT_WHY_CODES,
   CHANGES_FINDING_CODES,
+  COMMIT_LINK_FINDING_CODES,
   CHANGES_ERROR_CODES,
   COMPOSITES_ERROR_CODES,
   COMPOSITES_REASON_CODES,

package/src/workspace/reason-codes.ts

@@ -205,6 +205,9 @@ export const REASONS = {
   // The forward coverage check (check --changes, #2773): findings, one per changed path.
   "change-uncovered": "A path the diff changes is covered by no current decided record and no open work item, by path or by its member.",
   "change-out-of-scope": "A record in hand for the change, such as the work item it is for or a decision that item implements, lists a path the diff changes in its out_of_scope.",
+  // The commit link check (check --changes, #4029): findings, one per trunk commit.
+  "commit-unlinked": "A trunk commit in the range names no work item: it has no Chant-Record trailer of a work kind and no Chant-Lease trailer.",
+  "commit-wrongly-linked": "A trunk commit in the range names a work item that is not there: a Chant-Record whose id no work kind has or whose kind is not a work kind, a malformed Chant-Record, or a Chant-Lease that resolves to no work item, and no other trailer links it.",
   // The patch read (workspace patch): a read that fails.
   "patch-path-invalid": "workspace patch --path names a path that is not relative and inside the workspace.",
   // Composite instances joined to components (graph --composites, #2662): why the list is empty or has no component.
@@ -283,7 +286,7 @@ 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.
+  // Which commits passed CI (ci last-green, ci list 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.