@liflig/cdk-snapshot 1.1.0 → 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.
@@ -137,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` |
@@ -158,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`.
 
@@ -176,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.
 

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.js

@@ -3,6 +3,7 @@ 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; } });
@@ -16,5 +17,9 @@ Object.defineProperty(exports, "anyObject", { enumerable: true, get: function ()
  * 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);
+    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/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/cjs/normalize.js

@@ -5,7 +5,9 @@ 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
@@ -14,14 +16,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.
  */
-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;
+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)
@@ -69,6 +76,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/cjs/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/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.1.0",
+  "version": "1.2.0",
   "description": "Normalizes synthesized AWS CDK stacks for snapshot testing",
   "type": "module",
   "license": "MIT",