@liflig/cdk-snapshot 0.0.1 → 1.0.1

package/lib/bun.d.ts

@@ -0,0 +1,14 @@
+import type { Stack } from "aws-cdk-lib";
+import type { CdkSnapshotOptions, CdkTemplateOptions } from "./options.js";
+export type { CdkSnapshotOptions, CdkTemplateOptions } from "./options.js";
+declare module "bun:test" {
+    interface Matchers<T> {
+        toMatchCdkSnapshot(options?: CdkSnapshotOptions): T;
+    }
+}
+/**
+ * {@link cdkTemplateCore} with an asset placeholder Bun's serializer accepts.
+ *
+ * Bun recognizes only matchers created by its own `expect`.
+ */
+export declare function cdkTemplate(stack: Stack, options?: CdkTemplateOptions): Record<string, unknown>;

package/lib/bun.js

@@ -0,0 +1,15 @@
+import { expect } from "bun:test";
+import { cdkTemplate as cdkTemplateCore } from "./index.js";
+import { registerCdkMatcher } from "./matcher.js";
+/**
+ * {@link cdkTemplateCore} with an asset placeholder Bun's serializer accepts.
+ *
+ * Bun recognizes only matchers created by its own `expect`.
+ */
+export function cdkTemplate(stack, options = {}) {
+    return cdkTemplateCore(stack, {
+        assetPlaceholder: expect.any(Object),
+        ...options,
+    });
+}
+registerCdkMatcher(expect, cdkTemplate);

package/lib/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/index.js

@@ -0,0 +1,15 @@
+import { Template } from "aws-cdk-lib/assertions";
+import { normalize } from "./normalize.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 function cdkTemplate(stack, options = {}) {
+    return normalize(Template.fromStack(stack).toJSON(), options);
+}

package/lib/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/jest.js

@@ -0,0 +1,4 @@
+import { cdkTemplate } from "./index.js";
+import { registerCdkMatcher, requireExpect } from "./matcher.js";
+export { cdkTemplate } from "./index.js";
+registerCdkMatcher(requireExpect("Jest", globalThis.expect), cdkTemplate);

package/lib/matcher.d.ts

@@ -0,0 +1,22 @@
+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;
+}
+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/matcher.js

@@ -0,0 +1,35 @@
+/**
+ * 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 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 assertion = expect(cdkTemplate(received, templateOptions));
+            if (propertyMatchers) {
+                assertion.toMatchSnapshot(propertyMatchers);
+            }
+            else {
+                assertion.toMatchSnapshot();
+            }
+            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.
+ */
+export 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/node.d.ts

@@ -0,0 +1,9 @@
+export { cdkTemplate } from "./index.js";
+export type { CdkSnapshotOptions, CdkTemplateOptions } from "./options.js";
+/**
+ * Aligns `node:test` with the snapshot location and serialization the other
+ * runners use, so one set of snapshot files serves all of them.
+ *
+ * Call once, before any test runs.
+ */
+export declare function configureCdkSnapshots(): void;

package/lib/node.js

@@ -0,0 +1,19 @@
+import path from "node:path";
+import { snapshot } from "node:test";
+import { serialize } from "./serialize.js";
+export { cdkTemplate } from "./index.js";
+/**
+ * Aligns `node:test` with the snapshot location and serialization the other
+ * runners use, so one set of snapshot files serves all of them.
+ *
+ * Call once, before any test runs.
+ */
+export function configureCdkSnapshots() {
+    snapshot.setResolveSnapshotPath((testPath) => {
+        if (!testPath) {
+            throw new Error("@liflig/cdk-snapshot: snapshots require tests to be run from a file.");
+        }
+        return path.join(path.dirname(testPath), "__snapshots__", `${path.basename(testPath)}.snap`);
+    });
+    snapshot.setDefaultSnapshotSerializers([serialize]);
+}

package/lib/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/normalize.js

@@ -0,0 +1,137 @@
+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 = /:(.*)$/;
+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.
+ */
+export function normalize(template, options = {}) {
+    const { ignoreAssets = 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 (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>:<destination>"` — the hash changes on every
+ * synth, the destination does not.
+ */
+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/options.d.ts

@@ -0,0 +1,37 @@
+export interface CdkTemplateOptions {
+    /**
+     * Replace asset-derived values — Lambda `Code`, container `Image`, and the
+     * template parameters carrying asset hashes — with {@link anyObject}.
+     */
+    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 `Tags` from resource properties. */
+    ignoreTags?: boolean;
+    /** Mask asset paths and IDs 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/placeholder.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Stand-in for values that change on every synth, such as asset hashes.
+ * 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/placeholder.js

@@ -0,0 +1,14 @@
+/**
+ * Stand-in for values that change on every synth, such as asset hashes.
+ * 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 const anyObject = {
+    $$typeof: Symbol.for("jest.asymmetricMatcher"),
+    asymmetricMatch: (actual) => typeof actual === "object" && actual !== null,
+    toString: () => "Any",
+    getExpectedType: () => "Object",
+    toAsymmetricMatcher: () => "Any<Object>",
+};

package/lib/serialize.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Serializes a value the way Jest, Vitest and Bun serialize snapshots.
+ *
+ * `node:test` formats with `JSON.stringify` by default, which would make its
+ * snapshots incompatible with the other runners.
+ */
+export declare function serialize(value: unknown): string;

package/lib/serialize.js

@@ -0,0 +1,17 @@
+import { format, plugins } from "pretty-format";
+/**
+ * Serializes a value the way Jest, Vitest and Bun serialize snapshots.
+ *
+ * `node:test` formats with `JSON.stringify` by default, which would make its
+ * snapshots incompatible with the other runners.
+ */
+export function serialize(value) {
+    return format(value, {
+        escapeRegex: true,
+        escapeString: false,
+        indent: 2,
+        printBasicPrototype: false,
+        printFunctionName: false,
+        plugins: [plugins.AsymmetricMatcher],
+    });
+}

package/lib/vitest.d.ts

@@ -0,0 +1,8 @@
+import type { CdkSnapshotOptions } from "./options.js";
+export { cdkTemplate } from "./index.js";
+export type { CdkSnapshotOptions, CdkTemplateOptions } from "./options.js";
+declare module "vitest" {
+    interface Matchers<T = any> {
+        toMatchCdkSnapshot(options?: CdkSnapshotOptions): T;
+    }
+}

package/lib/vitest.js

@@ -0,0 +1,5 @@
+import { expect } from "vitest";
+import { cdkTemplate } from "./index.js";
+import { registerCdkMatcher } from "./matcher.js";
+export { cdkTemplate } from "./index.js";
+registerCdkMatcher(expect, cdkTemplate);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liflig/cdk-snapshot",
-  "version": "0.0.1",
+  "version": "1.0.1",
   "description": "Normalizes synthesized AWS CDK stacks for snapshot testing",
   "type": "module",
   "license": "MIT",
@@ -84,18 +84,19 @@
     "pretty-format": "^29.7.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.10",
+    "@biomejs/biome": "2.5.11",
     "@types/bun": "1.4.0",
     "@types/jest": "30.0.0",
     "@types/node": "24.13.3",
-    "aws-cdk-lib": "2.266.0",
+    "aws-cdk-lib": "2.267.0",
     "constructs": "10.8.1",
-    "jest": "30.4.2",
+    "jest": "30.5.0",
     "semantic-release": "25.0.9",
     "typescript": "7.0.2",
     "vitest": "4.1.11"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   }
 }