refactor: rewrite createRule and RuleTester

src/index.ts

@@ -1,5 +1,3 @@
-import type { TSESLint } from '@typescript-eslint/utils'
-
 // rules
 import electron from './config/electron'
 import errors from './config/errors'
@@ -56,6 +54,7 @@ import preferDefaultExport from './rules/prefer-default-export'
 import unambiguous from './rules/unambiguous'
 // configs
 import type { PluginConfig } from './types'
+import type { RuleModuleWithCustomMeta } from './utils'
 
 const configs = {
   recommended,
@@ -127,7 +126,7 @@ const rules = {
 
   // deprecated aliases to rules
   'imports-first': importsFirst,
-} satisfies Record<string, TSESLint.RuleModule<string, readonly unknown[]>>
+} satisfies Record<string, RuleModuleWithCustomMeta<string, readonly unknown[]>>
 
 export = {
   configs,

src/rules/imports-first.ts

@@ -1,15 +1,10 @@
-import { ESLintUtils } from '@typescript-eslint/utils'
-
-import { docsUrl } from '../utils/docs-url'
+import { createRule } from '../utils'
 
 import first from './first'
 
-const createRule = ESLintUtils.RuleCreator(ruleName =>
-  docsUrl(ruleName, '7b25c1cb95ee18acc1531002fd343e1e6031f9ed'),
-)
-
 export = createRule({
   ...first,
+  commitHash: '7b25c1cb95ee18acc1531002fd343e1e6031f9ed',
   name: 'imports-first',
   meta: {
     ...first.meta,

src/utils/create-rule.ts

@@ -1,5 +1,70 @@
+import type { TSESLint } from '@typescript-eslint/utils'
 import { ESLintUtils } from '@typescript-eslint/utils'
 
 import { docsUrl } from './docs-url'
 
-export const createRule = ESLintUtils.RuleCreator(docsUrl)
+// TSESLint.RuleMetaDataDocs, but with "category" property for eslint-doc-generator
+type MetaDataDocsWithCategory<Options extends readonly unknown[]> = {
+  /**
+   * The category the rule falls under
+   */
+  category?: string
+
+  recommended?:
+    | TSESLint.RuleRecommendation
+    | TSESLint.RuleRecommendationAcrossConfigs<Options>
+    | boolean
+} & Omit<TSESLint.RuleMetaDataDocs<Options>, 'recommended'>
+
+// TSESLint.RuleMetaData, but with "docs" property overriden for eslint-doc-generator
+type MetadataWithCustomDocs<
+  MessageIDs extends string,
+  Options extends readonly unknown[],
+> = {
+  docs: MetaDataDocsWithCategory<Options>
+} & Omit<TSESLint.RuleMetaData<MessageIDs, Options>, 'docs'>
+
+// TSESLint.RuleModule, but with "meta" property overriden for eslint-doc-generator
+export type RuleModuleWithCustomMeta<
+  MessageIds extends string,
+  Options extends readonly unknown[] = [],
+  ExtendedRuleListener extends TSESLint.RuleListener = TSESLint.RuleListener,
+> = {
+  meta: MetadataWithCustomDocs<MessageIds, Options>
+} & Omit<TSESLint.RuleModule<MessageIds, Options, ExtendedRuleListener>, 'meta'>
+
+type RuleCreateOption<
+  Options extends readonly unknown[],
+  MessageIds extends string,
+> = {
+  meta: MetadataWithCustomDocs<MessageIds, Options>
+  commitHash?: string
+} & Omit<ESLintUtils.RuleWithMetaAndName<Options, MessageIds>, 'meta'>
+
+export function createRule<
+  Options extends readonly unknown[],
+  MessageIds extends string,
+>({
+  name,
+  meta,
+  commitHash,
+  ...rules
+}: Readonly<RuleCreateOption<Options, MessageIds>>): RuleModuleWithCustomMeta<
+  MessageIds,
+  Options
+> {
+  const { docs, ...metaWithoutDocs } = meta
+  return {
+    ...ESLintUtils.RuleCreator.withoutDocs({
+      meta: metaWithoutDocs,
+      ...rules,
+    }),
+    meta: {
+      ...meta,
+      docs: {
+        ...docs,
+        url: docsUrl(name, commitHash),
+      },
+    },
+  }
+}

test/rules/consistent-type-specifier-style.spec.ts

@@ -1,6 +1,6 @@
-import { TSESLint, TSESTree } from '@typescript-eslint/utils'
+import { TSESTree } from '@typescript-eslint/utils'
 
-import { parsers, test } from '../utils'
+import { parsers, test, RuleTester } from '../utils'
 
 import rule from 'eslint-plugin-import-x/rules/consistent-type-specifier-style'
 
@@ -445,28 +445,28 @@ const FLOW_ONLY = {
 } as const
 
 describe('TypeScript', () => {
-  const ruleTester = new TSESLint.RuleTester({
+  const ruleTester = new RuleTester({
     parser: parsers.TS,
     parserOptions: {
       ecmaVersion: 6,
       sourceType: 'module',
     },
   })
-  ruleTester.run('consistent-type-specifier-style', rule, {
+  ruleTester.run$('consistent-type-specifier-style', rule, {
     valid: [...COMMON_TESTS.valid, ...TS_ONLY.valid],
     invalid: [...COMMON_TESTS.invalid, ...TS_ONLY.invalid],
   })
 })
 
 describe('Babel/Flow', () => {
-  const ruleTester = new TSESLint.RuleTester({
+  const ruleTester = new RuleTester({
     parser: parsers.BABEL,
     parserOptions: {
       ecmaVersion: 6,
       sourceType: 'module',
     },
   })
-  ruleTester.run('consistent-type-specifier-style', rule, {
+  ruleTester.run$('consistent-type-specifier-style', rule, {
     valid: [...COMMON_TESTS.valid, ...FLOW_ONLY.valid],
     invalid: [...COMMON_TESTS.invalid, ...FLOW_ONLY.invalid],
   })

test/rules/default.spec.ts

@@ -1,15 +1,13 @@
 import path from 'node:path'
 
-import { TSESLint } from '@typescript-eslint/utils'
-
-import { test, SYNTAX_CASES, parsers } from '../utils'
+import { test, SYNTAX_CASES, parsers, RuleTester } from '../utils'
 
 import rule from 'eslint-plugin-import-x/rules/default'
 import { CASE_SENSITIVE_FS } from 'eslint-plugin-import-x/utils'
 
-const ruleTester = new TSESLint.RuleTester()
+const ruleTester = new RuleTester()
 
-ruleTester.run('default', rule, {
+ruleTester.run$('default', rule, {
   valid: [
     test({ code: 'import "./malformed.js"' }),
 
@@ -161,7 +159,7 @@ ruleTester.run('default', rule, {
 
 // #311: import of mismatched case
 if (!CASE_SENSITIVE_FS) {
-  ruleTester.run('default (path case-insensitivity)', rule, {
+  ruleTester.run$('default (path case-insensitivity)', rule, {
     valid: [
       test({
         code: 'import foo from "./jsx/MyUncoolComponent.jsx"',
@@ -180,7 +178,7 @@ if (!CASE_SENSITIVE_FS) {
 
 describe('TypeScript', () => {
   const parser = parsers.TS
-  ruleTester.run(`default`, rule, {
+  ruleTester.run$(`default`, rule, {
     valid: [
       test({
         code: `import foobar from "./typescript-default"`,

test/rules/dynamic-import-chunkname.spec.ts

@@ -1,10 +1,10 @@
-import { TSESLint, TSESTree } from '@typescript-eslint/utils'
+import { TSESTree } from '@typescript-eslint/utils'
 
-import { SYNTAX_CASES, parsers } from '../utils'
+import { SYNTAX_CASES, parsers, RuleTester } from '../utils'
 
 import rule from 'eslint-plugin-import-x/rules/dynamic-import-chunkname'
 
-const ruleTester = new TSESLint.RuleTester()
+const ruleTester = new RuleTester()
 
 const pickyCommentFormat = '[a-zA-Z-_/.]+'
 
@@ -43,7 +43,7 @@ const pickyChunkNameFormatError = {
   },
 } as const
 
-ruleTester.run('dynamic-import-chunkname', rule, {
+ruleTester.run$('dynamic-import-chunkname', rule, {
   valid: [
     {
       code: `dynamicImport(
@@ -971,7 +971,7 @@ describe('TypeScript', () => {
   const typescriptParser = parsers.TS
   const nodeType = TSESTree.AST_NODE_TYPES.ImportExpression
 
-  ruleTester.run('dynamic-import-chunkname', rule, {
+  ruleTester.run$('dynamic-import-chunkname', rule, {
     valid: [
       {
         code: `import('test')`,

test/rules/export.spec.ts

@@ -1,12 +1,10 @@
-import { TSESLint } from '@typescript-eslint/utils'
-
-import { test, testFilePath, SYNTAX_CASES, parsers } from '../utils'
+import { test, testFilePath, SYNTAX_CASES, parsers, RuleTester } from '../utils'
 
 import rule from 'eslint-plugin-import-x/rules/export'
 
-const ruleTester = new TSESLint.RuleTester()
+const ruleTester = new RuleTester()
 
-ruleTester.run('export', rule, {
+ruleTester.run$('export', rule, {
   valid: [
     test({ code: 'import "./malformed.js"' }),
 
@@ -166,7 +164,7 @@ describe('TypeScript', () => {
     },
   }
 
-  ruleTester.run('export', rule, {
+  ruleTester.run$('export', rule, {
     valid: [
       // type/value name clash
       test({

test/rules/exports-last.spec.ts

@@ -1,19 +1,18 @@
-import { TSESLint } from '@typescript-eslint/utils'
 import type { TSESTree } from '@typescript-eslint/utils'
 
-import { test } from '../utils'
+import { test, RuleTester } from '../utils'
 
 import rule from 'eslint-plugin-import-x/rules/exports-last'
 
-const ruleTester = new TSESLint.RuleTester()
+const ruleTester = new RuleTester()
 
 const error = (type: `${TSESTree.AST_NODE_TYPES}`) =>
   ({
     messageId: 'end',
     type,
   }) as const
 
-ruleTester.run('exports-last', rule, {
+ruleTester.run$('exports-last', rule, {
   valid: [
     // Empty file
     test({

test/rules/extensions.spec.ts

@@ -1,12 +1,10 @@
-import { TSESLint } from '@typescript-eslint/utils'
-
-import { test, testFilePath, parsers } from '../utils'
+import { test, testFilePath, parsers, RuleTester } from '../utils'
 
 import rule from 'eslint-plugin-import-x/rules/extensions'
 
-const ruleTester = new TSESLint.RuleTester()
+const ruleTester = new RuleTester()
 
-ruleTester.run('extensions', rule, {
+ruleTester.run$('extensions', rule, {
   valid: [
     test({ code: 'import a from "@/a"' }),
     test({ code: 'import a from "a"' }),
@@ -662,7 +660,7 @@ ruleTester.run('extensions', rule, {
 describe('TypeScript', () => {
   const parser = parsers.TS
 
-  ruleTester.run(`${parser}: extensions ignore type-only`, rule, {
+  ruleTester.run$(`${parser}: extensions ignore type-only`, rule, {
     valid: [
       test({
         code: 'import type T from "./typescript-declare";',