@liflig/cdk-snapshot 1.0.2 → 1.1.0

package/README.md

@@ -25,7 +25,8 @@ npm install --save-dev @liflig/cdk-snapshot
 pnpm add -D @liflig/cdk-snapshot
 ```
 
-The package is ESM. Under Jest that needs configuration, see [Jest](#jest).
+The package is ESM, with a CommonJS build of the root and Jest entry points for
+CommonJS Jest projects.
 
 ## Usage
 
@@ -96,16 +97,17 @@ test("my stack", () => {
 });
 ```
 
-Jest loads this package as ESM, which it does only with its ESM support enabled:
+Instead of importing it in each test file, the entry point can be listed once in
+`setupFilesAfterEnv`.
+
+A CommonJS test file, including one ts-jest or babel-jest compiles to CommonJS, loads the
+CommonJS build and needs no configuration. An ESM test file loads the ESM build, and
+needs Jest's ESM support enabled as any ESM test file does:
 
 ```sh
 NODE_OPTIONS=--experimental-vm-modules jest
 ```
 
-A CommonJS test file additionally needs Node 24.9 or later, where Jest can `require()` an
-ESM package. Below that, the test file has to be ESM or go through a transform that
-compiles the package to CommonJS.
-
 The Jest entry point uses the global `expect`, so it throws on import if Jest is
 configured with `injectGlobals: false`.
 
@@ -205,15 +207,17 @@ make ci      # what the CI workflow runs: refuses a stale lockfile, fails on an
 ```
 
 `make snapshots` regenerates the unit snapshots plus the shared fixture under all four
-runners, which `test/compat.test.ts` then compares against each other.
+runners, Jest once as ESM and once as CommonJS, which `test/compat.test.ts` then compares
+against each other.
 
 `make compat-check` runs only the four runners and fails if their snapshots changed. CI
 runs it on the oldest Node that `engines` in `package.json` allows.
 
 ## Migrating from jest-cdk-snapshot
 
-Change the import. Call sites and `.snap` files stay as they are, since the options, their
-defaults and the serialization all match.
+Change the import, or the `setupFilesAfterEnv` entry. Call sites and `.snap` files stay
+as they are, since the options, their defaults and the serialization all match, and the
+Jest configuration stays as it is, CommonJS or ESM.
 
 ```diff
 -import "jest-cdk-snapshot"
@@ -224,9 +228,6 @@ Verified against two public CDK libraries, liflig-cdk and cdk-cloudfront-auth: e
 existing snapshot passes under `jest --ci`, and a forced `--updateSnapshot` rewrites
 nothing.
 
-Jest now has to run with ESM support enabled, since this package is ESM — see
-[Jest](#jest).
-
 One option is gone. `yaml` is not supported, so a project snapshotting YAML has to
 regenerate as JSON.
 

package/lib/cjs/index.d.ts

@@ -0,0 +1,14 @@
+import type { Stack } from "aws-cdk-lib";
+import type { CdkTemplateOptions } from "./options.js";
+export type { CdkSnapshotOptions, CdkTemplateOptions } from "./options.js";
+export { anyObject } from "./placeholder.js";
+/**
+ * Synthesizes `stack` to a CloudFormation template with deployment noise
+ * removed, ready to hand to a snapshot assertion.
+ *
+ * The stack is left untouched, so it can be synthesized again with different
+ * options.
+ *
+ * Bun users should import this from `@liflig/cdk-snapshot/bun` instead.
+ */
+export declare function cdkTemplate(stack: Stack, options?: CdkTemplateOptions): Record<string, unknown>;

package/lib/cjs/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.anyObject = void 0;
+exports.cdkTemplate = cdkTemplate;
+const assertions_1 = require("aws-cdk-lib/assertions");
+const normalize_js_1 = require("./normalize.js");
+var placeholder_js_1 = require("./placeholder.js");
+Object.defineProperty(exports, "anyObject", { enumerable: true, get: function () { return placeholder_js_1.anyObject; } });
+/**
+ * Synthesizes `stack` to a CloudFormation template with deployment noise
+ * removed, ready to hand to a snapshot assertion.
+ *
+ * The stack is left untouched, so it can be synthesized again with different
+ * options.
+ *
+ * Bun users should import this from `@liflig/cdk-snapshot/bun` instead.
+ */
+function cdkTemplate(stack, options = {}) {
+    return (0, normalize_js_1.normalize)(assertions_1.Template.fromStack(stack).toJSON(), options);
+}

package/lib/cjs/jest.d.ts

@@ -0,0 +1,10 @@
+import type { CdkSnapshotOptions } from "./options.js";
+export { cdkTemplate } from "./index.js";
+export type { CdkSnapshotOptions, CdkTemplateOptions } from "./options.js";
+declare global {
+    namespace jest {
+        interface Matchers<R, T = {}> {
+            toMatchCdkSnapshot(options?: CdkSnapshotOptions): R;
+        }
+    }
+}

package/lib/cjs/jest.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cdkTemplate = void 0;
+const index_js_1 = require("./index.js");
+const matcher_js_1 = require("./matcher.js");
+var index_js_2 = require("./index.js");
+Object.defineProperty(exports, "cdkTemplate", { enumerable: true, get: function () { return index_js_2.cdkTemplate; } });
+(0, matcher_js_1.registerCdkMatcher)((0, matcher_js_1.requireExpect)("Jest", globalThis.expect), index_js_1.cdkTemplate);

package/lib/cjs/matcher.d.ts

@@ -0,0 +1,29 @@
+import type { Stack } from "aws-cdk-lib";
+import type { CdkTemplateOptions } from "./options.js";
+/** The part of a runner's `expect` this matcher relies on. */
+export interface ExpectLike {
+    (actual: unknown): {
+        toMatchSnapshot(propertyMatchers?: Record<string, unknown>): void;
+    };
+    extend(matchers: Record<string, unknown>): void;
+    /** Jest and Vitest track assertion calls here; Bun has neither method. */
+    getState?(): {
+        assertionCalls: number;
+    };
+    setState?(state: {
+        assertionCalls: number;
+    }): void;
+}
+export type TemplateFn = (stack: Stack, options?: CdkTemplateOptions) => Record<string, unknown>;
+/**
+ * Registers `toMatchCdkSnapshot` on the runner's `expect`.
+ *
+ * The matcher delegates to the runner's own snapshot assertion, so snapshots
+ * keep the naming and format that runner already produces.
+ */
+export declare function registerCdkMatcher(expect: ExpectLike, cdkTemplate: TemplateFn): void;
+/**
+ * Narrows the `expect` a runner injected to the shape the matcher needs, or
+ * explains what to do when the runner injected nothing.
+ */
+export declare function requireExpect(runner: string, injected: unknown): ExpectLike;

package/lib/cjs/matcher.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerCdkMatcher = registerCdkMatcher;
+exports.requireExpect = requireExpect;
+/**
+ * Registers `toMatchCdkSnapshot` on the runner's `expect`.
+ *
+ * The matcher delegates to the runner's own snapshot assertion, so snapshots
+ * keep the naming and format that runner already produces.
+ */
+function registerCdkMatcher(expect, cdkTemplate) {
+    expect.extend({
+        toMatchCdkSnapshot(received, options = {}) {
+            if (this?.isNot) {
+                throw new Error("toMatchCdkSnapshot cannot be negated with `.not`.");
+            }
+            const { propertyMatchers, ...templateOptions } = options;
+            const assertionCalls = expect.getState?.().assertionCalls;
+            const assertion = expect(cdkTemplate(received, templateOptions));
+            if (propertyMatchers) {
+                assertion.toMatchSnapshot(propertyMatchers);
+            }
+            else {
+                assertion.toMatchSnapshot();
+            }
+            // The nested snapshot assertion must not count towards `expect.assertions()`.
+            if (assertionCalls !== undefined)
+                expect.setState?.({ assertionCalls });
+            return { pass: true, message: () => "" };
+        },
+    });
+}
+/**
+ * Narrows the `expect` a runner injected to the shape the matcher needs, or
+ * explains what to do when the runner injected nothing.
+ */
+function requireExpect(runner, injected) {
+    const candidate = injected;
+    if (typeof candidate?.extend !== "function") {
+        throw new Error(`@liflig/cdk-snapshot: ${runner} did not inject a global \`expect\`. Enable global injection, or use cdkTemplate() directly.`);
+    }
+    return candidate;
+}

package/lib/cjs/normalize.d.ts

@@ -0,0 +1,13 @@
+import type { CdkTemplateOptions } from "./options.js";
+/** A synthesized CloudFormation template. */
+export type Template = Record<string, any>;
+/**
+ * Returns a copy of `template` with the configured normalizations applied. The
+ * argument is left untouched: `Template.fromStack` hands out the assembly's
+ * cached template object, so mutating it would corrupt every later assertion
+ * on the same stack.
+ *
+ * Step order is significant: earlier steps can remove structures that later
+ * ones inspect.
+ */
+export declare function normalize(template: Template, options?: CdkTemplateOptions): Template;

package/lib/cjs/normalize.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalize = normalize;
+const placeholder_js_1 = require("./placeholder.js");
+const currentVersionRegex = /^(.+CurrentVersion[0-9A-F]{8})[0-9a-f]{32}$/;
+const pipelineCdkAssetsRegex = /cdk-assets\s+--path\s+\\"([^\\/]+)\/.+?assets\.json\\"\s+--verbose\s+publish\s+\\"(.+?)\\"/g;
+const assetDestinationRegex = /:(.*?)(?:-[0-9a-f]{8})?$/;
+const maskedVersionSuffix = "x".repeat(32);
+/**
+ * Returns a copy of `template` with the configured normalizations applied. The
+ * argument is left untouched: `Template.fromStack` hands out the assembly's
+ * cached template object, so mutating it would corrupt every later assertion
+ * on the same stack.
+ *
+ * Step order is significant: earlier steps can remove structures that later
+ * ones inspect.
+ */
+function normalize(template, options = {}) {
+    const { ignoreAssets = false, ignoreBootstrapVersion = true, ignoreCurrentVersion = false, ignoreMetadata = false, ignoreTags = false, ignorePipelineAssets = false, subsetResourceTypes, subsetResourceKeys, assetPlaceholder = placeholder_js_1.anyObject, } = options;
+    const result = structuredClone(template);
+    if (ignoreBootstrapVersion)
+        stripBootstrapVersion(result);
+    if (ignoreAssets)
+        stripAssets(result, assetPlaceholder);
+    if (ignoreCurrentVersion)
+        maskCurrentVersions(result);
+    if (ignorePipelineAssets)
+        maskPipelineAssets(result);
+    if (subsetResourceTypes) {
+        keepResources(result, (_key, resource) => subsetResourceTypes.includes(resource?.Type));
+    }
+    if (subsetResourceKeys) {
+        keepResources(result, (key) => subsetResourceKeys.includes(key));
+    }
+    if (ignoreMetadata)
+        stripMetadata(result);
+    if (ignoreTags)
+        stripTags(result);
+    return result;
+}
+function stripBootstrapVersion(template) {
+    const { Parameters, Rules } = template;
+    if (Parameters) {
+        delete Parameters.BootstrapVersion;
+        if (Object.keys(Parameters).length === 0)
+            delete template.Parameters;
+    }
+    if (Rules) {
+        delete Rules.CheckBootstrapVersion;
+        if (Object.keys(Rules).length === 0)
+            delete template.Rules;
+    }
+}
+function stripAssets(template, placeholder) {
+    if (!template.Resources)
+        return;
+    if (template.Parameters) {
+        template.Parameters = placeholder;
+    }
+    for (const resource of Object.values(template.Resources)) {
+        const properties = resource?.Properties;
+        if (!properties)
+            continue;
+        if (properties.Code) {
+            properties.Code = placeholder;
+        }
+        for (const definition of properties.ContainerDefinitions ?? []) {
+            definition.Image = placeholder;
+        }
+    }
+}
+function maskCurrentVersions(tree) {
+    transformStrings(tree, (value) => {
+        const match = currentVersionRegex.exec(value);
+        return match ? `${match[1]}${maskedVersionSuffix}` : value;
+    });
+}
+/**
+ * `cdk-assets ... publish "<hash>:<account>-<region>-<suffix>"` — the hash and
+ * the 8-hex suffix follow the asset's content, the account and region do not.
+ * CDK versions before the suffix emit `<hash>:<account>-<region>`.
+ */
+function maskPipelineAssets(tree) {
+    transformStrings(tree, (value) => value.replace(pipelineCdkAssetsRegex, (_match, assemblyDir, asset) => {
+        const destination = assetDestinationRegex.exec(asset)?.[1] || "<ASSET_ID>";
+        return `cdk-assets --path "<${assemblyDir}>" --verbose publish "${destination}"`;
+    }));
+}
+/** Rewrites every string in `tree`, object keys included, in place. */
+function transformStrings(tree, transform) {
+    if (tree == null || typeof tree !== "object")
+        return;
+    if (Array.isArray(tree)) {
+        for (let i = 0; i < tree.length; i++) {
+            const value = tree[i];
+            if (typeof value === "string") {
+                tree[i] = transform(value);
+            }
+            else {
+                transformStrings(value, transform);
+            }
+        }
+        return;
+    }
+    const record = tree;
+    for (const [key, value] of Object.entries(record)) {
+        const newKey = transform(key);
+        if (newKey !== key) {
+            record[newKey] = value;
+            delete record[key];
+        }
+        if (typeof value === "string") {
+            record[newKey] = transform(value);
+        }
+        else {
+            transformStrings(value, transform);
+        }
+    }
+}
+function keepResources(template, keep) {
+    if (!template.Resources)
+        return;
+    for (const [key, resource] of Object.entries(template.Resources)) {
+        if (!keep(key, resource)) {
+            delete template.Resources[key];
+        }
+    }
+}
+function stripMetadata(template) {
+    delete template.Metadata;
+    for (const resource of Object.values(template.Resources ?? {})) {
+        delete resource?.Metadata;
+    }
+}
+function stripTags(template) {
+    for (const resource of Object.values(template.Resources ?? {})) {
+        const properties = resource?.Properties;
+        if (properties?.Tags)
+            delete properties.Tags;
+    }
+}

package/lib/cjs/options.d.ts

@@ -0,0 +1,49 @@
+export interface CdkTemplateOptions {
+    /**
+     * Replace every resource's `Code` property, every container definition's
+     * `Image`, and the whole `Parameters` block with
+     * {@link CdkTemplateOptions.assetPlaceholder}.
+     *
+     * Assets elsewhere, such as Lambda layers, keep their hash. A function using
+     * `currentVersion` also needs
+     * {@link CdkTemplateOptions.ignoreCurrentVersion}, since the version's
+     * logical ID hashes the code.
+     */
+    ignoreAssets?: boolean;
+    /**
+     * Drop the CDK-managed `BootstrapVersion` parameter and its check rule.
+     * Defaults to `true`.
+     */
+    ignoreBootstrapVersion?: boolean;
+    /** Mask the content hash suffix on Lambda `CurrentVersion` logical IDs. */
+    ignoreCurrentVersion?: boolean;
+    /** Drop template and resource `Metadata`. */
+    ignoreMetadata?: boolean;
+    /**
+     * Drop each resource's `Tags` property. Tags nested deeper, such as a launch
+     * template's `TagSpecifications`, are kept.
+     */
+    ignoreTags?: boolean;
+    /**
+     * Mask asset paths, IDs and destination suffixes inside CDK Pipelines
+     * `cdk-assets` commands.
+     */
+    ignorePipelineAssets?: boolean;
+    /** Keep only resources of these CloudFormation types. */
+    subsetResourceTypes?: string[];
+    /** Keep only resources with these logical IDs. */
+    subsetResourceKeys?: string[];
+    /**
+     * Token substituted for asset-derived values. Defaults to a matcher
+     * serializing as `Any<Object>`; the Bun entry point overrides it.
+     */
+    assetPlaceholder?: unknown;
+}
+/** {@link CdkTemplateOptions} plus what only the snapshot matcher can apply. */
+export interface CdkSnapshotOptions extends CdkTemplateOptions {
+    /**
+     * Property matchers handed to the runner's snapshot assertion, for values
+     * the normalizations do not cover.
+     */
+    propertyMatchers?: Record<string, unknown>;
+}

package/lib/cjs/options.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/lib/cjs/placeholder.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Stand-in for asset-derived values, which change whenever an asset's content
+ * does.
+ * Serializes as `Any<Object>` so snapshots match across test runners.
+ *
+ * Bun accepts only matchers built by its own `expect`; the Bun entry point
+ * substitutes one.
+ */
+export declare const anyObject: unknown;

package/lib/cjs/placeholder.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.anyObject = void 0;
+/**
+ * Stand-in for asset-derived values, which change whenever an asset's content
+ * does.
+ * Serializes as `Any<Object>` so snapshots match across test runners.
+ *
+ * Bun accepts only matchers built by its own `expect`; the Bun entry point
+ * substitutes one.
+ */
+exports.anyObject = {
+    $$typeof: Symbol.for("jest.asymmetricMatcher"),
+    asymmetricMatch: (actual) => typeof actual === "object" && actual !== null,
+    toString: () => "Any",
+    getExpectedType: () => "Object",
+    toAsymmetricMatcher: () => "Any<Object>",
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liflig/cdk-snapshot",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Normalizes synthesized AWS CDK stacks for snapshot testing",
   "type": "module",
   "license": "MIT",
@@ -28,12 +28,18 @@
     "bun",
     "node-test"
   ],
-  "main": "./lib/index.js",
-  "types": "./lib/index.d.ts",
+  "main": "./lib/cjs/index.js",
+  "types": "./lib/cjs/index.d.ts",
   "exports": {
     ".": {
-      "types": "./lib/index.d.ts",
-      "import": "./lib/index.js",
+      "import": {
+        "types": "./lib/index.d.ts",
+        "default": "./lib/index.js"
+      },
+      "require": {
+        "types": "./lib/cjs/index.d.ts",
+        "default": "./lib/cjs/index.js"
+      },
       "default": "./lib/index.js"
     },
     "./bun": {
@@ -42,8 +48,14 @@
       "default": "./lib/bun.js"
     },
     "./jest": {
-      "types": "./lib/jest.d.ts",
-      "import": "./lib/jest.js",
+      "import": {
+        "types": "./lib/jest.d.ts",
+        "default": "./lib/jest.js"
+      },
+      "require": {
+        "types": "./lib/cjs/jest.d.ts",
+        "default": "./lib/cjs/jest.js"
+      },
       "default": "./lib/jest.js"
     },
     "./node": {
@@ -62,7 +74,7 @@
     "lib/**/*"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && tsc -p tsconfig.cjs.json && echo '{\"type\":\"commonjs\"}' > lib/cjs/package.json",
     "test": "bun test ./test",
     "snapshots": "bun test ./test --update-snapshots",
     "typecheck": "tsc -p tsconfig.check.json",