@slip-stream-kit/eslint-plugin 0.1.17 → 0.1.20

package/dist/rules/{props-type-name.d.ts → props-type-name/props-type-name.d.ts}

@@ -1,3 +1,2 @@
 import type { Rule } from 'eslint';
 export declare const propsTypeName: Rule.RuleModule;
-export default propsTypeName;

package/dist/rules/props-type-reference/index.d.ts

@@ -0,0 +1 @@
+export { propsTypeReference } from './props-type-reference';

package/dist/rules/{props-type-reference.d.ts → props-type-reference/props-type-reference.d.ts}

@@ -1,3 +1,2 @@
 import type { Rule } from 'eslint';
 export declare const propsTypeReference: Rule.RuleModule;
-export default propsTypeReference;

package/dist/rules/require-component-stories/index.d.ts

@@ -0,0 +1 @@
+export { requireComponentStories } from './require-component-stories';

package/dist/rules/{require-component-stories.d.ts → require-component-stories/require-component-stories.d.ts}

@@ -1,3 +1,2 @@
 import type { Rule } from 'eslint';
 export declare const requireComponentStories: Rule.RuleModule;
-export default requireComponentStories;

package/dist/rules/require-jsdoc-example/index.d.ts

@@ -0,0 +1 @@
+export { requireJsdocExample } from './require-jsdoc-example';

package/dist/rules/require-jsdoc-example/require-jsdoc-example.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from 'eslint';
+export declare const requireJsdocExample: Rule.RuleModule;

package/dist/utils/cognitive-complexity.d.ts

@@ -0,0 +1,14 @@
+import type * as ESTree from 'estree';
+export type FunctionNode = ESTree.ArrowFunctionExpression | ESTree.FunctionDeclaration | ESTree.FunctionExpression;
+/**
+ * Cognitive complexity of a function per the SonarSource white-paper model.
+ *
+ * Each `if`/ternary/switch/loop/`catch` adds 1 plus the current nesting level;
+ * `else`/`else if` adds 1 with no nesting bump; each run of a logical operator
+ * adds 1; recursion (a direct call to the enclosing function by name) adds 1.
+ * Nesting deepens inside every branch, loop, switch, `catch`, and nested function.
+ *
+ * @example
+ * cognitiveComplexity(node) // 0 for a flat function, 1 for a single `if`
+ */
+export declare const cognitiveComplexity: (fn: FunctionNode, enclosingName?: string | null) => number;

package/dist/utils/component.d.ts

@@ -1,11 +1,25 @@
 import type * as ESTree from 'estree';
 export type ComponentFunction = ESTree.ArrowFunctionExpression | ESTree.FunctionDeclaration | ESTree.FunctionExpression;
+export declare const isJsxNode: (node: ESTree.Node | null | undefined) => boolean;
 /**
  * Resolve the declared name of a function, looking through component wrappers
  * such as `memo`/`forwardRef` so that `const Comp = memo(({ a }) => ...)` is
  * still recognised by its PascalCase variable name.
  */
 export declare const getComponentName: (node: ComponentFunction) => string | null;
+/**
+ * Collect every *own* return argument of a function — the expression of each
+ * `return <expr>` reachable without entering a nested function scope, plus the
+ * implicit-return body of an expression-bodied arrow.
+ *
+ * Bare `return;` (a null argument) contributes nothing, so callers never receive
+ * a null and can safely walk each result. This is the multi-return counterpart
+ * to the boolean `returnsJsx`, which is defined in terms of it; the deliberate
+ * "skip nested scopes" behaviour answers *which* returns belong to this function
+ * (a `return` inside an inline `.map`/IIFE callback is that callback's return,
+ * not this one's).
+ */
+export declare const collectOwnReturnArguments: (node: ComponentFunction) => ESTree.Expression[];
 /** A function is treated as a React component when it is PascalCase-named or returns JSX. */
 export declare const isComponent: (node: ComponentFunction) => boolean;
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@slip-stream-kit/eslint-plugin",
   "type": "module",
-  "version": "0.1.17",
+  "version": "0.1.20",
   "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

@@ -308,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,