js-style-kit 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js-style-kit",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "A zero configuration style guide for ESLint and Prettier",
   "keywords": [
     "eslint",
@@ -25,7 +25,9 @@
   "types": "./dist/index.d.ts",
   "bin": "./dist/bin/index.cjs",
   "files": [
-    "dist"
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
   ],
   "scripts": {
     "build": "tsup",
@@ -40,41 +42,42 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@prettier/plugin-oxc": "^0.0.4",
-    "@tanstack/eslint-plugin-query": "^5.91.0",
-    "@typescript-eslint/parser": "^8.46.0",
-    "eslint": "^9.37.0",
-    "eslint-import-resolver-typescript": "^4.4.4",
-    "eslint-plugin-import-x": "^4.16.1",
-    "eslint-plugin-jest": "^29.0.1",
-    "eslint-plugin-jsdoc": "^61.1.1",
-    "eslint-plugin-nextjs": "^1.0.6",
-    "eslint-plugin-perfectionist": "^4.15.1",
-    "eslint-plugin-prefer-arrow-functions": "^3.9.1",
-    "eslint-plugin-react": "^7.37.5",
+    "@convex-dev/eslint-plugin": "0.0.1-alpha.4",
+    "@prettier/plugin-oxc": "0.0.4",
+    "@tanstack/eslint-plugin-query": "5.91.2",
+    "@typescript-eslint/parser": "8.46.0",
+    "eslint": "9.37.0",
+    "eslint-import-resolver-typescript": "4.4.4",
+    "eslint-plugin-import-x": "4.16.1",
+    "eslint-plugin-jest": "29.0.1",
+    "eslint-plugin-jsdoc": "61.1.4",
+    "eslint-plugin-nextjs": "1.1.0",
+    "eslint-plugin-perfectionist": "4.15.1",
+    "eslint-plugin-prefer-arrow-functions": "3.9.1",
+    "eslint-plugin-react": "7.37.5",
     "eslint-plugin-react-hooks": "7.0.0",
-    "eslint-plugin-react-refresh": "^0.4.23",
-    "eslint-plugin-storybook": "^9.1.10",
-    "eslint-plugin-turbo": "^2.5.8",
-    "eslint-plugin-unicorn": "^61.0.2",
-    "eslint-plugin-vitest": "^0.5.4",
-    "globals": "^16.4.0",
-    "prettier": "^3.6.2",
-    "prettier-plugin-css-order": "^2.1.2",
-    "prettier-plugin-curly": "^0.3.2",
-    "prettier-plugin-packagejson": "^2.5.19",
-    "prettier-plugin-sort-json": "^4.1.1",
-    "prettier-plugin-tailwindcss": "^0.6.14",
-    "typescript-eslint": "^8.46.0"
+    "eslint-plugin-react-refresh": "0.4.24",
+    "eslint-plugin-storybook": "9.1.12",
+    "eslint-plugin-turbo": "2.5.8",
+    "eslint-plugin-unicorn": "61.0.2",
+    "eslint-plugin-vitest": "0.5.4",
+    "globals": "16.4.0",
+    "prettier": "3.6.2",
+    "prettier-plugin-css-order": "2.1.2",
+    "prettier-plugin-curly": "0.3.2",
+    "prettier-plugin-packagejson": "2.5.19",
+    "prettier-plugin-sort-json": "4.1.1",
+    "prettier-plugin-tailwindcss": "0.7.0",
+    "typescript-eslint": "8.46.0"
   },
   "devDependencies": {
     "@repo/typescript-config": "workspace:*",
-    "@types/bun": "1.2.3",
-    "@types/node": "^22.18.10",
-    "commander": "^14.0.1",
-    "glob": "^11.0.3",
-    "tsup": "^8.5.0",
-    "typescript": "^5.9.3"
+    "@types/bun": "1.3.0",
+    "@types/node": "22.18.10",
+    "commander": "14.0.1",
+    "glob": "11.0.3",
+    "tsup": "8.5.0",
+    "typescript": "5.9.3"
   },
   "engines": {
     "node": "^20.11.0 || >=21.2.0"

package/src/eslint/base/README.md

@@ -0,0 +1,186 @@
+# Base ESLint Configuration
+
+The base configuration includes core ESLint rules that apply to all JavaScript and TypeScript projects. These rules are carefully selected from ESLint's recommended set with additional best practices.
+
+[← Back to main README](../../../README.md)
+
+## Overview
+
+This configuration is always enabled and provides:
+
+- Modern JavaScript best practices
+- Error prevention
+- Code quality improvements
+- Function style enforcement
+
+All rules are configured as **warnings** (not errors) to distinguish them from TypeScript errors in your IDE.
+
+[See all rules here](./rules.ts)
+
+## Function Style
+
+Control how functions should be written throughout your codebase:
+
+```js
+import { eslintConfig } from "js-style-kit";
+
+export default eslintConfig({
+  functionStyle: "arrow", // Default
+});
+```
+
+### Options
+
+#### `"arrow"` (default)
+
+Enforces arrow function expressions:
+
+```js
+// ✅ Good
+const add = (a, b) => a + b;
+const greet = () => console.log("Hello");
+
+// ❌ Bad
+function add(a, b) {
+  return a + b;
+}
+```
+
+#### `"declaration"`
+
+Enforces function declarations:
+
+```js
+// ✅ Good
+function add(a, b) {
+  return a + b;
+}
+
+// ❌ Bad
+const add = (a, b) => a + b;
+```
+
+#### `"expression"`
+
+Enforces function expressions:
+
+```js
+// ✅ Good
+const add = function (a, b) {
+  return a + b;
+};
+
+// ❌ Bad
+function add(a, b) {
+  return a + b;
+}
+const add = (a, b) => a + b;
+```
+
+#### `"off"`
+
+Disables function style enforcement - use any style you prefer.
+
+## Key Rules
+
+### Type Safety
+
+- **`eqeqeq`** - Require `===` and `!==` instead of `==` and `!=`
+- **`valid-typeof`** - Enforce comparing typeof expressions to valid strings
+- **`use-isnan`** - Require `isNaN()` when checking for NaN
+
+### Modern JavaScript
+
+- **`no-var`** - Require `let` or `const` instead of `var`
+- **`prefer-const`** - Prefer `const` over `let` when variables are never reassigned
+- **`prefer-arrow-callback`** - Prefer arrow functions as callbacks (when `functionStyle: "arrow"`)
+- **`prefer-template`** - Prefer template literals over string concatenation
+- **`prefer-spread`** - Prefer spread operator over `.apply()`
+- **`prefer-rest-params`** - Prefer rest parameters over `arguments`
+- **`object-shorthand`** - Require object literal shorthand syntax
+
+### Error Prevention
+
+- **`no-console`** - Disallow `console` except `console.info/warn/error`
+- **`no-debugger`** - Disallow `debugger` statements
+- **`no-alert`** - Disallow `alert`, `confirm`, and `prompt`
+- **`no-eval`** - Disallow `eval()`
+- **`no-implied-eval`** - Disallow implied `eval()` via `setTimeout`/`setInterval`
+- **`no-new-func`** - Disallow `Function` constructor
+- **`no-param-reassign`** - Disallow reassigning function parameters
+- **`array-callback-return`** - Require `return` statements in array method callbacks
+
+### Code Quality
+
+- **`curly`** - Require curly braces for multiline blocks
+- **`no-else-return`** - Disallow `else` after `return` in `if`
+- **`no-lonely-if`** - Disallow `if` as the only statement in `else`
+- **`no-unneeded-ternary`** - Disallow ternary operators when simpler alternatives exist
+- **`no-useless-return`** - Disallow redundant `return` statements
+- **`no-implicit-coercion`** - Disallow type conversion with shorter notations (prefer explicit conversion)
+
+### Naming Conventions
+
+- **`camelcase`** - Enforce camelCase naming (with exceptions for `UNSAFE_` React lifecycle methods)
+- **`new-cap`** - Require constructor names to begin with a capital letter
+- **`func-names`** - Require named function expressions
+
+### Dangerous Patterns
+
+- **`no-extend-native`** - Disallow extending native objects
+- **`no-proto`** - Disallow `__proto__` property
+- **`no-iterator`** - Disallow `__iterator__` property
+- **`no-new-wrappers`** - Disallow `new` for `String`, `Number`, and `Boolean`
+- **`no-bitwise`** - Disallow bitwise operators
+
+## TypeScript Integration
+
+When TypeScript is enabled, certain rules are automatically disabled to avoid conflicts with TypeScript's own checks:
+
+- `no-unused-vars` - Handled by `@typescript-eslint/no-unused-vars`
+- `no-unused-expressions` - Handled by `@typescript-eslint/no-unused-expressions`
+
+## Fixable Rules
+
+Many rules in this config are auto-fixable with `eslint --fix`:
+
+- ✅ `prefer-const` - Auto-converts `let` to `const`
+- ✅ `prefer-template` - Auto-converts string concatenation to template literals
+- ✅ `object-shorthand` - Auto-converts to shorthand syntax
+- ✅ `no-useless-rename` - Auto-removes useless renaming
+- ✅ `no-var` - Auto-converts `var` to `let`/`const`
+- ✅ And many more!
+
+Run `eslint . --fix` to automatically fix these issues.
+
+## Customization
+
+Override specific base rules using the `rules` option:
+
+```js
+import { eslintConfig } from "js-style-kit";
+
+export default eslintConfig({
+  rules: {
+    // Allow console.log in development
+    "no-console": "off",
+
+    // Make camelcase an error instead of warning
+    camelcase: "error",
+
+    // Allow bitwise operators
+    "no-bitwise": "off",
+  },
+});
+```
+
+## Related Configurations
+
+- [TypeScript](../typescript/README.md) - TypeScript-specific rules
+- [Import Plugin](../import/README.md) - Import/export validation
+- [Unicorn](../unicorn/README.md) - Additional best practices
+
+## Learn More
+
+- [ESLint Rules Documentation](https://eslint.org/docs/latest/rules/)
+- [Main README](../../../README.md)

package/src/eslint/base/config.ts

@@ -0,0 +1,37 @@
+import type {
+  EslintConfigObject,
+  EslintRuleConfig,
+  FunctionStyle,
+} from "../types.js";
+
+import { configNames } from "../constants.js";
+import { baseEslintRules } from "./rules.js";
+
+/**
+ * Creates a base ESLint configuration object with specified function style rules.
+ *
+ * @param functionStyle - Controls how functions should be written. Can be:
+ *   - "off": Disables function style enforcement
+ *   - "arrow": Enforces arrow function expressions
+ *   - "declaration": Enforces function declarations
+ *   - "expression": Enforces function expressions
+ * @param typescript - Whether TypeScript is being used in the project. When true, some rules are adjusted to be more TypeScript-friendly.
+ * @param customRules - Optional object containing custom rules to override or add to the base configuration.
+ * @returns ESLint configuration object
+ */
+export const baseEslintConfig = (
+  functionStyle: "off" | FunctionStyle,
+  typescript: boolean,
+  customRules?: Record<string, EslintRuleConfig>,
+): EslintConfigObject => ({
+  languageOptions: {
+    ecmaVersion: "latest",
+    sourceType: "module",
+  },
+  linterOptions: { reportUnusedDisableDirectives: true },
+  name: configNames.base,
+  rules: {
+    ...baseEslintRules(functionStyle, typescript),
+    ...(customRules ?? {}),
+  },
+});