Documentation not generated when package.json name prefix and Config name mismatch

[y-hsgw]

Hello,

I noticed an issue where documentation fails to generate if the prefix derived from the name field in package.json does not match the name in the Config.

Example: eslint-plugin-vitest
package.json: "name": "@vitest/eslint-plugin"
Config: vitest/${ruleName}
Since there is a mismatch between @vitest and vitest, the documentation for such as share configurations is not generated.
（It has been confirmed that resolving the mismatch allows the documentation to be generated correctly.）

It would be great if documentation could still be generated in such cases.
Are there any solutions or plans to address this?

Thank you!

[bmish]

Which documentation is missing? In eslint-plugin-vitest, I see that a generated rules list is present in the README, and the rule docs have generated headers.

However, when I run eslint-doc-generator in that project, the output changes. Is that project missing an .eslint-doc-generatorrc.js file?

[y-hsgw]

Which documentation is missing?

I would like to generate content like the following in the rule documentation:
💼⚠️ This rule is enabled in the ✅ recommended config. or This rule _warns_ in the 🌐 all config.

I run eslint-doc-generator in that project, the output changes.

This is because it generates a legacy config. As I will mention later, I plan to add a .eslint-doc-generatorrc.js file to address this and ignore it.

Is that project missing an .eslint-doc-generatorrc.js file?

Yes, it currently doesn't have one. I'm trying to fix that, but I'm encountering this issue in the process.
I am currently working on adding and fixing the .eslint-doc-generatorrc.js file in the following branch.
https://github.com/y-hsgw/eslint-plugin-vitest/blob/fix/eslint-doc-generator/.eslint-doc-generatorrc.js

In this branch, changing the name in package.json to "vitest/eslint-plugin" generates the expected documentation. However, since there are no plans to change the name, I am currently facing this issue.

[bmish]

I did some investigation.

eslint-plugin-vitest exports a configs object:

{
  "legacy-recommended": {
    "plugins": [ "@vitest" ],
    "rules": {
      "@vitest/expect-expect": "error",
      "@vitest/no-identical-title": "error",
      "...": "..."
    }
  },
  "legacy-all": {
    "plugins": [ "@vitest" ],
    "rules": {
      "@vitest/prefer-lowercase-title": "warn",
      "@vitest/max-nested-describe": "warn",
      "...": "..."
    }
  },
  "recommended": {
    "plugins": { "vitest": [{ "...": "..." }] },
    "rules": {
      "vitest/expect-expect": "error",
      "vitest/no-identical-title": "error",
      "...": "..."
    }
  },
  "all": {
    "plugins": { "vitest": [{ "...": "..." }] },
    "rules": {
      "vitest/prefer-lowercase-title": "warn",
      "vitest/max-nested-describe": "warn",
      "...": "..."
    }
  }
}

The plugin name used for the flat configs is different for the non-flat configs, and as such, the prefixes used for the rules in each config correspond to the plugin name in the config.

eslint-doc-generator contains a false assumption that the plugin prefix from package.json (@vitest) would always be used as the prefix in config rule names (and that all configs would use this same rule name prefix).

Could you fix the config plugin name inconsistency in eslint-plugin-vitest like this?

diff --git a/src/index.ts b/src/index.ts
index c0f11ba..eddf849 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -67,10 +67,10 @@ const createConfig = <R extends Linter.RulesRecord>(rules: R) => (
   Object.keys(rules).reduce((acc, ruleName) => {
     return {
       ...acc,
-      [`vitest/${ruleName}`]: rules[ruleName]
+      [`@vitest/${ruleName}`]: rules[ruleName]
     }
   }, {})) as {
-  [K in keyof R as `vitest/${Extract<K, string>}`]: R[K]
+  [K in keyof R as `@vitest/${Extract<K, string>}`]: R[K]
 }
 
 const createConfigLegacy = (rules: Record<string, string>) => ({
@@ -269,13 +269,13 @@ plugin.configs = {
   'legacy-all': createConfigLegacy(allRules),
   'recommended': {
     plugins: {
-      ['vitest']: plugin
+      ['@vitest']: plugin
     },
     rules: createConfig(recommended)
   },
   'all': {
     plugins: {
-      ['vitest']: plugin
+      ['@vitest']: plugin
     },
     rules: createConfig(allRules)
   },

This seems to help somewhat with the eslint-doc-generator problem since now the plugin name matches the plugin prefix @vitest from package.json.

However, there's a separate issue still which is that eslint-doc-generator thinks the actual rule names are all prefixed with the plugin prefix @vitest from package.json and refers to them like this throughout the documentation (e.g. the rule doc titles), whereas they are actually prefixed with vitest/ which is how they are referred to in a user's eslint.config.js or comments like // eslint-disable-line vitest/prefer-to-be-falsy.

So to summarize, there's a number of issues with eslint-doc-generator erroneously assuming the plugin prefix from package.json is always the appropriate rule prefix. But eslint-plugin-vitest appears to be using @vitest vs. vitest unnecessarily inconsistently and perhaps not following best naming practices with these, which is why this is the first report I've heard of this issue.

[y-hsgw]

Thank you for investigating and providing the background.😄 I understand the situation better now.
How about adding an option or some functionality to allow document generation even for naming patterns that may not follow the recommended practices, as seen in this issue?

[bmish]

We shouldn't need a new option to fix this bug in eslint-doc-generator. It should be possible to fix eslint-doc-generator so that it automatically works for any eslint plugin regardless of naming patterns. We'll have to determine the correct prefixes by reading from the right locations in the exported data from the eslint plugin, instead of simply using the prefix from the plugin's package.json everywhere. This may be somewhat tricky and require a lot of additional plumbing.

[y-hsgw]

I see, that makes perfect sense.
If I understand correctly, this would mean supporting multiple prefixes. Specifically, would it also require generating rule documentation titles that include multiple prefixes?
For example: Rule documentation title generation if legacy configs are not ignored.（expect-expect）
# Enforce having expectation in test body (@vitest/expect-expect, vitest/expect-expect)

[bmish]

In your plugin, shouldn't it always be:

# Enforce having expectation in test body (vitest/expect-expect)

I don't think the user can refer to the rule with @vitest/. You can test it out. Isn't it always vitest/ as far as the user is concerned?

[y-hsgw]

I'm curious about what kind of rule documentation titles would be generated if legacy-recommended orlegacy-allwere not included in ignoreConfigs. While the possibility might be low, I believe it's a case worth considering.
（In this case, I’m using eslint-plugin-vitest as an example, but essentially, I’m concerned about whether there’s a need to support multiple prefixes.🧐）

I don't think the user can refer to the rule with @vitest/

Does this refer to enabling the rule?

import vitest from '@vitest/eslint-plugin';

// ex: eslint.config.js
export default [
  ...
  {
    plugins: {
      ['@vitest']: vitest,
    },
    rules: {
      '@vitest/consistent-test-it': ['error', { fn: 'it' }],
    },
  }
]

With this setup, I believe the rule can be enabled.

[veritem]

Author of eslint-plugin-vitest here,

In this case, I’m using eslint-plugin-vitest as an example, but essentially, I’m concerned about whether there’s a need to support multiple prefixes.

I don't think eslint-doc-generator should generate docs for multiple prefixes in my opinion. We have adopted using multiple prefixes in eslint-plugin-vitest as a backward compatibility option for people still using the old eslint configuration format.