eslint-plugin-nextfriday 4.1.0 → 4.3.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # 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
+
+- [#126](https://github.com/next-friday/eslint-plugin-nextfriday/pull/126) [`ec5eec8`](https://github.com/next-friday/eslint-plugin-nextfriday/commit/ec5eec80689a5ec6470807077e94b7065d1cb13c) Thanks [@joetakara](https://github.com/joetakara)! - add four JSX rules that target a single anti-pattern: component files acting as content / type / naming dumping grounds. The `.tsx` and `.jsx` file is meant to describe one component's render — data, sub-types, and helper render-fragments belong elsewhere or under a clearer name.
+  - `jsx-no-data-array` flags top-level `const` declarations whose initializer is an array literal containing object literals — including `as const` and `satisfies` variants and exported declarations. Arrays of primitives are unaffected. The shape is a strong signal of fixture / seed / content data, which belongs in a sibling `*.data.ts` module.
+  - `jsx-no-data-object` flags top-level `const` declarations whose initializer is an object literal that contains a nested object or a nested array of objects — including `as const` and `satisfies` variants and exported declarations. Flat maps of primitives (`{ home: "/", about: "/about" }`) are not flagged. Nested configuration / content belongs in a data module.
+  - `jsx-no-sub-interface` flags any top-level `interface` or `type` declaration in a `.tsx` / `.jsx` file that is not the main props type for a component declared in the same file. The "main" type is determined by the parameter type of a top-level PascalCase function or arrow component, with common wrappers (`Readonly<T>`, `Required<T>`, `Partial<T>`, `PropsWithChildren<T>`, `NoInfer<T>`) unwrapped. Sub-interfaces (e.g. `StoreCardAddressProps` referenced as a field in `StoreCardProps`) and helper unions belong in their own module — typically a sibling `*.types.ts`. Files that declare no component at all are not checked, so type-only `.tsx` modules and re-export-only files are unaffected.
+  - `enforce-render-naming` flags variables declared inside a top-level PascalCase component whose initializer holds or returns JSX, but whose name does not start with `render` followed by a camelCase boundary. Detected JSX-producing initializers include `JSXElement` / `JSXFragment` literals, conditional and logical expressions whose branch is JSX, arrays of JSX, arrow / function expressions whose body returns JSX, `.map` / `.flatMap` / `.filter` calls whose callback returns JSX, and `as` / `satisfies` wrappers around any of the above. Both value form (`const renderHeader = <div />`) and function form (`const renderHeader = () => <div />`) satisfy the rule — the convention checks intent via the prefix, not the shape.
+
+  All four rules ship in the `react`, `react/recommended`, `nextjs`, and `nextjs/recommended` presets at `warn` and `error` severity respectively. Total rule count is now 63 (40 base + 23 JSX). None of the new rules are auto-fixable: each surfaces a structural decision (where to put the data, where to put the type, what to name the fragment) that the author should make explicitly.
+
 ## 4.1.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
 
@@ -458,9 +462,12 @@ In practice: turn the high tier on as `"error"` first, leave the medium tier as
 | Rule                                                                                     | Description                                                           | Fixable |
 | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------- |
 | [jsx-newline-between-elements](docs/rules/JSX_NEWLINE_BETWEEN_ELEMENTS.md)               | Require empty lines between sibling multi-line JSX children           | ✅      |
+| [jsx-no-data-array](docs/rules/JSX_NO_DATA_ARRAY.md)                                     | Disallow top-level array of object literals in `.tsx`/`.jsx`          | ❌      |
+| [jsx-no-data-object](docs/rules/JSX_NO_DATA_OBJECT.md)                                   | Disallow top-level nested object literals in `.tsx`/`.jsx`            | ❌      |
 | [jsx-no-inline-object-prop](docs/rules/JSX_NO_INLINE_OBJECT_PROP.md)                     | Disallow inline object literals in JSX props                          | ❌      |
 | [jsx-no-newline-single-line-elements](docs/rules/JSX_NO_NEWLINE_SINGLE_LINE_ELEMENTS.md) | Disallow empty lines between single-line sibling JSX elements         | ✅      |
 | [jsx-no-non-component-function](docs/rules/JSX_NO_NON_COMPONENT_FUNCTION.md)             | Disallow non-component functions at top level in .tsx/.jsx files      | ❌      |
+| [jsx-no-sub-interface](docs/rules/JSX_NO_SUB_INTERFACE.md)                               | Disallow sub-interfaces and helper types in component files           | ❌      |
 | [jsx-no-ternary-null](docs/rules/JSX_NO_TERNARY_NULL.md)                                 | Enforce logical AND over ternary with null/undefined in JSX           | ✅      |
 | [jsx-no-variable-in-callback](docs/rules/JSX_NO_VARIABLE_IN_CALLBACK.md)                 | Disallow variable declarations inside callback functions in JSX       | ❌      |
 | [jsx-require-suspense](docs/rules/JSX_REQUIRE_SUSPENSE.md)                               | Require lazy-loaded components to be wrapped in Suspense              | ❌      |
@@ -474,6 +481,7 @@ In practice: turn the high tier on as `"error"` first, leave the medium tier as
 | [react-props-destructure](docs/rules/REACT_PROPS_DESTRUCTURE.md)                         | Enforce destructuring props inside React component body               | ❌      |
 | [enforce-props-suffix](docs/rules/ENFORCE_PROPS_SUFFIX.md)                               | Enforce 'Props' suffix for interfaces and types in \*.tsx files       | ❌      |
 | [enforce-readonly-component-props](docs/rules/ENFORCE_READONLY_COMPONENT_PROPS.md)       | Enforce Readonly wrapper for React component props                    | ✅      |
+| [enforce-render-naming](docs/rules/ENFORCE_RENDER_NAMING.md)                             | Enforce 'render' prefix for variables holding JSX inside components   | ❌      |
 
 ## Configurations
 
@@ -481,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         | 19        | 59          |
-| `react/recommended`  | error    | 40         | 19        | 59          |
-| `nextjs`             | warn     | 40         | 19        | 59          |
-| `nextjs/recommended` | error    | 40         | 19        | 59          |
+| `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`
@@ -535,16 +545,20 @@ Included in `base`, `base/recommended`, and all other presets:
 - `nextfriday/sort-type-alphabetically`
 - `nextfriday/sort-type-required-first`
 
-### JSX Rules (19 rules)
+### JSX Rules (23 rules)
 
 Additionally included in `react`, `react/recommended`, `nextjs`, `nextjs/recommended`:
 
 - `nextfriday/enforce-props-suffix`
 - `nextfriday/enforce-readonly-component-props`
+- `nextfriday/enforce-render-naming`
 - `nextfriday/jsx-newline-between-elements`
+- `nextfriday/jsx-no-data-array`
+- `nextfriday/jsx-no-data-object`
 - `nextfriday/jsx-no-inline-object-prop`
 - `nextfriday/jsx-no-newline-single-line-elements`
 - `nextfriday/jsx-no-non-component-function`
+- `nextfriday/jsx-no-sub-interface`
 - `nextfriday/jsx-no-ternary-null`
 - `nextfriday/jsx-no-variable-in-callback`
 - `nextfriday/jsx-require-suspense`

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_RENDER_NAMING.md

@@ -0,0 +1,96 @@
+# enforce-render-naming
+
+Enforce `render` prefix for variables that hold or return JSX inside React components.
+
+## Rule Details
+
+This rule flags variables declared inside a React component (a top-level PascalCase function or arrow function) whose initializer holds or returns JSX, but whose name does not start with `render`. The `render` prefix makes intent explicit: a reader scanning the component body can tell at a glance which locals are render fragments and which are plain data.
+
+The rule applies inside any function or block nested within the component — not only the component's top-level body.
+
+The prefix must be `render` followed by a camelCase boundary (uppercase letter, or end-of-name). Names like `renderer` (lowercase letter after the prefix) do not count.
+
+### Why?
+
+- **Self-documenting code**: `renderPhoneEntries` reads as "this is a render fragment for phone entries". `phoneEntries` reads as "this is data — a list of phones". The distinction matters when the same component holds both.
+- **Refactor signal**: When you want to extract render fragments into separate components, grepping for `render*` finds candidates immediately.
+- **Consistency**: Aligns with `enforce-hook-naming` (`use*` for hooks) and `enforce-service-naming` (`fetch*` for services) — name-by-purpose conventions throughout the plugin.
+
+## Examples
+
+### Incorrect
+
+```tsx
+const Component = (props) => {
+  const header = <div />;
+  const cardElements = props.items.map((item) => <Card {...item} />);
+  const phoneEntries = props.phones.map((phone) => {
+    return <span>{phone}</span>;
+  });
+  const fallback = props.condition ? <A /> : <B />;
+  const banner = props.isVisible && <Banner />;
+  return (
+    <>
+      {header}
+      {cardElements}
+      {phoneEntries}
+      {fallback}
+      {banner}
+    </>
+  );
+};
+```
+
+### Correct
+
+```tsx
+const Component = (props) => {
+  const renderHeader = <div />;
+  const renderCardElements = props.items.map((item) => <Card {...item} />);
+  const renderPhoneEntries = props.phones.map((phone) => {
+    return <span>{phone}</span>;
+  });
+  const renderFallback = props.condition ? <A /> : <B />;
+  const renderBanner = props.isVisible && <Banner />;
+  return (
+    <>
+      {renderHeader}
+      {renderCardElements}
+      {renderPhoneEntries}
+      {renderFallback}
+      {renderBanner}
+    </>
+  );
+};
+```
+
+Both value form and function form are accepted as long as the prefix is correct:
+
+```tsx
+const renderHeader = <div />; // value form — eval once at component render
+const renderHeader = () => <div />; // function form — eval each call
+```
+
+## What This Rule Checks
+
+The rule fires when a `const` or `let` declaration is created **inside** a top-level PascalCase function (a React component) and the initializer is one of:
+
+- A `JSXElement` or `JSXFragment` directly
+- A `ConditionalExpression` whose consequent or alternate produces JSX
+- A `LogicalExpression` whose right-hand side produces JSX
+- An `ArrayExpression` containing JSX elements
+- An `ArrowFunctionExpression` or `FunctionExpression` whose body returns JSX
+- A `CallExpression` to `.map`, `.flatMap`, or `.filter` whose callback returns JSX
+- A `TSAsExpression` or `TSSatisfiesExpression` wrapping any of the above
+
+The rule applies only to `.tsx` and `.jsx` files. Variables declared outside any PascalCase function (top-level module constants, helpers in plain functions) are not checked.
+
+## When Not To Use It
+
+If your team prefers other naming conventions for extracted JSX (e.g., `*Element`, `*Section`, `*Fragment`), or if you do not extract JSX into intermediate variables in the first place.
+
+## Related Rules
+
+- [enforce-hook-naming](ENFORCE_HOOK_NAMING.md)
+- [enforce-service-naming](ENFORCE_SERVICE_NAMING.md)
+- [boolean-naming-prefix](BOOLEAN_NAMING_PREFIX.md)

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/JSX_NO_DATA_ARRAY.md

@@ -0,0 +1,63 @@
+# jsx-no-data-array
+
+Disallow top-level arrays of object literals in `.tsx`/`.jsx` files (extract to a data file).
+
+## Rule Details
+
+This rule flags top-level `const` declarations in `.tsx` and `.jsx` files whose initializer is an array literal containing one or more object literals. This shape is a strong signal of fixture / seed / content data, which belongs in a sibling data module — not in a component file.
+
+The rule fires on both unexported declarations and `export const` declarations, and on `as const` / `satisfies` variants.
+
+### Why?
+
+- **Separation of concerns**: Component files should describe rendering. Content / fixture data belongs in `*.data.ts`, `*.fixtures.ts`, a CMS, or a content layer.
+- **Diff hygiene**: Editing one address line should not produce noise inside the component diff.
+- **AI assistant pressure**: LLMs default to inlining mock data when they cannot find a data layer; a lint rule is the cheapest way to redirect them.
+
+## Examples
+
+### Incorrect
+
+```tsx
+const stores = [{ name: "Koh Samui", isOpen: true }];
+const items: Item[] = [{ id: 1 }, { id: 2 }];
+const config = [{ key: "a" }] as const;
+const data = [{ id: 1 }] satisfies readonly { id: number }[];
+export const navItems = [{ label: "Home", href: "/" }];
+```
+
+### Correct
+
+```tsx
+const TIMEOUT_MS = 1000;
+const labels = ["Home", "About", "Contact"];
+const numbers = [1, 2, 3];
+const ROUTES = { home: "/", about: "/about" };
+```
+
+Move arrays of object literals to a sibling data file:
+
+```ts
+// stores.data.ts
+export const stores = [{ name: "Koh Samui", isOpen: true }];
+```
+
+```tsx
+// HeaderStore.tsx
+import { stores } from "./stores.data";
+```
+
+## What This Rule Checks
+
+The rule fires when a top-level `const` declaration's initializer (after unwrapping `as`/`satisfies`) is an `ArrayExpression` and at least one of its elements is an `ObjectExpression` (also after unwrapping). Arrays of primitives, identifiers, or member expressions are not flagged.
+
+The rule applies only to `.tsx` and `.jsx` files. Plain `.ts` and `.js` files are not checked — extract data files into those extensions.
+
+## When Not To Use It
+
+If your project deliberately co-locates small static data with components, or if you treat `.tsx` files as both component and data layer.
+
+## Related Rules
+
+- [jsx-no-data-object](JSX_NO_DATA_OBJECT.md)
+- [jsx-no-non-component-function](JSX_NO_NON_COMPONENT_FUNCTION.md)

package/docs/rules/JSX_NO_DATA_OBJECT.md

@@ -0,0 +1,71 @@
+# jsx-no-data-object
+
+Disallow top-level nested object literals in `.tsx`/`.jsx` files (extract to a data file).
+
+## Rule Details
+
+This rule flags top-level `const` declarations in `.tsx` and `.jsx` files whose initializer is an object literal that contains at least one nested object or nested array. The "nesting" is the smell — flat maps of primitives are fine, but objects-of-objects or objects-of-object-arrays look like configuration / content data and belong in a data module.
+
+The rule fires on both unexported declarations and `export const` declarations, and on `as const` / `satisfies` variants.
+
+### Why?
+
+- **Separation of concerns**: Component files should describe rendering. Nested configuration / content belongs in a sibling data module.
+- **Diff hygiene**: Tweaking a nested setting should not bloat the component diff.
+- **AI assistant pressure**: LLMs default to inlining mock config when they cannot find a data layer; a lint rule is the cheapest way to redirect them.
+
+## Examples
+
+### Incorrect
+
+```tsx
+const config = { home: { url: "/" } };
+const config = { items: [{ id: 1 }] };
+const matrix = {
+  values: [
+    [1, 2],
+    [3, 4],
+  ],
+};
+const config = { a: { b: 1 } } as const;
+export const config = { a: { b: 1 } };
+```
+
+### Correct
+
+```tsx
+const TIMEOUT_MS = 1000;
+const ROUTES = { home: "/", about: "/about", contact: "/contact" };
+const labels = ["Home", "About"];
+const config = { a: 1, b: "x", c: true };
+```
+
+Move nested objects to a sibling data file:
+
+```ts
+// settings.data.ts
+export const settings = { home: { url: "/" } };
+```
+
+```tsx
+// HomePage.tsx
+import { settings } from "./settings.data";
+```
+
+## What This Rule Checks
+
+The rule fires when a top-level `const` declaration's initializer (after unwrapping `as`/`satisfies`) is an `ObjectExpression` whose properties contain at least one of:
+
+- A property whose value is another `ObjectExpression`
+- A property whose value is an `ArrayExpression` containing an `ObjectExpression` or another `ArrayExpression`
+
+Flat maps of primitives are not flagged. The rule applies only to `.tsx` and `.jsx` files.
+
+## When Not To Use It
+
+If your project deliberately co-locates small nested config with components, or if you treat `.tsx` files as both component and data layer.
+
+## Related Rules
+
+- [jsx-no-data-array](JSX_NO_DATA_ARRAY.md)
+- [jsx-no-non-component-function](JSX_NO_NON_COMPONENT_FUNCTION.md)

package/docs/rules/JSX_NO_SUB_INTERFACE.md

@@ -0,0 +1,86 @@
+# jsx-no-sub-interface
+
+Disallow sub-interfaces and helper types in component files; keep only the main component props.
+
+## Rule Details
+
+This rule flags any top-level `interface` or `type` declaration in a `.tsx` / `.jsx` file that is not the main props type for a component declared in the same file. Sub-interfaces (e.g., `StoreCardAddressProps` referenced as a field in `StoreCardProps`) and helper unions (e.g., `type StoreCardKind = "a" | "b"`) should live in their own modules — typically a sibling `*.types.ts` file or alongside their own component.
+
+The "main" props type is determined by the parameter type of a top-level PascalCase function or arrow component. Common wrappers like `Readonly<T>`, `Required<T>`, `Partial<T>`, `PropsWithChildren<T>`, and `NoInfer<T>` are unwrapped to find the underlying type name.
+
+If the file declares no component at all, the rule does not fire — pure `.tsx` / `.jsx` files used as type or re-export modules are skipped.
+
+### Why?
+
+- **Single responsibility per file**: A component file should describe one component. Sub-types pollute it with shapes that are referenced but not the component's own concern.
+- **Reusability**: Sub-types extracted to their own module can be imported by sibling components and tests; trapped inside a component file, they cannot.
+- **Diff hygiene**: Editing a sub-interface should not produce noise in the component diff.
+
+## Examples
+
+### Incorrect
+
+```tsx
+interface StoreCardProps {
+  address: StoreCardAddressProps;
+  image: StoreCardImageProps;
+  name: string;
+}
+
+interface StoreCardAddressProps {
+  label: string;
+  mapUrl: string;
+}
+
+interface StoreCardImageProps {
+  alt: string;
+  src: string;
+}
+
+type StoreCardKind = "phone" | "whatsapp";
+
+const StoreCard = (props: Readonly<StoreCardProps>) => <div />;
+```
+
+### Correct
+
+```tsx
+import type { StoreCardAddressProps } from "./store-card-address.types";
+import type { StoreCardImageProps } from "./store-card-image.types";
+
+interface StoreCardProps {
+  address: StoreCardAddressProps;
+  image: StoreCardImageProps;
+  name: string;
+}
+
+const StoreCard = (props: Readonly<StoreCardProps>) => <div />;
+```
+
+```ts
+// store-card-address.types.ts
+export interface StoreCardAddressProps {
+  label: string;
+  mapUrl: string;
+}
+```
+
+## What This Rule Checks
+
+The rule walks the program body and collects:
+
+- **Components** — top-level PascalCase `function` declarations and PascalCase `const X = (...) => ...` or `const X = function(...) {}` initializers, including ones wrapped in `export` / `export default`.
+- **Main types** — for each component, the type referenced by its first parameter's annotation, after unwrapping `Readonly<T>`, `Required<T>`, `Partial<T>`, `PropsWithChildren<T>`, and `NoInfer<T>`.
+- **Top-level type declarations** — `interface` and `type` declarations at the top level (including ones wrapped in `export`).
+
+Any top-level type declaration whose name is not in the set of main types is flagged. The rule does not fire when the file has no component.
+
+## When Not To Use It
+
+If your project deliberately co-locates sub-types and helper types with their consuming component, or if you keep the component and its supporting types in a single file by convention.
+
+## Related Rules
+
+- [enforce-props-suffix](ENFORCE_PROPS_SUFFIX.md)
+- [prefer-interface-for-component-props](PREFER_INTERFACE_FOR_COMPONENT_PROPS.md)
+- [prefer-interface-over-inline-types](PREFER_INTERFACE_OVER_INLINE_TYPES.md)

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