eslint-plugin-jest-formatting 3.0.0 → 4.0.0

package/AGENTS.md

@@ -0,0 +1,110 @@
+# AGENTS.md
+
+Briefing for AI coding agents working with or on `eslint-plugin-jest-formatting`. Everything here is also in [README.md](README.md) and [docs/rules](docs/rules); this is the short version.
+
+## What this plugin does
+
+`eslint-plugin-jest-formatting` provides ESLint rules that require a blank line before and after Jest blocks: `describe`, `test`/`it`, `beforeAll`, `beforeEach`, `afterAll`, `afterEach`, and groups of `expect` statements. That is its whole scope. It does not check test correctness, naming, or structure; [eslint-plugin-jest](https://github.com/jest-community/eslint-plugin-jest) does that, and the two are used together.
+
+Facts that hold for every rule:
+
+- No options. Configure severity only.
+- Autofixable with `eslint --fix`. The fixer only inserts newlines; it never removes or moves code.
+- Only neighbouring statements in the same block are compared. The first statement in a block needs no blank line before it and the last needs none after it. One blank line is enough.
+- A statement counts as a Jest call when it starts with the identifier (`describe(...)`, `describe.each(...)`, `await expect(...)`), not when the identifier appears later (`return expect(...)`, `const p = describe(...)`).
+- Works with ESLint 8, 9, and 10. Flat config (`eslint.config.js`) works on ESLint 8.57, 9, and 10. Legacy `.eslintrc` works on ESLint 8 and 9 only (9 needs `ESLINT_USE_FLAT_CONFIG=false`). Requires Node 22 or later. There is no Jest version requirement: nothing is imported from Jest.
+
+## Rules
+
+| Rule                                | Requires a blank line                                                          | `recommended` | `strict` |
+| ----------------------------------- | ------------------------------------------------------------------------------ | ------------- | -------- |
+| `padding-around-after-all-blocks`   | before and after each `afterAll` call                                          | yes           | yes      |
+| `padding-around-after-each-blocks`  | before and after each `afterEach` call                                         | yes           | yes      |
+| `padding-around-before-all-blocks`  | before and after each `beforeAll` call                                         | yes           | yes      |
+| `padding-around-before-each-blocks` | before and after each `beforeEach` call                                        | yes           | yes      |
+| `padding-around-describe-blocks`    | before and after each `describe`, `fdescribe`, or `xdescribe` block            | yes           | yes      |
+| `padding-around-expect-groups`      | before and after each run of consecutive `expect` statements, not between them | no            | yes      |
+| `padding-around-test-blocks`        | before and after each `test`, `it`, `fit`, `xit`, or `xtest` block             | yes           | yes      |
+| `padding-around-all`                | everything above, as one rule (one report per gap)                             | no            | yes      |
+
+`recommended` enables the six rules marked yes individually. `strict` enables `padding-around-all` only, which covers the same statements plus `expect` groups. Each rule's page in `docs/rules/<rule>.md` has the same sections in the same order: Rule summary, Why, Incorrect examples, Correct examples, Options, Fixability.
+
+## Configuration
+
+Flat config (ESLint 9+, `eslint.config.js`):
+
+```js
+import jestFormatting from 'eslint-plugin-jest-formatting';
+
+export default [
+  jestFormatting.configs['flat/recommended'], // or 'flat/strict'
+];
+```
+
+The flat configs set no `files`, so they apply wherever ESLint already lints. To limit them to test files, spread the config into an object with your own `files` (name the extensions; a bare `**/*.test.*` would also match Jest snapshot files). These patterns cover the same file names as the legacy presets:
+
+```js
+export default [
+  {
+    files: [
+      '**/*{.test,_test,Test,.spec,_spec,Spec}.{js,jsx,mjs,cjs,mts,cts,ts,tsx}',
+      '**/__tests__/**/*.{js,jsx,mjs,cjs,mts,cts,ts,tsx}',
+    ],
+    ...jestFormatting.configs['flat/recommended'],
+  },
+];
+```
+
+Legacy config (`.eslintrc`, ESLint 8 and 9 only), already scoped to common test-file globs:
+
+```json
+{
+  "extends": ["plugin:jest-formatting/recommended"]
+}
+```
+
+Use `"plugin:jest-formatting/strict"` for everything. Individual rules go in `rules` as `"jest-formatting/<rule>": "error"` in either style; flat config also needs `plugins: { 'jest-formatting': jestFormatting }`.
+
+Fixing a tree: `npx eslint --fix .`
+
+## Reading the output
+
+Every report uses one of two messages. `{{token}}` is the Jest identifier that matched (`describe`, `xit`, `expect`, ...). Both are reported on the statement that should have a blank line above it.
+
+- `missingPaddingBefore`: Missing blank line before `{{token}}`. Expected at least one blank line between the previous statement and this `{{token}}` call. Fix: insert an empty line between the statements, before any comments leading the next statement (autofixable with --fix).
+- `missingPaddingAfter`: Missing blank line after `{{token}}`. Expected at least one blank line between the `{{token}}` call above and this statement. Fix: insert an empty line between the statements, before any comments leading the next statement (autofixable with --fix).
+
+The message contains the fix, so there is no need to open the docs to act on it, and `eslint --fix` resolves all of them. When two rules both cover a gap (for example `beforeEach` followed by `describe` under `recommended`), the same line is reported twice, once per rule; one inserted blank line satisfies both.
+
+## Working in this repository
+
+Layout:
+
+- `src/index.ts`: plugin entry. The rule table (`ruleDefinitions`), the preset rule lists, and the legacy and flat config objects. Exported with `export = plugin` (CommonJS).
+- `src/rules/padding.ts`: the single rule factory `createRule`, the shared `messages`, and the statement-matching logic. All eight rules are instances of it.
+- `src/ast-utils.ts`: token and blank-line helpers.
+- `tests/lib/rules/*.spec.js`: one `RuleTester` spec per rule. `tests/lib/ast-utils.spec.ts`: helper tests.
+- `tests/dogfood.spec.js` and `tests/catfood.js`: linted by `yarn lint` through the repo's own `.eslintrc`, which extends `plugin:jest-formatting/recommended`. The spec must pass clean; `catfood.js` has bad padding on purpose and must be ignored, because it does not match the legacy config's test-file globs.
+- `docs/rules/*.md`: one page per rule in the fixed section order above. Each rule's `meta.docs.url` points at its page on the `master` branch.
+- `lib/`: `tsc` output, git-ignored, and the package `main`. Build before loading the plugin.
+
+Commands (Yarn 1, `yarn.lock` is checked in; without Yarn installed, `npx -y yarn@1 <script>` works):
+
+```bash
+yarn install --frozen-lockfile
+yarn test     # tsc build, then jest
+yarn lint     # build, prettier --check, eslint over the repo
+yarn format   # the same, writing fixes
+yarn build    # tsc only, into lib/
+```
+
+CI (`.github/workflows/ci.yml`) runs `yarn test` on each supported Node version and `yarn lint`; a `CI passed` job gates merges to `master`.
+
+Guardrails:
+
+- Rule behaviour is the public contract. Do not change what is reported, where it is reported, or what the fixer writes outside a major release. Rule names, the `recommended`, `strict`, `flat/recommended`, and `flat/strict` configs, and the two message IDs are public API.
+- Never weaken or delete a spec assertion to make a build green; fix the cause.
+- A rule change touches all of: `ruleDefinitions` in `src/index.ts`, its spec in `tests/lib/rules`, its page in `docs/rules`, and the rule lists in `README.md`, `AGENTS.md`, and `llms.txt`.
+- Messages are shared by all rules and live in `src/rules/padding.ts`; specs assert `messageId` and `data.token`, so update them together.
+- Specs use `parserOptions` because the dev dependency is ESLint 8. Under an ESLint 9+ `RuleTester` they need `languageOptions` instead.
+- Releases are manual. Do not run `npm publish` or push `v*` tags.

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## v4.0.0 - November 2, 2026
+
+Lint output is read by AI coding agents as often as by people, and agents act on rule messages literally. This release makes the plugin's messages, documentation and package easier for an agent, or a person, to understand and act on. The same code is reported at the same positions and `eslint --fix` writes the same output as in 3.1.0; the message text is new. Breaking Changes below lists what else can affect an upgrade.
+
+### Added
+
+- Flat config presets for ESLint 9 and 10: `configs['flat/recommended']` and `configs['flat/strict']`. Unlike the legacy presets they set no `files`, so your own config decides which files are linted. The legacy `plugin:jest-formatting/recommended` and `plugin:jest-formatting/strict` configs are unchanged. (#122, #120)
+- Every report carries a `messageId`, `missingPaddingBefore` or `missingPaddingAfter`, and a message that names the matched Jest call, states the expected form, and says how to fix it. For example: Missing blank line before `describe`. Expected at least one blank line between the previous statement and this `describe` call. Fix: insert an empty line between the statements, before any comments leading the next statement (autofixable with --fix).
+- Every rule declares `meta.type`, `meta.docs.description`, `meta.docs.url` and an empty `meta.schema`.
+- Every rule page in `docs/rules` has the same sections: Rule summary, Why, Incorrect examples, Correct examples, Options, Fixability. The "ESLint reports" block under each incorrect example is real output, and a test keeps it that way.
+- `AGENTS.md` and `llms.txt` for AI coding agents, and a README section on using the plugin with them.
+- The plugin object exposes `meta.name` and `meta.version`.
+
+### Breaking Changes
+
+- Requires ESLint 8, 9 or 10 and Node 22 or later. ESLint 7 and earlier, and Node 20 and earlier, are no longer supported. npm warns on an `engines` mismatch; Yarn 1 refuses to install unless `--ignore-engines` is passed.
+- The package exports one plugin object (`module.exports = plugin`) with `rules`, `configs` and `meta`, following eslint-plugin-jest. `require(...)`, `import plugin from ...` and `import { rules, configs } from ...` under TypeScript or a bundler keep working. In a native ESM file such as `eslint.config.mjs`, named imports (`import { configs } from 'eslint-plugin-jest-formatting'`) no longer resolve, and a namespace import (`import * as jestFormatting from ...`) no longer has `rules` or `configs`, so ESLint fails with `Could not find "<rule>" in plugin`. Use the default import.
+- Rules now declare an empty `meta.schema`, so ESLint 8 rejects a rule configured with options, such as `["error", {}]`, and stops with `Configuration for rule ... is invalid`. These options never had any effect (ESLint 9 and later already rejected them); configure severity only.
+- Rules now declare `meta.type: 'layout'`, so `eslint --fix-type layout` applies their fixes. It skipped them in 3.1.0.
+
+### Changed
+
+- The npm package contains only the compiled code, the rule docs, `AGENTS.md`, `llms.txt` and this changelog: 17 files, down from 47. Sources, tests and CI config are no longer shipped. The `module` field, which pointed at an unshipped TypeScript file, is gone.
+
+### Fixed
+
+- Rules load on ESLint 10, where `context.getSourceCode()` was removed.
+
+### Internal
+
+- CI runs on GitHub Actions against Node 22, 24 and 26. The CircleCI configuration, including its tag-triggered publish job, is gone; releases are manual.
+- New tests load the plugin through ESLint's own config loading under flat and legacy config, and check every rule's metadata and documentation page against the built plugin.
+
 ## v3.0.0 - May 4, 2021
 
 ### Breaking Changes

package/README.md

@@ -1,4 +1,4 @@
-[![CircleCI](https://circleci.com/gh/dangreenisrael/eslint-plugin-jest-formatting/tree/master.svg?style=svg)](https://circleci.com/gh/dangreenisrael/eslint-plugin-jest-formatting/tree/master)
+[![CI](https://github.com/dangreenisrael/eslint-plugin-jest-formatting/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/dangreenisrael/eslint-plugin-jest-formatting/actions/workflows/ci.yml)
 ![npm monthly downloads](https://img.shields.io/npm/dm/eslint-plugin-jest-formatting.svg)
 
 # eslint-plugin-jest-formatting
@@ -13,6 +13,8 @@ Like this plugin? [Say thanks with a ⭐️](https://github.com/dangreenisrael/e
 
 ## Installation
 
+Requires Node 22 or later and ESLint 8, 9, or 10. There is no Jest version requirement: the rules match identifiers such as `describe` and `expect` and import nothing from Jest.
+
 You'll first need to install [ESLint](http://eslint.org):
 
 ```
@@ -29,6 +31,37 @@ $ yarn add eslint-plugin-jest-formatting --dev
 
 ## Usage
 
+### Flat config (ESLint 9+, `eslint.config.js`)
+
+```js
+import jestFormatting from 'eslint-plugin-jest-formatting';
+
+export default [
+  // ...your other config objects
+  jestFormatting.configs['flat/recommended'],
+];
+```
+
+`flat/strict` enables every rule via `padding-around-all`. The flat configs do not set `files`, so the rules run on every file ESLint already lints. To scope them to test files, spread the config into your own object (name the extensions explicitly: in flat config a `files` glob opts matching files into linting, and a bare `**/*.test.*` would also match Jest snapshot files). These patterns cover the same file names as the legacy presets:
+
+```js
+export default [
+  {
+    files: [
+      '**/*{.test,_test,Test,.spec,_spec,Spec}.{js,jsx,mjs,cjs,mts,cts,ts,tsx}',
+      '**/__tests__/**/*.{js,jsx,mjs,cjs,mts,cts,ts,tsx}',
+    ],
+    ...jestFormatting.configs['flat/recommended'],
+  },
+];
+```
+
+With CommonJS use `const jestFormatting = require('eslint-plugin-jest-formatting');`.
+
+### Legacy config (`.eslintrc`)
+
+For ESLint 8 and 9 only: ESLint 10 no longer reads `.eslintrc`, and ESLint 9 needs `ESLINT_USE_FLAT_CONFIG=false` to read it.
+
 Add `jest-formatting` to the plugins section of your `.eslintrc` configuration file. You can omit the `eslint-plugin-` prefix:
 
 ```json
@@ -77,6 +110,16 @@ We also support a "strict" settings which enabled all of the rules for you
 - [padding-around-test-blocks](docs/rules/padding-around-test-blocks.md)
 - [padding-around-all](docs/rules/padding-around-all.md)
 
+## Using with AI coding agents
+
+This plugin is built to be driven by coding agents as well as people:
+
+- **Self-describing messages.** Every report says what is missing, where, and how to fix it, for example: `` Missing blank line before `describe`. Expected at least one blank line between the previous statement and this `describe` call. Fix: insert an empty line between the statements, before any comments leading the next statement (autofixable with --fix). `` An agent can act on the message without opening the docs.
+- **Everything is autofixable.** `eslint --fix` resolves every report from this plugin by inserting blank lines. The fixer never removes or reorders code.
+- **Fixed documentation shape.** Each page in [docs/rules](docs/rules) has the same sections in the same order: Rule summary, Why, Incorrect examples, Correct examples, Options, Fixability. Each rule's `meta.docs.url` points at its page.
+- **[AGENTS.md](AGENTS.md)** is a one-page briefing: what the plugin does, every rule in one line, flat and legacy config snippets, and how to build and test.
+- **[llms.txt](llms.txt)** lists the documentation in the [llms.txt](https://llmstxt.org) format for tools that fetch context automatically.
+
 ## Related Projects
 
 ### eslint-plugin-jest

package/docs/rules/padding-around-after-all-blocks.md

@@ -1,25 +1,87 @@
 # padding-around-after-all-blocks
 
-## Rule Details
+- **Rule ID:** `jest-formatting/padding-around-after-all-blocks`
+- **Presets:** `recommended`; covered by `padding-around-all` in `strict`
+- **Fixable:** yes, `eslint --fix` inserts the missing blank lines
+- **Options:** none
+- **Message IDs:** `missingPaddingBefore`, `missingPaddingAfter`
 
-This rule enforces a line of padding before _and_ after 1 or more `afterAll` statements.
+## Rule summary
 
-Note that it doesn't add/enforce a padding line if it's the last statement in its scope.
+Require a blank line before and after every `afterAll` call.
 
-Examples of **incorrect** code for this rule:
+- Matches every statement that starts with the identifier `afterAll`.
+- Only neighbouring statements in the same block are compared: the top level of the file, a `{ ... }` block such as a callback body, or a `switch` case. The first statement in a block needs no blank line before it, and the last needs none after it.
+- One blank line is enough; extra blank lines are never reported.
+- Two consecutive `afterAll` calls also need a blank line between them.
+- A comment on its own line is not a blank line, but a blank line on either side of a comment satisfies the rule.
+
+## Why
+
+`afterAll` runs once, after every test in its scope, so it is part of the suite's skeleton rather than of any one test. A blank line on each side keeps that teardown visually separate from the declarations and tests around it, which makes the setup and teardown structure of a file readable at a glance and keeps cleanup code from being mistaken for part of a neighbouring block.
+
+## Incorrect examples
 
 ```js
-const someText = 'abc';
-afterAll(() => {});
-describe('someText', () => {});
+/* eslint jest-formatting/padding-around-after-all-blocks: "error" */
+const server = startServer();
+afterAll(() => {
+  server.close();
+});
+describe('GET /health', () => {
+  test('responds with 200', async () => {
+    expect(await server.get('/health')).toBe(200);
+  });
+});
+```
+
+ESLint reports:
+
+```text
+3:1  error  Missing blank line before `afterAll`. Expected at least one blank line between the previous statement and this `afterAll` call. Fix: insert an empty line between the statements, before any comments leading the next statement (autofixable with --fix).  jest-formatting/padding-around-after-all-blocks
+6:1  error  Missing blank line after `afterAll`. Expected at least one blank line between the `afterAll` call above and this statement. Fix: insert an empty line between the statements, before any comments leading the next statement (autofixable with --fix).  jest-formatting/padding-around-after-all-blocks
 ```
 
-Examples of **correct** code for this rule:
+## Correct examples
 
 ```js
-const someText = 'abc';
+/* eslint jest-formatting/padding-around-after-all-blocks: "error" */
+const server = startServer();
+
+afterAll(() => {
+  server.close();
+});
+
+describe('GET /health', () => {
+  test('responds with 200', async () => {
+    expect(await server.get('/health')).toBe(200);
+  });
+});
+```
+
+## Options
 
-afterAll(() => {});
+This rule has no options; configure only the severity. Passing options makes ESLint reject the configuration, because the rule's schema is empty.
+
+```js
+// eslint.config.js (flat); the same `rules` entry works in a legacy .eslintrc
+import jestFormatting from 'eslint-plugin-jest-formatting';
 
-describe('someText', () => {});
+export default [
+  {
+    plugins: { 'jest-formatting': jestFormatting },
+    rules: {
+      'jest-formatting/padding-around-after-all-blocks': 'error',
+    },
+  },
+];
 ```
+
+## Fixability
+
+Fixable (`meta.fixable` is `"whitespace"`). `eslint --fix` resolves every report from this rule by inserting a newline after the last token of the statement before the gap, after any comment that trails on the same line, so that a blank line separates the two statements. The fix only adds whitespace; it never removes, moves, or reformats code.
+
+Both messages are reported on the statement that should have a blank line above it. `{{token}}` is the identifier that matched, for example `afterAll`.
+
+- `missingPaddingBefore`, reported on the `afterAll` call: Missing blank line before `{{token}}`. Expected at least one blank line between the previous statement and this `{{token}}` call. Fix: insert an empty line between the statements, before any comments leading the next statement (autofixable with --fix).
+- `missingPaddingAfter`, reported on the statement after the `afterAll` call: Missing blank line after `{{token}}`. Expected at least one blank line between the `{{token}}` call above and this statement. Fix: insert an empty line between the statements, before any comments leading the next statement (autofixable with --fix).

package/docs/rules/padding-around-after-each-blocks.md

@@ -1,29 +1,85 @@
 # padding-around-after-each-blocks
 
-## Rule Details
+- **Rule ID:** `jest-formatting/padding-around-after-each-blocks`
+- **Presets:** `recommended`; covered by `padding-around-all` in `strict`
+- **Fixable:** yes, `eslint --fix` inserts the missing blank lines
+- **Options:** none
+- **Message IDs:** `missingPaddingBefore`, `missingPaddingAfter`
 
-This rule enforces a line of padding before _and_ after 1 or more `afterEach` statements.
+## Rule summary
 
-Note that it doesn't add/enforce a padding line if it's the last statement in its scope.
+Require a blank line before and after every `afterEach` call.
 
-Examples of **incorrect** code for this rule:
+- Matches every statement that starts with the identifier `afterEach`.
+- Only neighbouring statements in the same block are compared: the top level of the file, a `{ ... }` block such as a callback body, or a `switch` case. The first statement in a block needs no blank line before it, and the last needs none after it.
+- One blank line is enough; extra blank lines are never reported.
+- Two consecutive `afterEach` calls also need a blank line between them.
+- A comment on its own line is not a blank line, but a blank line on either side of a comment satisfies the rule.
+
+## Why
+
+`afterEach` runs after every test in its scope. Padding it on both sides makes the per-test cleanup stand out from the tests it applies to and from suite-level code, so a reader scanning the file can see what resets between tests without reading each block's body.
+
+## Incorrect examples
 
 ```js
-const something = 123;
+/* eslint jest-formatting/padding-around-after-each-blocks: "error" */
+const spy = jest.spyOn(console, 'warn');
 afterEach(() => {
-  // more stuff
+  spy.mockClear();
+});
+test('warns once', () => {
+  warnOnce('x');
+  expect(spy).toHaveBeenCalledTimes(1);
 });
-describe('foo', () => {});
 ```
 
-Examples of **correct** code for this rule:
+ESLint reports:
+
+```text
+3:1  error  Missing blank line before `afterEach`. Expected at least one blank line between the previous statement and this `afterEach` call. Fix: insert an empty line between the statements, before any comments leading the next statement (autofixable with --fix).  jest-formatting/padding-around-after-each-blocks
+6:1  error  Missing blank line after `afterEach`. Expected at least one blank line between the `afterEach` call above and this statement. Fix: insert an empty line between the statements, before any comments leading the next statement (autofixable with --fix).  jest-formatting/padding-around-after-each-blocks
+```
+
+## Correct examples
 
 ```js
-const something = 123;
+/* eslint jest-formatting/padding-around-after-each-blocks: "error" */
+const spy = jest.spyOn(console, 'warn');
 
 afterEach(() => {
-  // more stuff
+  spy.mockClear();
+});
+
+test('warns once', () => {
+  warnOnce('x');
+  expect(spy).toHaveBeenCalledTimes(1);
 });
+```
+
+## Options
+
+This rule has no options; configure only the severity. Passing options makes ESLint reject the configuration, because the rule's schema is empty.
+
+```js
+// eslint.config.js (flat); the same `rules` entry works in a legacy .eslintrc
+import jestFormatting from 'eslint-plugin-jest-formatting';
 
-describe('foo', () => {});
+export default [
+  {
+    plugins: { 'jest-formatting': jestFormatting },
+    rules: {
+      'jest-formatting/padding-around-after-each-blocks': 'error',
+    },
+  },
+];
 ```
+
+## Fixability
+
+Fixable (`meta.fixable` is `"whitespace"`). `eslint --fix` resolves every report from this rule by inserting a newline after the last token of the statement before the gap, after any comment that trails on the same line, so that a blank line separates the two statements. The fix only adds whitespace; it never removes, moves, or reformats code.
+
+Both messages are reported on the statement that should have a blank line above it. `{{token}}` is the identifier that matched, for example `afterEach`.
+
+- `missingPaddingBefore`, reported on the `afterEach` call: Missing blank line before `{{token}}`. Expected at least one blank line between the previous statement and this `{{token}}` call. Fix: insert an empty line between the statements, before any comments leading the next statement (autofixable with --fix).
+- `missingPaddingAfter`, reported on the statement after the `afterEach` call: Missing blank line after `{{token}}`. Expected at least one blank line between the `{{token}}` call above and this statement. Fix: insert an empty line between the statements, before any comments leading the next statement (autofixable with --fix).

package/docs/rules/padding-around-all.md

@@ -1,13 +1,106 @@
 # padding-around-all
 
-## Rule Details
+- **Rule ID:** `jest-formatting/padding-around-all`
+- **Presets:** `strict`
+- **Fixable:** yes, `eslint --fix` inserts the missing blank lines
+- **Options:** none
+- **Message IDs:** `missingPaddingBefore`, `missingPaddingAfter`
 
-This is a meta rule that simply enables all of the following rules:
+## Rule summary
 
-- [padding-around-after-all-blocks](padding-around-after-all-blocks.md)
-- [padding-around-after-each-blocks](padding-around-after-each-blocks.md)
-- [padding-around-before-all-blocks](padding-around-before-all-blocks.md)
-- [padding-around-before-each-blocks](padding-around-before-each-blocks.md)
-- [padding-around-expect-groups](padding-around-expect-groups.md)
-- [padding-around-describe-blocks](padding-around-describe-blocks.md)
-- [padding-around-test-blocks](padding-around-test-blocks.md)
+Require a blank line before and after every Jest hook, `describe` block, `test` or `it` block, and group of `expect` statements, as a single rule that combines the seven `padding-around-*` rules.
+
+- Covers exactly the statements matched by [padding-around-after-all-blocks](padding-around-after-all-blocks.md), [padding-around-after-each-blocks](padding-around-after-each-blocks.md), [padding-around-before-all-blocks](padding-around-before-all-blocks.md), [padding-around-before-each-blocks](padding-around-before-each-blocks.md), [padding-around-describe-blocks](padding-around-describe-blocks.md), [padding-around-expect-groups](padding-around-expect-groups.md), and [padding-around-test-blocks](padding-around-test-blocks.md).
+- It is one rule, not an alias for seven: a gap is reported once even where two of the individual rules would both report it, and an `eslint-disable` comment must name `padding-around-all`.
+- Only neighbouring statements in the same block are compared: the top level of the file, a `{ ... }` block such as a callback body, or a `switch` case. The first statement in a block needs no blank line before it, and the last needs none after it.
+- One blank line is enough; extra blank lines are never reported.
+- Consecutive `expect` statements need no blank line between them; every other pair of consecutive Jest calls does.
+- A comment on its own line is not a blank line, but a blank line on either side of a comment satisfies the rule.
+
+## Why
+
+Using one rule for all Jest blocks gives a file a single consistent rhythm: every hook, suite, test, and assertion group is set off by blank lines. It is the rule behind the `strict` configs. Because it is a single rule, a gap between two different kinds of block (for example `beforeEach` followed by `describe`) is reported once, whereas enabling the seven individual rules reports that gap twice. To pad only some kinds of block, enable the individual rules instead of this one.
+
+## Incorrect examples
+
+```js
+/* eslint jest-formatting/padding-around-all: "error" */
+const db = connect();
+beforeAll(() => db.migrate());
+afterAll(() => db.close());
+describe('users', () => {
+  beforeEach(() => db.reset());
+  test('creates a user', async () => {
+    const user = await db.users.create({ name: 'Ada' });
+    expect(user.id).toBeDefined();
+    expect(user.name).toBe('Ada');
+  });
+  test('rejects an empty name', async () => {
+    await expect(db.users.create({ name: '' })).rejects.toThrow();
+  });
+});
+```
+
+ESLint reports:
+
+```text
+3:1  error  Missing blank line before `beforeAll`. Expected at least one blank line between the previous statement and this `beforeAll` call. Fix: insert an empty line between the statements, before any comments leading the next statement (autofixable with --fix).  jest-formatting/padding-around-all
+4:1  error  Missing blank line after `beforeAll`. Expected at least one blank line between the `beforeAll` call above and this statement. Fix: insert an empty line between the statements, before any comments leading the next statement (autofixable with --fix).  jest-formatting/padding-around-all
+5:1  error  Missing blank line before `describe`. Expected at least one blank line between the previous statement and this `describe` call. Fix: insert an empty line between the statements, before any comments leading the next statement (autofixable with --fix).  jest-formatting/padding-around-all
+7:3  error  Missing blank line before `test`. Expected at least one blank line between the previous statement and this `test` call. Fix: insert an empty line between the statements, before any comments leading the next statement (autofixable with --fix).  jest-formatting/padding-around-all
+9:5  error  Missing blank line before `expect`. Expected at least one blank line between the previous statement and this `expect` call. Fix: insert an empty line between the statements, before any comments leading the next statement (autofixable with --fix).  jest-formatting/padding-around-all
+12:3  error  Missing blank line after `test`. Expected at least one blank line between the `test` call above and this statement. Fix: insert an empty line between the statements, before any comments leading the next statement (autofixable with --fix).  jest-formatting/padding-around-all
+```
+
+## Correct examples
+
+```js
+/* eslint jest-formatting/padding-around-all: "error" */
+const db = connect();
+
+beforeAll(() => db.migrate());
+
+afterAll(() => db.close());
+
+describe('users', () => {
+  beforeEach(() => db.reset());
+
+  test('creates a user', async () => {
+    const user = await db.users.create({ name: 'Ada' });
+
+    expect(user.id).toBeDefined();
+    expect(user.name).toBe('Ada');
+  });
+
+  test('rejects an empty name', async () => {
+    await expect(db.users.create({ name: '' })).rejects.toThrow();
+  });
+});
+```
+
+## Options
+
+This rule has no options; configure only the severity. Passing options makes ESLint reject the configuration, because the rule's schema is empty.
+
+```js
+// eslint.config.js (flat); the same `rules` entry works in a legacy .eslintrc
+import jestFormatting from 'eslint-plugin-jest-formatting';
+
+export default [
+  {
+    plugins: { 'jest-formatting': jestFormatting },
+    rules: {
+      'jest-formatting/padding-around-all': 'error',
+    },
+  },
+];
+```
+
+## Fixability
+
+Fixable (`meta.fixable` is `"whitespace"`). `eslint --fix` resolves every report from this rule by inserting a newline after the last token of the statement before the gap, after any comment that trails on the same line, so that a blank line separates the two statements. The fix only adds whitespace; it never removes, moves, or reformats code.
+
+Both messages are reported on the statement that should have a blank line above it. `{{token}}` is the identifier that matched, for example `beforeEach`.
+
+- `missingPaddingBefore`, reported on the Jest call: Missing blank line before `{{token}}`. Expected at least one blank line between the previous statement and this `{{token}}` call. Fix: insert an empty line between the statements, before any comments leading the next statement (autofixable with --fix).
+- `missingPaddingAfter`, reported on the statement after the Jest call: Missing blank line after `{{token}}`. Expected at least one blank line between the `{{token}}` call above and this statement. Fix: insert an empty line between the statements, before any comments leading the next statement (autofixable with --fix).

package/docs/rules/padding-around-before-all-blocks.md

@@ -1,29 +1,83 @@
 # padding-around-before-all-blocks
 
-## Rule Details
+- **Rule ID:** `jest-formatting/padding-around-before-all-blocks`
+- **Presets:** `recommended`; covered by `padding-around-all` in `strict`
+- **Fixable:** yes, `eslint --fix` inserts the missing blank lines
+- **Options:** none
+- **Message IDs:** `missingPaddingBefore`, `missingPaddingAfter`
 
-This rule enforces a line of padding before _and_ after `beforeAll` statements.
+## Rule summary
 
-Note that it doesn't add/enforce a padding line if it's the last statement in its scope.
+Require a blank line before and after every `beforeAll` call.
 
-Examples of **incorrect** code for this rule:
+- Matches every statement that starts with the identifier `beforeAll`.
+- Only neighbouring statements in the same block are compared: the top level of the file, a `{ ... }` block such as a callback body, or a `switch` case. The first statement in a block needs no blank line before it, and the last needs none after it.
+- One blank line is enough; extra blank lines are never reported.
+- Two consecutive `beforeAll` calls also need a blank line between them.
+- A comment on its own line is not a blank line, but a blank line on either side of a comment satisfies the rule.
+
+## Why
+
+`beforeAll` is one-time setup shared by every test in its scope. Separating it with blank lines makes the shared setup easy to spot and keeps it from reading as the first step of whichever test happens to follow it.
+
+## Incorrect examples
 
 ```js
-const something = 123;
-beforeAll(() => {
-  // more stuff
+/* eslint jest-formatting/padding-around-before-all-blocks: "error" */
+let db;
+beforeAll(async () => {
+  db = await connect();
+});
+test('reads a row', async () => {
+  expect(await db.get(1)).toBeDefined();
 });
-describe('foo', () => {});
 ```
 
-Examples of **correct** code for this rule:
+ESLint reports:
+
+```text
+3:1  error  Missing blank line before `beforeAll`. Expected at least one blank line between the previous statement and this `beforeAll` call. Fix: insert an empty line between the statements, before any comments leading the next statement (autofixable with --fix).  jest-formatting/padding-around-before-all-blocks
+6:1  error  Missing blank line after `beforeAll`. Expected at least one blank line between the `beforeAll` call above and this statement. Fix: insert an empty line between the statements, before any comments leading the next statement (autofixable with --fix).  jest-formatting/padding-around-before-all-blocks
+```
+
+## Correct examples
 
 ```js
-const something = 123;
+/* eslint jest-formatting/padding-around-before-all-blocks: "error" */
+let db;
+
+beforeAll(async () => {
+  db = await connect();
+});
 
-beforeAll(() => {
-  // more stuff
+test('reads a row', async () => {
+  expect(await db.get(1)).toBeDefined();
 });
+```
+
+## Options
+
+This rule has no options; configure only the severity. Passing options makes ESLint reject the configuration, because the rule's schema is empty.
+
+```js
+// eslint.config.js (flat); the same `rules` entry works in a legacy .eslintrc
+import jestFormatting from 'eslint-plugin-jest-formatting';
 
-describe('foo', () => {});
+export default [
+  {
+    plugins: { 'jest-formatting': jestFormatting },
+    rules: {
+      'jest-formatting/padding-around-before-all-blocks': 'error',
+    },
+  },
+];
 ```
+
+## Fixability
+
+Fixable (`meta.fixable` is `"whitespace"`). `eslint --fix` resolves every report from this rule by inserting a newline after the last token of the statement before the gap, after any comment that trails on the same line, so that a blank line separates the two statements. The fix only adds whitespace; it never removes, moves, or reformats code.
+
+Both messages are reported on the statement that should have a blank line above it. `{{token}}` is the identifier that matched, for example `beforeAll`.
+
+- `missingPaddingBefore`, reported on the `beforeAll` call: Missing blank line before `{{token}}`. Expected at least one blank line between the previous statement and this `{{token}}` call. Fix: insert an empty line between the statements, before any comments leading the next statement (autofixable with --fix).
+- `missingPaddingAfter`, reported on the statement after the `beforeAll` call: Missing blank line after `{{token}}`. Expected at least one blank line between the `{{token}}` call above and this statement. Fix: insert an empty line between the statements, before any comments leading the next statement (autofixable with --fix).