@eslint-react/kit 4.0.1-beta.0 → 4.0.2-beta.0

package/README.md

@@ -9,7 +9,9 @@ ESLint React's toolkit for building custom React lint rules right inside your `e
 - [API Reference](#api-reference)
   - [`eslintReactKit` (default export)](#eslintreactkit-default-export)
   - [`RuleDefinition`](#ruledefinition)
-  - [`KitBuilder`](#kitbuilder)
+  - [`Builder`](#builder)
+    - [`getConfig`](#getconfig)
+    - [`getPlugin`](#getplugin)
   - [`merge`](#merge)
   - [`Kit` — the toolkit object](#kit--the-toolkit-object)
     - [`kit.collect`](#kitcollect) — Semantic collectors
@@ -22,6 +24,7 @@ ESLint React's toolkit for building custom React lint rules right inside your `e
   - [Component: Destructure component props](#component-destructure-component-props)
   - [Hooks: Warn on custom hooks that don't call other hooks](#hooks-warn-on-custom-hooks-that-dont-call-other-hooks)
   - [Multiple Collectors: No component/hook factories](#multiple-collectors-no-componenthook-factories)
+  - [Advanced Config: Using `getPlugin` for custom plugin namespace](#advanced-config-using-getplugin-for-custom-plugin-namespace)
 - [More Examples](#more-examples)
 
 ## Installation
@@ -85,10 +88,10 @@ The rule name is derived automatically from the function name (`functionComponen
 ```ts
 import eslintReactKit from "@eslint-react/kit";
 
-eslintReactKit(): KitBuilder
+eslintReactKit(): Builder
 ```
 
-Creates a `KitBuilder` instance for registering custom rules via the chainable `.use()` API.
+Creates a `Builder` instance for registering custom rules via the chainable `.use()` API.
 
 ### `RuleDefinition`
 
@@ -115,12 +118,13 @@ function forbidElements({ forbidden }: ForbidElementsOptions): RuleDefinition {
 }
 ```
 
-### `KitBuilder`
+### `Builder`
 
 ```ts
-interface KitBuilder {
-  use<F extends (...args: any[]) => RuleDefinition>(factory: F, ...args: Parameters<F>): KitBuilder;
-  getConfig(): Linter.Config;
+interface Builder {
+  use<F extends (...args: any[]) => RuleDefinition>(factory: F, ...args: Parameters<F>): Builder;
+  getConfig(args?: { files?: string[] }): Linter.Config;
+  getPlugin(): ESLint.Plugin;
 }
 ```
 
@@ -130,6 +134,11 @@ A chainable builder for registering custom rules.
 | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
 | `use`       | Registers a rule factory. The rule name is `kebabCase(factory.name)`. Options type is inferred from the factory signature. |
 | `getConfig` | Returns a `Linter.Config` with all registered rules enabled at `"error"` severity.                                         |
+| `getPlugin` | Returns an `ESLint.Plugin` containing the registered rules and plugin metadata.                                            |
+
+#### `getConfig`
+
+Returns a flat `Linter.Config` object with all registered rules set to `"error"`. This is a convenience wrapper that calls `getPlugin()` internally and adds the plugin plus rule entries to the config.
 
 ```ts
 eslintReactKit()
@@ -138,6 +147,34 @@ eslintReactKit()
   .getConfig();
 ```
 
+#### `getPlugin`
+
+Returns an `ESLint.Plugin` object containing the registered rules and plugin metadata (`name` and `version`). Use this when you need finer-grained control over how the plugin is integrated into your ESLint configuration — for example, when you want to choose the plugin namespace, set per-rule severities, or compose the plugin with other configs manually.
+
+```ts
+const kit = eslintReactKit()
+  .use(noForwardRef)
+  .use(forbidElements, { forbidden: new Map() });
+
+// Retrieve the raw plugin object
+const plugin = kit.getPlugin();
+// => { meta: { name: "@eslint-react/kit", version: "..." }, rules: { "no-forward-ref": ..., "forbid-elements": ... } }
+
+// Use it in a custom flat config with your own namespace and severity
+export default [
+  {
+    files: ["**/*.{ts,tsx}"],
+    plugins: {
+      "react-custom-rules": plugin,
+    },
+    rules: {
+      "react-custom-rules/no-forward-ref": "error",
+      "react-custom-rules/forbid-elements": "warn",
+    },
+  },
+];
+```
+
 ### `merge`
 
 ```ts
@@ -317,6 +354,8 @@ Exposes the normalized `react-x` settings from the ESLint shared configuration (
 **Usage:**
 
 ```ts
+import type { RuleDefinition } from "@eslint-react/kit";
+
 function requireReact19(): RuleDefinition {
   return (context, { settings }) => ({
     Program(program) {
@@ -340,6 +379,8 @@ function requireReact19(): RuleDefinition {
 This is a simplified kit reimplementation of the built-in [`react-x/no-forwardRef`](https://beta.eslint-react.xyz/docs/rules/no-forward-ref) rule.
 
 ```ts
+import type { RuleDefinition } from "@eslint-react/kit";
+
 function noForwardRef(): RuleDefinition {
   return (context, { is }) => ({
     CallExpression(node) {
@@ -361,6 +402,9 @@ eslintReactKit()
 This is a simplified kit reimplementation of the built-in [`react-x/prefer-destructuring-assignment`](https://beta.eslint-react.xyz/docs/rules/prefer-destructuring-assignment) rule.
 
 ```ts
+import type { RuleDefinition } from "@eslint-react/kit";
+import { merge } from "@eslint-react/kit";
+
 function destructureComponentProps(): RuleDefinition {
   return (context, { collect }) => {
     const { query, visitor } = collect.components(context);
@@ -370,13 +414,13 @@ function destructureComponentProps(): RuleDefinition {
         for (const { node } of query.all(program)) {
           const [props] = node.params;
           if (props == null) continue;
-          if (props.type !== AST.Identifier) continue;
+          if (props.type !== "Identifier") continue;
           const propName = props.name;
           const propVariable = context.sourceCode.getScope(node).variables.find((v) => v.name === propName);
           const propReferences = propVariable?.references ?? [];
           for (const ref of propReferences) {
             const { parent } = ref.identifier;
-            if (parent.type !== AST.MemberExpression) continue;
+            if (parent.type !== "MemberExpression") continue;
             context.report({
               message: "Use destructuring assignment for component props.",
               node: parent,
@@ -399,6 +443,9 @@ eslintReactKit()
 This is a simplified kit reimplementation of the built-in [`react-x/no-unnecessary-use-prefix`](https://beta.eslint-react.xyz/docs/rules/no-unnecessary-use-prefix) rule.
 
 ```ts
+import type { RuleDefinition } from "@eslint-react/kit";
+import { merge } from "@eslint-react/kit";
+
 function noUnnecessaryUsePrefix(): RuleDefinition {
   return (context, { collect }) => {
     const { query, visitor } = collect.hooks(context);
@@ -430,6 +477,10 @@ Disallow defining components or hooks inside other functions (factory pattern).
 This is a simplified kit reimplementation of the built-in [`react-x/component-hook-factories`](https://beta.eslint-react.xyz/docs/rules/component-hook-factories) rule.
 
 ```ts
+import type { RuleDefinition } from "@eslint-react/kit";
+import { merge } from "@eslint-react/kit";
+import type { TSESTree } from "@typescript-eslint/utils";
+
 function findParent({ parent }: TSESTree.Node, test: (n: TSESTree.Node) => boolean): TSESTree.Node | null {
   if (parent == null) return null;
   if (test(parent)) return parent;
@@ -472,6 +523,60 @@ eslintReactKit()
   .getConfig();
 ```
 
-## More Examples
+### Advanced Config: Using `getPlugin` for custom plugin namespace
+
+Use `getPlugin()` when you want full control over the plugin namespace and rule severities instead of the all-in-one `getConfig()`.
+
+```ts
+import eslintReactKit from "@eslint-react/kit";
+import type { RuleDefinition } from "@eslint-react/kit";
+
+function noForwardRef(): RuleDefinition {
+  return (context, { is }) => ({
+    CallExpression(node) {
+      if (is.forwardRefCall(node)) {
+        context.report({ node, message: "forwardRef is deprecated in React 19." });
+      }
+    },
+  });
+}
+
+function requireReact19(): RuleDefinition {
+  return (context, { settings }) => ({
+    Program(program) {
+      if (!settings.version.startsWith("19.")) {
+        context.report({
+          node: program,
+          message: `This project requires React 19, but detected version ${settings.version}.`,
+        });
+      }
+    },
+  });
+}
+
+const kit = eslintReactKit()
+  .use(noForwardRef)
+  .use(requireReact19);
+
+// Instead of kit.getConfig(), use kit.getPlugin() for full control:
+const plugin = kit.getPlugin();
+
+export default [
+  {
+    files: ["**/*.{ts,tsx}"],
+    plugins: {
+      // Choose your own namespace
+      "react-custom": plugin,
+    },
+    rules: {
+      // Set individual severities
+      "react-custom/no-forward-ref": "error",
+      "react-custom/require-react-19": "error",
+    },
+  },
+];
+```
+
+<!--## More Examples
 
-Please check the [Rule Recipes](https://beta.eslint-react.xyz/docs/configuration/configure-custom-rules#rule-recipes) in the documentation site.
+Please check the [Rule Recipes](https://beta.eslint-react.xyz/docs/configuration/configure-custom-rules#rule-recipes) in the documentation site.-->

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import { ESLintReactSettingsNormalized, RuleFix, RuleFixer, RuleListener, define
 import { TSESTreeFunction } from "@eslint-react/ast";
 import { TSESTree } from "@typescript-eslint/utils";
 import { RuleContext } from "@typescript-eslint/utils/ts-eslint";
-import { Linter } from "eslint";
+import { ESLint, Linter } from "eslint";
 
 //#region src/index.d.ts
 interface Collector<T> {
@@ -17,20 +17,13 @@ interface CollectorWithContext<T> extends Collector<T> {
     all(program: TSESTree.Program): T[];
   };
 }
-type RuleDefinition = (ctx: RuleContext, kit: RuleToolkit) => RuleListener;
-interface KitBuilder {
-  getConfig(args?: {
-    files?: string[];
-  }): Linter.Config;
-  use<F extends (...args: any[]) => RuleDefinition>(factory: F, ...args: Parameters<F>): KitBuilder;
-}
 interface RuleToolkit {
   collect: {
-    components(ctx: RuleContext, options?: {
+    components(context: RuleContext, options?: {
       collectDisplayName?: boolean;
       hint?: bigint;
     }): CollectorWithContext<core.FunctionComponentSemanticNode>;
-    hooks(ctx: RuleContext): CollectorWithContext<core.HookSemanticNode>;
+    hooks(context: RuleContext): CollectorWithContext<core.HookSemanticNode>;
   };
   flag: {
     component: typeof core.ComponentFlag;
@@ -106,7 +99,15 @@ interface RuleToolkit {
   };
   settings: ESLintReactSettingsNormalized;
 }
-declare function eslintReactKit(): KitBuilder;
+type RuleDefinition = (context: RuleContext, toolkit: RuleToolkit) => RuleListener;
+interface Builder {
+  getConfig(args?: {
+    files?: string[];
+  }): Linter.Config;
+  getPlugin(): ESLint.Plugin;
+  use<F extends (...args: any[]) => RuleDefinition>(factory: F, ...args: Parameters<F>): Builder;
+}
+declare function eslintReactKit(): Builder;
 declare module "@typescript-eslint/utils/ts-eslint" {
   interface RuleContext<MessageIds extends string = string, Options extends readonly unknown[] = readonly unknown[]> {
     report(descriptor: {
@@ -124,4 +125,4 @@ declare module "@typescript-eslint/utils/ts-eslint" {
   }
 }
 //#endregion
-export { Collector, CollectorWithContext, KitBuilder, RuleDefinition, type RuleFix, type RuleFixer, type RuleListener, eslintReactKit as default, merge };
+export { Builder, Collector, CollectorWithContext, RuleDefinition, type RuleFix, type RuleFixer, type RuleListener, eslintReactKit as default, merge };

package/dist/index.js

@@ -4,15 +4,15 @@ import { kebabCase } from "string-ts";
 
 //#region package.json
 var name = "@eslint-react/kit";
-var version = "4.0.1-beta.0";
+var version = "4.0.2-beta.0";
 
 //#endregion
 //#region src/index.ts
-function createKit(ctx) {
+function makeRuleToolkit(context) {
 	return {
 		collect: {
-			components(ctx, options) {
-				const { api, visitor } = core.getComponentCollector(ctx, options);
+			components(context, options) {
+				const { api, visitor } = core.getComponentCollector(context, options);
 				return {
 					query: { all(program) {
 						return api.getAllComponents(program);
@@ -20,8 +20,8 @@ function createKit(ctx) {
 					visitor
 				};
 			},
-			hooks(ctx) {
-				const { api, visitor } = core.getHookCollector(ctx);
+			hooks(context) {
+				const { api, visitor } = core.getHookCollector(context);
 				return {
 					query: { all(program) {
 						return api.getAllHooks(program);
@@ -36,45 +36,45 @@ function createKit(ctx) {
 			Default: core.DEFAULT_COMPONENT_DETECTION_HINT
 		} },
 		is: {
-			captureOwnerStack: core.isCaptureOwnerStack(ctx),
-			captureOwnerStackCall: core.isCaptureOwnerStackCall(ctx),
-			childrenCount: core.isChildrenCount(ctx),
-			childrenCountCall: core.isChildrenCountCall(ctx),
-			childrenForEach: core.isChildrenForEach(ctx),
-			childrenForEachCall: core.isChildrenForEachCall(ctx),
-			childrenMap: core.isChildrenMap(ctx),
-			childrenMapCall: core.isChildrenMapCall(ctx),
-			childrenOnly: core.isChildrenOnly(ctx),
-			childrenOnlyCall: core.isChildrenOnlyCall(ctx),
-			childrenToArray: core.isChildrenToArray(ctx),
-			childrenToArrayCall: core.isChildrenToArrayCall(ctx),
-			cloneElement: core.isCloneElement(ctx),
-			cloneElementCall: core.isCloneElementCall(ctx),
-			componentDefinition: (node, hint) => core.isComponentDefinition(ctx, node, hint),
+			captureOwnerStack: core.isCaptureOwnerStack(context),
+			captureOwnerStackCall: core.isCaptureOwnerStackCall(context),
+			childrenCount: core.isChildrenCount(context),
+			childrenCountCall: core.isChildrenCountCall(context),
+			childrenForEach: core.isChildrenForEach(context),
+			childrenForEachCall: core.isChildrenForEachCall(context),
+			childrenMap: core.isChildrenMap(context),
+			childrenMapCall: core.isChildrenMapCall(context),
+			childrenOnly: core.isChildrenOnly(context),
+			childrenOnlyCall: core.isChildrenOnlyCall(context),
+			childrenToArray: core.isChildrenToArray(context),
+			childrenToArrayCall: core.isChildrenToArrayCall(context),
+			cloneElement: core.isCloneElement(context),
+			cloneElementCall: core.isCloneElementCall(context),
+			componentDefinition: (node, hint) => core.isComponentDefinition(context, node, hint),
 			componentName: core.isComponentName,
 			componentNameLoose: core.isComponentNameLoose,
-			componentWrapperCall: (node) => core.isComponentWrapperCall(ctx, node),
-			componentWrapperCallback: (node) => core.isComponentWrapperCallback(ctx, node),
-			componentWrapperCallLoose: (node) => core.isComponentWrapperCallLoose(ctx, node),
-			createContext: core.isCreateContext(ctx),
-			createContextCall: core.isCreateContextCall(ctx),
-			createElement: core.isCreateElement(ctx),
-			createElementCall: core.isCreateElementCall(ctx),
-			createRef: core.isCreateRef(ctx),
-			createRefCall: core.isCreateRefCall(ctx),
-			forwardRef: core.isForwardRef(ctx),
-			forwardRefCall: core.isForwardRefCall(ctx),
+			componentWrapperCall: (node) => core.isComponentWrapperCall(context, node),
+			componentWrapperCallback: (node) => core.isComponentWrapperCallback(context, node),
+			componentWrapperCallLoose: (node) => core.isComponentWrapperCallLoose(context, node),
+			createContext: core.isCreateContext(context),
+			createContextCall: core.isCreateContextCall(context),
+			createElement: core.isCreateElement(context),
+			createElementCall: core.isCreateElementCall(context),
+			createRef: core.isCreateRef(context),
+			createRefCall: core.isCreateRefCall(context),
+			forwardRef: core.isForwardRef(context),
+			forwardRefCall: core.isForwardRefCall(context),
 			hook: core.isHook,
 			hookCall: core.isHookCall,
 			hookName: core.isHookName,
 			initializedFromReact: core.isInitializedFromReact,
 			initializedFromReactNative: core.isInitializedFromReactNative,
-			lazy: core.isLazy(ctx),
-			lazyCall: core.isLazyCall(ctx),
-			memo: core.isMemo(ctx),
-			memoCall: core.isMemoCall(ctx),
-			reactAPI: (api) => core.isReactAPI(api)(ctx),
-			reactAPICall: (api) => core.isReactAPICall(api)(ctx),
+			lazy: core.isLazy(context),
+			lazyCall: core.isLazyCall(context),
+			memo: core.isMemo(context),
+			memoCall: core.isMemoCall(context),
+			reactAPI: (api) => core.isReactAPI(api)(context),
+			reactAPICall: (api) => core.isReactAPICall(api)(context),
 			useActionStateCall: core.isUseActionStateCall,
 			useCall: core.isUseCall,
 			useCallbackCall: core.isUseCallbackCall,
@@ -99,45 +99,40 @@ function createKit(ctx) {
 			useSyncExternalStoreCall: core.isUseSyncExternalStoreCall,
 			useTransitionCall: core.isUseTransitionCall
 		},
-		settings: getSettingsFromContext(ctx)
+		settings: getSettingsFromContext(context)
 	};
 }
 function eslintReactKit() {
 	const idGen = new IdGenerator();
-	const rules = [];
+	const rules = {};
 	const builder = {
 		getConfig({ files = ["**/*.ts", "**/*.tsx"] } = {}) {
 			return {
 				files,
-				plugins: { [name]: {
-					meta: {
-						name,
-						version
-					},
-					rules: rules.reduce((acc, { name, make }) => {
-						Reflect.set(acc, name, {
-							meta: {
-								fixable: "code",
-								hasSuggestions: true
-							},
-							create(ctx) {
-								return make(ctx, createKit(ctx));
-							}
-						});
-						return acc;
-					}, {})
-				} },
-				rules: rules.reduce((acc, { name: name$1 }) => {
+				plugins: { [name]: builder.getPlugin() },
+				rules: Object.keys(rules).reduce((acc, name$1) => {
 					acc[`${name}/${name$1}`] = "error";
 					return acc;
 				}, {})
 			};
 		},
-		use(factory, ...args) {
-			const name = kebabCase(factory.name === "" ? idGen.next() : factory.name);
-			rules.push({
-				name,
-				make: factory(...args)
+		getPlugin() {
+			return {
+				meta: {
+					name,
+					version
+				},
+				rules
+			};
+		},
+		use(make, ...args) {
+			const name = kebabCase(make.name === "" ? idGen.next() : make.name);
+			Reflect.set(rules, name, {
+				meta: {
+					fixable: "code",
+					hasSuggestions: true
+				},
+				create: (context) => make(...args)(context, makeRuleToolkit(context))
 			});
 			return builder;
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eslint-react/kit",
-  "version": "4.0.1-beta.0",
+  "version": "4.0.2-beta.0",
   "description": "ESLint React's utility module for building custom rules.",
   "keywords": [
     "react",
@@ -38,9 +38,9 @@
   "dependencies": {
     "@typescript-eslint/utils": "^8.57.2",
     "string-ts": "^2.3.1",
-    "@eslint-react/core": "4.0.1-beta.0",
-    "@eslint-react/shared": "4.0.1-beta.0",
-    "@eslint-react/ast": "4.0.1-beta.0"
+    "@eslint-react/ast": "4.0.2-beta.0",
+    "@eslint-react/core": "4.0.2-beta.0",
+    "@eslint-react/shared": "4.0.2-beta.0"
   },
   "devDependencies": {
     "eslint": "^10.1.0",