eslint-plugin-nextfriday 4.2.0 → 4.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # eslint-plugin-nextfriday
 
+## 4.3.0
+
+### Minor Changes
+
+- [#128](https://github.com/next-friday/eslint-plugin-nextfriday/pull/128) [`b165ec5`](https://github.com/next-friday/eslint-plugin-nextfriday/commit/b165ec51eb3ec870a546ab808821426186543356) Thanks [@joetakara](https://github.com/joetakara)! - add enforce-hook-filename, enforce-test-filename, no-helper-function-in-hook, no-helper-function-in-test rules
+
 ## 4.2.0
 
 ### Minor Changes

package/README.md

@@ -413,6 +413,8 @@ In practice: turn the high tier on as `"error"` first, leave the medium tier as
 | [require-explicit-return-type](docs/rules/REQUIRE_EXPLICIT_RETURN_TYPE.md)   | Require explicit return types on functions for better documentation    | ❌      |
 | [no-complex-inline-return](docs/rules/NO_COMPLEX_INLINE_RETURN.md)           | Disallow complex inline expressions in return - extract to const first | ❌      |
 | [no-logic-in-params](docs/rules/NO_LOGIC_IN_PARAMS.md)                       | Disallow logic/conditions in function parameters - extract to const    | ❌      |
+| [enforce-hook-filename](docs/rules/ENFORCE_HOOK_FILENAME.md)                 | Enforce that files exporting custom hooks are named \*.hook.ts         | ❌      |
+| [enforce-test-filename](docs/rules/ENFORCE_TEST_FILENAME.md)                 | Enforce that files containing test code are named \*.test.ts           | ❌      |
 | [enforce-hook-naming](docs/rules/ENFORCE_HOOK_NAMING.md)                     | Enforce 'use' prefix for functions in \*.hook.ts files                 | ❌      |
 | [enforce-service-naming](docs/rules/ENFORCE_SERVICE_NAMING.md)               | Enforce 'fetch' prefix for async functions in \*.service.ts files      | ❌      |
 | [enforce-sorted-destructuring](docs/rules/ENFORCE_SORTED_DESTRUCTURING.md)   | Enforce alphabetical sorting of destructured properties                | ✅      |
@@ -427,6 +429,8 @@ In practice: turn the high tier on as `"error"` first, leave the medium tier as
 | [prefer-async-await](docs/rules/PREFER_ASYNC_AWAIT.md)                       | Enforce async/await over .then() promise chains                        | ❌      |
 | [no-nested-ternary](docs/rules/NO_NESTED_TERNARY.md)                         | Disallow nested ternary expressions                                    | ❌      |
 | [prefer-guard-clause](docs/rules/PREFER_GUARD_CLAUSE.md)                     | Enforce guard clause pattern instead of nested if statements           | ❌      |
+| [no-helper-function-in-hook](docs/rules/NO_HELPER_FUNCTION_IN_HOOK.md)       | Disallow non-hook helper function definitions in hook files            | ❌      |
+| [no-helper-function-in-test](docs/rules/NO_HELPER_FUNCTION_IN_TEST.md)       | Disallow helper function definitions in test files                     | ❌      |
 
 ### Import Optimization Rules
 
@@ -485,23 +489,25 @@ In practice: turn the high tier on as `"error"` first, leave the medium tier as
 
 | Preset               | Severity | Base Rules | JSX Rules | Total Rules |
 | -------------------- | -------- | ---------- | --------- | ----------- |
-| `base`               | warn     | 40         | 0         | 40          |
-| `base/recommended`   | error    | 40         | 0         | 40          |
-| `react`              | warn     | 40         | 23        | 63          |
-| `react/recommended`  | error    | 40         | 23        | 63          |
-| `nextjs`             | warn     | 40         | 23        | 63          |
-| `nextjs/recommended` | error    | 40         | 23        | 63          |
+| `base`               | warn     | 42         | 0         | 42          |
+| `base/recommended`   | error    | 42         | 0         | 42          |
+| `react`              | warn     | 42         | 23        | 65          |
+| `react/recommended`  | error    | 42         | 23        | 65          |
+| `nextjs`             | warn     | 42         | 23        | 65          |
+| `nextjs/recommended` | error    | 42         | 23        | 65          |
 
 The `nextjs` and `nextjs/recommended` presets currently share the same rule set as `react` and `react/recommended`; they are kept as named aliases for ergonomics.
 
-### Base Configuration Rules (40 rules)
+### Base Configuration Rules (42 rules)
 
 Included in `base`, `base/recommended`, and all other presets:
 
 - `nextfriday/boolean-naming-prefix`
 - `nextfriday/enforce-camel-case`
 - `nextfriday/enforce-constant-case`
+- `nextfriday/enforce-hook-filename`
 - `nextfriday/enforce-hook-naming`
+- `nextfriday/enforce-test-filename`
 - `nextfriday/enforce-property-case`
 - `nextfriday/enforce-service-naming`
 - `nextfriday/enforce-sorted-destructuring`

package/docs/rules/ENFORCE_HOOK_FILENAME.md

@@ -0,0 +1,77 @@
+# enforce-hook-filename
+
+Enforce that files exporting custom hooks are named `*.hook.ts` or `*.hooks.ts`.
+
+## Rule Details
+
+Any file that exports a custom hook (a function whose name starts with `use` followed by an uppercase letter) must have a `.hook.ts` or `.hooks.ts` suffix. This ensures hook files are consistently discoverable and that `no-helper-function-in-hook` can be reliably scoped to them.
+
+### Why?
+
+Without enforced naming, hooks can silently live inside service files, utility files, or component files — breaking the `files` glob that powers `no-helper-function-in-hook` and making codebases harder to navigate.
+
+## Examples
+
+### Incorrect
+
+```ts
+// use-user-data.ts ❌
+export function useUserData() {
+  return null;
+}
+```
+
+```ts
+// user.service.ts ❌
+export const useCurrentUser = () => null;
+```
+
+```ts
+// UserCard.tsx ❌
+export function useUserCard() {
+  return null;
+}
+```
+
+### Correct
+
+```ts
+// use-user-data.hook.ts ✅
+export function useUserData() {
+  return null;
+}
+```
+
+```ts
+// user.hooks.ts ✅
+export const useCurrentUser = () => null;
+```
+
+Re-exporting from an index file is fine — only the file that defines the hook must follow the naming convention:
+
+```ts
+// index.ts ✅
+export { useUserData } from "./use-user-data.hook";
+```
+
+## What This Rule Checks
+
+- `export function useFoo()` — named function declaration export
+- `export const useFoo = () =>` — arrow function export
+- `export const useFoo = function()` — function expression export
+- `export default function useFoo()` — default function declaration export
+
+A name is treated as a hook only when it starts with `use` followed by an uppercase letter (e.g. `useData`, not `user` or `use`).
+
+## Exceptions
+
+Files already named `*.hook.ts` or `*.hooks.ts` are skipped entirely. Re-exports (`export { useFoo } from "..."`) are not flagged.
+
+## When Not To Use It
+
+Disable per-file if you intentionally co-locate a small hook with its only consumer and do not plan to reuse it.
+
+## Related Rules
+
+- [enforce-hook-naming](./ENFORCE_HOOK_NAMING.md) — enforces the `use` prefix on functions inside hook files
+- [no-helper-function-in-hook](./NO_HELPER_FUNCTION_IN_HOOK.md) — disallows non-hook helpers inside hook files

package/docs/rules/ENFORCE_TEST_FILENAME.md

@@ -0,0 +1,61 @@
+# enforce-test-filename
+
+Enforce that files containing test code are named `*.test.ts` or `*.test.tsx`.
+
+## Rule Details
+
+Any file that calls test runner globals (`describe`, `it`, `test`, `beforeEach`, `beforeAll`, `afterEach`, `afterAll`) must have a `.test.ts` or `.test.tsx` suffix. Files named `*.spec.ts` or any other pattern are not allowed.
+
+### Why?
+
+Consistent naming makes test files predictable to find and reliable to target with `files` globs in ESLint configs (e.g. `no-helper-function-in-test`). Mixing `.spec.ts` and `.test.ts` breaks glob-based scoping.
+
+## Examples
+
+### Incorrect
+
+```ts
+// user.spec.ts ❌
+describe("user", () => {
+  it("works", () => {});
+});
+```
+
+```ts
+// user-tests.ts ❌
+it("works", () => {});
+```
+
+### Correct
+
+```ts
+// user.test.ts ✅
+describe("user", () => {
+  it("works", () => {});
+});
+```
+
+```ts
+// UserCard.test.tsx ✅
+test("renders", () => {});
+```
+
+## What This Rule Checks
+
+Files that contain calls to any of the following globals trigger the requirement:
+
+`describe`, `it`, `test`, `beforeEach`, `beforeAll`, `afterEach`, `afterAll`
+
+Only one error is reported per file regardless of how many test calls are present.
+
+## Exceptions
+
+Files already named `*.test.ts` or `*.test.tsx` are skipped entirely.
+
+## When Not To Use It
+
+Disable if your project intentionally uses `.spec.ts` as the test file convention.
+
+## Related Rules
+
+- [no-helper-function-in-test](./NO_HELPER_FUNCTION_IN_TEST.md) — disallows helper functions inside test files

package/docs/rules/NO_HELPER_FUNCTION_IN_HOOK.md

@@ -0,0 +1,86 @@
+# no-helper-function-in-hook
+
+Disallow non-hook helper function definitions in hook files.
+
+## Rule Details
+
+Custom hook files should contain only the hook function itself (prefixed with `use`) and its supporting constants. Utility functions that are not hooks must be extracted to a separate file and imported.
+
+### Why?
+
+Helper functions defined inside a hook file are invisible to the rest of the codebase, cannot be tested independently, and are harder to reuse. Keeping hook files focused on a single hook makes them easier to read and maintain.
+
+## Examples
+
+### Incorrect
+
+```ts
+function buildQueryKey(id: string): string {
+  return `item-${id}`;
+}
+
+export function useItemData(id: string) {
+  const key = buildQueryKey(id);
+  // ...
+}
+```
+
+```ts
+const formatResponse = (data: unknown) => data;
+
+export const useItemData = (id: string) => {
+  // ...
+};
+```
+
+### Correct
+
+```ts
+import { buildQueryKey } from "./item.utils";
+
+export function useItemData(id: string) {
+  const key = buildQueryKey(id);
+  // ...
+}
+```
+
+Functions defined inside the hook body are fine:
+
+```ts
+export function useItemData(id: string) {
+  function buildQueryKey() {
+    return `item-${id}`;
+  }
+  // ...
+}
+```
+
+## What This Rule Checks
+
+- Top-level `function` declarations whose name does not start with `use`
+- Top-level `const`/`let`/`var` declarations assigned an arrow function or function expression whose name does not start with `use`
+
+Both plain and `export`-prefixed declarations are checked.
+
+## Exceptions
+
+- Hook functions starting with `use` are allowed at the top level
+- Functions defined inside a hook body are not flagged
+- Non-function constants (strings, numbers, arrays, objects) are not flagged
+
+## When Not To Use It
+
+This rule should be scoped to hook files using the ESLint `files` glob:
+
+```js
+{
+  files: ["**/*.hook.ts", "**/*.hooks.ts"],
+  rules: {
+    "nextfriday/no-helper-function-in-hook": "error",
+  },
+}
+```
+
+## Related Rules
+
+- [enforce-hook-naming](./ENFORCE_HOOK_NAMING.md) — enforces the `use` prefix on all functions in hook files

package/docs/rules/NO_HELPER_FUNCTION_IN_TEST.md

@@ -0,0 +1,69 @@
+# no-helper-function-in-test
+
+Disallow helper function definitions in test files.
+
+## Rule Details
+
+Test files should contain only pure test code — `describe`, `it`, `test`, `beforeEach`, and similar test runner constructs. Helper functions defined at the top level of a test file are utility code that belongs in a separate file and should be imported.
+
+### Why?
+
+When helper functions are defined inside test files, they become invisible to other tests and are harder to maintain, test independently, and reuse. Keeping test files free of utility logic makes them easier to read and reason about.
+
+## Examples
+
+### Incorrect
+
+```ts
+function findTemplateFiles(directory: string): string[] {
+  // ...
+}
+
+const extractImports = (source: string): string[] => {
+  // ...
+};
+
+describe("template imports", () => {
+  it("must only import from allowed paths", () => {
+    // ...
+  });
+});
+```
+
+### Correct
+
+```ts
+import { findTemplateFiles, extractImports } from "./test-utils";
+
+describe("template imports", () => {
+  it("must only import from allowed paths", () => {
+    // ...
+  });
+});
+```
+
+## What This Rule Checks
+
+- Top-level `function` declarations
+- Top-level `const`/`let`/`var` declarations assigned an arrow function or function expression
+
+Constants that are not functions (regex patterns, arrays, objects) are allowed.
+
+## Exceptions
+
+Functions declared inside `describe`, `it`, `test`, `beforeEach`, or other callback bodies are not flagged.
+
+## When Not To Use It
+
+Disable this rule for files that are intentionally test utility modules (e.g., `test-utils.ts`, `helpers.ts`) rather than test suite files.
+
+This rule should be scoped to test files using the ESLint `files` glob:
+
+```js
+{
+  files: ["**/*.test.ts", "**/*.spec.ts", "**/*.test.tsx", "**/*.spec.tsx"],
+  rules: {
+    "nextfriday/no-helper-function-in-test": "error",
+  },
+}
+```