@intentius/chant-lexicon-aws 0.13.1 → 0.15.0

package/src/import/live-export.ts

@@ -1,5 +1,6 @@
 import type { ExportedTemplate, ResourceSelector } from "@intentius/chant/lexicon";
 import { hasOwnershipMarker, tagArrayToMap } from "@intentius/chant/ownership";
+import { AWS_TAG_OWNERSHIP_KEYS } from "../ownership";
 import { CFParser } from "./parser";
 
 /**
@@ -30,7 +31,7 @@ export function parseStackTemplate(
       if (selector?.name !== undefined && r.logicalId !== selector.name) return false;
       if (owned) {
         const tags = (r.properties as { Tags?: Array<{ Key?: string; Value?: unknown }> }).Tags;
-        if (!hasOwnershipMarker(tagArrayToMap(tags), "aws-tag")) return false;
+        if (!hasOwnershipMarker(tagArrayToMap(tags), AWS_TAG_OWNERSHIP_KEYS)) return false;
       }
       return true;
     }),

package/src/index.ts

@@ -93,3 +93,8 @@ export type {
 export { generate, writeGeneratedFiles } from "./codegen/generate";
 export { packageLexicon } from "./codegen/package";
 export type { PackageOptions, PackageResult } from "./codegen/package";
+
+// Component/release capabilities — the AWS operational leaves (cfn-deploy,
+// emr-*, code-deploy, …) contributed to core's capability-plugin seam. Core
+// loads `awsCapabilityPlugin` when a project's chant.config lists this lexicon.
+export { awsCapabilityPlugin } from "./components/capability-plugin";

package/src/lint/audit-catalog.ts

@@ -0,0 +1,45 @@
+/**
+ * The aws lexicon's `chant audit` catalog — metadata (title/tier/fix/authority/
+ * category) for the WAW* CloudFormation post-synth rules this lexicon ships.
+ * Contributed to core's aggregate via `awsPlugin.auditCatalog()` (#687, epic
+ * #350); core keeps only the generic catalog machinery + cross-cutting ids.
+ */
+
+import { auditRule, type RuleMeta, type Authority } from "@intentius/chant/audit/catalog";
+
+/** AWS Well-Architected Security Pillar — the authority chant cites for AWS security findings. */
+const AWS_SEC: Authority = {
+  name: "AWS — Security Pillar (Well-Architected)",
+  url: "https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/welcome.html",
+};
+
+/** Every WAW* audit rule's catalog entry. */
+export const awsAuditCatalog: Record<string, RuleMeta> = {
+  WAW010: auditRule("WAW010", "report-only", "guidance", "Redundant DependsOn", "Remove DependsOn already implied by a Ref/GetAtt.", { category: "best-practice" }),
+  WAW011: auditRule("WAW011", "report-only", "guidance", "Deprecated Lambda runtime", "Upgrade to a supported Lambda runtime.", { category: "best-practice" }),
+  WAW013: auditRule("WAW013", "merge-worthy", "guidance", "Child stack exports nothing", "Add stackOutput() exports the parent can reference.", { category: "correctness" }),
+  WAW014: auditRule("WAW014", "report-only", "guidance", "Nested stack outputs never referenced", "Reference the outputs or split into a separate build.", { category: "best-practice" }),
+  WAW015: auditRule("WAW015", "merge-worthy", "guidance", "Circular dependency between nested stacks", "Break the cycle between nested stacks.", { category: "correctness" }),
+  WAW016: auditRule("WAW016", "report-only", "guidance", "Deprecated property", "Replace the deprecated CloudFormation property.", { category: "best-practice" }),
+  WAW017: auditRule("WAW017", "report-only", "guidance", "Missing tags on a taggable resource", "Add tags for cost allocation and compliance.", { category: "best-practice" }),
+  WAW018: auditRule("WAW018", "merge-worthy", "guidance", "S3 bucket missing public access block", "Add a PublicAccessBlockConfiguration blocking all public access.", { authority: [AWS_SEC] }),
+  WAW019: auditRule("WAW019", "merge-worthy", "guidance", "Security group allows unrestricted ingress on a sensitive port", "Restrict the CIDR on SSH/RDP/database ports to known sources.", { authority: [AWS_SEC] }),
+  WAW020: auditRule("WAW020", "merge-worthy", "guidance", "IAM policy uses a wildcard Action", "Scope the policy to specific actions (least privilege).", { authority: [AWS_SEC] }),
+  WAW021: auditRule("WAW021", "merge-worthy", "guidance", "RDS storage not encrypted", "Enable StorageEncrypted for encryption at rest.", { authority: [AWS_SEC] }),
+  WAW022: auditRule("WAW022", "report-only", "guidance", "Lambda has no VpcConfig", "Consider a VpcConfig for network isolation if the function needs VPC resources.", { category: "best-practice" }),
+  WAW023: auditRule("WAW023", "report-only", "guidance", "CloudFront has no WAF web ACL", "Consider attaching a WAF web ACL.", { category: "best-practice" }),
+  WAW024: auditRule("WAW024", "report-only", "guidance", "ALB access logging disabled", "Enable access logging for audit trails.", { category: "best-practice" }),
+  WAW025: auditRule("WAW025", "merge-worthy", "guidance", "SNS topic not encrypted", "Set KmsMasterKeyId for encryption at rest.", { authority: [AWS_SEC] }),
+  WAW026: auditRule("WAW026", "merge-worthy", "guidance", "SQS queue not encrypted", "Enable SqsManagedSseEnabled or set KmsMasterKeyId.", { authority: [AWS_SEC] }),
+  WAW027: auditRule("WAW027", "report-only", "guidance", "DynamoDB point-in-time recovery disabled", "Enable PITR for recovery.", { category: "best-practice" }),
+  WAW028: auditRule("WAW028", "merge-worthy", "guidance", "EBS volume not encrypted", "Enable encryption at rest.", { authority: [AWS_SEC] }),
+  WAW029: auditRule("WAW029", "merge-worthy", "guidance", "Invalid DependsOn target", "Fix the dangling/self DependsOn reference.", { category: "correctness" }),
+  WAW030: auditRule("WAW030", "report-only", "guidance", "Missing DependsOn for a known ordering pattern", "Add the DependsOn the pattern requires.", { category: "best-practice" }),
+  WAW031: auditRule("WAW031", "report-only", "guidance", "EKS Addon missing ServiceAccountRoleArn", "Set ServiceAccountRoleArn (IRSA) for addons that need it.", { category: "best-practice" }),
+  WAW032: auditRule("WAW032", "merge-worthy", "guidance", "EFS transit encryption disabled on Fargate", "Enable transit encryption for the EFS volume.", { authority: [AWS_SEC] }),
+  WAW033: auditRule("WAW033", "merge-worthy", "guidance", "Solr heap exceeds Fargate task memory", "Lower SOLR_HEAP or raise task memory.", { category: "correctness" }),
+  WAW034: auditRule("WAW034", "report-only", "guidance", "Fargate Solr task under-provisioned", "Allocate >= 2048MB for the Solr task.", { category: "best-practice" }),
+  WAW035: auditRule("WAW035", "report-only", "guidance", "Solr container missing nofile ulimit", "Set a nofile ulimit >= 65535.", { category: "best-practice" }),
+  WAW036: auditRule("WAW036", "merge-worthy", "guidance", "Non-ASCII characters in resource properties", "Remove non-ASCII characters rejected at changeset time.", { category: "correctness" }),
+  WAW037: auditRule("WAW037", "merge-worthy", "guidance", "Null values in resource properties", "Fix the invalid AttrRef producing null property values.", { category: "correctness" }),
+};

package/src/lsp/completions.test.ts

@@ -46,7 +46,7 @@ describe("awsCompletions", () => {
     }
   });
 
-  test("limits results to 50", () => {
+  test("caps the unfiltered `new ` dump", () => {
     const ctx = makeCtx({
       linePrefix: "const x = new ",
       wordAtCursor: "",
@@ -55,7 +55,9 @@ describe("awsCompletions", () => {
     });
 
     const items = awsCompletions(ctx);
-    expect(items.length).toBeLessThanOrEqual(50);
+    // Bare `new ` (no prefix) returns a bounded sample; a typed prefix returns
+    // every match so common resources aren't truncated (#600).
+    expect(items.length).toBeLessThanOrEqual(100);
   });
 
   test("returns empty for non-matching context", () => {

package/src/op/activities/floci.test.ts

@@ -0,0 +1,67 @@
+import { describe, test, expect } from "vitest";
+import {
+  flociRunCommand,
+  flociRmCommand,
+  flociExistsCommand,
+  flociHealthUrl,
+  flociEnv,
+  isFlociReady,
+} from "./floci";
+
+describe("flociRunCommand (#704)", () => {
+  test("minimal — defaults name/port/image, no docker socket", () => {
+    expect(flociRunCommand({})).toBe(
+      "docker run -d --rm --name chant-floci -p 4566:4566 floci/floci:latest",
+    );
+  });
+
+  test("custom name, port, and image", () => {
+    const cmd = flociRunCommand({ name: "floci-e2e", port: 4599, image: "floci/floci:1.5.30" });
+    expect(cmd).toContain("--name floci-e2e");
+    expect(cmd).toContain("-p 4599:4566");
+    expect(cmd.endsWith("floci/floci:1.5.30")).toBe(true);
+  });
+
+  test("dockerSocket mounts the socket before the image (for the ECR backing registry)", () => {
+    const cmd = flociRunCommand({ dockerSocket: true });
+    expect(cmd).toContain("-v /var/run/docker.sock:/var/run/docker.sock");
+    // socket flag precedes the trailing image arg
+    expect(cmd.indexOf("/var/run/docker.sock")).toBeLessThan(cmd.indexOf("floci/floci"));
+  });
+});
+
+describe("flociRmCommand / flociExistsCommand (#704)", () => {
+  test("rm force-removes the container", () => {
+    expect(flociRmCommand("chant-floci")).toBe("docker rm -f chant-floci");
+  });
+
+  test("exists checks a running container by name", () => {
+    expect(flociExistsCommand("chant-floci")).toBe("docker ps -q -f name=chant-floci");
+  });
+});
+
+describe("flociHealthUrl / flociEnv (#704)", () => {
+  test("health url targets the localstack-compatible endpoint on the host port", () => {
+    expect(flociHealthUrl(4599)).toBe("http://localhost:4599/_localstack/health");
+  });
+
+  test("env points the aws CLI at the endpoint with test creds", () => {
+    expect(flociEnv(4566, "us-east-1")).toEqual({
+      AWS_ENDPOINT_URL: "http://localhost:4566",
+      AWS_ACCESS_KEY_ID: "test",
+      AWS_SECRET_ACCESS_KEY: "test",
+      AWS_REGION: "us-east-1",
+    });
+  });
+});
+
+describe("isFlociReady (#704)", () => {
+  test("true when the health body names the required service", () => {
+    const body = '{"services": {"s3": "available", "cloudformation": "available"}}';
+    expect(isFlociReady(body, "cloudformation")).toBe(true);
+  });
+
+  test("false before the service appears", () => {
+    expect(isFlociReady('{"services": {"s3": "available"}}', "cloudformation")).toBe(false);
+  });
+});

package/src/op/activities/floci.ts

@@ -0,0 +1,149 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { safeHeartbeat, sleep } from "@intentius/chant/op";
+
+const execAsync = promisify(exec);
+
+const DEFAULT_NAME = "chant-floci";
+const DEFAULT_PORT = 4566;
+const DEFAULT_IMAGE = "floci/floci:latest";
+const DEFAULT_REGION = "us-east-1";
+const DEFAULT_READY_SERVICE = "cloudformation";
+
+export interface FlociUpArgs {
+  /** Container name. Default: `chant-floci`. */
+  name?: string;
+  /** Host port mapped to the emulator's `:4566`. Default: `4566`. */
+  port?: number;
+  /** Floci image. Default: `floci/floci:latest`. */
+  image?: string;
+  /** Mount the docker socket — Floci needs it for the ECR backing registry. Default: `false`. */
+  dockerSocket?: boolean;
+  /** `AWS_REGION` exported for subsequent steps. Default: `us-east-1`. */
+  region?: string;
+  /** Service to wait for in `/_localstack/health`. Default: `cloudformation`. */
+  readyService?: string;
+  /** Readiness timeout in ms. Default: `60000`. */
+  timeoutMs?: number;
+  /** Health poll interval in ms. Default: `2000`. */
+  intervalMs?: number;
+}
+
+export interface FlociDownArgs {
+  /** Container name to remove. Default: `chant-floci`. */
+  name?: string;
+}
+
+/** `docker ps -q -f name=<name>` — non-empty stdout means the container is running. */
+export function flociExistsCommand(name: string): string {
+  return `docker ps -q -f name=${name}`;
+}
+
+/** Build the `docker run` command that boots Floci. */
+export function flociRunCommand(args: FlociUpArgs): string {
+  const name = args.name ?? DEFAULT_NAME;
+  const port = args.port ?? DEFAULT_PORT;
+  const image = args.image ?? DEFAULT_IMAGE;
+  const parts = ["docker", "run", "-d", "--rm", "--name", name, "-p", `${port}:4566`];
+  if (args.dockerSocket) parts.push("-v", "/var/run/docker.sock:/var/run/docker.sock");
+  parts.push(image);
+  return parts.join(" ");
+}
+
+/** Build the `docker rm -f` command. */
+export function flociRmCommand(name: string): string {
+  return `docker rm -f ${name}`;
+}
+
+/** The Floci health endpoint URL for a host port. */
+export function flociHealthUrl(port: number): string {
+  return `http://localhost:${port}/_localstack/health`;
+}
+
+/** The AWS env vars that point the `aws` CLI / SDK at a local Floci endpoint. */
+export function flociEnv(port: number, region: string): Record<string, string> {
+  return {
+    AWS_ENDPOINT_URL: `http://localhost:${port}`,
+    AWS_ACCESS_KEY_ID: "test",
+    AWS_SECRET_ACCESS_KEY: "test",
+    AWS_REGION: region,
+  };
+}
+
+/** True once the health body reports the required service (e.g. `"cloudformation"`). */
+export function isFlociReady(healthBody: string, service: string): boolean {
+  return healthBody.includes(`"${service}"`);
+}
+
+/**
+ * Boot a local Floci AWS emulator in Docker and point subsequent steps at it.
+ *
+ * Idempotent: reuses a running container of the same name. Waits for the health
+ * endpoint to report `readyService`, then sets `AWS_ENDPOINT_URL` + test creds in
+ * the process environment so a following `nativeApply`/`cfn-deploy` targets the
+ * emulator. Env injection assumes the in-process **local executor**; under a
+ * distributed Temporal worker, pass the endpoint explicitly instead.
+ *
+ * Uses longInfra profile — 20m timeout, heartbeat every poll (the image may pull).
+ */
+export async function flociUp(args: FlociUpArgs, signal?: AbortSignal): Promise<{ endpoint: string }> {
+  const name = args.name ?? DEFAULT_NAME;
+  const port = args.port ?? DEFAULT_PORT;
+  const region = args.region ?? DEFAULT_REGION;
+  const service = args.readyService ?? DEFAULT_READY_SERVICE;
+  const timeoutMs = args.timeoutMs ?? 60_000;
+  const intervalMs = args.intervalMs ?? 2_000;
+
+  let running = false;
+  try {
+    const { stdout } = await execAsync(flociExistsCommand(name), { signal });
+    running = Boolean(stdout.trim());
+  } catch {
+    // `docker ps` failed — assume not running and try to start it.
+  }
+
+  if (running) {
+    console.log(`Floci container "${name}" already running — reusing`);
+  } else {
+    await execAsync(flociRunCommand({ ...args, name, port }), { signal });
+  }
+
+  const url = flociHealthUrl(port);
+  const deadline = Date.now() + timeoutMs;
+  let ready = false;
+  while (Date.now() < deadline) {
+    if (signal?.aborted) throw new Error("flociUp aborted");
+    safeHeartbeat({ step: "flociUp", container: name });
+    try {
+      const { stdout } = await execAsync(`curl -fs ${url}`, { signal });
+      if (isFlociReady(stdout, service)) {
+        ready = true;
+        break;
+      }
+    } catch {
+      // Not up yet (connection refused / non-2xx) — retry.
+    }
+    await sleep(intervalMs, signal);
+  }
+  if (!ready) {
+    throw new Error(`Floci "${name}" did not become ready within ${timeoutMs}ms`);
+  }
+
+  const env = flociEnv(port, region);
+  Object.assign(process.env, env);
+  console.log(`Floci ready on ${env.AWS_ENDPOINT_URL} (service: ${service})`);
+  return { endpoint: env.AWS_ENDPOINT_URL };
+}
+
+/**
+ * Stop and remove the local Floci emulator container. A no-op success when the
+ * container is already gone. Uses fastIdempotent profile — 5m timeout.
+ */
+export async function flociDown(args: FlociDownArgs, signal?: AbortSignal): Promise<void> {
+  const name = args.name ?? DEFAULT_NAME;
+  try {
+    await execAsync(flociRmCommand(name), { signal });
+  } catch {
+    // Already removed (`--rm` on exit, or never started) — treat as success.
+  }
+}

package/src/op/activities/index.ts

@@ -0,0 +1,16 @@
+/**
+ * AWS Op activities — resolved by the core activity registry when a project's
+ * `chant.config.ts` lists the `aws` lexicon. Contributes the local Floci AWS
+ * emulator lifecycle (`flociUp`/`flociDown`).
+ */
+export {
+  flociUp,
+  flociDown,
+  flociRunCommand,
+  flociRmCommand,
+  flociExistsCommand,
+  flociHealthUrl,
+  flociEnv,
+  isFlociReady,
+} from "./floci";
+export type { FlociUpArgs, FlociDownArgs } from "./floci";

package/src/ownership.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, test } from "vitest";
+import { ownershipEntries } from "@intentius/chant/ownership";
+import { AWS_TAG_OWNERSHIP_KEYS } from "./ownership";
+
+describe("AWS_TAG_OWNERSHIP_KEYS", () => {
+  test("uses AWS colon-form tag keys", () => {
+    expect(AWS_TAG_OWNERSHIP_KEYS).toEqual({
+      managedBy: "chant:managed-by",
+      stack: "chant:stack",
+      env: "chant:env",
+    });
+  });
+
+  test("stamps the colon keys via the core ownershipEntries helper", () => {
+    const e = ownershipEntries(AWS_TAG_OWNERSHIP_KEYS, { stack: "billing", env: "prod" });
+    expect(e).toEqual({ "chant:managed-by": "chant", "chant:stack": "billing", "chant:env": "prod" });
+  });
+});

package/src/ownership.ts

@@ -0,0 +1,15 @@
+/**
+ * The aws lexicon's ownership tag convention. AWS tag keys allow `:`, so
+ * chant's markers use the `chant:<name>` form (distinct from the label-based
+ * convention core keeps for k8s/gcp). Core owns the generic stamp/detect logic
+ * (@intentius/chant/ownership); this is the aws-specific key naming it stamps.
+ */
+
+import type { ChannelKeys } from "@intentius/chant/ownership";
+
+/** AWS tag keys for chant's ownership markers. */
+export const AWS_TAG_OWNERSHIP_KEYS: ChannelKeys = {
+  managedBy: "chant:managed-by",
+  stack: "chant:stack",
+  env: "chant:env",
+};

package/src/plugin.ts

@@ -8,6 +8,7 @@ import type { TypeScriptGenerator } from "@intentius/chant/import/generator";
 import type { CompletionContext, CompletionItem, HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
 import { discoverLintRules } from "@intentius/chant/lint/discover";
 import { postSynthChecks as postSynthCheckList } from "./lint/post-synth";
+import { awsAuditCatalog } from "./lint/audit-catalog";
 import { createSkillsLoader, createDiffTool, createCatalogResource } from "@intentius/chant/lexicon-plugin-helpers";
 import { readFileSync } from "fs";
 import { join, dirname } from "path";
@@ -28,6 +29,8 @@ import { awsHover } from "./lsp/hover";
 export const awsPlugin: LexiconPlugin = {
   name: "aws",
   serializer: awsSerializer,
+  // Audit rule metadata for this lexicon's WAW* checks (#687).
+  auditCatalog: () => awsAuditCatalog,
 
   lintRules(): LintRule[] {
     const rulesDir = join(dirname(fileURLToPath(import.meta.url)), "lint", "rules");

package/src/serializer.ts

@@ -2,6 +2,7 @@ import type { Declarable, CoreParameter } from "@intentius/chant/declarable";
 import { isPropertyDeclarable } from "@intentius/chant/declarable";
 import type { Serializer, SerializerResult, SerializeContext } from "@intentius/chant/serializer";
 import { ownershipEntries, type OwnershipMarker } from "@intentius/chant/ownership";
+import { AWS_TAG_OWNERSHIP_KEYS } from "./ownership";
 import type { LexiconOutput } from "@intentius/chant/lexicon-output";
 import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
 import { isChildProject, type ChildProjectInstance } from "@intentius/chant/child-project";
@@ -155,7 +156,7 @@ function serializeToTemplate(
   // on key collisions.
   const defaultTagEntries: TagEntry[] = [];
   if (ownership) {
-    for (const [Key, Value] of Object.entries(ownershipEntries("aws-tag", ownership))) {
+    for (const [Key, Value] of Object.entries(ownershipEntries(AWS_TAG_OWNERSHIP_KEYS, ownership))) {
       defaultTagEntries.push({ Key, Value });
     }
   }