@intentius/chant 0.19.1 → 0.20.0

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";
+}