chore(core): add parseAnalytics function for debugging (#36125)

### Reason for this change

It always bothered me that we don't have an easy way of converting a template analytics string back for debugging.
This PR adds a debugging utility to decode analytics strings back into readable ConstructInfo objects.

### Description of changes

- Added `parseAnalytics()` function that reverses the `formatAnalytics()` encoding
- Added `parsePrefixEncodedList()` helper to decode the trie structure
- Added `trieToConstructInfos()` to convert trie back to ConstructInfo array
- Added comprehensive tests verifying parseAnalytics is the inverse of formatAnalytics

The implementation handles the v2:deflate64 format by base64 decoding, gunzipping, and parsing the prefix-encoded trie structure.

### Describe any new or updated permissions being added

None

### Description of how you validated changes

Added unit tests covering:
- Single construct parsing
- Multiple constructs with same version
- Nested module constructs
- Different versions

All tests verify that `parseAnalytics(formatAnalytics(x)) === x`

### Checklist
- [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md)

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: mrgrain

packages/aws-cdk-lib/core/lib/private/metadata-resource.ts

@@ -111,6 +111,43 @@ export function formatAnalytics(infos: ConstructInfo[], enableAdditionalTelemtry
   return analyticsString;
 }
 
+/**
+ * Takes an analytics string and converts it back into a readable format.
+ * Useful for debugging.
+ *
+ * @internal
+ */
+export function parseAnalytics(analyticsString: string): ConstructInfo[] {
+  const analyticsData = analyticsString.split(':');
+  if (analyticsData.length >= 3 && analyticsData[0] === 'v2' && analyticsData[1] === 'deflate64') {
+    const buffer = Buffer.from(analyticsData[2], 'base64');
+    const decompressedBuffer = zlib.gunzipSync(buffer);
+    const prefixEncodedList = decompressedBuffer.toString('utf8');
+    const trie = parsePrefixEncodedList(prefixEncodedList);
+    return trieToConstructInfos(trie);
+  } else {
+    throw new AssumptionError(`Invalid analytics string: ${analyticsString}`);
+  }
+}
+
+/**
+ * Converts a Trie back to a list of ConstructInfo objects.
+ */
+function trieToConstructInfos(trie: Trie): ConstructInfo[] {
+  const infos: ConstructInfo[] = [];
+  function traverse(node: Trie, path: string) {
+    if (node.size === 0) {
+      const [version, fqn] = path.split('!');
+      infos.push({ version, fqn });
+    }
+    for (const [key, value] of node.entries()) {
+      traverse(value, path + key);
+    }
+  }
+  traverse(trie, '');
+  return infos;
+}
+
 /**
  * Splits after non-alphanumeric characters (e.g., '.', '/') in the FQN
  * and insert each piece of the FQN in nested map (i.e., simple trie).
@@ -163,6 +200,54 @@ function prefixEncodeTrie(trie: Trie) {
   return prefixEncoded;
 }
 
+/**
+ * Parses a prefix-encoded "trie-ish" structure.
+ * This is the inverse of `prefixEncodeTrie`.
+ *
+ * Example input:
+ * A{B{C,D},EF}
+ *
+ * Becomes:
+ * ABC,ABD,AEF
+ *
+ * Example trie:
+ * A --> B --> C
+ *  |     \--> D
+ *  \--> E --> F
+ */
+function parsePrefixEncodedList(data: string): Trie {
+  const trie = new Trie();
+  let i = 0;
+
+  function parse(currentTrie: Trie, prefix: string) {
+    let token = '';
+    while (i < data.length) {
+      const char = data[i];
+      if (char === '{') {
+        i++;
+        parse(currentTrie, prefix + token);
+        token = '';
+      } else if (char === '}' || char === ',') {
+        if (token) {
+          insertFqnInTrie(prefix + token, trie);
+        }
+        i++;
+        if (char === '}') return;
+        token = '';
+      } else {
+        token += char;
+        i++;
+      }
+    }
+    if (token) {
+      insertFqnInTrie(prefix + token, trie);
+    }
+  }
+
+  parse(trie, '');
+  return trie;
+}
+
 /**
  * Sets the OS flag to "unknown" in order to ensure we get consistent results across operating systems.
  *

packages/aws-cdk-lib/core/test/metadata-resource.test.ts

@@ -2,7 +2,7 @@ import * as zlib from 'zlib';
 import { Construct } from 'constructs';
 import { ENABLE_ADDITIONAL_METADATA_COLLECTION } from '../../cx-api';
 import { App, Stack, IPolicyValidationPluginBeta1, IPolicyValidationContextBeta1, Stage, PolicyValidationPluginReportBeta1, FeatureFlags, Duration } from '../lib';
-import { formatAnalytics } from '../lib/private/metadata-resource';
+import { formatAnalytics, parseAnalytics } from '../lib/private/metadata-resource';
 import { ConstructInfo } from '../lib/private/runtime-info';
 
 describe('MetadataResource', () => {
@@ -222,6 +222,43 @@ describe('formatAnalytics', () => {
   }
 });
 
+describe('parseAnalytics', () => {
+  test('parseAnalytics is the inverse of formatAnalytics for single construct', () => {
+    const constructInfo = [{ fqn: 'aws-cdk-lib.Construct', version: '1.2.3' }];
+    const analytics = formatAnalytics(constructInfo);
+    expect(parseAnalytics(analytics)).toEqual(constructInfo);
+  });
+
+  test('parseAnalytics is the inverse of formatAnalytics for multiple constructs', () => {
+    const constructInfo = [
+      { fqn: 'aws-cdk-lib.Construct', version: '1.2.3' },
+      { fqn: 'aws-cdk-lib.CfnResource', version: '1.2.3' },
+      { fqn: 'aws-cdk-lib.Stack', version: '1.2.3' },
+    ];
+    const analytics = formatAnalytics(constructInfo);
+    expect(parseAnalytics(analytics)).toEqual(constructInfo);
+  });
+
+  test('parseAnalytics is the inverse of formatAnalytics for nested modules', () => {
+    const constructInfo = [
+      { fqn: 'aws-cdk-lib.Construct', version: '1.2.3' },
+      { fqn: 'aws-cdk-lib.aws_servicefoo.CoolResource', version: '1.2.3' },
+      { fqn: 'aws-cdk-lib.aws_servicefoo.OtherResource', version: '1.2.3' },
+    ];
+    const analytics = formatAnalytics(constructInfo);
+    expect(parseAnalytics(analytics)).toEqual(constructInfo);
+  });
+
+  test('parseAnalytics is the inverse of formatAnalytics for different versions', () => {
+    const constructInfo = [
+      { fqn: 'aws-cdk-lib.Construct', version: '1.2.3' },
+      { fqn: 'aws-cdk-lib.CoolResource', version: '0.1.2' },
+    ];
+    const analytics = formatAnalytics(constructInfo);
+    expect(parseAnalytics(analytics)).toEqual(constructInfo);
+  });
+});
+
 function plaintextConstructsFromAnalytics(analytics: string) {
   return zlib.gunzipSync(Buffer.from(analytics.split(':')[2], 'base64')).toString('utf-8');
 }