feat(eslint-config): optional rules for module authors (#377)

Author: antfu

docs/content/1.packages/1.config.md

@@ -68,33 +68,48 @@ You might also want to add a script entry to your `package.json`:
 
 ### Customizing the Config
 
-Note that `createConfigForNuxt()` returns `Promise<FlatConfig[]>`. ESLint allows you to run the promise directly on the default export. If you want to combine with other configs, you will need await and spread the result. For example:
+Note that `createConfigForNuxt()` returns a chainable [`FlatConfigComposer` instance](https://github.com/antfu/eslint-flat-config-utils#composer) from [`eslint-flat-config-utils`](https://github.com/antfu/eslint-flat-config-utils) which allows you to manipulate the ESLint flat config with ease. If you want to combine with other configs, you can use the `.append()` method:
 
 ```js [eslint.config.mjs]
 import { createConfigForNuxt } from '@nuxt/eslint-config/flat'
 
-export default [
-  ...await createConfigForNuxt({
-    // options here
-  }),
-  // other configs
-]
-// (which uses Top-level await)
+export default createConfigForNuxt({
+  // options here
+})
+  .prepend(
+    // ...Prepend some flat configs in front
+  )
+  // Override some rules in a specific config, based on their name
+  .override('nuxt/typescript', {
+    rules: {
+      // ...Override rules, for example:
+      '@typescript-eslint/ban-types': 'off'
+    }
+  })
+  // ...you can chain more operations as needed
 ```
 
-To make it easier, you can also use our helper `defineFlatConfigs`, which will also resolve and flatten the configs for you:
+`FlatConfigComposer` is also a Promise object, that you can use `await` to get the final config object.
+
+### Module Authors
+
+This config also provides rules for module/library authors. You can enable them by setting the `features.tooling` option to `true`:
+
+:::callout{icon="i-ph-crane-tower-duotone" color="amber"}
+This feature is experimental and may change in the future.
+:::
 
 ```js [eslint.config.mjs]
-import { defineFlatConfigs, createConfigForNuxt } from '@nuxt/eslint-config/flat'
-
-export default defineFlatConfigs(
-  createConfigForNuxt({
-    // options here
-  }),
-  // other configs
-)
+import { createConfigForNuxt } from '@nuxt/eslint-config/flat'
+
+export default createConfigForNuxt({
+  features: {
+    tooling: true
+  }
+})
 ```
 
+This will enable rules with `unicorn` and `jsdoc` plugins, to ensure your module is following best practices.
 
 ## Legacy Config Format
 

eslint.config.js

@@ -4,6 +4,7 @@ import { createConfigForNuxt } from '@nuxt/eslint-config/flat'
 export default createConfigForNuxt({
   features: {
     stylistic: true,
+    tooling: true,
   },
   dirs: {
     src: [

packages/eslint-config/package.json

@@ -45,6 +45,8 @@
     "@typescript-eslint/parser": "^7.5.0",
     "eslint-config-flat-gitignore": "^0.1.5",
     "eslint-flat-config-utils": "^0.2.0",
+    "eslint-plugin-jsdoc": "^48.2.2",
+    "eslint-plugin-unicorn": "^51.0.1",
     "eslint-plugin-import-x": "^0.5.0",
     "eslint-plugin-vue": "^9.24.0",
     "globals": "^15.0.0",

packages/eslint-config/src/flat/configs-tooling/jsdoc.ts

@@ -0,0 +1,41 @@
+import type { FlatConfigItem } from 'eslint-flat-config-utils'
+import jsdocPlugin from 'eslint-plugin-jsdoc'
+import { resolveOptions } from '../utils'
+import type { NuxtESLintConfigOptions } from '../types'
+
+export default function jsdoc(options: NuxtESLintConfigOptions = {}): FlatConfigItem[] {
+  const resolved = resolveOptions(options)
+
+  return [
+    {
+      name: 'nuxt/tooling/jsdoc',
+      plugins: {
+        jsdoc: jsdocPlugin,
+      },
+      rules: {
+        'jsdoc/check-access': 'warn',
+        'jsdoc/check-param-names': 'warn',
+        'jsdoc/check-property-names': 'warn',
+        'jsdoc/check-types': 'warn',
+        'jsdoc/empty-tags': 'warn',
+        'jsdoc/implements-on-classes': 'warn',
+        'jsdoc/no-defaults': 'warn',
+        'jsdoc/no-multi-asterisks': 'warn',
+        'jsdoc/require-param-name': 'warn',
+        'jsdoc/require-property': 'warn',
+        'jsdoc/require-property-description': 'warn',
+        'jsdoc/require-property-name': 'warn',
+        'jsdoc/require-returns-check': 'warn',
+        'jsdoc/require-returns-description': 'warn',
+        'jsdoc/require-yields-check': 'warn',
+
+        ...resolved.features.stylistic
+          ? {
+              'jsdoc/check-alignment': 'warn',
+              'jsdoc/multiline-blocks': 'warn',
+            }
+          : {},
+      },
+    },
+  ]
+}

packages/eslint-config/src/flat/configs-tooling/unicorn.ts

@@ -0,0 +1,42 @@
+// @ts-expect-error missing types
+import pluginUnicorn from 'eslint-plugin-unicorn'
+import type { FlatConfigItem } from 'eslint-flat-config-utils'
+
+export default function unicorn(): FlatConfigItem[] {
+  return [
+    {
+      name: 'nuxt/tooling/unicorn',
+      plugins: {
+        unicorn: pluginUnicorn,
+      },
+      rules: {
+        // Pass error message when throwing errors
+        'unicorn/error-message': 'error',
+        // Uppercase regex escapes
+        'unicorn/escape-case': 'error',
+        // Array.isArray instead of instanceof
+        'unicorn/no-instanceof-array': 'error',
+        // Ban `new Array` as `Array` constructor's params are ambiguous
+        'unicorn/no-new-array': 'error',
+        // Prevent deprecated `new Buffer()`
+        'unicorn/no-new-buffer': 'error',
+        // Lowercase number formatting for octal, hex, binary (0x1'error' instead of 0X1'error')
+        'unicorn/number-literal-case': 'error',
+        // textContent instead of innerText
+        'unicorn/prefer-dom-node-text-content': 'error',
+        // includes over indexOf when checking for existence
+        'unicorn/prefer-includes': 'error',
+        // Prefer using the node: protocol
+        'unicorn/prefer-node-protocol': 'error',
+        // Prefer using number properties like `Number.isNaN` rather than `isNaN`
+        'unicorn/prefer-number-properties': 'error',
+        // String methods startsWith/endsWith instead of more complicated stuff
+        'unicorn/prefer-string-starts-ends-with': 'error',
+        // Enforce throwing type error when throwing error while checking typeof
+        'unicorn/prefer-type-error': 'error',
+        // Use new when throwing error
+        'unicorn/throw-new-error': 'error',
+      },
+    },
+  ]
+}

packages/eslint-config/src/flat/index.ts

@@ -52,12 +52,21 @@ export function createConfigForNuxt(options: NuxtESLintConfigOptions = {}): Flat
     nuxt(resolved),
   )
 
+  if (resolved.features.tooling) {
+    c.append(
+      import('./configs-tooling/jsdoc').then(m => m.default(resolved)),
+      import('./configs-tooling/unicorn').then(m => m.default()),
+    )
+  }
+
   if (resolved.features.stylistic) {
-    c.append(import('./configs/stylistic').then(m => m.default(
-      typeof resolved.features.stylistic === 'boolean'
-        ? {}
-        : resolved.features.stylistic,
-    )))
+    const stylisticOptions = typeof resolved.features.stylistic === 'boolean'
+      ? {}
+      : resolved.features.stylistic
+
+    c.append(
+      import('./configs/stylistic').then(m => m.default(stylisticOptions)),
+    )
   }
 
   c.append(

packages/eslint-config/src/flat/types.ts

@@ -10,6 +10,14 @@ export interface NuxtESLintFeaturesOptions {
    */
   standalone?: boolean
 
+  /**
+   * Enable rules for Nuxt module authors or library authors
+   *
+   * @experimental Changes might not follow semver
+   * @default false
+   */
+  tooling?: boolean
+
   /**
    * Enable stylistic ESLint rules for formatting and code style check
    *

packages/eslint-config/src/flat/utils.ts

@@ -31,6 +31,7 @@ export function resolveOptions(
       standalone: true,
       stylistic: false,
       typescript: true,
+      tooling: false,
       ...config.features,
     },
     dirs,

packages/module/src/modules/checker.ts

@@ -1,4 +1,4 @@
-import { existsSync } from 'fs'
+import { existsSync } from 'node:fs'
 import { addVitePlugin, addWebpackPlugin, useLogger } from '@nuxt/kit'
 import { relative, resolve } from 'pathe'
 import { watch } from 'chokidar'