Default export is untyped for ESM

[reduckted]

Expected behavior

In an ESM project:

import jsdoc from 'eslint-plugin-jsdoc`;
// jsdoc is typed as ESLint.Plugin

Actual behavior

In an ESM project:

import jsdoc from 'eslint-plugin-jsdoc`;
// jsdoc is typed as any

I know the preferred way is to use the new exported jsdoc function, but I was using this plugin as this as part of a larger configuration and only need the plugin object. I can still get the plugin object, which is great 👍. It's just that now it doesn't have a type, so it results in a @typescript-eslint/no-unsafe-assignment warning when I try to assign it.

ESLint Config

N/A

ESLint sample

See code above.

Environment

• Node version: 22.19.0
• ESLint version 9.35.0
• eslint-plugin-jsdoc version: 55.0.3

[yunarch]

I can confirm this issue. According to the docs, we should be able to use Flat config (declarative), which is simply importing the plugin. As @reduckted mentioned, this still works, but we no longer get type information.

In versions < 55.0.0 (Also test it in latest one 55.0.3), the available configurations were visible through intellisense. For example:

import { default as pluginJsdoc } from 'eslint-plugin-jsdoc';

pluginJsdoc.configs['flat/recommended-error'].rules // ✅ Works with intellisense
pluginJsdoc.configs['no-existing-config'].rules    // ❌ Correctly reports an error

We could also see the full list of configs directly in the package without needing to check the docs, since type definitions provided intellisense support. This no longer works in >= 55.0.0, whether using Flat config (declarative) or Flat config (procedural):

import {jsdoc} from 'eslint-plugin-jsdoc';

export default [
  jsdoc({
    config: 'flat/recommended', // I’d expect to see available configs here, but there is no intellisense. It might be not possible 🤔  but that's what I would expect.
  })
];

Nothing is broken functionally, but without proper type support in newer versions, it’s much harder to catch mistakes, and some errors may go unnoticed.

[brettz9]

It seems I may have improved things somewhat with v55.0.4. Still don't have the new function working with types fully, but at least the old objects do appear better.

Update: With v55.0.5 I got it working with autocomplete of jsdoc({config: '...'}. But some nested objects may still be problematic.

[yunarch]

@brettz9 tested version55.0.5 and works as i would expect for both Flat config (declarative) and Flat config (procedural), i might need to check more because as you said for some nested objects might not fully work (but i don't have that use case).

For me, I would say version 55.0.5 solved this issue 😄 🚀

[brettz9]

And v55.1.0 adds TS for rules supplied to the function...

Btw, the function is a pretty light wrapper, so there's little reason really to use the objects anymore...

[brettz9]

v55.1.1 fixes an issue with supplying autocomplete for rules as well as should help behavior with any further nested types. It's looking better at least for ESM with arethetypeswrong. I will close now, as this should resolve, but feel free to comment further as needed. Feel free to subscribe to #1223 in case there are updates re: CommonJS types.

[yunarch]

55.1.1 works great 🚀

Adding some comments about why sometimes I would use Flat config (declarative) over jsdoc function, probably better suited for another issue/discussion but unsure where to place it and I don't want to start a whole discussion if there is no need for it. Feel free to guide me if you think is worth it 😄. For this issue, everything is working perfectly now.

@brettz9 My main (and maybe only) use case for preferring Flat config (declarative) over Flat config (procedural) is when I want tighter control over the configuration (mostly in the context of building a large shared config). Specifically, I want to:

• Define a configuration name
• Specify which files it applies to
• Specify ignores
• Override rules without needing to create a new config (already covered by jsdoc function)
• Add some additional settings to the ESLint flat config
• Maybe other options from a eslint flat config item

So if the jsdoc function could also allow adding/overriding properties from an ESLint flat config item (I'm referring to this type: import('eslint').Linter.Config), then I think there would be no strong reason to keep Flat config (declarative) around.

However, my understanding is that:

• Preferred way for almost all the cases: Flat config (procedural)
• You want full control then you need Flat config (declarative) but that might need some setup from your side.

And personally, I like having that distinction, mainly because, as I mentioned, the jsdoc function doesn’t currently cover all the properties an ESLint config item can have. But if it eventually does, then I don’t see any reason not to always use the jsdoc function and maybe remove Flat config (declarative) specially if affects maintaining the package 🤔.

[brettz9]

Yes, your vision was spot on.

v55.2.0 now supports copying over all documented import('eslint').Linter.Config properties (and makes a fix with rules not being merged).

[reduckted]

I just wanted to chime in and say thanks for fixing this. 56.0.1 (i didn't try the earlier versions) is working nicely for me. ❤️