feat(jsii): API compatibility checks by default

Adds an option `compat` (defaults to `true`) which automatically verifies API compatibility against the last published npm version.

The `compatIgnore` option can control the name of the ignore file.

API.md

@@ -393,6 +393,8 @@ new JsiiProject(options: JsiiProjectOptions)
   * **repository** (<code>string</code>)  *No description* 
   * **authorEmail** (<code>string</code>)  *No description* <span style="text-decoration: underline">*Optional*</span>
   * **authorUrl** (<code>string</code>)  *No description* <span style="text-decoration: underline">*Optional*</span>
+  * **compat** (<code>boolean</code>)  Automatically run API compatibility test against the latest version published to npm after compilation. <span style="text-decoration: underline">*Default*</span>: true
+  * **compatIgnore** (<code>string</code>)  Name of the ignore file for API compatibility tests. <span style="text-decoration: underline">*Default*</span>: .compatignore
   * **description** (<code>string</code>)  *No description* <span style="text-decoration: underline">*Optional*</span>
   * **docgen** (<code>boolean</code>)  Automatically generate API.md from jsii. <span style="text-decoration: underline">*Default*</span>: true
   * **dotnet** (<code>[JsiiDotNetTarget](#projen-jsiidotnettarget)</code>)  *No description* <span style="text-decoration: underline">*Optional*</span>
@@ -1187,6 +1189,8 @@ Name | Type | Description
 **bin**?🔹 | <code>Map<string, string></code> | Binary programs vended with your module.<br/><span style="text-decoration: underline">*Optional*</span>
 **buildWorkflow**?🔹 | <code>boolean</code> | Define a GitHub workflow for building PRs.<br/><span style="text-decoration: underline">*Default*</span>: true
 **bundledDependencies**?🔹 | <code>Array<string></code> | <span style="text-decoration: underline">*Optional*</span>
+**compat**?🔹 | <code>boolean</code> | Automatically run API compatibility test against the latest version published to npm after compilation.<br/><span style="text-decoration: underline">*Default*</span>: true
+**compatIgnore**?🔹 | <code>string</code> | Name of the ignore file for API compatibility tests.<br/><span style="text-decoration: underline">*Default*</span>: .compatignore
 **dependencies**?🔹 | <code>Map<string, [Semver](#projen-semver)></code> | <span style="text-decoration: underline">*Optional*</span>
 **description**?🔹 | <code>string</code> | <span style="text-decoration: underline">*Optional*</span>
 **devDependencies**?🔹 | <code>Map<string, [Semver](#projen-semver)></code> | <span style="text-decoration: underline">*Optional*</span>

package.json

@@ -16,9 +16,9 @@
     "test": "yarn eslint && rm -fr lib/ && jest --passWithNoTests",
     "bump": "standard-version",
     "release": "yarn bump && git push --follow-tags origin master",
-    "compile": "jsii --silence-warnings=reserved-word && jsii-docgen",
+    "compile": "jsii --silence-warnings=reserved-word && jsii-docgen && yarn compat",
     "watch": "jsii -w --silence-warnings=reserved-word",
-    "compat": "npx jsii-diff npm:$(node -p \"require('./package.json').name\")",
+    "compat": "npx jsii-diff npm:$(node -p \"require('./package.json').name\") -k --ignore-file .compatignore || (echo \"\nUNEXPECTED BREAKING CHANGES: add keys such as 'removed:constructs.Node.of' to .compatignore to skip.\n\" && exit 1)",
     "package": "jsii-pacmak",
     "build": "yarn test && yarn compile && yarn run package",
     "eslint": "eslint . --ext .ts",

src/jsii-project.ts

@@ -88,6 +88,23 @@ export interface JsiiProjectOptions extends CommonOptions {
    * @default "test"
    */
   readonly testdir?: string;
+
+  /**
+   * Automatically run API compatibility test against the latest version published to npm after compilation.
+   *
+   * - You can manually run compatbility tests using `yarn compat` if this feature is disabled.
+   * - You can ignore compatibility failures by adding lines to a ".compatignore" file.
+   *
+   * @default true
+   */
+  readonly compat?: boolean;
+
+  /**
+   * Name of the ignore file for API compatibility tests.
+   *
+   * @default .compatignore
+   */
+  readonly compatIgnore?: string;
 }
 
 export enum Stability {
@@ -143,10 +160,12 @@ export class JsiiProject extends NodeProject {
     // this is an unhelpful warning
     const jsiiFlags = '--silence-warnings=reserved-word';
 
+    const compatIgnore = options.compatIgnore ?? '.compatignore';
+
     this.addScripts({
       compile: Lazy.stringValue({ produce: () => this.renderCompileCommand() }),
       watch: `jsii -w ${jsiiFlags}`,
-      compat: 'npx jsii-diff npm:$(node -p "require(\'./package.json\').name")',
+      compat: `npx jsii-diff npm:$(node -p "require(\'./package.json\').name") -k --ignore-file ${compatIgnore} || (echo "\nUNEXPECTED BREAKING CHANGES: add keys such as \'removed:constructs.Node.of\' to ${compatIgnore} to skip.\n" && exit 1)`,
       package: 'jsii-pacmak',
 
       // we runn "test" first because it deletes "lib/"
@@ -301,6 +320,11 @@ export class JsiiProject extends NodeProject {
         },
       });
     }
+
+    const compat = options.compat ?? true;
+    if (compat) {
+      this.addCompileCommand('yarn compat');
+    }
   }
 
   /**