[api-extractor] Incorrect canonical reference to aliased class in .api.json

[fwienber]

Summary

While waiting for #1596 to be implemented, I tried to find a workaround to generate documentation for our packages that have multiple entry-points under different paths, but did not succeed caused by what I consider bugs in api-extractor's canonical reference resolving.

For packages with multiple entry points, which api-extractor currently does not support, this comment suggests the following approach:

If you don't need rollups, as a workaround you can simply create a fake entry point that reexports all your real entry points. That will work reasonably well for the API report and documentation features.

The "legacy" public API we want to generate documentation for uses one file per class and groups classes into subdirectories. To keep the original structure and to avoid name clashes, we must somehow retain the path name in the fake entry point.

To achieve this, I tried two approaches for the "fake" entry point index.d.ts:

1. Alias the classes with a path prefix, like so:
   export { Foo as subpath_Foo } from "./subpath/Foo"
2. Re-export only direct members and convert sub-paths to namespaces with their own index.d.ts, which can then be re-exported like so:
   import * as subpath from "./subpath"; export { subpath }
   (this is the suggested workaround for export * as subpath from "./subpath" not yet being supported by api-extractor)

Both approaches lead to incorrect references from a subclass to its (aliased) superclass.

Repro steps

To reproduce, clone the example repo and run

api-extractor run --local

The example project contains a src folder with four TypeScript .d.ts files with one class declaration each: A, B, somepath/A and somepath/B. In both cases, B is a subclass of A.
There is a "fake" entry point file src/index.d.ts, which re-exports all four entry points. It implements both approaches described above, namely using aliases and using a namespace, for which there is another "fake" sub-entry point src/somepath/index.d.ts that re-exports A and B from under the somepath path.

Expected result:

The generated file input/api-extractor-test.api.json should contain the correct canonical reference from namespaced module somepath.B to its superclass somepath.A:

    "canonicalReference": "api-extractor-test!somepath.A:class"

and/or the correct canonical reference from aliased module somepath_B to its superclass somepath_A:

    "canonicalReference": "api-extractor-test!somepath_A:class"

Actual result:

For both approaches, the reference incorrectly points to the top-level A:

    "canonicalReference": "api-extractor-test!A:class"

If you find the JSON file too confusing, you can generate Markdown files simply by calling

api-documenter markdown

The resulting Markdown files in folder markdown contain the corresponding wrong hyperlinks in file api-extractor-test.somepath.b.md ([A](./api-extractor-test.a.md) instead of [A](./api-extractor-test.somepath.a.md)) and api-extractor-test.somepath_b.md ([A](./api-extractor-test.a.md) instead of [A](./api-extractor-test.somepath_a.md)).
Of course, this is not api-documenter's fault, as the *.api.json file already contains the wrong canonical references.

Details

It seems that neither alias support (export { __ as __ }) nor namespace aliases (import * as __) are taken into account when resolving references.

The name-clash between A and somepath/A has been used to motivate the need for aliasing, but even without an actual clash, it still does not work.
If you change the name of somepath/A to something else in the example workspace, the superclass reference of somepath/B in api-extractor's output points to an incorrect, non-existing module name (also missing the path-part of the actual module name) and thus no hyperlink at all is rendered by api-documenter.

Standard questions

Please answer these questions to help us investigate your issue more quickly:

Question	Answer
@microsoft/api-extractor version?	7.29.2
Operating system?	Linux
API Extractor scenario?	docs (.api.json)
Would you consider contributing a PR?	Maybe (need help)
TypeScript compiler version?	4.7.4
Node.js version (node -v)?	v16.15.1

[zelliott]

Thanks for the amazing repro repository. I was able to repro the bug you described.

Some background: There are two separate code paths that generate declaration references.

1. Declaration references generated by api-extractor-model from the .api.json structure itself.
2. Declaration references generated by api-extractor via the DeclarationReferenceGenerator class.

The declaration references generated by code path 1 (by api-extractor-model) are the ones that are fields on each API item in the .api.json. You'll notice that these declaration references are as you'd expect (i.e. "api-extractor-test!somepath_A:class" instead of "api-extractor-test!A:class"). The model constructs these declaration references from its own structure.

The declaration references generated by code path 2 (by api-extractor) are the ones within each reference token. These declaration references are incorrect, as you've identified. Looking at each incorrect example one at a time...

• Expected: "api-extractor-test!somepath_A:class": When DeclarationReferenceGenerator attempts to generate a declaration reference for A, it doesn't know that "A" was "renamed" to "somepath_A" from the perspective of the package entry point. This knowledge is in the Collector, which DeclarationReferenceGenerator can easily use. The Collector creates a CollectorEntity for each of these symbols, and stores the nameForEmit which I believe will be "somepath_A" for symbol A.
• Expected: "api-extractor-test!somepath.A:class": When DeclarationReferenceGenerator attempts to generate a declaration reference for A, it seems to think the parent symbol is "the package entry point", when in fact it's the namespace somepath. I think the bug is somewhere in DeclarationReferenceGenerator._getParentReference.

I think both of these bugs should be fixable. You mentioned you might be interested in contributing a fix - is this enough to go off of? A good first step would be to create a mini reproducible test case in api-extractor-scenarios (our test project that includes various test scenarios) (if one doesn't already exist), and begin to familiarize yourself with DeclarationReferenceGenerator (step through it with breakpoints, etc).

[fwienber]

Thanks @zelliott for the detailed information - looks like a perfect starting point for me getting into this.

A good first step would be to create a mini reproducible test case in api-extractor-scenarios (our test project that includes various test scenarios) (if one doesn't already exist)

That should be simple to derive from the example I came up with, right?

, and begin to familiarize yourself with DeclarationReferenceGenerator (step through it with breakpoints, etc).

Actually, I already did that while trying to figure out what goes wrong, so it seems I am on the right track. That said, I did not yet come across the Collector, so thanks for that pointer.

One question, iirc I had one (!) unit test failure when running the api-extractor tests on main branch (without any code changes). If that is still the case, where could I report this / get help?

[fwienber]

So after updating main, the test failure is gone 😅 and I added my test scenario.
From the input scenario in src/, the output is generated into etc/, so far, so good. But is the only way to see that the test has passed that there is no git diff?

Remark: When running the tests under Linux (or more precise WSL 2), all generated text files use Windows line endings instead of Linux line endings, resulting in a gif diff. I helped myself by converting all touched files with dos2unix to see the "real" diff.

[fwienber]

Concerning the remark: It seems the reason for this behavior is that crlf is the default in api-extractor (not os, which imho would make more sense) and the build-tests do not explicitly set newlineKind: 'os' (which should be added here).
This seems to be one of the rare occasions where it becomes noticeable that TypeScript and its tools are a Microsoft product ;-)

May I include the fix in runScenarios.ts in my PR, or would you prefer a clean separation?

[zelliott]

That should be simple to derive from the example I came up with, right?

Yes! There's a good chance one of the existing test cases already repos your bug. If not, then perhaps the best test case to extend would be the api-extractor-scenarios/referenceTokens scenario (tests that canonical references are correct for different kinds of reference tokens).

But is the only way to see that the test has passed that there is no git diff?

Unfortunately, yes.

May I include the fix in runScenarios.ts in my PR, or would you prefer a clean separation?

I think it's totally reasonable to include this fix in your PR. Thanks for asking!

[fwienber]

Just for info, I created a Draft PR, in case you already want to have a look at the code changes and the extensive commit messages: #3602
Of course, there are still some open questions, but it basically seems to work.
In parallel, I am going to do the formal stuff (sign CLA, fill in PR description form).
Also, I still need to test the changes with our real-world scenario.