@intentius/chant 0.124.46 → 0.124.49

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

@@ -15,6 +15,8 @@ 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 { 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";
 
@@ -40,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]);
-    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]);
+    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]);
   });
 });
 
@@ -49,13 +51,13 @@ describe("chant workspace check on the chant repo (#2557)", () => {
   test("validates in the working tree and at HEAD", async () => {
     const now = result(await runChecks(REPO));
     expectValid(now);
-    expect(now.workspace).toEqual({ name: "chant", root: "." });
+    expect(now.workspace).toMatchObject({ name: "chant", root: "." });
     expect(now.declaration?.file).toBe("chant.workspace.json");
 
     const head = result(await runChecks(join(REPO, "packages", "core"), "HEAD"));
     expectValid(head);
     expect(head.at).toBe(git(REPO, "rev-parse", "HEAD"));
-    expect(head.workspace).toEqual({ name: "chant", root: "." });
+    expect(head.workspace).toMatchObject({ name: "chant", root: "." });
     expect(head.declaration?.file).toBe("../../chant.workspace.json");
   });
 });
@@ -82,7 +84,7 @@ describe("chant workspace check on built workspaces", () => {
     const doc = result(await runChecks(root));
     expectValid(doc);
     expect(doc.ok).toBe(false);
-    expect(doc.workspace).toEqual({ name: "acme", root: "." });
+    expect(doc.workspace).toEqual({ name: "acme", root: ".", repo: null });
     expect(ruleIds(doc)).toEqual(["WSP004", "WSP003"]);
 
     const tooOld = repo({ "chant.workspace.json": declaration([], { minReader: "999.0.0" }) });
@@ -93,7 +95,7 @@ describe("chant workspace check on built workspaces", () => {
     ] as const) {
       const d = result(await runChecks(dir));
       expectValid(d);
-      expect(d.workspace).toEqual({ name: null, root: "." });
+      expect(d.workspace).toEqual({ name: null, root: ".", repo: null });
       expect(d.declaration?.diagnostics.map((x) => [x.ruleId, x.code])).toEqual([["WSP001", code]]);
     }
   });

package/src/workspace/check.schema.json

@@ -65,6 +65,13 @@
                   ],
                   "description": "The declared name, or null when the declaration can't be read."
                 },
+                "repo": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "Added in contract 1 by #3168. The repository the document came from: the URL of the remote origin of the git repository that holds the workspace, with any user name or password removed, or null when there is no origin or the workspace is outside git. With name, root and the revision, it says which repository's workspace a document describes, so a reader that gathers several repositories' documents, such as an org workspace's repo members, tells them apart."
+                },
                 "root": {
                   "type": "string",
                   "description": "The workspace root relative to the git root, with / separators, \".\" for the git root itself. An absolute path outside a git repository."
@@ -341,7 +348,9 @@
             "ci-workflow-ungated-env",
             "ci-workflow-pipeline-missing",
             "ci-workflow-pipeline-differs",
-            "ci-workflow-publish-missing"
+            "ci-workflow-publish-missing",
+            "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)."
         }
@@ -463,7 +472,9 @@
             "ci-workflow-ungated-env",
             "ci-workflow-pipeline-missing",
             "ci-workflow-pipeline-differs",
-            "ci-workflow-publish-missing"
+            "ci-workflow-publish-missing",
+            "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/ci-branch.test.ts

@@ -0,0 +1,128 @@
+/**
+ * WSP152 (#4325): a member's generated pipeline targets the branch
+ * `ci.branches` routes the member to.
+ */
+
+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 { pipelineTargets, routeDifferences } from "./ci-branch";
+import { REASONS } from "../reason-codes";
+import { servedBranches } from "../ci-branches";
+
+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-branch-")));
+  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;
+}
+
+/** A generated pull-request pipeline, as chant writes it for a target `branch` (`--branch` is on the record and apply commands only). */
+const pipeline = (branch: string | null, triggers: string[] = branch === null ? [] : [branch]): string =>
+  [
+    "on:",
+    "  pull_request:",
+    ...(triggers.length > 0 ? [`    branches: [${triggers.join(", ")}]`] : []),
+    "  push:",
+    ...(triggers.length > 0 ? [`    branches: [${triggers.join(", ")}]`] : []),
+    "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${branch === null ? "" : ` --branch "${branch}"`}`,
+    "",
+  ].join("\n");
+
+const PIPELINE_PATH = ".github/workflows/chant-pr.app.prod.yml";
+const record = JSON.stringify({ schema: 1, files: [{ path: PIPELINE_PATH, command: "chant build" }] });
+const workspace = (branches: Record<string, string[]> | undefined, text: string, members = ["app"]): Record<string, string> => ({
+  "chant.workspace.json": JSON.stringify({ name: "acme", schema: 1, members: members.map((name) => ({ name, dir: name, kind: "other", because: name })), ...(branches ? { ci: { branches } } : {}) }),
+  ...Object.fromEntries(members.map((m) => [`${m}/.chant/generated.json`, record])),
+  [PIPELINE_PATH]: text,
+});
+
+const found = async (root: string) =>
+  (await runDeclarationChecks(root, (f) => f, { gather: false })).diagnostics.filter((d) => d.ruleId === "WSP152").map((d) => [d.code, d.entity ?? null, d.severity]);
+
+describe("what a pipeline targets", () => {
+  test("reads the --branch of each record and apply command, and the trigger branch lists", () => {
+    expect(pipelineTargets(pipeline("release"))).toEqual({
+      jobs: [{ line: 12, branch: "release" }],
+      triggers: [
+        { trigger: "push", branches: ["release"] },
+        { trigger: "pull_request", branches: ["release"] },
+      ],
+    });
+    expect(pipelineTargets(pipeline(null)).jobs).toEqual([{ line: 10, branch: null }]);
+    expect(pipelineTargets("not: [valid").triggers).toEqual([]);
+  });
+
+  test("a routed member's pipeline names its route in both places; an unrouted one does not name a reserved branch", () => {
+    const listed = ["release"];
+    expect(routeDifferences(pipelineTargets(pipeline("release")), "release", listed, "app")).toEqual([]);
+    expect(routeDifferences(pipelineTargets(pipeline("main")), "release", listed, "app")).toHaveLength(3);
+    expect(routeDifferences(pipelineTargets(pipeline(null)), "release", listed, "app")).toEqual([expect.stringContaining("the default branch")]);
+    expect(routeDifferences(pipelineTargets(pipeline("release", ["release", "main"])), "release", listed, "app")).toHaveLength(2);
+    expect(routeDifferences(pipelineTargets(pipeline("main")), null, listed, "app")).toEqual([]);
+    expect(routeDifferences(pipelineTargets(pipeline("release")), null, listed, "app")).toHaveLength(3);
+  });
+});
+
+describe("WSP152 over a workspace", () => {
+  test("a pipeline on the route passes, and a workspace with no ci.branches is not read", async () => {
+    expect(await found(repo(workspace({ release: ["app"] }, pipeline("release"))))).toEqual([]);
+    expect(await found(repo(workspace(undefined, pipeline("anything"))))).toEqual([]);
+  });
+
+  test("a pipeline generated before the route changed fails", async () => {
+    const root = repo(workspace({ release: ["app"] }, pipeline("main")));
+    expect(await found(root)).toEqual([
+      ["ci-branch-route-differs", "app", "error"],
+      ["ci-branch-route-differs", "app", "error"],
+      ["ci-branch-route-differs", "app", "error"],
+    ]);
+  });
+
+  test("an unrouted member's pipeline may not target a branch ci.branches reserves", async () => {
+    expect(await found(repo(workspace({ release: ["other"] }, pipeline("release"))))).toHaveLength(3);
+    expect(await found(repo(workspace({ release: ["other"] }, pipeline("main"))))).toEqual([]);
+  });
+
+  test("the code is a documented reason code", () => {
+    expect(REASONS["ci-branch-route-differs"]).toMatch(/targets a branch other than/);
+  });
+});
+
+describe("the branches ci serve polls (#4325)", () => {
+  const branches = { release: ["prod-*"], staging: ["stg-*"] };
+
+  test("a routed member polls its route alone, and a branch that disagrees is refused", () => {
+    expect(servedBranches(branches, "prod-eu", "main", false)).toEqual({ served: ["release"], routed: ["release"] });
+    expect(servedBranches(branches, "prod-eu", "release", true).served).toEqual(["release"]);
+    expect(() => servedBranches(branches, "prod-eu", "main", true)).toThrow(/routes member prod-eu to release/);
+  });
+
+  test("an unrouted member polls the default branch, and not one reserved for other members", () => {
+    expect(servedBranches(branches, "docs", "main", false)).toEqual({ served: ["main"], routed: [] });
+    expect(() => servedBranches(branches, "docs", "release", true)).toThrow(/member docs is not one/);
+  });
+
+  test("with no member, the default branch and then each routed branch", () => {
+    expect(servedBranches(branches, undefined, "main", false)).toEqual({ served: ["main", "release", "staging"], routed: ["release", "staging"] });
+    expect(servedBranches(undefined, undefined, "main", false)).toEqual({ served: ["main"], routed: [] });
+    expect(servedBranches(branches, undefined, "release", true).served).toEqual(["release", "staging"]);
+  });
+});

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

@@ -0,0 +1,141 @@
+/**
+ * WSP152 (#4325): a member's generated pull-request pipeline targets the
+ * branch `ci.branches` routes the member to.
+ *
+ * `chant build --pr-loop` refuses a branch that disagrees with the route
+ * (../member-pipeline.ts), but only when it writes the file. A route changed
+ * after the pipeline was generated, or a pipeline edited by hand, goes
+ * unnoticed until a push to the wrong branch applies nothing. This check
+ * reads the files each member's generated-file record lists and compares what
+ * they target with the route. It reads files and never runs them.
+ *
+ * A pipeline names its target in two places: the `--branch` its record and
+ * apply commands carry, and the `branches` of its `push` and `pull_request`
+ * triggers. A routed member's pipeline names the route in both. A member with
+ * no route may name a branch `ci.branches` does not list, and not one it
+ * lists, since that branch applies only the members its globs match.
+ */
+
+import type { WorkspaceCheck, WorkspaceDiagnostic } from "../checks";
+import type { Member } from "../declaration";
+import { routedBranch } from "../ci-branches";
+import { GENERATED_RECORD_FILE } from "../member-pipeline";
+import { joinPath } from "../tree";
+import { parseYAMLDocument } from "../../yaml";
+import { read } from "./security";
+
+export const WSP_CI_BRANCH_ROUTE = "WSP152";
+
+/** The finding code WSP152 reports. */
+export const CI_BRANCH_FINDING_CODES = ["ci-branch-route-differs"] as const;
+
+const memberDir = (dir: string) => (dir === "." ? "" : dir);
+
+/** A record or apply command of the pull-request loop: `ci run record|apply`, or `components pr-record|pr-apply`. */
+const JOB = /\bci\s+run\s+(?:record|apply)\b|\bcomponents\s+pr-(?:record|apply)\b/;
+const BRANCH_FLAG = /--branch(?:\s+|=)(?:"([^"]+)"|'([^']+)'|(\S+))/;
+
+/** What a pipeline file says it targets. */
+export interface PipelineTargets {
+  /** The `--branch` of each record or apply command, by line; null for a command with none. */
+  jobs: { line: number; branch: string | null }[];
+  /** The branches its `push` and `pull_request` triggers list, by trigger. Absent for a trigger with no list. */
+  triggers: { trigger: "push" | "pull_request"; branches: string[] }[];
+}
+
+/** The branches a pipeline file targets, read from its text. */
+export function pipelineTargets(text: string): PipelineTargets {
+  const jobs: PipelineTargets["jobs"] = [];
+  text.split("\n").forEach((line, i) => {
+    if (!JOB.test(line)) return;
+    const m = BRANCH_FLAG.exec(line);
+    jobs.push({ line: i + 1, branch: m ? (m[1] ?? m[2] ?? m[3] ?? null) : null });
+  });
+  const triggers: PipelineTargets["triggers"] = [];
+  try {
+    const doc = parseYAMLDocument(text) as { on?: unknown; true?: unknown } | null;
+    // YAML 1.1 reads a bare `on` key as true.
+    const on = doc && typeof doc === "object" ? (doc.on ?? doc.true) : undefined;
+    if (on && typeof on === "object" && !Array.isArray(on)) {
+      for (const trigger of ["push", "pull_request"] as const) {
+        const t = (on as Record<string, unknown>)[trigger];
+        const branches = t && typeof t === "object" ? (t as { branches?: unknown }).branches : undefined;
+        if (Array.isArray(branches)) triggers.push({ trigger, branches: branches.filter((b): b is string => typeof b === "string") });
+      }
+    }
+  } catch {
+    // A file that is not YAML has no triggers to compare; its commands still are.
+  }
+  return { jobs, triggers };
+}
+
+/**
+ * What differs between `targets` and the branch `own` the member is routed to
+ * (null when it has no route), as sentences. `listed` is every branch
+ * `ci.branches` names.
+ */
+export function routeDifferences(targets: PipelineTargets, own: string | null, listed: readonly string[], member: string): string[] {
+  const out: string[] = [];
+  const said = (b: string | null): string => (b === null ? "the default branch (it passes no --branch)" : b);
+  for (const j of targets.jobs) {
+    if (own !== null && j.branch !== own) out.push(`line ${j.line} targets ${said(j.branch)}, and ci.branches routes member ${member} to ${own}`);
+    else if (own === null && j.branch !== null && listed.includes(j.branch)) out.push(`line ${j.line} targets ${j.branch}, which ci.branches reserves for the members its globs match, and member ${member} is not one`);
+  }
+  for (const t of targets.triggers) {
+    if (own !== null && !(t.branches.length === 1 && t.branches[0] === own)) out.push(`its ${t.trigger} trigger lists ${t.branches.join(", ") || "no branch"}, and ci.branches routes member ${member} to ${own}`);
+    else if (own === null) {
+      const reserved = t.branches.filter((b) => listed.includes(b));
+      if (reserved.length > 0) out.push(`its ${t.trigger} trigger lists ${reserved.join(", ")}, which ci.branches reserves for the members its globs match, and member ${member} is not one`);
+    }
+  }
+  return out;
+}
+
+/** The files a member's generated-file record lists, which are pipelines the check can read. */
+function recordedFiles(ctx: Parameters<WorkspaceCheck["check"]>[0], member: Member): string[] {
+  const text = read(ctx.tree, joinPath(memberDir(member.dir), GENERATED_RECORD_FILE));
+  if (text === null) return [];
+  try {
+    const parsed = JSON.parse(text) as { files?: { path?: unknown }[] };
+    return (parsed.files ?? []).flatMap((f) => (typeof f.path === "string" && /\.ya?ml$/.test(f.path) ? [f.path] : []));
+  } catch {
+    return [];
+  }
+}
+
+export const CI_BRANCH_CHECKS: readonly WorkspaceCheck[] = [
+  {
+    id: WSP_CI_BRANCH_ROUTE,
+    name: "ci-branch-route",
+    description: "A member's generated pull-request pipeline targets the branch ci.branches routes the member to, in its record and apply commands and its push and pull_request triggers.",
+    severity: "error",
+    configurable: true,
+    check(ctx) {
+      const branches = ctx.declaration.ci?.branches;
+      if (!branches || Object.keys(branches).length === 0) return [];
+      const listed = Object.keys(branches);
+      const out: WorkspaceDiagnostic[] = [];
+      for (const member of ctx.declaration.members) {
+        const own = routedBranch(branches, member.name);
+        for (const path of recordedFiles(ctx, member)) {
+          const text = read(ctx.tree, path);
+          if (text === null) continue;
+          for (const why of routeDifferences(pipelineTargets(text), own, listed, member.name)) {
+            out.push({
+              checkId: this.id,
+              severity: this.severity,
+              code: CI_BRANCH_FINDING_CODES[0],
+              message: `WSP152: ${path}: ${why}; regenerate it with chant build --components --generate <forge> --pr-loop`,
+              pointer: "/ci/branches",
+              entity: member.name,
+              treeFile: path,
+              line: 1,
+              column: 1,
+            });
+          }
+        }
+      }
+      return out;
+    },
+  },
+];

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/);
+  });
+});

package/src/workspace/checks/gate-approval.ts

@@ -0,0 +1,121 @@
+/**
+ * WSP153 (#4404): an Op gate's `approval` block that `identity.gates` does
+ * not back at base.
+ *
+ * A run reads a gate's `quorum`, `policy`, `mode` and `context` from
+ * `identity.gates.<gate>` in the declaration at base (#4324, #4404). A field
+ * the entry leaves out is read from the Op being run, which the change under
+ * review can edit, so a pull request can lower a quorum or switch a policy to
+ * `log-only` and be judged by its own edit. The Op-side fallback stays so an
+ * existing Op does not drop to one approval overnight. This check names each
+ * gate that still leans on it, and the fields it leans on.
+ *
+ * It reads each member's built Ops (`dist/ops/<name>/op.json`) and runs
+ * nothing. An Op that has not been built is not seen.
+ */
+
+import type { WorkspaceCheck, WorkspaceDiagnostic } from "../checks";
+import { joinPath } from "../tree";
+import { read } from "./security";
+
+export const WSP_GATE_APPROVAL_UNBASED = "WSP153";
+
+/** The finding code WSP153 reports. */
+export const GATE_APPROVAL_FINDING_CODES = ["gate-approval-unbased"] as const;
+
+const memberDir = (dir: string) => (dir === "." ? "" : dir);
+
+type Fields = "quorum" | "policy" | "mode" | "context";
+
+interface GateUse {
+  gate: string;
+  /** What the Op's `approval` block sets. Context is the keys it sets. */
+  quorum: boolean;
+  policy: boolean;
+  mode: boolean;
+  context: string[];
+}
+
+interface StepJson {
+  kind?: string;
+  gate?: string;
+  signalName?: string;
+  approval?: { quorum?: unknown; policy?: unknown; mode?: unknown; context?: Record<string, unknown> };
+  steps?: StepJson[];
+}
+
+/** The gates of a built Op that declare an `approval` block, with the fields it sets. A gate that asks a decision point has none. */
+export function gateUses(op: { phases?: { steps?: StepJson[] }[]; onFailure?: { steps?: StepJson[] }[] }): GateUse[] {
+  const out: GateUse[] = [];
+  const visit = (step: StepJson): void => {
+    if (step.kind === "gate" && step.approval && typeof step.approval === "object") {
+      const a = step.approval;
+      out.push({
+        gate: step.gate ?? step.signalName ?? "",
+        quorum: a.quorum !== undefined,
+        policy: a.policy !== undefined,
+        mode: a.mode !== undefined,
+        context: a.context && typeof a.context === "object" ? Object.keys(a.context) : [],
+      });
+    }
+    if (step.kind === "effect") (step.steps ?? []).forEach(visit);
+  };
+  for (const p of [...(op.phases ?? []), ...(op.onFailure ?? [])]) (p.steps ?? []).forEach(visit);
+  return out;
+}
+
+/** The fields of `use` that `entry` (the gate's `identity.gates` entry, or undefined) does not set, as phrases. Empty when base backs every one. */
+export function unbasedFields(use: GateUse, entry: { quorum: unknown; policy: unknown; mode: unknown; context: Record<string, unknown> | null } | undefined): string[] {
+  const out: string[] = [];
+  const has = (f: Exclude<Fields, "context">): boolean => entry?.[f] !== null && entry?.[f] !== undefined;
+  for (const f of ["quorum", "policy", "mode"] as const) if (use[f] && !has(f)) out.push(f);
+  const loose = use.context.filter((k) => !(k in (entry?.context ?? {})));
+  if (loose.length > 0) out.push(`context (${loose.join(", ")})`);
+  return out;
+}
+
+export const GATE_APPROVAL_CHECKS: readonly WorkspaceCheck[] = [
+  {
+    id: WSP_GATE_APPROVAL_UNBASED,
+    name: "gate-approval-unbased",
+    description: "An Op gate declares an approval block whose quorum, policy, mode or context identity.gates does not set at base, so the change being run can edit it.",
+    severity: "warning",
+    configurable: true,
+    check(ctx) {
+      const out: WorkspaceDiagnostic[] = [];
+      const gates = ctx.declaration.identity?.gates ?? {};
+      for (const member of ctx.declaration.members) {
+        const opsDir = joinPath(memberDir(member.dir), "dist", "ops");
+        for (const entry of ctx.tree.list(opsDir) ?? []) {
+          if (entry.type !== "dir") continue;
+          const path = joinPath(opsDir, entry.name, "op.json");
+          const text = read(ctx.tree, path);
+          if (text === null) continue;
+          let op: Parameters<typeof gateUses>[0] & { name?: string };
+          try {
+            op = JSON.parse(text);
+          } catch {
+            continue;
+          }
+          for (const use of gateUses(op)) {
+            const base = gates[use.gate];
+            const missing = unbasedFields(use, base);
+            if (missing.length === 0) continue;
+            out.push({
+              checkId: this.id,
+              severity: this.severity,
+              code: GATE_APPROVAL_FINDING_CODES[0],
+              message: `WSP153: gate "${use.gate}" in Op ${op.name ?? entry.name} sets ${missing.join(", ")} in its approval block, and ${base ? `identity.gates.${use.gate}` : "identity.gates"} sets ${base ? "none of them" : `no entry for it`} at base, so a change can edit ${missing.length === 1 ? "it" : "them"} for its own run; declare ${base ? "them" : `identity.gates.${use.gate}`} in chant.workspace.json`,
+              pointer: base ? base.pointer : "/identity",
+              entity: use.gate,
+              treeFile: path,
+              line: 1,
+              column: 1,
+            });
+          }
+        }
+      }
+      return out;
+    },
+  },
+];

package/src/workspace/checks/links.ts

@@ -22,6 +22,9 @@
  * Links a kind's reader finds in a member's own files (#3932), such as a dbt
  * project's sources, are checked by WSP093 to WSP095 like declared ones, and
  * their findings name the member's file and line instead of the declaration.
+ * Links a member's lexicon reads from its declarations (#4397), such as the
+ * tables an otel `clickhouse` exporter writes, are checked the same way, with
+ * the reader named `lexicon <name>`.
  */
 
 import type { WorkspaceCheck, WorkspaceCheckContext, WorkspaceDiagnostic } from "../checks";
@@ -33,11 +36,19 @@ import { DEFAULT_LINK_KIND, LINK_KINDS, TELEMETRY_LINK_KIND, linkTargetProblem,
 const tables = new WeakMap<WorkspaceCheckContext, LinkTableRow[]>();
 const reads = new WeakMap<WorkspaceCheckContext, Map<string, KindLinkRead>>();
 
-/** What each member's kind reader found (#3932), read once per check run. */
+/**
+ * What each member's kind reader found (#3932), and the links its lexicons
+ * read from its declarations (#4397), read once per check run.
+ */
 function kindReads(ctx: WorkspaceCheckContext): Map<string, KindLinkRead> {
   let read = reads.get(ctx);
   if (!read) {
     read = readKindLinks(ctx.declaration, ctx.tree, ctx.kinds);
+    for (const [member, lexicon] of ctx.facts?.lexiconLinks ?? []) {
+      const prev = read.get(member);
+      // resolveLinks names one reader per member; the lexicon's links keep their file and line.
+      read.set(member, prev ? { ...prev, links: [...prev.links, ...lexicon.links], gaps: [...prev.gaps, ...lexicon.gaps] } : lexicon);
+    }
     reads.set(ctx, read);
   }
   return read;