Rule to mark types in JSDoc as used

[Josh-Cena]

Motivation

Consider the following code:

import type { ComponentType } from "react";

/** @see {@link ComponentType} */
export type Foo = number;

TypeScript compiler understands that ComponentType is used in JSDoc and hence will not flag it as unused; TS-ESLint, on the other hand, reports @typescript-eslint/no-unused-vars, because it's unaware of JSDoc.

ESLint offers the markVariableAsUsed API that we can leverage to mark this type as used. eslint-plugin-react takes advantage of this to mark React as used when there's JSX. I don't know if it's portable to types, but hopefully it is.

Current behavior

Reports error.

Desired behavior

Should not give @typescript-eslint/no-unused-vars

Alternatives considered

This could also be an extension in TS-ESLint, but AFAIK they never handle JSDoc, so I decided to see if you would consider it first.

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

[brettz9]

I personally prefer to use import() within the types, feeling the importing into code as kind of an anti-pattern, and as per #99 we don't want to continue the buggy support we have for this in no-undefined-types (the bugginess relates to the fact that our approach was to handle comment blocks one-by-one, but for proper unused variable support, it needs to process them all together).

However, as a separate rule, not on by default, I'd be open to a PR, but am not really inclined to work on this, as again, I kind of view it as an anti-pattern, albeit an approach supported by TypeScript and I think meriting accommodation to projects which want to use it.

[Josh-Cena]

I see. I do prefer to split the marking types as used feature into a separate rule, because then it would be purely syntactical (detecting @see or @param or similar tags), so we can probably handle the comment blocks one-by-one. I get your point about anti patterns; frankly, I like to use import type in TS files because the JSDoc import() alternative looks quite... ugly. Furthermore, I'm actually unable to get this working:

/** @typedef {import('react').ComponentType} ComponentType */

/** @see {@link ComponentType} */
export type Foo = number;

ComponentType is resolved as any, even when import('react').ComponentType seems to be correctly resolved.

[brettz9]

Does this work for you?

/** @typedef {typeof import(https://github.com/facebook/react/).ComponentType} ComponentType */

One admitted problem with the typedef approach though is that there is no means to mark it as local (as suggested per
microsoft/TypeScript#46011 (comment) ). It automatically gets exported as a type if generating a declaration file. Hopefully that will be fixed though, as it's one of two items I think particularly make TypeScript less than practical when trying to use plain JavaScript files (as some projects like ESLint want to do to keep the codebase accessible to more developers, and who do not want to curate a separate type declaration file as it is more likely to go out of sync when the types are not inline to the page) and thus holding me back from switching to TypeScript as our default mode (even for users without a TypeScript parser). @sandersn

[maribethb]

If I'm understanding this issue correctly, we would also like this feature as users of the Closure Compiler. We import types that are only used in JsDoc with

const {SomeType} = goog.requireType('Ns.SomeType');

but we have to add /* eslint-disable-next-line no-unused-vars */ above every one of these requireTypes. Since requireType is the Closure method for importing types specifically then I don't think this would be considered an antipattern.

I looked into doing this myself but we are moving towards es modules rather than closure modules so it wasn't worth implementing. But it would probably be useful to anyone using Closure Compiler.

[JohnLouderback]

I also would appreciate seeing this implemented. My use-case is also for @link. It works great with VS Code, but without marking the variables as used, other ES Lint plugin grumble.

[brettz9]

As discovered in #507 (referenced also in #99), there was an eslint issue which pointed to an issue in marking variables used on program exit (i.e., as when examining comment nodes which are not attached to other AST). As per that issue, we might need to implement our own custom scope analysis in place of markVariableAsUsed.

[kraenhansen]

@brettz9 do you think something changed upstream that might make it more feasible to implement now?
If you think this is possible and something you would take a PR for (even as a rule disabled by default) I'd love to take a stab at it 👍

[brettz9]

@kraenhansen : While there were some architectural changes on markVariableAsUsed recently (moving it to the SourceCode object away from context), I think the same issue must still exist with that function. You might just search online about scope analysis and ESLint. I haven't worked very much at all with that, but it should I think be possible to do what you need with such analysis.

But if you were to do so, I think you'd have to disable/reimplement the TypeScript no-unused-vars rule since there'd be no common API to rely on. Ideally, this would be fixed at the ESLint level as markVariableAsUsed is intended for this purpose of sharing such data between rules, but maybe implementing it separately would be more stable given the fact that ESLint has been ambivalent about markVariableAsUsed (being as that rules typically don't influence other rules' behavior, and there can be a deterministic problem as I recall with the order in which they're applied).