@intentius/chant 0.124.48 → 0.124.49

package/src/op/gate-approval.ts

@@ -43,6 +43,9 @@ import { createHash } from "node:crypto";
 import { lexiconModulePath, importLexiconPackage } from "../lexicon-module";
 import { isStepOutputRef, type StepOutputRef } from "./step-output-ref";
 import { GATE_PLAN_CONTEXT_KEY } from "./gate-plan-context";
+import { GATE_APPROVAL_MODES, gateBaseApprovalProblems, gatePolicyVersion, isContextValue, isGatePolicyRef } from "./gate-approval-base";
+
+export { GATE_APPROVAL_MODES, gateBaseApprovalProblems, gatePolicyVersion, isGatePolicyRef } from "./gate-approval-base";
 import { quorumProblems, type GateQuorumRule, type GateQuorumSpec } from "./gate-quorum";
 
 export type { GateQuorumRule, GateQuorumSpec } from "./gate-quorum";
@@ -50,7 +53,6 @@ export type { GateQuorumRule, GateQuorumSpec } from "./gate-quorum";
 /** What a policy's decision does to the gate. */
 export type GateApprovalMode = "log-only" | "enforce";
 
-export const GATE_APPROVAL_MODES: readonly GateApprovalMode[] = ["log-only", "enforce"];
 
 /**
  * A policy set a lexicon rendered for a gate — plain data, so it lands in the
@@ -159,10 +161,6 @@ export interface GatePolicyEvaluator {
   evaluateGatePolicy(policy: GatePolicyRef, request: GatePolicyRequest): Promise<GatePolicyAnswer> | GatePolicyAnswer;
 }
 
-/** The version of a gate policy: `sha256:` and the hex digest of its text. A lexicon's helper stamps it, and OPS015 checks it still matches. */
-export function gatePolicyVersion(text: string): string {
-  return `sha256:${createHash("sha256").update(text).digest("hex")}`;
-}
 
 /**
  * The digest of a gate's resolved approval context (#3774): `sha256:` and the
@@ -180,17 +178,6 @@ function sortedKeys(_key: string, value: unknown): unknown {
   return value;
 }
 
-export function isGatePolicyRef(value: unknown): value is GatePolicyRef {
-  if (typeof value !== "object" || value === null) return false;
-  const v = value as Record<string, unknown>;
-  return (
-    v.kind === "gate-policy" &&
-    typeof v.lexicon === "string" && v.lexicon !== "" &&
-    typeof v.name === "string" && v.name !== "" &&
-    typeof v.version === "string" && v.version !== "" &&
-    typeof v.text === "string" && v.text.trim() !== ""
-  );
-}
 
 /**
  * Everything wrong with an `approval` block, one line each. The `gate()`
@@ -256,13 +243,15 @@ export function gateApprovalProblems(approval: unknown): string[] {
   return problems;
 }
 
-function isContextValue(value: unknown): boolean {
-  if (typeof value === "string" || typeof value === "boolean") return true;
-  if (typeof value === "number") return Number.isFinite(value);
-  if (Array.isArray(value)) return value.every((v) => typeof v === "string");
-  return isStepOutputRef(value);
+/** A gate's `policy`, `mode` and `context` as `identity.gates.<gate>` declares them at base (#4404). A step output reference is not data a declaration can hold, so a context value is a plain one. */
+export interface GateBaseApproval {
+  policy?: GatePolicyRef | null;
+  mode?: GateApprovalMode | null;
+  context?: Record<string, string | number | boolean | string[]> | null;
 }
 
+
+
 /** Import `lexicon`'s evaluator. Throws a message that names the package when it is not installed or exports none. */
 export async function loadGatePolicyEvaluator(lexicon: string): Promise<GatePolicyEvaluator> {
   // chant #2520 — a lexicon declared by module path exports its evaluator from that module.

package/src/op/gate-name.ts

@@ -37,6 +37,21 @@ export const FAN_OUT_GATE_OP = "fan-out";
  */
 export const WORKSPACE_UPGRADE_GATE_OP = "workspace-upgrade";
 
+/**
+ * The op name a `chant workspace exit` gate is recorded under (#3177). The gate
+ * is the exit's scope (`workspace`, or the member names joined with `+`), and
+ * it binds the digest of the exit's patch. Like an upgrade it is a command
+ * with no `*.op.ts` behind it, and leaving is a person's decision.
+ */
+export const WORKSPACE_EXIT_GATE_OP = "workspace-exit";
+
+/**
+ * The op name a `chant workspace promote` gate is recorded under (#3178). The
+ * gate is the member, and it binds the digest of the promotion's patch. A
+ * command with no `*.op.ts` behind it, like the upgrade.
+ */
+export const WORKSPACE_PROMOTE_GATE_OP = "workspace-promote";
+
 /**
  * The op name the override gate records denials and overrides under (#3760):
  * `_gates/policy-override.jsonl`, gate the subject a policy denied. Like a
@@ -69,7 +84,7 @@ const PR_GATE_OP = /^pr-\d+(?:-[a-z0-9][a-z0-9-]*)?$/;
  * no Op config to read `neverOverMcp` from, the pending record carries it.
  */
 export function isNeverOverMcpGateOp(op: string): boolean {
-  return op === FAN_OUT_GATE_OP || op === WORKSPACE_UPGRADE_GATE_OP || op === OVERRIDE_GATE_OP || op === RELEASE_GATE_OP || PR_GATE_OP.test(op);
+  return op === FAN_OUT_GATE_OP || op === WORKSPACE_UPGRADE_GATE_OP || op === WORKSPACE_EXIT_GATE_OP || op === OVERRIDE_GATE_OP || op === RELEASE_GATE_OP || PR_GATE_OP.test(op);
 }
 
 /** Either spelling of a gate step's name. `gate` since #2202; `signalName` through 0.59.0. */

package/src/op/gate.ts

@@ -50,7 +50,7 @@ import { describePlanDigest, samePlanDigest } from "../lifecycle/plan-digest";
 import { isModelAuthored } from "../lifecycle/gate-origin";
 import { appliedGatePath, isApprovalSpent, parseAppliedGateLines, type AppliedGateRecord } from "../lifecycle/gate-applied";
 import { sortedJsonReplacer } from "../utils";
-import { gateContextDigest, type GateApprover, type ResolvedGateApproval } from "./gate-approval";
+import { gateContextDigest, type GateApprover, type GateBaseApproval, type ResolvedGateApproval } from "./gate-approval";
 import {
   quorumNeed, quorumRuleProgress, quorumRules, ruleNeedsProof, samePrincipal, trustQuorumJudge, UNPROVEN_JUDGE,
   type GateQuorumJudge, type GateQuorumRuleProgress, type GateQuorumSpec,
@@ -130,10 +130,11 @@ export interface GateLedgerPort {
 export interface GateApprovalRule {
   /**
    * `quorum` (#4324) is the entry's `identity.gates.<gate>.quorum` at base:
-   * the rules an Op gate of that name takes in place of its own. Absent or
+   * the rules an Op gate of that name takes in place of its own. `policy`,
+   * `mode` and `context` (#4404) are read the same way. Each is absent or
    * null when the entry sets none.
    */
-  requirement: { gate: string; class: string | null; quorum?: GateQuorumSpec | null };
+  requirement: { gate: string; class: string | null; quorum?: GateQuorumSpec | null } & GateBaseApproval;
   /** Why `approval` doesn't count, or null when it does. */
   refuses(approval: GateResolutionRecord): string | null;
 }

package/src/op/local-executor.ts

@@ -41,7 +41,7 @@ import { gateName } from "./gate-name";
 import { resolveGateAliases } from "./gate-alias";
 import { gatePointOf } from "./gate-point";
 import { evaluatePointGate, workspaceGatePointAsker, type GatePointAsker } from "./gate-point-run";
-import type { ResolvedGateApproval } from "./gate-approval";
+import type { GateBaseApproval, ResolvedGateApproval } from "./gate-approval";
 import { quorumRules, quorumRulesFor, type GateQuorumSpec } from "./gate-quorum";
 import { GATE_PLAN_CONTEXT_KEY, gatePlanSummaryOfResult } from "./gate-plan-context";
 import { withOpRunContext, type OpRunContext, type PassedGate } from "./run-context";
@@ -741,16 +741,36 @@ function gateFn(step: GateStep): string {
  * `approval.quorum` is not read then, so a change can't lower the quorum its
  * own run needs. The base quorum applies to a gate whose Op declares no
  * `approval` block too. With none at base, the Op's quorum applies as before.
+ *
+ * #4404: `policy`, `mode` and `context` are read the same way, each from its
+ * own `identity.gates.<gate>` field (`baseApproval`). A field the entry sets
+ * replaces the Op's. The base `context` wins key by key: a change can't edit a
+ * key the entry declares, but a key only the Op declares (often a step output
+ * the run computes) still reaches the policy. A field the entry leaves out
+ * still comes from the Op, and `chant workspace check` (WSP153) reports it.
  */
 export function resolveGateApproval(
   step: GateStep,
   resultsById: ReadonlyMap<string, unknown>,
   env?: string,
   atBase?: GateQuorumSpec | null,
+  baseApproval?: GateBaseApproval | null,
 ): ResolvedGateApproval | undefined {
   const baseQuorum = atBase ?? undefined;
-  const authored = step.approval ?? (baseQuorum !== undefined ? {} : undefined);
-  if (!authored) return undefined;
+  const base = {
+    policy: baseApproval?.policy ?? undefined,
+    mode: baseApproval?.mode ?? undefined,
+    context: baseApproval?.context ?? undefined,
+  };
+  const anyBase = baseQuorum !== undefined || base.policy !== undefined || base.mode !== undefined || base.context !== undefined;
+  const opApproval = step.approval ?? (anyBase ? {} : undefined);
+  if (!opApproval) return undefined;
+  const authored = {
+    ...opApproval,
+    ...(base.policy !== undefined ? { policy: base.policy } : {}),
+    ...(base.mode !== undefined ? { mode: base.mode } : {}),
+    ...(base.context !== undefined ? { context: { ...(opApproval.context ?? {}), ...base.context } } : {}),
+  };
   const quorum = baseQuorum ?? authored.quorum;
   let context: Record<string, unknown> | undefined;
   if (authored.context) {
@@ -801,7 +821,7 @@ async function runGateStep(
   // a run over a missing digest.
   const resolvedPlan = resolveStepOutputRefs(step.plan, resultsById);
   const planDigest = typeof resolvedPlan === "string" && resolvedPlan !== "" ? resolvedPlan : undefined;
-  // #4324: the workspace's rule for this gate at base, read once: its quorum
+  // #4324, #4404: the workspace's rule for this gate at base, read once: its quorum, policy, mode and context
   // replaces the Op's, and evaluateGate judges approvals by it. A read that
   // fails ends the step as a failing record, as a ledger read does below.
   let rule: GateApprovalRule | null;
@@ -810,7 +830,7 @@ async function runGateStep(
   } catch (err) {
     return { record: { phase: phaseName, fn: gateFn(step), args: {}, status: "fail", durationMs: Date.now() - start, error: errMessage(err) } };
   }
-  const approval = resolveGateApproval(step, resultsById, gates.env, rule?.requirement.quorum);
+  const approval = resolveGateApproval(step, resultsById, gates.env, rule?.requirement.quorum, rule?.requirement);
   // #3947: a gate that resumes stores the outputs the steps after it read.
   const resumeAt = gates.resume?.gates.get(step);
   let checkpoint: GateCheckpoint | undefined;

package/src/pr-loop-bundle.test.ts

@@ -40,8 +40,9 @@ describe("the pull-request loop bundle", () => {
       "packages/core/src/plan-summary.ts",
       "packages/core/src/pr-forge.ts",
       "packages/core/src/pr-loop.ts",
+      "packages/core/src/pr-migrations.ts",
     ]);
-    // About 89 KB today, after the hooks line (#4288), the blocked set (#4291), the scheduled-run reads (#4289) and the requires checks (#4301).
-    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(96 * 1024);
+    // About 89 KB today, after the hooks line (#4288), the blocked set (#4291), the scheduled-run reads (#4289) the requires checks (#4301) and the migration notes (#4407), about 97 KB.
+    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(100 * 1024);
   });
 });

package/src/pr-loop.test.ts

@@ -424,3 +424,55 @@ describe("the policy in the report and the note (#4294)", () => {
     expect(prStatusDescription({ ...denied, stage: "apply", status: "refused", refusal: "policy-denied" })).toBe("refused: the policy denied the plan (main.deny_public)");
   });
 });
+
+describe("new migration files in the plan note (#4407)", () => {
+  const migrations: NonNullable<PrReport["migrations"]> = [
+    {
+      member: "ledger",
+      reader: "goose-dir",
+      file: "db/00002_index.sql",
+      version: "00002",
+      name: "index",
+      type: "versioned",
+      dialect: "postgres",
+      statements: [
+        {
+          index: 1,
+          sql: "CREATE INDEX orders_status_idx ON orders (status)",
+          outcome: "classified",
+          changes: [{ rule: "SQLPG241", class: "concurrently", label: "needs CONCURRENTLY", title: "Create an index without CONCURRENTLY", lock: "SHARE" }],
+        },
+        {
+          index: 2,
+          sql: "ALTER TABLE orders ALTER COLUMN a TYPE bigint",
+          outcome: "undecided",
+          changes: [],
+          candidates: [
+            { rule: "SQLPG206", class: "metadata", label: "metadata only", title: "t" },
+            { rule: "SQLPG207", class: "rewrite", label: "ACCESS EXCLUSIVE rewrite or scan", title: "t" },
+          ],
+          note: "x",
+        },
+      ],
+    },
+  ];
+  const withMigrations: PrReport = { ...planReport, migrations };
+
+  test("the report validates and the note lists each statement with its class, rule and lock", () => {
+    expectValid(withMigrations);
+    const note = renderPrNote(withMigrations);
+    expect(note).toContain("New migration files (1), classified offline. Nothing is applied and no server is contacted.");
+    expect(note).toContain("`db/00002_index.sql` (member `ledger`, postgres)");
+    expect(note).toContain("- 1. `CREATE INDEX orders_status_idx ON orders (status)`: needs CONCURRENTLY (SQLPG241, SHARE)");
+    expect(note).toContain("undecided between SQLPG206 metadata only and SQLPG207 ACCESS EXCLUSIVE rewrite or scan");
+  });
+
+  test("a report with none renders as before", () => {
+    expect(renderPrNote(planReport)).not.toContain("migration");
+  });
+
+  test("a note line cannot be broken out of by a file's text", () => {
+    const note = renderPrNote({ ...withMigrations, migrations: [{ ...migrations[0]!, statements: [], error: "bad\n\n# heading `x`" }] });
+    expect(note).toContain("- not read: bad # heading `x`");
+  });
+});

package/src/pr-loop.ts

@@ -49,6 +49,7 @@
 
 import type { ChangeSetAction, ChangeSetDocument } from "./change-set";
 import type { PrRequireOutcome } from "./pr-requires";
+import { renderMigrationLines, type PrMigrationFile } from "./pr-migrations";
 import { GITHUB_COMMENT_LIMIT, groupChangeSet, renderPlanSummaryMarkdown } from "./plan-summary";
 
 /** The schema a pull-request report names in `$schema`. */
@@ -84,6 +85,9 @@ export const PR_REPORT_POLICY_FLOOR = "0.124.41";
 /** The first chant whose apply report can carry `beforeMerge` and the `requires-unmet` and `before-merge-off` refusals (#4301, ws-106). */
 export const PR_REPORT_BEFORE_MERGE_FLOOR = "0.124.42";
 
+/** The first chant whose plan report can carry `migrations` (#4407). */
+export const PR_REPORT_MIGRATIONS_FLOOR = "0.124.49";
+
 /** The gate a pull request's apply waits on, unless the pipeline names another. */
 export const PR_APPLY_GATE = "pr-apply";
 
@@ -436,6 +440,13 @@ export interface PrReport {
    * {@link PR_REPORT_OVERDUE_FLOOR}.
    */
   overdue?: PrOverdue[];
+  /**
+   * Plan stage (#4407): the migration files the pull request adds in a
+   * migration-directory workspace member, each statement classified offline.
+   * Absent when it adds none. Added within contract 1 by chant
+   * {@link PR_REPORT_MIGRATIONS_FLOOR}.
+   */
+  migrations?: PrMigrationFile[];
   /** Component names: which changed, which run because they depend on one, and what the change touched that no component deploys. */
   selection: {
     changed: string[];
@@ -690,6 +701,7 @@ export function renderPrNote(report: PrReport, options: { limit?: number; approv
     out.push("", `Hooks: ${passed} passed${other.length > 0 ? `; ${other.join("; ")}` : ""}.`);
   }
   out.push(...policyLines(report));
+  out.push(...renderMigrationLines(report.migrations));
   if (report.selection.unclaimed.length > 0) {
     out.push("", `Changed, and deployed by no component: ${report.selection.unclaimed.map(code).join(", ")}.`);
   }

package/src/pr-migrations.ts

@@ -0,0 +1,97 @@
+/**
+ * The migration files a pull request adds, classified for the plan note
+ * (#4407). This is the "check" adoption level: each new migration in a
+ * migration-directory workspace member (goose, golang-migrate,
+ * clickhouse-migrations, Flyway) is read offline and its statements are given
+ * the class the lexicon's classifier gives the same change. Nothing is applied
+ * and no server is contacted.
+ *
+ * Core holds the shapes and the note's lines. The classes come from a
+ * lexicon's `classifyMigrations` (`./lexicon.ts`), the way a lexicon's
+ * `classifyDisruption` supplies the disruption of an update. Pure: it imports
+ * nothing, so `./pr-loop.ts` can render it.
+ */
+
+/** One change a statement makes, under one classifier rule. */
+export interface MigrationChange {
+  rule: string;
+  /** The rule's class, e.g. `rebuild`, `concurrently`, `metadata`. */
+  class: string;
+  /** The class as a report names it, e.g. `REBUILD`. */
+  label: string;
+  title: string;
+  /** Postgres: the lock the rule names. */
+  lock?: string;
+  destructive?: boolean;
+  note?: string;
+}
+
+/** What one statement came to: `undecided` lists `candidates`; `unclassified` and `data` say why in `note`. */
+export interface MigrationStatement {
+  /** 1-based position among the file's up statements. */
+  index: number;
+  /** The statement's first line, cut to 120 characters. */
+  sql: string;
+  outcome: "classified" | "undecided" | "unclassified" | "data";
+  changes: MigrationChange[];
+  candidates?: MigrationChange[];
+  note?: string;
+}
+
+/** What a lexicon answers for one new migration file. */
+export interface MigrationFileClassification {
+  /** The file, relative to the workspace root. */
+  file: string;
+  statements: MigrationStatement[];
+  /** Set when the file could not be read (a Flyway placeholder with no value): why. */
+  error?: string;
+}
+
+/** A new migration file in the report's `migrations`. */
+export interface PrMigrationFile extends MigrationFileClassification {
+  /** The workspace member whose directory holds it. */
+  member: string;
+  /** The reader that listed it: `goose-dir`, `golang-migrate-dir`, `clickhouse-migrations-dir` or `flyway-dir`. */
+  reader: string;
+  version: string;
+  name: string;
+  type: "versioned" | "repeatable" | "baseline" | "undo";
+  dialect: string;
+}
+
+/** One line of plain text: the report is read from a file the head's job wrote, so nothing in it breaks the note's layout. */
+const line = (s: string): string => s.replace(/\s+/g, " ").trim();
+
+const code = (s: string): string => `\`${line(s).replace(/`/g, "'")}\``;
+
+const changeText = (c: MigrationChange): string => `${c.label} (${c.rule}${c.lock ? `, ${c.lock}` : ""})${c.destructive ? ", removes data" : ""}`;
+
+/** The statement's row in the note. */
+function statementText(s: MigrationStatement): string {
+  if (s.outcome === "classified") return s.changes.map(changeText).join("; ") + (s.note ? `. ${line(s.note)}` : "");
+  if (s.outcome === "undecided") {
+    const decided = s.changes.length > 0 ? `${s.changes.map(changeText).join("; ")}; ` : "";
+    return `${decided}undecided between ${(s.candidates ?? []).map((c) => `${c.rule} ${c.label}`).join(" and ")}${s.note ? `: ${line(s.note)}` : ""}`;
+  }
+  if (s.outcome === "unclassified") return `no class${s.note ? `: ${line(s.note)}` : ""}`;
+  return `data, not schema${s.note ? `: ${line(s.note)}` : ""}`;
+}
+
+/**
+ * The note's section: one heading line per new file and a list of its
+ * statements with their classes. Empty when the pull request adds none.
+ */
+export function renderMigrationLines(files: readonly PrMigrationFile[] | undefined): string[] {
+  if (!files || files.length === 0) return [];
+  const out: string[] = ["", `New migration files (${files.length}), classified offline. Nothing is applied and no server is contacted.`];
+  for (const f of files) {
+    out.push("", `${code(f.file)} (member ${code(f.member)}, ${f.dialect}${f.type === "versioned" ? "" : `, ${f.type}`})`);
+    if (f.error) {
+      out.push(`- not read: ${line(f.error)}`);
+      continue;
+    }
+    if (f.statements.length === 0) out.push("- no up statements");
+    for (const s of f.statements) out.push(`- ${s.index}. ${code(s.sql)}: ${statementText(s)}`);
+  }
+  return out;
+}

package/src/pr-post.ts

@@ -137,7 +137,7 @@ export async function postPlanReport(input: PlanPostInput): Promise<PlanPostResu
       state = prStatusState(report);
       description = prStatusDescription(report);
       // A member the change does not reach has nothing to say on the pull request (as pr-plan's own publish).
-      if (!(input.member && report.status === "nothing" && !report.overdue?.length)) note = planNoteFor(report, input.forge, prNoteMarker(input.env, input.member));
+      if (!(input.member && report.status === "nothing" && !report.overdue?.length && !report.migrations?.length)) note = planNoteFor(report, input.forge, prNoteMarker(input.env, input.member));
     } catch (err) {
       refused = `the plan report does not render: ${err instanceof Error ? err.message : String(err)}`;
       state = "failure";

package/src/workspace/__fixtures__/import/spacelift.json

@@ -0,0 +1,9 @@
+{
+  "account": "acme",
+  "stacks": [
+    { "id": "vpc", "name": "VPC", "space": "root", "projectRoot": "terraform/vpc", "vendor": "terraform", "labels": ["env:prod"] },
+    { "id": "db", "name": "Database", "projectRoot": "terraform/db", "labels": ["env:prod"], "policies": ["p1"], "dependsOn": [{ "stack": "vpc", "references": [{ "outputName": "subnet_ids", "inputName": "TF_VAR_subnets" }] }] },
+    { "id": "cfg", "name": "ansible-config", "vendor": "ansible", "projectRoot": "ansible", "dependsOn": [{ "stack": "db" }, { "stack": "nope" }], "contexts": ["c1"] }
+  ],
+  "policies": [{ "id": "p1", "name": "approval", "type": "APPROVAL" }]
+}

package/src/workspace/__fixtures__/import/tfc.json

@@ -0,0 +1,13 @@
+{
+  "organization": "acme",
+  "projects": [{ "id": "prj-1", "name": "platform" }],
+  "workspaces": [
+    { "id": "ws-net", "name": "network-prod", "project": "prj-1", "workingDirectory": "infra/network", "tags": ["env:prod"], "variables": [{ "key": "region" }, { "key": "token", "sensitive": true }], "vcsRepo": "acme/infra" },
+    { "id": "ws-app", "name": "app-prod", "project": "prj-1", "workingDirectory": "infra/app", "tags": ["env:prod"], "runTriggers": ["ws-net", "ws-gone"] },
+    { "id": "ws-app-dev", "name": "app-dev", "workingDirectory": "infra/app", "tags": ["environment:dev"], "runTriggers": ["network-prod"] }
+  ],
+  "policySets": [
+    { "name": "no-public-s3", "kind": "sentinel", "enforcement": "hard-mandatory", "workspaces": ["ws-app"] },
+    { "name": "tags-required", "global": true }
+  ]
+}

package/src/workspace/behold-kinds.test.ts

@@ -46,6 +46,7 @@ function install(root: string, from: string): string {
   mkdirSync(dir, { recursive: true });
   cpSync(join(from, "package.json"), join(dir, "package.json"));
   cpSync(join(from, "workspace-kinds.json"), join(dir, "workspace-kinds.json"));
+  if (existsSync(join(from, "schemas"))) cpSync(join(from, "schemas"), join(dir, "schemas"), { recursive: true });
   const targets = new Set<string>(["./index.js"]);
   const collect = (entry: unknown): void => {
     if (typeof entry === "string") targets.add(entry.replace("*", "workspace-kinds"));

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

@@ -16,6 +16,7 @@ import { DIAGRAM_FINDING_CODES } from "./checks/diagrams";
 import { SECURITY_FINDING_CODES } from "./checks/security";
 import { CI_WORKFLOW_FINDING_CODES } from "./ci-workflow";
 import { CI_BRANCH_FINDING_CODES } from "./checks/ci-branch";
+import { GATE_APPROVAL_FINDING_CODES } from "./checks/gate-approval";
 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";
 
@@ -41,8 +42,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, ...CI_WORKFLOW_FINDING_CODES, ...CI_BRANCH_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, ...CI_BRANCH_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, ...CI_BRANCH_FINDING_CODES, ...GATE_APPROVAL_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, ...CI_BRANCH_FINDING_CODES, ...GATE_APPROVAL_FINDING_CODES]);
   });
 });
 

package/src/workspace/check.schema.json

@@ -349,7 +349,8 @@
             "ci-workflow-pipeline-missing",
             "ci-workflow-pipeline-differs",
             "ci-workflow-publish-missing",
-            "ci-branch-route-differs"
+            "ci-branch-route-differs",
+            "gate-approval-unbased"
           ],
           "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)."
         }
@@ -472,7 +473,8 @@
             "ci-workflow-pipeline-missing",
             "ci-workflow-pipeline-differs",
             "ci-workflow-publish-missing",
-            "ci-branch-route-differs"
+            "ci-branch-route-differs",
+            "gate-approval-unbased"
           ],
           "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/gate-approval.test.ts

@@ -0,0 +1,77 @@
+/**
+ * WSP153 (#4404): an Op gate's approval block that `identity.gates` does not
+ * set at base.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { runDeclarationChecks } from "../checks";
+import { gateUses, unbasedFields } from "./gate-approval";
+import { REASONS } from "../reason-codes";
+
+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-gate-approval-")));
+  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 op = (approval: unknown): string =>
+  JSON.stringify({ name: "release", phases: [{ name: "Gate", parallel: false, steps: [{ kind: "gate", gate: "ship", timeout: "48h", ...(approval ? { approval } : {}) }] }] });
+const workspace = (gates: Record<string, unknown> | undefined, opText: string): Record<string, string> => ({
+  "chant.workspace.json": JSON.stringify({ name: "acme", schema: 1, members: [{ name: "app", dir: "app", kind: "other", because: "app" }], ...(gates ? { identity: { gates } } : {}) }),
+  "app/dist/ops/release/op.json": opText,
+});
+const found = async (root: string) =>
+  (await runDeclarationChecks(root, (f) => f, { gather: false })).diagnostics.filter((d) => d.ruleId === "WSP153");
+
+describe("WSP153: an approval block base does not back", () => {
+  test("a gate with an approval block and no entry at base is reported, with the fields it sets", async () => {
+    const [d] = await found(repo(workspace(undefined, op({ quorum: { count: 2 }, mode: "enforce" }))));
+    expect(d).toMatchObject({ code: "gate-approval-unbased", severity: "warning", entity: "ship" });
+    expect(d.message).toMatch(/gate "ship" in Op release sets quorum, mode in its approval block/);
+    expect(d.message).toMatch(/no entry for it at base/);
+  });
+
+  test("an entry that sets only some of the fields leaves the rest reported", async () => {
+    const root = repo(workspace({ ship: { quorum: { count: 2 } } }, op({ quorum: { count: 2 }, mode: "enforce", context: { risk: "low", team: "x" } })));
+    const [d] = await found(root);
+    expect(d.message).toMatch(/sets mode, context \(risk, team\)/);
+    expect(d.message).toMatch(/identity\.gates\.ship sets none of them/);
+  });
+
+  test("an entry that sets every field the Op does is clean", async () => {
+    const approval = { quorum: { count: 2 }, mode: "enforce", context: { risk: "low" } };
+    const clean = repo(workspace({ ship: { quorum: { count: 2 }, mode: "enforce", context: { risk: "high" } } }, op(approval)));
+    expect(await found(clean)).toEqual([]);
+  });
+
+  test("a gate with no approval block, or an Op that is not built, is not reported", async () => {
+    expect(await found(repo(workspace(undefined, op(undefined))))).toEqual([]);
+    expect(await found(repo({ "chant.workspace.json": JSON.stringify({ name: "acme", schema: 1, members: [{ name: "app", dir: "app", kind: "other", because: "app" }] }) }))).toEqual([]);
+  });
+
+  test("it reads gates nested in an effect and in onFailure", () => {
+    const uses = gateUses({
+      phases: [{ steps: [{ kind: "effect", steps: [{ kind: "gate", gate: "inner", approval: { mode: "enforce" } }] }] }],
+      onFailure: [{ steps: [{ kind: "gate", signalName: "undo", approval: { quorum: { count: 2 } } }] }],
+    });
+    expect(uses.map((u) => u.gate)).toEqual(["inner", "undo"]);
+    expect(unbasedFields(uses[0], undefined)).toEqual(["mode"]);
+  });
+
+  test("the code is a documented reason code", () => {
+    expect(REASONS["gate-approval-unbased"]).toMatch(/identity\.gates does not set at base/);
+  });
+});