Support JSDoc name paths in JavaScript

[DanielRosenwasser]

Background

Part of TypeScript's goal is to provide a rich tooling experience. This includes the scenarios where users are

1. Writing TypeScript which integrates with existing JSDoc'd JavaScript.
2. Using checkJs on a full JS project to leverage the breadth of .d.ts files on DefinitelyTyped.
3. Providing a great experience on VS/VS Code/etc. for people who are using JSDoc in loose ways that will hopefully work (or who are willing to put in the effort to get things to work).

We'd like to provide users richer tools that can possibly work for existing code as well.

Basic Proposal

This issue pertains to our JavaScript support via the language service, allowJs, and checkJs.

It tracks understanding some combined set of functionality between JSDoc's namepaths as well as the way in which import paths function in TypeScript today.

For example, the following @typedef tags import the Request and Response interfaces from the module specifiers "express" and "../node_modules/express.Response".

/**
 * @typedef {module:express.Request} Request
 * @typedef {module:../node_modules/express.Response} Response
 */

Since in TypeScript the import specifier "express" could originate from...

• a folder under node_modules when using "moduleResolution": "node"
• an ambient module declaration like declare module "express"
• something which has been path mapped in compilerOptions.paths

we would do the same resolution here for express in module:express.Request.

Open questions:

1. What about paths with spaces?
2. How does this work with CommonJS/ESM interop?

What this issue doesn't cover?

While name paths are typically introduced via the the /** @module */ tag (which is not currently supported), this proposal doesn't rely on it. In our brief research, it was unclear whether enough users had a consistent understanding of the tag.

However, one could speculate that the module tag would function similarly to an ambient module declaration. This should be covered in a different proposal.

[aozgaa]

For reference, this is a possible solution to #14377.

[DanielRosenwasser]

We're going to hold off on any new JSDoc syntax, and wait for more feedback here. As per #22445, our current recommendation is to wait on #14844 and then use

/**
 * @type {import("express").foo}
 */
let x;

[mhegazy]

closing in favor of #14844