feat: internal accessibility (#390)

Respect the `@internal` jsdoc tag on types and members. Any type of member marked internal will not be exposed in the API of the module and in .d.ts. files (through `--strip-internal`).

Members (properties/methods) that are marked as `@internal` must also have an underscore prefix (i.e. `_myMethod`) and vice versa in order to ensure that implementers or subclasses won't modify  accessibility.

If a class implements (or an interface extends) an internal or private interface, that interface is erased from the implementer's API. So it is possible to use internal interfaces as bases, while still maintaining API integrity (related to #287).

Fixes #388

BREAKING CHANGE: member names that begin with underscore now must be marked as "@internal" in their jsdocs, which will cause them to disappear from type declaration files and jsii APIs.

Author: Elad Ben-Israel

packages/jsii-calc/lib/compliance.ts

@@ -1335,3 +1335,92 @@ export class Constructors {
         return new PrivateClass();
     }
 }
+
+// internal can be used to represent members that can only be accessed from the current module
+export class StripInternal {
+    public youSeeMe = 'hello';
+
+    /**
+     * This is an internal thing
+     * @internal
+     */
+    public _youDontSeeMeAlthoughIamPublic = 'world'
+}
+
+/**
+ * @internal
+ */
+export class InternalClass {
+    public iAmNotHere = 'yes';
+}
+
+/**
+ * @internal
+ */
+export interface IInternalInterface {
+    prop: string;
+}
+
+/**
+ * @internal
+ */
+export enum InternalEnum {
+    Member1 = 12,
+    Member2 = 23
+}
+
+export interface IInterfaceWithInternal {
+    visible(): void;
+
+    /** @internal */
+    _hidden(): void;
+}
+
+export class ImplementsInterfaceWithInternal implements IInterfaceWithInternal {
+    visible() { }
+
+    /** @internal */
+    _hidden() { }
+
+    /** @internal */
+    _alsoHidden() { }
+
+    /** @internal */
+    _propertiesToo?: string;
+}
+
+export class ImplementsInterfaceWithInternalSubclass extends ImplementsInterfaceWithInternal {
+    /** @internal */
+    _alsoHidden() { }
+
+    /**
+     * @internal
+     */
+    public _propertiesToo?: string;
+}
+
+//
+// hidden interface erasure
+// if a class/interface uses a hidden (private/internal) interface as base, the base will
+// be erased from the API
+//
+
+interface IPrivateInterface {
+    private: string;
+}
+
+export interface ExtendsInternalInterface extends IInternalInterface {
+    boom: boolean
+}
+
+export class ImplementInternalInterface implements IInternalInterface {
+    prop = 'implement me'
+}
+
+export class ImplementsPrivateInterface implements IPrivateInterface {
+    public private = 'i came from private into the light'
+}
+
+export interface ExtendsPrivateInterface extends IPrivateInterface {
+    moreThings: string[];
+}

packages/jsii-calc/test/assembly.jsii

@@ -1478,6 +1478,43 @@
         }
       ]
     },
+    "jsii-calc.ExtendsInternalInterface": {
+      "assembly": "jsii-calc",
+      "datatype": true,
+      "fqn": "jsii-calc.ExtendsInternalInterface",
+      "kind": "interface",
+      "name": "ExtendsInternalInterface",
+      "properties": [
+        {
+          "abstract": true,
+          "name": "boom",
+          "type": {
+            "primitive": "boolean"
+          }
+        }
+      ]
+    },
+    "jsii-calc.ExtendsPrivateInterface": {
+      "assembly": "jsii-calc",
+      "datatype": true,
+      "fqn": "jsii-calc.ExtendsPrivateInterface",
+      "kind": "interface",
+      "name": "ExtendsPrivateInterface",
+      "properties": [
+        {
+          "abstract": true,
+          "name": "moreThings",
+          "type": {
+            "collection": {
+              "elementtype": {
+                "primitive": "string"
+              },
+              "kind": "array"
+            }
+          }
+        }
+      ]
+    },
     "jsii-calc.GiveMeStructs": {
       "assembly": "jsii-calc",
       "fqn": "jsii-calc.GiveMeStructs",
@@ -1649,6 +1686,18 @@
         }
       ]
     },
+    "jsii-calc.IInterfaceWithInternal": {
+      "assembly": "jsii-calc",
+      "fqn": "jsii-calc.IInterfaceWithInternal",
+      "kind": "interface",
+      "methods": [
+        {
+          "abstract": true,
+          "name": "visible"
+        }
+      ],
+      "name": "IInterfaceWithInternal"
+    },
     "jsii-calc.IInterfaceWithMethods": {
       "assembly": "jsii-calc",
       "fqn": "jsii-calc.IInterfaceWithMethods",
@@ -1776,6 +1825,74 @@
         }
       ]
     },
+    "jsii-calc.ImplementInternalInterface": {
+      "assembly": "jsii-calc",
+      "fqn": "jsii-calc.ImplementInternalInterface",
+      "initializer": {
+        "initializer": true
+      },
+      "kind": "class",
+      "name": "ImplementInternalInterface",
+      "properties": [
+        {
+          "name": "prop",
+          "type": {
+            "primitive": "string"
+          }
+        }
+      ]
+    },
+    "jsii-calc.ImplementsInterfaceWithInternal": {
+      "assembly": "jsii-calc",
+      "fqn": "jsii-calc.ImplementsInterfaceWithInternal",
+      "initializer": {
+        "initializer": true
+      },
+      "interfaces": [
+        {
+          "fqn": "jsii-calc.IInterfaceWithInternal"
+        }
+      ],
+      "kind": "class",
+      "methods": [
+        {
+          "name": "visible",
+          "overrides": {
+            "fqn": "jsii-calc.IInterfaceWithInternal"
+          }
+        }
+      ],
+      "name": "ImplementsInterfaceWithInternal"
+    },
+    "jsii-calc.ImplementsInterfaceWithInternalSubclass": {
+      "assembly": "jsii-calc",
+      "base": {
+        "fqn": "jsii-calc.ImplementsInterfaceWithInternal"
+      },
+      "fqn": "jsii-calc.ImplementsInterfaceWithInternalSubclass",
+      "initializer": {
+        "initializer": true
+      },
+      "kind": "class",
+      "name": "ImplementsInterfaceWithInternalSubclass"
+    },
+    "jsii-calc.ImplementsPrivateInterface": {
+      "assembly": "jsii-calc",
+      "fqn": "jsii-calc.ImplementsPrivateInterface",
+      "initializer": {
+        "initializer": true
+      },
+      "kind": "class",
+      "name": "ImplementsPrivateInterface",
+      "properties": [
+        {
+          "name": "private",
+          "type": {
+            "primitive": "string"
+          }
+        }
+      ]
+    },
     "jsii-calc.ImplictBaseOfBase": {
       "assembly": "jsii-calc",
       "datatype": true,
@@ -3318,6 +3435,23 @@
       ],
       "name": "StringEnum"
     },
+    "jsii-calc.StripInternal": {
+      "assembly": "jsii-calc",
+      "fqn": "jsii-calc.StripInternal",
+      "initializer": {
+        "initializer": true
+      },
+      "kind": "class",
+      "name": "StripInternal",
+      "properties": [
+        {
+          "name": "youSeeMe",
+          "type": {
+            "primitive": "string"
+          }
+        }
+      ]
+    },
     "jsii-calc.Sum": {
       "assembly": "jsii-calc",
       "base": {
@@ -3949,5 +4083,5 @@
     }
   },
   "version": "0.7.15",
-  "fingerprint": "IWSOEhdZzuvrss5K2WBjZCawXayV13yCAKTj/kJ9+mo="
+  "fingerprint": "iMxRj3lsHKNzSiBrjCyBH6Pp7Uvo+1Sxh/jN3hW+3nA="
 }