chore: add type comment to exported plugin

[JoshuaKGoldberg]

This will give a bit nicer of an IDE experience for folks working in editors such as VS Code that have built-in TypeScript support.

[voxpelli]

Shouldn't help as TS doesn't read JSDoc comments from node_modules?

Would need to compile it to a .d.ts?

[JoshuaKGoldberg]

parserOptions.projectService picks it up, it happens in the repro linked in the issue.

[voxpelli]

Even when maxNodeModuleJsDepth hasn’t been set to something other than the default 0?

Such behavior has already caused issues in ESLint as TS has an undocumented behavior of setting it when using jsconfig.json: eslint/eslint#18100 (comment)

JSDoc comments should not be relied upon

[JoshuaKGoldberg]

Even when maxNodeModuleJsDepth hasn’t been set to something other than the default 0?

Yes, per the reproduction case I linked in the issue.

Agreed that .d.ts files would be better. That's more work that I don't have time for right now.

Personally, I'd rather lean towards "perfect is the enemy of good" and ship this now + hope for that eventually. There's no harm in including these type-rich JSDocs for pure .js codebases. They benefit the codebase's development itself, help pave the path for more formal TS adoption, and can also help in cases like the reproduction I linked in the issue.

[voxpelli]

Even when maxNodeModuleJsDepth hasn’t been set to something other than the default 0?

Yes, per the reproduction case I linked in the issue

So typescript eslint is not respecting the tsconfig in this regard?

I’m pro fixing #310 but against making any changes to JSDoc comments because others have decided to consume them as published types. eslint/eslint#18100 (comment) is one of many proofs that it’s a bad idea to consume JSDoc comments from third party modules

Unless this module publishes type definitions this module should be interpreted as untyped is my opinion

[voxpelli]

I don't object to the change itself, but I object to it being a solution to the problem at hand

[JoshuaKGoldberg]

@voxpelli it's also useful for internal development and doesn't impact users using sanctioned type methods. If we ignore the reasoning around external types, do you have any remaining blockers?

[voxpelli]

@JoshuaKGoldberg no other blockers, if we change it so that this doesn't promote usage of it externally in any way then I'm okay with it

[JoshuaKGoldberg]

The comment as-is is exactly what one would do for a purely internal change. There's nothing to be done to promote or not-promote it externally.

[voxpelli]

Removing the Fixes 😜

[JoshuaKGoldberg]

Thanks all!