feat(cognito): user pools are now in developer preview (aws#8522)

Adopting an entirely new banner style that allows for announcing
stability on segments of the construct library.

----

[Rendered version](https://github.com/aws/aws-cdk/blob/nija-at/cognito-stability/packages/%40aws-cdk/aws-cognito/README.md)

----

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

packages/@aws-cdk/aws-cognito/README.md

@@ -2,17 +2,18 @@
 <!--BEGIN STABILITY BANNER-->
 ---
 
-![cfn-resources: Stable](https://img.shields.io/badge/cfn--resources-stable-success.svg?style=for-the-badge)
+| Features | Stability |
+| --- | --- |
+| CFN Resources | ![Stable](https://img.shields.io/badge/stable-success.svg?style=for-the-badge) |
+| Higher level constructs for User Pools | ![Developer Preview](https://img.shields.io/badge/developer--preview-informational.svg?style=for-the-badge) |
+| Higher level constructs for Identity Pools | ![Not Implemented](https://img.shields.io/badge/not--implemented-black.svg?style=for-the-badge) |
 
-> All classes with the `Cfn` prefix in this module ([CFN Resources](https://docs.aws.amazon.com/cdk/latest/guide/constructs.html#constructs_lib)) are always stable and safe to use.
+> **CFN Resources:** All classes with the `Cfn` prefix in this module ([CFN Resources](https://docs.aws.amazon.com/cdk/latest/guide/constructs.html#constructs_lib)) are always stable and safe to use.
 
-![cdk-constructs: Experimental](https://img.shields.io/badge/cdk--constructs-experimental-important.svg?style=for-the-badge)
-
-> The APIs of higher level constructs in this module are experimental and under active development. They are subject to non-backward compatible changes or removal in any future version. These are not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be announced in the release notes. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.
+> **Developer Preview:** Higher level constructs in this module that are marked as developer preview have completed their phase of active development and are looking for adoption and feedback. While the same caveats around non-backward compatible as Experimental constructs apply, they will undergo fewer breaking changes. Just as with Experimental constructs, these are not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be announced in the release notes.
 
 ---
 <!--END STABILITY BANNER-->
-
 [Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/what-is-amazon-cognito.html) provides
 authentication, authorization, and user management for your web and mobile apps. Your users can sign in directly with a
 user name and password, or through a third party such as Facebook, Amazon, Google or Apple.
@@ -558,3 +559,4 @@ const signInUrl = domain.signInUrl(client, {
   redirectUrl: 'https://myapp.com/home', // must be a URL configured under 'callbackUrls' with the client
 })
 ```
+

packages/@aws-cdk/aws-cognito/package.json

@@ -102,7 +102,16 @@
     ]
   },
   "stability": "experimental",
-  "maturity": "experimental",
+  "features": [
+    {
+      "name": "Higher level constructs for User Pools",
+      "stability": "Developer Preview"
+    },
+    {
+      "name": "Higher level constructs for Identity Pools",
+      "stability": "Not Implemented"
+    }
+  ],
   "awscdkio": {
     "announce": false
   }

tools/pkglint/.gitignore

@@ -3,3 +3,4 @@
 *.d.ts
 dist
 lib/generated/resources.ts
+!jest.config.js

tools/pkglint/jest.config.js

@@ -0,0 +1,5 @@
+module.exports = {
+  testMatch: [
+    "**/?(*.)+(test).js",
+  ],
+};

tools/pkglint/lib/banners/features-cfn-stable.md

@@ -0,0 +1 @@
+> **CFN Resources:** All classes with the `Cfn` prefix in this module ([CFN Resources](https://docs.aws.amazon.com/cdk/latest/guide/constructs.html#constructs_lib)) are always stable and safe to use.

tools/pkglint/lib/banners/features-developer-preview.md

@@ -0,0 +1 @@
+> **Developer Preview:** Higher level constructs in this module that are marked as developer preview have completed their phase of active development and are looking for adoption and feedback. While the same caveats around non-backward compatible as Experimental constructs apply, they will undergo fewer breaking changes. Just as with Experimental constructs, these are not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be announced in the release notes.

tools/pkglint/lib/banners/features-experimental.md

@@ -0,0 +1 @@
+> **Experimental:** Higher level constructs in this module that are marked as experimental are under active development. They are subject to non-backward compatible changes or removal in any future version. These are not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be announced in the release notes. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.

tools/pkglint/lib/banners/features-stable.md

@@ -0,0 +1 @@
+> **Stable:** Higher level constructs in this module that are marked stable will not undergo any breaking changes. They will strictly follow the [Semantic Versioning](https://semver.org/) model.

tools/pkglint/lib/rules.ts

@@ -183,6 +183,11 @@ export class MaturitySetting extends ValidationRule {
       return;
     }
 
+    if (pkg.json.features) {
+      // Skip this in favour of the FeatureStabilityRule.
+      return;
+    }
+
     let maturity = pkg.json.maturity as string | undefined;
     const stability = pkg.json.stability as string | undefined;
     if (!maturity) {
@@ -227,7 +232,7 @@ export class MaturitySetting extends ValidationRule {
     }
 
     const readmeContent = fs.readFileSync(readmeFile, { encoding: 'utf8' });
-    const badgeRegex = new RegExp(badge.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\w+/g, '\\w+'));
+    const badgeRegex = toRegExp(badge);
     if (!badgeRegex.test(readmeContent)) {
       // Removing a possible old, now invalid stability indication from the README.md before adding a new one
       const [title, ...body] = readmeContent.replace(/<!--BEGIN STABILITY BANNER-->(?:.|\n)+<!--END STABILITY BANNER-->\n+/m, '').split('\n');
@@ -300,6 +305,11 @@ export class StabilitySetting extends ValidationRule {
       return;
     }
 
+    if (pkg.json.features) {
+      // Skip this in favour of the FeatureStabilityRule.
+      return;
+    }
+
     const maturity = pkg.json.maturity as string | undefined;
     const stability = pkg.json.stability as string | undefined;
 
@@ -314,6 +324,84 @@ export class StabilitySetting extends ValidationRule {
   }
 }
 
+export class FeatureStabilityRule extends ValidationRule {
+  public readonly name = 'package-info/feature-stability';
+  private readonly badges: { [key: string]: string } = {
+    'Not Implemented': 'https://img.shields.io/badge/not--implemented-black.svg?style=for-the-badge',
+    'Experimental': 'https://img.shields.io/badge/experimental-important.svg?style=for-the-badge',
+    'Developer Preview': 'https://img.shields.io/badge/developer--preview-informational.svg?style=for-the-badge',
+    'Stable': 'https://img.shields.io/badge/stable-success.svg?style=for-the-badge',
+  };
+
+  public validate(pkg: PackageJson): void {
+    if (pkg.json.private || !pkg.json.features) {
+      return;
+    }
+
+    const stabilityBanner: string = [
+      '<!--BEGIN STABILITY BANNER-->',
+      '---',
+      '',
+      '| Features | Stability |',
+      '| --- | --- |',
+      ...this.featureEntries(pkg),
+      '',
+      ...this.bannerNotices(pkg),
+      '---',
+      '<!--END STABILITY BANNER-->',
+    ].join('\n');
+
+    const readmeFile = path.join(pkg.packageRoot, 'README.md');
+    if (!fs.existsSync(readmeFile)) {
+      // Presence of the file is asserted by another rule
+      return;
+    }
+    const readmeContent = fs.readFileSync(readmeFile, { encoding: 'utf8' });
+    const stabilityRegex = toRegExp(stabilityBanner);
+    if (!stabilityRegex.test(readmeContent)) {
+      const [title, ...body] = readmeContent.replace(/<!--BEGIN STABILITY BANNER-->(?:.|\n)+<!--END STABILITY BANNER-->\n+/m, '').split('\n');
+      pkg.report({
+        ruleName: this.name,
+        message: 'Stability banner does not match as expected',
+        fix: () => fs.writeFileSync(readmeFile, [title, stabilityBanner, ...body].join('\n')),
+      });
+    }
+  }
+
+  private featureEntries(pkg: PackageJson): string[] {
+    const entries: string[] = [];
+    if (pkg.json['cdk-build']?.cloudformation) {
+      entries.push(`| CFN Resources | ![Stable](${this.badges.Stable}) |`);
+    }
+    pkg.json.features.forEach((feature: { [key: string]: string }) => {
+      const badge = this.badges[feature.stability];
+      if (!badge) {
+        throw new Error(`Unknown stability - ${feature.stability}`);
+      }
+      entries.push(`| ${feature.name} | ![${feature.stability}](${badge}) |`);
+    });
+    return entries;
+  }
+
+  private bannerNotices(pkg: PackageJson): string[] {
+    const notices: string[] = [];
+    if (pkg.json['cdk-build']?.cloudformation) {
+      notices.push(readBannerFile('features-cfn-stable.md'));
+      notices.push('');
+    }
+
+    const noticeOrder = [ 'Experimental', 'Developer Preview', 'Stable' ];
+    const stabilities = pkg.json.features.map((f: { [k: string]: string }) => f.stability);
+    const filteredNotices = noticeOrder.filter(v => stabilities.includes(v));
+    filteredNotices.map((notice) => {
+      const lowerTrainCase = notice.toLowerCase().replace(/\s/g, '-');
+      notices.push(readBannerFile(`features-${lowerTrainCase}.md`));
+      notices.push('');
+    });
+    return notices;
+  }
+}
+
 /**
  * Keywords must contain CDK keywords and be sorted
  */
@@ -1289,3 +1377,11 @@ function repoRoot(dir: string) {
   }
   return root;
 }
+
+function toRegExp(str: string): RegExp {
+  return new RegExp(str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\w+/g, '\\w+'));
+}
+
+function readBannerFile(file: string): string {
+  return fs.readFileSync(path.join(__dirname, 'banners', file), { encoding: 'utf-8' });
+}

tools/pkglint/package.json

@@ -17,8 +17,9 @@
   },
   "scripts": {
     "build": "tsc -b && tslint -p . && chmod +x bin/pkglint",
-    "build+test": "npm run build",
-    "build+test+package": "npm run build",
+    "test": "jest",
+    "build+test": "npm run build && npm test",
+    "build+test+package": "npm run build && npm test",
     "watch": "tsc -b -w",
     "lint": "tsc -b && tslint -p . --force"
   },
@@ -37,6 +38,7 @@
     "@types/fs-extra": "^8.1.0",
     "@types/semver": "^7.2.0",
     "@types/yargs": "^15.0.5",
+    "jest": "^25.5.4",
     "typescript": "~3.8.3"
   },
   "dependencies": {