@microsoft/api-extractor 7.29.5 → 7.31.0

package/lib/generators/ApiModelGenerator.js

@@ -38,7 +38,7 @@ class ApiModelGenerator {
     constructor(collector) {
         this._collector = collector;
         this._apiModel = new api_extractor_model_1.ApiModel();
-        this._referenceGenerator = new DeclarationReferenceGenerator_1.DeclarationReferenceGenerator(collector.packageJsonLookup, collector.workingPackage.name, collector.program, collector.typeChecker, collector.bundledPackageNames);
+        this._referenceGenerator = new DeclarationReferenceGenerator_1.DeclarationReferenceGenerator(collector);
     }
     get apiModel() {
         return this._apiModel;
@@ -53,19 +53,25 @@ class ApiModelGenerator {
         this._apiModel.addMember(apiPackage);
         const apiEntryPoint = new api_extractor_model_1.ApiEntryPoint({ name: '' });
         apiPackage.addMember(apiEntryPoint);
-        // Create a CollectorEntity for each top-level export
         for (const entity of this._collector.entities) {
-            if (entity.exported) {
-                this._processAstEntity(entity.astEntity, entity.nameForEmit, apiEntryPoint);
+            // Only process entities that are exported from the entry point. Entities that are exported from
+            // `AstNamespaceImport` entities will be processed by `_processAstNamespaceImport`. However, if
+            // we are including forgotten exports, then process everything.
+            if (entity.exportedFromEntryPoint || this._collector.extractorConfig.docModelIncludeForgottenExports) {
+                this._processAstEntity(entity.astEntity, {
+                    name: entity.nameForEmit,
+                    isExported: entity.exportedFromEntryPoint,
+                    parentApiItem: apiEntryPoint
+                });
             }
         }
         return apiPackage;
     }
-    _processAstEntity(astEntity, exportedName, parentApiItem) {
+    _processAstEntity(astEntity, context) {
         if (astEntity instanceof AstSymbol_1.AstSymbol) {
             // Skip ancillary declarations; we will process them with the main declaration
             for (const astDeclaration of this._collector.getNonAncillaryDeclarations(astEntity)) {
-                this._processDeclaration(astDeclaration, exportedName, parentApiItem);
+                this._processDeclaration(astDeclaration, context);
             }
             return;
         }
@@ -80,19 +86,20 @@ class ApiModelGenerator {
             //   export { example1, example2 }
             //
             // The current logic does not try to associate "thing()" with a specific parent.  Instead
-            // the API documentation will show duplicated entries for example1.thing() and example2.thing()./
+            // the API documentation will show duplicated entries for example1.thing() and example2.thing().
             //
             // This could be improved in the future, but it requires a stable mechanism for choosing an associated parent.
             // For thoughts about this:  https://github.com/microsoft/rushstack/issues/1308
-            this._processAstModule(astEntity.astModule, exportedName, parentApiItem);
+            this._processAstNamespaceImport(astEntity, context);
             return;
         }
         // TODO: Figure out how to represent reexported AstImport objects.  Basically we need to introduce a new
         // ApiItem subclass for "export alias", similar to a type alias, but representing declarations of the
         // form "export { X } from 'external-package'".  We can also use this to solve GitHub issue #950.
     }
-    _processAstModule(astModule, exportedName, parentApiItem) {
-        const name = exportedName ? exportedName : astModule.moduleSymbol.name;
+    _processAstNamespaceImport(astNamespaceImport, context) {
+        const astModule = astNamespaceImport.astModule;
+        const { name, isExported, parentApiItem } = context;
         const containerKey = api_extractor_model_1.ApiNamespace.getContainerKey(name);
         let apiNamespace = parentApiItem.tryGetMemberByKey(containerKey);
         if (apiNamespace === undefined) {
@@ -100,15 +107,20 @@ class ApiModelGenerator {
                 name,
                 docComment: undefined,
                 releaseTag: api_extractor_model_1.ReleaseTag.None,
-                excerptTokens: []
+                excerptTokens: [],
+                isExported
             });
             parentApiItem.addMember(apiNamespace);
         }
         astModule.astModuleExportInfo.exportedLocalEntities.forEach((exportedEntity, exportedName) => {
-            this._processAstEntity(exportedEntity, exportedName, apiNamespace);
+            this._processAstEntity(exportedEntity, {
+                name: exportedName,
+                isExported: true,
+                parentApiItem: apiNamespace
+            });
         });
     }
-    _processDeclaration(astDeclaration, exportedName, parentApiItem) {
+    _processDeclaration(astDeclaration, context) {
         if ((astDeclaration.modifierFlags & ts.ModifierFlags.Private) !== 0) {
             return; // trim out private declarations
         }
@@ -119,69 +131,70 @@ class ApiModelGenerator {
         }
         switch (astDeclaration.declaration.kind) {
             case ts.SyntaxKind.CallSignature:
-                this._processApiCallSignature(astDeclaration, exportedName, parentApiItem);
+                this._processApiCallSignature(astDeclaration, context);
                 break;
             case ts.SyntaxKind.Constructor:
-                this._processApiConstructor(astDeclaration, exportedName, parentApiItem);
+                this._processApiConstructor(astDeclaration, context);
                 break;
             case ts.SyntaxKind.ConstructSignature:
-                this._processApiConstructSignature(astDeclaration, exportedName, parentApiItem);
+                this._processApiConstructSignature(astDeclaration, context);
                 break;
             case ts.SyntaxKind.ClassDeclaration:
-                this._processApiClass(astDeclaration, exportedName, parentApiItem);
+                this._processApiClass(astDeclaration, context);
                 break;
             case ts.SyntaxKind.EnumDeclaration:
-                this._processApiEnum(astDeclaration, exportedName, parentApiItem);
+                this._processApiEnum(astDeclaration, context);
                 break;
             case ts.SyntaxKind.EnumMember:
-                this._processApiEnumMember(astDeclaration, exportedName, parentApiItem);
+                this._processApiEnumMember(astDeclaration, context);
                 break;
             case ts.SyntaxKind.FunctionDeclaration:
-                this._processApiFunction(astDeclaration, exportedName, parentApiItem);
+                this._processApiFunction(astDeclaration, context);
                 break;
             case ts.SyntaxKind.GetAccessor:
-                this._processApiProperty(astDeclaration, exportedName, parentApiItem);
+                this._processApiProperty(astDeclaration, context);
                 break;
             case ts.SyntaxKind.SetAccessor:
-                this._processApiProperty(astDeclaration, exportedName, parentApiItem);
+                this._processApiProperty(astDeclaration, context);
                 break;
             case ts.SyntaxKind.IndexSignature:
-                this._processApiIndexSignature(astDeclaration, exportedName, parentApiItem);
+                this._processApiIndexSignature(astDeclaration, context);
                 break;
             case ts.SyntaxKind.InterfaceDeclaration:
-                this._processApiInterface(astDeclaration, exportedName, parentApiItem);
+                this._processApiInterface(astDeclaration, context);
                 break;
             case ts.SyntaxKind.MethodDeclaration:
-                this._processApiMethod(astDeclaration, exportedName, parentApiItem);
+                this._processApiMethod(astDeclaration, context);
                 break;
             case ts.SyntaxKind.MethodSignature:
-                this._processApiMethodSignature(astDeclaration, exportedName, parentApiItem);
+                this._processApiMethodSignature(astDeclaration, context);
                 break;
             case ts.SyntaxKind.ModuleDeclaration:
-                this._processApiNamespace(astDeclaration, exportedName, parentApiItem);
+                this._processApiNamespace(astDeclaration, context);
                 break;
             case ts.SyntaxKind.PropertyDeclaration:
-                this._processApiProperty(astDeclaration, exportedName, parentApiItem);
+                this._processApiProperty(astDeclaration, context);
                 break;
             case ts.SyntaxKind.PropertySignature:
-                this._processApiPropertySignature(astDeclaration, exportedName, parentApiItem);
+                this._processApiPropertySignature(astDeclaration, context);
                 break;
             case ts.SyntaxKind.TypeAliasDeclaration:
-                this._processApiTypeAlias(astDeclaration, exportedName, parentApiItem);
+                this._processApiTypeAlias(astDeclaration, context);
                 break;
             case ts.SyntaxKind.VariableDeclaration:
-                this._processApiVariable(astDeclaration, exportedName, parentApiItem);
+                this._processApiVariable(astDeclaration, context);
                 break;
             default:
             // ignore unknown types
         }
     }
-    _processChildDeclarations(astDeclaration, exportedName, parentApiItem) {
+    _processChildDeclarations(astDeclaration, context) {
         for (const childDeclaration of astDeclaration.children) {
-            this._processDeclaration(childDeclaration, undefined, parentApiItem);
+            this._processDeclaration(childDeclaration, Object.assign(Object.assign({}, context), { name: childDeclaration.astSymbol.localName }));
         }
     }
-    _processApiCallSignature(astDeclaration, exportedName, parentApiItem) {
+    _processApiCallSignature(astDeclaration, context) {
+        const { parentApiItem } = context;
         const overloadIndex = this._collector.getOverloadIndex(astDeclaration);
         const containerKey = api_extractor_model_1.ApiCallSignature.getContainerKey(overloadIndex);
         let apiCallSignature = parentApiItem.tryGetMemberByKey(containerKey);
@@ -208,7 +221,8 @@ class ApiModelGenerator {
             parentApiItem.addMember(apiCallSignature);
         }
     }
-    _processApiConstructor(astDeclaration, exportedName, parentApiItem) {
+    _processApiConstructor(astDeclaration, context) {
+        const { parentApiItem } = context;
         const overloadIndex = this._collector.getOverloadIndex(astDeclaration);
         const containerKey = api_extractor_model_1.ApiConstructor.getContainerKey(overloadIndex);
         let apiConstructor = parentApiItem.tryGetMemberByKey(containerKey);
@@ -232,8 +246,8 @@ class ApiModelGenerator {
             parentApiItem.addMember(apiConstructor);
         }
     }
-    _processApiClass(astDeclaration, exportedName, parentApiItem) {
-        const name = exportedName ? exportedName : astDeclaration.astSymbol.localName;
+    _processApiClass(astDeclaration, context) {
+        const { name, isExported, parentApiItem } = context;
         const containerKey = api_extractor_model_1.ApiClass.getContainerKey(name);
         let apiClass = parentApiItem.tryGetMemberByKey(containerKey);
         if (apiClass === undefined) {
@@ -268,13 +282,15 @@ class ApiModelGenerator {
                 excerptTokens,
                 typeParameters,
                 extendsTokenRange,
-                implementsTokenRanges
+                implementsTokenRanges,
+                isExported
             });
             parentApiItem.addMember(apiClass);
         }
-        this._processChildDeclarations(astDeclaration, exportedName, apiClass);
+        this._processChildDeclarations(astDeclaration, Object.assign(Object.assign({}, context), { parentApiItem: apiClass }));
     }
-    _processApiConstructSignature(astDeclaration, exportedName, parentApiItem) {
+    _processApiConstructSignature(astDeclaration, context) {
+        const { parentApiItem } = context;
         const overloadIndex = this._collector.getOverloadIndex(astDeclaration);
         const containerKey = api_extractor_model_1.ApiConstructSignature.getContainerKey(overloadIndex);
         let apiConstructSignature = parentApiItem.tryGetMemberByKey(containerKey);
@@ -301,8 +317,8 @@ class ApiModelGenerator {
             parentApiItem.addMember(apiConstructSignature);
         }
     }
-    _processApiEnum(astDeclaration, exportedName, parentApiItem) {
-        const name = exportedName ? exportedName : astDeclaration.astSymbol.localName;
+    _processApiEnum(astDeclaration, context) {
+        const { name, isExported, parentApiItem } = context;
         const containerKey = api_extractor_model_1.ApiEnum.getContainerKey(name);
         let apiEnum = parentApiItem.tryGetMemberByKey(containerKey);
         if (apiEnum === undefined) {
@@ -311,13 +327,20 @@ class ApiModelGenerator {
             const docComment = apiItemMetadata.tsdocComment;
             const releaseTag = apiItemMetadata.effectiveReleaseTag;
             const preserveMemberOrder = this._collector.extractorConfig.enumMemberOrder === api_extractor_model_1.EnumMemberOrder.Preserve;
-            apiEnum = new api_extractor_model_1.ApiEnum({ name, docComment, releaseTag, excerptTokens, preserveMemberOrder });
+            apiEnum = new api_extractor_model_1.ApiEnum({
+                name,
+                docComment,
+                releaseTag,
+                excerptTokens,
+                preserveMemberOrder,
+                isExported
+            });
             parentApiItem.addMember(apiEnum);
         }
-        this._processChildDeclarations(astDeclaration, exportedName, apiEnum);
+        this._processChildDeclarations(astDeclaration, Object.assign(Object.assign({}, context), { parentApiItem: apiEnum }));
     }
-    _processApiEnumMember(astDeclaration, exportedName, parentApiItem) {
-        const name = exportedName ? exportedName : astDeclaration.astSymbol.localName;
+    _processApiEnumMember(astDeclaration, context) {
+        const { name, parentApiItem } = context;
         const containerKey = api_extractor_model_1.ApiEnumMember.getContainerKey(name);
         let apiEnumMember = parentApiItem.tryGetMemberByKey(containerKey);
         if (apiEnumMember === undefined) {
@@ -342,8 +365,8 @@ class ApiModelGenerator {
             parentApiItem.addMember(apiEnumMember);
         }
     }
-    _processApiFunction(astDeclaration, exportedName, parentApiItem) {
-        const name = exportedName ? exportedName : astDeclaration.astSymbol.localName;
+    _processApiFunction(astDeclaration, context) {
+        const { name, isExported, parentApiItem } = context;
         const overloadIndex = this._collector.getOverloadIndex(astDeclaration);
         const containerKey = api_extractor_model_1.ApiFunction.getContainerKey(name, overloadIndex);
         let apiFunction = parentApiItem.tryGetMemberByKey(containerKey);
@@ -358,9 +381,6 @@ class ApiModelGenerator {
             const apiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
             const docComment = apiItemMetadata.tsdocComment;
             const releaseTag = apiItemMetadata.effectiveReleaseTag;
-            if (releaseTag === api_extractor_model_1.ReleaseTag.Internal || releaseTag === api_extractor_model_1.ReleaseTag.Alpha) {
-                return; // trim out items marked as "@internal" or "@alpha"
-            }
             apiFunction = new api_extractor_model_1.ApiFunction({
                 name,
                 docComment,
@@ -369,12 +389,14 @@ class ApiModelGenerator {
                 parameters,
                 overloadIndex,
                 excerptTokens,
-                returnTypeTokenRange
+                returnTypeTokenRange,
+                isExported
             });
             parentApiItem.addMember(apiFunction);
         }
     }
-    _processApiIndexSignature(astDeclaration, exportedName, parentApiItem) {
+    _processApiIndexSignature(astDeclaration, context) {
+        const { parentApiItem } = context;
         const overloadIndex = this._collector.getOverloadIndex(astDeclaration);
         const containerKey = api_extractor_model_1.ApiIndexSignature.getContainerKey(overloadIndex);
         let apiIndexSignature = parentApiItem.tryGetMemberByKey(containerKey);
@@ -401,8 +423,8 @@ class ApiModelGenerator {
             parentApiItem.addMember(apiIndexSignature);
         }
     }
-    _processApiInterface(astDeclaration, exportedName, parentApiItem) {
-        const name = exportedName ? exportedName : astDeclaration.astSymbol.localName;
+    _processApiInterface(astDeclaration, context) {
+        const { name, isExported, parentApiItem } = context;
         const containerKey = api_extractor_model_1.ApiInterface.getContainerKey(name);
         let apiInterface = parentApiItem.tryGetMemberByKey(containerKey);
         if (apiInterface === undefined) {
@@ -429,14 +451,15 @@ class ApiModelGenerator {
                 releaseTag,
                 excerptTokens,
                 typeParameters,
-                extendsTokenRanges
+                extendsTokenRanges,
+                isExported
             });
             parentApiItem.addMember(apiInterface);
         }
-        this._processChildDeclarations(astDeclaration, exportedName, apiInterface);
+        this._processChildDeclarations(astDeclaration, Object.assign(Object.assign({}, context), { parentApiItem: apiInterface }));
     }
-    _processApiMethod(astDeclaration, exportedName, parentApiItem) {
-        const name = exportedName ? exportedName : astDeclaration.astSymbol.localName;
+    _processApiMethod(astDeclaration, context) {
+        const { name, parentApiItem } = context;
         const isStatic = (astDeclaration.modifierFlags & ts.ModifierFlags.Static) !== 0;
         const overloadIndex = this._collector.getOverloadIndex(astDeclaration);
         const containerKey = api_extractor_model_1.ApiMethod.getContainerKey(name, isStatic, overloadIndex);
@@ -473,8 +496,8 @@ class ApiModelGenerator {
             parentApiItem.addMember(apiMethod);
         }
     }
-    _processApiMethodSignature(astDeclaration, exportedName, parentApiItem) {
-        const name = exportedName ? exportedName : astDeclaration.astSymbol.localName;
+    _processApiMethodSignature(astDeclaration, context) {
+        const { name, parentApiItem } = context;
         const overloadIndex = this._collector.getOverloadIndex(astDeclaration);
         const containerKey = api_extractor_model_1.ApiMethodSignature.getContainerKey(name, overloadIndex);
         let apiMethodSignature = parentApiItem.tryGetMemberByKey(containerKey);
@@ -504,8 +527,8 @@ class ApiModelGenerator {
             parentApiItem.addMember(apiMethodSignature);
         }
     }
-    _processApiNamespace(astDeclaration, exportedName, parentApiItem) {
-        const name = exportedName ? exportedName : astDeclaration.astSymbol.localName;
+    _processApiNamespace(astDeclaration, context) {
+        const { name, isExported, parentApiItem } = context;
         const containerKey = api_extractor_model_1.ApiNamespace.getContainerKey(name);
         let apiNamespace = parentApiItem.tryGetMemberByKey(containerKey);
         if (apiNamespace === undefined) {
@@ -513,13 +536,13 @@ class ApiModelGenerator {
             const apiItemMetadata = this._collector.fetchApiItemMetadata(astDeclaration);
             const docComment = apiItemMetadata.tsdocComment;
             const releaseTag = apiItemMetadata.effectiveReleaseTag;
-            apiNamespace = new api_extractor_model_1.ApiNamespace({ name, docComment, releaseTag, excerptTokens });
+            apiNamespace = new api_extractor_model_1.ApiNamespace({ name, docComment, releaseTag, excerptTokens, isExported });
             parentApiItem.addMember(apiNamespace);
         }
-        this._processChildDeclarations(astDeclaration, exportedName, apiNamespace);
+        this._processChildDeclarations(astDeclaration, Object.assign(Object.assign({}, context), { parentApiItem: apiNamespace }));
     }
-    _processApiProperty(astDeclaration, exportedName, parentApiItem) {
-        const name = exportedName ? exportedName : astDeclaration.astSymbol.localName;
+    _processApiProperty(astDeclaration, context) {
+        const { name, parentApiItem } = context;
         const isStatic = (astDeclaration.modifierFlags & ts.ModifierFlags.Static) !== 0;
         const containerKey = api_extractor_model_1.ApiProperty.getContainerKey(name, isStatic);
         let apiProperty = parentApiItem.tryGetMemberByKey(containerKey);
@@ -567,8 +590,8 @@ class ApiModelGenerator {
             // we assume its signature is identical, because the language requires that.
         }
     }
-    _processApiPropertySignature(astDeclaration, exportedName, parentApiItem) {
-        const name = exportedName ? exportedName : astDeclaration.astSymbol.localName;
+    _processApiPropertySignature(astDeclaration, context) {
+        const { name, parentApiItem } = context;
         const containerKey = api_extractor_model_1.ApiPropertySignature.getContainerKey(name);
         let apiPropertySignature = parentApiItem.tryGetMemberByKey(containerKey);
         if (apiPropertySignature === undefined) {
@@ -598,8 +621,8 @@ class ApiModelGenerator {
             // we assume its signature is identical, because the language requires that.
         }
     }
-    _processApiTypeAlias(astDeclaration, exportedName, parentApiItem) {
-        const name = exportedName ? exportedName : astDeclaration.astSymbol.localName;
+    _processApiTypeAlias(astDeclaration, context) {
+        const { name, isExported, parentApiItem } = context;
         const containerKey = api_extractor_model_1.ApiTypeAlias.getContainerKey(name);
         let apiTypeAlias = parentApiItem.tryGetMemberByKey(containerKey);
         if (apiTypeAlias === undefined) {
@@ -618,13 +641,14 @@ class ApiModelGenerator {
                 typeParameters,
                 releaseTag,
                 excerptTokens,
-                typeTokenRange
+                typeTokenRange,
+                isExported
             });
             parentApiItem.addMember(apiTypeAlias);
         }
     }
-    _processApiVariable(astDeclaration, exportedName, parentApiItem) {
-        const name = exportedName ? exportedName : astDeclaration.astSymbol.localName;
+    _processApiVariable(astDeclaration, context) {
+        const { name, isExported, parentApiItem } = context;
         const containerKey = api_extractor_model_1.ApiVariable.getContainerKey(name);
         let apiVariable = parentApiItem.tryGetMemberByKey(containerKey);
         if (apiVariable === undefined) {
@@ -649,7 +673,8 @@ class ApiModelGenerator {
                 excerptTokens,
                 variableTypeTokenRange,
                 initializerTokenRange,
-                isReadonly
+                isReadonly,
+                isExported
             });
             parentApiItem.addMember(apiVariable);
         }