oxlint-config-awesomeness 2.0.0 → 3.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 Opinionated Oxlint config for software houses that want all their apps to feel the same.
 
-**430 rules** across **10 plugins**. Built for full-stack TypeScript monorepos with React, Next.js, Hono, Prisma, and more.
+**450 rules** across **10 plugins**. Built for full-stack TypeScript monorepos with React, Next.js, Hono, Prisma, and more.
 
 ## Installation
 
@@ -38,6 +38,38 @@ export default defineConfig({
 
 Then run `pnpm oxlint` or `npx oxlint`.
 
+## Upgrading from 2.x
+
+3.0 adds **28 new restriction-level rules** that error on patterns AI-generated code routinely produces. Existing 2.x codebases may see new lint errors on upgrade — this is intentional; each rule catches a real failure mode.
+
+**What's newly enforced:**
+
+- **TypeScript escape hatches** — `no-explicit-any`, `no-non-null-assertion`, `no-non-null-asserted-nullish-coalescing`, `no-require-imports`, `no-var-requires`, `no-import-type-side-effects`, `use-unknown-in-catch-callback-variable`, `promise-function-async`, `no-dynamic-delete`, `no-invalid-void-type`, `no-empty-object-type`
+- **React correctness** — `button-has-type` (defaults silently submit forms), `no-danger` (XSS vector), `no-unknown-property`; `react/jsx-no-useless-fragment` re-enabled via `pedantic`
+- **Modern JS / Node hygiene** — `unicorn/prefer-node-protocol`, `unicorn/prefer-number-properties`, `unicorn/prefer-modern-math-apis`, `unicorn/no-document-cookie`, `unicorn/no-process-exit`, `unicorn/no-abusive-eslint-disable`, `node/handle-callback-err`, `node/no-new-require`, `node/no-path-concat`, `promise/catch-or-return`
+- **Core ESLint** — `no-var`, `no-use-before-define`, `no-empty`
+- **Import graph** — `import/no-cycle`
+- **Accessibility** — `jsx-a11y/anchor-ambiguous-text`
+
+**What changed in overrides:**
+
+- New `bin/**` and `scripts/**` override turns off `no-console` and `unicorn/no-process-exit` for CLI entry points.
+- Test override extended: the new strict rules that produce noise in tests (`no-require-imports`, `no-var-requires`, `promise-function-async`, `no-non-null-asserted-nullish-coalescing`, `import/no-cycle`, `no-empty`, `no-use-before-define`) are off inside tests.
+
+**Fixing common failures:**
+
+| Error | Fix |
+|-------|-----|
+| `: any` / `as any` | Use `unknown` + narrowing, or a real type. |
+| `value!` | Narrow with a type guard or throw explicitly. |
+| `<button onClick={...}>` | Add `type="button"` (or `"submit"`/`"reset"` as needed). |
+| `import fs from 'fs'` | `import fs from 'node:fs'`. |
+| `require(...)` in TS | Convert to ESM `import`. |
+| `fn(): Promise<T>` | Add `async` to the function. |
+| `catch((err) => err.message)` | `err` is `unknown` — narrow with `err instanceof Error`. |
+
+Every rule has inline code documentation with bad/good examples in the [All Rules](#all-rules) section below.
+
 ## FAQ
 
 ### I installed the package but no `.oxlintrc.json` was created. What did I miss?
@@ -96,18 +128,38 @@ The config includes smart overrides so strict rules don't create noise in files
 
 | Files | Relaxed Rules |
 |-------|---------------|
-| `*.test.ts`, `*.spec.ts`, `__tests__/**` | `no-explicit-any`, all `no-unsafe-*`, `max-lines`, `max-statements`, `no-empty-function` |
+| `*.test.ts`, `*.spec.ts`, `__tests__/**` | `no-explicit-any`, `no-non-null-assertion` (+ asserted-nullish variant), `no-require-imports`, `no-var-requires`, `promise-function-async`, all `no-unsafe-*`, `import/no-cycle`, `max-lines`, `max-lines-per-function`, `max-nested-callbacks`, `max-statements`, `no-empty`, `no-empty-function`, `no-use-before-define` |
 | `*.stories.tsx` | `no-console`, `no-multi-comp` |
 | `**/seed.ts`, `**/migrate.ts` | `no-console` |
+| `**/bin/**`, `scripts/**` | `no-console`, `unicorn/no-process-exit` |
 | `*.config.ts`, `next.config.*`, etc. | `max-lines`, `no-anonymous-default-export` |
 | `**/e2e/**/fixtures/**` | `rules-of-hooks` |
 | `*.ts`, `*.tsx` (all TypeScript) | Rules handled natively by the TS compiler (`no-undef`, `no-redeclare`, etc.) |
 
 ## Cherry-Picked Restriction Rules
 
-Instead of enabling the entire `restriction` category (which includes rules like `no-bitwise`, `no-plusplus`, `capitalized-comments` that cause daily friction), this config cherry-picks the most valuable restriction rules:
+Instead of enabling the entire `restriction` category (which includes rules like `no-bitwise`, `no-plusplus`, `capitalized-comments` that cause daily friction), this config cherry-picks the most valuable restriction rules, grouped by plugin:
+
+**Core ESLint**
+`curly`, `default-case`, `eqeqeq`, `grouped-accessor-pairs`, `max-classes-per-file`, `max-depth`, `max-lines`, `max-nested-callbacks`, `max-params`, `no-alert`, `no-caller`, `no-console`, `no-empty`, `no-eval`, `no-extend-native`, `no-implicit-coercion`, `no-new-func`, `no-new-wrappers`, `no-object-constructor`, `no-param-reassign`, `no-proto`, `no-return-assign`, `no-script-url`, `no-shadow`, `no-throw-literal`, `no-use-before-define`, `no-var`, `no-void`, `prefer-promise-reject-errors`, `prefer-template`
+
+**TypeScript** — blocks escape hatches (`any`, `!`, `require`) that AI-generated code routinely produces:
+`@typescript-eslint/no-dynamic-delete`, `no-empty-object-type`, `no-explicit-any`, `no-import-type-side-effects`, `no-invalid-void-type`, `no-non-null-asserted-nullish-coalescing`, `no-non-null-assertion`, `no-require-imports`, `no-var-requires`, `promise-function-async`, `use-unknown-in-catch-callback-variable`
+
+**React**
+`react/button-has-type`, `react/no-danger`, `react/no-unknown-property`
+
+**Import graph**
+`import/no-cycle`
+
+**Unicorn** (modern JS + anti-escape-hatch)
+`unicorn/no-abusive-eslint-disable`, `unicorn/no-document-cookie`, `unicorn/no-process-exit`, `unicorn/prefer-modern-math-apis`, `unicorn/prefer-node-protocol`, `unicorn/prefer-number-properties`
+
+**Promise / Node**
+`promise/catch-or-return`, `node/handle-callback-err`, `node/no-new-require`, `node/no-path-concat`
 
-`curly`, `default-case`, `eqeqeq`, `grouped-accessor-pairs`, `max-classes-per-file`, `max-depth`, `max-lines`, `max-nested-callbacks`, `max-params`, `no-alert`, `no-caller`, `no-console`, `no-eval`, `no-extend-native`, `no-implicit-coercion`, `no-new-func`, `no-new-wrappers`, `no-object-constructor`, `no-param-reassign`, `no-proto`, `no-return-assign`, `no-script-url`, `no-shadow`, `no-throw-literal`, `no-void`, `prefer-promise-reject-errors`, `prefer-template`
+**Accessibility**
+`jsx-a11y/anchor-ambiguous-text`
 
 ## Disabled by Intent
 
@@ -115,7 +167,7 @@ The five categories are enabled at `error`, but a small set of category-included
 
 | Category of fight | Rules off |
 |-------------------|-----------|
-| **React 17+ JSX transform / composition** | `react/react-in-jsx-scope`, `react/jsx-props-no-spreading`, `react/jsx-max-depth`, `react/no-array-index-key`, `react/jsx-no-useless-fragment`, `react/jsx-no-constructed-context-values` |
+| **React 17+ JSX transform / composition** | `react/react-in-jsx-scope`, `react/jsx-props-no-spreading`, `react/jsx-max-depth`, `react/no-array-index-key`, `react/jsx-no-constructed-context-values` |
 | **Modern ESM (named exports, side-effect imports, namespace imports, `node:` protocol)** | `import/no-named-export`, `import/prefer-default-export`, `import/group-exports`, `import/exports-last`, `import/no-anonymous-default-export`, `import/no-nodejs-modules`, `import/no-unassigned-import`, `import/no-namespace`, `import/max-dependencies`, `import/first`, `import/consistent-type-specifier-style` |
 | **Pedantic style preferences** | `no-magic-numbers`, `no-ternary`, `no-inline-comments`, `capitalized-comments`, `arrow-body-style`, `func-style`, `func-names`, `init-declarations`, `no-inferrable-types`, `prefer-destructuring`, `no-negated-condition`, `no-continue`, `parameter-properties`, `max-statements`, `max-lines-per-function`, `id-length` |
 | **Unicorn overreach** | `unicorn/prefer-global-this`, `unicorn/no-useless-undefined`, `unicorn/no-nested-ternary`, `unicorn/explicit-length-check`, `unicorn/custom-error-definition`, `unicorn/no-zero-fractions`, `unicorn/escape-case`, `unicorn/no-array-callback-reference`, `unicorn/no-array-for-each`, `unicorn/no-array-reduce` |

package/bin/init.js

@@ -34,7 +34,9 @@ if (command !== "init") {
 const target = resolve("oxlint.config.ts");
 
 if (existsSync(target) && !values.force) {
-  process.stderr.write("oxlint.config.ts already exists. Re-run with --force.\n");
+  process.stderr.write(
+    "oxlint.config.ts already exists. Re-run with --force.\n",
+  );
   process.exit(1);
 }
 

package/index.js

@@ -1,12 +1,20 @@
-import { defineConfig } from 'oxlint';
+import { defineConfig } from "oxlint";
 
 export default defineConfig({
+  // Bulk-enable oxlint categories as errors.
+  // `restriction` is intentionally excluded — oxlint docs warn against enabling it as a whole
+  // since those rules forbid valid language features. We cherry-pick restriction rules below.
   categories: {
-    correctness: 'error',
-    pedantic: 'error',
-    perf: 'error',
-    style: 'error',
-    suspicious: 'error',
+    // Outright bugs: unreachable code, constant conditions, invalid regex, etc.
+    correctness: "error",
+    // Style nitpicks that routinely prevent real bugs (strict booleans, unsafe any, etc.).
+    pedantic: "error",
+    // Patterns with measurable runtime cost.
+    perf: "error",
+    // Non-functional consistency — deterministic, no judgement calls.
+    style: "error",
+    // Code that's probably wrong but not provably so.
+    suspicious: "error",
   },
   env: {
     browser: true,
@@ -14,284 +22,519 @@ export default defineConfig({
     es2024: true,
     node: true,
   },
+  // JS-plugin bridge for ESLint plugins oxlint doesn't yet implement natively.
   jsPlugins: [
-    'eslint-plugin-no-only-tests',
-    'eslint-plugin-perfectionist',
-    'eslint-plugin-unused-imports',
-    { name: 'react-hooks-js', specifier: 'eslint-plugin-react-hooks' },
+    "eslint-plugin-no-only-tests",
+    "eslint-plugin-perfectionist",
+    "eslint-plugin-unused-imports",
+    // React Compiler's own lint rules — stricter than classic react-hooks;
+    // enforce the purity/memoization/gating invariants the compiler needs.
+    { name: "react-hooks-js", specifier: "eslint-plugin-react-hooks" },
   ],
   overrides: [
-    // TypeScript files — disable rules handled natively by the TS compiler
+    // TypeScript files — turn off rules the TS compiler already enforces via its type system.
+    // Running them again would be pure overhead and occasionally produce false positives.
     {
-      files: ['**/*.ts', '**/*.tsx', '**/*.mts', '**/*.cts'],
+      files: ["**/*.ts", "**/*.tsx", "**/*.mts", "**/*.cts"],
       rules: {
-        'constructor-super': 'off',
-        'getter-return': 'off',
-        'no-class-assign': 'off',
-        'no-const-assign': 'off',
-        'no-dupe-class-members': 'off',
-        'no-dupe-keys': 'off',
-        'no-func-assign': 'off',
-        'no-import-assign': 'off',
-        'no-new-native-nonconstructor': 'off',
-        'no-obj-calls': 'off',
-        'no-redeclare': 'off',
-        'no-setter-return': 'off',
-        'no-this-before-super': 'off',
-        'no-undef': 'off',
-        'no-unreachable': 'off',
-        'no-unsafe-negation': 'off',
-        'no-with': 'off',
-        'prefer-rest-params': 'error',
-        'prefer-spread': 'error',
+        // TS enforces `super()` requirements via class hierarchy checks.
+        "constructor-super": "off",
+        // TS catches missing returns via the function's declared return type.
+        "getter-return": "off",
+        // Class bindings are const in TS — reassignment is a compile error.
+        "no-class-assign": "off",
+        // `const` bindings can't be reassigned — TS catches this.
+        "no-const-assign": "off",
+        // Duplicate class members produce a TS compile error.
+        "no-dupe-class-members": "off",
+        // Duplicate object keys are reported by TS.
+        "no-dupe-keys": "off",
+        // Function declarations are const-bound in TS.
+        "no-func-assign": "off",
+        // Imports are read-only bindings — TS catches reassignment.
+        "no-import-assign": "off",
+        // TS signatures prevent calling non-constructors with `new`.
+        "no-new-native-nonconstructor": "off",
+        // `Math()` / `JSON()` aren't callable per TS lib types.
+        "no-obj-calls": "off",
+        // Redeclaration is a TS compile error.
+        "no-redeclare": "off",
+        // TS enforces setter signatures must not return values.
+        "no-setter-return": "off",
+        // TS catches `this` before `super()` in derived constructors.
+        "no-this-before-super": "off",
+        // TS resolves all references — unresolved identifiers fail to compile.
+        "no-undef": "off",
+        // TS reports unreachable code as a diagnostic.
+        "no-unreachable": "off",
+        // TS narrows operators; `!a instanceof B` becomes a type error.
+        "no-unsafe-negation": "off",
+        // `with` statements aren't allowed in strict mode or TS at all.
+        "no-with": "off",
+        // Not type-checked by TS — prefer `...args` over `arguments`.
+        "prefer-rest-params": "error",
+        // Not type-checked by TS — prefer spread over `.apply()`.
+        "prefer-spread": "error",
       },
     },
-    // Test files — relax strict rules that create noise in tests
+    // Test files — relax strict rules that generate noise in mocks, fixtures, describe blocks.
     {
       files: [
-        '**/*.test.ts',
-        '**/*.test.tsx',
-        '**/*.spec.ts',
-        '**/*.spec.tsx',
-        '**/__tests__/**',
+        "**/*.test.ts",
+        "**/*.test.tsx",
+        "**/*.spec.ts",
+        "**/*.spec.tsx",
+        "**/__tests__/**",
       ],
       rules: {
-        '@typescript-eslint/no-explicit-any': 'off',
-        '@typescript-eslint/no-non-null-assertion': 'off',
-        '@typescript-eslint/no-unsafe-argument': 'off',
-        '@typescript-eslint/no-unsafe-assignment': 'off',
-        '@typescript-eslint/no-unsafe-call': 'off',
-        '@typescript-eslint/no-unsafe-member-access': 'off',
-        '@typescript-eslint/no-unsafe-return': 'off',
-        'max-lines': 'off',
-        'max-lines-per-function': 'off',
-        'max-nested-callbacks': 'off',
-        'max-statements': 'off',
-        'no-empty-function': 'off',
+        // Mocks are commonly typed `any` for speed.
+        "@typescript-eslint/no-explicit-any": "off",
+        // Fixtures chain `!` + `??` for narrowing.
+        "@typescript-eslint/no-non-null-asserted-nullish-coalescing": "off",
+        // Fixtures narrow via `!` on known-populated test data.
+        "@typescript-eslint/no-non-null-assertion": "off",
+        // `jest.mock` / `vi.mock` factories use `require()`.
+        "@typescript-eslint/no-require-imports": "off",
+        // Mocks don't carry type info.
+        "@typescript-eslint/no-unsafe-argument": "off",
+        "@typescript-eslint/no-unsafe-assignment": "off",
+        "@typescript-eslint/no-unsafe-call": "off",
+        "@typescript-eslint/no-unsafe-member-access": "off",
+        "@typescript-eslint/no-unsafe-return": "off",
+        // Legacy `var x = require(...)` still appears in older test setups.
+        "@typescript-eslint/no-var-requires": "off",
+        // Mock implementations may return bare promises without `async`.
+        "@typescript-eslint/promise-function-async": "off",
+        // Test utilities can legitimately form small local cycles.
+        "import/no-cycle": "off",
+        // `describe`/`it` blocks legitimately exceed size limits.
+        "max-lines": "off",
+        "max-lines-per-function": "off",
+        "max-nested-callbacks": "off",
+        "max-statements": "off",
+        // Empty test stubs are valid placeholders.
+        "no-empty": "off",
+        // Empty mock implementations are common.
+        "no-empty-function": "off",
+        // Test helpers are often defined after the `describe` that uses them.
+        "no-use-before-define": "off",
       },
     },
-    // Storybook stories — relax rules for component documentation
+    // Storybook stories — component documentation has its own idioms.
     {
-      files: ['**/*.stories.ts', '**/*.stories.tsx'],
+      files: ["**/*.stories.ts", "**/*.stories.tsx"],
       rules: {
-        'no-console': 'off',
-        'react/no-multi-comp': 'off',
+        // `console.log` is a valid teaching tool in stories.
+        "no-console": "off",
+        // Stories legitimately export multiple component variants.
+        "react/no-multi-comp": "off",
       },
     },
-    // Seed and migration files — allow console for CLI output
+    // Seed and migration scripts — one-shot CLI tools with log output.
     {
-      files: ['**/seed.ts', '**/seed.js', '**/migrate.ts', '**/migrate.js'],
+      files: ["**/seed.ts", "**/seed.js", "**/migrate.ts", "**/migrate.js"],
       rules: {
-        'no-console': 'off',
+        // CLI tools print progress to stdout.
+        "no-console": "off",
       },
     },
-    // Config files — relax rules for tooling configs
+    // CLI entry points — `process.exit` and console output are the whole point.
+    {
+      files: ["**/bin/**", "scripts/**"],
+      rules: {
+        "no-console": "off",
+        "unicorn/no-process-exit": "off",
+      },
+    },
+    // Config files — build tooling is allowed anonymous defaults and long files.
     {
       files: [
-        '*.config.ts',
-        '*.config.js',
-        '*.config.mjs',
-        '*.config.mts',
-        '**/.storybook/**',
-        'vitest.config.*',
-        'playwright.config.*',
-        'tailwind.config.*',
-        'postcss.config.*',
-        'next.config.*',
+        "*.config.ts",
+        "*.config.js",
+        "*.config.mjs",
+        "*.config.mts",
+        "**/.storybook/**",
+        "vitest.config.*",
+        "playwright.config.*",
+        "tailwind.config.*",
+        "postcss.config.*",
+        "next.config.*",
       ],
       rules: {
-        'import-x/no-anonymous-default-export': 'off',
-        'max-lines': 'off',
+        // Tool configs are traditionally `export default {...}` with no name.
+        "import-x/no-anonymous-default-export": "off",
+        // Big configs (webpack, next) routinely exceed 400 lines.
+        "max-lines": "off",
       },
     },
-    // E2E test fixtures — may not follow standard component rules
+    // Playwright/Cypress E2E fixtures — test harness code, not React components.
     {
-      files: ['**/e2e/**/fixtures/**', '**/e2e/**/*.ts'],
+      files: ["**/e2e/**/fixtures/**", "**/e2e/**/*.ts"],
       rules: {
-        'react-hooks/rules-of-hooks': 'off',
+        // Playwright fixtures use hook-like names (`test.extend`) that trip the rule.
+        "react-hooks/rules-of-hooks": "off",
       },
     },
   ],
   plugins: [
-    'typescript',
-    'import',
-    'react',
-    'unicorn',
-    'jsx-a11y',
-    'promise',
-    'nextjs',
-    'oxc',
-    'node',
+    "typescript",
+    "import",
+    "react",
+    "unicorn",
+    "jsx-a11y",
+    "promise",
+    "nextjs",
+    "oxc",
+    "node",
   ],
   rules: {
     // TypeScript — custom options
-    '@typescript-eslint/array-type': [
-      'error',
-      {
-        default: 'generic',
-      },
-    ],
-    '@typescript-eslint/consistent-type-definitions': ['error', 'type'],
+
+    // Prefer `Array<T>` over `T[]` — generic form scales to complex element types
+    // (`Array<() => void>` vs `(() => void)[]`) without extra parentheses.
+    "@typescript-eslint/array-type": ["error", { default: "generic" }],
+    // Force `type` over `interface` — `type` supports unions/intersections/mapped types
+    // and can't be accidentally merged via declaration merging.
+    "@typescript-eslint/consistent-type-definitions": ["error", "type"],
 
     // Core eslint — custom options
-    'eslint/no-duplicate-imports': ['error',
-      {
-      allowSeparateTypeImports: true,
-      }
+
+    // Prevent duplicate import statements but still allow separating type-only imports
+    // from value imports (`import type { X } from 'x'; import { y } from 'x';`).
+    "eslint/no-duplicate-imports": [
+      "error",
+      { allowSeparateTypeImports: true },
     ],
-    'no-warning-comments': [
-      'error',
-      {
-        terms: ['@nocommit'],
-      },
+    // Block `@nocommit` markers from reaching main — a hard stop for WIP code.
+    "no-warning-comments": ["error", { terms: ["@nocommit"] }],
+
+    // Restriction — core eslint (cherry-picked from the 90 rules in `restriction`)
+
+    // Always use braces — prevents the dangling-else bug and ambiguous single-line bodies.
+    curly: "error",
+    // Require a `default` case in switch — forces explicit handling of unknown values.
+    "default-case": "error",
+    // Ban `==` — type coercion is the single largest source of surprise in JS.
+    eqeqeq: "error",
+    // Keep get/set pairs adjacent — readers expect them together.
+    "grouped-accessor-pairs": "error",
+    // One class per file — keeps files focused and imports unambiguous.
+    "max-classes-per-file": ["error", { max: 1 }],
+    // Cap nesting at 4 — deeper usually means an extraction is overdue.
+    "max-depth": ["error", { max: 4 }],
+    // 400-line ceiling (comments + blanks excluded) — force splitting by concern.
+    "max-lines": [
+      "error",
+      { max: 400, skipBlankLines: true, skipComments: true },
     ],
+    // Deeply nested callbacks are a refactor smell — convert to async/await or extract.
+    "max-nested-callbacks": ["error", { max: 3 }],
+    // More than 4 positional params → pass an options object for readability.
+    "max-params": ["error", { max: 4 }],
+    // `alert()` is never production UI — use a toast/modal primitive.
+    "no-alert": "error",
+    // `.caller`/`.arguments.callee` are deprecated and strict-mode errors.
+    "no-caller": "error",
+    // Ship with a real logger, not `console.*` — overrides above allow CLIs/stories.
+    "no-console": "error",
+    // Empty blocks are either a forgotten TODO or a logic bug.
+    "no-empty": "error",
+    // Banned as a security + performance anti-pattern; defeats static analysis.
+    "no-eval": "error",
+    // Mutating `Array.prototype` etc. breaks every library that trusts the globals.
+    "no-extend-native": "error",
+    // Be explicit with conversions — `Number(x)` over `+x`, except `!!x` (idiomatic).
+    "no-implicit-coercion": ["error", { allow: ["!!"] }],
+    // Runtime code generation from strings — same security and performance issues as dynamic exec.
+    "no-new-func": "error",
+    // `new String/Number/Boolean(...)` creates boxed objects that fail `===`.
+    "no-new-wrappers": "error",
+    // Prefer `{}` literal over `new Object()`.
+    "no-object-constructor": "error",
+    // Params are inputs, not locals — reassigning them hides the original value.
+    "no-param-reassign": "error",
+    // `__proto__` is deprecated — use `Object.getPrototypeOf`.
+    "no-proto": "error",
+    // `return a = b` looks like a typo for `==`.
+    "no-return-assign": "error",
+    // `javascript:` URLs are XSS vectors.
+    "no-script-url": "error",
+    // Shadowing outer-scope names hides bugs during refactors.
+    "no-shadow": "error",
+    // Always throw `Error` objects — literals have no stack trace.
+    "no-throw-literal": "error",
+    // Catch TDZ bugs from using `let`/`const` before their declaration.
+    "no-use-before-define": "error",
+    // `var` has function scope — use `let`/`const` (block-scoped).
+    "no-var": "error",
+    // Allow `void promise` to explicitly ignore a floating promise — a real pattern.
+    "no-void": ["error", { allowAsStatement: true }],
+    // Reject promises with `Error` instances so stack traces survive.
+    "prefer-promise-reject-errors": "error",
+    // Template literals > string concatenation — fewer escape/coercion bugs.
+    "prefer-template": "error",
+
+    // Restriction — TypeScript
+    // Highest-leverage rules for AI-generated code: they block the escape hatches
+    // (`any`, `!`, `require`) that AI reaches for when it can't figure out the right type.
+
+    // `delete obj[dynamicKey]` is usually a type-lie — the key may not be optional.
+    "@typescript-eslint/no-dynamic-delete": "error",
+    // `{}` means "any non-nullish value" — almost never what people mean.
+    "@typescript-eslint/no-empty-object-type": "error",
+    // The #1 AI tell. Use `unknown` + narrowing or a real type.
+    "@typescript-eslint/no-explicit-any": "error",
+    // Ensure `import type` has no runtime side effects — keeps bundles clean.
+    "@typescript-eslint/no-import-type-side-effects": "error",
+    // `void` only makes sense as a return type or a generic constraint.
+    "@typescript-eslint/no-invalid-void-type": "error",
+    // `x! ?? fallback` is always a bug — the `!` already asserts non-null.
+    "@typescript-eslint/no-non-null-asserted-nullish-coalescing": "error",
+    // Non-null `!` lies to the checker. Narrow properly or throw explicitly.
+    "@typescript-eslint/no-non-null-assertion": "error",
+    // Use ESM `import` — `require()` breaks tree-shaking and type inference.
+    "@typescript-eslint/no-require-imports": "error",
+    "@typescript-eslint/no-var-requires": "error",
+    // Promise-returning functions must be `async` — guarantees thrown errors become rejections.
+    "@typescript-eslint/promise-function-async": "error",
+    // `.catch((err) => ...)` — `err` should be `unknown`, not `any` (strict TS behavior).
+    "@typescript-eslint/use-unknown-in-catch-callback-variable": "error",
+
+    // Restriction — React
+
+    // `<button>` defaults to `type="submit"` — silently submits enclosing forms. Must be explicit.
+    "react/button-has-type": "error",
+    // Raw HTML insertion in JSX is an XSS vector — require a deliberate opt-out.
+    "react/no-danger": "error",
+    // Catches typos like `class=` or `tabindex=` in JSX.
+    "react/no-unknown-property": "error",
+
+    // Restriction — import graph
+
+    // Circular imports produce `undefined` exports at runtime — a real-world crash source.
+    "import/no-cycle": "error",
+
+    // Restriction — unicorn (modern JS + anti-escape-hatch)
+
+    // Blanket `// eslint-disable` without a rule name is the universal AI escape hatch.
+    "unicorn/no-abusive-eslint-disable": "error",
+    // Direct `document.cookie` access — use a cookie library for encoding/security.
+    "unicorn/no-document-cookie": "error",
+    // `process.exit()` skips `finally` blocks and async flushes. CLI override above handles CLIs.
+    "unicorn/no-process-exit": "error",
+    // `Math.trunc(x)` over `x | 0` — clearer intent, correct for numbers outside Int32 range.
+    "unicorn/prefer-modern-math-apis": "error",
+    // `import { fs } from 'node:fs'` — the `node:` prefix disambiguates from npm packages.
+    "unicorn/prefer-node-protocol": "error",
+    // `Number.isNaN(x)` over `isNaN(x)` — the global coerces strings before checking.
+    "unicorn/prefer-number-properties": "error",
+
+    // Restriction — promise / node
+
+    // Callback-style APIs: always handle the `err` argument.
+    "node/handle-callback-err": "error",
+    // `new require(...)` is meaningless — require is a function, not a constructor.
+    "node/no-new-require": "error",
+    // String-concatenating paths breaks on Windows — use `path.join`.
+    "node/no-path-concat": "error",
+    // Every promise chain must end with `.catch()` or `return` — unhandled rejections are silent bugs.
+    "promise/catch-or-return": "error",
 
-    
-
-    // Restriction — cherry-picked (not bulk-enabled)
-    curly: 'error',
-    'default-case': 'error',
-    eqeqeq: 'error',
-    'grouped-accessor-pairs': 'error',
-    'max-classes-per-file': ['error', { max: 1 }],
-    'max-depth': ['error', { max: 4 }],
-    'max-lines': ['error', { max: 400, skipBlankLines: true, skipComments: true }],
-    'max-nested-callbacks': ['error', { max: 3 }],
-    'max-params': ['error', { max: 4 }],
-    'no-alert': 'error',
-    'no-caller': 'error',
-    'no-console': 'error',
-    'no-eval': 'error',
-    'no-extend-native': 'error',
-    'no-implicit-coercion': ['error', { allow: ['!!'] }],
-    'no-new-func': 'error',
-    'no-new-wrappers': 'error',
-    'no-object-constructor': 'error',
-    'no-param-reassign': 'error',
-    'no-proto': 'error',
-    'no-return-assign': 'error',
-    'no-script-url': 'error',
-    'no-shadow': 'error',
-    'no-throw-literal': 'error',
-    'no-void': ['error', { allowAsStatement: true }],
-    'prefer-promise-reject-errors': 'error',
-    'prefer-template': 'error',
+    // Restriction — a11y
+
+    // "click here", "read more", "link" — ambiguous link text fails screen readers.
+    "jsx-a11y/anchor-ambiguous-text": "error",
 
     // Disabled — incompatible with React 17+ JSX transform and common composition patterns
-    'react/jsx-max-depth': 'off',
-    'react/jsx-no-constructed-context-values': 'off',
-    'react/jsx-no-useless-fragment': 'off',
-    'react/jsx-props-no-spreading': 'off',
-    'react/no-array-index-key': 'off',
-    'react/react-in-jsx-scope': 'off',
-
-    // Disabled — modern ESM uses named exports; side-effect imports (CSS, polyfills, node: protocol) are legitimate; namespace imports are canonical for Sentry, Prisma, etc.
-    'import/consistent-type-specifier-style': 'off',
-    'import/exports-last': 'off',
-    'import/first': 'off',
-    'import/group-exports': 'off',
-    'import/max-dependencies': 'off',
-    'import/no-anonymous-default-export': 'off',
-    'import/no-named-export': 'off',
-    'import/no-namespace': 'off',
-    'import/no-nodejs-modules': 'off',
-    'import/no-unassigned-import': 'off',
-    'import/prefer-default-export': 'off',
+
+    // JSX depth is constrained by composition, not by a magic number.
+    "react/jsx-max-depth": "off",
+    // React Compiler (`react-hooks-js`) handles memoization — no need to pre-extract context values.
+    "react/jsx-no-constructed-context-values": "off",
+    // Prop spreading is a valid composition pattern with proper types.
+    "react/jsx-props-no-spreading": "off",
+    // Static lists have stable indices — false positives outweigh real catches.
+    "react/no-array-index-key": "off",
+    // React 17+ automatic JSX runtime — no import needed.
+    "react/react-in-jsx-scope": "off",
+
+    // Disabled — import rules that fight modern ESM / legitimate patterns
+
+    // Mixing `import type` styles in one project is fine.
+    "import/consistent-type-specifier-style": "off",
+    // "Exports at end" is style preference, not correctness.
+    "import/exports-last": "off",
+    // Side-effect imports (CSS, polyfills) must come first — conflicts with this rule.
+    "import/first": "off",
+    // Grouping exports isn't meaningful with named exports.
+    "import/group-exports": "off",
+    // Dependency count caps don't catch real problems.
+    "import/max-dependencies": "off",
+    // Anonymous default exports are normal in configs and utilities.
+    "import/no-anonymous-default-export": "off",
+    // Named exports are the modern ESM norm.
+    "import/no-named-export": "off",
+    // `import * as Sentry from '@sentry/node'` is the canonical API for Sentry/Prisma/etc.
+    "import/no-namespace": "off",
+    // Node built-ins (`node:fs`) are legitimate in Node code.
+    "import/no-nodejs-modules": "off",
+    // Side-effect imports for CSS and polyfills are required.
+    "import/no-unassigned-import": "off",
+    // Modern codebases prefer named exports; default exports are the exception.
+    "import/prefer-default-export": "off",
 
     // Disabled — pedantic style preferences that fight day-to-day clarity
-    'arrow-body-style': 'off',
-    'capitalized-comments': 'off',
-    'func-names': 'off',
-    'func-style': 'off',
-    'id-length': 'off',
-    'init-declarations': 'off',
-    'max-lines-per-function': 'off',
-    'max-statements': 'off',
-    'no-continue': 'off',
-    'no-inferrable-types': 'off',
-    'no-inline-comments': 'off',
-    'no-magic-numbers': 'off',
-    'no-negated-condition': 'off',
-    'no-ternary': 'off',
-    'parameter-properties': 'off',
-    'prefer-destructuring': 'off',
+
+    // Block bodies are sometimes clearer (breakpoints, multi-statement arrows).
+    "arrow-body-style": "off",
+    // Capitalization of comments is noise.
+    "capitalized-comments": "off",
+    // Anonymous arrows are canonical in modern code.
+    "func-names": "off",
+    // Mixing declarations and expressions is a project's call.
+    "func-style": "off",
+    // `i`, `x`, `n` are fine in small scopes.
+    "id-length": "off",
+    // `let x; ... x = compute();` is a real pattern.
+    "init-declarations": "off",
+    // Too blunt — well-factored functions can still be long.
+    "max-lines-per-function": "off",
+    // Too blunt — modern async code has many statements by design.
+    "max-statements": "off",
+    // `continue` is often clearer than extra nesting.
+    "no-continue": "off",
+    // Explicit types on simple assignments is a style choice, not an error.
+    "no-inferrable-types": "off",
+    // Inline `// ...` comments are sometimes the clearest option.
+    "no-inline-comments": "off",
+    // Too noisy — most numbers in UI code have obvious meaning.
+    "no-magic-numbers": "off",
+    // `if (!done)` is often clearer than `if (done === false)`.
+    "no-negated-condition": "off",
+    // Ternaries are fine in expressions.
+    "no-ternary": "off",
+    // TS parameter properties (`constructor(private x: T)`) are a valid shorthand.
+    "parameter-properties": "off",
+    // Destructuring isn't always clearer — `arr[0]` can be better than `const [first] = arr`.
+    "prefer-destructuring": "off",
 
     // Disabled — unicorn rules that overreach into legitimate patterns
-    'unicorn/custom-error-definition': 'off',
-    'unicorn/escape-case': 'off',
-    'unicorn/explicit-length-check': 'off',
-    'unicorn/no-array-callback-reference': 'off',
-    'unicorn/no-array-for-each': 'off',
-    'unicorn/no-array-reduce': 'off',
-    'unicorn/no-nested-ternary': 'off',
-    'unicorn/no-useless-undefined': 'off',
-    'unicorn/no-zero-fractions': 'off',
-    'unicorn/prefer-global-this': 'off',
-
-    // Disabled — async/await is preferred but raw Promise constructors and callbacks remain idiomatic in many APIs (event emitters, streams, callback adapters)
-    'promise/avoid-new': 'off',
-    'promise/param-names': 'off',
-    'promise/prefer-await-to-callbacks': 'off',
-
-    // Style overrides — handled by perfectionist/oxfmt
-    'sort-imports': 'off',
-    'sort-keys': 'off',
-    'sort-vars': 'off',
-
-    // Unicorn — enforce kebab-case but allow Next.js bracket patterns
-    // Next.js dynamic routes ([slug], [...catchAll]) and special files (_app, _document)
-    'unicorn/filename-case': [
-      'error',
-      {
-        case: 'kebabCase',
-        ignore: [String.raw`\[.*\]`, '^_.*'],
-      },
-    ],
-    'unicorn/no-null': 'off',
 
-    // Perfectionist — sorting
-    'perfectionist/sort-enums': [
-      'error',
+    // Over-prescribes a specific custom-error shape.
+    "unicorn/custom-error-definition": "off",
+    // Escape-case fights non-English strings and regex literals.
+    "unicorn/escape-case": "off",
+    // `if (arr.length)` is a valid idiom for "has elements".
+    "unicorn/explicit-length-check": "off",
+    // `.map(fn)` is the canonical callback pattern.
+    "unicorn/no-array-callback-reference": "off",
+    // `forEach` is fine for side effects.
+    "unicorn/no-array-for-each": "off",
+    // `reduce` is fine — the rule is ideological, not mechanical.
+    "unicorn/no-array-reduce": "off",
+    // Nested ternaries are sometimes the clearest expression.
+    "unicorn/no-nested-ternary": "off",
+    // `return undefined` is sometimes explicit and intentional.
+    "unicorn/no-useless-undefined": "off",
+    // `1.0` can signal "this is a floating-point value" in domain code.
+    "unicorn/no-zero-fractions": "off",
+    // `window` and `self` are fine in clearly-browser code.
+    "unicorn/prefer-global-this": "off",
+
+    // Disabled — raw Promise constructors and callbacks stay idiomatic for adapters
+
+    // `new Promise` is required when wrapping event emitters, streams, or callback APIs.
+    "promise/avoid-new": "off",
+    // `(resolve, reject)` is the idiomatic parameter naming.
+    "promise/param-names": "off",
+    // Event emitters and streams are callback-based and stay that way.
+    "promise/prefer-await-to-callbacks": "off",
+
+    // Style overrides — handled deterministically by perfectionist/oxfmt
+    "sort-imports": "off",
+    "sort-keys": "off",
+    "sort-vars": "off",
+
+    // Unicorn — filename-case
+
+    // kebab-case matches the CLAUDE.md convention, with exceptions for:
+    // - Next.js dynamic routes: `[slug].tsx`, `[...catchAll].tsx`
+    // - Next.js special files: `_app.tsx`, `_document.tsx`
+    "unicorn/filename-case": [
+      "error",
       {
-        partitionByComment: true,
-        sortByValue: 'always',
+        case: "kebabCase",
+        ignore: [String.raw`\[.*\]`, "^_.*"],
       },
     ],
-    'perfectionist/sort-heritage-clauses': 'error',
-    'perfectionist/sort-jsx-props': 'error',
-    'perfectionist/sort-object-types': 'error',
-    'perfectionist/sort-objects': [
-      'error',
-      {
-        partitionByComment: true,
-      },
+    // `null` is a legitimate, distinct value — don't force `undefined` everywhere.
+    "unicorn/no-null": "off",
+
+    // Perfectionist — deterministic sorting keeps diffs stable and review-friendly
+
+    // Enums sorted by value make intent + ordering obvious; partitionByComment preserves groupings.
+    "perfectionist/sort-enums": [
+      "error",
+      { partitionByComment: true, sortByValue: "always" },
     ],
+    // `class Foo extends A, B` — alphabetical for stable diffs.
+    "perfectionist/sort-heritage-clauses": "error",
+    // JSX prop order is a huge diff-noise source — sort it.
+    "perfectionist/sort-jsx-props": "error",
+    // Type fields sorted alphabetically for scannability.
+    "perfectionist/sort-object-types": "error",
+    // Object keys alphabetical; partitionByComment preserves intentional grouping.
+    "perfectionist/sort-objects": ["error", { partitionByComment: true }],
+
+    // React Compiler (react-hooks-js) — enforce the invariants the compiler needs
+    // to safely auto-memoize your components.
 
-    // React Compiler (react-hooks-js)
-    'react-hooks-js/component-hook-factories': 'error',
-    'react-hooks-js/config': 'error',
-    'react-hooks-js/error-boundaries': 'error',
-    'react-hooks-js/gating': 'error',
-    'react-hooks-js/globals': 'error',
-    'react-hooks-js/immutability': 'error',
-    'react-hooks-js/incompatible-library': 'error',
-    'react-hooks-js/preserve-manual-memoization': 'error',
-    'react-hooks-js/purity': 'error',
-    'react-hooks-js/refs': 'error',
-    'react-hooks-js/set-state-in-effect': 'error',
-    'react-hooks-js/set-state-in-render': 'error',
-    'react-hooks-js/static-components': 'error',
-    'react-hooks-js/unsupported-syntax': 'error',
-    'react-hooks-js/use-memo': 'error',
-
-    // React hooks
-    'react-hooks/exhaustive-deps': 'error',
-    'react-hooks/rules-of-hooks': 'error',
-
-    // No only tests
-    'no-only-tests/no-only-tests': 'error',
+    // Hooks can't be created inside components — they must be module-level.
+    "react-hooks-js/component-hook-factories": "error",
+    // Validates the plugin's own config shape.
+    "react-hooks-js/config": "error",
+    // Error boundaries have specific invariants the compiler respects.
+    "react-hooks-js/error-boundaries": "error",
+    // Feature-flag gating must be consistent so the compiler can reason about it.
+    "react-hooks-js/gating": "error",
+    // No global mutation during render — breaks compiler's purity assumptions.
+    "react-hooks-js/globals": "error",
+    // Don't mutate props or state — compiler assumes immutability.
+    "react-hooks-js/immutability": "error",
+    // Flags libraries the compiler can't safely optimize around.
+    "react-hooks-js/incompatible-library": "error",
+    // If you wrote `useMemo`/`useCallback`, keep them — the compiler preserves your intent.
+    "react-hooks-js/preserve-manual-memoization": "error",
+    // Render must be pure — no side effects, no I/O, no randomness.
+    "react-hooks-js/purity": "error",
+    // Refs belong in effects and handlers, not render.
+    "react-hooks-js/refs": "error",
+    // Setting state inside an effect must be carefully guarded.
+    "react-hooks-js/set-state-in-effect": "error",
+    // Never set state during render — infinite loop.
+    "react-hooks-js/set-state-in-render": "error",
+    // Prefer static component definitions over dynamic factories.
+    "react-hooks-js/static-components": "error",
+    // Syntax (decorators, specific private-field patterns) the compiler can't analyze.
+    "react-hooks-js/unsupported-syntax": "error",
+    // Enforces the modern `useMemo` shape the compiler expects.
+    "react-hooks-js/use-memo": "error",
+
+    // React hooks — the classic rules, still necessary even with the compiler
+
+    // Dependency array must include every value referenced in the effect.
+    "react-hooks/exhaustive-deps": "error",
+    // Hooks only at the top level, only from React functions — never in conditions/loops.
+    "react-hooks/rules-of-hooks": "error",
+
+    // Testing
+
+    // `.only()` in a test file skips every other test — must never land on main.
+    "no-only-tests/no-only-tests": "error",
 
     // Unused imports
-    'unused-imports/no-unused-imports': 'error',
+
+    // Dead imports bloat bundles and mislead readers — remove them.
+    "unused-imports/no-unused-imports": "error",
   },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oxlint-config-awesomeness",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Oxlint config with sensible defaults.",
   "keywords": [
     "autofix",