@intentius/chant 0.124.45 → 0.124.46

package/src/components/pr-env-run.ts

@@ -16,9 +16,11 @@
  * - the report and the note ({@link renderPrEnvNote}).
  *
  * `chant components pr-env` (../cli/handlers/pr-env.ts) runs these with the
- * components adapter and the lexicons' teardown. The ports default to
- * chant/lifecycle in the working directory and the gate ledger there
- * ({@link lifecyclePrEnvPorts}).
+ * components adapter and the lexicons' teardown, and the ports over
+ * chant/lifecycle and the gate ledger in ./pr-env-ports.ts
+ * (`lifecyclePrEnvPorts`). Those ports load the gate and its schema checks,
+ * so they live apart: a product that brings its own ports bundles this
+ * module without them (pr-env-run-bundle.test.ts).
  */
 
 import { spawnSync } from "node:child_process";
@@ -29,19 +31,11 @@ import { withoutForgeTokens } from "../ci-handover";
 import type { ChantConfig } from "../config";
 import type { TeardownCandidate, TeardownHole, TeardownOutcome } from "../lexicon";
 import type { ObservationLexicon } from "../lexicon";
-import type { PrForge } from "../pr-forge";
 import {
   PR_ENV_EXIT,
   PR_ENV_GATE,
-  PR_ENV_LEDGER_DIR,
-  PR_ENV_LEDGER_FILE,
   expired,
   livePrEnvironments,
-  parsePrEnvRecords,
-  prEnvNoteMarker,
-  prEnvStatusContext,
-  prEnvStatusDescription,
-  prEnvStatusState,
   prEnvironmentName,
   renderPrEnvNote,
   teardownComplete,
@@ -425,71 +419,6 @@ export async function prEnvSweep(input: PrEnvSweepInput): Promise<{ exit: number
   return { exit, results };
 }
 
-// ── the ports chant itself uses ────────────────────────────────────────────
-
-/**
- * The note and the `chant/pr-env` status on the forge. A refusal from the
- * forge warns and never fails the run.
- */
-export function forgePrEnvPublisher(forge: PrForge, warn: (message: string) => void = () => {}): (report: PrEnvReport) => Promise<void> {
-  return async (report) => {
-    const { forgePrincipalOf } = await import("../pr-forge");
-    const note = renderPrEnvNote(report, forgePrincipalOf(forge.kind, forge.host, "<your-login>"));
-    if (report.head) {
-      try {
-        await forge.setStatus(report.head, { context: prEnvStatusContext(report.member), state: prEnvStatusState(report), description: prEnvStatusDescription(report), ...(forge.runUrl ? { url: forge.runUrl } : {}) });
-      } catch (err) {
-        warn(`could not set the ${prEnvStatusContext(report.member)} status: ${messageOf(err)}`);
-      }
-    }
-    try {
-      await forge.upsertNote(report.pr, prEnvNoteMarker(report.env, report.member), note);
-    } catch (err) {
-      warn(`could not post the note on #${report.pr}: ${messageOf(err)}`);
-    }
-  };
-}
-
-/**
- * The ports over chant/lifecycle in `cwd` (default the working directory):
- * the records at `_pr-envs/records.jsonl`, appended and pushed, and the gate
- * ledger read without writing a pending fact. With `forge`, the note and
- * status are posted and the sweep asks it whether a pull request is open.
- */
-export function lifecyclePrEnvPorts(opts: { cwd?: string; forge?: PrForge; log?: (line: string) => void; warn?: (message: string) => void } = {}): PrEnvPorts {
-  const at = opts.cwd ? { cwd: opts.cwd } : undefined;
-  const warn = opts.warn ?? (() => {});
-  const forge = opts.forge;
-  return {
-    async readRecords() {
-      const { fetchLifecycle, readBlobFromPath } = await import("../lifecycle/git");
-      await fetchLifecycle(at).catch(() => false);
-      return parsePrEnvRecords(await readBlobFromPath(PR_ENV_LEDGER_DIR, PR_ENV_LEDGER_FILE, at));
-    },
-    async appendRecord(record) {
-      const { appendLedgerLine, fetchLifecycle, pushLifecycleReport } = await import("../lifecycle/git");
-      try {
-        await fetchLifecycle(at).catch(() => false);
-        await appendLedgerLine(PR_ENV_LEDGER_DIR, PR_ENV_LEDGER_FILE, JSON.stringify(record), `Pull request environment ${record.env} ${record.kind} (${record.result})`, at);
-        const pushed = await pushLifecycleReport(at);
-        if (pushed.pushWarning) warn(pushed.pushWarning);
-      } catch (err) {
-        warn(`could not record ${record.env}'s ${record.kind} on chant/lifecycle: ${messageOf(err)}`);
-      }
-    },
-    async decideGate(input) {
-      const { approvalOf, decidePrGate, readOnlyLedger } = await import("./pr-run");
-      const { gitGateLedgerPort } = await import("../op/gate");
-      const approval = approvalOf(await decidePrGate(readOnlyLedger(gitGateLedgerPort(at)), input));
-      return { status: approval.status, ...(approval.approvedBy ? { approvedBy: approval.approvedBy } : {}) };
-    },
-    ...(forge ? { publish: forgePrEnvPublisher(forge, warn) } : {}),
-    ...(forge?.pullRequestState ? { pullRequestState: (pr: number) => forge.pullRequestState!(pr) } : {}),
-    ...(opts.log ? { log: opts.log } : {}),
-    warn,
-  };
-}
-
 // ── a teardown command ─────────────────────────────────────────────────────
 
 /** `ci.prEnvironment.teardown` (#4330): a command that tears down what no lexicon does. */

package/src/components/pr-environment.ts

@@ -39,7 +39,8 @@
  * as a lexicon does.
  */
 
-import { environmentEndpoint, environmentName, isEnvironmentPattern, isOwnershipParamRef, matchesDeclaredEnvironment, resolveOwnershipStack, type ChantConfig, type EnvironmentDeclaration } from "../config";
+import type { ChantConfig } from "../config";
+import { environmentEndpoint, environmentName, isEnvironmentPattern, isOwnershipParamRef, matchesDeclaredEnvironment, resolveOwnershipStack, type EnvironmentDeclaration } from "../config-environments";
 import type { OwnershipMarker } from "../ownership";
 import { executeTeardown, planTeardown, type TeardownPlan, type TeardownPlanEntry, type TeardownReport } from "../lifecycle/teardown";
 import type { ObservationLexicon, TeardownCandidate, TeardownEnumeration, TeardownExecution } from "../lexicon";

package/src/config-environments.ts

@@ -0,0 +1,133 @@
+/**
+ * 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.
+ */
+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;
+}
+
+/** 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,22 @@ 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,
+  environmentName,
+  environmentNames,
+  isEnvironmentPattern,
+  isOwnershipParamRef,
+  matchesDeclaredEnvironment,
+  matchesEnvironmentPattern,
+  resolveOwnershipStack,
+  type EnvironmentDeclaration,
+  type OwnershipEnv,
+} from "./config-environments";
+import { isOwnershipParamRef, resolveOwnershipStack, type EnvironmentDeclaration, type OwnershipEnv } from "./config-environments";
 
 /**
  * Zod schema for ChantConfig validation.
@@ -157,6 +66,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 +212,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 +694,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/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);