@liflig/cdk-snapshot 1.0.2 → 1.2.0

package/README.md

@@ -6,7 +6,7 @@
 [![license](https://img.shields.io/npm/l/@liflig/cdk-snapshot.svg)](LICENSE)
 
 Snapshot testing for AWS CDK stacks. A stack is synthesized to CloudFormation and
-normalized before it is snapshotted. The CDK bootstrap version is always dropped.
+normalized before it is snapshotted. The CDK bootstrap version is dropped by default.
 Asset hashes, Lambda version suffixes and CDK Pipelines asset IDs change whenever
 an asset's content does; the [options](#options) mask them, so a snapshot fails only
 when the infrastructure itself changed.
@@ -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`.
 
@@ -135,6 +137,7 @@ correct the count.
 | Option | Type | Default | Effect |
 | --- | --- | --- | --- |
 | `ignoreAssets` | `boolean` | `false` | Replaces every `Code` property, every container definition's `Image` and the whole `Parameters` block with `Any<Object>` |
+| `ignoreAssetHashes` | `boolean` | `false` | Replaces the hash of every asset in the app with `<ASSET_HASH>`, wherever it appears |
 | `ignoreBootstrapVersion` | `boolean` | `true` | Drops the `BootstrapVersion` parameter and its check rule |
 | `ignoreCurrentVersion` | `boolean` | `false` | Masks the content hash on Lambda `CurrentVersion` logical IDs and every reference to them |
 | `ignoreMetadata` | `boolean` | `false` | Drops template and resource `Metadata` |
@@ -156,11 +159,29 @@ only if it matches both.
   `Code.fromBucket` key or to a registry image tag such as `nginx:1.27` does not show.
 - Assets outside Lambda `Code` and container images keep their hash: Lambda layers,
   `BucketDeployment` sources, Step Functions and API Gateway definitions read from files,
-  and nested stack templates.
+  and nested stack templates. `ignoreAssetHashes` covers them.
 - A function's `currentVersion` logical ID is a hash over its configuration, code
   included, so a stack that uses it also needs `ignoreCurrentVersion` to stay stable.
 - It does nothing to a template with no `Resources`.
 
+`ignoreAssetHashes` is the precise alternative. It reads the hash of every file and
+container image asset from the asset manifests the app synthesizes, CDK Pipelines stages
+included, and replaces exactly those hashes wherever a string in the template holds one:
+
+```diff
+ "Code": {
+   "S3Bucket": "cdk-hnb659fds-assets-112233445566-eu-west-1",
+-  "S3Key": "9b8fce7ae7f25ef82fdbaf6b72523b99d0875c0c9c826642819fb51f11d9b125.zip",
++  "S3Key": "<ASSET_HASH>.zip",
+ },
+```
+
+Everything else stays visible: the stack's parameters, inline code, registry image tags
+and any hash that belongs to no asset. A function using `currentVersion` still needs
+`ignoreCurrentVersion`, and a CDK Pipeline still needs `ignorePipelineAssets` for its
+destination suffixes, which are not asset hashes. The hashes come from the asset
+manifests that CDK's default synthesizer writes.
+
 `ignoreTags` drops the `Tags` property of each resource. Tags nested deeper stay, such as
 those `Tags.of()` propagates into a launch template's `TagSpecifications`.
 
@@ -174,8 +195,8 @@ its own `expect`.
 
 ## How it works
 
-Everything is built around one pure function, `cdkTemplate`, which turns a stack into a
-normalized template object. Each runner gets a thin adapter that wraps that function in
+Everything is built around one function, `cdkTemplate`, which synthesizes a stack and
+hands the template to a pure normalizer. Each runner gets a thin adapter that wraps that function in
 whatever the runner's own snapshot assertion looks like, so snapshots keep the naming and
 format that runner already produces.
 
@@ -205,15 +226,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 +247,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/assets.d.ts

@@ -0,0 +1,11 @@
+import { type Stack } from "aws-cdk-lib";
+/**
+ * The IDs of every file and container image asset in the cloud assembly
+ * `stack` belongs to, nested assemblies such as CDK Pipelines stages included.
+ * Under CDK's default synthesizer an asset's ID is the hash it is published
+ * under.
+ *
+ * Synthesis is cached per stage, so this reads the assembly the stack's
+ * template came from.
+ */
+export declare function assetHashes(stack: Stack): Set<string>;

package/lib/assets.js

@@ -0,0 +1,39 @@
+import { readFileSync } from "node:fs";
+import { Stage } from "aws-cdk-lib";
+/**
+ * The IDs of every file and container image asset in the cloud assembly
+ * `stack` belongs to, nested assemblies such as CDK Pipelines stages included.
+ * Under CDK's default synthesizer an asset's ID is the hash it is published
+ * under.
+ *
+ * Synthesis is cached per stage, so this reads the assembly the stack's
+ * template came from.
+ */
+export function assetHashes(stack) {
+    const hashes = new Set();
+    const stage = Stage.of(stack);
+    if (stage)
+        collect(stage.synth(), hashes);
+    return hashes;
+}
+// Artifacts are told apart by manifest type rather than instanceof, which
+// fails when the app was built with a different copy of aws-cdk-lib.
+function collect(assembly, hashes) {
+    for (const artifact of assembly.artifacts) {
+        switch (artifact.manifest.type) {
+            case "cdk:asset-manifest": {
+                const { file } = artifact;
+                const { files = {}, dockerImages = {} } = JSON.parse(readFileSync(file, "utf8"));
+                for (const id of Object.keys({ ...files, ...dockerImages })) {
+                    hashes.add(id);
+                }
+                break;
+            }
+            case "cdk:cloud-assembly": {
+                const { nestedAssembly } = artifact;
+                collect(nestedAssembly, hashes);
+                break;
+            }
+        }
+    }
+}

package/lib/cjs/assets.d.ts

@@ -0,0 +1,11 @@
+import { type Stack } from "aws-cdk-lib";
+/**
+ * The IDs of every file and container image asset in the cloud assembly
+ * `stack` belongs to, nested assemblies such as CDK Pipelines stages included.
+ * Under CDK's default synthesizer an asset's ID is the hash it is published
+ * under.
+ *
+ * Synthesis is cached per stage, so this reads the assembly the stack's
+ * template came from.
+ */
+export declare function assetHashes(stack: Stack): Set<string>;

package/lib/cjs/assets.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assetHashes = assetHashes;
+const node_fs_1 = require("node:fs");
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+/**
+ * The IDs of every file and container image asset in the cloud assembly
+ * `stack` belongs to, nested assemblies such as CDK Pipelines stages included.
+ * Under CDK's default synthesizer an asset's ID is the hash it is published
+ * under.
+ *
+ * Synthesis is cached per stage, so this reads the assembly the stack's
+ * template came from.
+ */
+function assetHashes(stack) {
+    const hashes = new Set();
+    const stage = aws_cdk_lib_1.Stage.of(stack);
+    if (stage)
+        collect(stage.synth(), hashes);
+    return hashes;
+}
+// Artifacts are told apart by manifest type rather than instanceof, which
+// fails when the app was built with a different copy of aws-cdk-lib.
+function collect(assembly, hashes) {
+    for (const artifact of assembly.artifacts) {
+        switch (artifact.manifest.type) {
+            case "cdk:asset-manifest": {
+                const { file } = artifact;
+                const { files = {}, dockerImages = {} } = JSON.parse((0, node_fs_1.readFileSync)(file, "utf8"));
+                for (const id of Object.keys({ ...files, ...dockerImages })) {
+                    hashes.add(id);
+                }
+                break;
+            }
+            case "cdk:cloud-assembly": {
+                const { nestedAssembly } = artifact;
+                collect(nestedAssembly, hashes);
+                break;
+            }
+        }
+    }
+}

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,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.anyObject = void 0;
+exports.cdkTemplate = cdkTemplate;
+const assertions_1 = require("aws-cdk-lib/assertions");
+const assets_js_1 = require("./assets.js");
+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 = {}) {
+    const template = assertions_1.Template.fromStack(stack).toJSON();
+    const hashes = options.ignoreAssetHashes
+        ? (0, assets_js_1.assetHashes)(stack)
+        : new Set();
+    return (0, normalize_js_1.normalize)(template, options, hashes);
+}

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,16 @@
+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.
+ *
+ * `assetHashes` are the hashes {@link CdkTemplateOptions.ignoreAssetHashes}
+ * masks, as read from the stack's cloud assembly.
+ */
+export declare function normalize(template: Template, options?: CdkTemplateOptions, assetHashes?: ReadonlySet<string>): Template;

package/lib/cjs/normalize.js

@@ -0,0 +1,155 @@
+"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 assetHashRegex = /(?<![0-9a-f])[0-9a-f]{64}(?![0-9a-f])/g;
+const maskedVersionSuffix = "x".repeat(32);
+const maskedAssetHash = "<ASSET_HASH>";
+/**
+ * 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.
+ *
+ * `assetHashes` are the hashes {@link CdkTemplateOptions.ignoreAssetHashes}
+ * masks, as read from the stack's cloud assembly.
+ */
+function normalize(template, options = {}, assetHashes = new Set()) {
+    const { ignoreAssets = false, ignoreAssetHashes = 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 (ignoreAssetHashes)
+        maskAssetHashes(result, assetHashes);
+    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;
+        }
+    }
+}
+/**
+ * Only a standalone 64-hex run is a candidate, so a longer hex string that
+ * happens to contain an asset hash is left intact.
+ */
+function maskAssetHashes(tree, hashes) {
+    transformStrings(tree, (value) => value.replace(assetHashRegex, (hash) => hashes.has(hash) ? maskedAssetHash : hash));
+}
+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,61 @@
+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;
+    /**
+     * Replace the hash of every asset in the app with `<ASSET_HASH>`, wherever
+     * a string in the template holds it: Lambda code and layers, container
+     * images, `BucketDeployment` sources, nested stack templates, CDK Pipelines
+     * commands. The rest of each value stays, and values that are not assets
+     * are untouched.
+     *
+     * The hashes are read from the asset manifests CDK's default synthesizer
+     * writes. A function using `currentVersion` also needs
+     * {@link CdkTemplateOptions.ignoreCurrentVersion}.
+     */
+    ignoreAssetHashes?: 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/lib/index.js

@@ -1,4 +1,5 @@
 import { Template } from "aws-cdk-lib/assertions";
+import { assetHashes } from "./assets.js";
 import { normalize } from "./normalize.js";
 export { anyObject } from "./placeholder.js";
 /**
@@ -11,5 +12,9 @@ export { anyObject } from "./placeholder.js";
  * Bun users should import this from `@liflig/cdk-snapshot/bun` instead.
  */
 export function cdkTemplate(stack, options = {}) {
-    return normalize(Template.fromStack(stack).toJSON(), options);
+    const template = Template.fromStack(stack).toJSON();
+    const hashes = options.ignoreAssetHashes
+        ? assetHashes(stack)
+        : new Set();
+    return normalize(template, options, hashes);
 }

package/lib/normalize.d.ts

@@ -9,5 +9,8 @@ export type Template = Record<string, any>;
  *
  * Step order is significant: earlier steps can remove structures that later
  * ones inspect.
+ *
+ * `assetHashes` are the hashes {@link CdkTemplateOptions.ignoreAssetHashes}
+ * masks, as read from the stack's cloud assembly.
  */
-export declare function normalize(template: Template, options?: CdkTemplateOptions): Template;
+export declare function normalize(template: Template, options?: CdkTemplateOptions, assetHashes?: ReadonlySet<string>): Template;

package/lib/normalize.js

@@ -2,7 +2,9 @@ import { anyObject } from "./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 assetHashRegex = /(?<![0-9a-f])[0-9a-f]{64}(?![0-9a-f])/g;
 const maskedVersionSuffix = "x".repeat(32);
+const maskedAssetHash = "<ASSET_HASH>";
 /**
  * Returns a copy of `template` with the configured normalizations applied. The
  * argument is left untouched: `Template.fromStack` hands out the assembly's
@@ -11,14 +13,19 @@ const maskedVersionSuffix = "x".repeat(32);
  *
  * Step order is significant: earlier steps can remove structures that later
  * ones inspect.
+ *
+ * `assetHashes` are the hashes {@link CdkTemplateOptions.ignoreAssetHashes}
+ * masks, as read from the stack's cloud assembly.
  */
-export function normalize(template, options = {}) {
-    const { ignoreAssets = false, ignoreBootstrapVersion = true, ignoreCurrentVersion = false, ignoreMetadata = false, ignoreTags = false, ignorePipelineAssets = false, subsetResourceTypes, subsetResourceKeys, assetPlaceholder = anyObject, } = options;
+export function normalize(template, options = {}, assetHashes = new Set()) {
+    const { ignoreAssets = false, ignoreAssetHashes = false, ignoreBootstrapVersion = true, ignoreCurrentVersion = false, ignoreMetadata = false, ignoreTags = false, ignorePipelineAssets = false, subsetResourceTypes, subsetResourceKeys, assetPlaceholder = anyObject, } = options;
     const result = structuredClone(template);
     if (ignoreBootstrapVersion)
         stripBootstrapVersion(result);
     if (ignoreAssets)
         stripAssets(result, assetPlaceholder);
+    if (ignoreAssetHashes)
+        maskAssetHashes(result, assetHashes);
     if (ignoreCurrentVersion)
         maskCurrentVersions(result);
     if (ignorePipelineAssets)
@@ -66,6 +73,13 @@ function stripAssets(template, placeholder) {
         }
     }
 }
+/**
+ * Only a standalone 64-hex run is a candidate, so a longer hex string that
+ * happens to contain an asset hash is left intact.
+ */
+function maskAssetHashes(tree, hashes) {
+    transformStrings(tree, (value) => value.replace(assetHashRegex, (hash) => hashes.has(hash) ? maskedAssetHash : hash));
+}
 function maskCurrentVersions(tree) {
     transformStrings(tree, (value) => {
         const match = currentVersionRegex.exec(value);

package/lib/options.d.ts

@@ -10,6 +10,18 @@ export interface CdkTemplateOptions {
      * logical ID hashes the code.
      */
     ignoreAssets?: boolean;
+    /**
+     * Replace the hash of every asset in the app with `<ASSET_HASH>`, wherever
+     * a string in the template holds it: Lambda code and layers, container
+     * images, `BucketDeployment` sources, nested stack templates, CDK Pipelines
+     * commands. The rest of each value stays, and values that are not assets
+     * are untouched.
+     *
+     * The hashes are read from the asset manifests CDK's default synthesizer
+     * writes. A function using `currentVersion` also needs
+     * {@link CdkTemplateOptions.ignoreCurrentVersion}.
+     */
+    ignoreAssetHashes?: boolean;
     /**
      * Drop the CDK-managed `BootstrapVersion` parameter and its check rule.
      * Defaults to `true`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liflig/cdk-snapshot",
-  "version": "1.0.2",
+  "version": "1.2.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",