@intentius/chant 0.124.45 → 0.124.48

package/src/config-environments.ts

@@ -0,0 +1,160 @@
+/**
+ * The pure helpers over a loaded config's `environments` and `ownership`:
+ * names, patterns, endpoints and the ownership stack. ./config.ts re-exports
+ * them. They import nothing at runtime, so ./components/pr-environment.ts and
+ * ./live-endpoint.ts use them without bundling the config loader.
+ */
+
+import type { ChantConfig } from "./config";
+
+/**
+ * One project-declared environment (chant #1166). Historically always a bare
+ * name (`"floci"`); an entry can now instead carry the endpoint that
+ * environment's `--live` reads should target (`{ name: "floci", endpoint:
+ * "http://localhost:4566" }`), so a project pointed at a local emulator is
+ * self-sufficient — no ambient `AWS_ENDPOINT_URL` export required to avoid
+ * silently querying real AWS. See {@link environmentName}, {@link
+ * environmentNames}, {@link environmentEndpoint} below, and
+ * `./live-endpoint.ts`'s `applyLiveEndpoint`, the CLI-side consumer.
+ *
+ * The array's order is the member's promotion order (#4030, see
+ * `./workspace/promotion-order.ts`), and `canary: true` marks a step as the
+ * canary step of that order. The canary is declared and surfaced; chant does
+ * not yet act on it.
+ *
+ * `executor` names the forge and the committed workflow that deploys the
+ * environment (#4402), so a reader such as behold knows a release there runs
+ * through CI rather than a local `chant run`. chant declares and prints it
+ * (`chant workspace graph --composites`); it never dispatches it.
+ */
+export type EnvironmentDeclaration = string | { name: string; endpoint?: string; canary?: boolean; executor?: EnvironmentExecutor };
+
+/** The forges an environment's executor can name (#4402). */
+export const EXECUTOR_FORGES = ["github", "gitlab", "forgejo"] as const;
+
+/** The forge workflow that deploys one environment (#4402). */
+export interface EnvironmentExecutor {
+  forge: (typeof EXECUTOR_FORGES)[number];
+  /** The committed workflow file the forge runs, such as `deploy-prod.yml` under `.github/workflows/`, or `.gitlab-ci.yml`. */
+  workflow: string;
+}
+
+/**
+ * `ownership.env`: a literal environment identity, or a reference to a
+ * declared build parameter whose resolved value becomes the identity (#1396).
+ */
+export type OwnershipEnv = string | { param: string };
+
+/** The declared name of one `environments` entry, whichever form it takes. */
+export function environmentName(entry: EnvironmentDeclaration): string {
+  return typeof entry === "string" ? entry : entry.name;
+}
+
+/**
+ * Every declared environment's name, in `environments` order. `undefined` in,
+ * `undefined` out — mirrors the field itself being optional, so a caller that
+ * already writes `config.environments?.something` can keep doing so:
+ * `environmentNames(config.environments)?.includes(name)`.
+ */
+export function environmentNames(environments: EnvironmentDeclaration[] | undefined): string[] | undefined {
+  return environments?.map(environmentName);
+}
+
+/**
+ * Whether a declared environment name is a glob pattern rather than a literal
+ * (#1221) — it contains at least one `*`.
+ */
+export function isEnvironmentPattern(declaredName: string): boolean {
+  return declaredName.includes("*");
+}
+
+/**
+ * Anchored `*`-glob match (#1221): each `*` in `pattern` matches any run of
+ * characters (possibly empty); everything else matches itself. Deliberately
+ * the whole surface — no `?`, no character classes, no regex. A pattern with
+ * no `*` degenerates to string equality.
+ */
+export function matchesEnvironmentPattern(pattern: string, name: string): boolean {
+  const parts = pattern.split("*");
+  if (parts.length === 1) return pattern === name;
+  const first = parts[0];
+  const last = parts[parts.length - 1];
+  if (!name.startsWith(first)) return false;
+  let cursor = first.length;
+  for (let i = 1; i < parts.length - 1; i++) {
+    const part = parts[i];
+    if (part === "") continue;
+    const at = name.indexOf(part, cursor);
+    if (at === -1) return false;
+    cursor = at + part.length;
+  }
+  return name.length - cursor >= last.length && name.endsWith(last);
+}
+
+/**
+ * Environment-membership test (#1221): is `name` covered by this project's
+ * declared `environments`? A literal entry matches by equality; an entry
+ * containing `*` matches as a glob pattern (`"pr-*"` covers `pr-42`).
+ * Literals are checked first across the whole list, then patterns — so a
+ * name that is declared outright never depends on pattern order. `undefined`
+ * / empty `environments` returns `false`; callers that treat "no declared
+ * environments" as "anything goes" (e.g. {@link unknownEnvError} in
+ * `./env.ts`) guard that case themselves.
+ */
+export function matchesDeclaredEnvironment(
+  environments: EnvironmentDeclaration[] | undefined,
+  name: string,
+): boolean {
+  const names = environmentNames(environments) ?? [];
+  if (names.includes(name)) return true;
+  return names.some((declared) => isEnvironmentPattern(declared) && matchesEnvironmentPattern(declared, name));
+}
+
+/**
+ * The endpoint `name` declares (chant #1166) — `undefined` for a bare-string
+ * entry, an entry with no `endpoint` set, or a name this project doesn't
+ * declare at all. `./live-endpoint.ts`'s `applyLiveEndpoint` is the consumer:
+ * it injects this into the ambient env var each observing lexicon's CLI
+ * shell-out reads (e.g. `AWS_ENDPOINT_URL`), unless that var is already set —
+ * ambient always wins.
+ *
+ * A pattern entry (#1221) can carry an endpoint too: `{ name: "pr-*",
+ * endpoint }` supplies the endpoint for every `pr-<n>` environment. A literal
+ * entry always wins over a pattern — declaring `pr-special` alongside
+ * `pr-*` resolves `pr-special` to the literal entry's endpoint (or none).
+ */
+export function environmentEndpoint(environments: EnvironmentDeclaration[] | undefined, name: string): string | undefined {
+  const found =
+    environments?.find((e) => environmentName(e) === name) ??
+    environments?.find((e) => isEnvironmentPattern(environmentName(e)) && matchesEnvironmentPattern(environmentName(e), name));
+  return found && typeof found !== "string" ? found.endpoint : undefined;
+}
+
+/**
+ * The executor `name` declares (#4402), resolved like {@link
+ * environmentEndpoint}: a literal entry wins over a pattern, and a literal
+ * entry with no executor does not fall through to a pattern's.
+ */
+export function environmentExecutor(environments: EnvironmentDeclaration[] | undefined, name: string): EnvironmentExecutor | undefined {
+  const found =
+    environments?.find((e) => environmentName(e) === name) ??
+    environments?.find((e) => isEnvironmentPattern(environmentName(e)) && matchesEnvironmentPattern(environmentName(e), name));
+  return found && typeof found !== "string" ? found.executor : undefined;
+}
+
+/** Whether an `ownership.env` entry is a build-parameter reference rather than a literal. */
+export function isOwnershipParamRef(env: OwnershipEnv | undefined): env is { param: string } {
+  return typeof env === "object" && env !== null && typeof env.param === "string";
+}
+
+/**
+ * The ownership stack identity alone — `ownership.stack` when marking is on
+ * (no `stack`, or `enabled: false`, means off). For callers that need the
+ * stack and nothing else (a field manager, a prune selector) and so have no
+ * build parameters to resolve `env` against.
+ */
+export function resolveOwnershipStack(config: Pick<ChantConfig, "ownership">): string | undefined {
+  const o = config.ownership;
+  if (!o || !o.stack || o.enabled === false) return undefined;
+  return o.stack;
+}

package/src/config.ts

@@ -14,113 +14,25 @@ import { lexiconNames, pathLexiconRoot, registerLexiconDeclarations, type Lexico
 import { decideConfigSchema, type DecideConfig } from "./op/decide-config";
 import { PublishDeclarationSchema, type PublishDeclaration } from "./lifecycle/publish-declaration";
 
-/**
- * One project-declared environment (chant #1166). Historically always a bare
- * name (`"floci"`); an entry can now instead carry the endpoint that
- * environment's `--live` reads should target (`{ name: "floci", endpoint:
- * "http://localhost:4566" }`), so a project pointed at a local emulator is
- * self-sufficient — no ambient `AWS_ENDPOINT_URL` export required to avoid
- * silently querying real AWS. See {@link environmentName}, {@link
- * environmentNames}, {@link environmentEndpoint} below, and
- * `./live-endpoint.ts`'s `applyLiveEndpoint`, the CLI-side consumer.
- *
- * The array's order is the member's promotion order (#4030, see
- * `./workspace/promotion-order.ts`), and `canary: true` marks a step as the
- * canary step of that order. The canary is declared and surfaced; chant does
- * not yet act on it.
- */
-export type EnvironmentDeclaration = string | { name: string; endpoint?: string; canary?: boolean };
-
-/**
- * `ownership.env`: a literal environment identity, or a reference to a
- * declared build parameter whose resolved value becomes the identity (#1396).
- */
-export type OwnershipEnv = string | { param: string };
-
-/** The declared name of one `environments` entry, whichever form it takes. */
-export function environmentName(entry: EnvironmentDeclaration): string {
-  return typeof entry === "string" ? entry : entry.name;
-}
-
-/**
- * Every declared environment's name, in `environments` order. `undefined` in,
- * `undefined` out — mirrors the field itself being optional, so a caller that
- * already writes `config.environments?.something` can keep doing so:
- * `environmentNames(config.environments)?.includes(name)`.
- */
-export function environmentNames(environments: EnvironmentDeclaration[] | undefined): string[] | undefined {
-  return environments?.map(environmentName);
-}
-
-/**
- * Whether a declared environment name is a glob pattern rather than a literal
- * (#1221) — it contains at least one `*`.
- */
-export function isEnvironmentPattern(declaredName: string): boolean {
-  return declaredName.includes("*");
-}
-
-/**
- * Anchored `*`-glob match (#1221): each `*` in `pattern` matches any run of
- * characters (possibly empty); everything else matches itself. Deliberately
- * the whole surface — no `?`, no character classes, no regex. A pattern with
- * no `*` degenerates to string equality.
- */
-export function matchesEnvironmentPattern(pattern: string, name: string): boolean {
-  const parts = pattern.split("*");
-  if (parts.length === 1) return pattern === name;
-  const first = parts[0];
-  const last = parts[parts.length - 1];
-  if (!name.startsWith(first)) return false;
-  let cursor = first.length;
-  for (let i = 1; i < parts.length - 1; i++) {
-    const part = parts[i];
-    if (part === "") continue;
-    const at = name.indexOf(part, cursor);
-    if (at === -1) return false;
-    cursor = at + part.length;
-  }
-  return name.length - cursor >= last.length && name.endsWith(last);
-}
-
-/**
- * Environment-membership test (#1221): is `name` covered by this project's
- * declared `environments`? A literal entry matches by equality; an entry
- * containing `*` matches as a glob pattern (`"pr-*"` covers `pr-42`).
- * Literals are checked first across the whole list, then patterns — so a
- * name that is declared outright never depends on pattern order. `undefined`
- * / empty `environments` returns `false`; callers that treat "no declared
- * environments" as "anything goes" (e.g. {@link unknownEnvError} in
- * `./env.ts`) guard that case themselves.
- */
-export function matchesDeclaredEnvironment(
-  environments: EnvironmentDeclaration[] | undefined,
-  name: string,
-): boolean {
-  const names = environmentNames(environments) ?? [];
-  if (names.includes(name)) return true;
-  return names.some((declared) => isEnvironmentPattern(declared) && matchesEnvironmentPattern(declared, name));
-}
-
-/**
- * The endpoint `name` declares (chant #1166) — `undefined` for a bare-string
- * entry, an entry with no `endpoint` set, or a name this project doesn't
- * declare at all. `./live-endpoint.ts`'s `applyLiveEndpoint` is the consumer:
- * it injects this into the ambient env var each observing lexicon's CLI
- * shell-out reads (e.g. `AWS_ENDPOINT_URL`), unless that var is already set —
- * ambient always wins.
- *
- * A pattern entry (#1221) can carry an endpoint too: `{ name: "pr-*",
- * endpoint }` supplies the endpoint for every `pr-<n>` environment. A literal
- * entry always wins over a pattern — declaring `pr-special` alongside
- * `pr-*` resolves `pr-special` to the literal entry's endpoint (or none).
- */
-export function environmentEndpoint(environments: EnvironmentDeclaration[] | undefined, name: string): string | undefined {
-  const found =
-    environments?.find((e) => environmentName(e) === name) ??
-    environments?.find((e) => isEnvironmentPattern(environmentName(e)) && matchesEnvironmentPattern(environmentName(e), name));
-  return found && typeof found !== "string" ? found.endpoint : undefined;
-}
+// The environment and ownership helpers that read a config already loaded
+// live in ./config-environments.ts, which loads nothing, so a bundle that
+// needs only them stays clear of the loader below (#4356 follow-up).
+export {
+  environmentEndpoint,
+  environmentExecutor,
+  environmentName,
+  EXECUTOR_FORGES,
+  environmentNames,
+  isEnvironmentPattern,
+  isOwnershipParamRef,
+  matchesDeclaredEnvironment,
+  matchesEnvironmentPattern,
+  resolveOwnershipStack,
+  type EnvironmentDeclaration,
+  type EnvironmentExecutor,
+  type OwnershipEnv,
+} from "./config-environments";
+import { EXECUTOR_FORGES, isOwnershipParamRef, resolveOwnershipStack, type EnvironmentDeclaration, type OwnershipEnv } from "./config-environments";
 
 /**
  * Zod schema for ChantConfig validation.
@@ -131,6 +43,10 @@ const EnvironmentEntrySchema = z.union([
     name: z.string().min(1),
     endpoint: z.string().min(1).optional(),
     canary: z.boolean().optional(),
+    executor: z.object({
+      forge: z.enum(EXECUTOR_FORGES),
+      workflow: z.string().min(1),
+    }).strict().optional(),
   }),
 ]);
 
@@ -157,6 +73,10 @@ export const ChantConfigSchema = z.object({
   build: z.object({
     fold: z.boolean().optional(),
   }).optional(),
+  // Strict like `run`: a misspelt `lint` would leave the gate on with nothing said.
+  graph: z.object({
+    lint: z.enum(["gate", "report"]).optional(),
+  }).strict().optional(),
   buildParams: z.record(
     z.string(),
     z.object({
@@ -299,6 +219,23 @@ export interface ChantConfig {
   /** Lint configuration (rules, extends, overrides, plugins) */
   lint?: LintConfig;
 
+  /**
+   * How `chant graph` treats lint errors (INTENTIUS/behold#919).
+   *
+   * `"gate"` (the default) refuses to emit the entity graph for source that
+   * fails `chant lint`: the graph stands for source chant will build.
+   * `"report"` emits it anyway and carries every lint finding on the IR's
+   * `meta.lint`, for a project that only reads source it did not author. The
+   * reader project `chant workspace graph` writes for a terraform or choudoufu
+   * member sets it, and so does behold's scratch project for a bare Terraform
+   * folder: an error-severity finding there describes the estate, and the
+   * person needs the picture to look at it. A chant older than the key
+   * ignores it and gates as before.
+   */
+  graph?: {
+    lint?: "gate" | "report";
+  };
+
   /**
    * Telemetry attribution (#2558, D22): lexicons that declare workloads stamp
    * resource attributes (`chant.workspace`, `chant.member`, `chant.decl`,
@@ -764,23 +701,6 @@ function warnIfFragmentShadowsProjectConfig(configPath: string): void {
 /** Top-level keys that make a config a *project* config rather than a lint fragment. */
 const PROJECT_CONFIG_KEYS = new Set(Object.keys(ChantConfigSchema.shape).filter((k) => k !== "lint"));
 
-/** Whether an `ownership.env` entry is a build-parameter reference rather than a literal. */
-export function isOwnershipParamRef(env: OwnershipEnv | undefined): env is { param: string } {
-  return typeof env === "object" && env !== null && typeof env.param === "string";
-}
-
-/**
- * The ownership stack identity alone — `ownership.stack` when marking is on
- * (no `stack`, or `enabled: false`, means off). For callers that need the
- * stack and nothing else (a field manager, a prune selector) and so have no
- * build parameters to resolve `env` against.
- */
-export function resolveOwnershipStack(config: ChantConfig): string | undefined {
-  const o = config.ownership;
-  if (!o || !o.stack || o.enabled === false) return undefined;
-  return o.stack;
-}
-
 /**
  * Resolve the `env` half of the ownership marker (#1396). A literal is
  * returned as-is. A `{ param }` reference is looked up in this build's resolved

package/src/gate-decision-bundle.test.ts

@@ -48,6 +48,7 @@ describe("the gate-decision bundle", () => {
       "packages/core/src/op/gate-point.ts",
       "packages/core/src/op/gate-quorum.ts",
       "packages/core/src/op/op-waves.ts",
+      "packages/core/src/wave-blocked.ts",
       "packages/core/src/wave-layout.ts",
       "packages/core/src/workspace/class-data.ts",
       "packages/core/src/workspace/identity-gate-rule.ts",

package/src/gate-decision-identity.test.ts

@@ -218,6 +218,15 @@ describe.skipIf(!hasSshKeygen)("identity.gates read at base, as chant reads it",
       expect(decided.status === "approved" && decided.via === "ledger" ? decided.resolution : null).toEqual(check.satisfied ? check.resolution : null);
     }
   });
+
+  test("a gate's quorum at base, as chant reads it (#4324)", () => {
+    const rules = [{ targets: ["prod"], count: 2, roles: ["platform"] }, { count: 1 }];
+    const { r, base } = setup(() => ({}), { identity: { gates: { ship: { quorum: rules }, deploy: { class: "human" } } } });
+    const here = identityGateAdmissionAt(r.dir, base, "ship")!;
+    expect(here.requirement.quorum).toEqual(rules);
+    expect(here.requirement.quorum).toEqual(gateAdmission(r.dir, "ship", base)!.requirement.quorum);
+    expect(identityGateAdmissionAt(r.dir, base, "deploy")!.requirement).toEqual({ gate: "deploy", class: "human" });
+  });
 });
 
 describe("admitApprover", () => {

package/src/gate-decision.ts

@@ -30,7 +30,10 @@
  * Approval rules (#4290), a quorum as a list of `{ targets, count, roles,
  * notAuthor }`, are judged with `./op/gate-quorum.ts`, re-exported here:
  * {@link trustRolesAt} and {@link gateSignersAt} read what
- * `trustQuorumJudge` judges by, at base.
+ * `trustQuorumJudge` judges by, at base. A product's own review lines
+ * (#4333) become one approval per reviewer with `recordedReviewApprovals`,
+ * and `changeInvolvement` names everyone involved in a change for the
+ * judge to leave out.
  *
  * The module reads the ledger lines and the review it is handed; reading
  * them is the caller's. It imports no TypeScript, esbuild, zod, ajv, lint,
@@ -63,6 +66,7 @@ import { CORE_CLASSES, admitApprover, type ClassGrant, type GateAdmissionRule, t
 import { diskFiles, findInstalledPackage, mergePinClasses, parseClassDataByHand, readClassFiles, type PinClassRead } from "./workspace/class-data";
 import type { GateResolutionRecord, PendingGateRecord } from "./lifecycle/gate-ledger";
 import type { MergedReview } from "./op/gate-review";
+import { quorumProblems as quorumProblemsOf, type GateQuorumSpec as QuorumSpec } from "./op/gate-quorum";
 import type { GateApprovalSource } from "./op/op-waves";
 
 export { GATE_APPROVAL_SOURCES, type GateApprovalSource } from "./op/op-waves";
@@ -124,6 +128,14 @@ export {
   targetGlobMatch,
   trustQuorumJudge,
   UNPROVEN_JUDGE,
+  changeInvolvement,
+  involvedWhy,
+  principalNames,
+  recordedReviewApprovals,
+  recordedReviewOf,
+  requestedByTrailers,
+  type QuorumInvolvement,
+  type RecordedReview,
   type GateQuorumJudge,
   type GateQuorumRule,
   type GateQuorumRuleProgress,
@@ -213,6 +225,11 @@ export function trustRolesAt(repo: string, base: string): Record<string, string[
 export interface IdentityGate {
   gate: string;
   class: string | null;
+  /**
+   * `identity.gates.<gate>.quorum` (#4324): the approval rules an Op gate of
+   * this name takes in place of its own. Absent when the entry sets none.
+   */
+  quorum?: QuorumSpec;
 }
 
 /** The declaration at `base`, parsed, or null when there is none. Throws when it cannot be parsed. */
@@ -228,8 +245,14 @@ function declarationAt(repo: string, base: string): { file: string; value: unkno
 }
 
 function identityGatesOf(declaration: unknown): IdentityGate[] {
-  const gates = (declaration as { identity?: { gates?: Record<string, { class?: unknown } | null> } } | null)?.identity?.gates ?? {};
-  return Object.entries(gates).map(([gate, entry]) => ({ gate, class: typeof entry?.class === "string" ? entry.class : null }));
+  const gates = (declaration as { identity?: { gates?: Record<string, { class?: unknown; quorum?: unknown } | null> } } | null)?.identity?.gates ?? {};
+  return Object.entries(gates).map(([gate, entry]) => {
+    if (entry?.quorum === undefined) return { gate, class: typeof entry?.class === "string" ? entry.class : null };
+    // #4324: a quorum chant would refuse leaves the gate undecidable, as chant's own read does.
+    const [problem] = quorumProblemsOf(entry.quorum, `identity.gates.${gate}.quorum`, { notAuthor: false });
+    if (problem) throw new Error(`chant.workspace.json at base: ${problem.replace(/`/g, "")}, so the gate cannot be decided`);
+    return { gate, class: typeof entry.class === "string" ? entry.class : null, quorum: structuredClone(entry.quorum) as QuorumSpec };
+  });
 }
 
 /**

package/src/graph-detail.ts

@@ -1,4 +1,5 @@
 import type { GraphIR, IRNode, IREdge } from "./graph-ir";
+import { subTemplateRefs } from "./graph-sub-template";
 
 /**
  * Detail tiers — the diagram "detail dial". Each level is a pure IR → IR
@@ -60,13 +61,13 @@ function paintAttrs(attrs: Record<string, unknown>): Record<string, unknown> {
   return out;
 }
 
-/** A `{ $ref: "producer.attribute" }` envelope — a reference, not a property tree. */
+/** A `{ $ref: "producer.attribute" }` or `{ $sub: "..." }` (#4373) envelope — a reference, not a property tree. */
 function isRefEnvelope(v: unknown): boolean {
   return (
     typeof v === "object" &&
     v !== null &&
     !Array.isArray(v) &&
-    typeof (v as { $ref?: unknown }).$ref === "string"
+    (typeof (v as { $ref?: unknown }).$ref === "string" || typeof (v as { $sub?: unknown }).$sub === "string")
   );
 }
 
@@ -271,7 +272,8 @@ function toAttributes(ir: GraphIR): GraphIR {
   return { ...ir, edges };
 }
 
-/** Find the attribute in a `{ $ref: "producer.attribute" }` envelope under attrs. */
+/** Find the attribute in a `{ $ref: "producer.attribute" }` envelope under attrs,
+ * or in a `{ $sub }` envelope's `${producer.attribute}` (#4373). */
 function findRefAttr(attrs: Record<string, unknown>, producer: string): string | undefined {
   let found: string | undefined;
   const visit = (v: unknown): void => {
@@ -288,6 +290,16 @@ function findRefAttr(attrs: Record<string, unknown>, producer: string): string |
         return;
       }
     }
+    const sub = (v as { $sub?: unknown; $vars?: unknown }).$sub;
+    if (typeof sub === "string") {
+      const vars = (v as { $vars?: unknown }).$vars;
+      const bound = new Set(vars && typeof vars === "object" ? Object.keys(vars) : []);
+      const hit = subTemplateRefs(sub, bound).find((r) => r.name === producer && r.attr);
+      if (hit) {
+        found = hit.attr;
+        return;
+      }
+    }
     for (const val of Object.values(v as Record<string, unknown>)) visit(val);
   };
   visit(attrs);