microsoft
[api-extractor] TSDoc references from non-internal API exports to internal exports does not error
Summary
Since API-Extractor does not include @internal API exports when generating its doc model, it is impossible for {@link} or {@inheritDoc} references from non-internal API exports to internal API exports to ever be resolved correctly.
API-Extractor has logic that checks for invalid references and reports them via the ae-unresolved-link and ae-unresolved-inheritdoc-reference settings, but the above situation does not trigger these rules.
Given that API-Extractor unconditionally excludes @internal API exports, this situation should ideally be caught.
Example
Consider a package with 2 API exports: foo and bar.
foo is @public, and bar is @internal.
foo's documentation contains {@link bar}.
The package has API-Extractor configured with ae-unresolved-link as an error.
Given that API-Extractor unconditionally strips @internal exports from its doc model, the result of running API-Extractor on this package will yield a model that contains just foo with a doc comment that links to bar, which does not exist in the model.
Repro steps
A repro of the above example can be found here: https://github.com/Josmithr/api-extractor-playground/tree/link-to-internal
Standard questions
Please answer these questions to help us investigate your issue more quickly:
| Question | Answer |
|---|---|
@microsoft/api-extractor version? |
7.52.2 |
| Operating system? | Linux |
| API Extractor scenario? | docs (.api.json) |
| Would you consider contributing a PR? | Yes |
| TypeScript compiler version? | 5.8.2 |
Node.js version (node -v)? |
20.19.0 |
