@intentius/chant 0.19.1 → 0.21.0

package/src/lifecycle/git.test.ts

@@ -2,6 +2,7 @@ import { describe, test, expect } from "vitest";
 import { withTestDir } from "@intentius/chant-test-utils";
 import { spawnSync } from "node:child_process";
 import { writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
   writeSnapshot,
@@ -182,12 +183,16 @@ describe("lifecycle/git", () => {
    * `origin`. Returns the clone path; the caller writes snapshots there.
    */
   async function setupClonePair(): Promise<{ clonePath: string; remotePath: string; cleanup: () => Promise<void> }> {
-    const remotePath = join(import.meta.dirname ?? "/tmp", `chant-state-remote-${Date.now()}-${Math.random()}`);
-    const clonePath = join(import.meta.dirname ?? "/tmp", `chant-state-clone-${Date.now()}-${Math.random()}`);
+    // These land in the OS temp dir, never under `import.meta.dirname` — that
+    // would put live git repos inside `packages/core/src`, which other suites
+    // walk recursively while this one creates and deletes them (update.test.ts
+    // -> copyTypeFiles hit ENOENT mid-walk that way).
+    const remotePath = join(tmpdir(), `chant-state-remote-${Date.now()}-${Math.random()}`);
+    const clonePath = join(tmpdir(), `chant-state-clone-${Date.now()}-${Math.random()}`);
     const { mkdir, rm } = await import("node:fs/promises");
     await mkdir(remotePath, { recursive: true });
     git(["init", "-q", "--bare", "-b", "main"], remotePath);
-    git(["clone", "-q", remotePath, clonePath], import.meta.dirname ?? "/tmp");
+    git(["clone", "-q", remotePath, clonePath], tmpdir());
     git(["config", "user.email", "test@chant.dev"], clonePath);
     git(["config", "user.name", "Test"], clonePath);
     writeFileSync(join(clonePath, "README.md"), "fixture\n");
@@ -233,9 +238,9 @@ describe("lifecycle/git", () => {
   test("concurrent write rejected: second push throws StaleLifecycleBranchError", async () => {
     // Simulate two concurrent operators by setting up two clones of the same remote.
     const { clonePath: cloneA, remotePath, cleanup } = await setupClonePair();
-    const cloneB = join(import.meta.dirname ?? "/tmp", `chant-state-clone-b-${Date.now()}-${Math.random()}`);
+    const cloneB = join(tmpdir(), `chant-state-clone-b-${Date.now()}-${Math.random()}`);
     try {
-      git(["clone", "-q", remotePath, cloneB], import.meta.dirname ?? "/tmp");
+      git(["clone", "-q", remotePath, cloneB], tmpdir());
       git(["config", "user.email", "test@chant.dev"], cloneB);
       git(["config", "user.name", "Test"], cloneB);
 

package/src/lifecycle/release-ledger.test.ts

@@ -129,6 +129,34 @@ describe("release-ledger", () => {
       });
     });
 
+    test("records an approver, distinct from the actor, for a gated change (#1035)", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        await appendReleaseRecord(
+          makeInput({ actor: "ci-bot", approver: "alice@corp" }),
+          { cwd: dir },
+        );
+        const { records } = await readReleaseLedger("prod", { cwd: dir });
+        expect(records).toHaveLength(1);
+        expect(records[0].actor).toBe("ci-bot");
+        expect(records[0].approver).toBe("alice@corp");
+        // Separation of duties: approver is not just an echo of actor.
+        expect(records[0].approver).not.toBe(records[0].actor);
+      });
+    });
+
+    test("approver is absent for an ungated change (#1035)", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        await appendReleaseRecord(makeInput(), { cwd: dir });
+        const { records } = await readReleaseLedger("prod", { cwd: dir });
+        expect(records).toHaveLength(1);
+        expect(records[0].approver).toBeUndefined();
+        // The optional approver never blocks a valid ungated record.
+        expect(validateReleaseRecord({ version: 1, ...makeInput() })).toEqual([]);
+      });
+    });
+
     test("release ledger and snapshot coexist on the same orphan branch without clobbering each other", async () => {
       const { writeSnapshot, readSnapshot } = await import("./git");
       await withTestDir(async (dir) => {

package/src/lifecycle/release-ledger.ts

@@ -65,6 +65,17 @@ export interface ReleaseRecord {
   timestamp: string;
   /** Who/what triggered the deploy (a username, a CI actor, a service account). */
   actor: string;
+  /**
+   * Who approved the change at its durable approval gate (#1035). Populated for
+   * a gated change — the same identity the approver supplied when they cleared
+   * the Temporal gate (`chant run signal ... --approver`, carried in the gate
+   * signal payload and thus the workflow history). Optional and omitted for an
+   * ungated change (nothing to approve), so `actor` alone answers "who made
+   * it" while `approver` answers "who approved it" only where a gate exists.
+   * Distinct from `actor`: the approver is deliberately a different person than
+   * the one who triggered the deploy (separation of duties).
+   */
+  approver?: string;
   /** Optional: the archive's own manifest digest (../components/verbs/build-archive.ts's `manifestDigest`), when the caller has it — lets a reader recover full build contents/provenance, not just the promoted image digest. */
   manifestDigest?: string;
 }

package/src/lint/component-checks.ts

@@ -93,15 +93,22 @@ export interface ComponentCheck {
  * error under the pseudo-check id "COMP000" rather than silently dropped —
  * matching how `discoverComponents`'s caller (`../components/cli-support.ts`)
  * always surfaces `result.errors` rather than ignoring them.
+ *
+ * `sandbox` (chant #1051, `chant lint --sandbox`) is threaded straight
+ * through to `discoverComponents` — `chant lint`'s own AST-only rule engine
+ * never executes project source (see this module's own doc comment), but
+ * COMP* checks exist precisely because they need the discovered `Component`
+ * graph, which does mean importing `*.component.ts` files.
  */
 export async function runComponentChecks(
   path: string,
   checks: ComponentCheck[],
   registryContext?: Pick<ComponentCheckContext, "knownKinds" | "rollbackPolicies">,
+  sandbox?: boolean,
 ): Promise<ComponentCheckDiagnostic[]> {
   if (checks.length === 0) return [];
 
-  const result = await discoverComponents(path);
+  const result = await discoverComponents(path, { sandbox });
   const diagnostics: ComponentCheckDiagnostic[] = [];
 
   for (const err of result.errors) {

package/src/lint/rules/evl001-non-literal-expression.ts

@@ -1,6 +1,7 @@
 import * as ts from "typescript";
 import type { LintRule, LintContext, LintDiagnostic } from "../rule";
 import { isInsideCompositeFactory } from "./composite-scope";
+import { checkObjectMember } from "../../fold/subset";
 
 /**
  * EVL001: Non-Literal Expression in Resource Constructor
@@ -9,104 +10,20 @@ import { isInsideCompositeFactory } from "./composite-scope";
  * Allowed: literals, identifiers, property access, object/array literals,
  * template expressions, binary/unary/conditional, as/satisfies casts.
  * Blocked: function calls, method calls, and other dynamic expressions.
+ *
+ * This is a *diagnostic* (chant #1024, epic #1019) — it exists to give a
+ * friendly, early, precisely-located error before synthesis, over exactly
+ * the same subset definition `fold()` (the actual enforcement layer,
+ * {@link "../../fold/fold"}) uses to decide what it can reduce. Both import
+ * the single classifier in {@link "../../fold/subset"}
+ * ({@link checkObjectMember}) so a construct flagged here is exactly a
+ * construct `fold()` rejects, and vice versa — see that module's doc
+ * comment for the few environment-dependent exceptions (identifier
+ * resolution, intrinsic tag registration, spread-source runtime type,
+ * `&&`/`||`/`??`/`? :` short-circuit laziness) that can't be unified
+ * through shape alone.
  */
 
-function isStaticallyEvaluable(node: ts.Node): boolean {
-  // Literals
-  if (
-    ts.isStringLiteral(node) ||
-    ts.isNumericLiteral(node) ||
-    ts.isNoSubstitutionTemplateLiteral(node) ||
-    node.kind === ts.SyntaxKind.TrueKeyword ||
-    node.kind === ts.SyntaxKind.FalseKeyword ||
-    node.kind === ts.SyntaxKind.NullKeyword ||
-    node.kind === ts.SyntaxKind.UndefinedKeyword
-  ) {
-    return true;
-  }
-
-  // Identifiers (variable references)
-  if (ts.isIdentifier(node)) return true;
-
-  // Property access: obj.prop
-  if (ts.isPropertyAccessExpression(node)) {
-    return isStaticallyEvaluable(node.expression);
-  }
-
-  // Element access with static key: obj["key"] or obj[0]
-  if (ts.isElementAccessExpression(node)) {
-    return (
-      isStaticallyEvaluable(node.expression) &&
-      (ts.isStringLiteral(node.argumentExpression) ||
-        ts.isNumericLiteral(node.argumentExpression))
-    );
-  }
-
-  // Object literals — check all property values
-  if (ts.isObjectLiteralExpression(node)) {
-    return node.properties.every((prop) => {
-      if (ts.isPropertyAssignment(prop)) return isStaticallyEvaluable(prop.initializer);
-      if (ts.isShorthandPropertyAssignment(prop)) return true;
-      if (ts.isSpreadAssignment(prop)) return isStaticallyEvaluable(prop.expression);
-      return false;
-    });
-  }
-
-  // Array literals — check all elements
-  if (ts.isArrayLiteralExpression(node)) {
-    return node.elements.every((el) => isStaticallyEvaluable(el));
-  }
-
-  // Template expressions (tagged or untagged)
-  if (ts.isTemplateExpression(node)) return true;
-  if (ts.isTaggedTemplateExpression(node)) return true;
-
-  // Binary expressions: a + b, a ?? b, etc.
-  if (ts.isBinaryExpression(node)) {
-    return isStaticallyEvaluable(node.left) && isStaticallyEvaluable(node.right);
-  }
-
-  // Prefix unary: !x, -x
-  if (ts.isPrefixUnaryExpression(node)) {
-    return isStaticallyEvaluable(node.operand);
-  }
-
-  // Conditional: a ? b : c
-  if (ts.isConditionalExpression(node)) {
-    return (
-      isStaticallyEvaluable(node.condition) &&
-      isStaticallyEvaluable(node.whenTrue) &&
-      isStaticallyEvaluable(node.whenFalse)
-    );
-  }
-
-  // Type assertions: x as T, x satisfies T
-  if (ts.isAsExpression(node) || ts.isSatisfiesExpression(node)) {
-    return isStaticallyEvaluable(node.expression);
-  }
-
-  // Parenthesized expression
-  if (ts.isParenthesizedExpression(node)) {
-    return isStaticallyEvaluable(node.expression);
-  }
-
-  // Non-null assertion: x!
-  if (ts.isNonNullExpression(node)) {
-    return isStaticallyEvaluable(node.expression);
-  }
-
-  // Spread element in arrays
-  if (ts.isSpreadElement(node)) {
-    return isStaticallyEvaluable(node.expression);
-  }
-
-  // new Expression (resource constructors) — allowed as property values
-  if (ts.isNewExpression(node)) return true;
-
-  // Everything else (call expressions, etc.) is not statically evaluable
-  return false;
-}
-
 function checkNode(node: ts.Node, context: LintContext, diagnostics: LintDiagnostic[]): void {
   // Skip resource constructors inside Composite() factory callbacks
   if (ts.isNewExpression(node) && !isInsideCompositeFactory(node)) {
@@ -114,20 +31,19 @@ function checkNode(node: ts.Node, context: LintContext, diagnostics: LintDiagnos
       const firstArg = node.arguments[0];
       if (ts.isObjectLiteralExpression(firstArg)) {
         for (const prop of firstArg.properties) {
-          if (ts.isPropertyAssignment(prop)) {
-            if (!isStaticallyEvaluable(prop.initializer)) {
-              const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(
-                prop.initializer.getStart(context.sourceFile),
-              );
-              diagnostics.push({
-                file: context.filePath,
-                line: line + 1,
-                column: character + 1,
-                ruleId: "EVL001",
-                severity: "error",
-                message: `Non-literal expression in resource constructor property — value must be statically evaluable`,
-              });
-            }
+          const violation = checkObjectMember(prop);
+          if (violation) {
+            const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(
+              violation.node.getStart(context.sourceFile),
+            );
+            diagnostics.push({
+              file: context.filePath,
+              line: line + 1,
+              column: character + 1,
+              ruleId: "EVL001",
+              severity: "error",
+              message: `Non-literal expression in resource constructor property — value must be statically evaluable`,
+            });
           }
         }
       }

package/src/lint/rules/evl003-dynamic-property-access.ts

@@ -1,19 +1,28 @@
 import * as ts from "typescript";
 import type { LintRule, LintContext, LintDiagnostic } from "../rule";
+import { isLiteralElementKey } from "../../fold/subset";
 
 /**
  * EVL003: Dynamic Property Access
  *
  * Computed property access (obj[key]) must use a string or numeric literal key.
  * Dynamic keys (variables, expressions) are not statically evaluable.
+ *
+ * Shares its key-shape predicate with `fold()`'s `elementKey()`
+ * ({@link "../../fold/fold"}) via {@link "../../fold/subset"} (#1024) — a
+ * dynamic element-access key is exactly the construct `fold()` rejects with
+ * `FoldError.ruleId === "EVL003"`, and the diagnostic is located at the key
+ * itself (not the whole `obj[key]` access), matching where `fold()`'s
+ * `elementKey()` throws — so a rejection and its EVL003 diagnostic cite the
+ * same position, not just the same rule id.
  */
 
 function checkNode(node: ts.Node, context: LintContext, diagnostics: LintDiagnostic[]): void {
   if (ts.isElementAccessExpression(node)) {
     const arg = node.argumentExpression;
-    if (!ts.isStringLiteral(arg) && !ts.isNumericLiteral(arg)) {
+    if (!isLiteralElementKey(arg)) {
       const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(
-        node.getStart(context.sourceFile),
+        arg.getStart(context.sourceFile),
       );
       diagnostics.push({
         file: context.filePath,

package/src/params.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, test } from "vitest";
+import { params, setBuildParams } from "./params";
+
+describe("params — the shared build-time-parameters object", () => {
+  test("starts empty", () => {
+    setBuildParams({});
+    expect(params).toEqual({});
+  });
+
+  test("setBuildParams mutates the SAME object in place, never rebinds it", () => {
+    const before = params;
+    setBuildParams({ tier: "production", replicas: 3, enabled: true });
+    expect(params).toBe(before);
+    expect(params).toEqual({ tier: "production", replicas: 3, enabled: true });
+  });
+
+  test("a second call fully replaces the previous values (no stale leftover keys)", () => {
+    setBuildParams({ a: "1", b: "2" });
+    setBuildParams({ c: "3" });
+    expect(params).toEqual({ c: "3" });
+  });
+});

package/src/params.ts

@@ -0,0 +1,66 @@
+/**
+ * Build-time parameters — the runtime binding source references (chant #1064,
+ * follow-up to epic #1019's fold work).
+ *
+ * This is deliberately NOT `Parameter` (`lexicons/aws/src/parameter.ts`), which
+ * is a deploy-time CloudFormation parameter: it emits a `Parameters:` block and
+ * resolves when the STACK deploys. A build-time parameter resolves before the
+ * template is even synthesized — its value can change WHICH resources are
+ * produced at all (loomster's `LOOM_TIER` selecting `light` vs `production` vs
+ * `production-ha`), which a deploy-time `Parameter` structurally cannot do.
+ *
+ * Project source never reads `process.env` directly to vary a build — that
+ * reads ambient state at module-evaluation time, which `fold()` correctly
+ * cannot reduce to a value (see ../fold/fold.ts). Instead it imports this
+ * module's `params` object:
+ *
+ * ```ts
+ * import { params } from "@intentius/chant/params";
+ * export const tier = params.tier as Tier;
+ * ```
+ *
+ * `params` is declared, validated (type + optional `enum`), and resolved by
+ * the CLI BEFORE discovery ever touches a project file (../build-params.ts's
+ * `resolveBuildParams`, driven by `chant build --param`/`--params-file`/a
+ * declared `env` mapping/`chant.config.ts`'s `buildParams` defaults). Two
+ * consumers read the resolved values, and both see the identical object:
+ *
+ *  - The FOLD path (../discovery/fold-import.ts's `buildExternals`) recognizes
+ *    a named `params` import resolving to *this* module and substitutes the
+ *    already-resolved values directly, with zero import performed — so
+ *    `params.tier` folds to a LITERAL, not a symbolic node. This is the entire
+ *    point: the value is known at build invocation, so there is nothing left
+ *    to defer.
+ *  - The RUN path (a run-fallback file that imports this module for real)
+ *    gets the exact same values, because `setBuildParams` below is called
+ *    once, in-process, before ANY project file is imported or folded —
+ *    mutating this shared object in place rather than replacing the binding,
+ *    so a live-imported reference always observes the current build's values.
+ */
+
+import type { BuildParamValue } from "./build-params";
+
+export type { BuildParamValue };
+
+/**
+ * The current build's resolved parameter values, keyed by declared name.
+ * Empty until a build populates it via {@link setBuildParams}. Mutated IN
+ * PLACE (never reassigned) so a real `import { params }` in a run-fallback
+ * file — which captures this exact object reference at import time — always
+ * observes whatever the current build resolved, even though the import
+ * happens after this module was first loaded.
+ */
+export const params: Record<string, BuildParamValue> = {};
+
+/**
+ * Replace the shared {@link params} object's contents in place. Called once
+ * per build (../discovery/index.ts's `discover()`), before any project file
+ * is imported or folded, with the CLI/config-resolved values
+ * (../build-params.ts's `resolveBuildParams`). Never called from project
+ * source — this is chant's own build-invocation plumbing, not a public
+ * authoring API.
+ */
+export function setBuildParams(values: Readonly<Record<string, BuildParamValue>>): void {
+  for (const key of Object.keys(params)) delete params[key];
+  Object.assign(params, values);
+}

package/src/provenance.ts

@@ -8,6 +8,12 @@
  * This is entity-level provenance (which file declared it, and which composite
  * expanded it), not a YAML-line source map. It answers "where did this resource
  * come from?", which is the question an agent asks before changing it.
+ *
+ * {@link BuildParamProvenance} (chant #1064) is the other half: not "where did
+ * this ENTITY come from" but "what INPUTS was this whole BUILD invoked with" —
+ * the question ambient `process.env` reads used to answer invisibly. See
+ * ../build-params.ts for declaration/resolution and ../build.ts's
+ * `BuildResult.buildParams` for where a build surfaces it.
  */
 
 const PROVENANCE = Symbol.for("chant.provenance");
@@ -52,3 +58,19 @@ export function setProvenance(entity: object, prov: EntityProvenance): void {
 export function getProvenance(entity: object): EntityProvenance | undefined {
   return (entity as Record<symbol, unknown>)[PROVENANCE] as EntityProvenance | undefined;
 }
+
+/**
+ * One resolved build-time parameter (chant #1064, see ../build-params.ts): its
+ * final value and which source won it, so a build's parameter inputs are
+ * auditable rather than inferred. `source` records precedence, most to least
+ * specific: an explicit `--param`/`--params-file` value beats a declared `env`
+ * mapping, which beats `chant.config.ts`'s `default`.
+ */
+export interface BuildParamProvenance {
+  /** The declared parameter name (a key of `chant.config.ts`'s `buildParams`). */
+  name: string;
+  /** The resolved, type-coerced value actually bound to `params.<name>` for this build. */
+  value: string | number | boolean;
+  /** Which input supplied the value. */
+  source: "cli" | "params-file" | "env" | "default";
+}

package/src/runtime.ts

@@ -54,18 +54,27 @@ export function createResource(
 
 /**
  * Create a property-kind class for a given property type.
+ *
+ * Instances carry DECLARABLE_MARKER/lexicon/entityType/kind at runtime (set
+ * via defineProperty below), so they already satisfy `Declarable` — the
+ * return type just needs to say so. Before this, the signature was
+ * `Record<string, unknown>` with no `Declarable`, so any composite that
+ * returned a property-kind instance as a top-level member only type-checked
+ * by accident: either the caller went through an untyped `require()` (losing
+ * the type entirely) or never assigned the instance where its `Declarable`-ness
+ * was checked statically. See chant #1068.
  */
 export function createProperty(
   type: string,
   lexicon: string,
-): new (props: Record<string, unknown>) => Record<string, unknown> {
+): new (props: Record<string, unknown>) => Declarable & Record<string, unknown> {
   const PropertyClass = function (this: Record<string, unknown>, props: Record<string, unknown>) {
     Object.defineProperty(this, DECLARABLE_MARKER, { value: true, enumerable: false });
     Object.defineProperty(this, "lexicon", { value: lexicon, enumerable: false });
     Object.defineProperty(this, "entityType", { value: type, enumerable: false });
     Object.defineProperty(this, "kind", { value: "property", enumerable: false });
     Object.defineProperty(this, "props", { value: props ?? {}, enumerable: false, configurable: true });
-  } as unknown as new (props: Record<string, unknown>) => Record<string, unknown>;
+  } as unknown as new (props: Record<string, unknown>) => Declarable & Record<string, unknown>;
 
   Object.defineProperty(PropertyClass, "name", { value: type.split(".").pop() ?? type });