feat: Register module-level stability

packages/jsii-calc/README.md

@@ -1,4 +1,5 @@
 # jsii Calculator
+![API Stability: experimental](https://img.shields.io/badge/API%20Stability-experimental-important.svg)
 
 This library is used to demonstrate and test the features of JSII
 

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": {

packages/jsii-calc/test/assembly.jsii

@@ -182,6 +182,11 @@
     }
   },
   "description": "A simple calcuator built on JSII.",
+  "docs": {
+    "remarks": "![API Stability: experimental](https://img.shields.io/badge/API%20Stability-experimental-important.svg)\n\nThis library is used to demonstrate and test the features of JSII\n\n## Sphinx\n\nThis file will be incorporated into the sphinx documentation.\n\nIf this file starts with an \"H1\" line (in our case `# jsii Calculator`), this\nheading will be used as the Sphinx topic name. Otherwise, the name of the module\n(`jsii-calc`) will be used instead.\n\n\n\n\n",
+    "stability": "experimental",
+    "summary": "# jsii Calculator"
+  },
   "homepage": "https://github.com/awslabs/jsii.git",
   "jsiiVersion": "0.11.0",
   "license": "Apache-2.0",
@@ -193,9 +198,6 @@
     }
   },
   "name": "jsii-calc",
-  "readme": {
-    "markdown": "# jsii Calculator\n\nThis library is used to demonstrate and test the features of JSII\n\n## Sphinx\n\nThis file will be incorporated into the sphinx documentation.\n\nIf this file starts with an \"H1\" line (in our case `# jsii Calculator`), this\nheading will be used as the Sphinx topic name. Otherwise, the name of the module\n(`jsii-calc`) will be used instead.\n\n\n\n\n"
-  },
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/jsii.git"
@@ -6810,5 +6812,5 @@
     }
   },
   "version": "0.11.0",
-  "fingerprint": "i8GdLx7YlhttP5/pB0dKItig1wFkp/DwDdUtbYsIdfc="
+  "fingerprint": "5ejpZLVHjfmn1dghKkB/85hdGJuSRGZtxSIH+SF+b6Y="
 }

packages/jsii-pacmak/lib/markdown.ts

@@ -114,6 +114,12 @@ export function md2rst(text: string) {
     return doc.toString();
 }
 
+export function md2html(text: string): string {
+  const parser = new commonmark.Parser({ smart: false });
+  const renderer = new commonmark.HtmlRenderer({ smart: false, safe: true });
+  return renderer.render(parser.parse(text));
+}
+
 /**
  * Build a document incrementally
  */
@@ -236,4 +242,4 @@ function pump(ast: commonmark.Node, handlers: Handlers) {
          │ └── text
          └── text
 
- */
+ */

packages/jsii-pacmak/lib/targets/java.ts

@@ -5,6 +5,7 @@ import path = require('path');
 import xmlbuilder = require('xmlbuilder');
 import { Generator } from '../generator';
 import logging = require('../logging');
+import { md2html } from '../markdown';
 import { PackageInfo, Target, TargetOptions } from '../target';
 import { shell } from '../util';
 import { VERSION, VERSION_DESC } from '../version';
@@ -166,6 +167,8 @@ class JavaGenerator extends Generator {
     protected onBeginAssembly(assm: spec.Assembly, fingerprint: boolean) {
         this.emitFullGeneratorInfo = fingerprint;
         this.moduleClass = this.emitModuleFile(assm);
+
+        this.emitPackageInfo(assm);
     }
 
     protected onEndAssembly(assm: spec.Assembly, fingerprint: boolean) {
@@ -346,6 +349,39 @@ class JavaGenerator extends Generator {
         }
     }
 
+    private emitPackageInfo(mod: spec.Assembly) {
+        if (!mod.docs) { return; }
+
+        const packageName = this.getNativeName(mod, undefined);
+        const packageInfoFile = this.toJavaFilePath(mod.name + '.package-info');
+        this.code.openFile(packageInfoFile);
+        this.code.line('/**');
+        if (mod.docs.summary || mod.docs.remarks) {
+            const mdown = new Array<string>();
+            if (mod.docs.summary) {
+                mdown.push(mod.docs.summary);
+            }
+            if (mod.docs.remarks) {
+                mdown.push(mod.docs.remarks);
+            }
+            for (const line of md2html(mdown.join('\n')).split('\n')) {
+                this.code.line(` * ${line}`);
+            }
+            this.code.line(' *');
+        }
+        if (mod.docs.deprecated) {
+            this.code.line(` * @deprecated ${mod.docs.deprecated}`);
+        } else if (mod.docs.stability) {
+            this.code.line(` * @stability ${mod.docs.stability}`);
+        }
+        this.code.line(' */');
+        if (mod.docs.deprecated) {
+            this.code.line('@Deprecated');
+        }
+        this.code.line(`package ${packageName};`);
+        this.code.closeFile(packageInfoFile);
+    }
+
     private emitMavenPom(assm: spec.Assembly, fingerprint: boolean) {
         const self = this;
 
@@ -441,6 +477,9 @@ class JavaGenerator extends Generator {
                                 configuration: {
                                     failOnError: false,
                                     show: 'protected',
+                                    sourceFileExcludes: {
+                                        exclude: ['**/$Module.java']
+                                    },
                                     // Adding these makes JavaDoc generation about a 3rd faster (which is far and away the most
                                     // expensive part of the build)
                                     additionalJOption: ['-J-XX:+TieredCompilation', '-J-XX:TieredStopAtLevel=1']
@@ -1161,11 +1200,11 @@ class JavaGenerator extends Generator {
 
     private getNativeName(assm: spec.Assembly, name: string | undefined): string;
     private getNativeName(assm: spec.PackageVersion, name: string | undefined, assmName: string): string;
-    private getNativeName(assm: spec.Assembly | spec.PackageVersion,
+    private getNativeName(assm: spec.Assembly | spec.PackageVersion,
                           name: string | undefined,
                           assmName: string = (assm as spec.Assembly).name): string {
         const javaPackage = assm.targets && assm.targets.java && assm.targets.java.package;
-        if (!javaPackage) { throw new Error(`The module ${assmName} does not have a java.package setting`); }
+        if (!javaPackage) { throw new Error(`The module ${assmName} does not have a java.package setting`); }
         return `${javaPackage}${name ? `.${name}` : ''}`;
     }
 

packages/jsii-pacmak/lib/targets/python.ts

@@ -1097,7 +1097,10 @@ class Package {
         }
 
         code.openFile("README.md");
-        code.line(this.metadata.readme !== undefined ? this.metadata.readme.markdown : "");
+        const readme = this.metadata.docs && this.metadata.docs.summary
+            ? `${this.metadata.docs.summary}\n${this.metadata.docs.remarks || ''}`
+            : '';
+        code.line(readme);
         code.closeFile("README.md");
 
         // Strip " (build abcdef)" from the jsii version
@@ -1825,4 +1828,4 @@ function onelineDescription(docs: spec.Docs | undefined) {
     if (docs.remarks) { parts.push(md2rst(docs.remarks)); }
     if (docs.default) { parts.push(`Default: ${md2rst(docs.default)}`); }
     return parts.join(' ').replace(/\s+/g, ' ');
-}
+}

packages/jsii-pacmak/lib/targets/sphinx.ts

@@ -714,14 +714,14 @@ class SphinxDocsGenerator extends Generator {
      * @returns header: the contents of the header (or undefined)
      */
     private emitReadme(assm: spec.Assembly): { readmeFile?: string, readmeHeader?: string } {
-        if (!assm.readme) {
+        if (!assm.docs || !assm.docs.summary) {
             return {
                 readmeFile: undefined,
                 readmeHeader: undefined
             };
         }
 
-        let lines = assm.readme.markdown.split('\n');
+        let lines = [assm.docs.summary, ...(assm.docs.remarks && assm.docs.remarks.split('\n') || [])];
         let readmeHeader;
 
         if (lines[0].startsWith('# ')) {

packages/jsii-pacmak/test/expected.jsii-calc-base/java/pom.xml

@@ -103,6 +103,9 @@
         <configuration>
           <failOnError>false</failOnError>
           <show>protected</show>
+          <sourceFileExcludes>
+            <exclude>**/$Module.java</exclude>
+          </sourceFileExcludes>
           <additionalJOption>-J-XX:+TieredCompilation</additionalJOption>
           <additionalJOption>-J-XX:TieredStopAtLevel=1</additionalJOption>
         </configuration>

packages/jsii-pacmak/test/expected.jsii-calc-lib/java/pom.xml

@@ -103,6 +103,9 @@
         <configuration>
           <failOnError>false</failOnError>
           <show>protected</show>
+          <sourceFileExcludes>
+            <exclude>**/$Module.java</exclude>
+          </sourceFileExcludes>
           <additionalJOption>-J-XX:+TieredCompilation</additionalJOption>
           <additionalJOption>-J-XX:TieredStopAtLevel=1</additionalJOption>
         </configuration>

packages/jsii-pacmak/test/expected.jsii-calc/dotnet/Amazon.JSII.Tests.CalculatorPackageId/.jsii

@@ -182,6 +182,11 @@
     }
   },
   "description": "A simple calcuator built on JSII.",
+  "docs": {
+    "remarks": "![API Stability: experimental](https://img.shields.io/badge/API%20Stability-experimental-important.svg)\n\nThis library is used to demonstrate and test the features of JSII\n\n## Sphinx\n\nThis file will be incorporated into the sphinx documentation.\n\nIf this file starts with an \"H1\" line (in our case `# jsii Calculator`), this\nheading will be used as the Sphinx topic name. Otherwise, the name of the module\n(`jsii-calc`) will be used instead.\n\n\n\n\n",
+    "stability": "experimental",
+    "summary": "# jsii Calculator"
+  },
   "homepage": "https://github.com/awslabs/jsii.git",
   "jsiiVersion": "0.11.0",
   "license": "Apache-2.0",
@@ -193,9 +198,6 @@
     }
   },
   "name": "jsii-calc",
-  "readme": {
-    "markdown": "# jsii Calculator\n\nThis library is used to demonstrate and test the features of JSII\n\n## Sphinx\n\nThis file will be incorporated into the sphinx documentation.\n\nIf this file starts with an \"H1\" line (in our case `# jsii Calculator`), this\nheading will be used as the Sphinx topic name. Otherwise, the name of the module\n(`jsii-calc`) will be used instead.\n\n\n\n\n"
-  },
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/jsii.git"
@@ -6810,5 +6812,5 @@
     }
   },
   "version": "0.11.0",
-  "fingerprint": "i8GdLx7YlhttP5/pB0dKItig1wFkp/DwDdUtbYsIdfc="
+  "fingerprint": "5ejpZLVHjfmn1dghKkB/85hdGJuSRGZtxSIH+SF+b6Y="
 }

packages/jsii-pacmak/test/expected.jsii-calc/java/pom.xml

@@ -134,6 +134,9 @@
         <configuration>
           <failOnError>false</failOnError>
           <show>protected</show>
+          <sourceFileExcludes>
+            <exclude>**/$Module.java</exclude>
+          </sourceFileExcludes>
           <additionalJOption>-J-XX:+TieredCompilation</additionalJOption>
           <additionalJOption>-J-XX:TieredStopAtLevel=1</additionalJOption>
         </configuration>

packages/jsii-pacmak/test/expected.jsii-calc/java/src/main/java/software/amazon/jsii/tests/calculator/package-info.java

@@ -0,0 +1,14 @@
+/**
+ * <h1>jsii Calculator</h1>
+ * <p><img src="https://img.shields.io/badge/API%20Stability-experimental-important.svg" alt="API Stability: experimental" /></p>
+ * <p>This library is used to demonstrate and test the features of JSII</p>
+ * <h2>Sphinx</h2>
+ * <p>This file will be incorporated into the sphinx documentation.</p>
+ * <p>If this file starts with an &quot;H1&quot; line (in our case <code># jsii Calculator</code>), this
+ * heading will be used as the Sphinx topic name. Otherwise, the name of the module
+ * (<code>jsii-calc</code>) will be used instead.</p>
+ * 
+ *
+ * @stability experimental
+ */
+package software.amazon.jsii.tests.calculator;

packages/jsii-pacmak/test/expected.jsii-calc/python/README.md

@@ -1,4 +1,5 @@
 # jsii Calculator
+![API Stability: experimental](https://img.shields.io/badge/API%20Stability-experimental-important.svg)
 
 This library is used to demonstrate and test the features of JSII
 

packages/jsii-pacmak/test/expected.jsii-calc/sphinx/_jsii-calc.README.md

@@ -1,3 +1,4 @@
+![API Stability: experimental](https://img.shields.io/badge/API%20Stability-experimental-important.svg)
 
 This library is used to demonstrate and test the features of JSII
 

packages/jsii-spec/lib/spec.ts

@@ -134,13 +134,6 @@ export interface Assembly extends Documentable {
      * @default none
      */
     types?: { [fqn: string]: Type };
-
-    /**
-     * The top-level readme document for this assembly (if any).
-     *
-     * @default none
-     */
-    readme?: { markdown: string };
 }
 
 /**

packages/jsii/lib/assembler.ts

@@ -60,11 +60,20 @@ export class Assembler implements Emitter {
         ts.DiagnosticCategory.Suggestion,
         'A "homepage" field should be specified in "package.json"');
     }
-    const readme = await _loadReadme.call(this);
-    if (!readme) {
+    const docs = await _loadReadme.call(this);
+    if (!docs || !docs.summary) {
       this._diagnostic(null,
         ts.DiagnosticCategory.Suggestion,
-        'There is not "README.md" file. It is recommended to have one.');
+        'There is no "README.md" file. It is recommended to have one.');
+    }
+
+    if (docs && docs.stability) {
+      const badge = _stabilityBadge(docs.stability);
+      if (!docs || !docs.remarks || docs.remarks.indexOf(badge) < 0) {
+        this._diagnostic(null,
+          ts.DiagnosticCategory.Error,
+          `The "README.md" file does not document the API stability (${docs.stability}). The following markdown badge is required:\n\t${badge}`);
+      }
     }
 
     this._types = {};
@@ -99,7 +108,7 @@ export class Assembler implements Emitter {
 
     const jsiiVersion = this.projectInfo.jsiiVersionFormat === 'short' ? SHORT_VERSION : VERSION;
 
-    const assembly = {
+    const assembly: spec.Assembly = {
       schema: spec.SchemaVersion.LATEST,
       name: this.projectInfo.name,
       version: this.projectInfo.version,
@@ -115,7 +124,7 @@ export class Assembler implements Emitter {
       types: this._types,
       targets: this.projectInfo.targets,
       metadata: this.projectInfo.metadata,
-      readme,
+      docs,
       jsiiVersion,
       fingerprint: '<TBD>',
     };
@@ -141,14 +150,26 @@ export class Assembler implements Emitter {
       delete this._diagnostics;
     }
 
-    async function _loadReadme(this: Assembler) {
+    async function _loadReadme(this: Assembler): Promise<spec.Docs | undefined> {
       const readmePath = path.join(this.projectInfo.projectRoot, 'README.md');
-      if (!await fs.pathExists(readmePath)) { return undefined; }
-      const renderedLines = await literate.includeAndRenderExamples(
+      if (!await fs.pathExists(readmePath)) {
+        return this.projectInfo.deprecated || this.projectInfo.stability
+          ? {
+              deprecated: this.projectInfo.deprecated,
+              stability: this.projectInfo.stability
+            }
+          : undefined;
+      }
+      const [summary, ...remarks] = await literate.includeAndRenderExamples(
         await literate.loadFromFile(readmePath),
         literate.fileSystemLoader(this.projectInfo.projectRoot)
       );
-      return { markdown: renderedLines.join('\n') };
+      return {
+        deprecated: this.projectInfo.deprecated,
+        stability: this.projectInfo.stability,
+        summary,
+        remarks: remarks.join('\n')
+      };
     }
   }
 
@@ -1629,3 +1650,18 @@ const PROHIBITED_MEMBER_NAMES = ['equals', 'hashcode'];
 function isProhibitedMemberName(name: string) {
   return PROHIBITED_MEMBER_NAMES.includes(name.toLowerCase());
 }
+
+function _stabilityBadge(stability: spec.Stability) {
+  return `![API Stability: ${stability}](https://img.shields.io/badge/API%20Stability-${stability}-${_stabilityColor()}.svg)`;
+
+  function _stabilityColor() {
+    switch (stability) {
+      case spec.Stability.Stable:
+        return 'success';
+      case spec.Stability.Experimental:
+        return 'important';
+      default:
+        return 'critical';
+    }
+  }
+}

packages/jsii/lib/project-info.ts

@@ -17,6 +17,8 @@ export interface ProjectInfo {
     readonly name: string;
     readonly version: string;
     readonly author: spec.Person;
+    readonly deprecated?: string;
+    readonly stability?: spec.Stability;
     readonly license: string;
     readonly repository: {
         readonly type: string;
@@ -105,6 +107,8 @@ export async function loadProjectInfo(projectRoot: string, { fixPeerDependencies
 
         name: _required(pkg.name, 'The "package.json" file must specify the "name" attribute'),
         version: _required(pkg.version, 'The "package.json" file must specify the "version" attribute'),
+        deprecated: pkg.deprecated,
+        stability: pkg.stability && _validateStability(pkg.stability),
         author: _toPerson(_required(pkg.author, 'The "package.json" file must specify the "author" attribute'), 'author'),
         repository: {
             url: _required(pkg.repository.url, 'The "package.json" file must specify the "repository.url" attribute'),
@@ -228,3 +232,10 @@ function _validateVersionFormat(format: string): 'short' | 'full' {
     }
     return format;
 }
+
+function _validateStability(stability: string): spec.Stability {
+    if (Object.values(spec.Stability).indexOf(stability) !== -1) {
+        return stability as spec.Stability;
+    }
+    throw new Error(`Invalid stability "${stability}", it must be one of ${Object.values(spec.Stability).join(', ')}`);
+}