@caspeco/eslint-config-react 5.0.0-beta.0

package/README.md

@@ -0,0 +1,104 @@
+# @caspeco/eslint-config-react
+
+Caspeco ESLint configuration for React + TypeScript projects.
+
+## Installation
+
+```bash
+npm install --save-dev @caspeco/eslint-config-react
+```
+
+### Migrating from v4.x
+
+If you're upgrading from `@caspeco/eslint-config` v4.x, use the automated migration script:
+
+```bash
+# Preview changes
+npx caspeco-react-migrate-v5 src/ --dry-run
+
+# Apply changes
+npx caspeco-react-migrate-v5 src/
+```
+
+This updates the plugin namespace from `caspeco/` to `caspeco-react/`. See the [Migration Guide](../../MIGRATION.md) for details.
+
+## Usage
+
+Create an `eslint.config.js` file in your project root:
+
+```js
+import config from "@caspeco/eslint-config-react";
+
+export default [{ ignores: ["dist/**/*", "build/**/*"] }, ...config];
+```
+
+## What's Included
+
+This configuration includes everything from our TypeScript config plus React-specific rules:
+
+### Base TypeScript Configuration
+
+- **TypeScript ESLint** - recommended-type-checked config
+- **No Barrel Files** - Prevents barrel file usage
+- **File Naming Conventions** - Enforces kebab-case for files and folders
+- **Prettier Integration** - Compatible with Prettier formatting
+
+### React-Specific Configuration
+
+- **React Plugin** - Core React linting rules
+- **React Hooks** - Enforces rules of hooks
+- **React Refresh** - Fast Refresh support for Vite/development
+- **Caspeco Plugin** - Custom rules for Caspeco projects (Chakra UI import restrictions)
+
+## Peer Dependencies
+
+This package requires the following peer dependencies (automatically installed by npm 7+):
+
+- `eslint` >=9
+- `eslint-plugin-react` >=7.37.0
+- `eslint-plugin-react-hooks` >=7
+- `eslint-plugin-react-refresh` >=0.4.0
+- `globals` >=15
+
+**Note:** Additional TypeScript-related peer dependencies are inherited from `@caspeco/eslint-config-ts` (installed automatically as a regular dependency).
+
+## Plugins
+
+### eslint-plugin-react
+
+[eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react)
+
+Core React linting rules with the following customizations:
+
+- `react-in-jsx-scope`: off (not needed in modern React)
+- `prop-types`: off (using TypeScript instead)
+- `display-name`: off
+
+### eslint-plugin-react-hooks
+
+[eslint-plugin-react-hooks](https://www.npmjs.com/package/eslint-plugin-react-hooks)
+
+Enforces:
+
+- Rules of Hooks (error)
+- Exhaustive dependencies (warning)
+
+### eslint-plugin-react-refresh
+
+[eslint-plugin-react-refresh](https://github.com/ArnaudBarre/eslint-plugin-react-refresh)
+
+Ensures components are compatible with Fast Refresh in development.
+
+### caspeco-react-plugin
+
+Custom React-specific plugin with Caspeco rules:
+
+- Discourages direct imports from `@chakra-ui/react` (use themed components instead)
+
+## Relationship with @caspeco/eslint-config-ts
+
+This package depends on and extends `@caspeco/eslint-config-ts`, which is automatically installed as a dependency. This ensures React projects always use the same TypeScript rules without drift. If you're building a React project, use this package. For vanilla TypeScript projects, use `@caspeco/eslint-config-ts`.
+
+## License
+
+MIT

package/bin/README.md

@@ -0,0 +1,40 @@
+# Migration Scripts
+
+## caspeco-react-migrate-v5
+
+Automated migration script for updating from `@caspeco/eslint-config` v4.x to `@caspeco/eslint-config-react` v5.x.
+
+### Usage
+
+```bash
+# Preview changes (dry run)
+npx caspeco-react-migrate-v5 src/ --dry-run
+
+# Apply changes
+npx caspeco-react-migrate-v5 src/
+
+# Scan entire project
+npx caspeco-react-migrate-v5 .
+```
+
+### What it does
+
+- Updates rule names: `caspeco/discourage-chakra-import` → `caspeco-react/discourage-chakra-import`
+- Fixes ESLint disable comments
+- Updates config files
+- Processes `.js`, `.jsx`, `.ts`, `.tsx`, `.json`, and `.md` files
+
+### Files processed
+
+The script automatically:
+
+- Skips `node_modules`, `.git`, `dist`, `build`, and `coverage` directories
+- Recursively processes all supported file types
+- Shows a summary of changes made
+
+### Options
+
+- `--dry-run`: Preview changes without modifying files
+- First argument: Path to scan (defaults to current directory)
+
+See the [Migration Guide](../../../MIGRATION.md) for full migration instructions.

package/bin/caspeco-react-migrate-v5.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+
+/**
+ * Migration script for v4.x to v5.x
+ *
+ * This script updates:
+ * - Package imports: @caspeco/eslint-config → @caspeco/eslint-config-react
+ * - Named imports: { reactConfig } → default import
+ * - Variable references: reactConfig → config
+ * - Rule names: caspeco/discourage-chakra-import → caspeco-react/discourage-chakra-import
+ * - ESLint disable comments
+ *
+ * Usage:
+ *   npx caspeco-react-migrate-v5 [path] [--dry-run]
+ *
+ * Examples:
+ *   npx caspeco-react-migrate-v5 src/
+ *   npx caspeco-react-migrate-v5 . --dry-run
+ */
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const args = process.argv.slice(2);
+const isDryRun = args.includes("--dry-run");
+const targetPath = args.find((arg) => !arg.startsWith("--")) || ".";
+
+// Patterns to search and replace
+const replacements = [
+	{
+		pattern: /caspeco\/discourage-chakra-import/g,
+		replacement: "caspeco-react/discourage-chakra-import",
+		description: "Rule name",
+	},
+];
+
+// Import transformation for eslint.config.js files
+function transformImports(content, filename) {
+	if (!filename.includes("eslint.config.")) {
+		return { content, hasChanges: false };
+	}
+
+	let transformed = content;
+	let hasChanges = false;
+
+	// Replace import { reactConfig } from "@caspeco/eslint-config" → import config from "@caspeco/eslint-config-react"
+	const importPattern = /import\s*\{\s*reactConfig\s*\}\s*from\s*["']@caspeco\/eslint-config["']/;
+	if (importPattern.test(transformed)) {
+		transformed = transformed.replace(importPattern, 'import config from "@caspeco/eslint-config-react"');
+		hasChanges = true;
+
+		// If we changed the import, also update variable references
+		transformed = transformed.replace(/\breactConfig\b/g, "config");
+	}
+
+	return { content: transformed, hasChanges };
+}
+
+// File extensions to process
+const extensions = [".js", ".jsx", ".ts", ".tsx", ".json", ".md", ".mjs", ".cjs"];
+
+let filesProcessed = 0;
+let filesChanged = 0;
+let totalReplacements = 0;
+
+/**
+ * Recursively process directory
+ */
+function processDirectory(dir) {
+	const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+	for (const entry of entries) {
+		const fullPath = path.join(dir, entry.name);
+
+		// Skip node_modules, .git, dist, build directories
+		if (entry.isDirectory()) {
+			if (["node_modules", ".git", "dist", "build", "coverage"].includes(entry.name)) {
+				continue;
+			}
+			processDirectory(fullPath);
+		} else {
+			const ext = path.extname(entry.name);
+			if (extensions.includes(ext)) {
+				processFile(fullPath);
+			}
+		}
+	}
+}
+
+/**
+ * Process a single file
+ */
+function processFile(filePath) {
+	filesProcessed++;
+
+	let content;
+	try {
+		content = fs.readFileSync(filePath, "utf8");
+	} catch (err) {
+		console.error(`Error reading ${filePath}:`, err.message);
+		return;
+	}
+
+	let newContent = content;
+	let fileReplacements = 0;
+
+	// First, try import transformations for config files
+	const filename = path.basename(filePath);
+	const importResult = transformImports(newContent, filename);
+	if (importResult.hasChanges) {
+		newContent = importResult.content;
+		fileReplacements++; // Count as one logical replacement (import + references)
+	}
+
+	// Then apply all other replacement patterns
+	for (const { pattern, replacement } of replacements) {
+		const matches = newContent.match(pattern);
+		if (matches) {
+			fileReplacements += matches.length;
+			newContent = newContent.replace(pattern, replacement);
+		}
+	}
+
+	// If changes were made
+	if (fileReplacements > 0) {
+		filesChanged++;
+		totalReplacements += fileReplacements;
+
+		const relativePath = path.relative(process.cwd(), filePath);
+		console.log(
+			`${isDryRun ? "[DRY RUN] " : ""}✓ ${relativePath} (${fileReplacements} replacement${fileReplacements > 1 ? "s" : ""})`,
+		);
+
+		if (!isDryRun) {
+			try {
+				fs.writeFileSync(filePath, newContent, "utf8");
+			} catch (err) {
+				console.error(`Error writing ${filePath}:`, err.message);
+			}
+		}
+	}
+}
+
+/**
+ * Main execution
+ */
+function main() {
+	console.log("Caspeco Plugin Migration Tool");
+	console.log("==============================\n");
+
+	if (isDryRun) {
+		console.log("🔍 Running in DRY RUN mode - no files will be modified\n");
+	}
+
+	const resolvedPath = path.resolve(targetPath);
+
+	if (!fs.existsSync(resolvedPath)) {
+		console.error(`Error: Path "${targetPath}" does not exist`);
+		process.exit(1);
+	}
+
+	console.log(`Scanning: ${resolvedPath}\n`);
+
+	const stat = fs.statSync(resolvedPath);
+	if (stat.isDirectory()) {
+		processDirectory(resolvedPath);
+	} else {
+		processFile(resolvedPath);
+	}
+
+	console.log("\nSummary:");
+	console.log("========");
+	console.log(`Files scanned: ${filesProcessed}`);
+	console.log(`Files with changes: ${filesChanged}`);
+	console.log(`Total replacements: ${totalReplacements}`);
+
+	if (isDryRun && filesChanged > 0) {
+		console.log("\n💡 Run without --dry-run to apply changes");
+	} else if (filesChanged > 0) {
+		console.log("\n✅ Migration complete!");
+	} else {
+		console.log("\n✨ No files needed migration");
+	}
+}
+
+main();

package/package.json

@@ -0,0 +1,54 @@
+{
+	"name": "@caspeco/eslint-config-react",
+	"version": "5.0.0-beta.0",
+	"description": "Caspeco ESLint configuration for React projects",
+	"keywords": [
+		"eslint",
+		"eslint-config",
+		"react",
+		"typescript",
+		"caspeco"
+	],
+	"homepage": "https://github.com/Caspeco/eslint-config#readme",
+	"bugs": {
+		"url": "https://github.com/Caspeco/eslint-config/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/Caspeco/eslint-config",
+		"directory": "packages/eslint-config-react"
+	},
+	"license": "MIT",
+	"type": "module",
+	"main": "src/index.js",
+	"bin": {
+		"caspeco-react-migrate-v5": "./bin/caspeco-react-migrate-v5.js"
+	},
+	"files": [
+		"src",
+		"bin"
+	],
+	"scripts": {
+		"test": "vitest"
+	},
+	"dependencies": {
+		"@caspeco/eslint-config-ts": "*"
+	},
+	"devDependencies": {
+		"@caspeco/test-utils": "*"
+	},
+	"peerDependencies": {
+		"eslint": ">=9",
+		"eslint-plugin-react": ">=7.37.0",
+		"eslint-plugin-react-hooks": ">=7",
+		"eslint-plugin-react-refresh": ">=0.4.0",
+		"globals": ">=15"
+	},
+	"engines": {
+		"node": ">=24",
+		"npm": ">=11.5.1"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/src/index.js

@@ -0,0 +1,74 @@
+import tsConfig from "@caspeco/eslint-config-ts";
+import reactRefresh from "eslint-plugin-react-refresh";
+import reactPlugin from "eslint-plugin-react";
+import reactHooksPlugin from "eslint-plugin-react-hooks";
+import caspecoReactPlugin from "./plugins/caspeco-react.js";
+import globals from "globals";
+
+/** @type {import('@typescript-eslint/utils').TSESLint.FlatConfig.ConfigArray} */
+const flatConfig = [
+	// Extend the vanilla TypeScript config
+	...tsConfig,
+	// React plugin recommended config
+	{
+		...reactPlugin.configs.flat?.recommended,
+		files: ["**/*.ts", "**/*.tsx", "**/*.jsx"],
+		settings: {
+			react: {
+				version: "detect",
+			},
+		},
+		languageOptions: {
+			...reactPlugin.configs.flat?.recommended.languageOptions,
+			globals: {
+				...globals.serviceworker,
+				...globals.browser,
+			},
+			parserOptions: {
+				...reactPlugin.configs.flat?.recommended.languageOptions?.parserOptions,
+				ecmaVersion: "latest",
+			},
+		},
+		rules: {
+			...reactPlugin.configs.flat?.recommended.rules,
+			"react/react-in-jsx-scope": "off",
+			"react/prop-types": "off",
+			"react/display-name": "off",
+		},
+	},
+	// React hooks plugin recommended config
+	{
+		...reactHooksPlugin.configs.recommended,
+		plugins: { "react-hooks": reactHooksPlugin },
+		files: ["**/*.ts", "**/*.tsx", "**/*.jsx"],
+		rules: {
+			"react-hooks/rules-of-hooks": "error",
+			"react-hooks/exhaustive-deps": "warn",
+			// We ignore the compiler specific rules as we need React 19 for this.
+			// https://github.com/facebook/react/tree/main/packages/eslint-plugin-react-hooks#flat-config-eslintconfigjsts-1
+			// When we support this, we can add:
+			// ...reactHooksPlugin.configs.recommended.rules,
+		},
+	},
+	// React refresh plugin config
+	{
+		...reactRefresh.configs.recommended,
+		files: ["**/*.ts", "**/*.tsx", "**/*.jsx"],
+		rules: {
+			...reactRefresh.configs.recommended.rules,
+			"react-refresh/only-export-components": ["warn", { allowConstantExport: true }],
+		},
+	},
+	// Caspeco React custom rules
+	{
+		files: ["**/*.ts", "**/*.tsx", "**/*.jsx"],
+		plugins: {
+			"caspeco-react": caspecoReactPlugin,
+		},
+		rules: {
+			"caspeco-react/discourage-chakra-import": "error",
+		},
+	},
+];
+
+export default flatConfig;

package/src/plugins/caspeco-react.js

@@ -0,0 +1,45 @@
+/**
+ * @typedef {import("eslint").Rule.RuleModule} Rule
+ */
+
+/**
+ * @type {{ rules: { [key: string]: Rule } }}
+ */
+const caspeco = {
+	rules: {
+		"discourage-chakra-import": {
+			meta: {
+				type: "suggestion",
+				docs: {
+					description:
+						'Discourage importing anything from "@chakra-ui/*". Use imports from "@caspeco/casper-ui-library" instead.',
+					category: "Best Practices",
+					url: "https://caspeco.github.io/eslint-config/#/plugins/caspeco?id=caspecodiscourage-chakra-import",
+					recommended: false,
+				},
+				messages: {
+					restrictedImport: "Importing from {{importPath}} is discouraged.",
+				},
+				schema: [],
+			},
+			create(context) {
+				return {
+					ImportDeclaration(node) {
+						const importPath = node.source.value;
+						if (typeof importPath === "string" && importPath.startsWith("@chakra-ui/")) {
+							context.report({
+								node,
+								messageId: "restrictedImport",
+								data: {
+									importPath,
+								},
+							});
+						}
+					},
+				};
+			},
+		},
+	},
+};
+
+export default caspeco;