eslint-plugin-nextfriday 4.0.0 → 4.2.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # eslint-plugin-nextfriday
 
+## 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
+
+- [#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

@@ -458,20 +458,26 @@ 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              | ❌      |
 | [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               | ❌      |
 | [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,10 +487,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         | 23        | 63          |
+| `react/recommended`  | error    | 40         | 23        | 63          |
+| `nextjs`             | warn     | 40         | 23        | 63          |
+| `nextjs/recommended` | error    | 40         | 23        | 63          |
 
 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,22 +539,28 @@ Included in `base`, `base/recommended`, and all other presets:
 - `nextfriday/sort-type-alphabetically`
 - `nextfriday/sort-type-required-first`
 
-### JSX Rules (17 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`
 - `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 +583,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/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/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_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)