chore: rewrite readmes correctly in aws-cdk-lib and monocdk

packages/@monocdk-experiment/rewrite-imports/lib/rewrite.ts

@@ -88,6 +88,44 @@ export function rewriteImports(sourceText: string, fileName: string = 'index.ts'
   }
 }
 
+/**
+ * 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 fileName   a customized file name to provide the TypeScript processor.
+ *
+ * @returns the updated source code.
+ */
+export function rewriteReadmeImports(sourceText: string, fileName: string = 'index.ts'): string {
+  let updatedSourceText = sourceText;
+  // Search for readme code snippets
+  // we sometimes use 'text' for typescript only snippets, so their imports should be translated as well.
+  let snippets = sourceText.match(/```(ts|typescript|text)([\S\s]*?)```/g);
+  for (const snip of snippets ?? []) {
+    const lines = snip.split('\n');
+    // remove '```ts' and '```'
+    const snipCode = lines.splice(1, lines.length-2).join('\n');
+    const rewrittenSnipCode = rewriteImports(snipCode, fileName);
+    if (snipCode !== rewrittenSnipCode) {
+      updatedSourceText = updatedSourceText.replace(snipCode, rewrittenSnipCode);
+    }
+  }
+  return updatedSourceText;
+}
+
 const EXEMPTIONS = new Set([
   '@aws-cdk/cloudformation-diff',
 ]);

packages/@monocdk-experiment/rewrite-imports/test/rewrite.test.ts

@@ -1,4 +1,4 @@
-import { rewriteImports } from '../lib/rewrite';
+import { rewriteImports, rewriteReadmeImports } from '../lib/rewrite';
 
 describe(rewriteImports, () => {
   test('correctly rewrites naked "import"', () => {
@@ -73,3 +73,97 @@ describe(rewriteImports, () => {
   console.log('Look! I did something!');`);
   });
 });
+
+describe(rewriteReadmeImports, () => {
+  test('parses ts code snippet', () => {
+    const output = rewriteReadmeImports(`
+    Some README text.
+    \`\`\`ts
+    import * as s3 from '@aws-cdk/aws-s3';
+    import { Construct } from "@aws-cdk/core";
+    \`\`\`
+    Some more README text.`, 'subject.ts');
+
+    expect(output).toBe(`
+    Some README text.
+    \`\`\`ts
+    import * as s3 from 'monocdk/aws-s3';
+    import { Construct } from "monocdk";
+    \`\`\`
+    Some more README text.`);
+  });
+
+  test('parses typescript code snippet', () => {
+    const output = rewriteReadmeImports(`
+    Some README text.
+    \`\`\`typescript
+    import * as s3 from '@aws-cdk/aws-s3';
+    import { Construct } from "@aws-cdk/core";
+    \`\`\`
+    Some more README text.`, 'subject.ts');
+
+    expect(output).toBe(`
+    Some README text.
+    \`\`\`typescript
+    import * as s3 from 'monocdk/aws-s3';
+    import { Construct } from "monocdk";
+    \`\`\`
+    Some more README text.`);
+  });
+
+  test('parses text code snippet', () => {
+    const output = rewriteReadmeImports(`
+    Some README text.
+    \`\`\`text
+    import * as s3 from '@aws-cdk/aws-s3';
+    import { Construct } from "@aws-cdk/core";
+    \`\`\`
+    Some more README text.`, 'subject.ts');
+
+    expect(output).toBe(`
+    Some README text.
+    \`\`\`text
+    import * as s3 from 'monocdk/aws-s3';
+    import { Construct } from "monocdk";
+    \`\`\`
+    Some more README text.`);
+  });
+
+  test('ignores non ts|typescript|text code snippet', () => {
+    const output = rewriteReadmeImports(`
+    Some README text.
+    \`\`\`java
+    import * as s3 from '@aws-cdk/aws-s3';
+    \`\`\`
+    Some more README text.`, 'subject.ts');
+
+    expect(output).toBe(`
+    Some README text.
+    \`\`\`java
+    import * as s3 from '@aws-cdk/aws-s3';
+    \`\`\`
+    Some more README text.`);
+  });
+
+  test('parses multiple snippets', () => {
+    const output = rewriteReadmeImports(`
+    Some README text.
+    \`\`\`ts
+    import * as s3 from '@aws-cdk/aws-s3';
+    \`\`\`
+    Some more README text.
+    \`\`\`ts
+    import { CfnDeliveryStream } from '@aws-cdk/aws-kinesisfirehose';
+    \`\`\``, 'subject.ts');
+
+    expect(output).toBe(`
+    Some README text.
+    \`\`\`ts
+    import * as s3 from 'monocdk/aws-s3';
+    \`\`\`
+    Some more README text.
+    \`\`\`ts
+    import { CfnDeliveryStream } from 'monocdk/aws-kinesisfirehose';
+    \`\`\``);
+  });
+});

packages/aws-cdk-migration/lib/rewrite.ts

@@ -121,6 +121,44 @@ export function rewriteImports(sourceText: string, fileName: string = 'index.ts'
   }
 }
 
+/**
+ * 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 fileName   a customized file name to provide the TypeScript processor.
+ *
+ * @returns the updated source code.
+ */
+export function rewriteReadmeImports(sourceText: string, fileName: string = 'index.ts', options: RewriteOptions = {}): string {
+  let updatedSourceText = sourceText;
+  // Search for readme code snippets
+  // we sometimes use 'text' for typescript only snippets, so their imports should be translated as well.
+  let snippets = sourceText.match(/```(ts|typescript|text)([\S\s]*?)```/g);
+  for (const snip of snippets ?? []) {
+    const lines = snip.split('\n');
+    // remove '```ts' and '```'
+    const snipCode = lines.splice(1, lines.length-2).join('\n');
+    const rewrittenSnipCode = rewriteImports(snipCode, fileName, options);
+    if (snipCode !== rewrittenSnipCode) {
+      updatedSourceText = updatedSourceText.replace(snipCode, rewrittenSnipCode);
+    }
+  }
+  return updatedSourceText;
+}
+
 const EXEMPTIONS = new Set([
   '@aws-cdk/cloudformation-diff',
   // The dev-tools

packages/aws-cdk-migration/test/rewrite.test.ts

@@ -1,4 +1,4 @@
-import { rewriteImports } from '../lib/rewrite';
+import { rewriteImports, rewriteReadmeImports } from '../lib/rewrite';
 
 describe(rewriteImports, () => {
   test('correctly rewrites naked "import"', () => {
@@ -35,42 +35,42 @@ describe(rewriteImports, () => {
 
   test('correctly rewrites "import from"', () => {
     const output = rewriteImports(`
-  // something before
-  import * as s3 from '@aws-cdk/aws-s3';
-  import * as cfndiff from '@aws-cdk/cloudformation-diff';
-  import { Construct } from "@aws-cdk/core";
-  // something after
+    // something before
+    import * as s3 from '@aws-cdk/aws-s3';
+    import * as cfndiff from '@aws-cdk/cloudformation-diff';
+    import { Construct } from "@aws-cdk/core";
+    // something after
 
-  console.log('Look! I did something!');`, 'subject.ts');
+    console.log('Look! I did something!');`, 'subject.ts');
 
     expect(output).toBe(`
-  // something before
-  import * as s3 from 'aws-cdk-lib/aws-s3';
-  import * as cfndiff from '@aws-cdk/cloudformation-diff';
-  import { Construct } from "aws-cdk-lib";
-  // something after
+    // something before
+    import * as s3 from 'aws-cdk-lib/aws-s3';
+    import * as cfndiff from '@aws-cdk/cloudformation-diff';
+    import { Construct } from "aws-cdk-lib";
+    // something after
 
-  console.log('Look! I did something!');`);
+    console.log('Look! I did something!');`);
   });
 
   test('correctly rewrites "import = require"', () => {
     const output = rewriteImports(`
-  // something before
-  import s3 = require('@aws-cdk/aws-s3');
-  import cfndiff = require('@aws-cdk/cloudformation-diff');
-  import { Construct } = require("@aws-cdk/core");
-  // something after
+    // something before
+    import s3 = require('@aws-cdk/aws-s3');
+    import cfndiff = require('@aws-cdk/cloudformation-diff');
+    import { Construct } = require("@aws-cdk/core");
+    // something after
 
-  console.log('Look! I did something!');`, 'subject.ts');
+    console.log('Look! I did something!');`, 'subject.ts');
 
     expect(output).toBe(`
-  // something before
-  import s3 = require('aws-cdk-lib/aws-s3');
-  import cfndiff = require('@aws-cdk/cloudformation-diff');
-  import { Construct } = require("aws-cdk-lib");
-  // something after
+    // something before
+    import s3 = require('aws-cdk-lib/aws-s3');
+    import cfndiff = require('@aws-cdk/cloudformation-diff');
+    import { Construct } = require("aws-cdk-lib");
+    // something after
 
-  console.log('Look! I did something!');`);
+    console.log('Look! I did something!');`);
   });
 
   test('does not rewrite @aws-cdk/assert', () => {
@@ -137,3 +137,97 @@ describe(rewriteImports, () => {
     console.log('Look! I did something!');`);
   });
 });
+
+describe(rewriteReadmeImports, () => {
+  test('parses ts code snippet', () => {
+    const output = rewriteReadmeImports(`
+    Some README text.
+    \`\`\`ts
+    import * as s3 from '@aws-cdk/aws-s3';
+    import { Construct } from "@aws-cdk/core";
+    \`\`\`
+    Some more README text.`, 'subject.ts');
+
+    expect(output).toBe(`
+    Some README text.
+    \`\`\`ts
+    import * as s3 from 'aws-cdk-lib/aws-s3';
+    import { Construct } from "aws-cdk-lib";
+    \`\`\`
+    Some more README text.`);
+  });
+
+  test('parses typescript code snippet', () => {
+    const output = rewriteReadmeImports(`
+    Some README text.
+    \`\`\`typescript
+    import * as s3 from '@aws-cdk/aws-s3';
+    import { Construct } from "@aws-cdk/core";
+    \`\`\`
+    Some more README text.`, 'subject.ts');
+
+    expect(output).toBe(`
+    Some README text.
+    \`\`\`typescript
+    import * as s3 from 'aws-cdk-lib/aws-s3';
+    import { Construct } from "aws-cdk-lib";
+    \`\`\`
+    Some more README text.`);
+  });
+
+  test('parses text code snippet', () => {
+    const output = rewriteReadmeImports(`
+    Some README text.
+    \`\`\`text
+    import * as s3 from '@aws-cdk/aws-s3';
+    import { Construct } from "@aws-cdk/core";
+    \`\`\`
+    Some more README text.`, 'subject.ts');
+
+    expect(output).toBe(`
+    Some README text.
+    \`\`\`text
+    import * as s3 from 'aws-cdk-lib/aws-s3';
+    import { Construct } from "aws-cdk-lib";
+    \`\`\`
+    Some more README text.`);
+  });
+
+  test('ignores non ts|typescript|text code snippet', () => {
+    const output = rewriteReadmeImports(`
+    Some README text.
+    \`\`\`java
+    import * as s3 from '@aws-cdk/aws-s3';
+    \`\`\`
+    Some more README text.`, 'subject.ts');
+
+    expect(output).toBe(`
+    Some README text.
+    \`\`\`java
+    import * as s3 from '@aws-cdk/aws-s3';
+    \`\`\`
+    Some more README text.`);
+  });
+
+  test('parses multiple snippets', () => {
+    const output = rewriteReadmeImports(`
+    Some README text.
+    \`\`\`ts
+    import * as s3 from '@aws-cdk/aws-s3';
+    \`\`\`
+    Some more README text.
+    \`\`\`ts
+    import { CfnDeliveryStream } from '@aws-cdk/aws-kinesisfirehose';
+    \`\`\``, 'subject.ts');
+
+    expect(output).toBe(`
+    Some README text.
+    \`\`\`ts
+    import * as s3 from 'aws-cdk-lib/aws-s3';
+    \`\`\`
+    Some more README text.
+    \`\`\`ts
+    import { CfnDeliveryStream } from 'aws-cdk-lib/aws-kinesisfirehose';
+    \`\`\``);
+  });
+});

tools/@aws-cdk/individual-pkg-gen/transform-packages.ts

@@ -116,7 +116,7 @@ function transformPackages(): void {
           .filter(line => !line.match(/export \* from '.*\.generated'/))
           .join('\n');
         fs.outputFileSync(destination, indexLines);
-      } else if (sourceFileName.endsWith('.ts') && !sourceFileName.endsWith('.d.ts')) {
+      } else if (sourceFileName.endsWith('.ts') && !sourceFileName.endsWith('.d.ts') || sourceFileName.endsWith('.ts-fixture')) {
         const sourceCode = fs.readFileSync(source).toString();
         const sourceCodeOutput = awsCdkMigration.rewriteImports(sourceCode, sourceFileName, {
           customModules: alphaPackages,
@@ -130,7 +130,12 @@ function transformPackages(): void {
         [CFN_STABILITY_BANNER, FEATURE_CFN_STABILITY_BANNER, FEATURE_CFN_STABILITY_LINE].forEach(pattern => {
           sourceCode = sourceCode.replace(pattern, '');
         });
-        fs.outputFileSync(destination, sourceCode);
+        const sourceCodeOutput = awsCdkMigration.rewriteReadmeImports(sourceCode, sourceFileName, {
+          customModules: alphaPackages,
+          rewriteCfnImports: true,
+          packageUnscopedName: `${pkg.name.substring('@aws-cdk/'.length)}`,
+        });
+        fs.outputFileSync(destination, sourceCodeOutput);
       } else {
         const stat = fs.statSync(source);
         if (stat.isDirectory()) {