eslint-plugin-nextfriday 3.2.1 → 4.1.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # 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
+
+- [#122](https://github.com/next-friday/eslint-plugin-nextfriday/pull/122) [`a9c5237`](https://github.com/next-friday/eslint-plugin-nextfriday/commit/a9c52375dfe7d7064ead37c611c680e4c8d6be9f) Thanks [@joetakara](https://github.com/joetakara)! - Breaking changes
+  - Remove `enforce-curly-newline` rule. Use ESLint's built-in `curly: "all"` instead. Consumers should add `"curly": ["error", "all"]` to their ESLint config.
+  - Narrow `no-inline-nested-object` to truly nested structures only. Flat collections (objects of primitive properties, arrays of identifiers/member expressions/primitives) are now allowed inline because Prettier already controls their wrapping via `printWidth`. Eliminates the fix loop with Prettier on cases like `{ allow: [target.utils, target.types, target.constants] }`.
+
+  New rules
+  - Add `prefer-props-with-children`. Reports `children: ReactNode` declarations and recommends `PropsWithChildren<T>`. Included in `react` and `nextjs` presets.
+  - Add `prefer-interface-for-component-props`. Auto-fixes `type FooProps = {...}` to `interface FooProps {...}` in `.tsx` and `.jsx` files. Included in `react` and `nextjs` presets.
+
+  Fixes
+  - `prefer-import-type` skips imports with inline `type` markers, deferring to `no-inline-type-import`.
+  - `prefer-named-param-types` skips React component functions with single non-destructured `Identifier` param, deferring to `prefer-interface-over-inline-types`.
+
 ## 3.2.1
 
 ### Patch Changes

package/README.md

@@ -50,7 +50,7 @@ export default [nextfriday.configs["nextjs/recommended"]];
 
 To use a preset and adjust individual rules, append a second config object after the preset. Later objects override earlier ones, so you can change severity, swap options, or add rules without re-declaring the entire preset.
 
-For example, enforce PascalCase for React components via the `react/recommended` preset (which already runs `nextfriday/jsx-pascal-case` and `nextfriday/enforce-camel-case` as errors), and add a rule override on top:
+For example, start with the `react/recommended` preset (which runs `nextfriday/enforce-camel-case` and `nextfriday/enforce-props-suffix` as errors) and add a rule override on top:
 
 ```js
 import nextfriday from "eslint-plugin-nextfriday";
@@ -60,7 +60,6 @@ export default [
 
   {
     rules: {
-      "nextfriday/jsx-pascal-case": "error",
       "nextfriday/enforce-props-suffix": "error",
       "nextfriday/sort-imports": "warn",
     },
@@ -68,7 +67,7 @@ export default [
 ];
 ```
 
-The first object enables every rule in `react/recommended`. The second object reaffirms `jsx-pascal-case` (already enforced — useful when you want it loud and explicit), enables `enforce-props-suffix`, and downgrades `sort-imports` from error to warning.
+The first object enables every rule in `react/recommended`. The second object reaffirms `enforce-props-suffix` (already enforced — useful when you want it loud and explicit) and downgrades `sort-imports` from error to warning.
 
 ### Manual Configuration
 
@@ -108,10 +107,6 @@ export default [
       "nextfriday/enforce-property-case": "error",
       "nextfriday/no-misleading-constant-case": "error",
 
-      // File Naming
-      "nextfriday/file-kebab-case": "error",
-      "nextfriday/jsx-pascal-case": "error",
-
       // Code Style
       "nextfriday/no-emoji": "error",
       "nextfriday/prefer-destructuring-params": "error",
@@ -130,7 +125,6 @@ export default [
       "nextfriday/no-inline-nested-object": "error",
       "nextfriday/no-inline-return-properties": "error",
       "nextfriday/prefer-async-await": "error",
-      "nextfriday/enforce-curly-newline": "error",
       "nextfriday/no-nested-ternary": "error",
       "nextfriday/prefer-guard-clause": "error",
 
@@ -166,9 +160,6 @@ export default [
       "nextfriday/react-props-destructure": "error",
       "nextfriday/enforce-props-suffix": "error",
       "nextfriday/enforce-readonly-component-props": "error",
-
-      // Next.js
-      "nextfriday/nextjs-require-public-env": "error",
     },
   },
 ];
@@ -388,11 +379,11 @@ Once a directory hits zero, lock it in (step 4). Once the warn-level count hits
 
 When the warn-level preset surfaces hundreds of violations, fix them in this order — high-impact rules catch real bugs, while low-impact rules are style preferences that can wait.
 
-| Tier                                  | Examples                                                                                                                                                                           | Why first                                                                                                                       |
-| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| High — correctness and runtime safety | `no-direct-date`, `no-env-fallback`, `nextjs-require-public-env`, `enforce-readonly-component-props`, `jsx-no-non-component-function`, `enforce-hook-naming`, `no-logic-in-params` | Each violation can mask a bug, leak config, or break React's rules of hooks. Fix before they ship.                              |
-| Medium — structure and naming         | `boolean-naming-prefix`, `enforce-camel-case`, `enforce-constant-case`, `file-kebab-case`, `jsx-pascal-case`, `enforce-props-suffix`, `prefer-import-type`                         | No runtime impact, but inconsistent naming compounds review and onboarding cost. Fix once the high tier is clean.               |
-| Low — formatting and ordering         | `sort-imports`, `sort-exports`, `sort-type-alphabetically`, `jsx-sort-props`, `newline-before-return`, `newline-after-multiline-block`, `no-emoji`                                 | Cosmetic. Most are auto-fixable, so a single `pnpm eslint --fix` pass typically clears the whole codebase. Save these for last. |
+| Tier                                  | Examples                                                                                                                                              | Why first                                                                                                                       |
+| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| High — correctness and runtime safety | `no-direct-date`, `no-env-fallback`, `enforce-readonly-component-props`, `jsx-no-non-component-function`, `enforce-hook-naming`, `no-logic-in-params` | Each violation can mask a bug, leak config, or break React's rules of hooks. Fix before they ship.                              |
+| Medium — structure and naming         | `boolean-naming-prefix`, `enforce-camel-case`, `enforce-constant-case`, `enforce-props-suffix`, `prefer-import-type`                                  | No runtime impact, but inconsistent naming compounds review and onboarding cost. Fix once the high tier is clean.               |
+| Low — formatting and ordering         | `sort-imports`, `sort-exports`, `sort-type-alphabetically`, `jsx-sort-props`, `newline-before-return`, `newline-after-multiline-block`, `no-emoji`    | Cosmetic. Most are auto-fixable, so a single `pnpm eslint --fix` pass typically clears the whole codebase. Save these for last. |
 
 In practice: turn the high tier on as `"error"` first, leave the medium tier as `"warn"` while you migrate, and run the auto-fixers for the low tier in a single dedicated PR.
 
@@ -412,13 +403,6 @@ In practice: turn the high tier on as `"error"` first, leave the medium tier as
 | [enforce-property-case](docs/rules/ENFORCE_PROPERTY_CASE.md)             | Enforce camelCase for unquoted object property keys                   | ❌      |
 | [no-misleading-constant-case](docs/rules/NO_MISLEADING_CONSTANT_CASE.md) | Disallow SCREAMING_SNAKE_CASE in local scope and for dynamic values   | ❌      |
 
-### File Naming Rules
-
-| Rule                                             | Description                                          | Fixable |
-| ------------------------------------------------ | ---------------------------------------------------- | ------- |
-| [file-kebab-case](docs/rules/FILE_KEBAB_CASE.md) | Enforce kebab-case filenames for .ts and .js files   | ❌      |
-| [jsx-pascal-case](docs/rules/JSX_PASCAL_CASE.md) | Enforce PascalCase filenames for .jsx and .tsx files | ❌      |
-
 ### Code Style Rules
 
 | Rule                                                                         | Description                                                            | Fixable |
@@ -441,7 +425,6 @@ In practice: turn the high tier on as `"error"` first, leave the medium tier as
 | [no-inline-nested-object](docs/rules/NO_INLINE_NESTED_OBJECT.md)             | Require nested objects and arrays to span multiple lines               | ✅      |
 | [no-inline-return-properties](docs/rules/NO_INLINE_RETURN_PROPERTIES.md)     | Require return object properties to use shorthand notation             | ❌      |
 | [prefer-async-await](docs/rules/PREFER_ASYNC_AWAIT.md)                       | Enforce async/await over .then() promise chains                        | ❌      |
-| [enforce-curly-newline](docs/rules/ENFORCE_CURLY_NEWLINE.md)                 | Enforce curly braces for multi-line if, forbid for single-line         | ✅      |
 | [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           | ❌      |
 
@@ -458,16 +441,17 @@ In practice: turn the high tier on as `"error"` first, leave the medium tier as
 
 ### Type Pattern Rules
 
-| Rule                                                                                   | Description                                                      | Fixable |
-| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------- |
-| [enforce-type-declaration-order](docs/rules/ENFORCE_TYPE_DECLARATION_ORDER.md)         | Enforce referenced types are declared after their consumer       | ❌      |
-| [no-nested-interface-declaration](docs/rules/NO_NESTED_INTERFACE_DECLARATION.md)       | Disallow inline object types in interface/type properties        | ❌      |
-| [prefer-named-param-types](docs/rules/PREFER_NAMED_PARAM_TYPES.md)                     | Enforce named types for function parameters with object types    | ❌      |
-| [prefer-inline-literal-union](docs/rules/PREFER_INLINE_LITERAL_UNION.md)               | Enforce inlining literal union types for better IDE hover info   | ✅      |
-| [prefer-inline-type-export](docs/rules/PREFER_INLINE_TYPE_EXPORT.md)                   | Require type/interface exports inline at the declaration         | ✅      |
-| [prefer-interface-over-inline-types](docs/rules/PREFER_INTERFACE_OVER_INLINE_TYPES.md) | Enforce interface declarations over inline types for React props | ❌      |
-| [sort-type-alphabetically](docs/rules/SORT_TYPE_ALPHABETICALLY.md)                     | Enforce A-Z sorting of properties within type groups             | ✅      |
-| [sort-type-required-first](docs/rules/SORT_TYPE_REQUIRED_FIRST.md)                     | Enforce required properties before optional in types/interfaces  | ✅      |
+| Rule                                                                                       | Description                                                       | Fixable |
+| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- | ------- |
+| [enforce-type-declaration-order](docs/rules/ENFORCE_TYPE_DECLARATION_ORDER.md)             | Enforce referenced types are declared after their consumer        | ❌      |
+| [no-nested-interface-declaration](docs/rules/NO_NESTED_INTERFACE_DECLARATION.md)           | Disallow inline object types in interface/type properties         | ❌      |
+| [prefer-named-param-types](docs/rules/PREFER_NAMED_PARAM_TYPES.md)                         | Enforce named types for function parameters with object types     | ❌      |
+| [prefer-inline-literal-union](docs/rules/PREFER_INLINE_LITERAL_UNION.md)                   | Enforce inlining literal union types for better IDE hover info    | ✅      |
+| [prefer-inline-type-export](docs/rules/PREFER_INLINE_TYPE_EXPORT.md)                       | Require type/interface exports inline at the declaration          | ✅      |
+| [prefer-interface-for-component-props](docs/rules/PREFER_INTERFACE_FOR_COMPONENT_PROPS.md) | Enforce interface over type alias for component prop declarations | ✅      |
+| [prefer-interface-over-inline-types](docs/rules/PREFER_INTERFACE_OVER_INLINE_TYPES.md)     | Enforce interface declarations over inline types for React props  | ❌      |
+| [sort-type-alphabetically](docs/rules/SORT_TYPE_ALPHABETICALLY.md)                         | Enforce A-Z sorting of properties within type groups              | ✅      |
+| [sort-type-required-first](docs/rules/SORT_TYPE_REQUIRED_FIRST.md)                         | Enforce required properties before optional in types/interfaces   | ✅      |
 
 ### React/JSX Rules
 
@@ -483,46 +467,41 @@ 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               | ❌      |
 | [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                    | ✅      |
 
-### Next.js Rules
-
-| Rule                                                                 | Description                                                   | Fixable |
-| -------------------------------------------------------------------- | ------------------------------------------------------------- | ------- |
-| [nextjs-require-public-env](docs/rules/NEXTJS_REQUIRE_PUBLIC_ENV.md) | Require NEXT*PUBLIC* prefix for env vars in client components | ❌      |
-
 ## Configurations
 
 ### Configuration Presets Overview
 
-| Preset               | Severity | Base Rules | JSX Rules | Next.js Rules | Total Rules |
-| -------------------- | -------- | ---------- | --------- | ------------- | ----------- |
-| `base`               | warn     | 42         | 0         | 0             | 42          |
-| `base/recommended`   | error    | 42         | 0         | 0             | 42          |
-| `react`              | warn     | 42         | 16        | 0             | 58          |
-| `react/recommended`  | error    | 42         | 16        | 0             | 58          |
-| `nextjs`             | warn     | 42         | 16        | 1             | 59          |
-| `nextjs/recommended` | error    | 42         | 16        | 1             | 59          |
+| 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          |
 
-The `nextjs` and `nextjs/recommended` presets ship as an array of two flat-config objects: the rule set above, plus a routing override that disables `nextfriday/file-kebab-case` and `nextfriday/jsx-pascal-case` for files matching `app/**/*.{js,jsx,ts,tsx}`, `src/app/**/*.{js,jsx,ts,tsx}`, `pages/**/*.{js,jsx,ts,tsx}`, and `src/pages/**/*.{js,jsx,ts,tsx}`. Next.js owns the filenames in those directories (`page.tsx`, `layout.tsx`, `route.ts`, `middleware.ts`, etc.), so the plugin steps out of the way. ESLint 9+ flattens nested config arrays automatically, so spreading the preset works as expected.
+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 (42 rules)
+### Base Configuration Rules (40 rules)
 
 Included in `base`, `base/recommended`, and all other presets:
 
 - `nextfriday/boolean-naming-prefix`
 - `nextfriday/enforce-camel-case`
 - `nextfriday/enforce-constant-case`
-- `nextfriday/enforce-curly-newline`
 - `nextfriday/enforce-hook-naming`
 - `nextfriday/enforce-property-case`
 - `nextfriday/enforce-service-naming`
 - `nextfriday/enforce-sorted-destructuring`
 - `nextfriday/enforce-type-declaration-order`
-- `nextfriday/file-kebab-case`
 - `nextfriday/index-export-only`
 - `nextfriday/newline-after-multiline-block`
 - `nextfriday/newline-before-return`
@@ -556,7 +535,7 @@ Included in `base`, `base/recommended`, and all other presets:
 - `nextfriday/sort-type-alphabetically`
 - `nextfriday/sort-type-required-first`
 
-### JSX Rules (16 rules)
+### JSX Rules (19 rules)
 
 Additionally included in `react`, `react/recommended`, `nextjs`, `nextjs/recommended`:
 
@@ -568,21 +547,18 @@ Additionally included in `react`, `react/recommended`, `nextjs`, `nextjs/recomme
 - `nextfriday/jsx-no-non-component-function`
 - `nextfriday/jsx-no-ternary-null`
 - `nextfriday/jsx-no-variable-in-callback`
-- `nextfriday/jsx-pascal-case`
 - `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`
+- `nextfriday/prefer-props-with-children`
 - `nextfriday/react-props-destructure`
 
-### Next.js Only Rules (1 rule)
-
-Additionally included in `nextjs`, `nextjs/recommended` only:
-
-- `nextfriday/nextjs-require-public-env`
-
 ### Severity Levels
 
 - **`base` / `react` / `nextjs`**: All rules set to `"warn"`
@@ -599,16 +575,6 @@ Additionally included in `nextjs`, `nextjs/recommended` only:
 - **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 56 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/agents/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The producer skill (`/grill-with-docs`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/grill-with-docs`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

package/docs/agents/issue-tracker.md

@@ -0,0 +1,22 @@
+# Issue tracker: GitHub
+
+Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.

package/docs/agents/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.

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

@@ -1,62 +1,80 @@
 # no-inline-nested-object
 
-Require nested objects and arrays with multiple properties to span multiple lines.
+Require object or array values that contain further nested objects or arrays to span multiple lines.
 
 ## Rule Details
 
-This rule enforces that when an object property's value is another object or array with more than one element, it should span multiple lines rather than being written inline. Single-property nested objects are allowed inline. This improves readability and makes diffs cleaner when properties are added or removed.
+This rule enforces that when an object property's value is itself an object or array **that contains further nested structures inside**, it must span multiple lines. Flat collections — objects of primitive properties or arrays of simple references — are allowed inline because Prettier already controls their wrapping via `printWidth`.
+
+A "nested structure" is any object or array element/property whose value is another object or array. The rule deliberately ignores depth-1 collections so it does not fight Prettier on simple data and configuration tables.
+
+### Why?
+
+Truly nested structures are easy to misread when collapsed onto a single line, and adding or removing an inner element produces noisy diffs. Flat collections do not have the same problem and are best left to Prettier's line-length logic.
 
 ## Examples
 
 ### Incorrect
 
+<!-- prettier-ignore -->
 ```ts
-const config = {
-  database: { host: "localhost", port: 5432, name: "myapp" },
+const obj = {
+  items: [{ a: 1 }, { b: 2 }],
+};
+```
+
+<!-- prettier-ignore -->
+```ts
+const obj = {
+  matrix: [[1, 2], [3, 4]],
 };
 ```
 
 ```ts
-const routes = {
-  api: { users: "/api/users", posts: "/api/posts" },
-  auth: { login: "/auth/login", logout: "/auth/logout" },
+const obj = {
+  layer: { inner: { leaf: 1 } },
+};
+```
+
+```ts
+const obj = {
+  wrap: { items: [1, 2, 3] },
 };
 ```
 
 ### Correct
 
+<!-- prettier-ignore -->
 ```ts
-const config = {
-  database: { host: "localhost" },
+const obj = {
+  items: [
+    { a: 1 },
+    { b: 2 },
+  ],
 };
 ```
 
 ```ts
-const config = {
-  database: {
-    host: "localhost",
-    port: 5432,
-    name: "myapp",
+const obj = {
+  layer: {
+    inner: { leaf: 1 },
   },
 };
 ```
 
+Flat values stay inline:
+
 ```ts
-const routes = {
-  api: {
-    users: "/api/users",
-    posts: "/api/posts",
-  },
-  auth: {
-    login: "/auth/login",
-    logout: "/auth/logout",
-  },
+const obj = {
+  config: { enabled: true, timeout: 5000 },
+  database: { host: "localhost", port: 5432, name: "myapp" },
 };
 ```
 
 ```ts
-const validationRules = {
-  required: ["name", "email", "password"],
+const obj = {
+  options: ["primary", "foreground", "danger", "outline", "ghost", "link"],
+  allow: [target.utils, target.types, target.constants],
 };
 ```
 
@@ -71,8 +89,8 @@ const initialState = {
 
 ## When Not To Use It
 
-If you prefer compact inline nested objects for all cases, or if your team has different formatting preferences.
+If your team prefers compact single-line nested structures regardless of depth, or if your project has different formatting preferences.
 
 ## Fixable
 
-This rule is auto-fixable. Running ESLint with the `--fix` flag will automatically expand inline nested objects and arrays with multiple properties to multiple lines.
+This rule is auto-fixable. Running ESLint with the `--fix` flag will expand inline collections that contain nested structures onto multiple lines.

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)

package/docs/rules/PREFER_GUARD_CLAUSE.md

@@ -36,12 +36,14 @@ function validate(user) {
 function process(data) {
   if (!data) return [];
   if (!data.items) return [];
+
   return data.items.map(toItem);
 }
 
 function validate(user) {
   if (!user) return null;
   if (!user.isAdmin) return null;
+
   return adminDashboard();
 }
 ```

package/docs/rules/PREFER_IMPORT_TYPE.md

@@ -61,6 +61,10 @@ import { TSESTree } from "@typescript-eslint/utils";
 import type { TSESTree } from "@typescript-eslint/utils";
 ```
 
+## Exceptions
+
+This rule defers to [`no-inline-type-import`](./NO_INLINE_TYPE_IMPORT.md) when an import already contains an inline `type` marker (for example, `import { type Foo } from "x"`). Reporting both rules on the same statement produces overlapping messages and conflicting fixes, so `prefer-import-type` skips the import in that case and lets `no-inline-type-import` produce the canonical fix.
+
 ## When Not To Use It
 
 - If your project doesn't use TypeScript
@@ -69,4 +73,5 @@ import type { TSESTree } from "@typescript-eslint/utils";
 
 ## Related Rules
 
+- [no-inline-type-import](./NO_INLINE_TYPE_IMPORT.md) - Owns the `import { type Foo }` case
 - [@typescript-eslint/consistent-type-imports](https://typescript-eslint.io/rules/consistent-type-imports/) - Similar rule from typescript-eslint