Merge pull request #4434 from Josmithr/regexp-bundledPackages

api-extractor: Add glob support in `bundledPackages`

Author: octogonz

README.md

@@ -140,6 +140,8 @@ These GitHub repositories provide supplementary resources for Rush Stack:
 | [/build-tests/api-extractor-lib1-test](./build-tests/api-extractor-lib1-test/) | Building this project is a regression test for api-extractor |
 | [/build-tests/api-extractor-lib2-test](./build-tests/api-extractor-lib2-test/) | Building this project is a regression test for api-extractor |
 | [/build-tests/api-extractor-lib3-test](./build-tests/api-extractor-lib3-test/) | Building this project is a regression test for api-extractor |
+| [/build-tests/api-extractor-lib4-test](./build-tests/api-extractor-lib4-test/) | Building this project is a regression test for api-extractor |
+| [/build-tests/api-extractor-lib5-test](./build-tests/api-extractor-lib5-test/) | Building this project is a regression test for api-extractor |
 | [/build-tests/api-extractor-scenarios](./build-tests/api-extractor-scenarios/) | Building this project is a regression test for api-extractor |
 | [/build-tests/api-extractor-test-01](./build-tests/api-extractor-test-01/) | Building this project is a regression test for api-extractor |
 | [/build-tests/api-extractor-test-02](./build-tests/api-extractor-test-02/) | Building this project is a regression test for api-extractor |

apps/api-extractor/package.json

@@ -45,6 +45,7 @@
     "@rushstack/terminal": "workspace:*",
     "@rushstack/ts-command-line": "workspace:*",
     "lodash": "~4.17.15",
+    "minimatch": "~3.0.3",
     "resolve": "~1.22.1",
     "semver": "~7.5.4",
     "source-map": "~0.6.1",
@@ -55,6 +56,7 @@
     "@rushstack/heft": "0.65.5",
     "@types/heft-jest": "1.0.1",
     "@types/lodash": "4.14.116",
+    "@types/minimatch": "3.0.5",
     "@types/node": "18.17.15",
     "@types/resolve": "1.20.2",
     "@types/semver": "7.5.0",

apps/api-extractor/src/api/ExtractorConfig.ts

@@ -837,11 +837,9 @@ export class ExtractorConfig {
       }
 
       const bundledPackages: string[] = configObject.bundledPackages || [];
-      for (const bundledPackage of bundledPackages) {
-        if (!PackageName.isValidName(bundledPackage)) {
-          throw new Error(`The "bundledPackages" list contains an invalid package name: "${bundledPackage}"`);
-        }
-      }
+
+      // Note: we cannot fully validate package name patterns, as the strings may contain wildcards.
+      // We won't know if the entries are valid until we can compare them against the package.json "dependencies" contents.
 
       const tsconfigFilePath: string = ExtractorConfig._resolvePathWithTokens(
         'tsconfigFilePath',

apps/api-extractor/src/api/IConfigFile.ts

@@ -378,8 +378,17 @@ export interface IConfigFile {
    * A list of NPM package names whose exports should be treated as part of this package.
    *
    * @remarks
+   * Also supports glob patterns.
+   * Note: glob patterns will **only** be resolved against dependencies listed in the project's package.json file.
    *
-   * For example, suppose that Webpack is used to generate a distributed bundle for the project `library1`,
+   * * This is both a safety and a performance precaution.
+   *
+   * Exact package names will be applied against any dependency encountered while walking the type graph, regardless of
+   * dependencies listed in the package.json.
+   *
+   * @example
+   *
+   * Suppose that Webpack is used to generate a distributed bundle for the project `library1`,
    * and another NPM package `library2` is embedded in this bundle.  Some types from `library2` may become part
    * of the exported API for `library1`, but by default API Extractor would generate a .d.ts rollup that explicitly
    * imports `library2`.  To avoid this, we can specify:

apps/api-extractor/src/collector/Collector.ts

@@ -3,8 +3,15 @@
 
 import * as ts from 'typescript';
 import * as tsdoc from '@microsoft/tsdoc';
-import { PackageJsonLookup, Sort, InternalError } from '@rushstack/node-core-library';
+import {
+  PackageJsonLookup,
+  Sort,
+  InternalError,
+  type INodePackageJson,
+  PackageName
+} from '@rushstack/node-core-library';
 import { ReleaseTag } from '@microsoft/api-extractor-model';
+import minimatch from 'minimatch';
 
 import { ExtractorMessageId } from '../api/ExtractorMessageId';
 
@@ -132,7 +139,11 @@ export class Collector {
 
     this._tsdocParser = new tsdoc.TSDocParser(this.extractorConfig.tsdocConfiguration);
 
-    this.bundledPackageNames = new Set<string>(this.extractorConfig.bundledPackages);
+    // Resolve package name patterns and store concrete set of bundled package dependency names
+    this.bundledPackageNames = Collector._resolveBundledPackagePatterns(
+      this.extractorConfig.bundledPackages,
+      this.extractorConfig.packageJson
+    );
 
     this.astSymbolTable = new AstSymbolTable(
       this.program,
@@ -147,6 +158,55 @@ export class Collector {
   }
 
   /**
+   * Resolve provided `bundledPackages` names and glob patterns to a list of explicit package names.
+   *
+   * @remarks
+   * Explicit package names will be included in the output unconditionally. However, wildcard patterns will
+   * only be matched against the various dependencies listed in the provided package.json (if there was one).
+   * Patterns will be matched against `dependencies`, `devDependencies`, `optionalDependencies`, and `peerDependencies`.
+   *
+   * @param bundledPackages - The list of package names and/or glob patterns to resolve.
+   * @param packageJson - The package.json of the package being processed (if there is one).
+   * @returns The set of resolved package names to be bundled during analysis.
+   */
+  private static _resolveBundledPackagePatterns(
+    bundledPackages: string[],
+    packageJson: INodePackageJson | undefined
+  ): ReadonlySet<string> {
+    if (bundledPackages.length === 0) {
+      // If no `bundledPackages` were specified, then there is nothing to resolve.
+      // Return an empty set.
+      return new Set<string>();
+    }
+
+    // Accumulate all declared dependencies.
+    // Any wildcard patterns in `bundledPackages` will be resolved against these.
+    const dependencyNames: Set<string> = new Set<string>();
+    Object.keys(packageJson?.dependencies ?? {}).forEach((dep) => dependencyNames.add(dep));
+    Object.keys(packageJson?.devDependencies ?? {}).forEach((dep) => dependencyNames.add(dep));
+    Object.keys(packageJson?.peerDependencies ?? {}).forEach((dep) => dependencyNames.add(dep));
+    Object.keys(packageJson?.optionalDependencies ?? {}).forEach((dep) => dependencyNames.add(dep));
+
+    // The set of resolved package names to be populated and returned
+    const resolvedPackageNames: Set<string> = new Set<string>();
+
+    for (const packageNameOrPattern of bundledPackages) {
+      // If the string is an exact package name, use it regardless of package.json contents
+      if (PackageName.isValidName(packageNameOrPattern)) {
+        resolvedPackageNames.add(packageNameOrPattern);
+      } else {
+        // If the entry isn't an exact package name, assume glob pattern and search for matches
+        for (const dependencyName of dependencyNames) {
+          if (minimatch(dependencyName, packageNameOrPattern)) {
+            resolvedPackageNames.add(dependencyName);
+          }
+        }
+      }
+    }
+    return resolvedPackageNames;
+  }
+
+  /**a
    * Returns a list of names (e.g. "example-library") that should appear in a reference like this:
    *
    * ```

apps/api-extractor/src/generators/DtsRollupGenerator.ts

@@ -107,7 +107,7 @@ export class DtsRollupGenerator {
       if (entity.astEntity instanceof AstImport) {
         // Note: it isn't valid to trim imports based on their release tags.
         // E.g. class Foo (`@public`) extends interface Bar (`@beta`) from some external library.
-        // API-Extractor cannot trim `import { Bar } from "externa-library"` when generating its public rollup,
+        // API-Extractor cannot trim `import { Bar } from "external-library"` when generating its public rollup,
         // or the export of `Foo` would include a broken reference to `Bar`.
         const astImport: AstImport = entity.astEntity;
         DtsEmitHelpers.emitImport(writer, entity, astImport);

apps/api-extractor/src/schemas/api-extractor-template.json

@@ -53,12 +53,19 @@
    * For example, suppose that Webpack is used to generate a distributed bundle for the project "library1",
    * and another NPM package "library2" is embedded in this bundle.  Some types from library2 may become part
    * of the exported API for library1, but by default API Extractor would generate a .d.ts rollup that explicitly
-   * imports library2.  To avoid this, we can specify:
+   * imports library2.  To avoid this, we might specify:
    *
    *   "bundledPackages": [ "library2" ],
    *
    * This would direct API Extractor to embed those types directly in the .d.ts rollup, as if they had been
    * local files for library1.
+   *
+   * The "bundledPackages" elements may specify glob patterns using minimatch syntax.  To ensure deterministic
+   * output, globs are expanded by matching explicitly declared top-level dependencies only.  For example,
+   * the pattern below will NOT match "@my-company/example" unless it appears in a field such as "dependencies"
+   * or "devDependencies" of the project's package.json file:
+   *
+   *   "bundledPackages": [ "@my-company/*" ],
    */
   "bundledPackages": [],
 

apps/api-extractor/src/schemas/api-extractor.schema.json

@@ -24,7 +24,7 @@
     },
 
     "bundledPackages": {
-      "description": "A list of NPM package names whose exports should be treated as part of this package.",
+      "description": "A list of NPM package names whose exports should be treated as part of this package. Also supports glob patterns.",
       "type": "array",
       "items": {
         "type": "string"

build-tests/api-extractor-lib3-test/dist/api-extractor-lib3-test.d.ts

@@ -11,4 +11,9 @@ import { Lib1Class } from 'api-extractor-lib1-test';
 
 export { Lib1Class }
 
+/** @public */
+export declare class Lib3Class {
+    prop: boolean;
+}
+
 export { }

build-tests/api-extractor-lib3-test/etc/api-extractor-lib3-test.api.md

@@ -8,4 +8,10 @@ import { Lib1Class } from 'api-extractor-lib1-test';
 
 export { Lib1Class }
 
+// @public (undocumented)
+export class Lib3Class {
+    // (undocumented)
+    prop: boolean;
+}
+
 ```