feat: Register module-level stability (#515)

Adds the necessary code to detect and forward module-level stability
indications to the assembly, so it can be used by downstream languages.
This effectively removes the `markdown` attribute from the `Assembly` in
favor of using the `docs` attribute.

Also, renders a `package-info.json` file for packages that have
documentation (a `README.md` file, deprecation notice, or stability
indication).

Implements awslabs/cdk-ops#367

Author: RomainMuller

packages/jsii-calc-lib/package.json

@@ -2,6 +2,8 @@
   "name": "@scope/jsii-calc-lib",
   "version": "0.11.0",
   "description": "A simple calcuator library built on JSII.",
+  "stability": "deprecated",
+  "deprecated": "Really just deprecated for shows...",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "private": true,
@@ -51,4 +53,4 @@
     "type": "git",
     "url": "https://github.com/awslabs/jsii.git"
   }
-}
+}

packages/jsii-calc-lib/test/assembly.jsii

@@ -84,6 +84,10 @@
     }
   },
   "description": "A simple calcuator library built on JSII.",
+  "docs": {
+    "deprecated": "Really just deprecated for shows...",
+    "stability": "deprecated"
+  },
   "homepage": "https://github.com/awslabs/jsii.git",
   "jsiiVersion": "0.11.0",
   "license": "Apache-2.0",
@@ -496,5 +500,5 @@
     }
   },
   "version": "0.11.0",
-  "fingerprint": "EtAUzTnV+hmz9yrXilnsS0MhQuQ/qmpmbwxvdLu561k="
+  "fingerprint": "x/BbPdAJTYB6QY83ucqo0CNLa2NoLebqPMbMY7BsyR4="
 }

packages/jsii-calc/lib/compliance.ts

@@ -1631,7 +1631,6 @@ export interface OptionalStruct {
  *
  * @see https://aws.amazon.com/
  * @customAttribute hasAValue
- * @deprecated Use something else please
  * @stable
  */
 export class ClassWithDocs {

packages/jsii-calc/lib/index.ts

@@ -2,3 +2,4 @@ export * from './calculator';
 export * from './compliance';
 export * from './documented';
 export * from './erasures';
+export * from './stability';

packages/jsii-calc/lib/stability.ts

@@ -0,0 +1,104 @@
+// The following tests validate emission of stability markers
+
+/** @experimental */
+export interface ExperimentalStruct {
+  /** @experimental */
+  readonly readonlyProperty: string;
+}
+/** @experimental */
+export interface IExperimentalInterface {
+  /** @experimental */
+  mutableProperty?: number;
+  /** @experimental */
+  method(): void;
+}
+/** @experimental */
+export class ExperimentalClass {
+  /** @experimental */
+  public readonly readonlyProperty: string;
+  /** @experimental */
+  public mutableProperty?: number;
+  /** @experimental */
+  constructor(readonlyString: string, mutableNumber?: number) {
+    this.readonlyProperty = readonlyString;
+    this.mutableProperty = mutableNumber;
+  }
+
+  /** @experimental */
+  public method(): void { return; }
+}
+/** @experimental */
+export enum ExperimentalEnum {
+  /** @experimental */
+  OptionA,
+  /** @experimental */
+  OptionB
+}
+
+/** @stable */
+export interface StableStruct {
+  /** @stable */
+  readonly readonlyProperty: string;
+}
+/** @stable */
+export interface IStableInterface {
+  /** @stable */
+  mutableProperty?: number;
+  /** @stable */
+  method(): void;
+}
+/** @stable */
+export class StableClass {
+  /** @stable */
+  public readonly readonlyProperty: string = 'wazoo';
+  /** @stable */
+  public mutableProperty?: number;
+  /** @stable */
+  constructor(readonlyString: string, mutableNumber?: number) {
+    this.readonlyProperty = readonlyString;
+    this.mutableProperty = mutableNumber;
+  }
+  /** @stable */
+  public method(): void { return; }
+}
+/** @stable */
+export enum StableEnum {
+  /** @stable */
+  OptionA,
+  /** @stable */
+  OptionB
+}
+
+/** @deprecated it just wraps a string */
+export interface DeprecatedStruct {
+  /** @deprecated well, yeah */
+  readonly readonlyProperty: string;
+}
+/** @deprecated useless interface */
+export interface IDeprecatedInterface {
+  /** @deprecated could be better */
+  mutableProperty?: number;
+  /** @deprecated services no purpose */
+  method(): void;
+}
+/** @deprecated a pretty boring class */
+export class DeprecatedClass {
+  /** @deprecated this is not always "wazoo", be ready to be disappointed */
+  public readonly readonlyProperty: string;
+  /** @deprecated shouldn't have been mutable */
+  public mutableProperty?: number;
+  /** @deprecated this constructor is "just" okay */
+  constructor(readonlyString: string, mutableNumber?: number) {
+    this.readonlyProperty = readonlyString;
+    this.mutableProperty = mutableNumber;
+  }
+  /** @deprecated it was a bad idea */
+  public method(): void { return; }
+}
+/** @deprecated your deprecated selection of bad options */
+export enum DeprecatedEnum {
+  /** @deprecated option A is not great */
+  OptionA,
+  /** @deprecated option B is kinda bad, too */
+  OptionB
+}

packages/jsii-calc/package.json

@@ -5,6 +5,7 @@
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "private": true,
+  "stability": "experimental",
   "jsii": {
     "outdir": "dist",
     "targets": {