[api-extractor] support bundle files configed with tsconfig.ts'option: paths

[xkn1ght]

configed by tsconfig "alias", but treat with external dependency

Summary

already asked in the chat room, comfirmed that it's not supported now.

my tsconfig.json as below

    "baseUrl": "./",
    "paths": {
      "@interface/*": ["src/interface/*"],
    }

Expected result:
expert:

export interface Foo {}

Actual result:

import { Foo } from '@interface/test'
export { Foo }

Details

seems api-extractor ignore those @interface declaration files, treating them as external deps.

I am searching inside the source code, but still don't know which module parse the AST and mark isExternal as true.

PS: Seems pnpm link and rush link doesn't support link monorepo/api-extractor to my demo (outside rushstack monorepo). So I run the dev mode by relative path: node ../../../rushatck/apps/api-extractor/lib/start.js. Is any better way to dev?

Standard questions

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

Question	Answer
@microsoft/api-extractor version?	^7.19.5
Operating system?	mac
API Extractor scenario?	rollups (.d.ts)
Would you consider contributing a PR?	Yes
TypeScript compiler version?	4.4.3
Node.js version (node -v)?	14.17.4

[zelliott]

I am searching inside the source code, but still don't know which module parse the AST and mark isExternal as true.

I believe _isExternalModulePath is the method that's responsible for determining which imports are from external packages.

Last I spoke about this issue with @octogonz, I believe our conclusion was that API Extractor should support path mappings defined in the tsconfig. So we should fix this issue. I also believe there was some reason why path mappings are problematic from an API consumer point of view (or maybe it was from a rushstack point of view), but I can't remember now.

Maybe this fix is as easy as updating _isExternalModulePath to first apply/resolve any tsconfig path mappings before continuing with its current logic? @xkn1ght would you be interested in contributing a fix for this?

[xkn1ght]

Maybe this fix is as easy as updating _isExternalModulePath to first apply/resolve any tsconfig path mappings before continuing with its current logic

thanks, after my searching, it work by 2 steps.

1. update _isExternalModulePath as quote.
2. modify TypeScriptInternals.getResolvedModule function. When having a paths-mapping moduleSpecifier, load it from the lib folder rather than call (ts as any).getResolvedModule, which load it from the src folder.

I will open a pr and close the issue Later.

[zelliott]

Hey @xkn1ght any progress on this? If not, then I'll try to pick it up.

[zelliott]

I opened #3321 for this. @xkn1ght can you patch this in and see if it fixes your issue?

[octogonz]

Fixed in @microsoft/api-extractor 7.21.0

[octogonz]

We encountered a regression which is fixed in PR #3339, however with that change some additional work is required to fully support tsconfig path mappings. Reopening this issue to track that work.

[zelliott]

Before #3321 and #3339, API Extractor would not run correctly on projects that have path mappings applied to its generated .d.ts files. Instead, API Extractor would consider any path-mapped import statements (e.g. import {Foo} from 'some/path/mapping';) as external modules and not generate documentation for them (even if some/path/mapping actually resolves to an package-internal import).

After the PRs above, API Extractor should have better/full support with projects that have path mappings applied to its .d.ts files. To validate this, I want to add a build-tests/ test case... but I'm having a hard time coming up with a realistic example of a project that has path mappings applied to its .d.ts output.

@xkn1ght, can you share more about your specific use case? It'd be helpful to have a link to your project that is affected by this issue.

[hax]

Another similar case is #xxx defined in imports field of "package.json" file, it seems api-extractor currently treat them as external deps.