eslint-plugin-nextfriday 2.0.0 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # eslint-plugin-nextfriday
 
+## 3.1.0
+
+### Minor Changes
+
+- [#116](https://github.com/next-friday/eslint-plugin-nextfriday/pull/116) [`64ced55`](https://github.com/next-friday/eslint-plugin-nextfriday/commit/64ced556b4099a40ca2f4750523c7a079d2c81d8) Thanks [@joetakara](https://github.com/joetakara)! - `nextjs` and `nextjs/recommended` presets now also disable `nextfriday/file-kebab-case` (in addition to `nextfriday/jsx-pascal-case`) for files under `app/**`, `src/app/**`, `pages/**`, and `src/pages/**`. The override globs are expanded from `*.{jsx,tsx}` to `*.{js,jsx,ts,tsx}` so `route.ts`, `middleware.ts`, and other framework-named `.ts`/`.js` files in those directories are no longer flagged by either filename rule. Filename conventions in routing directories are owned by the framework, not by this plugin.
+
+  The `react` and `react/recommended` presets are unchanged — projects using them still enforce `file-kebab-case` on every `.ts`/`.js` and `jsx-pascal-case` on every `.tsx`/`.jsx`.
+
+### Patch Changes
+
+- [#116](https://github.com/next-friday/eslint-plugin-nextfriday/pull/116) [`64ced55`](https://github.com/next-friday/eslint-plugin-nextfriday/commit/64ced556b4099a40ca2f4750523c7a079d2c81d8) Thanks [@joetakara](https://github.com/joetakara)! - Documentation quality improvements targeting Context7 scoring gaps:
+  - `README.md` — "Per-Directory Configuration" section now explains how flat config resolves rules (config-array order, `files`/`ignores` precedence, why flat replaces `.eslintrc` overrides), adds a preset-tier-per-directory table, and lists common edge cases (glob ordering, top-level vs scoped `ignores`, spreading array-shaped presets, `--print-config` for debugging).
+  - `README.md` — "Migration Strategy" section is restructured around six concrete phases: surveying violations with `eslint --format json | jq`, isolating the auto-fix pass into its own PR, adopting the warn-level preset, ratcheting clean directories to `/recommended`, managing exceptions (severity override → directory override → disable comment, in that order of preference), and tracking violation count over time. The "Prioritize rules by impact" table is unchanged.
+  - `docs/rules/ENFORCE_CONSTANT_CASE.md` — Configuration section split into install / enable-just-this-rule / enable-with-related-rules / enable-via-preset / scope-to-directory subsections, plus a "Severity-only — no rule options" callout clarifying that the legacy `["error", { ... }]` array form is not accepted because no rule in this plugin has options.
+
+## 3.0.0
+
+### Major Changes
+
+- [#114](https://github.com/next-friday/eslint-plugin-nextfriday/pull/114) [`7933269`](https://github.com/next-friday/eslint-plugin-nextfriday/commit/793326971cbbf15aaf2015f13622b7eff0fd51b2) Thanks [@joetakara](https://github.com/joetakara)! - Remove bundled `configs.sonarjs` and `configs.unicorn`. These configs are no longer exported. Consumers that previously did `...nextfriday.configs.sonarjs` or `...nextfriday.configs.unicorn` must install `eslint-plugin-sonarjs` and/or `eslint-plugin-unicorn` directly and configure them in their own flat config.
+
+  Migration:
+
+  ```js
+  import sonarjs from "eslint-plugin-sonarjs";
+  import unicorn from "eslint-plugin-unicorn";
+
+  export default [
+    {
+      plugins: { sonarjs },
+      rules: { ...sonarjs.configs.recommended.rules },
+    },
+    {
+      plugins: { unicorn },
+      rules: { ...unicorn.configs.recommended.rules },
+    },
+  ];
+  ```
+
+  The remaining six presets (`base`, `base/recommended`, `react`, `react/recommended`, `nextjs`, `nextjs/recommended`) are unchanged.
+
+- [#114](https://github.com/next-friday/eslint-plugin-nextfriday/pull/114) [`7933269`](https://github.com/next-friday/eslint-plugin-nextfriday/commit/793326971cbbf15aaf2015f13622b7eff0fd51b2) Thanks [@joetakara](https://github.com/joetakara)! - `nextjs` and `nextjs/recommended` presets are now arrays of flat-config objects instead of a single object. The first object enables the rules; the second disables `nextfriday/jsx-pascal-case` for files matching `app/**/*.{jsx,tsx}`, `src/app/**/*.{jsx,tsx}`, `pages/**/*.{jsx,tsx}`, and `src/pages/**/*.{jsx,tsx}` — Next.js's official routing directories where filenames are owned by the framework (`page.tsx`, `layout.tsx`, `error.tsx`, etc.).
+
+  `base`, `base/recommended`, `react`, and `react/recommended` are unchanged — they remain single config objects and `jsx-pascal-case` is enforced everywhere when those presets are used.
+
+  The `jsx-pascal-case` rule itself no longer special-cases any filename or directory. Scope is expressed in the preset via ESLint's `files` glob, not via rule-internal allowlists. Consumers using `react`/`react/recommended` on a Next.js project must either switch to the `nextjs` preset or add their own `files`-scoped override.
+
+  Migration:
+
+  ```js
+  import nextfriday from "eslint-plugin-nextfriday";
+
+  export default [nextfriday.configs["nextjs/recommended"]];
+  ```
+
+  ESLint 9+ flattens nested config arrays automatically, so existing usage continues to work.
+
+### Patch Changes
+
+- [#114](https://github.com/next-friday/eslint-plugin-nextfriday/pull/114) [`7933269`](https://github.com/next-friday/eslint-plugin-nextfriday/commit/793326971cbbf15aaf2015f13622b7eff0fd51b2) Thanks [@joetakara](https://github.com/joetakara)! - Fix `enforce-constant-case` flagging conventional names in framework config files. The rule now skips entirely when run on `*.config.{ts,mjs,cjs,js}`, `*.rc.*`, `*.setup.*`, `*.spec.*`, `*.test.*`, `.eslintrc*`, `.babelrc*`, and `.prettierrc*`. Frameworks like Next.js require `nextConfig` in `next.config.ts`, Vite/Tailwind require `config`, etc. — these conventions can no longer be incorrectly flagged as needing `SCREAMING_SNAKE_CASE`.
+
 ## 2.0.0
 
 ### Major Changes

package/README.md

@@ -46,24 +46,49 @@ export default [nextfriday.configs.nextjs];
 export default [nextfriday.configs["nextjs/recommended"]];
 ```
 
-#### Bundled Plugin Configs
+### Extending a Preset with Rule Overrides
 
-Pre-configured configs for popular plugins. No extra install needed — they ship as dependencies. These configs are arrays, so use the spread operator (`...`) to merge them into your flat config.
+To use a preset and adjust individual rules, append a second config object after the preset. Later objects override earlier ones, so you can change severity, swap options, or add rules without re-declaring the entire preset.
+
+For example, enforce PascalCase for React components via the `react/recommended` preset (which already runs `nextfriday/jsx-pascal-case` and `nextfriday/enforce-camel-case` as errors), and add a rule override on top:
 
 ```js
 import nextfriday from "eslint-plugin-nextfriday";
 
-export default [nextfriday.configs["react/recommended"], ...nextfriday.configs.sonarjs, ...nextfriday.configs.unicorn];
+export default [
+  nextfriday.configs["react/recommended"],
+
+  {
+    rules: {
+      "nextfriday/jsx-pascal-case": "error",
+      "nextfriday/enforce-props-suffix": "error",
+      "nextfriday/sort-imports": "warn",
+    },
+  },
+];
 ```
 
-| Config    | Plugin                | Description                                                                                                |
-| --------- | --------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `sonarjs` | eslint-plugin-sonarjs | SonarJS recommended rules for bug detection and code quality                                               |
-| `unicorn` | eslint-plugin-unicorn | Unicorn recommended rules (with `filename-case` and `prevent-abbreviations` off, `no-null` off in JSX/TSX) |
+The first object enables every rule in `react/recommended`. The second object reaffirms `jsx-pascal-case` (already enforced — useful when you want it loud and explicit), enables `enforce-props-suffix`, and downgrades `sort-imports` from error to warning.
 
 ### Manual Configuration
 
-If you prefer to configure rules manually:
+#### When to use manual configuration vs a preset
+
+Reach for a preset (`base`, `react`, `nextjs`, or any `/recommended` variant) by default. Presets are curated, kept in sync with new rules as the plugin grows, and require almost no maintenance on your side.
+
+Choose manual configuration when one of these applies:
+
+| Scenario                                                                            | Why manual fits better                                                                                                              |
+| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| You only need a few specific rules                                                  | Presets enable the full set; manual lets you adopt rules one at a time.                                                             |
+| You want to opt out of new rules added in future plugin releases                    | Manual configs are explicit — new rules added to a preset would automatically apply, manual configs don't change without your edit. |
+| You're consolidating multiple ESLint plugins and want fine-grained per-rule control | Avoids preset rules conflicting with rules from other plugins.                                                                      |
+| You're building a higher-level shared config for your org                           | You can hand-pick exactly which NextFriday rules to bundle into your own preset.                                                    |
+| You're debugging a rule conflict                                                    | Manual makes the active rule set unambiguous.                                                                                       |
+
+For every other case — new projects, gradual adoption, library code, application code — start from a preset and use [Extending a Preset with Rule Overrides](#extending-a-preset-with-rule-overrides) when you need to adjust specific rules.
+
+#### Manual configuration example
 
 ```js
 import nextfriday from "eslint-plugin-nextfriday";
@@ -151,8 +176,230 @@ export default [
 
 > **Note:** This plugin requires ESLint 9+ and only supports the flat config format. Legacy `.eslintrc` configurations are not supported.
 
+### Per-Directory Configuration
+
+#### How ESLint flat config resolves rules
+
+Flat config (the only format this plugin supports) is an **array of config objects** evaluated in order. For every file ESLint lints, it walks the array and merges every object whose `files` glob matches and whose `ignores` glob does not. Later objects override earlier ones rule-by-rule, so the **last matching object wins** for any given rule. Objects with no `files` field apply globally; objects with only `ignores` at the top level remove files from the entire run.
+
+This is why per-directory configuration works: you stack a global default first, then layer narrower `files`-scoped objects on top. ESLint 9+ also flattens nested arrays automatically, so spreading a preset that ships as an array (like `nextfriday.configs.nextjs`) works the same as spreading a single object.
+
+The legacy `.eslintrc` format used `overrides` and an inheritance tree to express the same thing. Flat config replaces that tree with a flat, deterministic array — easier to reason about, no implicit merging across `extends`, and no `parserOptions` plumbing per directory. The plugin does not ship `.eslintrc` shims, so projects on ESLint 8 or below cannot consume it without upgrading.
+
+#### Layering strict and loose presets
+
+Apply different rule severities to different directories by stacking config objects:
+
+```js
+import nextfriday from "eslint-plugin-nextfriday";
+
+export default [
+  {
+    ignores: ["src/legacy/**", "dist/**", "build/**", "**/*.generated.ts"],
+  },
+
+  nextfriday.configs.react,
+
+  {
+    files: ["src/components/**/*.{ts,tsx}", "src/hooks/**/*.{ts,tsx}"],
+    ...nextfriday.configs["react/recommended"],
+  },
+
+  {
+    files: ["src/utils/**/*.ts", "src/lib/**/*.ts"],
+    rules: {
+      "nextfriday/require-explicit-return-type": "error",
+      "nextfriday/no-relative-imports": "error",
+    },
+  },
+
+  {
+    files: ["**/*.{test,spec}.{ts,tsx}"],
+    rules: {
+      "nextfriday/require-explicit-return-type": "off",
+      "nextfriday/no-single-char-variables": "off",
+      "nextfriday/no-direct-date": "off",
+    },
+  },
+];
+```
+
+Reading top to bottom:
+
+1. **Top-level `ignores`** removes legacy and build artifacts from the entire run. A config object containing _only_ `ignores` is treated as a global ignore — narrower `ignores` inside a `files`-scoped object only affect that object.
+2. **`nextfriday.configs.react`** applies as the warn-level baseline to every file ESLint sees (no `files` glob).
+3. **Component and hook directories** get promoted to `react/recommended` (errors). Because this object comes after the baseline, its severities win.
+4. **Utility directories** keep the warn-level baseline but selectively promote two correctness rules to `error`. Use this pattern when you don't want the full `/recommended` preset but do want specific rules treated as blocking.
+5. **Test files** keep most rules but turn off rules that conflict with common test patterns (single-letter loop counters, frozen `Date.now()` mocks, void-returning `it()` callbacks).
+
+#### Choosing a preset tier per directory
+
+| Code area                         | Suggested preset                            | Why                                                                        |
+| --------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------- |
+| Library / SDK code                | `base/recommended` or `react/recommended`   | Public surface should be tightest. `error` blocks regressions at PR time.  |
+| New product code                  | `react/recommended` or `nextjs/recommended` | New code starts clean; lock the conventions in immediately.                |
+| Mature product code mid-migration | `react` or `nextjs` (warn)                  | Ship while migrating. Switch to `/recommended` after a clean run.          |
+| Tests, scripts, fixtures          | preset + targeted overrides                 | Keep the core lint signal; turn off rules that mismatch test/CLI patterns. |
+| Legacy / vendored / generated     | top-level `ignores`                         | No lint signal at all. Don't waste reviewer attention or CI time.          |
+
+#### Edge cases and troubleshooting
+
+- **Glob precedence is order-dependent, not specificity-based.** A more specific glob later in the array wins; a more specific glob _earlier_ in the array does not. If `files: ["src/**"]` appears after `files: ["src/components/**"]`, the broader rule set wins for components. Put broader configs first.
+- **`files` and `ignores` are anchored to the project root** (the directory containing `eslint.config.{js,mjs,ts}`), not the file's directory. Use `**/` prefixes for matches anywhere in the tree (e.g., `**/*.test.ts`).
+- **Top-level `ignores` ≠ `ignores` inside a config object.** A standalone object `{ ignores: [...] }` removes files from the entire run; an `ignores` field next to `files` and `rules` only narrows that one config object's match.
+- **Spreading a preset replaces, not merges, the `plugins` field.** If you spread `...nextfriday.configs.react` and then a different config later, the later object's `plugins` wins. Re-declare `plugins: { nextfriday }` if you add rules in a later object.
+- **`nextfriday.configs.nextjs` is an array, not a single object.** Spreading it inline with `...nextfriday.configs.nextjs` only spreads array indices, not the inner objects. Use it as an array entry (`nextfriday.configs.nextjs,`) instead, so ESLint 9+ flattens it.
+- **Two presets in one project.** Use scoped `files` rather than two unscoped presets — unscoped presets stack and the later one's rule severities win for every file, which is rarely what you want.
+- **Verifying the resolved config for a file:** `pnpm eslint --print-config path/to/file.tsx` prints the merged config ESLint would actually use. Reach for this when a rule fires (or doesn't) and you can't tell why.
+
+### Migration Strategy
+
+For an existing codebase with many violations, treat the migration as a phased rollout — survey, fix, lock in, repeat.
+
+#### 1. Survey violations before changing anything
+
+Install the plugin as a dev dependency, drop a warn-level preset into `eslint.config.mjs`, and run a read-only lint. Don't `--fix` yet — you want to see the raw shape of the codebase first.
+
+```bash
+pnpm add -D eslint-plugin-nextfriday eslint
+pnpm eslint . --no-fix
+```
+
+Group violations by rule so you can plan the work. Most CI dashboards do this for you, but a one-liner works locally:
+
+```bash
+pnpm eslint . --no-fix --format json | jq -r '.[].messages[].ruleId' | sort | uniq -c | sort -rn
+```
+
+The output tells you which rules account for most of the noise. A rule with 3 violations is a 10-minute fix; a rule with 800 is a multi-week project. Plan accordingly.
+
+#### 2. Run the auto-fixers in an isolated PR
+
+Roughly a third of this plugin's rules are auto-fixable (the `Fixable ✅` column in the [Rules](#rules) table). Run them in a dedicated commit so the diff is purely mechanical and reviewers don't have to read every line:
+
+```bash
+pnpm eslint . --fix
+git add -u && git commit -m "style(lint): autofix nextfriday rules"
+```
+
+Open this as its own PR. Mixing auto-fix output with hand-written changes in the same diff makes review almost impossible.
+
+#### 3. Adopt the warn-level preset
+
+After the auto-fix pass, drop in the warn-level preset so the remaining violations surface during local dev and CI without breaking the build:
+
+```js
+import nextfriday from "eslint-plugin-nextfriday";
+
+export default [nextfriday.configs.react];
+```
+
+Warnings don't fail `eslint --max-warnings=0`, so add that flag in CI only when you're ready to block on warnings. Until then, warnings are visible signal without pressure.
+
+#### 4. Lock in clean directories one at a time
+
+As individual directories or features reach zero violations, promote them to `/recommended` (errors) so regressions block at PR time. Everything else stays on the warn-level preset.
+
+```js
+import nextfriday from "eslint-plugin-nextfriday";
+
+export default [
+  nextfriday.configs.react,
+
+  {
+    files: ["src/components/v2/**/*.{ts,tsx}", "src/lib/**/*.ts"],
+    ...nextfriday.configs["react/recommended"],
+  },
+];
+```
+
+Repeat per directory. This is how you ratchet without flag-day rewrites.
+
+#### 5. Manage exceptions explicitly
+
+Three ways to carve out an exception, in order of preference. Pick the narrowest one that solves the problem.
+
+**Per-rule severity override** — turn off a single noisy rule globally until you can fix it at the codebase level:
+
+```js
+export default [
+  nextfriday.configs["react/recommended"],
+
+  {
+    rules: {
+      "nextfriday/require-explicit-return-type": "warn",
+      "nextfriday/sort-imports": "off",
+    },
+  },
+];
+```
+
+**Per-directory exception** — keep the rule strict everywhere except one stubborn corner:
+
+```js
+export default [
+  nextfriday.configs["react/recommended"],
+
+  {
+    files: ["src/legacy/**/*.{ts,tsx}"],
+    rules: {
+      "nextfriday/no-relative-imports": "off",
+      "nextfriday/enforce-camel-case": "off",
+    },
+  },
+];
+```
+
+**Per-file or per-line disable comments** — last resort, for genuinely irreducible cases:
+
+```ts
+// eslint-disable-next-line nextfriday/no-direct-date
+const epochAnchor = new Date(0);
+
+/* eslint-disable nextfriday/no-emoji */
+export const FLAG_EMOJIS = ["🇹🇭", "🇯🇵", "🇺🇸"];
+/* eslint-enable nextfriday/no-emoji */
+```
+
+Always disable a _named_ rule, never blanket-disable ESLint. A blanket `// eslint-disable` mutes every rule including correctness ones, so legitimate bugs slip through later.
+
+**Skip vendored or generated files entirely** with a top-level ignore — these aren't exceptions to manage, they're code you don't lint at all:
+
+```js
+export default [
+  {
+    ignores: ["dist/**", "build/**", "coverage/**", "**/*.generated.ts"],
+  },
+
+  nextfriday.configs["react/recommended"],
+];
+```
+
+#### 6. Track progress so the migration actually lands
+
+Migrations stall when nobody can see how close you are. Two cheap signals:
+
+- **Violation count over time.** Pipe `pnpm eslint . --no-fix --format compact | wc -l` into your CI metrics or a daily Slack post. Trend it weekly. If the number stops dropping, the migration has stalled.
+- **Verify a single file's resolved config.** When a contributor asks "why did this rule fire on my file?", run `pnpm eslint --print-config path/to/file.tsx`. The output shows exactly which severity ESLint resolved for every rule on that file — usually answers the question in seconds.
+
+Once a directory hits zero, lock it in (step 4). Once the warn-level count hits zero across the whole repo, switch the global preset to `/recommended` and add `--max-warnings=0` to CI. The migration is done.
+
+#### Prioritize rules by impact
+
+When the warn-level preset surfaces hundreds of violations, fix them in this order — high-impact rules catch real bugs, while low-impact rules are style preferences that can wait.
+
+| Tier                                  | Examples                                                                                                                                                                           | Why first                                                                                                                       |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| High — correctness and runtime safety | `no-direct-date`, `no-env-fallback`, `nextjs-require-public-env`, `enforce-readonly-component-props`, `jsx-no-non-component-function`, `enforce-hook-naming`, `no-logic-in-params` | Each violation can mask a bug, leak config, or break React's rules of hooks. Fix before they ship.                              |
+| Medium — structure and naming         | `boolean-naming-prefix`, `enforce-camel-case`, `enforce-constant-case`, `file-kebab-case`, `jsx-pascal-case`, `enforce-props-suffix`, `prefer-import-type`                         | No runtime impact, but inconsistent naming compounds review and onboarding cost. Fix once the high tier is clean.               |
+| Low — formatting and ordering         | `sort-imports`, `sort-exports`, `sort-type-alphabetically`, `jsx-sort-props`, `newline-before-return`, `newline-after-multiline-block`, `no-emoji`                                 | Cosmetic. Most are auto-fixable, so a single `pnpm eslint --fix` pass typically clears the whole codebase. Save these for last. |
+
+In practice: turn the high tier on as `"error"` first, leave the medium tier as `"warn"` while you migrate, and run the auto-fixers for the low tier in a single dedicated PR.
+
 ## Rules
 
+> All rules in this plugin have no configurable options (`schema: []`). The only knob is severity — set each rule to `"error"`, `"warn"`, or `"off"`. Behavior is intentionally fixed so that the same rule means the same thing across every project.
+
 ### Variable Naming Rules
 
 | Rule                                                                     | Description                                                           | Fixable |
@@ -253,10 +500,12 @@ export default [
 | -------------------- | -------- | ---------- | --------- | ------------- | ----------- |
 | `base`               | warn     | 40         | 0         | 0             | 40          |
 | `base/recommended`   | error    | 40         | 0         | 0             | 40          |
-| `react`              | warn     | 40         | 15        | 0             | 55          |
-| `react/recommended`  | error    | 40         | 15        | 0             | 55          |
-| `nextjs`             | warn     | 40         | 15        | 1             | 56          |
-| `nextjs/recommended` | error    | 40         | 15        | 1             | 56          |
+| `react`              | warn     | 40         | 16        | 0             | 56          |
+| `react/recommended`  | error    | 40         | 16        | 0             | 56          |
+| `nextjs`             | warn     | 40         | 16        | 1             | 57          |
+| `nextjs/recommended` | error    | 40         | 16        | 1             | 57          |
+
+The `nextjs` and `nextjs/recommended` presets ship as an array of two flat-config objects: the rule set above, plus a routing override that disables `nextfriday/file-kebab-case` and `nextfriday/jsx-pascal-case` for files matching `app/**/*.{js,jsx,ts,tsx}`, `src/app/**/*.{js,jsx,ts,tsx}`, `pages/**/*.{js,jsx,ts,tsx}`, and `src/pages/**/*.{js,jsx,ts,tsx}`. Next.js owns the filenames in those directories (`page.tsx`, `layout.tsx`, `route.ts`, `middleware.ts`, etc.), so the plugin steps out of the way. ESLint 9+ flattens nested config arrays automatically, so spreading the preset works as expected.
 
 ### Base Configuration Rules (40 rules)
 

package/docs/rules/BOOLEAN_NAMING_PREFIX.md

@@ -80,6 +80,19 @@ The rule identifies boolean variables and parameters by:
 | `does`   | Action capability             | `doesExist`, `doesMatch`, `doesContain`       |
 | `had`    | Past possession               | `hadError`, `hadAccess`, `hadPrevious`        |
 
+## Not Checked
+
+To keep the rule unobtrusive on patterns that are usually shaped by external APIs or framework conventions, these locations are intentionally ignored:
+
+- **Class methods, getters, and setters.** `class Foo { get valid() {...} }` and `class Foo { set valid(v) {...} }` are not checked.
+- **Class fields (property definitions).** `class Foo { valid = true }` is not checked.
+- **Object literal properties.** `{ valid: true }` and `{ open: true, closed: false }` are not checked. Object keys often mirror an external schema (API responses, config payloads, DB rows) where renaming would be incorrect.
+- **Computed property names.** `{ [key]: true }` is not checked because the name is dynamic.
+- **Destructuring patterns.** `const { valid } = result;` is not checked — rename at the source instead, or use a destructuring alias (`const { valid: isValid } = result;`).
+- **Property access.** `if (user.valid) {}` is not checked.
+
+If you need stricter coverage of object/class members, pair this rule with [`@typescript-eslint/naming-convention`](https://typescript-eslint.io/rules/naming-convention/), which can target `classProperty`, `objectLiteralProperty`, `accessor`, and other selectors with custom prefix patterns.
+
 ## When Not To Use It
 
 - When working with external APIs that return boolean fields with different naming conventions

package/docs/rules/ENFORCE_CONSTANT_CASE.md

@@ -8,6 +8,8 @@ This rule ensures that global-scope `const` declarations with static values use
 
 Only global scope (top-level of a file) is checked. Local scope constants inside functions are not checked by this rule.
 
+**Config files are exempt.** Files matching `*.config.{ts,mjs,cjs,js}`, `*.rc.*`, `*.setup.*`, `*.spec.*`, `*.test.*`, `.eslintrc*`, `.babelrc*`, and `.prettierrc*` skip this rule entirely. This avoids conflicts with framework conventions that require specific identifier names — e.g. Next.js expects `nextConfig` (not `NEXT_CONFIG`) in `next.config.ts`, Vite expects `config`, Tailwind expects `config`, etc.
+
 ## Examples
 
 ### Incorrect
@@ -54,6 +56,97 @@ function foo() {
 }
 ```
 
+## Configuration
+
+This rule has no options — only severity is configurable (`"error"`, `"warn"`, `"off"`). It pairs with [`no-misleading-constant-case`](./NO_MISLEADING_CONSTANT_CASE.md) so that static globals use `SCREAMING_SNAKE_CASE` while local scopes and dynamic values keep `camelCase`.
+
+### Install
+
+```bash
+pnpm add -D eslint-plugin-nextfriday eslint
+# npm install --save-dev eslint-plugin-nextfriday eslint
+# yarn add --dev eslint-plugin-nextfriday eslint
+```
+
+### Enable just this rule
+
+Use this when you want the rule but not the rest of the preset (e.g., adopting one rule at a time during a migration). The `plugins` field registers the plugin under the `nextfriday` namespace; the `rules` field turns on the rule by name:
+
+```js
+import nextfriday from "eslint-plugin-nextfriday";
+
+export default [
+  {
+    plugins: { nextfriday },
+    rules: {
+      "nextfriday/enforce-constant-case": "error",
+    },
+  },
+];
+```
+
+### Enable with related rules
+
+Constants, locals, and dynamic values each need a different naming convention. Enable the trio together so violations from any direction surface:
+
+```js
+import nextfriday from "eslint-plugin-nextfriday";
+
+export default [
+  {
+    plugins: { nextfriday },
+    rules: {
+      "nextfriday/enforce-constant-case": "error",
+      "nextfriday/no-misleading-constant-case": "error",
+      "nextfriday/enforce-camel-case": "error",
+    },
+  },
+];
+```
+
+### Enable via a preset
+
+Every preset includes this rule at the preset's severity (`warn` or `error`). This is the simplest setup and the recommended one for most projects:
+
+```js
+import nextfriday from "eslint-plugin-nextfriday";
+
+export default [nextfriday.configs["base/recommended"]];
+```
+
+### Scope to a directory
+
+If you're migrating an existing codebase, scope the rule to a clean directory first and leave the rest of the project on `"warn"` until you've fixed the violations there. ESLint 9+ flat config layers configs in array order; the later object's severity wins for any file matching its `files` glob:
+
+```js
+import nextfriday from "eslint-plugin-nextfriday";
+
+export default [
+  nextfriday.configs.base,
+
+  {
+    files: ["src/config/**/*.ts", "src/lib/**/*.ts"],
+    rules: {
+      "nextfriday/enforce-constant-case": "error",
+    },
+  },
+];
+```
+
+### Severity-only — no rule options
+
+Each rule in this plugin uses `schema: []` and `defaultOptions: []` (no options). The flat-config value is **only** the severity string — `"error"`, `"warn"`, or `"off"`. The legacy `["error", { ... }]` array form is not accepted because there are no options to pass.
+
+```js
+// Correct
+"nextfriday/enforce-constant-case": "error"
+
+// Won't apply — there are no options to override
+"nextfriday/enforce-constant-case": ["error", { allowCamelCase: true }]
+```
+
+This plugin only supports ESLint 9+ flat config — legacy `.eslintrc` is not supported. Projects on ESLint 8 or below cannot consume it without upgrading.
+
 ## When Not To Use It
 
 - If your project uses different naming conventions for constants

package/docs/rules/FILE_KEBAB_CASE.md

@@ -28,6 +28,43 @@ This rule enforces that all TypeScript (.ts) and JavaScript (.js) files use keba
 - `user-service.ts`
 - `api-utils.ts`
 
+## Allowed Patterns and Edge Cases
+
+- **Only `.ts` and `.js` are checked.** `.tsx` and `.jsx` files are ignored — use [`jsx-pascal-case`](./JSX_PASCAL_CASE.md) for React component filenames.
+- **Compound extensions are allowed when each segment is kebab-case.** Both the basename and the trailing token before the file extension are validated independently. This pattern is useful for config, setup, spec, test, and rc files:
+  - `next.config.ts` ✓
+  - `vitest.setup.ts` ✓
+  - `user-service.test.ts` ✓
+  - `auth.spec.ts` ✓
+  - `eslint.rc.ts` ✓
+- **Numbers are allowed inside segments.** `file-with-numbers-123.ts` ✓
+- **Single-word filenames are valid.** `single.ts` ✓ (no hyphens needed)
+
+## Scoping the Rule
+
+This rule has **no built-in framework detection**. It checks every `.ts`/`.js` file it sees against kebab-case. In Next.js projects, routing directories (`app/`, `pages/`) contain framework-named files (`route.ts`, `middleware.ts`) that already happen to be kebab-case — but if you colocate helpers there with non-kebab names (`useThing.ts`, `MyHelper.ts`), the rule will flag them.
+
+The `nextjs` and `nextjs/recommended` presets ship with an override that **automatically disables this rule** for files under `app/**`, `src/app/**`, `pages/**`, and `src/pages/**` (matched against `*.{js,jsx,ts,tsx}`). Filename conventions in those directories are owned by the framework, not by this plugin. The `base` and `react` presets do **not** include this override — they enforce `file-kebab-case` on every `.ts`/`.js` regardless of directory.
+
+## Disabling the Rule
+
+To opt out for additional directories or file patterns, add an override in your flat config:
+
+```js
+import nextfriday from "eslint-plugin-nextfriday";
+
+export default [
+  nextfriday.configs["base/recommended"],
+
+  {
+    files: ["src/legacy/**/*.ts", "src/vendor/**/*.js"],
+    rules: {
+      "nextfriday/file-kebab-case": "off",
+    },
+  },
+];
+```
+
 ## When Not To Use It
 
 If your project has established naming conventions that conflict with kebab-case, or if you're working with frameworks that require specific filename patterns, you may want to disable this rule.

package/docs/rules/JSX_PASCAL_CASE.md

@@ -28,6 +28,40 @@ This rule enforces that JSX and TSX files use PascalCase naming convention for t
 - `LoginForm.tsx`
 - `UserProfile2.jsx` (PascalCase with numbers)
 
+## Scoping the Rule
+
+This rule has **no built-in framework detection** and no allowlist of "known" filenames. It checks every `.jsx`/`.tsx` it sees against PascalCase.
+
+The `nextjs` and `nextjs/recommended` presets ship with an override that **automatically disables this rule** for files under `app/**`, `src/app/**`, `pages/**`, and `src/pages/**` — Next.js owns those filenames (`page.tsx`, `layout.tsx`, `error.tsx`, etc.). If you use a `nextjs` preset, you do not need to add a routing override yourself.
+
+The `base` and `react` presets do **not** include this override. If you use `react` on a Next.js project (or any project that mixes PascalCase component files with lowercase framework routing files), scope the rule explicitly via ESLint's `files` glob:
+
+```js
+import nextfriday from "eslint-plugin-nextfriday";
+
+export default [
+  nextfriday.configs.react,
+
+  {
+    files: ["src/components/**/*.{jsx,tsx}", "components/**/*.{jsx,tsx}"],
+    rules: {
+      "nextfriday/jsx-pascal-case": "error",
+    },
+  },
+
+  {
+    files: ["src/app/**/*.{jsx,tsx}", "app/**/*.{jsx,tsx}", "src/pages/**/*.{jsx,tsx}", "pages/**/*.{jsx,tsx}"],
+    rules: {
+      "nextfriday/jsx-pascal-case": "off",
+    },
+  },
+];
+```
+
+The first override turns the rule on only inside component directories where PascalCase is the convention. The second override explicitly disables the rule for Next.js routing directories where the framework owns the filename.
+
+The plugin deliberately does not try to detect Next.js, Remix, or other framework conventions outside of the `nextjs` preset — folder structures vary across projects (monorepos, custom `app` locations, hybrid Pages + App Router setups), and a built-in allowlist would inevitably go stale. ESLint's `files` glob is the deterministic way to express the scope you actually want.
+
 ## When Not To Use It
 
 If your project uses different naming conventions for JSX/TSX files, you can disable this rule.