Make JSDoc skipping public, plus more configurable

[jakebailey]

For #52959.

This is a follow-up to #52921.

This changes the way we do the new JSDoc skipping, instead replacing it with a publicly-available option which lets you control how much info you want. Specifically, you can specify:

• JSDocParsingMode.ParseAll, the default, which is to keep parsing JSDoc and including it in the tree. This is the default used by tsserver, services, etc, where we definitely need all of that info.
• JSDocParsingMode.ParseForTypeErrors, which only parses JSDoc tags which have a semantic meaning to the checker which impact error calculation, that is, any JSDoc in a non-TS/TSX file, or any JSDoc containing @see or @link. This is the new default when calling from tsc, and would be a good default for anyone orchestrating TS builds, e.g. heft, nx.
• JSDocParsingMode.ParseForTypeInfo, if you only query type info, but never care about its errors. This parses JSDoc in JS files, but doesn't in TS files at all (as they are never used for type info there). This is good for something like ts-eslint with type info (which does not surface errors).
• JSDocParsingMode.ParseNone, which always skips JSDoc, no matter what. This is good for those who only want the parser, e.g. formatters like prettier, ts-eslint without type information, transpileModule, maybe others. Set this at your own risk.

To use this when calling createSourceFile, set jsDocParsingMode on the create options:

const sourceFile = ts.createSourceFile(
    filename,
    content,
    { languageVersion: ts.ScriptTarget.ESNext, jsDocParsingMode: ts.JSDocParsingMode.ParseNone },
);

To use this when constructing a host, set jsDocParsingMode:

const host = ts.createCompilerHost(options);
host.jsDocParsingMode = ts.JSDocParsingMode.ParseForTypeInfo;
// or
const host = ts.createIncrementalCompilerHost(options);
host.jsDocParsingMode = ts.JSDocParsingMode.ParseForTypeErrors;
// or
const host = ts.createWatchCompilerHost(...);
host.jsDocParsingMode = ts.JSDocParsingMode.ParseForTypeErrors;

FYI @fisker @bradzacher @JoshuaKGoldberg @JamesHenry @dmichon-msft

[typescript-bot]

Looks like you're introducing a change to the public API surface area. If this includes breaking changes, please document them on our wiki's API Breaking Changes page.

Also, please make sure @DanielRosenwasser and @RyanCavanaugh are aware of the changes, just as a heads up.

[jakebailey]

Bleh, there's that dprint ternary annoyance again that Sheetal noted (https://github.com/microsoft/TypeScript/actions/runs/6178742090/job/16772520512?pr=55739), maybe that's dprint/dprint-plugin-typescript#450 ?

[bradzacher]

Copying from the other PR

I think my main concern is that people will want to read out the .jsDoc properties by asking typescript-eslint for the original AST nodes (e.g. #55139), and then find that the info was never populated, or similar. I also wanted to try and make .jsDoc lazy and only create it when accessed (since we have the text anyway), but since JSDoc is bound by the binder, you can't really do that.

I think that this is going to be the rare case, if it even exists across the ecosystem.
If this is a configurable thing then we can easily set it up to be configurable on our side too - eg a user can pass parserOptions.tsJSdoc or something in their eslint config if a plugin needs it (and plugins can add it to their recommended config).

The vast majority of the ecosystem would just get faster-by-default lint runs which would be a big win for everyone!

[jakebailey]

On that front, I probably need to figure out a way to plumb this through ProjectService too.

[jakebailey]

Marking as ready for review, though I need to double check that I have plumbed this up through createProgram and so on.

[jakebailey]

It turns out that I missed a lot of places that should plumb this. This will be tricky. ☹️

[sheetalkamat]

I dont think we should be threading in this to defaults. User of this API can always call thius method and override getSourceFile on their own .. there is nothing special here.

[jakebailey]

I think that not providing this parameter will make it very inconvenient; this function and createCompilerHostWorker are what call createGetSourceFile, which is internal and non-trivial, and then wrap it again in another closure. Setting the JSDoc parsing mode is a lot like setting a default setParentNodes which this function already does.

[jakebailey]

See: https://github.com/typescript-eslint/typescript-eslint/blob/7826910d8c6ba4d2d40b8d55fcf7fd39fe290d88/packages/typescript-estree/src/create-program/useProvidedPrograms.ts#L84

[jakebailey]

Generally speaking I think this means that anywhere we can expect to find setParentNodes, we probably need to be expecting jsDocParsingMode.

[sheetalkamat]

Hmm.. Generally i like to go with conservative approach and avoid having to add additional surface area that we have to keep maintaining. This is ok i guess though , user can just create source file from file text easily to override but ok.

[weswigham]

If the option is fed in via the CreateSourceFileOptions, rather than a top-level field, callers will already have the opportunity to request it on a per-file basis when making the file, rather than needing to set it on the host as a whole.

[jakebailey]

FYI @nonara; in executeCommandLine.ts, there's a new global defaultJSDocParsingMode; in tsc here that's set to ParseForTypeErrors, but it's likely that someone's plugin will actually need this to be reset to ParseAll in order to get all of the JSDoc nodes they expect. e.g. I suspect typia reads JSDoc, somehow. Probably others. Just something to watch out for!

[jakebailey]

Last minute bikeshedding; ParseForErrors? Technically, this covers grammar checks.

[jakebailey]

But, not actually sure we do grammar checks which relate to JSDoc. I assume not.

[sandersn]

Not in TS files, no. Just in JS files.

[nonara]

Thanks for the heads up!

[jakebailey]

Alright, seems like everything is alright; I'm going to merge so we can get this in for 5.3. Thank you everyone for the feedback, hopefully it works out (and tell me if it doesn't).

[samchon]

Thanks for detailed documentation.