feat: strip @internal

strips classes, interfaces, enums or members that have an "@internal" jsdoc tag both from the jsii assembly manifest and .d.ts fixes #388
aws · Mar 18, 2019 · 85f50f8 · 85f50f8
1 parent 7cc65a1
commit 85f50f8
Show file tree

Hide file tree

Showing 4 changed files with 73 additions and 6 deletions.
diff --git a/packages/jsii-calc/lib/compliance.ts b/packages/jsii-calc/lib/compliance.ts
@@ -1335,3 +1335,34 @@ 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 { }
+
+/**
+ * @internal
+ */
+export enum InternalEnum {
+    Member1 = 12,
+    Member2 = 23
+}
diff --git a/packages/jsii-calc/test/assembly.jsii b/packages/jsii-calc/test/assembly.jsii
@@ -3318,6 +3318,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 +3966,5 @@
     }
   },
   "version": "0.7.15",
-  "fingerprint": "IWSOEhdZzuvrss5K2WBjZCawXayV13yCAKTj/kJ9+mo="
+  "fingerprint": "73Alf0ZvqK2FlLtj23s9t2mdHy29p1KR8E8O6oLIxh4="
 }
diff --git a/packages/jsii/lib/assembler.ts b/packages/jsii/lib/assembler.ts
@@ -337,11 +337,15 @@ export class Assembler implements Emitter {
         return [jsiiType];
     }
 
-    private async _visitClass(type: ts.Type, namespace: string[]): Promise<spec.ClassType> {
+    private async _visitClass(type: ts.Type, namespace: string[]): Promise<spec.ClassType | undefined> {
         if (LOG.isTraceEnabled()) {
             LOG.trace(`Processing class: ${colors.gray(namespace.join('.'))}.${colors.cyan(type.symbol.name)}`);
         }
 
+        if (_isInternal(type.symbol)) {
+            return undefined;
+        }
+
         const fqn = `${[this.projectInfo.name, ...namespace].join('.')}.${type.symbol.name}`;
 
         const jsiiType: spec.ClassType = {
@@ -479,11 +483,15 @@ export class Assembler implements Emitter {
         return _sortMembers(this._visitDocumentation(type.symbol, jsiiType));
     }
 
-    private async _visitEnum(type: ts.Type, namespace: string[]): Promise<spec.EnumType> {
+    private async _visitEnum(type: ts.Type, namespace: string[]): Promise<spec.EnumType | undefined> {
         if (LOG.isTraceEnabled()) {
             LOG.trace(`Processing enum: ${colors.gray(namespace.join('.'))}.${colors.cyan(type.symbol.name)}`);
         }
 
+        if (_isInternal(type.symbol)) {
+            return undefined;
+        }
+
         const decl = type.symbol.valueDeclaration;
         const flags = ts.getCombinedModifierFlags(decl);
         // tslint:disable-next-line:no-bitwise
@@ -553,11 +561,15 @@ export class Assembler implements Emitter {
         }
     }
 
-    private async _visitInterface(type: ts.Type, namespace: string[]): Promise<spec.InterfaceType> {
+    private async _visitInterface(type: ts.Type, namespace: string[]): Promise<spec.InterfaceType | undefined> {
         if (LOG.isTraceEnabled()) {
             LOG.trace(`Processing interface: ${colors.gray(namespace.join('.'))}.${colors.cyan(type.symbol.name)}`);
         }
 
+        if (_isInternal(type.symbol)) {
+            return undefined;
+        }
+
         const fqn = `${[this.projectInfo.name, ...namespace].join('.')}.${type.symbol.name}`;
 
         const jsiiType: spec.InterfaceType = {
@@ -723,6 +735,7 @@ export class Assembler implements Emitter {
              */
             return;
         }
+
         if (LOG.isTraceEnabled()) {
             LOG.trace(`Processing property: ${colors.green(type.fqn)}#${colors.cyan(symbol.name)}`);
         }
@@ -1058,12 +1071,17 @@ function _isExported(node: ts.Declaration): boolean {
  * @return ``true`` if the symbol should be hidden
  */
 function _isHidden(symbol: ts.Symbol): boolean {
-    return !symbol.valueDeclaration
-        || symbol.name.startsWith('_')
+    return _isInternal(symbol) // if this property is marked "@internal", we strip it from the API
+        || !symbol.valueDeclaration
         // tslint:disable-next-line:no-bitwise
         || (ts.getCombinedModifierFlags(symbol.valueDeclaration) & ts.ModifierFlags.Private) !== 0;
 }
 
+function _isInternal(symbol: ts.Symbol): boolean {
+    return symbol.getJsDocTags().some(tag => tag.name === 'internal')
+        || symbol.name.startsWith('_');
+}
+
 function _isProtected(symbol: ts.Symbol): boolean {
     return !!symbol.valueDeclaration
         // tslint:disable-next-line:no-bitwise

diff --git a/packages/jsii/lib/compiler.ts b/packages/jsii/lib/compiler.ts
@@ -29,6 +29,7 @@ const COMPILER_OPTIONS: ts.CompilerOptions = {
     strict: true,
     strictNullChecks: true,
     strictPropertyInitialization: false,
+    stripInternal: true,
     target: ts.ScriptTarget.ES2018
 };