@aws/nx-plugin 1.0.0-rc.5 → 1.0.0-rc.50

package/src/utils/mcp.js

@@ -1,42 +1,44 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.configureMcpServers = exports.NX_PLUGIN_MCP_SERVER_ARGS = exports.NX_PLUGIN_MCP_SERVER_COMMAND = exports.NX_PLUGIN_MCP_SERVER_NAME = void 0;
 /**
  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  * SPDX-License-Identifier: Apache-2.0
- */
-const devkit_1 = require("@nx/devkit");
-const toml_1 = require("./toml");
+ */ import { readJson, writeJson } from "@nx/devkit";
+import { updateToml } from "./toml.js";
 /**
  * Name of the Nx Plugin for AWS MCP server, used as the key in each agent's config.
- */
-exports.NX_PLUGIN_MCP_SERVER_NAME = 'nx-plugin-for-aws';
+ */ export const NX_PLUGIN_MCP_SERVER_NAME = 'nx-plugin-for-aws';
 /**
  * Command used to launch the Nx Plugin for AWS MCP server.
- */
-exports.NX_PLUGIN_MCP_SERVER_COMMAND = 'npx';
+ */ export const NX_PLUGIN_MCP_SERVER_COMMAND = 'npx';
+/**
+ * Package providing the Nx Plugin for AWS MCP server.
+ */ export const NX_PLUGIN_MCP_PACKAGE_NAME = '@aws/nx-plugin-mcp';
 /**
  * Arguments used to launch the Nx Plugin for AWS MCP server.
- */
-exports.NX_PLUGIN_MCP_SERVER_ARGS = ['-y', '@aws/nx-plugin-mcp@next'];
+ *
+ * npx prefers a locally installed package over the registry, and generators
+ * declare this package as a workspace devDependency, so the server tracks the
+ * version in the workspace's lockfile. `-y` falls back to fetching from the
+ * registry for a workspace where it isn't installed.
+ */ export const NX_PLUGIN_MCP_SERVER_ARGS = [
+    '-y',
+    NX_PLUGIN_MCP_PACKAGE_NAME
+];
 /**
  * A single stdio MCP server entry, shared by agents that use the `mcpServers` config shape.
- */
-const stdioServerEntry = () => ({
-    command: exports.NX_PLUGIN_MCP_SERVER_COMMAND,
-    args: exports.NX_PLUGIN_MCP_SERVER_ARGS,
-});
+ */ const stdioServerEntry = ()=>({
+        command: NX_PLUGIN_MCP_SERVER_COMMAND,
+        args: NX_PLUGIN_MCP_SERVER_ARGS
+    });
 /**
  * Merge the Nx Plugin for AWS MCP server into a JSON config file under the given key,
  * preserving any other servers already configured. Creates the file if it does not exist.
- */
-const mergeJsonMcpConfig = (tree, filePath, key, entry) => {
-    const config = tree.exists(filePath) ? (0, devkit_1.readJson)(tree, filePath) : {};
+ */ const mergeJsonMcpConfig = (tree, filePath, key, entry)=>{
+    const config = tree.exists(filePath) ? readJson(tree, filePath) : {};
     config[key] = {
         ...config[key],
-        [exports.NX_PLUGIN_MCP_SERVER_NAME]: entry,
+        [NX_PLUGIN_MCP_SERVER_NAME]: entry
     };
-    (0, devkit_1.writeJson)(tree, filePath, config);
+    writeJson(tree, filePath, config);
 };
 /**
  * Configure the Nx Plugin for AWS MCP server across the project-level config locations
@@ -44,38 +46,37 @@ const mergeJsonMcpConfig = (tree, filePath, key, entry) => {
  * AWS projects with the Nx Plugin for AWS.
  *
  * Existing servers and unrelated config in each file are preserved.
- */
-const configureMcpServers = (tree) => {
+ */ export const configureMcpServers = (tree)=>{
     // Agents using the `mcpServers` config shape (Claude Code, Cursor, Kiro, Gemini CLI)
     const mcpServersFiles = [
-        '.mcp.json', // Claude Code
-        '.cursor/mcp.json', // Cursor
-        '.kiro/settings/mcp.json', // Kiro
-        '.gemini/settings.json', // Gemini CLI
+        '.mcp.json',
+        '.cursor/mcp.json',
+        '.kiro/settings/mcp.json',
+        '.gemini/settings.json'
     ];
-    for (const filePath of mcpServersFiles) {
+    for (const filePath of mcpServersFiles){
         mergeJsonMcpConfig(tree, filePath, 'mcpServers', stdioServerEntry());
     }
     // GitHub Copilot uses the `servers` key with an explicit `type`
     mergeJsonMcpConfig(tree, '.vscode/mcp.json', 'servers', {
         type: 'stdio',
-        ...stdioServerEntry(),
+        ...stdioServerEntry()
     });
     // OpenAI Codex CLI uses TOML under the `mcp_servers` table
     const codexConfig = '.codex/config.toml';
     if (!tree.exists(codexConfig)) {
         tree.write(codexConfig, '');
     }
-    (0, toml_1.updateToml)(tree, codexConfig, (prev) => ({
-        ...prev,
-        mcp_servers: {
-            ...prev.mcp_servers,
-            [exports.NX_PLUGIN_MCP_SERVER_NAME]: {
-                command: exports.NX_PLUGIN_MCP_SERVER_COMMAND,
-                args: exports.NX_PLUGIN_MCP_SERVER_ARGS,
-            },
-        },
-    }));
+    updateToml(tree, codexConfig, (prev)=>({
+            ...prev,
+            mcp_servers: {
+                ...prev.mcp_servers,
+                [NX_PLUGIN_MCP_SERVER_NAME]: {
+                    command: NX_PLUGIN_MCP_SERVER_COMMAND,
+                    args: NX_PLUGIN_MCP_SERVER_ARGS
+                }
+            }
+        }));
 };
-exports.configureMcpServers = configureMcpServers;
+
 //# sourceMappingURL=mcp.js.map

package/src/utils/mcp.js.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../../../../../packages/nx-plugin/src/utils/mcp.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACH,uCAAuD;AACvD,iCAAoC;AAEpC;;GAEG;AACU,QAAA,yBAAyB,GAAG,mBAAmB,CAAC;AAE7D;;GAEG;AACU,QAAA,4BAA4B,GAAG,KAAK,CAAC;AAElD;;GAEG;AACU,QAAA,yBAAyB,GAAG,CAAC,IAAI,EAAE,yBAAyB,CAAC,CAAC;AAE3E;;GAEG;AACH,MAAM,gBAAgB,GAAG,GAAG,EAAE,CAAC,CAAC;IAC9B,OAAO,EAAE,oCAA4B;IACrC,IAAI,EAAE,iCAAyB;CAChC,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,kBAAkB,GAAG,CACzB,IAAU,EACV,QAAgB,EAChB,GAA6B,EAC7B,KAA8B,EAC9B,EAAE;IACF,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAA,iBAAQ,EAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACrE,MAAM,CAAC,GAAG,CAAC,GAAG;QACZ,GAAG,MAAM,CAAC,GAAG,CAAC;QACd,CAAC,iCAAyB,CAAC,EAAE,KAAK;KACnC,CAAC;IACF,IAAA,kBAAS,EAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;AACpC,CAAC,CAAC;AAEF;;;;;;GAMG;AACI,MAAM,mBAAmB,GAAG,CAAC,IAAU,EAAE,EAAE;IAChD,qFAAqF;IACrF,MAAM,eAAe,GAAG;QACtB,WAAW,EAAE,cAAc;QAC3B,kBAAkB,EAAE,SAAS;QAC7B,yBAAyB,EAAE,OAAO;QAClC,uBAAuB,EAAE,aAAa;KACvC,CAAC;IACF,KAAK,MAAM,QAAQ,IAAI,eAAe,EAAE,CAAC;QACvC,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,YAAY,EAAE,gBAAgB,EAAE,CAAC,CAAC;IACvE,CAAC;IAED,gEAAgE;IAChE,kBAAkB,CAAC,IAAI,EAAE,kBAAkB,EAAE,SAAS,EAAE;QACtD,IAAI,EAAE,OAAO;QACb,GAAG,gBAAgB,EAAE;KACtB,CAAC,CAAC;IAEH,2DAA2D;IAC3D,MAAM,WAAW,GAAG,oBAAoB,CAAC;IACzC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;QAC9B,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;IAC9B,CAAC;IACD,IAAA,iBAAU,EAAC,IAAI,EAAE,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACvC,GAAG,IAAI;QACP,WAAW,EAAE;YACX,GAAI,IAAI,CAAC,WAAsB;YAC/B,CAAC,iCAAyB,CAAC,EAAE;gBAC3B,OAAO,EAAE,oCAA4B;gBACrC,IAAI,EAAE,iCAAyB;aAChC;SACF;KACF,CAAC,CAAC,CAAC;AACN,CAAC,CAAC;AAjCW,QAAA,mBAAmB,uBAiC9B"}
+{"version":3,"sources":["../../../../../packages/nx-plugin/src/utils/mcp.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport { readJson, type Tree, writeJson } from '@nx/devkit';\nimport { updateToml } from './toml';\n\n/**\n * Name of the Nx Plugin for AWS MCP server, used as the key in each agent's config.\n */\nexport const NX_PLUGIN_MCP_SERVER_NAME = 'nx-plugin-for-aws';\n\n/**\n * Command used to launch the Nx Plugin for AWS MCP server.\n */\nexport const NX_PLUGIN_MCP_SERVER_COMMAND = 'npx';\n\n/**\n * Package providing the Nx Plugin for AWS MCP server.\n */\nexport const NX_PLUGIN_MCP_PACKAGE_NAME = '@aws/nx-plugin-mcp';\n\n/**\n * Arguments used to launch the Nx Plugin for AWS MCP server.\n *\n * npx prefers a locally installed package over the registry, and generators\n * declare this package as a workspace devDependency, so the server tracks the\n * version in the workspace's lockfile. `-y` falls back to fetching from the\n * registry for a workspace where it isn't installed.\n */\nexport const NX_PLUGIN_MCP_SERVER_ARGS = ['-y', NX_PLUGIN_MCP_PACKAGE_NAME];\n\n/**\n * A single stdio MCP server entry, shared by agents that use the `mcpServers` config shape.\n */\nconst stdioServerEntry = () => ({\n  command: NX_PLUGIN_MCP_SERVER_COMMAND,\n  args: NX_PLUGIN_MCP_SERVER_ARGS,\n});\n\n/**\n * Merge the Nx Plugin for AWS MCP server into a JSON config file under the given key,\n * preserving any other servers already configured. Creates the file if it does not exist.\n */\nconst mergeJsonMcpConfig = (\n  tree: Tree,\n  filePath: string,\n  key: 'mcpServers' | 'servers',\n  entry: Record<string, unknown>,\n) => {\n  const config = tree.exists(filePath) ? readJson(tree, filePath) : {};\n  config[key] = {\n    ...config[key],\n    [NX_PLUGIN_MCP_SERVER_NAME]: entry,\n  };\n  writeJson(tree, filePath, config);\n};\n\n/**\n * Configure the Nx Plugin for AWS MCP server across the project-level config locations\n * used by common coding agents, so agents working in the workspace can use it to scaffold\n * AWS projects with the Nx Plugin for AWS.\n *\n * Existing servers and unrelated config in each file are preserved.\n */\nexport const configureMcpServers = (tree: Tree) => {\n  // Agents using the `mcpServers` config shape (Claude Code, Cursor, Kiro, Gemini CLI)\n  const mcpServersFiles = [\n    '.mcp.json', // Claude Code\n    '.cursor/mcp.json', // Cursor\n    '.kiro/settings/mcp.json', // Kiro\n    '.gemini/settings.json', // Gemini CLI\n  ];\n  for (const filePath of mcpServersFiles) {\n    mergeJsonMcpConfig(tree, filePath, 'mcpServers', stdioServerEntry());\n  }\n\n  // GitHub Copilot uses the `servers` key with an explicit `type`\n  mergeJsonMcpConfig(tree, '.vscode/mcp.json', 'servers', {\n    type: 'stdio',\n    ...stdioServerEntry(),\n  });\n\n  // OpenAI Codex CLI uses TOML under the `mcp_servers` table\n  const codexConfig = '.codex/config.toml';\n  if (!tree.exists(codexConfig)) {\n    tree.write(codexConfig, '');\n  }\n  updateToml(tree, codexConfig, (prev) => ({\n    ...prev,\n    mcp_servers: {\n      ...(prev.mcp_servers as object),\n      [NX_PLUGIN_MCP_SERVER_NAME]: {\n        command: NX_PLUGIN_MCP_SERVER_COMMAND,\n        args: NX_PLUGIN_MCP_SERVER_ARGS,\n      },\n    },\n  }));\n};\n"],"names":["readJson","writeJson","updateToml","NX_PLUGIN_MCP_SERVER_NAME","NX_PLUGIN_MCP_SERVER_COMMAND","NX_PLUGIN_MCP_PACKAGE_NAME","NX_PLUGIN_MCP_SERVER_ARGS","stdioServerEntry","command","args","mergeJsonMcpConfig","tree","filePath","key","entry","config","exists","configureMcpServers","mcpServersFiles","type","codexConfig","write","prev","mcp_servers"],"mappings":"AAAA;;;CAGC,GACD,SAASA,QAAQ,EAAaC,SAAS,QAAQ,aAAa;AAC5D,SAASC,UAAU,QAAQ,YAAS;AAEpC;;CAEC,GACD,OAAO,MAAMC,4BAA4B,oBAAoB;AAE7D;;CAEC,GACD,OAAO,MAAMC,+BAA+B,MAAM;AAElD;;CAEC,GACD,OAAO,MAAMC,6BAA6B,qBAAqB;AAE/D;;;;;;;CAOC,GACD,OAAO,MAAMC,4BAA4B;IAAC;IAAMD;CAA2B,CAAC;AAE5E;;CAEC,GACD,MAAME,mBAAmB,IAAO,CAAA;QAC9BC,SAASJ;QACTK,MAAMH;IACR,CAAA;AAEA;;;CAGC,GACD,MAAMI,qBAAqB,CACzBC,MACAC,UACAC,KACAC;IAEA,MAAMC,SAASJ,KAAKK,MAAM,CAACJ,YAAYZ,SAASW,MAAMC,YAAY,CAAC;IACnEG,MAAM,CAACF,IAAI,GAAG;QACZ,GAAGE,MAAM,CAACF,IAAI;QACd,CAACV,0BAA0B,EAAEW;IAC/B;IACAb,UAAUU,MAAMC,UAAUG;AAC5B;AAEA;;;;;;CAMC,GACD,OAAO,MAAME,sBAAsB,CAACN;IAClC,qFAAqF;IACrF,MAAMO,kBAAkB;QACtB;QACA;QACA;QACA;KACD;IACD,KAAK,MAAMN,YAAYM,gBAAiB;QACtCR,mBAAmBC,MAAMC,UAAU,cAAcL;IACnD;IAEA,gEAAgE;IAChEG,mBAAmBC,MAAM,oBAAoB,WAAW;QACtDQ,MAAM;QACN,GAAGZ,kBAAkB;IACvB;IAEA,2DAA2D;IAC3D,MAAMa,cAAc;IACpB,IAAI,CAACT,KAAKK,MAAM,CAACI,cAAc;QAC7BT,KAAKU,KAAK,CAACD,aAAa;IAC1B;IACAlB,WAAWS,MAAMS,aAAa,CAACE,OAAU,CAAA;YACvC,GAAGA,IAAI;YACPC,aAAa;gBACX,GAAID,KAAKC,WAAW;gBACpB,CAACpB,0BAA0B,EAAE;oBAC3BK,SAASJ;oBACTK,MAAMH;gBACR;YACF;QACF,CAAA;AACF,EAAE"}

package/src/utils/metrics.d.ts

@@ -2,13 +2,19 @@
  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
-import { Tree } from '@nx/devkit';
-import { NxGeneratorInfo } from './nx';
+import { type Tree } from '@nx/devkit';
+import { type NxGeneratorInfo } from './nx';
 export declare const METRIC_ID = "uksb-4wk0bqpg5s";
 export declare const METRICS_ASPECT_FILE_PATH: string;
 export declare const TERRAFORM_METRICS_FILE_PATH: string;
 /**
  * Instruments metrics by updating the MetricsAspect in common/constructs/src/core/app.ts if the file exists,
- * or updating the Terraform metrics CloudFormation stack if it exists
+ * and/or updating the Terraform metrics CloudFormation stack if it exists.
+ *
+ * Both files are converged to the same tag set (the union of tags already
+ * present in either file plus the incoming generators). This keeps the tag set
+ * deterministic regardless of the order in which metrics files are created
+ * across a multi-generator run, so re-running the same set of generators does
+ * not grow the tags.
  */
 export declare const addGeneratorMetricsIfApplicable: (tree: Tree, generatorInfo: NxGeneratorInfo[]) => Promise<void>;

package/src/utils/metrics.js

@@ -1,65 +1,80 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.addGeneratorMetricsIfApplicable = exports.TERRAFORM_METRICS_FILE_PATH = exports.METRICS_ASPECT_FILE_PATH = exports.METRIC_ID = void 0;
 /**
  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  * SPDX-License-Identifier: Apache-2.0
- */
-const devkit_1 = require("@nx/devkit");
-const ast_1 = require("./ast");
-const format_1 = require("./format");
-const nx_1 = require("./nx");
-const shared_constructs_constants_1 = require("./shared-constructs-constants");
+ */ import { joinPathFragments } from "@nx/devkit";
+import { applyGritQL, captureAllGritQL } from "./ast.js";
+import { formatFilesInSubtree } from "./format.js";
+import { getPackageVersion } from "./nx.js";
+import { PACKAGES_DIR, SHARED_CONSTRUCTS_DIR, SHARED_TERRAFORM_DIR } from "./shared-constructs-constants.js";
 // Used to identify @aws/nx-plugin in AWS metrics
-exports.METRIC_ID = 'uksb-4wk0bqpg5s';
+export const METRIC_ID = 'uksb-4wk0bqpg5s';
 // File in which the MetricsAspect may exist (CDK)
-exports.METRICS_ASPECT_FILE_PATH = (0, devkit_1.joinPathFragments)(shared_constructs_constants_1.PACKAGES_DIR, shared_constructs_constants_1.SHARED_CONSTRUCTS_DIR, 'src', 'core', 'app.ts');
+export const METRICS_ASPECT_FILE_PATH = joinPathFragments(PACKAGES_DIR, SHARED_CONSTRUCTS_DIR, 'src', 'core', 'app.ts');
 // File in which the Terraform metrics CloudFormation stack may exist
-exports.TERRAFORM_METRICS_FILE_PATH = (0, devkit_1.joinPathFragments)(shared_constructs_constants_1.PACKAGES_DIR, shared_constructs_constants_1.SHARED_TERRAFORM_DIR, 'src', 'metrics', 'metrics.tf');
+export const TERRAFORM_METRICS_FILE_PATH = joinPathFragments(PACKAGES_DIR, SHARED_TERRAFORM_DIR, 'src', 'metrics', 'metrics.tf');
 // GritQL `within` clause to scope matches to the MetricsAspect class body
 const WITHIN_METRICS_ASPECT = '$old <: within `class MetricsAspect implements $_ { $_ }`';
+// Strip the surrounding quotes from a captured string literal (eg 'g1' or "g1")
+const unquote = (literal)=>literal.slice(1, -1);
+// Extracts the existing metric tags from the CDK MetricsAspect tags array
+const readCdkMetricTags = async (tree)=>(await captureAllGritQL(tree, METRICS_ASPECT_FILE_PATH, `\`$tag\` where { $tag <: string(), $tag <: within \`const tags: string[] = $_\` }`)).map(unquote);
+// Extracts the existing metric tags from the Terraform metric_tags array
+const readTerraformMetricTags = async (tree)=>(await captureAllGritQL(tree, TERRAFORM_METRICS_FILE_PATH, '`"$tag"` where { $tag <: within `metric_tags = $_` }')).map(unquote);
 /**
  * Instruments metrics by updating the MetricsAspect in common/constructs/src/core/app.ts if the file exists,
- * or updating the Terraform metrics CloudFormation stack if it exists
- */
-const addGeneratorMetricsIfApplicable = async (tree, generatorInfo) => {
-    // Handle CDK metrics
-    if (tree.exists(exports.METRICS_ASPECT_FILE_PATH)) {
-        // Update the id
-        await (0, ast_1.applyGritQL)(tree, exports.METRICS_ASPECT_FILE_PATH, `\`const id = $old\` => \`const id = '${exports.METRIC_ID}'\`` +
-            ` where { ${WITHIN_METRICS_ASPECT} }`);
-        // Update the version
-        await (0, ast_1.applyGritQL)(tree, exports.METRICS_ASPECT_FILE_PATH, `\`const version = $old\` => \`const version = '${(0, nx_1.getPackageVersion)()}'\`` +
-            ` where { ${WITHIN_METRICS_ASPECT} }`);
-        // Add each generator as a tag
-        for (const info of generatorInfo) {
-            await (0, ast_1.applyGritQL)(tree, exports.METRICS_ASPECT_FILE_PATH, `\`const tags: string[] = $old\`` +
-                ` where { ${WITHIN_METRICS_ASPECT},` +
-                ` if ($old <: \`[]\`) { $old => \`['${info.metric}']\` }` +
-                ` else { $old <: \`[$items]\` where { $items += \`, '${info.metric}'\` } },` +
-                ` $old <: not contains \`'${info.metric}'\` }`);
-        }
-        await (0, format_1.formatFilesInSubtree)(tree, exports.METRICS_ASPECT_FILE_PATH);
+ * and/or updating the Terraform metrics CloudFormation stack if it exists.
+ *
+ * Both files are converged to the same tag set (the union of tags already
+ * present in either file plus the incoming generators). This keeps the tag set
+ * deterministic regardless of the order in which metrics files are created
+ * across a multi-generator run, so re-running the same set of generators does
+ * not grow the tags.
+ */ export const addGeneratorMetricsIfApplicable = async (tree, generatorInfo)=>{
+    const cdkExists = tree.exists(METRICS_ASPECT_FILE_PATH);
+    const terraformExists = tree.exists(TERRAFORM_METRICS_FILE_PATH);
+    if (!cdkExists && !terraformExists) {
+        return;
     }
-    // Handle Terraform metrics
-    if (tree.exists(exports.TERRAFORM_METRICS_FILE_PATH)) {
-        await updateTerraformMetrics(tree, generatorInfo);
+    // Converge both files to the union of all known tags so the set is stable
+    // regardless of when each metrics file was created.
+    const tags = [
+        ...new Set([
+            ...await readCdkMetricTags(tree),
+            ...await readTerraformMetricTags(tree),
+            ...generatorInfo.map((info)=>info.metric)
+        ])
+    ];
+    if (cdkExists) {
+        await updateCdkMetrics(tree, tags);
     }
+    if (terraformExists) {
+        await updateTerraformMetrics(tree, tags);
+    }
+};
+/**
+ * Updates the CDK MetricsAspect with the metric id, version and tags
+ */ const updateCdkMetrics = async (tree, tags)=>{
+    // Update the id
+    await applyGritQL(tree, METRICS_ASPECT_FILE_PATH, `\`const id = $old\` => \`const id = '${METRIC_ID}'\`` + ` where { ${WITHIN_METRICS_ASPECT} }`);
+    // Update the version
+    await applyGritQL(tree, METRICS_ASPECT_FILE_PATH, `\`const version = $old\` => \`const version = '${getPackageVersion()}'\`` + ` where { ${WITHIN_METRICS_ASPECT} }`);
+    // Add each tag, leaving existing tags in place to keep re-runs stable
+    for (const tag of tags){
+        await applyGritQL(tree, METRICS_ASPECT_FILE_PATH, `\`const tags: string[] = $old\`` + ` where { ${WITHIN_METRICS_ASPECT},` + ` if ($old <: \`[]\`) { $old => \`['${tag}']\` }` + ` else { $old <: \`[$items]\` where { $items += \`, '${tag}'\` } },` + ` $old <: not contains \`'${tag}'\` }`);
+    }
+    await formatFilesInSubtree(tree, METRICS_ASPECT_FILE_PATH);
 };
-exports.addGeneratorMetricsIfApplicable = addGeneratorMetricsIfApplicable;
 /**
- * Updates the Terraform metrics CloudFormation stack with generator information
- */
-const updateTerraformMetrics = async (tree, generatorInfo) => {
+ * Updates the Terraform metrics CloudFormation stack with the metric id, version and tags
+ */ const updateTerraformMetrics = async (tree, tags)=>{
     // Update metric_id
-    await (0, ast_1.applyGritQL)(tree, exports.TERRAFORM_METRICS_FILE_PATH, `\`metric_id = $old\` => \`metric_id = "${exports.METRIC_ID}"\``);
+    await applyGritQL(tree, TERRAFORM_METRICS_FILE_PATH, `\`metric_id = $old\` => \`metric_id = "${METRIC_ID}"\``);
     // Update metric_version
-    await (0, ast_1.applyGritQL)(tree, exports.TERRAFORM_METRICS_FILE_PATH, `\`metric_version = $old\` => \`metric_version = "${(0, nx_1.getPackageVersion)()}"\``);
-    // Update metric_tags
-    for (const info of generatorInfo) {
-        await (0, ast_1.applyGritQL)(tree, exports.TERRAFORM_METRICS_FILE_PATH, `or { \`metric_tags = []\` => \`metric_tags = ["${info.metric}"]\`,` +
-            ` \`metric_tags = [$items]\` where { $items += \`, "${info.metric}"\` }` +
-            ` where { $items <: not contains \`"${info.metric}"\` } }`);
+    await applyGritQL(tree, TERRAFORM_METRICS_FILE_PATH, `\`metric_version = $old\` => \`metric_version = "${getPackageVersion()}"\``);
+    // Add each tag, leaving existing tags in place to keep re-runs stable
+    for (const tag of tags){
+        await applyGritQL(tree, TERRAFORM_METRICS_FILE_PATH, `or { \`metric_tags = []\` => \`metric_tags = ["${tag}"]\`,` + ` \`metric_tags = [$items]\` where { $items += \`, "${tag}"\` }` + ` where { $items <: not contains \`"${tag}"\` } }`);
     }
 };
+
 //# sourceMappingURL=metrics.js.map

package/src/utils/metrics.js.map

@@ -1 +1 @@
-{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../../../../packages/nx-plugin/src/utils/metrics.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACH,uCAAqD;AACrD,+BAAoC;AACpC,qCAAgD;AAChD,6BAA0D;AAC1D,+EAIuC;AAEvC,iDAAiD;AACpC,QAAA,SAAS,GAAG,iBAAiB,CAAC;AAE3C,kDAAkD;AACrC,QAAA,wBAAwB,GAAG,IAAA,0BAAiB,EACvD,0CAAY,EACZ,mDAAqB,EACrB,KAAK,EACL,MAAM,EACN,QAAQ,CACT,CAAC;AAEF,qEAAqE;AACxD,QAAA,2BAA2B,GAAG,IAAA,0BAAiB,EAC1D,0CAAY,EACZ,kDAAoB,EACpB,KAAK,EACL,SAAS,EACT,YAAY,CACb,CAAC;AAEF,0EAA0E;AAC1E,MAAM,qBAAqB,GACzB,2DAA2D,CAAC;AAE9D;;;GAGG;AACI,MAAM,+BAA+B,GAAG,KAAK,EAClD,IAAU,EACV,aAAgC,EAChC,EAAE;IACF,qBAAqB;IACrB,IAAI,IAAI,CAAC,MAAM,CAAC,gCAAwB,CAAC,EAAE,CAAC;QAC1C,gBAAgB;QAChB,MAAM,IAAA,iBAAW,EACf,IAAI,EACJ,gCAAwB,EACxB,wCAAwC,iBAAS,KAAK;YACpD,YAAY,qBAAqB,IAAI,CACxC,CAAC;QAEF,qBAAqB;QACrB,MAAM,IAAA,iBAAW,EACf,IAAI,EACJ,gCAAwB,EACxB,kDAAkD,IAAA,sBAAiB,GAAE,KAAK;YACxE,YAAY,qBAAqB,IAAI,CACxC,CAAC;QAEF,8BAA8B;QAC9B,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;YACjC,MAAM,IAAA,iBAAW,EACf,IAAI,EACJ,gCAAwB,EACxB,iCAAiC;gBAC/B,YAAY,qBAAqB,GAAG;gBACpC,sCAAsC,IAAI,CAAC,MAAM,QAAQ;gBACzD,uDAAuD,IAAI,CAAC,MAAM,UAAU;gBAC5E,4BAA4B,IAAI,CAAC,MAAM,OAAO,CACjD,CAAC;QACJ,CAAC;QAED,MAAM,IAAA,6BAAoB,EAAC,IAAI,EAAE,gCAAwB,CAAC,CAAC;IAC7D,CAAC;IAED,2BAA2B;IAC3B,IAAI,IAAI,CAAC,MAAM,CAAC,mCAA2B,CAAC,EAAE,CAAC;QAC7C,MAAM,sBAAsB,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IACpD,CAAC;AACH,CAAC,CAAC;AA1CW,QAAA,+BAA+B,mCA0C1C;AAEF;;GAEG;AACH,MAAM,sBAAsB,GAAG,KAAK,EAClC,IAAU,EACV,aAAgC,EAChC,EAAE;IACF,mBAAmB;IACnB,MAAM,IAAA,iBAAW,EACf,IAAI,EACJ,mCAA2B,EAC3B,0CAA0C,iBAAS,KAAK,CACzD,CAAC;IAEF,wBAAwB;IACxB,MAAM,IAAA,iBAAW,EACf,IAAI,EACJ,mCAA2B,EAC3B,oDAAoD,IAAA,sBAAiB,GAAE,KAAK,CAC7E,CAAC;IAEF,qBAAqB;IACrB,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QACjC,MAAM,IAAA,iBAAW,EACf,IAAI,EACJ,mCAA2B,EAC3B,kDAAkD,IAAI,CAAC,MAAM,OAAO;YAClE,sDAAsD,IAAI,CAAC,MAAM,OAAO;YACxE,sCAAsC,IAAI,CAAC,MAAM,SAAS,CAC7D,CAAC;IACJ,CAAC;AACH,CAAC,CAAC"}
+{"version":3,"sources":["../../../../../packages/nx-plugin/src/utils/metrics.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport { joinPathFragments, type Tree } from '@nx/devkit';\nimport { applyGritQL, captureAllGritQL } from './ast';\nimport { formatFilesInSubtree } from './format';\nimport { getPackageVersion, type NxGeneratorInfo } from './nx';\nimport {\n  PACKAGES_DIR,\n  SHARED_CONSTRUCTS_DIR,\n  SHARED_TERRAFORM_DIR,\n} from './shared-constructs-constants';\n\n// Used to identify @aws/nx-plugin in AWS metrics\nexport const METRIC_ID = 'uksb-4wk0bqpg5s';\n\n// File in which the MetricsAspect may exist (CDK)\nexport const METRICS_ASPECT_FILE_PATH = joinPathFragments(\n  PACKAGES_DIR,\n  SHARED_CONSTRUCTS_DIR,\n  'src',\n  'core',\n  'app.ts',\n);\n\n// File in which the Terraform metrics CloudFormation stack may exist\nexport const TERRAFORM_METRICS_FILE_PATH = joinPathFragments(\n  PACKAGES_DIR,\n  SHARED_TERRAFORM_DIR,\n  'src',\n  'metrics',\n  'metrics.tf',\n);\n\n// GritQL `within` clause to scope matches to the MetricsAspect class body\nconst WITHIN_METRICS_ASPECT =\n  '$old <: within `class MetricsAspect implements $_ { $_ }`';\n\n// Strip the surrounding quotes from a captured string literal (eg 'g1' or \"g1\")\nconst unquote = (literal: string): string => literal.slice(1, -1);\n\n// Extracts the existing metric tags from the CDK MetricsAspect tags array\nconst readCdkMetricTags = async (tree: Tree): Promise<string[]> =>\n  (\n    await captureAllGritQL(\n      tree,\n      METRICS_ASPECT_FILE_PATH,\n      `\\`$tag\\` where { $tag <: string(), $tag <: within \\`const tags: string[] = $_\\` }`,\n    )\n  ).map(unquote);\n\n// Extracts the existing metric tags from the Terraform metric_tags array\nconst readTerraformMetricTags = async (tree: Tree): Promise<string[]> =>\n  (\n    await captureAllGritQL(\n      tree,\n      TERRAFORM_METRICS_FILE_PATH,\n      '`\"$tag\"` where { $tag <: within `metric_tags = $_` }',\n    )\n  ).map(unquote);\n\n/**\n * Instruments metrics by updating the MetricsAspect in common/constructs/src/core/app.ts if the file exists,\n * and/or updating the Terraform metrics CloudFormation stack if it exists.\n *\n * Both files are converged to the same tag set (the union of tags already\n * present in either file plus the incoming generators). This keeps the tag set\n * deterministic regardless of the order in which metrics files are created\n * across a multi-generator run, so re-running the same set of generators does\n * not grow the tags.\n */\nexport const addGeneratorMetricsIfApplicable = async (\n  tree: Tree,\n  generatorInfo: NxGeneratorInfo[],\n) => {\n  const cdkExists = tree.exists(METRICS_ASPECT_FILE_PATH);\n  const terraformExists = tree.exists(TERRAFORM_METRICS_FILE_PATH);\n\n  if (!cdkExists && !terraformExists) {\n    return;\n  }\n\n  // Converge both files to the union of all known tags so the set is stable\n  // regardless of when each metrics file was created.\n  const tags = [\n    ...new Set([\n      ...(await readCdkMetricTags(tree)),\n      ...(await readTerraformMetricTags(tree)),\n      ...generatorInfo.map((info) => info.metric),\n    ]),\n  ];\n\n  if (cdkExists) {\n    await updateCdkMetrics(tree, tags);\n  }\n\n  if (terraformExists) {\n    await updateTerraformMetrics(tree, tags);\n  }\n};\n\n/**\n * Updates the CDK MetricsAspect with the metric id, version and tags\n */\nconst updateCdkMetrics = async (tree: Tree, tags: string[]) => {\n  // Update the id\n  await applyGritQL(\n    tree,\n    METRICS_ASPECT_FILE_PATH,\n    `\\`const id = $old\\` => \\`const id = '${METRIC_ID}'\\`` +\n      ` where { ${WITHIN_METRICS_ASPECT} }`,\n  );\n\n  // Update the version\n  await applyGritQL(\n    tree,\n    METRICS_ASPECT_FILE_PATH,\n    `\\`const version = $old\\` => \\`const version = '${getPackageVersion()}'\\`` +\n      ` where { ${WITHIN_METRICS_ASPECT} }`,\n  );\n\n  // Add each tag, leaving existing tags in place to keep re-runs stable\n  for (const tag of tags) {\n    await applyGritQL(\n      tree,\n      METRICS_ASPECT_FILE_PATH,\n      `\\`const tags: string[] = $old\\`` +\n        ` where { ${WITHIN_METRICS_ASPECT},` +\n        ` if ($old <: \\`[]\\`) { $old => \\`['${tag}']\\` }` +\n        ` else { $old <: \\`[$items]\\` where { $items += \\`, '${tag}'\\` } },` +\n        ` $old <: not contains \\`'${tag}'\\` }`,\n    );\n  }\n\n  await formatFilesInSubtree(tree, METRICS_ASPECT_FILE_PATH);\n};\n\n/**\n * Updates the Terraform metrics CloudFormation stack with the metric id, version and tags\n */\nconst updateTerraformMetrics = async (tree: Tree, tags: string[]) => {\n  // Update metric_id\n  await applyGritQL(\n    tree,\n    TERRAFORM_METRICS_FILE_PATH,\n    `\\`metric_id = $old\\` => \\`metric_id = \"${METRIC_ID}\"\\``,\n  );\n\n  // Update metric_version\n  await applyGritQL(\n    tree,\n    TERRAFORM_METRICS_FILE_PATH,\n    `\\`metric_version = $old\\` => \\`metric_version = \"${getPackageVersion()}\"\\``,\n  );\n\n  // Add each tag, leaving existing tags in place to keep re-runs stable\n  for (const tag of tags) {\n    await applyGritQL(\n      tree,\n      TERRAFORM_METRICS_FILE_PATH,\n      `or { \\`metric_tags = []\\` => \\`metric_tags = [\"${tag}\"]\\`,` +\n        ` \\`metric_tags = [$items]\\` where { $items += \\`, \"${tag}\"\\` }` +\n        ` where { $items <: not contains \\`\"${tag}\"\\` } }`,\n    );\n  }\n};\n"],"names":["joinPathFragments","applyGritQL","captureAllGritQL","formatFilesInSubtree","getPackageVersion","PACKAGES_DIR","SHARED_CONSTRUCTS_DIR","SHARED_TERRAFORM_DIR","METRIC_ID","METRICS_ASPECT_FILE_PATH","TERRAFORM_METRICS_FILE_PATH","WITHIN_METRICS_ASPECT","unquote","literal","slice","readCdkMetricTags","tree","map","readTerraformMetricTags","addGeneratorMetricsIfApplicable","generatorInfo","cdkExists","exists","terraformExists","tags","Set","info","metric","updateCdkMetrics","updateTerraformMetrics","tag"],"mappings":"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"}

package/src/utils/migration-versions.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { compare } from 'semver';
+/**
+ * Version stamping for migrations.
+ *
+ * A new migration is committed with no `version` — releases are calculated from
+ * conventional commits and written only to `dist/` and a git tag, so versions
+ * reach the published `migrations.json` two ways:
+ *
+ * - At release time (`scripts/stamp-migrations.ts`) entries still missing a
+ *   version are stamped into the compiled `migrations.json`: an already shipped
+ *   one gets the earliest release tag registering it, and a net-new one gets the
+ *   version the release is about to publish, which the release job passes in
+ *   after `nx release version` writes it to the dist manifests.
+ * - The weekly `update-versions` PR backfills the version of the release that
+ *   shipped each migration, moving and re-keying it accordingly
+ *   (`scripts/backfill-migration-versions.ts`), so source converges on the
+ *   versions of everything already released.
+ *
+ * A version already in source always wins, so backfilled entries are stable.
+ */
+export interface MigrationsJson {
+    generators?: Record<string, {
+        version?: string;
+    } & Record<string, unknown>>;
+}
+/** Ascending semver comparator for `Array.prototype.sort`. */
+export declare const compareVersions: typeof compare;
+/** Whether a string is an exact semver version. */
+export declare const isValidVersion: (version: string) => boolean;
+/**
+ * Map of migration key -> version of the earliest release that registers it,
+ * resolved only for the entries still missing a `version` (one already recorded
+ * in source wins, so its history doesn't need reading). A migration that hasn't
+ * been released is absent.
+ *
+ * Walks releases newest first and stops as soon as every entry is resolved: an
+ * entry that has disappeared from a release's `migrations.json` was first
+ * registered by the release after it, which is the one that shipped it.
+ *
+ * @param migrations parsed source migrations.json
+ * @param versions released versions in descending semver order
+ * @param readReleasedMigrations reads the `migrations.json` published by a given
+ *   version, or undefined if it predates the manifest
+ */
+export declare const readShippedMigrationVersions: (migrations: MigrationsJson, versions: string[], readReleasedMigrations: (version: string) => MigrationsJson | undefined) => Record<string, string>;
+/**
+ * Return a copy of the migrations collection with a `version` stamped onto
+ * every generator entry, preserving any already present.
+ *
+ * @param migrations parsed migrations.json to stamp
+ * @param shippedVersions migration key -> version of the earliest release
+ *   tag that registers it (absent for migrations that haven't shipped)
+ * @param pendingVersion version the release is about to publish, stamped onto
+ *   unshipped migrations so their version is one that really shipped
+ */
+export declare const stampMigrationVersions: (migrations: MigrationsJson, shippedVersions: Record<string, string>, pendingVersion: string) => MigrationsJson;
+/** Directory a newly scaffolded migration lands in, before a release claims it. */
+export declare const LATEST_MIGRATIONS_DIR = "latest";
+/** Directory holding the migrations shipped by a given release. */
+export declare const versionMigrationsDir: (version: string) => string;
+/**
+ * Key a migration is registered under in `migrations.json`. Prefixed with its
+ * directory so reusing a name in a later release can't silently overwrite the
+ * one that already shipped.
+ */
+export declare const migrationKey: (dir: string, name: string) => string;
+/** A migration directory move the caller needs to make on disk. */
+export interface MigrationDirMove {
+    name: string;
+    version: string;
+    from: string;
+    to: string;
+}
+/**
+ * Record the release that shipped each migration on entries without a version,
+ * re-keying them and re-pointing their paths at that release's folder, and
+ * return the collection alongside the keys that changed and the directory moves
+ * to make on disk.
+ *
+ * Unlike `stampMigrationVersions` this only records already-released versions,
+ * leaving the release to decide what a net-new migration gets.
+ *
+ * @param migrations parsed migrations.json to backfill
+ * @param shippedVersions migration key -> version of the earliest release tag
+ *   that registers it (absent for migrations that haven't shipped)
+ */
+export declare const backfillMigrationVersions: (migrations: MigrationsJson, shippedVersions: Record<string, string>) => {
+    migrations: MigrationsJson;
+    backfilled: string[];
+    moves: MigrationDirMove[];
+};

package/src/utils/migration-versions.js

@@ -0,0 +1,128 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { compare, valid } from "semver";
+/** Ascending semver comparator for `Array.prototype.sort`. */ export const compareVersions = compare;
+/** Whether a string is an exact semver version. */ export const isValidVersion = (version)=>valid(version) !== null;
+/**
+ * Map of migration key -> version of the earliest release that registers it,
+ * resolved only for the entries still missing a `version` (one already recorded
+ * in source wins, so its history doesn't need reading). A migration that hasn't
+ * been released is absent.
+ *
+ * Walks releases newest first and stops as soon as every entry is resolved: an
+ * entry that has disappeared from a release's `migrations.json` was first
+ * registered by the release after it, which is the one that shipped it.
+ *
+ * @param migrations parsed source migrations.json
+ * @param versions released versions in descending semver order
+ * @param readReleasedMigrations reads the `migrations.json` published by a given
+ *   version, or undefined if it predates the manifest
+ */ export const readShippedMigrationVersions = (migrations, versions, readReleasedMigrations)=>{
+    const shippedVersions = {};
+    let unresolved = Object.entries(migrations.generators ?? {}).filter(([, entry])=>!entry.version).map(([key])=>key);
+    for (const version of versions){
+        if (unresolved.length === 0) {
+            break;
+        }
+        const registered = new Set(Object.keys(readReleasedMigrations(version)?.generators ?? {}));
+        // Entries gone at this release keep the version recorded from the release
+        // after it (if any) and stop being looked up.
+        unresolved = unresolved.filter((key)=>registered.has(key));
+        for (const key of unresolved){
+            shippedVersions[key] = version;
+        }
+    }
+    return shippedVersions;
+};
+/**
+ * Return a copy of the migrations collection with a `version` stamped onto
+ * every generator entry, preserving any already present.
+ *
+ * @param migrations parsed migrations.json to stamp
+ * @param shippedVersions migration key -> version of the earliest release
+ *   tag that registers it (absent for migrations that haven't shipped)
+ * @param pendingVersion version the release is about to publish, stamped onto
+ *   unshipped migrations so their version is one that really shipped
+ */ export const stampMigrationVersions = (migrations, shippedVersions, pendingVersion)=>({
+        ...migrations,
+        generators: Object.fromEntries(Object.entries(migrations.generators ?? {}).map(([name, entry])=>[
+                name,
+                {
+                    version: shippedVersions[name] ?? pendingVersion,
+                    ...entry
+                }
+            ]))
+    });
+/** Directory a newly scaffolded migration lands in, before a release claims it. */ export const LATEST_MIGRATIONS_DIR = 'latest';
+/** Directory holding the migrations shipped by a given release. */ export const versionMigrationsDir = (version)=>`v${version}`;
+/**
+ * Key a migration is registered under in `migrations.json`. Prefixed with its
+ * directory so reusing a name in a later release can't silently overwrite the
+ * one that already shipped.
+ */ export const migrationKey = (dir, name)=>`${dir}-${name}`;
+const LATEST_KEY_PREFIX = `${LATEST_MIGRATIONS_DIR}-`;
+/**
+ * Record the release that shipped each migration on entries without a version,
+ * re-keying them and re-pointing their paths at that release's folder, and
+ * return the collection alongside the keys that changed and the directory moves
+ * to make on disk.
+ *
+ * Unlike `stampMigrationVersions` this only records already-released versions,
+ * leaving the release to decide what a net-new migration gets.
+ *
+ * @param migrations parsed migrations.json to backfill
+ * @param shippedVersions migration key -> version of the earliest release tag
+ *   that registers it (absent for migrations that haven't shipped)
+ */ export const backfillMigrationVersions = (migrations, shippedVersions)=>{
+    const generators = {};
+    const backfilled = [];
+    const moves = [];
+    for (const [key, entry] of Object.entries(migrations.generators ?? {})){
+        const version = shippedVersions[key];
+        if (entry.version || !version) {
+            generators[key] = entry;
+            continue;
+        }
+        const name = key.startsWith(LATEST_KEY_PREFIX) ? key.slice(LATEST_KEY_PREFIX.length) : key;
+        const versionDir = versionMigrationsDir(version);
+        const latestSegment = `/${LATEST_MIGRATIONS_DIR}/${name}/`;
+        const versionSegment = `/${versionDir}/${name}/`;
+        // Re-point each path field at the version folder, recording the move the
+        // caller needs to make on disk the first time one is found.
+        const repointed = {};
+        let moved = false;
+        for (const [field, value] of Object.entries(entry)){
+            if (typeof value !== 'string' || !value.includes(latestSegment)) {
+                repointed[field] = value;
+                continue;
+            }
+            repointed[field] = value.replace(latestSegment, versionSegment);
+            if (!moved) {
+                moved = true;
+                const dir = value.slice(0, value.indexOf(latestSegment));
+                moves.push({
+                    name,
+                    version,
+                    from: `${dir}${latestSegment}`.replace(/^\.\/|\/$/g, ''),
+                    to: `${dir}${versionSegment}`.replace(/^\.\/|\/$/g, '')
+                });
+            }
+        }
+        generators[migrationKey(versionDir, name)] = {
+            version,
+            ...repointed
+        };
+        backfilled.push(key);
+    }
+    return {
+        migrations: {
+            ...migrations,
+            generators
+        },
+        backfilled,
+        moves
+    };
+};
+
+//# sourceMappingURL=migration-versions.js.map

package/src/utils/migration-versions.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../packages/nx-plugin/src/utils/migration-versions.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport { compare, valid } from 'semver';\n\n/**\n * Version stamping for migrations.\n *\n * A new migration is committed with no `version` — releases are calculated from\n * conventional commits and written only to `dist/` and a git tag, so versions\n * reach the published `migrations.json` two ways:\n *\n * - At release time (`scripts/stamp-migrations.ts`) entries still missing a\n *   version are stamped into the compiled `migrations.json`: an already shipped\n *   one gets the earliest release tag registering it, and a net-new one gets the\n *   version the release is about to publish, which the release job passes in\n *   after `nx release version` writes it to the dist manifests.\n * - The weekly `update-versions` PR backfills the version of the release that\n *   shipped each migration, moving and re-keying it accordingly\n *   (`scripts/backfill-migration-versions.ts`), so source converges on the\n *   versions of everything already released.\n *\n * A version already in source always wins, so backfilled entries are stable.\n */\n\nexport interface MigrationsJson {\n  generators?: Record<string, { version?: string } & Record<string, unknown>>;\n}\n\n/** Ascending semver comparator for `Array.prototype.sort`. */\nexport const compareVersions = compare;\n\n/** Whether a string is an exact semver version. */\nexport const isValidVersion = (version: string): boolean =>\n  valid(version) !== null;\n\n/**\n * Map of migration key -> version of the earliest release that registers it,\n * resolved only for the entries still missing a `version` (one already recorded\n * in source wins, so its history doesn't need reading). A migration that hasn't\n * been released is absent.\n *\n * Walks releases newest first and stops as soon as every entry is resolved: an\n * entry that has disappeared from a release's `migrations.json` was first\n * registered by the release after it, which is the one that shipped it.\n *\n * @param migrations parsed source migrations.json\n * @param versions released versions in descending semver order\n * @param readReleasedMigrations reads the `migrations.json` published by a given\n *   version, or undefined if it predates the manifest\n */\nexport const readShippedMigrationVersions = (\n  migrations: MigrationsJson,\n  versions: string[],\n  readReleasedMigrations: (version: string) => MigrationsJson | undefined,\n): Record<string, string> => {\n  const shippedVersions: Record<string, string> = {};\n  let unresolved = Object.entries(migrations.generators ?? {})\n    .filter(([, entry]) => !entry.version)\n    .map(([key]) => key);\n\n  for (const version of versions) {\n    if (unresolved.length === 0) {\n      break;\n    }\n    const registered = new Set(\n      Object.keys(readReleasedMigrations(version)?.generators ?? {}),\n    );\n    // Entries gone at this release keep the version recorded from the release\n    // after it (if any) and stop being looked up.\n    unresolved = unresolved.filter((key) => registered.has(key));\n    for (const key of unresolved) {\n      shippedVersions[key] = version;\n    }\n  }\n\n  return shippedVersions;\n};\n\n/**\n * Return a copy of the migrations collection with a `version` stamped onto\n * every generator entry, preserving any already present.\n *\n * @param migrations parsed migrations.json to stamp\n * @param shippedVersions migration key -> version of the earliest release\n *   tag that registers it (absent for migrations that haven't shipped)\n * @param pendingVersion version the release is about to publish, stamped onto\n *   unshipped migrations so their version is one that really shipped\n */\nexport const stampMigrationVersions = (\n  migrations: MigrationsJson,\n  shippedVersions: Record<string, string>,\n  pendingVersion: string,\n): MigrationsJson => ({\n  ...migrations,\n  generators: Object.fromEntries(\n    Object.entries(migrations.generators ?? {}).map(([name, entry]) => [\n      name,\n      { version: shippedVersions[name] ?? pendingVersion, ...entry },\n    ]),\n  ),\n});\n\n/** Directory a newly scaffolded migration lands in, before a release claims it. */\nexport const LATEST_MIGRATIONS_DIR = 'latest';\n\n/** Directory holding the migrations shipped by a given release. */\nexport const versionMigrationsDir = (version: string) => `v${version}`;\n\n/**\n * Key a migration is registered under in `migrations.json`. Prefixed with its\n * directory so reusing a name in a later release can't silently overwrite the\n * one that already shipped.\n */\nexport const migrationKey = (dir: string, name: string) => `${dir}-${name}`;\n\nconst LATEST_KEY_PREFIX = `${LATEST_MIGRATIONS_DIR}-`;\n\n/** A migration directory move the caller needs to make on disk. */\nexport interface MigrationDirMove {\n  name: string;\n  version: string;\n  from: string;\n  to: string;\n}\n\n/**\n * Record the release that shipped each migration on entries without a version,\n * re-keying them and re-pointing their paths at that release's folder, and\n * return the collection alongside the keys that changed and the directory moves\n * to make on disk.\n *\n * Unlike `stampMigrationVersions` this only records already-released versions,\n * leaving the release to decide what a net-new migration gets.\n *\n * @param migrations parsed migrations.json to backfill\n * @param shippedVersions migration key -> version of the earliest release tag\n *   that registers it (absent for migrations that haven't shipped)\n */\nexport const backfillMigrationVersions = (\n  migrations: MigrationsJson,\n  shippedVersions: Record<string, string>,\n): {\n  migrations: MigrationsJson;\n  backfilled: string[];\n  moves: MigrationDirMove[];\n} => {\n  const generators: NonNullable<MigrationsJson['generators']> = {};\n  const backfilled: string[] = [];\n  const moves: MigrationDirMove[] = [];\n\n  for (const [key, entry] of Object.entries(migrations.generators ?? {})) {\n    const version = shippedVersions[key];\n    if (entry.version || !version) {\n      generators[key] = entry;\n      continue;\n    }\n\n    const name = key.startsWith(LATEST_KEY_PREFIX)\n      ? key.slice(LATEST_KEY_PREFIX.length)\n      : key;\n    const versionDir = versionMigrationsDir(version);\n    const latestSegment = `/${LATEST_MIGRATIONS_DIR}/${name}/`;\n    const versionSegment = `/${versionDir}/${name}/`;\n\n    // Re-point each path field at the version folder, recording the move the\n    // caller needs to make on disk the first time one is found.\n    const repointed: Record<string, unknown> = {};\n    let moved = false;\n    for (const [field, value] of Object.entries(entry)) {\n      if (typeof value !== 'string' || !value.includes(latestSegment)) {\n        repointed[field] = value;\n        continue;\n      }\n      repointed[field] = value.replace(latestSegment, versionSegment);\n      if (!moved) {\n        moved = true;\n        const dir = value.slice(0, value.indexOf(latestSegment));\n        moves.push({\n          name,\n          version,\n          from: `${dir}${latestSegment}`.replace(/^\\.\\/|\\/$/g, ''),\n          to: `${dir}${versionSegment}`.replace(/^\\.\\/|\\/$/g, ''),\n        });\n      }\n    }\n\n    generators[migrationKey(versionDir, name)] = { version, ...repointed };\n    backfilled.push(key);\n  }\n\n  return { migrations: { ...migrations, generators }, backfilled, moves };\n};\n"],"names":["compare","valid","compareVersions","isValidVersion","version","readShippedMigrationVersions","migrations","versions","readReleasedMigrations","shippedVersions","unresolved","Object","entries","generators","filter","entry","map","key","length","registered","Set","keys","has","stampMigrationVersions","pendingVersion","fromEntries","name","LATEST_MIGRATIONS_DIR","versionMigrationsDir","migrationKey","dir","LATEST_KEY_PREFIX","backfillMigrationVersions","backfilled","moves","startsWith","slice","versionDir","latestSegment","versionSegment","repointed","moved","field","value","includes","replace","indexOf","push","from","to"],"mappings":"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"}

package/src/utils/mock-project-graph.js

@@ -1,10 +1,7 @@
-"use strict";
 /**
  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  * SPDX-License-Identifier: Apache-2.0
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-/**
+ */ /**
  * Mock createProjectGraphAsync to avoid expensive project graph building in tests.
  *
  * This is the vitest equivalent of Nx's own internal testing utility:
@@ -15,13 +12,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * 2. @nx/devkit's exports are wrapped with read-only getters by vitest
  * 3. The CJS module at nx/src/project-graph/project-graph.js is the actual
  *    implementation that @nx/devkit re-exports
- */
-const module_1 = require("module");
-// @ts-expect-error test utility used by vite only
-const _require = (0, module_1.createRequire)(import.meta.url);
+ */ import { createRequire } from "module";
+const _require = createRequire(import.meta.url);
 const projectGraph = _require('nx/src/project-graph/project-graph');
-projectGraph.createProjectGraphAsync = async () => ({
-    nodes: {},
-    dependencies: {},
-});
+projectGraph.createProjectGraphAsync = async ()=>({
+        nodes: {},
+        dependencies: {}
+    });
+
 //# sourceMappingURL=mock-project-graph.js.map