@composurecdk/core 0.6.0 → 0.7.0

package/dist/construct-id.js

@@ -10,7 +10,7 @@
  * These helpers consolidate that sanitization in one place so every builder
  * in the monorepo applies the same constraints.
  */
-// eslint-disable-next-line no-control-regex
+// eslint-disable-next-line no-control-regex -- the regex must literally match control characters to strip them from construct IDs
 const UNSAFE = /[/\x00-\x1f\x7f]/g;
 /**
  * Return a construct-ID-safe copy of `raw` by replacing unsafe characters

package/dist/construct-id.js.map

@@ -1 +1 @@
-{"version":3,"file":"construct-id.js","sourceRoot":"","sources":["../src/construct-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,4CAA4C;AAC5C,MAAM,MAAM,GAAG,mBAAmB,CAAC;AAEnC;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC7C,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,WAAW,CAAC,GAAG,KAAqD;IAClF,OAAO,KAAK;SACT,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;SACjE,GAAG,CAAC,mBAAmB,CAAC;SACxB,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC"}
+{"version":3,"file":"construct-id.js","sourceRoot":"","sources":["../src/construct-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,kIAAkI;AAClI,MAAM,MAAM,GAAG,mBAAmB,CAAC;AAEnC;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC7C,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,WAAW,CAAC,GAAG,KAAqD;IAClF,OAAO,KAAK;SACT,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;SACjE,GAAG,CAAC,mBAAmB,CAAC;SACxB,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC"}

package/dist/testing.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Asserts that {@link IBuilder.copy | `.copy()`} returns an independent
+ * builder that preserves non-`props` state set via {@link COPY_STATE}.
+ *
+ * The helper is the standard way per-package tests verify each accumulator
+ * a builder holds outside `props`. It executes the following sequence and
+ * asserts the two invariants implied by ADR-0005:
+ *
+ * 1. Build a **baseline**: `factory()` then `configure()`.
+ * 2. Build the **copy**: `factory()`, `configure()`, then `.copy()`.
+ *    Apply `mutate()` to the original *after* the copy is taken.
+ * 3. Build the **original** (now carrying both `configure` and `mutate`).
+ *
+ * Note that the baseline is constructed via `factory()` rather than via
+ * `.copy()` — using `.copy()` would make the helper unable to detect a
+ * broken `[COPY_STATE]`, since both the "baseline" and the "copy" would
+ * drop the same state and still match.
+ *
+ * Then:
+ *
+ * - `inspect(copyResult)` must deep-equal `inspect(baselineResult)` —
+ *   the copy preserved exactly the state that `configure` set up.
+ *   A failure here means `[COPY_STATE]` is missing, incomplete, or buggy.
+ * - `inspect(originalResult)` must deep-not-equal `inspect(baselineResult)` —
+ *   `mutate` actually changed inspectable state. Without this sanity
+ *   check, a no-op `mutate` would let the first assertion pass
+ *   trivially, hiding an isolation bug.
+ *
+ * @param args.factory - Returns a fresh, unconfigured builder. Called
+ *   twice — the helper builds two independent instances so that the
+ *   build calls don't share construct scopes and so the baseline does
+ *   not depend on `.copy()`.
+ * @param args.configure - Applies the state under test (e.g. adds a
+ *   `customAlarm`, configures `#vpc`, appends a `subscription`). Called
+ *   on the baseline and on the original.
+ * @param args.mutate - Applied to the original *after* the copy is taken.
+ *   Must change something the `inspect` callback can see — typically a
+ *   second `configure`-shaped call that adds another item to the
+ *   accumulator under test.
+ * @param args.build - Calls `.build(scope, id)` against a fresh CDK
+ *   scope. Three separate scopes are required (one per build) — return a
+ *   freshly constructed scope each call. Reusing a scope across calls
+ *   surfaces as a CDK duplicate-id error rather than a silent leak.
+ * @param args.inspect - Extracts the slice of the build result whose
+ *   shape depends on the state under test (e.g.
+ *   `result => Object.keys(result.alarms)`).
+ *
+ * @example
+ * ```ts
+ * import { App, Stack } from "aws-cdk-lib";
+ * import { assertCopyPreservesState } from "@composurecdk/core/testing";
+ *
+ * assertCopyPreservesState({
+ *   factory: () => createCertificateBuilder().domainName("example.com"),
+ *   configure: (b) => b.customAlarm({ id: "FirstAlarm", ... }),
+ *   mutate: (b) => b.customAlarm({ id: "SecondAlarm", ... }),
+ *   build: (b) => b.build(new Stack(new App(), "S"), "Cert"),
+ *   inspect: (r) => Object.keys(r.alarms).sort(),
+ * });
+ * ```
+ */
+export declare function assertCopyPreservesState<B extends {
+    copy(): B;
+}, R>(args: {
+    factory: () => B;
+    configure: (builder: B) => void;
+    mutate: (builder: B) => void;
+    build: (builder: B) => R;
+    inspect: (result: R) => unknown;
+}): void;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS;IAAE,IAAI,IAAI,CAAC,CAAA;CAAE,EAAE,CAAC,EAAE,IAAI,EAAE;IACzE,OAAO,EAAE,MAAM,CAAC,CAAC;IACjB,SAAS,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,CAAC;IAChC,MAAM,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,CAAC;IAC7B,KAAK,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;IACzB,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC;CACjC,GAAG,IAAI,CAsCP"}

package/dist/testing.js

@@ -0,0 +1,121 @@
+/**
+ * Asserts that {@link IBuilder.copy | `.copy()`} returns an independent
+ * builder that preserves non-`props` state set via {@link COPY_STATE}.
+ *
+ * The helper is the standard way per-package tests verify each accumulator
+ * a builder holds outside `props`. It executes the following sequence and
+ * asserts the two invariants implied by ADR-0005:
+ *
+ * 1. Build a **baseline**: `factory()` then `configure()`.
+ * 2. Build the **copy**: `factory()`, `configure()`, then `.copy()`.
+ *    Apply `mutate()` to the original *after* the copy is taken.
+ * 3. Build the **original** (now carrying both `configure` and `mutate`).
+ *
+ * Note that the baseline is constructed via `factory()` rather than via
+ * `.copy()` — using `.copy()` would make the helper unable to detect a
+ * broken `[COPY_STATE]`, since both the "baseline" and the "copy" would
+ * drop the same state and still match.
+ *
+ * Then:
+ *
+ * - `inspect(copyResult)` must deep-equal `inspect(baselineResult)` —
+ *   the copy preserved exactly the state that `configure` set up.
+ *   A failure here means `[COPY_STATE]` is missing, incomplete, or buggy.
+ * - `inspect(originalResult)` must deep-not-equal `inspect(baselineResult)` —
+ *   `mutate` actually changed inspectable state. Without this sanity
+ *   check, a no-op `mutate` would let the first assertion pass
+ *   trivially, hiding an isolation bug.
+ *
+ * @param args.factory - Returns a fresh, unconfigured builder. Called
+ *   twice — the helper builds two independent instances so that the
+ *   build calls don't share construct scopes and so the baseline does
+ *   not depend on `.copy()`.
+ * @param args.configure - Applies the state under test (e.g. adds a
+ *   `customAlarm`, configures `#vpc`, appends a `subscription`). Called
+ *   on the baseline and on the original.
+ * @param args.mutate - Applied to the original *after* the copy is taken.
+ *   Must change something the `inspect` callback can see — typically a
+ *   second `configure`-shaped call that adds another item to the
+ *   accumulator under test.
+ * @param args.build - Calls `.build(scope, id)` against a fresh CDK
+ *   scope. Three separate scopes are required (one per build) — return a
+ *   freshly constructed scope each call. Reusing a scope across calls
+ *   surfaces as a CDK duplicate-id error rather than a silent leak.
+ * @param args.inspect - Extracts the slice of the build result whose
+ *   shape depends on the state under test (e.g.
+ *   `result => Object.keys(result.alarms)`).
+ *
+ * @example
+ * ```ts
+ * import { App, Stack } from "aws-cdk-lib";
+ * import { assertCopyPreservesState } from "@composurecdk/core/testing";
+ *
+ * assertCopyPreservesState({
+ *   factory: () => createCertificateBuilder().domainName("example.com"),
+ *   configure: (b) => b.customAlarm({ id: "FirstAlarm", ... }),
+ *   mutate: (b) => b.customAlarm({ id: "SecondAlarm", ... }),
+ *   build: (b) => b.build(new Stack(new App(), "S"), "Cert"),
+ *   inspect: (r) => Object.keys(r.alarms).sort(),
+ * });
+ * ```
+ */
+export function assertCopyPreservesState(args) {
+    const { factory, configure, mutate, build, inspect } = args;
+    const baseline = factory();
+    configure(baseline);
+    const baselineState = inspect(build(baseline));
+    const original = factory();
+    configure(original);
+    if (typeof original.copy !== "function") {
+        throw new Error("assertCopyPreservesState: builder returned by `factory` has no `.copy()` method. " +
+            "Pass a builder produced by `Builder()` / `taggedBuilder()` from `@composurecdk/core` / `@composurecdk/cloudformation`.");
+    }
+    const copy = original.copy();
+    mutate(original);
+    const originalState = inspect(build(original));
+    const copyState = inspect(build(copy));
+    if (deepEqual(originalState, baselineState)) {
+        throw new Error("assertCopyPreservesState: `mutate` did not change inspectable state on the original — " +
+            "the test cannot detect a leak through `.copy()`. Make `mutate` and `inspect` cover " +
+            "the same accumulator.\n" +
+            `  baseline: ${format(baselineState)}\n` +
+            `  original: ${format(originalState)}`);
+    }
+    if (!deepEqual(copyState, baselineState)) {
+        throw new Error("assertCopyPreservesState: `.copy()` did not preserve state set by `configure`. " +
+            "The builder is missing, incomplete, or has a buggy `[COPY_STATE]` hook (see ADR-0005).\n" +
+            `  baseline: ${format(baselineState)}\n` +
+            `  copy:     ${format(copyState)}`);
+    }
+}
+function deepEqual(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== "object" || a === null)
+        return false;
+    if (typeof b !== "object" || b === null)
+        return false;
+    if (Array.isArray(a)) {
+        if (!Array.isArray(b) || a.length !== b.length)
+            return false;
+        return a.every((item, i) => deepEqual(item, b[i]));
+    }
+    if (Array.isArray(b))
+        return false;
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    const bRec = b;
+    return aKeys.every((k) => Object.prototype.hasOwnProperty.call(bRec, k) &&
+        deepEqual(a[k], bRec[k]));
+}
+function format(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@composurecdk/core",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Composable CDK component system — lifecycle, dependency resolution, and builder pattern",
   "repository": {
     "type": "git",
@@ -13,6 +13,10 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./testing": {
+      "import": "./dist/testing.js",
+      "types": "./dist/testing.d.ts"
     }
   },
   "files": [