Generating typescript definitions from JSDOC marked javascript fails

[ggreco]

TypeScript Version: tried both with 4.0.x and 4.1.0-dev.20201026

Search Terms: jsdoc generate javascript definitions

Code

The goal here is to create a index.d.ts for a library from a JSDoc documented javascript library, the problem is that if the type of an object specified in a file, in this case rectangle.js, is "declared" as parameter or return type in another one:

/**
     * Adds a rectangle
     * 
     * @returns {Rectangle} the rect
     */
  addRectangle() { /* ... */ }

... then an error is emitted since typescript tries to import it again as private symbol (at least this is my interpretation), a workaround pointed in another similar bug (closed) is to replace all the declarations of objects inside the JSDOC markup with something like:

/**
     * Adds a rectangle
     * 
     * @returns {import('./rectangle').Rectangle} the rect
     */
  addRectangle() { /* ... */ }

.... this works, but totally destroy the JSDoc markup of the library.

Simple repo that reproduces the problem (we need 3 files to reproduce it so I thought to keep it external):

https://github.com/ggreco/doc2dec

• checkout the repo
• npm install
• npm run build (or npx tsc)

Expected behavior:

I expect the types to be generated correctly in "types" (index.d.ts and rectangle.d.ts).

Actual behavior:

The compilation fails with this error:
error TS9006: Declaration emit for this file requires using private name 'Rectangle' from module '"/Users/gabry/projects/ts-test/rectangle"'. An explicit type annotation may unblock declaration emit.

index.d.ts is not generated.

Related Issues:
#37832 (closed but not for this particular case)

[Bnaya]

Few notes:
exporting also Rectangle alongside Render does not solve it.

Workaround:
Using import('./rectangle').Rectangle

[weswigham]

Fun fact! In nightly typescript Rectangle in a jsdoc in the example resolves to the static side of the Rectangle class's shape! (What you'd normally think of as typeof Rectangle). This is most certainly an unintended bug, introduced alongside binding const {Thing} = require("./lib") as an alias. What's going wrong is that while the importing statement is an Alias, the exporting statement, module.export = { Rectangle } still isn't, so we return the wrong half of the symbol (using the old jsdoc fallback lookup chicanery, which goes for the static side and not a class instance type because it's a property of an object). @sandersn do we want to "complete the loop" we started by changing how the require statements were bound, as it were, and actually bind module.export = { Rectangle } type statements as Aliases? Or do we want to introduce some strange lookup hacks to allow us to look at it like an Alias event though it's not bound as one (😦)?

That's not the only issue - we're also not painting the visibility of these newly-Alias'd require style imports correctly. I have a fix for that part ready, which can stand on its own (and improves the output of an existing test).