feat: Register module-level stability

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,9 @@
     }
   },
   "description": "A simple calcuator built on JSII.",
+  "docs": {
+    "stability": "experimental"
+  },
   "homepage": "https://github.com/awslabs/jsii.git",
   "jsiiVersion": "0.11.0",
   "license": "Apache-2.0",
@@ -6810,5 +6813,5 @@
     }
   },
   "version": "0.11.0",
-  "fingerprint": "i8GdLx7YlhttP5/pB0dKItig1wFkp/DwDdUtbYsIdfc="
+  "fingerprint": "KKOrdvjcsF9ItTXwTs/c4WE7VmYP0adJh/N9hx3+USo="
 }

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,32 @@ 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.readme) {
+            for (const line of md2html(mod.readme.markdown).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 +470,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 +1193,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,7 @@ class Package {
         }
 
         code.openFile("README.md");
-        code.line(this.metadata.readme !== undefined ? this.metadata.readme.markdown : "");
+        code.line(this.metadata.readme && this.metadata.readme.markdown);
         code.closeFile("README.md");
 
         // Strip " (build abcdef)" from the jsii version
@@ -1825,4 +1825,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/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,9 @@
     }
   },
   "description": "A simple calcuator built on JSII.",
+  "docs": {
+    "stability": "experimental"
+  },
   "homepage": "https://github.com/awslabs/jsii.git",
   "jsiiVersion": "0.11.0",
   "license": "Apache-2.0",
@@ -6810,5 +6813,5 @@
     }
   },
   "version": "0.11.0",
-  "fingerprint": "i8GdLx7YlhttP5/pB0dKItig1wFkp/DwDdUtbYsIdfc="
+  "fingerprint": "KKOrdvjcsF9ItTXwTs/c4WE7VmYP0adJh/N9hx3+USo="
 }

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,13 @@
+/**
+ * <h1>jsii Calculator</h1>
+ * <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-spec/lib/spec.ts

@@ -334,15 +334,27 @@ export interface Docs {
 }
 
 /**
- * API Stability levels.
+ * API Stability levels. These are modeled after the `node` stability index.
+ *
+ * @see https://nodejs.org/api/documentation.html#documentation_stability_index.
  */
 export enum Stability {
     /**
-     * Experimental APIs may change in breaking ways in a minor version update.
+     * The API may emit warnings. Backward compatibility is not guaranteed.
+     */
+    Deprecated = 'deprecated',
+
+    /**
+     * This API is still under active development and subject to non-backward
+     * compatible changes or removal in any future version. Use of the API is
+     * not recommended in production environments. Experimental APIs are not
+     * subject to the Semantic Versioning model.
      */
     Experimental = 'experimental',
+
     /**
-     * Stable APIs may not change in breaking ways without a major version bump.
+     * This API is subject to the Semantic Versioning model and may not change
+     * in breaking ways in a subsequent minor or patch version.
      */
     Stable = 'stable',
 }

packages/jsii/lib/assembler.ts

@@ -61,11 +61,12 @@ export class Assembler implements Emitter {
         'A "homepage" field should be specified in "package.json"');
     }
     const readme = await _loadReadme.call(this);
-    if (!readme) {
+    if (readme == null) {
       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.');
     }
+    const docs = _loadDocs.call(this);
 
     this._types = {};
     this._deferred = [];
@@ -99,7 +100,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,6 +116,7 @@ export class Assembler implements Emitter {
       types: this._types,
       targets: this.projectInfo.targets,
       metadata: this.projectInfo.metadata,
+      docs,
       readme,
       jsiiVersion,
       fingerprint: '<TBD>',
@@ -143,12 +145,23 @@ export class Assembler implements Emitter {
 
     async function _loadReadme(this: Assembler) {
       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 undefined;
+      }
+      const markdown = await literate.includeAndRenderExamples(
         await literate.loadFromFile(readmePath),
         literate.fileSystemLoader(this.projectInfo.projectRoot)
       );
-      return { markdown: renderedLines.join('\n') };
+      return { markdown: markdown.join('\n') };
+    }
+
+    function _loadDocs(this: Assembler): spec.Docs | undefined {
+      if (!this.projectInfo.stability && !this.projectInfo.deprecated) {
+        return undefined;
+      }
+      const deprecated = this.projectInfo.deprecated;
+      const stability = this.projectInfo.stability;
+      return { deprecated, stability };
     }
   }
 

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: _validateStability(pkg.stability, pkg.deprecated),
         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,18 @@ function _validateVersionFormat(format: string): 'short' | 'full' {
     }
     return format;
 }
+
+function _validateStability(stability: string | undefined, deprecated: string | undefined): spec.Stability | undefined {
+    if (!stability && deprecated) {
+        stability = spec.Stability.Deprecated;
+    } else if (deprecated && stability !== spec.Stability.Deprecated) {
+        throw new Error(`Package is deprecated (${deprecated}), but it's stability is ${stability} and not ${spec.Stability.Deprecated}`);
+    }
+    if (!stability) {
+        return undefined;
+    }
+    if (Object.values(spec.Stability).indexOf(stability) === -1) {
+        throw new Error(`Invalid stability "${stability}", it must be one of ${Object.values(spec.Stability).join(', ')}`);
+    }
+    return stability as spec.Stability;
+}