eslint-plugin-nextfriday 4.0.0 → 4.1.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # eslint-plugin-nextfriday
 
+## 4.1.0
+
+### Minor Changes
+
+- [#124](https://github.com/next-friday/eslint-plugin-nextfriday/pull/124) [`be12809`](https://github.com/next-friday/eslint-plugin-nextfriday/commit/be128098e2af102a153c3d01546a2921518f4b96) Thanks [@joetakara](https://github.com/joetakara)! - add two JSX rules targeting unnecessary wrapper noise (the "Divitis" anti-pattern):
+  - `no-ghost-wrapper` flags bare `<div>` / `<span>` elements that carry no meaningful attributes. Self-closing variants are checked the same way. The `key` prop alone does not silence the rule, since `key` carries no structural intent. Any other attribute — `className`, `style`, `id`, `ref`, `role`, `aria-*`, `data-*`, `tabIndex`, event handlers, or spread attributes — is considered meaningful and lets the element pass.
+  - `no-redundant-fragment` flags Fragments (`<>...</>`, `<Fragment>`, `<React.Fragment>`) that wrap zero or one child. JSX text consisting only of whitespace is not counted. Long-form Fragments carrying a `key` attribute are exempt, since `key` is the canonical reason long-form Fragment exists (the shorthand `<>...</>` cannot accept attributes).
+
+  Both rules are report-only — no autofix is provided so authors retain control over which structural alternative (Fragment, semantic element, unwrapping the children) best fits the surrounding code. Both are added to the JSX rule tier and ship in the `react`, `react/recommended`, `nextjs`, and `nextjs/recommended` presets at `warn` and `error` severity respectively.
+
 ## 4.0.0
 
 ### Major Changes

package/README.md

@@ -467,6 +467,8 @@ In practice: turn the high tier on as `"error"` first, leave the medium tier as
 | [jsx-simple-props](docs/rules/JSX_SIMPLE_PROPS.md)                                       | Enforce simple prop values (strings, variables, callbacks, ReactNode) | ❌      |
 | [jsx-sort-props](docs/rules/JSX_SORT_PROPS.md)                                           | Enforce JSX props are sorted by value type                            | ✅      |
 | [jsx-spread-props-last](docs/rules/JSX_SPREAD_PROPS_LAST.md)                             | Enforce JSX spread attributes appear after all other props            | ❌      |
+| [no-ghost-wrapper](docs/rules/NO_GHOST_WRAPPER.md)                                       | Disallow bare `<div>`/`<span>` with no meaningful attributes          | ❌      |
+| [no-redundant-fragment](docs/rules/NO_REDUNDANT_FRAGMENT.md)                             | Disallow Fragments wrapping zero or one child                         | ❌      |
 | [prefer-jsx-template-literals](docs/rules/PREFER_JSX_TEMPLATE_LITERALS.md)               | Enforce template literals instead of mixing text and JSX expressions  | ✅      |
 | [prefer-props-with-children](docs/rules/PREFER_PROPS_WITH_CHILDREN.md)                   | Prefer PropsWithChildren over manually declaring children: ReactNode  | ❌      |
 | [react-props-destructure](docs/rules/REACT_PROPS_DESTRUCTURE.md)                         | Enforce destructuring props inside React component body               | ❌      |
@@ -481,10 +483,10 @@ In practice: turn the high tier on as `"error"` first, leave the medium tier as
 | -------------------- | -------- | ---------- | --------- | ----------- |
 | `base`               | warn     | 40         | 0         | 40          |
 | `base/recommended`   | error    | 40         | 0         | 40          |
-| `react`              | warn     | 40         | 17        | 57          |
-| `react/recommended`  | error    | 40         | 17        | 57          |
-| `nextjs`             | warn     | 40         | 17        | 57          |
-| `nextjs/recommended` | error    | 40         | 17        | 57          |
+| `react`              | warn     | 40         | 19        | 59          |
+| `react/recommended`  | error    | 40         | 19        | 59          |
+| `nextjs`             | warn     | 40         | 19        | 59          |
+| `nextjs/recommended` | error    | 40         | 19        | 59          |
 
 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.
 
@@ -533,7 +535,7 @@ Included in `base`, `base/recommended`, and all other presets:
 - `nextfriday/sort-type-alphabetically`
 - `nextfriday/sort-type-required-first`
 
-### JSX Rules (17 rules)
+### JSX Rules (19 rules)
 
 Additionally included in `react`, `react/recommended`, `nextjs`, `nextjs/recommended`:
 
@@ -549,6 +551,8 @@ Additionally included in `react`, `react/recommended`, `nextjs`, `nextjs/recomme
 - `nextfriday/jsx-simple-props`
 - `nextfriday/jsx-sort-props`
 - `nextfriday/jsx-spread-props-last`
+- `nextfriday/no-ghost-wrapper`
+- `nextfriday/no-redundant-fragment`
 - `nextfriday/prefer-interface-for-component-props`
 - `nextfriday/prefer-interface-over-inline-types`
 - `nextfriday/prefer-jsx-template-literals`
@@ -571,16 +575,6 @@ Additionally included in `react`, `react/recommended`, `nextjs`, `nextjs/recomme
 - **Clean code practices**: Prevents emoji usage, enforces parameter destructuring, and more
 - **Formatting rules**: Enforces consistent blank lines around multi-line blocks and return statements
 
-## Agent Skill
-
-This plugin ships with an [Agent Skill](https://github.com/anthropics/skills) that teaches AI coding assistants (Claude Code, Cursor, etc.) all 57 rules so they generate compliant code from the start.
-
-```bash
-npx skills add next-friday/eslint-plugin-nextfriday --skill eslint-plugin-nextfriday
-```
-
-Once installed, AI assistants will automatically follow the naming, code style, type, JSX, import, and formatting patterns enforced by this plugin — reducing lint errors to zero.
-
 ## Need Help?
 
 If you encounter any issues or have questions:

package/docs/rules/NO_GHOST_WRAPPER.md

@@ -0,0 +1,75 @@
+# no-ghost-wrapper
+
+Disallow bare `<div>` and `<span>` elements that have no meaningful attributes.
+
+## Rule Details
+
+This rule flags `<div>` and `<span>` elements that carry zero meaningful attributes — the "ghost wrapper" anti-pattern (also called "Divitis"). These elements add depth to the DOM tree without contributing semantics, styling, behavior, accessibility hooks, or test hooks.
+
+The `key` prop alone does not count as meaningful: `key` is a React-only signal for list reconciliation and carries no structural intent.
+
+### Why?
+
+- **Semantic clarity**: A wrapper without attributes signals that the author has not decided whether the element is structural, presentational, or semantic.
+- **DOM bloat**: Empty wrappers extend the DOM tree, increasing layout work and accessibility-tree noise.
+- **Cognitive load**: Reviewers must guess whether a bare wrapper is intentional or a leftover from refactoring.
+- **Better alternatives exist**: Fragments (`<>...</>`), semantic elements (`<section>`, `<article>`, `<header>`, `<nav>`), or simply unwrapping the children.
+
+## Examples
+
+### Incorrect
+
+```tsx
+<div>x</div>
+<span>text</span>
+<div></div>
+<div> </div>
+<div />
+<span />
+<div key={item.id}>x</div>
+<div>{children}</div>
+```
+
+### Correct
+
+```tsx
+<div className="container">x</div>
+<div data-testid="root">x</div>
+<div role="button">x</div>
+<div aria-label="close">x</div>
+<div ref={ref}>x</div>
+<div onClick={handleClick}>x</div>
+<div id="anchor">x</div>
+<div style={{ color: "red" }}>x</div>
+<div {...props}>x</div>
+<div tabIndex={0}>x</div>
+<section>x</section>
+<article>x</article>
+<>x</>
+```
+
+## What This Rule Checks
+
+The rule fires on a `<div>` or `<span>` opening element when, after filtering out a lone `key` attribute, it has zero remaining attributes (including spread attributes). Self-closing elements (`<div />`, `<span />`) are checked the same way.
+
+Any of the following attributes count as meaningful and silence the rule:
+
+- `className`
+- `style`
+- `id`
+- `ref`
+- `role`
+- `aria-*`
+- `data-*`
+- `tabIndex`
+- Event handlers (`onClick`, `onChange`, etc.)
+- Spread attributes (`{...props}`)
+- Any other JSX attribute except `key`
+
+## When Not To Use It
+
+If your codebase intentionally uses bare `<div>` and `<span>` as structural placeholders, or if you rely on parent CSS selectors that target a fixed wrapper depth.
+
+## Related Rules
+
+- [no-redundant-fragment](NO_REDUNDANT_FRAGMENT.md)

package/docs/rules/NO_REDUNDANT_FRAGMENT.md

@@ -0,0 +1,56 @@
+# no-redundant-fragment
+
+Disallow Fragments that wrap zero or one child.
+
+## Rule Details
+
+This rule flags Fragments (`<>...</>`, `<Fragment>...</Fragment>`, `<React.Fragment>...</React.Fragment>`) that wrap zero or one child. A Fragment is only justified when grouping multiple sibling nodes, or when a `key` prop is required during list iteration.
+
+A Fragment with a single child is structurally equivalent to that child alone. An empty Fragment renders nothing and adds noise to the source.
+
+### Why?
+
+- **Source clarity**: A Fragment around a single child is dead syntax — it tells the reader nothing.
+- **Less noise in the AST**: Devtools, search, and codemods do not have to step over an extra layer.
+- **Forces a decision**: Either the children are siblings (Fragment is the right tool) or they are not (drop it).
+
+## Examples
+
+### Incorrect
+
+```tsx
+<></>
+<>{x}</>
+<><A /></>
+<>text</>
+<Fragment>x</Fragment>
+<React.Fragment>{x}</React.Fragment>
+<React.Fragment></React.Fragment>
+```
+
+### Correct
+
+```tsx
+<>{a}{b}</>
+<><A /><B /></>
+<Fragment>{a}{b}</Fragment>
+<React.Fragment>{a}{b}</React.Fragment>
+
+// key is the legitimate reason to use long-form Fragment:
+<React.Fragment key={item.id}>{item.label}{item.value}</React.Fragment>
+<Fragment key={k}>{x}</Fragment>
+```
+
+## What This Rule Checks
+
+A Fragment is flagged when its meaningful children count is `0` or `1`. JSX text nodes that contain only whitespace are not counted as children.
+
+The rule does not fire on a long-form Fragment (`<Fragment>` or `<React.Fragment>`) that carries a `key` attribute — `key` is the canonical reason long-form Fragment exists, since the shorthand `<>...</>` cannot accept attributes.
+
+## When Not To Use It
+
+If your codebase uses single-child Fragments to keep diffs stable around conditionally-rendered siblings, or if you rely on a build-time transform that depends on the Fragment wrapper.
+
+## Related Rules
+
+- [no-ghost-wrapper](NO_GHOST_WRAPPER.md)