From ba4151dd787af7581a83d533506cc037bf3696a7 Mon Sep 17 00:00:00 2001 From: Kelvin Schoofs <14597409+SchoofsKelvin@users.noreply.github.com> Date: Wed, 7 Jul 2021 02:29:02 +0200 Subject: [PATCH 1/4] [api-extractor] Don't export trimmed namespace members during rollup (#2791) --- .../src/generators/DtsRollupGenerator.ts | 9 ++++++++ .../etc/api-extractor-test-04.api.md | 22 +++++++++++++++++-- .../src/NamespaceWithTrimming.ts | 8 +++++++ .../api-extractor-test-04/src/index.ts | 7 ++++++ 4 files changed, 44 insertions(+), 2 deletions(-) create mode 100644 build-tests/api-extractor-test-04/src/NamespaceWithTrimming.ts diff --git a/apps/api-extractor/src/generators/DtsRollupGenerator.ts b/apps/api-extractor/src/generators/DtsRollupGenerator.ts index 452dcd3b37..69eaafe188 100644 --- a/apps/api-extractor/src/generators/DtsRollupGenerator.ts +++ b/apps/api-extractor/src/generators/DtsRollupGenerator.ts @@ -203,6 +203,15 @@ 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 symbolMetadata: SymbolMetadata | undefined = + collector.tryFetchMetadataForAstEntity(exportedEntity); + const maxEffectiveReleaseTag: ReleaseTag = symbolMetadata + ? symbolMetadata.maxEffectiveReleaseTag + : ReleaseTag.None; + if (!this._shouldIncludeReleaseTag(maxEffectiveReleaseTag, dtsKind)) continue; + if (collectorEntity.nameForEmit === exportedName) { exportClauses.push(collectorEntity.nameForEmit); } else { 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 index 1e0c766263..3142c04114 100644 --- 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 { } @@ -83,6 +83,24 @@ export interface IPublicComplexInterface { export { Lib1Interface } +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"; + // @public export class PublicClass { // @internal diff --git a/build-tests/api-extractor-test-04/src/NamespaceWithTrimming.ts b/build-tests/api-extractor-test-04/src/NamespaceWithTrimming.ts new file mode 100644 index 0000000000..7045c1aa3e --- /dev/null +++ b/build-tests/api-extractor-test-04/src/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/build-tests/api-extractor-test-04/src/index.ts b/build-tests/api-extractor-test-04/src/index.ts index dbb54cf803..73d1408013 100644 --- a/build-tests/api-extractor-test-04/src/index.ts +++ b/build-tests/api-extractor-test-04/src/index.ts @@ -36,3 +36,10 @@ export type ExportedAlias = AlphaClass; export { IPublicComplexInterface } from './IPublicComplexInterface'; export { Lib1Interface } from 'api-extractor-lib1-test'; + +/** + * 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 }; From 73f21c08dff150d0dc1083db3bdce07f4166407b Mon Sep 17 00:00:00 2001 From: Kelvin Schoofs <14597409+SchoofsKelvin@users.noreply.github.com> Date: Wed, 7 Jul 2021 02:34:19 +0200 Subject: [PATCH 2/4] Add rush change file --- .../api-extractor/master_2021-07-07-00-32.json | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 common/changes/@microsoft/api-extractor/master_2021-07-07-00-32.json 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 new file mode 100644 index 0000000000..0702cbb950 --- /dev/null +++ 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": "14597409+SchoofsKelvin@users.noreply.github.com" +} \ No newline at end of file From 357d626a55a62540b897e866ec428f8dcfc6b6a7 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Mon, 4 Dec 2023 12:52:15 -0800 Subject: [PATCH 3/4] Move test case to the api-extractor-scenarios project --- .../api-extractor-scenarios.api.json | 244 ++++++++++++++++++ .../api-extractor-scenarios.api.md | 27 ++ .../exportImportStarAs3/rollup-public.d.ts | 15 ++ .../etc/exportImportStarAs3/rollup.d.ts | 19 ++ .../NamespaceWithTrimming.ts | 0 .../config/api-extractor-overrides.json | 7 + .../src/exportImportStarAs3/index.ts | 6 + .../etc/api-extractor-test-04.api.md | 22 +- .../api-extractor-test-04/src/index.ts | 7 - 9 files changed, 320 insertions(+), 27 deletions(-) create mode 100644 build-tests/api-extractor-scenarios/etc/exportImportStarAs3/api-extractor-scenarios.api.json create mode 100644 build-tests/api-extractor-scenarios/etc/exportImportStarAs3/api-extractor-scenarios.api.md create mode 100644 build-tests/api-extractor-scenarios/etc/exportImportStarAs3/rollup-public.d.ts create mode 100644 build-tests/api-extractor-scenarios/etc/exportImportStarAs3/rollup.d.ts rename build-tests/{api-extractor-test-04/src => api-extractor-scenarios/src/exportImportStarAs3}/NamespaceWithTrimming.ts (100%) create mode 100644 build-tests/api-extractor-scenarios/src/exportImportStarAs3/config/api-extractor-overrides.json create mode 100644 build-tests/api-extractor-scenarios/src/exportImportStarAs3/index.ts 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 new file mode 100644 index 0000000000..7d32f70cb3 --- /dev/null +++ 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/build-tests/api-extractor-scenarios/etc/exportImportStarAs3/api-extractor-scenarios.api.md b/build-tests/api-extractor-scenarios/etc/exportImportStarAs3/api-extractor-scenarios.api.md new file mode 100644 index 0000000000..e9a2e07d1b --- /dev/null +++ b/build-tests/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 new file mode 100644 index 0000000000..386f2a3006 --- /dev/null +++ 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 new file mode 100644 index 0000000000..c2331582e0 --- /dev/null +++ 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-test-04/src/NamespaceWithTrimming.ts b/build-tests/api-extractor-scenarios/src/exportImportStarAs3/NamespaceWithTrimming.ts similarity index 100% rename from build-tests/api-extractor-test-04/src/NamespaceWithTrimming.ts rename to build-tests/api-extractor-scenarios/src/exportImportStarAs3/NamespaceWithTrimming.ts diff --git a/build-tests/api-extractor-scenarios/src/exportImportStarAs3/config/api-extractor-overrides.json b/build-tests/api-extractor-scenarios/src/exportImportStarAs3/config/api-extractor-overrides.json new file mode 100644 index 0000000000..56d14e1823 --- /dev/null +++ b/build-tests/api-extractor-scenarios/src/exportImportStarAs3/config/api-extractor-overrides.json @@ -0,0 +1,7 @@ +{ + "dtsRollup": { + "enabled": true, + "untrimmedFilePath": "/temp/etc/exportImportStarAs3/rollup.d.ts", + "publicTrimmedFilePath": "/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 new file mode 100644 index 0000000000..0afcd1c27e --- /dev/null +++ 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 index 3142c04114..1e0c766263 100644 --- 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 { } @@ -83,24 +83,6 @@ export interface IPublicComplexInterface { export { Lib1Interface } -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"; - // @public export class PublicClass { // @internal diff --git a/build-tests/api-extractor-test-04/src/index.ts b/build-tests/api-extractor-test-04/src/index.ts index 73d1408013..dbb54cf803 100644 --- a/build-tests/api-extractor-test-04/src/index.ts +++ b/build-tests/api-extractor-test-04/src/index.ts @@ -36,10 +36,3 @@ export type ExportedAlias = AlphaClass; export { IPublicComplexInterface } from './IPublicComplexInterface'; export { Lib1Interface } from 'api-extractor-lib1-test'; - -/** - * 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 }; From 8e65f37f55e3b174d42703ccb1fd2380e3f5d990 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Mon, 4 Dec 2023 13:03:20 -0800 Subject: [PATCH 4/4] Fix lint issues --- .../api-extractor/src/generators/DtsRollupGenerator.ts | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/apps/api-extractor/src/generators/DtsRollupGenerator.ts b/apps/api-extractor/src/generators/DtsRollupGenerator.ts index a11a01498a..7a9e9fb555 100644 --- a/apps/api-extractor/src/generators/DtsRollupGenerator.ts +++ b/apps/api-extractor/src/generators/DtsRollupGenerator.ts @@ -211,12 +211,14 @@ 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 symbolMetadata: SymbolMetadata | undefined = + const exportedSymbolMetadata: SymbolMetadata | undefined = collector.tryFetchMetadataForAstEntity(exportedEntity); - const maxEffectiveReleaseTag: ReleaseTag = symbolMetadata - ? symbolMetadata.maxEffectiveReleaseTag + const exportedMaxEffectiveReleaseTag: ReleaseTag = exportedSymbolMetadata + ? exportedSymbolMetadata.maxEffectiveReleaseTag : ReleaseTag.None; - if (!this._shouldIncludeReleaseTag(maxEffectiveReleaseTag, dtsKind)) continue; + if (!this._shouldIncludeReleaseTag(exportedMaxEffectiveReleaseTag, dtsKind)) { + continue; + } if (collectorEntity.nameForEmit === exportedName) { exportClauses.push(collectorEntity.nameForEmit);