[api-extractor] Emit /// <reference lib="" /> in rolled up .d.ts

[southpolesteve]

I'm attempting to adopt API extractor in https://github.com/Azure/azure-cosmos-js and ran into a blocker. /// <reference lib="" /> directives are missing from the rolled up .d.ts file. We had switched to these recently instead of specifying lib in tsconfig.json to make things more pleasant for TS consumers.

Relevant Azure Cosmos issue Azure/azure-cosmos-js#161
Relevant TS issue microsoft/TypeScript#26497

[octogonz]

@southpolesteve I'd be happy to help you get this working. Would you be able to provide a Git branch with an isolated example that repros the issue? That would help me to investigate it more easily. If this is a time-sensitive need, feel free to contact me at work.

[southpolesteve]

@pgonzal Here is my WIP branch https://github.com/Azure/azure-cosmos-js/tree/api-extractor

npm run compile && npm run extract-api

[octogonz]

Thanks @southpolesteve for providing the repro branch.

We're currently using the 3.0.x version of the TypeScript compiler. It seems that the compiler itself does not emit the /// <reference lib="____" /> into the .d.ts files unless I upgrade to 3.1. So the first step is to upgrade API Extractor to use the newer compiler. That's pretty easy.

The second challenge is that TypeChecker.getSymbolAtLocation() seems to skip over the /// <reference... line and take us directly to the declaration in the typescript/lib folder. In other words, it's not obvious how we would determine which reference lines we need to include in the rollup file. We could cheat and simply include every reference from every source file that we touch. That might cause problems if it's overly inclusive, however. I'm out of office today, but tomorrow I will chat with the compiler owners and see if there's an API that would allow us to determine this precisely.

It occurred to me that maybe API Extractor should provide a config setting that allows you to manually inject text into your rollup file. This could provide a fairly general workaround when people encounter edge cases like this.

[octogonz]

@iclanton Could we set up a 3.1 flavor of rush-stack-compiler?

[octogonz]

We could cheat and simply include every reference from every source file that we touch. That might cause problems if it's overly inclusive, however.

I noticed that we're already doing something similar with typeReferenceDirectives (for /// <reference type="___" />) in DtsRollupGenerator._collectTypeDefinitionReferences(), and it doesn't seem to have caused any problems so far.

The compiler API provides a similar libReferenceDirectives array, so if there isn't a more elegant solution, we can just collect them in the same way:

    interface SourceFile extends Declaration {
        typeReferenceDirectives: ReadonlyArray<FileReference>;
        libReferenceDirectives: ReadonlyArray<FileReference>;
        . . .
    }

[octogonz]

@southpolesteve This fix was published as API Extractor 6.1.6

[southpolesteve]

This is looking good. Thanks!