chore(ubergen): tell users about experimental package (#18012)

When ubergen generate a barebones README for an experimental package's
stable variant, add in a paragraph that directs users to the
experimental library so they have an easier time finding it.


----

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

tools/@aws-cdk/pkglint/lib/library-creation.ts

@@ -56,11 +56,12 @@ export function createModuleDefinitionFromCfnNamespace(namespace: string): Modul
 }
 
 
-export async function createLibraryReadme(namespace: string, readmePath: string) {
+export async function createLibraryReadme(namespace: string, readmePath: string, alphaPackageName?: string) {
   const module = createModuleDefinitionFromCfnNamespace(namespace);
 
   await fs.writeFile(readmePath, cfnOnlyReadmeContents({
     cfnNamespace: namespace,
     packageName: module.packageName,
+    alphaPackageName,
   }));
 }

tools/@aws-cdk/pkglint/lib/readme-contents.ts

@@ -11,6 +11,14 @@ export interface LibraryReadmeOptions {
    * The name under which we publish this NPM package
    */
   readonly packageName: string;
+
+  /**
+   * Alpha package name
+   *
+   * If the "actual" contents of this library are available in another package,
+   * give the name here.
+   */
+  readonly alphaPackageName?: string;
 }
 
 /**
@@ -55,6 +63,13 @@ export function cfnOnlyReadmeContents(options: LibraryReadmeOptions) {
     '```ts nofixture',
     `import * as ${importName} from '${options.packageName}';`,
     '```',
+    ...(options.alphaPackageName ? [
+      '',
+      '> The construct library for this service is in preview. Since it is not stable yet, it is distributed',
+      '> as a separate package so that you can pin its version independently of the rest of the CDK. See the package named:',
+      '>',
+      `>     ${options.alphaPackageName}`,
+    ] : []),
     '',
     '<!--BEGIN CFNONLY DISCLAIMER-->',
     '',

tools/@aws-cdk/ubergen/bin/ubergen.ts

@@ -364,13 +364,16 @@ async function transformPackage(
     await fs.mkdirp(destinationLib);
     await cfn2ts(cfnScopes, destinationLib);
 
+    // We know what this is going to be, so predict it
+    const alphaPackageName = `${library.packageJson.name}-alpha`;
+
     // create a lib/index.ts which only exports the generated files
     fs.writeFileSync(path.join(destinationLib, 'index.ts'),
       /// logic copied from `create-missing-libraries.ts`
       cfnScopes.map(s => (s === 'AWS::Serverless' ? 'AWS::SAM' : s).split('::')[1].toLocaleLowerCase())
         .map(s => `export * from './${s}.generated';`)
         .join('\n'));
-    await pkglint.createLibraryReadme(cfnScopes[0], path.join(destination, 'README.md'));
+    await pkglint.createLibraryReadme(cfnScopes[0], path.join(destination, 'README.md'), alphaPackageName);
 
     await copyOrTransformFiles(destination, destination, allLibraries, uberPackageJson);
   } else {