Merge pull request #2793 from SchoofsKelvin/fix-issue-2791

[api-extractor] Don't export trimmed namespace members during rollup
microsoft · Dec 5, 2023 · b375ec0 · b375ec0
2 parents e785f02 + 8e65f37
commit b375ec0
Show file tree

Hide file tree

Showing 10 changed files with 350 additions and 2 deletions.
diff --git a/apps/api-extractor/src/generators/DtsRollupGenerator.ts b/apps/api-extractor/src/generators/DtsRollupGenerator.ts
@@ -209,6 +209,17 @@ export class DtsRollupGenerator {
             );
           }
 
+          // If the entity's declaration won't be included, then neither should the namespace export it
+          // This fixes the issue encountered here: https://github.com/microsoft/rushstack/issues/2791
+          const exportedSymbolMetadata: SymbolMetadata | undefined =
+            collector.tryFetchMetadataForAstEntity(exportedEntity);
+          const exportedMaxEffectiveReleaseTag: ReleaseTag = exportedSymbolMetadata
+            ? exportedSymbolMetadata.maxEffectiveReleaseTag
+            : ReleaseTag.None;
+          if (!this._shouldIncludeReleaseTag(exportedMaxEffectiveReleaseTag, dtsKind)) {
+            continue;
+          }
+
           if (collectorEntity.nameForEmit === exportedName) {
             exportClauses.push(collectorEntity.nameForEmit);
           } else {

diff --git a/build-tests/api-extractor-scenarios/etc/exportImportStarAs3/api-extractor-scenarios.api.json b/build-tests/api-extractor-scenarios/etc/exportImportStarAs3/api-extractor-scenarios.api.json
@@ -0,0 +1,244 @@
+{
+  "metadata": {
+    "toolPackage": "@microsoft/api-extractor",
+    "toolVersion": "[test mode]",
+    "schemaVersion": 1011,
+    "oldestForwardsCompatibleVersion": 1001,
+    "tsdocConfig": {
+      "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
+      "noStandardTags": true,
+      "tagDefinitions": [
+        {
+          "tagName": "@alpha",
+          "syntaxKind": "modifier"
+        },
+        {
+          "tagName": "@beta",
+          "syntaxKind": "modifier"
+        },
+        {
+          "tagName": "@defaultValue",
+          "syntaxKind": "block"
+        },
+        {
+          "tagName": "@decorator",
+          "syntaxKind": "block",
+          "allowMultiple": true
+        },
+        {
+          "tagName": "@deprecated",
+          "syntaxKind": "block"
+        },
+        {
+          "tagName": "@eventProperty",
+          "syntaxKind": "modifier"
+        },
+        {
+          "tagName": "@example",
+          "syntaxKind": "block",
+          "allowMultiple": true
+        },
+        {
+          "tagName": "@experimental",
+          "syntaxKind": "modifier"
+        },
+        {
+          "tagName": "@inheritDoc",
+          "syntaxKind": "inline"
+        },
+        {
+          "tagName": "@internal",
+          "syntaxKind": "modifier"
+        },
+        {
+          "tagName": "@label",
+          "syntaxKind": "inline"
+        },
+        {
+          "tagName": "@link",
+          "syntaxKind": "inline",
+          "allowMultiple": true
+        },
+        {
+          "tagName": "@override",
+          "syntaxKind": "modifier"
+        },
+        {
+          "tagName": "@packageDocumentation",
+          "syntaxKind": "modifier"
+        },
+        {
+          "tagName": "@param",
+          "syntaxKind": "block",
+          "allowMultiple": true
+        },
+        {
+          "tagName": "@privateRemarks",
+          "syntaxKind": "block"
+        },
+        {
+          "tagName": "@public",
+          "syntaxKind": "modifier"
+        },
+        {
+          "tagName": "@readonly",
+          "syntaxKind": "modifier"
+        },
+        {
+          "tagName": "@remarks",
+          "syntaxKind": "block"
+        },
+        {
+          "tagName": "@returns",
+          "syntaxKind": "block"
+        },
+        {
+          "tagName": "@sealed",
+          "syntaxKind": "modifier"
+        },
+        {
+          "tagName": "@see",
+          "syntaxKind": "block"
+        },
+        {
+          "tagName": "@throws",
+          "syntaxKind": "block",
+          "allowMultiple": true
+        },
+        {
+          "tagName": "@typeParam",
+          "syntaxKind": "block",
+          "allowMultiple": true
+        },
+        {
+          "tagName": "@virtual",
+          "syntaxKind": "modifier"
+        },
+        {
+          "tagName": "@betaDocumentation",
+          "syntaxKind": "modifier"
+        },
+        {
+          "tagName": "@internalRemarks",
+          "syntaxKind": "block"
+        },
+        {
+          "tagName": "@preapproved",
+          "syntaxKind": "modifier"
+        }
+      ],
+      "supportForTags": {
+        "@alpha": true,
+        "@beta": true,
+        "@defaultValue": true,
+        "@decorator": true,
+        "@deprecated": true,
+        "@eventProperty": true,
+        "@example": true,
+        "@experimental": true,
+        "@inheritDoc": true,
+        "@internal": true,
+        "@label": true,
+        "@link": true,
+        "@override": true,
+        "@packageDocumentation": true,
+        "@param": true,
+        "@privateRemarks": true,
+        "@public": true,
+        "@readonly": true,
+        "@remarks": true,
+        "@returns": true,
+        "@sealed": true,
+        "@see": true,
+        "@throws": true,
+        "@typeParam": true,
+        "@virtual": true,
+        "@betaDocumentation": true,
+        "@internalRemarks": true,
+        "@preapproved": true
+      },
+      "reportUnsupportedHtmlElements": false
+    }
+  },
+  "kind": "Package",
+  "canonicalReference": "api-extractor-scenarios!",
+  "docComment": "",
+  "name": "api-extractor-scenarios",
+  "preserveMemberOrder": false,
+  "members": [
+    {
+      "kind": "EntryPoint",
+      "canonicalReference": "api-extractor-scenarios!",
+      "name": "",
+      "preserveMemberOrder": false,
+      "members": [
+        {
+          "kind": "Namespace",
+          "canonicalReference": "api-extractor-scenarios!NS:namespace",
+          "docComment": "",
+          "excerptTokens": [],
+          "fileUrlPath": "src/exportImportStarAs3/index.ts",
+          "releaseTag": "None",
+          "name": "NS",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "Variable",
+              "canonicalReference": "api-extractor-scenarios!NS.NS_BETA:var",
+              "docComment": "/**\n * @beta\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "NS_BETA = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "\"BETA\""
+                }
+              ],
+              "fileUrlPath": "src/exportImportStarAs3/NamespaceWithTrimming.ts",
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isReadonly": true,
+              "releaseTag": "Beta",
+              "name": "NS_BETA",
+              "variableTypeTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              }
+            },
+            {
+              "kind": "Variable",
+              "canonicalReference": "api-extractor-scenarios!NS.NS_PUBLIC:var",
+              "docComment": "/**\n * @public\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "NS_PUBLIC = "
+                },
+                {
+                  "kind": "Content",
+                  "text": "\"PUBLIC\""
+                }
+              ],
+              "fileUrlPath": "src/exportImportStarAs3/NamespaceWithTrimming.ts",
+              "initializerTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isReadonly": true,
+              "releaseTag": "Public",
+              "name": "NS_PUBLIC",
+              "variableTypeTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
diff --git a/.../api-extractor-scenarios/etc/exportImportStarAs3/api-extractor-scenarios.api.md b/.../api-extractor-scenarios/etc/exportImportStarAs3/api-extractor-scenarios.api.md
@@ -0,0 +1,27 @@
+## API Report File for "api-extractor-scenarios"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+declare namespace NS {
+    export {
+        NS_PUBLIC,
+        NS_BETA,
+        NS_INTERNAL
+    }
+}
+export { NS }
+
+// @beta (undocumented)
+const NS_BETA = "BETA";
+
+// @internal (undocumented)
+const NS_INTERNAL = "INTERNAL";
+
+// @public (undocumented)
+const NS_PUBLIC = "PUBLIC";
+
+// (No @packageDocumentation comment for this package)
+
+```
diff --git a/build-tests/api-extractor-scenarios/etc/exportImportStarAs3/rollup-public.d.ts b/build-tests/api-extractor-scenarios/etc/exportImportStarAs3/rollup-public.d.ts
@@ -0,0 +1,15 @@
+declare namespace NS {
+    export {
+        NS_PUBLIC
+    }
+}
+export { NS }
+
+/* Excluded from this release type: NS_BETA */
+
+/* Excluded from this release type: NS_INTERNAL */
+
+/** @public */
+declare const NS_PUBLIC = "PUBLIC";
+
+export { }
diff --git a/build-tests/api-extractor-scenarios/etc/exportImportStarAs3/rollup.d.ts b/build-tests/api-extractor-scenarios/etc/exportImportStarAs3/rollup.d.ts
@@ -0,0 +1,19 @@
+declare namespace NS {
+    export {
+        NS_PUBLIC,
+        NS_BETA,
+        NS_INTERNAL
+    }
+}
+export { NS }
+
+/** @beta */
+declare const NS_BETA = "BETA";
+
+/** @internal */
+declare const NS_INTERNAL = "INTERNAL";
+
+/** @public */
+declare const NS_PUBLIC = "PUBLIC";
+
+export { }
diff --git a/build-tests/api-extractor-scenarios/src/exportImportStarAs3/NamespaceWithTrimming.ts b/build-tests/api-extractor-scenarios/src/exportImportStarAs3/NamespaceWithTrimming.ts
@@ -0,0 +1,8 @@
+/** @public */
+export const NS_PUBLIC = 'PUBLIC';
+
+/** @beta */
+export const NS_BETA = 'BETA';
+
+/** @internal */
+export const NS_INTERNAL = 'INTERNAL';
diff --git a/...tests/api-extractor-scenarios/src/exportImportStarAs3/config/api-extractor-overrides.json b/...tests/api-extractor-scenarios/src/exportImportStarAs3/config/api-extractor-overrides.json
@@ -0,0 +1,7 @@
+{
+  "dtsRollup": {
+    "enabled": true,
+    "untrimmedFilePath": "<projectFolder>/temp/etc/exportImportStarAs3/rollup.d.ts",
+    "publicTrimmedFilePath": "<projectFolder>/temp/etc/exportImportStarAs3/rollup-public.d.ts"
+  }
+}
diff --git a/build-tests/api-extractor-scenarios/src/exportImportStarAs3/index.ts b/build-tests/api-extractor-scenarios/src/exportImportStarAs3/index.ts
@@ -0,0 +1,6 @@
+/**
+ * Test that when exporting namespaces, we don't export members that got trimmed.
+ * See this issue: https://github.com/microsoft/rushstack/issues/2791
+ */
+import * as NS from './NamespaceWithTrimming';
+export { NS };
diff --git a/build-tests/api-extractor-test-04/etc/api-extractor-test-04.api.md b/build-tests/api-extractor-test-04/etc/api-extractor-test-04.api.md
@@ -61,14 +61,14 @@ export namespace EntangledNamespace {
 export type ExportedAlias = AlphaClass;
 
 // Warning: (ae-internal-missing-underscore) The name "InternalClass" should be prefixed with an underscore because the declaration is marked as @internal
-//
+// 
 // @internal
 export class InternalClass {
     undecoratedMember(): void;
 }
 
 // Warning: (ae-internal-missing-underscore) The name "IPublicClassInternalParameters" should be prefixed with an underscore because the declaration is marked as @internal
-//
+// 
 // @internal
 export interface IPublicClassInternalParameters {
 }

diff --git a/common/changes/@microsoft/api-extractor/master_2021-07-07-00-32.json b/common/changes/@microsoft/api-extractor/master_2021-07-07-00-32.json
@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "comment": "Don't export trimmed namespace members during rollup (#2791)",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/api-extractor",
+  "email": "[email protected]"
+}