chore: rewrite readmes correctly in aws-cdk-lib and monocdk (backport #17573) (#17635)

This is an automatic backport of pull request #17573 done by [Mergify](https://mergify.com).
Cherry-pick of 66e37cc has failed:
```
On branch mergify/bp/master/pr-17573
Your branch is up to date with 'origin/master'.

You are currently cherry-picking commit 66e37cc.
  (fix conflicts and run "git cherry-pick --continue")
  (use "git cherry-pick --skip" to skip this patch)
  (use "git cherry-pick --abort" to cancel the cherry-pick operation)

Changes to be committed:
	modified:   packages/@aws-cdk/cfnspec/test/libary-creation.test.ts
	modified:   packages/aws-cdk-lib/.gitignore
	modified:   packages/aws-cdk-lib/package.json
	modified:   packages/aws-cdk-lib/scripts/verify-imports-resolve-same.ts
	deleted:    packages/aws-cdk-lib/scripts/verify-readme-import-rewrites.ts
	modified:   packages/aws-cdk-migration/bin/rewrite-imports-v2.ts
	modified:   packages/aws-cdk-migration/lib/rewrite.ts
	modified:   packages/aws-cdk-migration/test/rewrite.test.ts
	modified:   packages/monocdk/.gitignore
	modified:   tools/@aws-cdk/cdk-build-tools/bin/cdk-build.ts
	modified:   tools/@aws-cdk/individual-pkg-gen/transform-packages.ts
	modified:   tools/@aws-cdk/ubergen/bin/ubergen.ts
	modified:   tools/@aws-cdk/ubergen/package.json

Unmerged paths:
  (use "git add <file>..." to mark resolution)
	both modified:   packages/@aws-cdk/cfnspec/lib/library-creation.ts

```


To fix up this pull request, you can check it out locally. See documentation: https://docs.github.com/en/github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally

---


<details>
<summary>Mergify commands and options</summary>

<br />

More conditions and actions can be found in the [documentation](https://docs.mergify.com/).

You can also trigger Mergify actions by commenting on this pull request:

- `@Mergifyio refresh` will re-evaluate the rules
- `@Mergifyio rebase` will rebase this PR on its base branch
- `@Mergifyio update` will merge the base branch into this PR
- `@Mergifyio backport <destination>` will backport this PR on `<destination>` branch

Additionally, on Mergify [dashboard](https://dashboard.mergify.com/) you can:

- look at your merge queues
- generate the Mergify configuration with the config editor.

Finally, you can contact us on https://mergify.com
</details>

Author: mergify[bot]

packages/@aws-cdk/cfnspec/lib/library-creation.ts

@@ -76,7 +76,7 @@ export async function createLibraryReadme(namespace: string, readmePath: string)
     'This module is part of the [AWS Cloud Development Kit](https://github.com/aws/aws-cdk) project.',
     '',
     '```ts nofixture',
-    `import ${module.moduleName.toLocaleLowerCase()} = require('${module.packageName}');`,
+    `import * as ${module.moduleName.toLocaleLowerCase().replace(/[^a-z0-9_]/g, '_')} from '${module.packageName}';`,
     '```',
     '',
   ].join('\n'), 'utf8');

packages/@aws-cdk/cfnspec/test/libary-creation.test.ts

@@ -1,7 +1,8 @@
-import { createModuleDefinitionFromCfnNamespace } from '../lib';
+import * as path from 'path';
+import * as fs from 'fs-extra';
+import { createModuleDefinitionFromCfnNamespace, createLibraryReadme } from '../lib';
 
 describe('createModuleDefinitionFromCfnNamespace', () => {
-
   test('base case', () => {
     const module = createModuleDefinitionFromCfnNamespace('AWS::EC2');
 
@@ -55,5 +56,15 @@ describe('createModuleDefinitionFromCfnNamespace', () => {
       pythonModuleName: 'aws_cdk.alexa_ask',
     });
   });
+});
 
+describe('createLibraryReadme', () => {
+  test('library name is valid', async () => {
+    const tempDir = fs.mkdtempSync(path.join(__dirname, 'temp'));
+    const readmePath = path.join(tempDir, 'README.md');
+    await createLibraryReadme('Alexa::ASK', readmePath);
+
+    const readme = fs.readFileSync(readmePath, { encoding: 'utf8' });
+    expect(readme).toContain("import * as alexa_ask from '@aws-cdk/alexa-ask';");
+  });
 });

packages/aws-cdk-lib/.gitignore

@@ -5,7 +5,7 @@
 !LICENSE
 !NOTICE
 !README.md
-!scripts/*
+!scripts/
 
 .LAST_BUILD
 *.snk

packages/aws-cdk-lib/package.json

@@ -38,8 +38,7 @@
     },
     "stripDeprecated": true,
     "post": [
-      "node ./scripts/verify-readme-import-rewrites.js",
-      "node ./scripts/verify-import-resolve-same.js"
+      "node ./scripts/verify-imports-resolve-same.js"
     ]
   },
   "cdk-package": {

packages/aws-cdk-lib/scripts/verify-imports-resolve-same.ts

@@ -84,7 +84,7 @@ async function compileAndResolve(fileName: string, contents: string, symbolName:
   }
 
   // Return the filename
-  const srcFile = sym.declarations?.[0].getSourceFile().fileName;
+  const srcFile = sym.declarations?.[0].getSourceFile().fileName.replace(/.ts|.js|.d.ts/, '');
   if (!srcFile) {
     console.log(sym);
     throw new Error(`Symbol ${symbolName} in '${contents}' does not resolve to a source location`);

packages/aws-cdk-lib/scripts/verify-readme-import-rewrites.ts

@@ -3,7 +3,7 @@ import * as fs from 'fs';
 import { promisify } from 'util';
 import * as _glob from 'glob';
 
-import { rewriteImports } from '../lib/rewrite';
+import { rewriteMonoPackageImports } from '../lib/rewrite';
 
 const glob = promisify(_glob);
 
@@ -23,7 +23,7 @@ async function main() {
     const files = await glob(arg, { ignore, matchBase: true });
     for (const file of files) {
       const input = await fs.promises.readFile(file, { encoding: 'utf8' });
-      const output = rewriteImports(input, file);
+      const output = rewriteMonoPackageImports(input, 'aws-cdk-lib', file);
       if (output.trim() !== input.trim()) {
         await fs.promises.writeFile(file, output);
       }

packages/aws-cdk-migration/bin/rewrite-imports-v2.ts

@@ -42,18 +42,79 @@ export interface RewriteOptions {
  * - `require('@aws-cdk/lib');
  *
  * @param sourceText the source code where imports should be re-written.
+ * @param libName the mono CDK library name.
  * @param fileName   a customized file name to provide the TypeScript processor.
  *
  * @returns the updated source code.
  */
-export function rewriteImports(sourceText: string, fileName: string = 'index.ts', options: RewriteOptions = {}): string {
+export function rewriteMonoPackageImports(sourceText: string, libName: string, fileName: string = 'index.ts', options: RewriteOptions = {}): string {
+  return rewriteImports(sourceText, (modPath, importedElements) => updatedExternalLocation(modPath, libName, options, importedElements), fileName);
+}
+
+/**
+ * Re-writes READMEs of "hyper-modular" CDK imports (most packages in `@aws-cdk/*`)
+ * to the relevant "mono" CDK import path. The re-writing will only modify the imported
+ * library path, presrving the existing quote style, etc...
+ *
+ * Syntax errors in the README snippets being processed may cause some import
+ * statements to not be re-written.
+ *
+ * Supported import statement forms are:
+ * - `import * as lib from '@aws-cdk/lib';`
+ * - `import { Type } from '@aws-cdk/lib';`
+ * - `import '@aws-cdk/lib';`
+ * - `import lib = require('@aws-cdk/lib');`
+ * - `import { Type } = require('@aws-cdk/lib');
+ * - `require('@aws-cdk/lib');
+ *
+ * @param sourceText the README where snippet imports should be re-written.
+ * @param libName the mono CDK library name.
+ * @param fileName   a customized file name to provide the TypeScript processor.
+ *
+ * @returns the updated source code.
+ */
+export function rewriteReadmeImports(sourceText: string, libName: string, fileName: string = 'index.ts', options: RewriteOptions = {}): string {
+  return sourceText.replace(/(```(?:ts|typescript|text)[^\n]*\n)(.*?)(\n\s*```)/gs, (_m, prefix, body, suffix) => {
+    return prefix +
+      rewriteImports(body, (modPath, importedElements) => updatedExternalLocation(modPath, libName, options, importedElements), fileName) +
+      suffix;
+  });
+}
+
+/**
+ * Re-writes "hyper-modular" CDK imports (most packages in `@aws-cdk/*`) to the
+ * relevant "mono" CDK import path. The re-writing will only modify the imported
+ * library path, presrving the existing quote style, etc...
+ *
+ * Syntax errors in the source file being processed may cause some import
+ * statements to not be re-written.
+ *
+ * Supported import statement forms are:
+ * - `import * as lib from '@aws-cdk/lib';`
+ * - `import { Type } from '@aws-cdk/lib';`
+ * - `import '@aws-cdk/lib';`
+ * - `import lib = require('@aws-cdk/lib');`
+ * - `import { Type } = require('@aws-cdk/lib');
+ * - `require('@aws-cdk/lib');
+ *
+ * @param sourceText         the source code where imports should be re-written.
+ * @param updatedLocation    a function that returns the updated location of the import.
+ * @param fileName           a customized file name to provide the TypeScript processor.
+ *
+ * @returns the updated source code.
+ */
+export function rewriteImports(
+  sourceText: string,
+  updatedLocation: (modulePath: string, importedElements?: ts.NodeArray<ts.ImportSpecifier>) => string | undefined,
+  fileName: string = 'index.ts',
+): string {
   const sourceFile = ts.createSourceFile(fileName, sourceText, ts.ScriptTarget.ES2018);
 
   const replacements = new Array<{ original: ts.Node, updatedLocation: string }>();
 
   const visitor = <T extends ts.Node>(node: T): ts.VisitResult<T> => {
     const moduleSpecifier = getModuleSpecifier(node);
-    const newTarget = moduleSpecifier && updatedLocationOf(moduleSpecifier.text, options, getImportedElements(node));
+    const newTarget = moduleSpecifier && updatedLocation(moduleSpecifier.text, getImportedElements(node));
 
     if (moduleSpecifier != null && newTarget != null) {
       replacements.push({ original: moduleSpecifier, updatedLocation: newTarget });
@@ -131,15 +192,20 @@ const EXEMPTIONS = new Set([
   '@aws-cdk/pkglint',
 ]);
 
-function updatedLocationOf(modulePath: string, options: RewriteOptions, importedElements?: ts.NodeArray<ts.ImportSpecifier>): string | undefined {
+function updatedExternalLocation(
+  modulePath: string,
+  libName: string,
+  options: RewriteOptions,
+  importedElements?: ts.NodeArray<ts.ImportSpecifier>,
+): string | undefined {
   const customModulePath = options.customModules?.[modulePath];
   if (customModulePath) {
     let awsCdkLibLocation = undefined;
     importedElements?.forEach(e => {
       if (e.name.text.startsWith('Cfn') || e.propertyName?.text.startsWith('Cfn')) {
         // This is an L1 import, so don't return the customModulePath (which is the alpha module).
         // Return the relevant aws-cdk-lib location.
-        awsCdkLibLocation = `aws-cdk-lib/${modulePath.substring('@aws-cdk/'.length)}`;
+        awsCdkLibLocation = `${libName}/${modulePath.substring('@aws-cdk/'.length)}`;
       }
     });
     if (awsCdkLibLocation) {
@@ -149,7 +215,7 @@ function updatedLocationOf(modulePath: string, options: RewriteOptions, imported
   }
 
   if (options.rewriteCfnImports && modulePath.endsWith(`${options.packageUnscopedName?.substr('aws-'.length)}.generated`)) {
-    return `aws-cdk-lib/${options.packageUnscopedName}`;
+    return `${libName}/${options.packageUnscopedName}`;
   }
 
   if (
@@ -161,11 +227,11 @@ function updatedLocationOf(modulePath: string, options: RewriteOptions, imported
   }
 
   if (modulePath.startsWith('@aws-cdk/core/lib')) {
-    return `aws-cdk-lib/lib/core/lib/${modulePath.substring('@aws-cdk/core/lib/'.length)}`;
+    return `${libName}/core/lib/${modulePath.substring('@aws-cdk/core/lib/'.length)}`;
   }
 
   if (modulePath === '@aws-cdk/core') {
-    return 'aws-cdk-lib';
+    return libName;
   }
 
   // These 2 are unchanged
@@ -183,7 +249,7 @@ function updatedLocationOf(modulePath: string, options: RewriteOptions, imported
     return '@aws-cdk/assert/jest';
   }
 
-  return `aws-cdk-lib/${modulePath.substring('@aws-cdk/'.length)}`;
+  return `${libName}/${modulePath.substring('@aws-cdk/'.length)}`;
 }
 
 /**