@intentius/chant 0.19.0 → 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";
+}

package/src/terraform/adopt-state.test.ts

@@ -55,7 +55,7 @@ describe("adoptFromState", () => {
     expect(types).toContain("aws_s3_bucket");
     expect(types).toContain("aws_sqs_queue");
     expect(types).toEqual([...types].sort());
-    expect(types).not.toContain("aws_instance"); // not yet mapped
+    expect(types).not.toContain("aws_glue_job"); // not yet mapped
   });
 
   test("returns null for a type with no native constructor", () => {

package/src/terraform/aws-resources.test.ts

@@ -27,10 +27,17 @@ describe("AWS carve-out table", () => {
     expect(AWS_CARVE_TYPES.length).toBeGreaterThanOrEqual(20);
   });
 
-  test("every constructor name is unique and non-empty", () => {
-    const ctors = AWS_CARVE_TYPES.map((t) => t.ctor);
-    expect(ctors.every((c) => c.length > 0)).toBe(true);
-    expect(new Set(ctors).size).toBe(ctors.length);
+  test("constructors are non-empty and consistent per native type", () => {
+    // A constructor may be shared by TF aliases for the same native resource
+    // (e.g. aws_lb and aws_alb both → LoadBalancer), but a given native type
+    // must always map to the same constructor.
+    const byNative = new Map<string, string>();
+    for (const t of AWS_CARVE_TYPES) {
+      expect(t.ctor.length).toBeGreaterThan(0);
+      const seen = byNative.get(t.nativeType);
+      if (seen) expect(t.ctor).toBe(seen);
+      else byNative.set(t.nativeType, t.ctor);
+    }
   });
 });
 

package/src/terraform/aws-resources.ts

@@ -108,6 +108,66 @@ export const AWS_CARVE_TYPES: AwsCarveType[] = [
     fields: { name: "LogGroupName", retention_in_days: "RetentionInDays", kms_key_id: "KmsKeyId" }, tags: true },
   { tfType: "aws_cloudwatch_metric_alarm", tier: 2, nativeType: "AWS::CloudWatch::Alarm", ctor: "Alarm", identityAttr: "alarm_name",
     fields: { alarm_name: "AlarmName", comparison_operator: "ComparisonOperator", metric_name: "MetricName", namespace: "Namespace", threshold: "Threshold", evaluation_periods: "EvaluationPeriods", period: "Period", statistic: "Statistic", alarm_description: "AlarmDescription" }, tags: true },
+  { tfType: "aws_cloudwatch_event_rule", tier: 2, nativeType: "AWS::Events::Rule", ctor: "EventRule", identityAttr: "name",
+    fields: { name: "Name", schedule_expression: "ScheduleExpression", event_pattern: json("EventPattern"), description: "Description", state: "State" } },
+
+  // ── Compute (EC2 / ECS / ASG) ──
+  { tfType: "aws_instance", tier: 2, nativeType: "AWS::EC2::Instance", ctor: "Instance",
+    fields: { ami: "ImageId", instance_type: "InstanceType", subnet_id: "SubnetId", key_name: "KeyName", availability_zone: "AvailabilityZone", iam_instance_profile: "IamInstanceProfile" }, tags: true },
+  { tfType: "aws_launch_template", tier: 2, nativeType: "AWS::EC2::LaunchTemplate", ctor: "LaunchTemplate", identityAttr: "name",
+    fields: { name: "LaunchTemplateName" }, tags: true },
+  { tfType: "aws_autoscaling_group", tier: 2, nativeType: "AWS::AutoScaling::AutoScalingGroup", ctor: "AutoScalingGroup", identityAttr: "name",
+    fields: { name: "AutoScalingGroupName", min_size: "MinSize", max_size: "MaxSize", desired_capacity: "DesiredCapacity", vpc_zone_identifier: "VPCZoneIdentifier", health_check_type: "HealthCheckType" } },
+  { tfType: "aws_ecs_cluster", tier: 1, nativeType: "AWS::ECS::Cluster", ctor: "EcsCluster", identityAttr: "name",
+    fields: { name: "ClusterName" }, tags: true },
+  { tfType: "aws_ecs_task_definition", tier: 3, nativeType: "AWS::ECS::TaskDefinition", ctor: "TaskDefinition",
+    fields: { family: "Family", cpu: "Cpu", memory: "Memory", network_mode: "NetworkMode", execution_role_arn: "ExecutionRoleArn", task_role_arn: "TaskRoleArn" }, tags: true },
+  { tfType: "aws_ebs_volume", tier: 1, nativeType: "AWS::EC2::Volume", ctor: "EC2Volume",
+    fields: { availability_zone: "AvailabilityZone", size: "Size", type: "VolumeType", encrypted: "Encrypted", iops: "Iops" }, tags: true },
+
+  // ── Load balancing (ELBv2; aws_alb is a legacy alias) ──
+  { tfType: "aws_lb", tier: 2, nativeType: "AWS::ElasticLoadBalancingV2::LoadBalancer", ctor: "LoadBalancer", identityAttr: "name",
+    fields: { name: "Name", load_balancer_type: "Type", internal: { prop: "Scheme", transform: (v) => (v === true ? "internal" : v === false ? "internet-facing" : v) } }, tags: true },
+  { tfType: "aws_alb", tier: 2, nativeType: "AWS::ElasticLoadBalancingV2::LoadBalancer", ctor: "LoadBalancer", identityAttr: "name",
+    fields: { name: "Name", load_balancer_type: "Type", internal: { prop: "Scheme", transform: (v) => (v === true ? "internal" : v === false ? "internet-facing" : v) } }, tags: true },
+  { tfType: "aws_lb_target_group", tier: 2, nativeType: "AWS::ElasticLoadBalancingV2::TargetGroup", ctor: "TargetGroup", identityAttr: "name",
+    fields: { name: "Name", port: "Port", protocol: "Protocol", vpc_id: "VpcId", target_type: "TargetType" }, tags: true },
+  { tfType: "aws_lb_listener", tier: 2, nativeType: "AWS::ElasticLoadBalancingV2::Listener", ctor: "Listener",
+    fields: { port: "Port", protocol: "Protocol", load_balancer_arn: "LoadBalancerArn" } },
+
+  // ── Databases & cache ──
+  { tfType: "aws_db_instance", tier: 2, nativeType: "AWS::RDS::DBInstance", ctor: "DbInstance", identityAttr: "identifier",
+    fields: { identifier: "DBInstanceIdentifier", engine: "Engine", engine_version: "EngineVersion", instance_class: "DBInstanceClass", allocated_storage: "AllocatedStorage", db_name: "DBName", multi_az: "MultiAZ", storage_encrypted: "StorageEncrypted" }, tags: true },
+  { tfType: "aws_db_subnet_group", tier: 1, nativeType: "AWS::RDS::DBSubnetGroup", ctor: "RDSDBSubnetGroup", identityAttr: "name",
+    fields: { name: "DBSubnetGroupName", description: "DBSubnetGroupDescription", subnet_ids: "SubnetIds" }, tags: true },
+  { tfType: "aws_elasticache_cluster", tier: 2, nativeType: "AWS::ElastiCache::CacheCluster", ctor: "CacheCluster",
+    fields: { engine: "Engine", node_type: "CacheNodeType", num_cache_nodes: "NumCacheNodes", engine_version: "EngineVersion" }, tags: true },
+  { tfType: "aws_elasticache_replication_group", tier: 2, nativeType: "AWS::ElastiCache::ReplicationGroup", ctor: "ReplicationGroup", identityAttr: "replication_group_id",
+    fields: { replication_group_id: "ReplicationGroupId", description: "ReplicationGroupDescription", node_type: "CacheNodeType", engine: "Engine" }, tags: true },
+
+  // ── DNS, CDN & API ──
+  { tfType: "aws_route53_record", tier: 2, nativeType: "AWS::Route53::RecordSet", ctor: "RecordSet",
+    fields: { name: "Name", type: "Type", ttl: "TTL", zone_id: "HostedZoneId", records: "ResourceRecords" } },
+  { tfType: "aws_api_gateway_rest_api", tier: 2, nativeType: "AWS::ApiGateway::RestApi", ctor: "RestApi", identityAttr: "name",
+    fields: { name: "Name", description: "Description" }, tags: true },
+  { tfType: "aws_apigatewayv2_api", tier: 2, nativeType: "AWS::ApiGatewayV2::Api", ctor: "HttpApi", identityAttr: "name",
+    fields: { name: "Name", protocol_type: "ProtocolType", description: "Description" }, tags: true },
+
+  // ── IAM (users/groups), certs & keys ──
+  { tfType: "aws_iam_user", tier: 1, nativeType: "AWS::IAM::User", ctor: "IAMUser", identityAttr: "name",
+    fields: { name: "UserName", path: "Path" }, tags: true },
+  { tfType: "aws_iam_group", tier: 1, nativeType: "AWS::IAM::Group", ctor: "IAMGroup", identityAttr: "name",
+    fields: { name: "GroupName", path: "Path" } },
+  { tfType: "aws_acm_certificate", tier: 2, nativeType: "AWS::CertificateManager::Certificate", ctor: "AcmCertificate", identityAttr: "domain_name",
+    fields: { domain_name: "DomainName", validation_method: "ValidationMethod", subject_alternative_names: "SubjectAlternativeNames" }, tags: true },
+  { tfType: "aws_kms_alias", tier: 1, nativeType: "AWS::KMS::Alias", ctor: "KMSAlias", identityAttr: "name",
+    fields: { name: "AliasName", target_key_id: "TargetKeyId" } },
+
+  // ── Messaging & step functions ──
+  { tfType: "aws_sns_topic_subscription", tier: 2, nativeType: "AWS::SNS::Subscription", ctor: "Subscription",
+    fields: { protocol: "Protocol", endpoint: "Endpoint", topic_arn: "TopicArn" } },
+  { tfType: "aws_sfn_state_machine", tier: 3, nativeType: "AWS::StepFunctions::StateMachine", ctor: "StateMachine", identityAttr: "name",
+    fields: { name: "StateMachineName", role_arn: "RoleArn", type: "StateMachineType" }, tags: true },
 ];
 
 const BY_TYPE = new Map(AWS_CARVE_TYPES.map((t) => [t.tfType, t]));