eslint-plugin-nextfriday 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # 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

package/README.md

@@ -178,44 +178,115 @@ export default [
 
 ### Per-Directory Configuration
 
-ESLint flat config is an array of config objects. Each object's `files` and `ignores` glob patterns scope its rules to a subset of the project. Use this to apply different rule severities to different directories.
+#### 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 [
   {
-    files: ["src/components/**/*.{ts,tsx}"],
-    ...nextfriday.configs["react/recommended"],
+    ignores: ["src/legacy/**", "dist/**", "build/**", "**/*.generated.ts"],
   },
 
+  nextfriday.configs.react,
+
   {
-    files: ["src/utils/**/*.ts"],
-    ...nextfriday.configs.base,
+    files: ["src/components/**/*.{ts,tsx}", "src/hooks/**/*.{ts,tsx}"],
+    ...nextfriday.configs["react/recommended"],
   },
 
   {
-    files: ["src/legacy/**/*.{ts,tsx}"],
-    ignores: ["src/legacy/**/*"],
+    files: ["src/utils/**/*.ts", "src/lib/**/*.ts"],
+    rules: {
+      "nextfriday/require-explicit-return-type": "error",
+      "nextfriday/no-relative-imports": "error",
+    },
   },
 
   {
-    files: ["**/*.test.{ts,tsx}"],
+    files: ["**/*.{test,spec}.{ts,tsx}"],
     rules: {
       "nextfriday/require-explicit-return-type": "off",
       "nextfriday/no-single-char-variables": "off",
+      "nextfriday/no-direct-date": "off",
     },
   },
 ];
 ```
 
-The first config block applies the strict `react/recommended` preset (errors) to component files. The second applies the looser `base` preset (warnings) to utilities. The third excludes legacy code from linting entirely. The fourth keeps lint enabled for tests but turns off rules that conflict with common test patterns.
+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, enable rules gradually instead of all at once. Three patterns, in order of how disruptive each is to your team:
+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
 
-**1. Start with the warn-level preset.** All rules surface as warnings, so the build still passes. Fix issues at your own pace, then switch to `/recommended`.
+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";
@@ -223,7 +294,11 @@ import nextfriday from "eslint-plugin-nextfriday";
 export default [nextfriday.configs.react];
 ```
 
-**2. Lock-in a clean directory at a time.** Use `files` to apply `/recommended` (errors) only where the code is already clean, and the warn-level preset everywhere else.
+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";
@@ -238,11 +313,15 @@ export default [
 ];
 ```
 
-**3. Disable individual rules until the codebase is ready.** Re-declare specific rules with a lower severity (or `"off"`) after spreading the preset. Useful when one rule produces too much noise to fix at once.
+Repeat per directory. This is how you ratchet without flag-day rewrites.
 
-```js
-import nextfriday from "eslint-plugin-nextfriday";
+#### 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"],
 
@@ -255,14 +334,56 @@ export default [
 ];
 ```
 
-Pair these with `ignores` to skip vendored or generated files entirely:
+**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
-{
-  ignores: ["dist/**", "build/**", "**/*.generated.ts"],
-}
+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.
@@ -379,10 +500,12 @@ In practice: turn the high tier on as `"error"` first, leave the medium tier as
 | -------------------- | -------- | ---------- | --------- | ------------- | ----------- |
 | `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/ENFORCE_CONSTANT_CASE.md

@@ -58,7 +58,36 @@ function foo() {
 
 ## Configuration
 
-This rule 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`. ESLint 9+ flat config:
+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";
@@ -75,7 +104,9 @@ export default [
 ];
 ```
 
-Or via a preset (every preset already enables all three at the configured severity):
+### 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";
@@ -83,7 +114,38 @@ import nextfriday from "eslint-plugin-nextfriday";
 export default [nextfriday.configs["base/recommended"]];
 ```
 
-This plugin only supports ESLint 9+ flat config — legacy `.eslintrc` is not supported.
+### 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
 

package/docs/rules/FILE_KEBAB_CASE.md

@@ -40,9 +40,15 @@ This rule enforces that all TypeScript (.ts) and JavaScript (.js) files use keba
 - **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 a specific directory or file pattern, add an override in your flat config:
+To opt out for additional directories or file patterns, add an override in your flat config:
 
 ```js
 import nextfriday from "eslint-plugin-nextfriday";

package/docs/rules/JSX_PASCAL_CASE.md

@@ -30,7 +30,11 @@ This rule enforces that JSX and TSX files use PascalCase naming convention for t
 
 ## Scoping the Rule
 
-This rule has **no built-in framework detection** and no allowlist of "known" filenames. It checks every `.jsx`/`.tsx` it sees. If your project mixes component files with framework routing files that use lowercase names (e.g. Next.js App Router `page.tsx`, `layout.tsx`, `error.tsx`, or Pages Router `_app.tsx`), scope the rule explicitly via ESLint's `files` glob in flat config:
+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";
@@ -56,7 +60,7 @@ export default [
 
 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 automatically — 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.
+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
 

package/lib/index.cjs

@@ -40,7 +40,7 @@ module.exports = __toCommonJS(index_exports);
 // package.json
 var package_default = {
   name: "eslint-plugin-nextfriday",
-  version: "3.0.0",
+  version: "3.1.0",
   description: "A comprehensive ESLint plugin providing custom rules and configurations for Next Friday development workflows.",
   keywords: [
     "eslint",
@@ -4747,14 +4747,15 @@ var createConfig = (configRules) => ({
   rules: configRules
 });
 var NEXTJS_ROUTING_GLOBS = [
-  "app/**/*.{jsx,tsx}",
-  "src/app/**/*.{jsx,tsx}",
-  "pages/**/*.{jsx,tsx}",
-  "src/pages/**/*.{jsx,tsx}"
+  "app/**/*.{js,jsx,ts,tsx}",
+  "src/app/**/*.{js,jsx,ts,tsx}",
+  "pages/**/*.{js,jsx,ts,tsx}",
+  "src/pages/**/*.{js,jsx,ts,tsx}"
 ];
 var nextjsRoutingOverride = {
   files: NEXTJS_ROUTING_GLOBS,
   rules: {
+    "nextfriday/file-kebab-case": "off",
     "nextfriday/jsx-pascal-case": "off"
   }
 };