eslint-plugin-nextfriday 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # eslint-plugin-nextfriday
 
+## 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,109 @@ export default [
 
 > **Note:** This plugin requires ESLint 9+ and only supports the flat config format. Legacy `.eslintrc` configurations are not supported.
 
+### 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.
+
+```js
+import nextfriday from "eslint-plugin-nextfriday";
+
+export default [
+  {
+    files: ["src/components/**/*.{ts,tsx}"],
+    ...nextfriday.configs["react/recommended"],
+  },
+
+  {
+    files: ["src/utils/**/*.ts"],
+    ...nextfriday.configs.base,
+  },
+
+  {
+    files: ["src/legacy/**/*.{ts,tsx}"],
+    ignores: ["src/legacy/**/*"],
+  },
+
+  {
+    files: ["**/*.test.{ts,tsx}"],
+    rules: {
+      "nextfriday/require-explicit-return-type": "off",
+      "nextfriday/no-single-char-variables": "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.
+
+### 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:
+
+**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`.
+
+```js
+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.
+
+```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"],
+  },
+];
+```
+
+**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.
+
+```js
+import nextfriday from "eslint-plugin-nextfriday";
+
+export default [
+  nextfriday.configs["react/recommended"],
+
+  {
+    rules: {
+      "nextfriday/require-explicit-return-type": "warn",
+      "nextfriday/sort-imports": "off",
+    },
+  },
+];
+```
+
+Pair these with `ignores` to skip vendored or generated files entirely:
+
+```js
+{
+  ignores: ["dist/**", "build/**", "**/*.generated.ts"],
+}
+```
+
+#### 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 |

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,35 @@ 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:
+
+```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",
+    },
+  },
+];
+```
+
+Or via a preset (every preset already enables all three at the configured severity):
+
+```js
+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.
+
 ## When Not To Use It
 
 - If your project uses different naming conventions for constants

package/docs/rules/FILE_KEBAB_CASE.md

@@ -28,6 +28,37 @@ 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)
+
+## Disabling the Rule
+
+To opt out for a specific directory or file pattern, 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,36 @@ 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. 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:
+
+```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 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.
+
 ## When Not To Use It
 
 If your project uses different naming conventions for JSX/TSX files, you can disable this rule.