@intentius/chant 0.124.33 → 0.124.34

package/src/components/release-gate.ts

@@ -39,6 +39,14 @@
  * planned by that capability, as a pull request's plan is. A plan that
  * returns no change-set part is a hole, since nothing says what it changes.
  *
+ * A dependency the promote also deploys is read from its plan, not from the
+ * estate (#4168 step 4, the rule #3999 gave a pull request): a dependent is
+ * planned against the outputs its upstream's plan says it will expose, and a
+ * reference the plan can't say is listed in `unknownInputs`. Any other
+ * dependency is read as it stands. What each component was planned against is
+ * kept in `reads`, so the promote can hold it back when an upstream applies
+ * as another value (`./promote-rounds.ts`).
+ *
  * Any other component is a `chant` member compared with what the
  * environment runs now: its latest deploy record and the release that record
  * names. The artifact digest, each template the release's target records for
@@ -52,8 +60,8 @@
  * recorded since (#4035): its record names what ran before that run.
  */
 
-import type { CapabilityRegistry } from "./capability";
-import { deployContext, resolveComponentGraph, resolveStepInput, type DriverComponent, type DriverGate, type DriverPhase, type DriverStep } from "./driver";
+import type { CapabilityRegistry, PlannedOutputs } from "./capability";
+import { deployContext, resolveComponentGraph, resolveStepInput, unresolvedWiringReferences, type DriverComponent, type DriverGate, type DriverPhase, type DriverStep } from "./driver";
 import { componentPlanDigest } from "./gate-plan";
 import { gateName, RELEASE_GATE_OP } from "../op/gate-name";
 import { capabilitySteps, planContext, readComponentOutputs } from "./wave-plan";
@@ -123,6 +131,23 @@ export interface ReleaseChangeSetInput {
   seededOutputs?: Record<string, Record<string, unknown>>;
   /** The chant version to record in the document. */
   chant?: string;
+  /**
+   * Plan only these components (a later round or wave, ./promote-rounds.ts).
+   * The others are not planned; a dependency among them is read from
+   * `seededOutputs`, which then holds what the run left. Default: every one.
+   */
+  only?: ReadonlySet<string>;
+}
+
+/** A release's change set for an environment, and what each component was planned against. */
+export interface ReleasePlan {
+  doc: ChangeSetDocument;
+  /** Per planned component, the outputs of its dependencies as its plan read them. */
+  reads: Record<string, Record<string, Record<string, unknown>>>;
+  /** Per dependency read from its plan, the names of the outputs the plan knows, sorted. Absent when none. */
+  plannedOutputs?: Record<string, string[]>;
+  /** Per component, the references to a promoted upstream that no value stands for until it applies, sorted. Absent when none. */
+  unknownInputs?: Record<string, string[]>;
 }
 
 const byString = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
@@ -240,65 +265,105 @@ export function chantComponentPart(input: {
  * that fails to plan: it becomes a failed member.
  */
 export async function planReleaseChangeSet(input: ReleaseChangeSetInput): Promise<ChangeSetDocument> {
+  return (await planReleaseSet(input)).doc;
+}
+
+/**
+ * {@link planReleaseChangeSet}, with what each component read. Components are
+ * planned a wave at a time, so a dependency the promote deploys has planned
+ * before its dependents read its outputs.
+ */
+export async function planReleaseSet(input: ReleaseChangeSetInput): Promise<ReleasePlan> {
   const { release, env, registry } = input;
   const components = [...input.components];
   const byName = new Map(components.map((c) => [c.name, c]));
   const outputs: Record<string, Record<string, unknown>> = { ...(input.seededOutputs ?? {}) };
   const read = new Set(Object.keys(outputs));
   const parts: ChangeSetPart[] = [];
-  const { order } = resolveComponentGraph(components.map((c) => ({ ...c, dependsOn: (c.dependsOn ?? []).filter((d) => byName.has(d)) })));
-  for (const name of order) {
-    const component = byName.get(name)!;
-    const digest = input.digests.get(name) ?? "";
-    const plannable = capabilitySteps(component.deploy).filter((s) => registry.has(s.kind) && registry.resolve(s.kind).plan !== undefined);
-    if (plannable.length === 0) {
-      parts.push(chantComponentPart({ component, release, env, digest, current: input.current.get(name), unsettled: input.unsettled?.get(name) }));
-      continue;
-    }
-    const ctx = deployContext({ env }, name);
-    try {
-      for (const dep of component.dependsOn ?? []) {
-        if (read.has(dep) || !byName.has(dep)) continue;
-        read.add(dep);
-        const found = await readComponentOutputs(byName.get(dep)!, registry, deployContext({ env }, dep), outputs);
-        if (found) outputs[dep] = found;
+  const plannedBy = new Map<string, PlannedOutputs | undefined>();
+  const planned: Record<string, string[]> = {};
+  const unknownInputs: Record<string, string[]> = {};
+  const reads: ReleasePlan["reads"] = {};
+  const inPlan = (name: string): boolean => input.only === undefined || input.only.has(name);
+  const isPlannable = (c: DriverComponent): boolean =>
+    capabilitySteps(c.deploy).some((s) => registry.has(s.kind) && registry.resolve(s.kind).plan !== undefined);
+  const { waves } = resolveComponentGraph(components.map((c) => ({ ...c, dependsOn: (c.dependsOn ?? []).filter((d) => byName.has(d)) })));
+  for (const wave of waves) {
+    const planning = wave.filter(inPlan);
+    for (const name of planning) {
+      const component = byName.get(name)!;
+      const digest = input.digests.get(name) ?? "";
+      const plannable = capabilitySteps(component.deploy).filter((s) => registry.has(s.kind) && registry.resolve(s.kind).plan !== undefined);
+      if (plannable.length === 0) {
+        parts.push(chantComponentPart({ component, release, env, digest, current: input.current.get(name), unsettled: input.unsettled?.get(name) }));
+        continue;
       }
-      for (const step of plannable) {
-        const { kind, ...rest } = step;
-        const planned = await registry.resolve(kind).plan!(planContext(ctx, rest, outputs), resolveStepInput(rest, {}, outputs) as never);
-        parts.push(
-          planned.changeSet ?? {
-            member: {
-              member: planned.member,
-              lexicon: "chant",
-              planner: "chant",
-              status: "planned",
-              planDigest: planned.planDigest,
-              holes: [{ address: planned.member, reason: `its ${kind} plan describes no changes, so what it changes is unknown` }],
+      const ctx = deployContext({ env }, name);
+      try {
+        for (const dep of component.dependsOn ?? []) {
+          if (read.has(dep) || !byName.has(dep)) continue;
+          read.add(dep);
+          // A dependency this promote plans exposes what its plan says (#3999).
+          if (plannedBy.has(dep) && isPlannable(byName.get(dep)!)) {
+            const known = plannedBy.get(dep)?.known ?? {};
+            outputs[dep] = { ...known };
+            planned[dep] = Object.keys(known).sort();
+            continue;
+          }
+          const found = await readComponentOutputs(byName.get(dep)!, registry, deployContext({ env }, dep), outputs);
+          if (found) outputs[dep] = found;
+        }
+        reads[name] = Object.fromEntries((component.dependsOn ?? []).filter((d) => d in outputs).map((d) => [d, structuredClone(outputs[d])]));
+        const unknown = new Set<string>();
+        let exposes: PlannedOutputs | undefined;
+        for (const step of plannable) {
+          const { kind, ...rest } = step;
+          for (const r of unresolvedWiringReferences(rest, outputs)) if (plannedBy.has(r.source) && !r.publish) unknown.add(r.ref);
+          const result = await registry.resolve(kind).plan!(planContext(ctx, rest, outputs), resolveStepInput(rest, {}, outputs) as never);
+          if (result.outputs) exposes = { known: { ...(exposes?.known ?? {}), ...result.outputs.known }, unknown: [...new Set([...(exposes?.unknown ?? []), ...result.outputs.unknown])].sort() };
+          parts.push(
+            result.changeSet ?? {
+              member: {
+                member: result.member,
+                lexicon: "chant",
+                planner: "chant",
+                status: "planned",
+                planDigest: result.planDigest,
+                holes: [{ address: result.member, reason: `its ${kind} plan describes no changes, so what it changes is unknown` }],
+              },
+              entries: [],
             },
-            entries: [],
+          );
+        }
+        plannedBy.set(name, exposes);
+        if (unknown.size > 0) unknownInputs[name] = [...unknown].sort();
+      } catch (err) {
+        plannedBy.set(name, undefined);
+        parts.push({
+          member: {
+            member: name,
+            lexicon: "chant",
+            planner: "chant",
+            status: "failed",
+            error: err instanceof Error ? err.message : String(err),
+            planDigest: null,
+            holes: [],
           },
-        );
+          entries: [],
+        });
       }
-    } catch (err) {
-      parts.push({
-        member: {
-          member: name,
-          lexicon: "chant",
-          planner: "chant",
-          status: "failed",
-          error: err instanceof Error ? err.message : String(err),
-          planDigest: null,
-          holes: [],
-        },
-        entries: [],
-      });
     }
   }
-  return composeChangeSet(parts, {
+  const doc = composeChangeSet(parts, {
     ...(input.chant !== undefined ? { chant: input.chant } : {}),
     planned: { releaseDigest: release.releaseDigest, environment: env },
   });
+  return {
+    doc,
+    reads,
+    ...(Object.keys(planned).length > 0 ? { plannedOutputs: planned } : {}),
+    ...(Object.keys(unknownInputs).length > 0 ? { unknownInputs } : {}),
+  };
 }
 
 /** The members a release gate refuses: provisional ones, which no approval of the document covers (`change-set.mdx`). */

package/src/graph-declared-exports.test.ts

@@ -0,0 +1,40 @@
+import { describe, test, expect, vi } from "vitest";
+
+/**
+ * Side-by-side stacks keep their exports and imports (#4202). The live overlay
+ * builds the declared canvas per stack, and that canvas dropped the member's
+ * exports, so a workspace viewer had nothing to join another member's import
+ * to once an environment was picked.
+ */
+vi.mock("./discovery/index", () => ({ discover: vi.fn(async () => ({ entities: new Map(), errors: [] })) }));
+vi.mock("./graph-ir", () => ({
+  buildGraphIr: vi.fn(() => ({
+    nodes: [
+      { id: "webAlb", kind: "AWS::ElasticLoadBalancingV2::LoadBalancer", lexicon: "aws" },
+      { id: "zoneId", kind: "AWS::CloudFormation::Parameter", lexicon: "aws" },
+    ],
+    edges: [],
+    groups: {},
+    exports: [{ name: "awsEndpoint", node: "webAlb", attr: "DNSName" }],
+    imports: [{ name: "zoneId", node: "zoneId" }],
+  })),
+}));
+
+const { buildDeclaredPerStack } = await import("./graph-declared");
+
+describe("buildDeclaredPerStack keeps exports and imports (#4202)", () => {
+  test("an export's node is qualified like the nodes, and its name is unchanged", async () => {
+    const ir = await buildDeclaredPerStack([{ name: "three-cloud-aws", src: "src" }], "/project");
+    expect(ir.nodes.map((n) => n.id)).toContain("three-cloud-aws::webAlb");
+    expect(ir.exports).toEqual([{ name: "awsEndpoint", node: "three-cloud-aws::webAlb", attr: "DNSName" }]);
+    expect(ir.imports).toEqual([{ name: "zoneId", node: "three-cloud-aws::zoneId" }]);
+    const ids = new Set(ir.nodes.map((n) => n.id));
+    for (const e of ir.exports ?? []) expect(ids.has(e.node!)).toBe(true);
+  });
+
+  test("a stack without src brings no exports", async () => {
+    const ir = await buildDeclaredPerStack([{ name: "unbuilt" }], "/project");
+    expect(ir.exports).toBeUndefined();
+    expect(ir.imports).toBeUndefined();
+  });
+});

package/src/graph-declared.ts

@@ -13,6 +13,10 @@ import { buildGraphIr, type GraphIR, type IRNode } from "./graph-ir";
  * that live side, build each stack's `src` in isolation and qualify its node ids
  * and edge endpoints the same way. Stacks are merged into one graph.
  *
+ * Each stack's exports and imports come along with their `node` qualified the
+ * same way (#4202), so a workspace viewer can still match an import in another
+ * member to an export here once an environment is picked.
+ *
  * A stack without `src` contributes nothing here — it has no declared source to
  * scope to (its live nodes still show as foreign in the overlay).
  */
@@ -22,6 +26,8 @@ export async function buildDeclaredPerStack(
 ): Promise<GraphIR> {
   const nodes: IRNode[] = [];
   const edges: GraphIR["edges"] = [];
+  const exports: NonNullable<GraphIR["exports"]> = [];
+  const imports: NonNullable<GraphIR["imports"]> = [];
   // Which nodes belong to which stack (#1433). This is not derived or guessed:
   // the stack is declared in config and every node here is being renamed with
   // its name on the line below. The membership was always known and thrown
@@ -38,8 +44,10 @@ export async function buildDeclaredPerStack(
       (byStack[st.name] ??= []).push(id);
     }
     for (const e of g.edges) edges.push({ ...e, from: q(e.from), to: q(e.to) });
+    for (const e of g.exports ?? []) exports.push({ ...e, ...(e.node ? { node: q(e.node) } : {}) });
+    for (const i of g.imports ?? []) imports.push({ ...i, node: q(i.node) });
   }
   for (const ids of Object.values(byStack)) ids.sort();
   const groups: GraphIR["groups"] = Object.keys(byStack).length ? { byStack } : {};
-  return { nodes, edges, groups };
+  return { nodes, edges, groups, ...(exports.length ? { exports } : {}), ...(imports.length ? { imports } : {}) };
 }

package/src/workspace/__fixtures__/contract-repo.ts

@@ -27,7 +27,7 @@ export function scratchDir(prefix = "chant-contract-"): string {
 }
 
 export function git(cwd: string, ...args: string[]): string {
-  return execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@example.com", "-c", "commit.gpgsign=false", ...args], {
+  return execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@example.com", "-c", "commit.gpgsign=false", "-c", "gc.auto=0", "-c", "maintenance.auto=false", ...args], {
     cwd,
     encoding: "utf-8",
     stdio: ["ignore", "pipe", "pipe"],
@@ -67,7 +67,16 @@ export function repoFixture(build: () => string, prefix = "chant-contract-copy-"
   return () => {
     if (template === undefined || !existsSync(template)) template = build();
     const root = scratchDir(prefix);
-    cpSync(template, root, { recursive: true });
+    // A commit can leave a detached `git gc --auto` or maintenance run moving
+    // the template's objects, and a copy that meets it fails with ENOENT on
+    // .git/objects. Copy once more after it settles.
+    try {
+      cpSync(template, root, { recursive: true });
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+      rmSync(root, { recursive: true, force: true });
+      cpSync(template, root, { recursive: true });
+    }
     return root;
   };
 }

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

@@ -14,6 +14,7 @@ import { BOX_FINDING_CODES } from "./checks/boxes";
 import { RECORD_FINDING_CODES } from "./checks/records";
 import { DIAGRAM_FINDING_CODES } from "./checks/diagrams";
 import { SECURITY_FINDING_CODES } from "./checks/security";
+import { CI_WORKFLOW_FINDING_CODES } from "./ci-workflow";
 import { WORKSPACE_ERROR_CODES } from "./declaration";
 import { CHECK_CODES, CHECK_CONTRACT_VERSION, CHECK_ERROR_CODES, CHECK_OUTPUT_SCHEMA_ID, runChecks, type CheckDocument } from "./lineage-check";
 
@@ -39,8 +40,8 @@ describe("check output schema", () => {
   test("lists exactly the codes the code can return", () => {
     expect(schema.$defs.lockFinding.properties.code.enum).toEqual([...CHECK_CODES]);
     expect(schema.$defs.failure.properties.error.properties.code.enum).toEqual([...CHECK_ERROR_CODES]);
-    expect(schema.$defs.diagnostic.properties.code.enum).toEqual([...WORKSPACE_ERROR_CODES, ...BOX_FINDING_CODES, ...RECORD_FINDING_CODES, ...DIAGRAM_FINDING_CODES, ...SECURITY_FINDING_CODES]);
-    expect(schema.$defs.suppressed.properties.code.enum).toEqual([...WORKSPACE_ERROR_CODES, ...BOX_FINDING_CODES, ...RECORD_FINDING_CODES, ...DIAGRAM_FINDING_CODES, ...SECURITY_FINDING_CODES]);
+    expect(schema.$defs.diagnostic.properties.code.enum).toEqual([...WORKSPACE_ERROR_CODES, ...BOX_FINDING_CODES, ...RECORD_FINDING_CODES, ...DIAGRAM_FINDING_CODES, ...SECURITY_FINDING_CODES, ...CI_WORKFLOW_FINDING_CODES]);
+    expect(schema.$defs.suppressed.properties.code.enum).toEqual([...WORKSPACE_ERROR_CODES, ...BOX_FINDING_CODES, ...RECORD_FINDING_CODES, ...DIAGRAM_FINDING_CODES, ...SECURITY_FINDING_CODES, ...CI_WORKFLOW_FINDING_CODES]);
   });
 });
 

package/src/workspace/check.schema.json

@@ -332,7 +332,16 @@
 
             "security-runner-start-no-role",
 
-            "security-trust-unreadable"
+            "security-trust-unreadable",
+            "ci-workflow-green-undeclared",
+            "ci-workflow-no-pre-merge",
+            "ci-workflow-apply-in-green",
+            "ci-workflow-no-components",
+            "ci-workflow-no-environments",
+            "ci-workflow-ungated-env",
+            "ci-workflow-pipeline-missing",
+            "ci-workflow-pipeline-differs",
+            "ci-workflow-publish-missing"
           ],
           "description": "For WSP001: why the declaration can't be read. For WSP121 to WSP127, the box finding (#2726, #2727, #2780, #2850). For WSP117, work-acceptance-unmet (#2772). For WSP118, flag-stale (#4024). For WSP131 to WSP133, the diagram finding (#2764)."
         }
@@ -445,7 +454,16 @@
 
             "security-runner-start-no-role",
 
-            "security-trust-unreadable"
+            "security-trust-unreadable",
+            "ci-workflow-green-undeclared",
+            "ci-workflow-no-pre-merge",
+            "ci-workflow-apply-in-green",
+            "ci-workflow-no-components",
+            "ci-workflow-no-environments",
+            "ci-workflow-ungated-env",
+            "ci-workflow-pipeline-missing",
+            "ci-workflow-pipeline-differs",
+            "ci-workflow-publish-missing"
           ],
           "description": "For WSP001: why the declaration can't be read. For WSP121 to WSP127, the box finding (#2726, #2727, #2780, #2850). For WSP117, work-acceptance-unmet (#2772). For WSP118, flag-stale (#4024). For WSP131 to WSP133, the diagram finding (#2764)."
         },

package/src/workspace/checks/ci-workflow.test.ts

@@ -0,0 +1,150 @@
+/**
+ * WSP151, what a member under ci.workflow still lacks (#4168 step 6), and the
+ * reference page printed from CI_WORKFLOW_REQUIREMENTS.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterAll, describe, expect, test } from "vitest";
+import { runDeclarationChecks } from "../checks";
+import { ciWorkflowTable, CI_WORKFLOW_FINDING_CODES, workflowOf } from "../ci-workflow";
+import { REASON_CODES } from "../reason-codes";
+
+const DOCS = fileURLToPath(new URL("../../../../../docs/src/content/docs/", import.meta.url));
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+function repo(files: Record<string, string>): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-ci-workflow-")));
+  scratch.push(root);
+  execFileSync("git", ["init", "-q"], { cwd: root });
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  return root;
+}
+
+const member = (extra: Record<string, unknown> = {}) => ({ name: "app", dir: "app", kind: "other", because: "the app", ...extra });
+const declaration = (extra: Record<string, unknown> = {}, members = [member()]) => JSON.stringify({ name: "acme", schema: 1, members, ...extra }, null, 2);
+const green = (extra: Record<string, unknown> = {}) => ({ branch: "main", phases: { check: ["check"], suites: ["suites"] }, require: ["check", "suites"], preMerge: ["check"], ...extra });
+
+const CONFIG = 'export default { lexicons: ["aws"], environments: ["staging", "prod"] };\n';
+const COMPONENT = 'import { gate, phase } from "@intentius/chant/components/component";\nexport const app = { name: "app", deploy: [phase("Apply", [gate("prod")])] };\n';
+const PIPELINE = [
+  "on: [pull_request, push]",
+  "jobs:",
+  "  plan:",
+  "    steps:",
+  "      - run: chant ci run plan --in-place --no-push --env prod --gate pr-apply --forge github",
+  "  record:",
+  "    steps:",
+  "      - run: chant ci run record --in-place --env prod --gate pr-apply --forge github",
+  "",
+].join("\n");
+const TICK = "jobs:\n  tick:\n    steps:\n      - run: npx --yes @intentius/chant@0.124.33 ci tick\n";
+const PUBLISH = "jobs:\n  publish:\n    steps:\n      - run: npx chant release publish \"$LABEL\"\n";
+
+/** A member under trunk-curated with everything the workflow needs. */
+const complete = (extra: Record<string, string> = {}) => ({
+  "chant.workspace.json": declaration({ ci: { workflow: "trunk-curated", green: green() } }),
+  "app/chant.config.ts": CONFIG,
+  "app/app.component.ts": COMPONENT,
+  ".github/workflows/chant-pr.yml": PIPELINE,
+  ".github/workflows/chant-ci-green.yml": TICK,
+  ".github/workflows/chant-release.yml": PUBLISH,
+  ...extra,
+});
+
+/** The WSP151 findings as [code, entity]. */
+const found = async (root: string) =>
+  (await runDeclarationChecks(root, (f) => f, { gather: false })).diagnostics.filter((d) => d.ruleId === "WSP151").map((d) => [d.code, d.entity ?? null]);
+
+describe("ci.workflow (WSP151)", () => {
+  test("a declaration that names no workflow gets no finding", async () => {
+    const root = repo({ "chant.workspace.json": declaration(), "app/chant.config.ts": "export default {};\n" });
+    expect(await found(root)).toEqual([]);
+  });
+
+  test("a workspace with everything trunk-curated needs passes", async () => {
+    expect(await found(repo(complete()))).toEqual([]);
+  });
+
+  test("an empty workspace under trunk-curated reports each missing piece", async () => {
+    const root = repo({ "chant.workspace.json": declaration({ ci: { workflow: "trunk-curated" } }), "app/chant.config.ts": "export default {};\n" });
+    expect(await found(root)).toEqual([
+      ["ci-workflow-no-environments", "app"],
+      ["ci-workflow-no-components", "app"],
+      ["ci-workflow-green-undeclared", null],
+      ["ci-workflow-pipeline-missing", null],
+      ["ci-workflow-publish-missing", null],
+    ]);
+  });
+
+  test("no preMerge phases, and a required phase that matches the apply job", async () => {
+    const root = repo(complete({ "chant.workspace.json": declaration({ ci: { workflow: "trunk-curated", green: green({ phases: { check: ["check"], deploy: ["*apply"] }, require: ["check", "deploy"], preMerge: [] }) } }) }));
+    expect(await found(root)).toEqual([
+      ["ci-workflow-no-pre-merge", null],
+      ["ci-workflow-apply-in-green", null],
+    ]);
+  });
+
+  test("a component with no gate", async () => {
+    const root = repo(complete({ "app/app.component.ts": 'export const app = { name: "app", deploy: [] };\n' }));
+    expect(await found(root)).toEqual([["ci-workflow-ungated-env", "app"]]);
+  });
+
+  test("trunk-curated with an apply job on merge differs", async () => {
+    const root = repo(complete({ ".github/workflows/chant-pr.yml": PIPELINE.replace("ci run record", "ci run apply") }));
+    expect(await found(root)).toEqual([["ci-workflow-pipeline-differs", null]]);
+  });
+
+  test("trunk-curated+apply-on-merge with only a record job differs, and with an apply job passes", async () => {
+    const decl = declaration({ ci: { workflow: "trunk-curated+apply-on-merge", green: green() } });
+    expect(await found(repo(complete({ "chant.workspace.json": decl })))).toEqual([["ci-workflow-pipeline-differs", null]]);
+    expect(await found(repo(complete({ "chant.workspace.json": decl, ".github/workflows/chant-pr.yml": PIPELINE.replace("ci run record", "ci run apply") })))).toEqual([]);
+  });
+
+  test("a member's own workflow wins, and a top-level workflow skips members that don't build with chant", async () => {
+    const root = repo({
+      ...complete(),
+      "chant.workspace.json": declaration({ ci: { green: green() } }, [member({ ci: { workflow: "trunk-curated" } }), member({ name: "docs", dir: "docs" })]),
+      "docs/README.md": "",
+    });
+    expect(await found(root)).toEqual([]);
+    const top = repo({ ...complete(), "docs/README.md": "", "chant.workspace.json": declaration({ ci: { workflow: "trunk-curated", green: green() } }, [member(), member({ name: "docs", dir: "docs" })]) });
+    expect(await found(top)).toEqual([]);
+  });
+
+  test("ci.green.preMerge must name declared phases", async () => {
+    const root = repo({ "chant.workspace.json": declaration({ ci: { green: green({ preMerge: ["lint"] }) } }) });
+    const report = await runDeclarationChecks(root, (f) => f, { gather: false });
+    expect(report.diagnostics.find((d) => d.ruleId === "WSP001")?.message).toMatch(/ci\.green\.preMerge names the phase "lint"/);
+  });
+});
+
+describe("workflowOf", () => {
+  test("the member's own wins over the top level's", () => {
+    const d = { ci: { green: null, workflow: "trunk-curated" as const, reportUrl: null } };
+    expect(workflowOf(d, { ciWorkflow: null })).toBe("trunk-curated");
+    expect(workflowOf(d, { ciWorkflow: "trunk-curated+apply-on-merge" })).toBe("trunk-curated+apply-on-merge");
+    expect(workflowOf({ ci: null }, null)).toBeNull();
+  });
+});
+
+describe("the ci.workflow codes and reference page", () => {
+  test("every code is a read-contract reason code", () => {
+    for (const code of CI_WORKFLOW_FINDING_CODES) expect(REASON_CODES, code).toContain(code);
+  });
+
+  test("the CI workflows page carries the table CI_WORKFLOW_REQUIREMENTS prints", () => {
+    const page = readFileSync(join(DOCS, "reference", "ci-workflows.mdx"), "utf-8");
+    const table = /^\| Code \| Requirement \|[^\n]*\n(?:\|[^\n]*\n)*/m.exec(page)?.[0].trimEnd();
+    expect(table, "regenerate the table under Requirements from ciWorkflowTable()").toBe(ciWorkflowTable());
+  });
+});

package/src/workspace/checks/ci-workflow.ts

@@ -0,0 +1,129 @@
+/**
+ * WSP151 (#4168 step 6): what a member under `ci.workflow` still lacks.
+ *
+ * A declaration that names no workflow gets no finding from this file. The
+ * requirements and their codes are {@link CI_WORKFLOW_REQUIREMENTS}
+ * (../ci-workflow.ts). Like the security checklists (./security.ts), the
+ * check reads files and never runs them: `chant.config.ts` for the
+ * environments (its literal `environments`, as `workspace status` reads it),
+ * `*.component.ts` for components and gates, and the forge pipeline files for
+ * the jobs. A generated file that differs from what its generator writes is
+ * WSP101 to WSP106's to report; this check asks only whether the jobs the
+ * workflow needs are there.
+ */
+
+import type { WorkspaceCheck, WorkspaceDiagnostic } from "../checks";
+import type { CiWorkflow, Member } from "../declaration";
+import { appliesOnMerge, STUB_MARKER, workflowOf, type CiWorkflowCode } from "../ci-workflow";
+import { matchesCheckRun } from "../ci-green";
+import { staticPromotionOrder } from "../promotion-order";
+import { joinPath } from "../tree";
+import { allPipelineFiles, commandLines, componentFiles, read } from "./security";
+
+export const WSP_CI_WORKFLOW = "WSP151";
+
+const memberDir = (dir: string) => (dir === "." ? "" : dir);
+
+const PLAN = /\bci\s+run\s+plan\b|\bcomponents\s+pr-plan\b/;
+const RECORD = /\bci\s+run\s+record\b|\bcomponents\s+pr-record\b/;
+const APPLY = /\bci\s+run\s+apply\b|\bcomponents\s+pr-apply\b/;
+const TICK = /\bci\s+tick\b/;
+const PUBLISH = /\brelease\s+publish\b/;
+
+/** The apply job names a required phase could match. */
+const APPLY_JOB_NAMES = ["apply", "pr-apply"];
+
+export const CI_WORKFLOW_CHECKS: readonly WorkspaceCheck[] = [
+  {
+    id: WSP_CI_WORKFLOW,
+    name: "ci-workflow",
+    description: "Under ci.workflow: ci.green with pre-merge phases and no apply job required, each member with a component, environments and a gate on each component, and pipeline files that plan, record (or apply under apply on merge), tick and publish.",
+    severity: "warning",
+    configurable: true,
+    check(ctx) {
+      const d = ctx.declaration;
+      const under = d.members
+        .map((m) => ({ member: m, workflow: workflowOf(d, m) }))
+        .filter((u): u is { member: Member; workflow: CiWorkflow } => u.workflow !== null)
+        // The top level's workflow covers the members that build with chant; a member that names one itself is held to it.
+        .filter((u) => u.member.ciWorkflow !== null || ctx.tree.stat(joinPath(memberDir(u.member.dir), "chant.config.ts")) === "file");
+      if (under.length === 0 && !d.ci?.workflow) return [];
+      const pointer = d.ci?.workflow ? "/ci/workflow" : `${under[0]!.member.pointer}/ci/workflow`;
+      const out: WorkspaceDiagnostic[] = [];
+      const finding = (code: CiWorkflowCode, message: string, at: { pointer?: string; entity?: string; treeFile?: string; line?: number } = {}): void => {
+        out.push({
+          checkId: this.id,
+          severity: this.severity,
+          code,
+          message: `${code}: ${message}`,
+          pointer: at.pointer ?? pointer,
+          ...(at.entity !== undefined ? { entity: at.entity } : {}),
+          ...(at.treeFile !== undefined ? { treeFile: at.treeFile, line: at.line ?? 1, column: 1 } : {}),
+        });
+      };
+
+      const green = d.ci?.green ?? null;
+      if (!green) {
+        finding("ci-workflow-green-undeclared", "the workspace follows a ci.workflow and declares no ci.green, so no commit gets a verdict and no release can be cut; run chant ci init or add a ci.green block");
+      } else {
+        if ((green.preMerge ?? []).length === 0) {
+          finding("ci-workflow-no-pre-merge", "ci.green.preMerge names no phase, so nothing says which checks run before the branch moves; name the quick ones", { pointer: green.pointer });
+        }
+        for (const name of green.require) {
+          const phase = green.phases.find((p) => p.name === name);
+          const hit = phase?.runs.find((pattern) => APPLY_JOB_NAMES.some((job) => matchesCheckRun(pattern, job)));
+          if (phase && hit) {
+            finding("ci-workflow-apply-in-green", `the required phase ${name} matches the apply job with ${JSON.stringify(hit)}, so an apply that waits for a green commit would wait on itself; drop the pattern`, { pointer: phase.pointer });
+          }
+        }
+      }
+
+      for (const { member } of under) {
+        const dir = memberDir(member.dir);
+        const components = componentFiles(ctx.tree, dir);
+        if (components.length === 0) {
+          finding("ci-workflow-no-components", `member ${member.name} declares no component, so nothing of it can be cut or promoted; chant ci init writes a stub`, { pointer: member.pointer, entity: member.name });
+        } else if (components.every((f) => (read(ctx.tree, f) ?? "").includes(STUB_MARKER))) {
+          finding("ci-workflow-no-components", `member ${member.name}'s only component is the stub chant ci init wrote (${components[0]}); say how it is built and deployed, then delete its ${STUB_MARKER} line`, { pointer: member.pointer, entity: member.name, treeFile: components[0] });
+        }
+        const configPath = joinPath(dir, "chant.config.ts");
+        const config = read(ctx.tree, configPath);
+        // A config whose environments aren't literals can't be read without running it; say nothing rather than guess.
+        const order = config === null ? [] : staticPromotionOrder(config);
+        if (order !== undefined && order.length === 0) {
+          finding("ci-workflow-no-environments", `member ${member.name}'s chant.config.ts declares no environments, so a release has nowhere to be promoted to`, { pointer: member.pointer, entity: member.name, ...(config !== null ? { treeFile: configPath } : {}) });
+        }
+        for (const file of components) {
+          const text = read(ctx.tree, file) ?? "";
+          if (/\bgate\s*\(|kind\s*:\s*["']gate["']/.test(text)) continue;
+          const last = order && order.length > 0 ? order[order.length - 1]!.name : "the last environment";
+          finding("ci-workflow-ungated-env", `${file} has no gate, so a promote to ${last} waits on no approval; add a gate() step`, { pointer: member.pointer, entity: member.name, treeFile: file });
+        }
+      }
+
+      const files = allPipelineFiles(ctx);
+      const has = (re: RegExp) => files.some((f) => f.lines.some((l) => re.test(l)));
+      const applyOnMerge = under.some((u) => appliesOnMerge(u.workflow)) || (d.ci?.workflow ? appliesOnMerge(d.ci.workflow) : false);
+      const missing = [
+        ...(has(PLAN) ? [] : ["a plan job (ci run plan)"]),
+        ...(has(RECORD) || has(APPLY) ? [] : [applyOnMerge ? "an apply job (ci run apply)" : "a record job (ci run record)"]),
+        ...(has(TICK) ? [] : ["chant ci tick"]),
+      ];
+      if (missing.length > 0) {
+        finding("ci-workflow-pipeline-missing", `no pipeline file runs ${missing.join(", ")}; generate them with chant build --components --generate <forge> --pr-loop and chant ci workflow`);
+      }
+      if (!applyOnMerge) {
+        for (const l of commandLines(ctx, APPLY)) {
+          finding("ci-workflow-pipeline-differs", `${l.path} applies on merge, and the workflow is trunk-curated, where a merge records the plan and deploys nothing; regenerate without --apply-on-merge, or set ci.workflow to trunk-curated+apply-on-merge`, { treeFile: l.path, line: l.line });
+        }
+      } else if (!has(APPLY) && has(RECORD)) {
+        const l = commandLines(ctx, RECORD)[0]!;
+        finding("ci-workflow-pipeline-differs", `${l.path} records on merge, and the workflow is trunk-curated+apply-on-merge; regenerate with --apply-on-merge`, { treeFile: l.path, line: l.line });
+      }
+      if (!has(PUBLISH)) {
+        finding("ci-workflow-publish-missing", "no pipeline file runs chant release publish, so a cut release is never published; generate one with chant release workflow");
+      }
+      return out;
+    },
+  },
+];