@jabworks/eslint-plugin 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @jabworks/eslint-plugin
+
+## 1.0.0
+
+### Major Changes
+
+- Initial release

package/README.md

@@ -0,0 +1,74 @@
+# @jabworks/eslint-plugin
+
+A custom ESLint plugin and shareable config for JavaScript, TypeScript, React, and Next.js projects. This package provides a set of curated rules and configurations to help enforce code quality, consistency, and best practices across your codebase.
+
+## Features
+
+- **Comprehensive rule sets** for JavaScript, TypeScript, React, and Next.js
+- **Opinionated import sorting** with `simple-import-sort`
+- **Best practices** and stylistic rules
+- **Prettier integration** for code formatting
+- **Support for modern ECMAScript features**
+- **Flat config support** (ESLint v9+)
+
+## Installation
+
+```bash
+pnpm add -D @jabworks/eslint-plugin
+# or
+yarn add -D @jabworks/eslint-plugin
+# or
+npm install --save-dev @jabworks/eslint-plugin
+```
+
+## Usage
+
+Add the plugin to your ESLint configuration. Example using the flat config format (recommended for ESLint v9+):
+
+```js
+// eslint.config.js or eslint.config.mjs
+import { plugin as jablabPlugin } from '@jabworks/eslint-plugin';
+
+export default [
+	...jablabPlugin.configs.base,
+	// or for React/Next.js/TypeScript/Vitest:
+	// ...jablabPlugin.configs.react,
+	// ...jablabPlugin.configs.next,
+	// ...jablabPlugin.configs.typescript,
+	// ...jablabPlugin.configs.vitest,
+];
+```
+
+Or, if using legacy config:
+
+```json
+{
+	"extends": ["plugin:@jabworks/base"]
+}
+```
+
+## Available Configs
+
+- `base` – General JavaScript/TypeScript rules
+- `comments` – Rules for ESLint directive comments
+- `react` – React-specific rules
+- `next` – Next.js-specific rules
+- `typescript` – TypeScript-specific rules
+- `vitest` – Vitest-specific rules
+
+## Example: Import Sorting
+
+This plugin enforces a consistent import order using `simple-import-sort`. Example:
+
+```js
+import React from 'react';
+import express from 'express';
+import lodash from 'lodash';
+import myUtil from '@/utils/myUtil';
+import helper from './helper';
+import styles from './styles.css';
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,60 @@
+{
+  "description": "Opinionated ESLint plugin and flat config for JS, TS, React, and Next.js",
+  "devDependencies": {
+    "@eslint-community/eslint-plugin-eslint-comments": "^4.5.0",
+    "@eslint/js": "^9.27.0",
+    "@next/eslint-plugin-next": "^15.3.2",
+    "@stylistic/eslint-plugin": "^4.4.0",
+    "@types/node": "^22.15.23",
+    "@vitest/eslint-plugin": "^1.2.1",
+    "eslint": "^9.27.0",
+    "eslint-config-prettier": "^10.1.5",
+    "eslint-import-resolver-alias": "^1.1.2",
+    "eslint-import-resolver-typescript": "^4.4.1",
+    "eslint-plugin-eslint-comments": "^3.2.0",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-jest": "^28.11.1",
+    "eslint-plugin-jsx-a11y": "^6.10.2",
+    "eslint-plugin-playwright": "^2.2.0",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-compiler": "19.1.0-rc.2",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "eslint-plugin-testing-library": "^7.2.2",
+    "eslint-plugin-turbo": "^2.5.3",
+    "eslint-plugin-unicorn": "^59.0.1",
+    "globals": "^16.2.0",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.33.0",
+    "@jabworks/typescript-config": "0.0.0"
+  },
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "types": "./src/types/index.d.ts"
+    }
+  },
+  "keywords": [
+    "eslint",
+    "eslint-config",
+    "eslint-plugin",
+    "eslintplugin",
+    "typescript",
+    "typescript-eslint"
+  ],
+  "main": "./src/index.js",
+  "name": "@jabworks/eslint-plugin",
+  "peerDependencies": {
+    "eslint": ">=9.27.0",
+    "typescript": ">=5.8.0",
+    "typescript-eslint": ">=8.33.0"
+  },
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "type": "module",
+  "types": "./src/types/index.d.ts",
+  "version": "1.0.0"
+}

package/src/configs/base.js

@@ -0,0 +1,60 @@
+import eslintjs from '@eslint/js';
+import stylisticPlugin from '@stylistic/eslint-plugin';
+import eslintConfigPrettier from 'eslint-config-prettier';
+import importPlugin from 'eslint-plugin-import';
+import simpleImportSort from 'eslint-plugin-simple-import-sort';
+import unicorn from 'eslint-plugin-unicorn';
+import tseslint from 'typescript-eslint';
+import bestPractice from '../rules/best-practice.js';
+import es6 from '../rules/es6.js';
+import importConfig from '../rules/import.js';
+import possibleErrors from '../rules/possible-errors.js';
+import stylistic from '../rules/stylistic.js';
+import variables from '../rules/variables.js';
+import comments from './comments.js';
+
+/** @type {import('eslint').Linter.Config} */
+export const baseConfig = {
+	name: '@jabworks/eslint-config-base',
+	plugins: {
+		unicorn,
+		'simple-import-sort': simpleImportSort,
+	},
+	rules: {
+		...bestPractice,
+		...es6,
+		...importConfig,
+		...possibleErrors,
+		...stylistic,
+		...variables,
+	},
+	ignores: [
+		'dist/**',
+		'build/**',
+		'out/**',
+		'coverage/**',
+		'node_modules/**',
+		'eslint.config.js',
+		'eslint.config.mjs',
+		'eslint.config.cjs',
+		'*.config.js',
+		'*.config.mjs',
+		'*.config.cjs',
+	],
+};
+
+/** @type {import('eslint').Linter.Config[]} */
+const configs = [
+	eslintjs.configs.recommended,
+	eslintConfigPrettier,
+	...tseslint.configs.recommended,
+	importPlugin.flatConfigs.recommended,
+	...comments,
+	stylisticPlugin.configs.customize({
+		semi: true,
+		arrowParens: 'as-needed',
+	}),
+	baseConfig,
+];
+
+export default configs;

package/src/configs/comments.js

@@ -0,0 +1,13 @@
+import comments from '@eslint-community/eslint-plugin-eslint-comments/configs';
+import commentsRules from '../rules/comments.js';
+
+/** @type {import('eslint').Linter.Config} */
+export const commentsConfig = {
+	name: '@jabworks/eslint-config-comments',
+	rules: commentsRules,
+};
+
+/** @type {import('eslint').Linter.Config[]} */
+const configs = [comments.recommended, commentsConfig];
+
+export default configs;

package/src/configs/next.js

@@ -0,0 +1,86 @@
+import js from '@eslint/js';
+import pluginNext from '@next/eslint-plugin-next';
+import eslintConfigPrettier from 'eslint-config-prettier';
+import importPlugin from 'eslint-plugin-import';
+import pluginReact from 'eslint-plugin-react';
+import pluginReactHooks from 'eslint-plugin-react-hooks';
+import globals from 'globals';
+
+import reactRules from '../rules/react.js';
+import baseConfig from './base.js';
+import tseslintConfigs, { tseslintConfig } from './typescript.js';
+
+/** @type {import('eslint').Linter.Config[]} */
+const configs = [
+	...baseConfig,
+	js.configs.recommended,
+	eslintConfigPrettier,
+	importPlugin.flatConfigs.recommended,
+	pluginReact.configs.flat.recommended,
+	...tseslintConfigs,
+	{
+		name: '@jabworks/eslint-config-nextjs',
+		plugins: {
+			'@next/next': pluginNext,
+			'react-hooks': pluginReactHooks,
+		},
+		languageOptions: {
+			...pluginReact.configs.flat.recommended?.languageOptions,
+			globals: {
+				...globals.serviceworker,
+			},
+			parserOptions: {
+				projectService: true,
+				tsconfigRootDir: import.meta.dirname,
+			},
+		},
+		settings: {
+			'import/resolver': { node: {} },
+			react: { version: 'detect' },
+		},
+		linterOptions: {
+			reportUnusedDisableDirectives: true,
+		},
+		rules: {
+			...pluginReactHooks.configs['recommended-latest'].rules,
+			...reactRules,
+			...pluginNext.configs.recommended.rules,
+			...pluginNext.configs['core-web-vitals'].rules,
+			...tseslintConfig.rules,
+		},
+	},
+	{
+		files: [
+			'*.config.cjs',
+			'*.config.js',
+			'*.config.mjs',
+			'*.config.ts',
+			'**/*.d.ts',
+			'**/*.stories.ts',
+			'**/*.stories.tsx',
+			'app/**/*error.tsx',
+			'app/**/layout.tsx',
+			'app/**/not-found.tsx',
+			'app/**/opengraph-image.tsx',
+			'app/**/page.tsx',
+			'app/apple-icon.tsx',
+			'app/robots.ts',
+			'app/sitemap.ts',
+			'next.config.mjs',
+			'src/app/**/*error.tsx',
+			'src/app/**/layout.tsx',
+			'src/app/**/not-found.tsx',
+			'src/app/**/opengraph-image.tsx',
+			'src/app/**/page.tsx',
+			'src/app/apple-icon.tsx',
+			'src/app/robots.ts',
+			'src/app/sitemap.ts',
+		],
+		rules: {
+			'import/no-default-export': 'off',
+			'import/prefer-default-export': ['error', { target: 'any' }],
+		},
+	},
+];
+
+export default configs;

package/src/configs/react.js

@@ -0,0 +1,52 @@
+import js from '@eslint/js';
+import eslintConfigPrettier from 'eslint-config-prettier';
+import importPlugin from 'eslint-plugin-import';
+import pluginReact from 'eslint-plugin-react';
+import pluginReactHooks from 'eslint-plugin-react-hooks';
+import globals from 'globals';
+
+import reactRules from '../rules/react.js';
+import baseConfig from './base.js';
+import tseslintConfig from './typescript.js';
+
+/** @type {import("eslint").Linter.Config} */
+export const reactConfig = {
+	name: '@jabworks/eslint-config-react',
+	languageOptions: {
+		...pluginReact.configs.flat.recommended?.languageOptions,
+		globals: {
+			...globals.serviceworker,
+			...globals.browser,
+		},
+		parserOptions: {
+			projectService: true,
+			tsconfigRootDir: import.meta.dirname,
+		},
+	},
+	plugins: {
+		'react-hooks': pluginReactHooks,
+	},
+	settings: { react: { version: 'detect' } },
+	rules: {
+		...pluginReactHooks.configs['recommended-latest'].rules,
+		...reactRules,
+		'import/no-cycle': 'error',
+	},
+};
+
+/**
+ * A custom ESLint configuration for libraries that use React.
+ *
+ * @type {import("eslint").Linter.Config[]}
+ */
+const configs = [
+	js.configs.recommended,
+	eslintConfigPrettier,
+	importPlugin.flatConfigs.recommended,
+	...baseConfig,
+	...tseslintConfig,
+	pluginReact.configs.flat.recommended,
+	reactConfig,
+];
+
+export default configs;

package/src/configs/typescript.js

@@ -0,0 +1,30 @@
+import eslintConfigPrettier from 'eslint-config-prettier';
+import importPlugin from 'eslint-plugin-import';
+import tseslint from 'typescript-eslint';
+
+import { TYPESCRIPT_FILES } from '../lib/constants.js';
+import typescriptExtensionRules from '../rules/typescript.extension.js';
+import typescriptImportRules from '../rules/typescript.import.js';
+import typescriptRules from '../rules/typescript.js';
+
+/** @type {import('eslint').Linter.Config} */
+export const tseslintConfig = {
+	name: '@jabworks/eslint-config-typescript',
+	files: TYPESCRIPT_FILES,
+	rules: {
+		...typescriptRules,
+		...typescriptExtensionRules,
+		...typescriptImportRules,
+	},
+};
+
+/** @type {import('eslint').Linter.Config[]} */
+const configs = [
+	...tseslint.configs.strictTypeChecked,
+	...tseslint.configs.stylisticTypeChecked,
+	importPlugin.flatConfigs.typescript,
+	eslintConfigPrettier,
+	tseslintConfig,
+];
+
+export default configs;

package/src/configs/vitest.js

@@ -0,0 +1,28 @@
+import vitest from '@vitest/eslint-plugin';
+import globals from 'globals';
+
+import vitestRules from '../rules/vitest.js';
+
+/** @type {import('eslint').Linter.Config[]} */
+const configs = [
+	{
+		name: '@jabworks/eslint-config-vitest',
+		files: ['**/*.test.{js,ts,mjs,cjs,jsx,tsx}', '**/__tests__/**', '**/tests/**'],
+		plugins: {
+			vitest,
+		},
+		languageOptions: {
+			globals: {
+				...globals.node,
+				...globals.vitest,
+				vi: 'readonly',
+			},
+		},
+		rules: {
+			...vitest.configs.recommended.rules,
+			...vitestRules,
+		},
+	},
+];
+
+export default configs;

package/src/index.js

@@ -0,0 +1,25 @@
+import pkg from '../package.json' with { type: 'json' };
+import base from './configs/base.js';
+import comments from './configs/comments.js';
+import next from './configs/next.js';
+import react from './configs/react.js';
+import typescript from './configs/typescript.js';
+import vitest from './configs/vitest.js';
+
+const { name, version } = pkg;
+
+/** @type {import('eslint').ESLint.Plugin} */
+export const plugin = {
+	meta: {
+		name,
+		version,
+	},
+	configs: {
+		base,
+		comments,
+		next,
+		react,
+		typescript,
+		vitest,
+	},
+};

package/src/lib/constants.js

@@ -0,0 +1,3 @@
+export const ECMA_VERSION = 2021;
+export const JAVASCRIPT_FILES = ['*.js?(x)', '*.mjs'];
+export const TYPESCRIPT_FILES = ['*.ts?(x)'];

package/src/rules/best-practice.js

@@ -0,0 +1,228 @@
+/** @type {import('eslint').Linter.RulesRecord} */
+const rules = {
+	/**
+	 * Require return statements in array methods callbacks.
+	 *
+	 * 🚫 Not fixable -https://eslint.org/docs/rules/array-callback-return
+	 */
+	'array-callback-return': ['error', { allowImplicit: true }],
+	/**
+	 * Treat `var` statements as if they were block scoped.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/block-scoped-var
+	 */
+	'block-scoped-var': 'error',
+	/**
+	 * Require curly braces for multiline blocks.
+	 *
+	 * 🔧 Fixable - https://eslint.org/docs/rules/curly
+	 */
+	curly: ['warn', 'multi-line'],
+	/**
+	 * Require default clauses in switch statements to be last (if used).
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/default-case-last
+	 */
+	'default-case-last': 'error',
+	/**
+	 * Require triple equals (`===` and `!==`).
+	 *
+	 * 🔧 Fixable - https://eslint.org/docs/rules/eqeqeq
+	 */
+	eqeqeq: 'error',
+	/**
+	 * Require grouped accessor pairs in object literals and classes.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/grouped-accessor-pairs
+	 */
+	'grouped-accessor-pairs': 'error',
+	/**
+	 * Disallow use of `alert()`.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/no-alert
+	 */
+	'no-alert': 'error',
+	/**
+	 * Disallow use of `caller`/`callee`.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/no-caller
+	 */
+	'no-caller': 'error',
+	/**
+	 * Disallow returning value in constructor.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/no-constructor-return
+	 */
+	'no-constructor-return': 'error',
+	/**
+	 * Disallow using an `else` if the `if` block contains a return.
+	 *
+	 * 🔧 Fixable - https://eslint.org/docs/rules/no-else-return
+	 */
+	'no-else-return': 'warn',
+	/**
+	 * Disallow `eval()`.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/no-eval
+	 */
+	'no-eval': 'error',
+	/**
+	 * Disallow extending native objects.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/no-extend-native
+	 */
+	'no-extend-native': 'error',
+	/**
+	 * Disallow unnecessary function binding.
+	 *
+	 * 🔧 Fixable - https://eslint.org/docs/rules/no-extra-bind
+	 */
+	'no-extra-bind': 'error',
+	/**
+	 * Disallow unnecessary labels.
+	 *
+	 * 🔧 Fixable - https://eslint.org/docs/rules/no-extra-label
+	 */
+	'no-extra-label': 'error',
+	/**
+	 * Disallow floating decimals.
+	 *
+	 * 🔧 Fixable - https://eslint.org/docs/rules/no-floating-decimal
+	 */
+	'no-floating-decimal': 'error',
+	/**
+	 * Make people convert types explicitly e.g. `Boolean(foo)` instead of `!!foo`.
+	 *
+	 * 🔧 Partially Fixable - https://eslint.org/docs/rules/no-implicit-coercion
+	 */
+	'no-implicit-coercion': 'error',
+	/**
+	 * Disallow use of `eval()`-like methods.
+	 *
+	 * https://eslint.org/docs/rules/no-implied-eval
+	 */
+	'no-implied-eval': 'error',
+	/**
+	 * Disallow usage of `__iterator__` property.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/no-iterator
+	 */
+	'no-iterator': 'error',
+	/**
+	 * Disallow use of labels for anything other than loops and switches.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/no-labels
+	 */
+	'no-labels': ['error'],
+	/**
+	 * Disallow unnecessary nested blocks.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/no-lone-blocks
+	 */
+	'no-lone-blocks': 'error',
+	/**
+	 * Disallow `new` for side effects.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/no-new
+	 */
+	'no-new': 'error',
+	/**
+	 * Disallow function constructors.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/no-new-func
+	 */
+	'no-new-func': 'error',
+	/**
+	 * Disallow primitive wrapper instances, such as `new String('foo')`.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/no-new-wrappers
+	 */
+	'no-new-wrappers': 'error',
+	/**
+	 * Disallow use of octal escape sequences in string literals.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/no-octal-escape
+	 */
+	'no-octal-escape': 'error',
+	/**
+	 * Disallow reassignment of function parameters.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/no-param-reassign
+	 */
+	'no-param-reassign': 'error',
+	/**
+	 * Disallow usage of the deprecated `__proto__` property.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/no-proto
+	 */
+	'no-proto': 'error',
+	/**
+	 * Disallow assignment in `return` statement.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/no-return-assign
+	 */
+	'no-return-assign': 'error',
+	/**
+	 * Disallow use of `javascript:` urls.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/no-script-url
+	 */
+	'no-script-url': 'error',
+	/**
+	 * Disallow comparisons where both sides are exactly the same.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/no-self-compare
+	 */
+	'no-self-compare': 'error',
+	/**
+	 * Disallow use of comma operator.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/no-sequences
+	 */
+	'no-sequences': 'error',
+	/**
+	 * Disallow unnecessary `.call()` and `.apply()`.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/no-useless-call
+	 */
+	'no-useless-call': 'error',
+	/**
+	 * Disallow unnecessary concatenation of strings.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/no-useless-concat
+	 */
+	'no-useless-concat': 'error',
+	/**
+	 * Disallow redundant return statements.
+	 *
+	 * 🔧 Fixable - https://eslint.org/docs/rules/no-useless-return
+	 */
+	'no-useless-return': 'warn',
+	/**
+	 * Require using named capture groups in regular expressions.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/prefer-named-capture-group
+	 */
+	// 'prefer-named-capture-group': 'error',
+	/**
+	 * Require using Error objects as Promise rejection reasons.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/prefer-promise-reject-errors
+	 */
+	'prefer-promise-reject-errors': ['error', { allowEmptyReject: true }],
+	/**
+	 * Disallow use of the RegExp constructor in favor of regular expression
+	 * literals.
+	 *
+	 * 🚫 Not fixable - https://eslint.org/docs/rules/prefer-regex-literals
+	 */
+	'prefer-regex-literals': 'error',
+	/**
+	 * Disallow "Yoda conditions", ensuring the comparison.
+	 *
+	 * 🔧 Fixable - https://eslint.org/docs/rules/yoda
+	 */
+	yoda: 'warn',
+};
+
+export default rules;

package/src/rules/comments.js

@@ -0,0 +1,12 @@
+/** @type {import('eslint').Linter.RulesRecord} */
+const rules = {
+	'@eslint-community/eslint-comments/disable-enable-pair': 'off',
+	/**
+	 * Require comments on ESlint disable directives.
+	 *
+	 * 🚫 Not fixable - https://eslint-community.github.io/eslint-plugin-eslint-comments/rules/require-description.html
+	 */
+	'@eslint-community/eslint-comments/require-description': 'error',
+};
+
+export default rules;