@slip-stream-kit/eslint-plugin 0.1.15 → 0.1.19

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@slip-stream-kit/eslint-plugin",
   "type": "module",
-  "version": "0.1.15",
+  "version": "0.1.19",
   "description": "Custom ESLint rules enforcing the white-label frontend architecture conventions",
   "author": "Arthur Saenko <arthur.saenz7@gmail.com> (https://github.com/ArthurSaenz)",
   "license": "MIT",
@@ -52,10 +52,10 @@
   },
   "devDependencies": {
     "@types/node": "catalog:",
-    "@typescript-eslint/parser": "^8.61.1",
+    "@typescript-eslint/parser": "^8.62.0",
     "@wl/eslint-config": "workspace:*",
     "esbuild": "^0.28.0",
-    "eslint": "^10.5.0",
+    "eslint": "^10.6.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9"
   }

package/readme.md

@@ -11,8 +11,8 @@ pnpm add -D @wl/eslint-plugin
 ## Usage (flat config)
 
 Enable everything via the recommended preset. It is an array of config blocks
-(rules scoped to `*.tsx`, with `component-file-order` turned off for
-`*.stories.{ts,tsx}`), so spread it:
+(rules scoped to `*.tsx`, with `component-file-order` and `props-type-name`
+turned off for `*.stories.{ts,tsx}`), so spread it:
 
 ```js
 // eslint.config.js
@@ -136,12 +136,61 @@ matching files, `ignore` skips matching files (and takes precedence over
 }
 ```
 
+### `props-type-name`
+
+A React component's props type must be named **`<ComponentName>Props`** (e.g.
+`ButtonProps` for `Button`). This complements `props-type-reference`: that rule
+requires a _named_ type (not an inline literal); this rule requires that name to
+follow the convention. Report-only.
+
+```tsx
+// ❌ Incorrect — props type does not match the component name
+const Button = (props: Props) => <button>{props.label}</button>
+function Card({ title }: CardConfig) {
+  return <div>{title}</div>
+}
+
+// ✅ Correct — `<ComponentName>Props`
+const Button = (props: ButtonProps) => <button>{props.label}</button>
+function Card({ title }: CardProps) {
+  return <div>{title}</div>
+}
+```
+
+The component is detected the same way as the other rules (PascalCase name
+through `memo`/`forwardRef`/`observer` wrappers, or a JSX return). Only a simple
+named type reference on the first parameter is checked: inline object types are
+the `props-type-reference` rule's concern, and anonymous components, untyped
+props, and qualified/generic annotations (`NS.Props`, `FC<Props>`) are left
+alone. An imported props type with a non-conventional name is still flagged —
+use `paths`/`ignore` to exempt it.
+
+The recommended preset turns this rule **off for `*.stories.{ts,tsx}`**: story
+templates legitimately reference the component's own props type (e.g.
+`const Template = (args: ButtonProps) => ...`) rather than `<TemplateName>Props`.
+
+#### Option: `paths` / `ignore` (optional)
+
+Same glob semantics as `component-file-order`: `paths` restricts the rule to
+matching files, `ignore` skips matching files (and takes precedence over
+`paths`).
+
+```js
+{
+  rules: {
+    '@wl/props-type-name': ['error', { ignore: ['**/*.stories.tsx'] }],
+  },
+}
+```
+
 ### `component-file-order`
 
 Enforce a strict top-level order in files that contain a React component:
-**imports → component props interface/type → component declaration**. Constants
-and helpers between the interface and the component are allowed. Report-only (it
-does not auto-reorder code).
+**imports → component props interface/type → component declaration**, with the
+props interface declared **immediately before** the component — no constants,
+helpers, or other declarations wedged between them. Helpers are allowed _after_
+the component (or between two separate component blocks). Report-only (it does
+not auto-reorder code).
 
 ```tsx
 // ❌ Incorrect — interface before imports, or component before its interface
@@ -162,15 +211,18 @@ const Card = (props: CardProps) => {
 }
 ```
 
-The rule activates only when the file actually contains a component. The "props
-interface" is any top-level `interface`/`type` whose name ends in `Props`.
+The rule activates only when the file actually contains a component. A
+component's props interface is matched by the **type its parameter actually
+references** (e.g. `Props` in `(props: Props)`), not by a name convention — so an
+interface named anything is enforced, as long as the component uses it. (When the
+parameter has no resolvable named type, the rule falls back to looking for a
+`<ComponentName>Props` interface.)
 
 When the first component's props type is **imported** (e.g.
 `import type { CardProps } from './types'`) instead of declared in the file,
 there is no in-file interface to anchor against — so the component itself must
 sit immediately after the imports, with no stray top-level definitions wedged in
-between. Only the first component is anchored this way; the props binding must be
-the conventional `<ComponentName>Props` name for the check to apply.
+between. Only the first component is anchored this way.
 
 ```tsx
 // ❌ Incorrect — props imported, but a stray const sits before the component
@@ -256,6 +308,165 @@ to add your own, e.g. an `app/` router):
 }
 ```
 
+### `max-jsx-return-size`
+
+Warn when a single component **return** renders too many JSX elements. Large
+return blocks are hard to scan; the fix is to extract part of the markup into a
+variable or a sub-component. Report-only — the remedy is left to the developer
+(no autofix), because safely extracting JSX touches scope, hooks, and keys.
+
+```tsx
+// ❌ Incorrect — one return renders too many elements (default max 20)
+const Dashboard = () => (
+  <div>
+    <header>…</header>
+    <main>… lots of nested markup …</main>
+    <footer>…</footer>
+  </div>
+)
+
+// ✅ Correct — extract parts into variables or sub-components
+const Dashboard = () => {
+  const header = <header>…</header>
+  const footer = <footer>…</footer>
+
+  return (
+    <div>
+      {header}
+      <Main />
+      {footer}
+    </div>
+  )
+}
+```
+
+The metric is a **count of `JSXElement` nodes in the returned expression** —
+formatting-independent (Prettier reflow never changes the verdict). Each return
+in a component is measured on its own, so a small guard such as
+`if (loading) return <Spinner />` is never penalised by a large sibling return.
+
+Counting rules:
+
+- **Extraction lowers the count.** JSX hoisted into a variable is referenced as
+  `{header}` (a JSX expression container, not a `JSXElement`), so it is not
+  counted — extracting strictly reduces the number.
+- **Fragments are free.** `<>…</>` contributes `0`; its children still count.
+- **Inline-callback JSX counts** in the parent return: `<ul>{items.map(() => <li />)}</ul>`
+  counts `<ul>` and `<li>` (extract a `<Row />` sub-component to reduce it).
+- **Conditional branches are summed:** `cond ? <A /> : <B />` counts both sides.
+- **JSX in attributes is counted:** `<Foo icon={<Icon />} />` counts `Foo` and `Icon`.
+
+Only **top-level declared** components are inspected (same as
+`component-arrow-function`), so anonymous inline callbacks are never reported on
+their own. A top-level JSX-returning helper (e.g. `const renderRow = () => <li />`)
+is treated as a component and measured. The message names the component when
+resolvable and uses a generic `component` for anonymous defaults.
+
+**Actionable message.** When one block dominates the return, the message points
+at it — its tag, line, and element count — so a human (or an automated lint →
+fix → lint loop) knows exactly what to lift out:
+
+```
+Dashboard renders 28 JSX elements in one return (max 20). Extract the largest
+block — <section> at line 14 (12 elements) — into a variable or a sub-component.
+```
+
+When no single block dominates (e.g. many flat sibling elements), there is
+nothing useful to point at, so the message instead advises splitting the return
+into smaller sub-components.
+
+#### Option: `maxElements` (optional)
+
+The element ceiling before the rule reports. Defaults to `20`. Only counts
+strictly greater than the ceiling are reported (`count === max` is allowed).
+
+```js
+{
+  rules: {
+    '@wl/max-jsx-return-size': ['error', { maxElements: 25 }],
+  },
+}
+```
+
+#### Option: `paths` / `ignore` (optional)
+
+Same glob semantics as the other rules: `paths` restricts the rule to matching
+files, `ignore` skips matching files (and takes precedence over `paths`).
+
+### `max-components-per-file`
+
+Caps how many React components a single file may declare; extra components
+belong in their own files. This keeps files focused and discoverable instead of
+growing into multi-component junk drawers.
+
+```tsx
+// ❌ Incorrect — 5 components in one file (default ceiling is 4)
+const A = () => <div />
+const B = () => <div />
+const C = () => <div />
+const D = () => <div />
+const E = () => <div /> // reported here: "This file declares 5 components (max 4)"
+
+// ✅ Correct — split the extra component into its own file
+```
+
+Only **top-level** declarations are counted. A multi-declarator statement
+(`const A = () => …, B = () => …`) counts each component separately. Re-exports
+(`export { X } from './x'`) declare nothing and are not counted, and
+`styled.div\`…\`` tagged templates are not component functions, so they are not
+counted either. Nested / in-render components are intentionally out of scope —
+that is a different concern (component identity / re-render stability), better
+served by `react/no-unstable-nested-components`.
+
+Detection uses the same heuristic as the other rules (PascalCase name through
+`memo`/`forwardRef`/`observer` wrappers, or a JSX return). A consequence worth
+knowing: a PascalCase-named function that returns a non-JSX value (e.g. a factory
+`const Make = () => ({ … })`) is counted as a component, because the name
+short-circuits the check. This is consistent across the plugin.
+
+The rule reports **once per file**, anchored to the first component over the
+limit, rather than once per excess component — there is no autofix, so a single
+file-scoped diagnostic is more useful than N copies of the same advice.
+
+In the recommended preset the ceiling is `4` for `*.tsx` generally and tightened
+to `1` for dumb `*-component.tsx` files (matching the one-component-per-file
+convention the props/order/stories rules already assume); `**/pages/**` and
+`**/routes/**` are exempt, since route/page modules legitimately co-locate
+multiple route or layout components. For a file that genuinely needs to break the
+ceiling, use an inline `// eslint-disable-next-line @wl/max-components-per-file`.
+
+#### Why a custom rule (vs `react/no-multi-comp`)
+
+`eslint-plugin-react`'s `no-multi-comp` covers similar ground but effectively
+enforces a fixed ceiling of 1 (it flags the 2nd+ component) and cannot be
+configured to an arbitrary limit. This rule exists because it (1) supports a
+configurable `maxComponents` ceiling, (2) supports tiered per-file-type limits
+via flat-config layering, and (3) reuses this plugin's centralized component
+detection so its behavior matches the sibling `@wl` rules. (`eslint-plugin-react`
+is not a dependency of this repo.)
+
+#### Option: `maxComponents` (optional)
+
+The component ceiling before the rule reports. Defaults to `4`. Only counts
+strictly greater than the ceiling are reported (`count === max` is allowed).
+
+```js
+{
+  rules: {
+    '@wl/max-components-per-file': ['error', { maxComponents: 2 }],
+  },
+}
+```
+
+#### Option: `paths` / `ignore` (optional)
+
+Same glob semantics as the other rules: `paths` restricts the rule to matching
+files, `ignore` skips matching files (and takes precedence over `paths`).
+
+> **Flat-config note:** options are **replaced**, not merged, across matching
+> config blocks. If you override `maxComponents` for a glob, re-declare `ignore`
+> in that same block or its exemptions are lost.
+
 ### `require-component-stories`
 
 Require a co-located Storybook story for every dumb component. By default it enforces two layouts,