rushstack icon indicating copy to clipboard operation
rushstack copied to clipboard

[api-extractor] `bundledPackages` fails on API doc links in bundled package to non-re-exported members

Open Josmithr opened this issue 3 years ago • 0 comments

The bundledPackages option is great for managing cross-package re-exports in a way that makes reasoning about the local API surface in a wholistic way. Unfortunately, the tooling currently fails in a key scenario that is blocking my team from being able to adopt it.

Namely, consider the following mono repo scenario: repo

  • package-a
    • apiMember1
    • apiMember2
  • package-b
    • (re-exports) package-a/apiMember1

package-a exports two API members.

/**
 * (Some documentation)
 * Also see {@link apiMember2}
 */
export const apiMember1 = 1;

/**
 * (Some more documentation)
 */
export const apiMember2 = 2;

package-b depends on package-a and re-exports apiMember1 from package-a.

export { apiMember1 } from 'package-a';

When running api-extractor in package-b, it fails with an error about being unable to resolve apiMember1's TSDoc link to apiMember2. E.g.:

Warning: [...]/api-extractor-playground/packages/package-a/dist/apiMember1.d.ts:13:1 - (ae-unresolved-link) The @link reference could not be resolved: The package "@api-extractor-playground/package-b" does not have an export "apiMember2"

In this case, the link should be able to resolve to the package-local symbols for apiMember2 in package-a, but API-Extractor only looks in package-b, and fails to find it.

I am happy to provide more context / examples if needed, but this is really problematic for our environment. bundledPackages would solve a lot of problems for us, both in terms of managing the package API surfaces and for our generated documentation, but this issue is a blocker.

Josmithr avatar Jul 05 '22 22:07 Josmithr