@crescware/eslint-plugin-crescware-single-behavior-per-test 0.0.1

package/README.md

@@ -0,0 +1,157 @@
+# @crescware/eslint-plugin-crescware-single-behavior-per-test
+
+An ESLint-compatible rule, run through [oxlint](https://oxc.rs/docs/guide/usage/linter)'s `jsPlugins`, that forbids writing more than one top-level `expect()` in a single `test()` / `it()` — and, instead of merely banning it, tells you exactly how to fix it.
+
+## Why
+
+A test should verify a single behavior, but agents and humans alike pile several `expect`s into one test. Plain prose (CLAUDE.md, review comments) does not stop this because prose has no binding force — it can be ignored. A lint rule does: it fails the edit loop and the build.
+
+But a bare ban (e.g. `max-expects: 1`) is weak. If it only says "no" without showing the way out, the reader optimizes for the cheapest way to clear the error — commenting out one `expect`. A ban with no exit is not a norm. This rule carries the exit in the error message itself. The message is written as a prompt for the reader (today, usually a coding agent): it names the concrete next edit, and for the one genuinely undecidable case it asks rather than commands.
+
+The ban is the floor; the guidance rides on top of it. The severity is always `error`.
+
+## Install
+
+```sh
+pnpm add -D @crescware/eslint-plugin-crescware-single-behavior-per-test
+```
+
+## Usage
+
+Register the plugin in your `.oxlintrc.json` and enable the rule:
+
+```json
+{
+  "jsPlugins": ["@crescware/eslint-plugin-crescware-single-behavior-per-test"],
+  "rules": {
+    "crescware-single-behavior-per-test/single-behavior-per-test": "error"
+  }
+}
+```
+
+## What it reports
+
+The rule counts the **direct** `expect()` assertions in a `test` / `it` callback — the ones written as statements directly in the callback body. When there are two or more, it classifies the test by _what varies between the assertions_ and emits one of these verdicts. Each message is either an assertion (the fix is determined by the syntax) or a question (the syntax cannot decide).
+
+### consolidate (assertion)
+
+Several fields of the **same object** are asserted separately. Compare the object once.
+
+```ts
+// reported
+test("compute result", () => {
+  const r = compute();
+  expect(r.status).toBe("ok");
+  expect(r.code).toBe(200);
+});
+
+// fix: one exhaustive toEqual (list every field; no partial-match matcher)
+test("compute result", () => {
+  expect(compute()).toEqual({ status: "ok", code: 200 });
+});
+```
+
+### split-by-act (assertion)
+
+A state change (assignment, mutation, `await`, or a call on the value under test) sits **between** assertions. The before- and after-states are two behaviors.
+
+```ts
+// reported
+test("counter", () => {
+  const c = new Counter();
+  expect(c.value).toBe(0);
+  c.increment();
+  expect(c.value).toBe(1);
+});
+
+// fix: split at the Act into two tests, each with its own Arrange/Act
+```
+
+### split-by-heterogeneity (assertion)
+
+The matchers or the asserted shapes differ — the test checks more than one contract.
+
+```ts
+// reported (a value contract and an error contract)
+test("parse", () => {
+  expect(parse("x")).toEqual({ ok: true });
+  expect(parseThrows).toThrow();
+});
+
+// fix: one test() per contract
+```
+
+### each-or-split (question)
+
+The **same operation** is called with only the inputs changing. Syntax cannot tell whether these are the same claim over different data (→ `test.each`) or different contracts (→ split), so the rule asks and hands you the criterion: restate each case as one sentence — same sentence with different values means `test.each`, a different claim means split.
+
+```ts
+// reported — you decide test.each vs split
+test("add", () => {
+  expect(add(1, 2)).toBe(3);
+  expect(add(3, 4)).toBe(7);
+});
+```
+
+### loop-each (assertion)
+
+Assertions run inside a loop, an iteration callback (`forEach` / `map` / …), or a repeated call to a local assertion helper — a hand-rolled parametrized test. A loop applies an identical body per item, so this is unambiguously `test.each` (and `test.each` reports _which_ case failed, where a loop stops at the first).
+
+```ts
+// reported
+test("all positive", () => {
+  for (const x of items) {
+    expect(x).toBeGreaterThan(0);
+  }
+});
+
+// fix
+test.each(items)("%s is positive", (x) => {
+  expect(x).toBeGreaterThan(0);
+});
+```
+
+### generic (question)
+
+When the exit cannot be named — a computed matcher, an unusual receiver, different objects, an exact duplicate, mismatched call arguments — the ban still holds and the message hands you the four-branch self-diagnosis checklist so you can route the fix yourself.
+
+## Scope
+
+- Only **direct** assertions are classified. Assertions in a loop / iteration callback / repeated local helper are routed to `loop-each`; assertions behind a cross-file or imported helper are a static-analysis blind spot and are not counted.
+- Modifier and async chains are understood: `expect(x).not.toBe(...)`, `expect(x).resolves.toBe(...)`, `await expect(x).resolves.toBe(...)`, `expect.soft(x).toBe(...)`.
+- `test`, `it`, `it.only`, and `test.each(table)(...)` callbacks are recognized.
+- The rule never autofixes — a lazy set of partial assertions cannot be mechanically rebuilt into an exhaustive `toEqual` — it reports only.
+
+## Companion: `no-restricted-matchers`
+
+The `consolidate` fix asks for an exhaustive `toEqual` and forbids partial-match matchers (`toMatchObject` etc.), because a field you omit goes unchecked. This rule states that in prose but does not enforce it; pair it with your test framework's `no-restricted-matchers` to give that prohibition real teeth. The two cooperate loosely and toggle independently.
+
+## Stack
+
+- **Runtime**: Node.js 24 (via [mise](https://mise.jdx.dev/))
+- **Package manager**: pnpm (via corepack)
+- **Language**: TypeScript ([native preview](https://github.com/microsoft/typescript-go))
+- **Test**: [Vitest](https://vitest.dev/) (fixture integration tests that run oxlint over `fixtures/cases`)
+- **Lint**: [oxlint](https://oxc.rs/docs/guide/usage/linter) (the repo dogfoods this very rule)
+- **Format**: [oxfmt](https://github.com/oxc-project/oxc)
+- **Unused code**: [Knip](https://knip.dev/)
+
+## Setup
+
+```sh
+mise install
+corepack enable
+pnpm install
+```
+
+## Scripts
+
+| Command            | Description                              |
+| ------------------ | ---------------------------------------- |
+| `pnpm build`       | Compile `src` to `dist`                  |
+| `pnpm check`       | Run all checks (types, lint, knip, test) |
+| `pnpm check:types` | Type check                               |
+| `pnpm check:lint`  | Lint and format check                    |
+| `pnpm check:knip`  | Unused files/exports check               |
+| `pnpm test`        | Run fixture integration tests            |
+| `pnpm format`      | Fix lint and format                      |

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+type ReportDescriptor = {
+    message: string;
+    node: unknown;
+};
+type RuleContext = {
+    report: (descriptor: ReportDescriptor) => void;
+};
+type Visitor = Record<string, (node: never) => void>;
+declare const plugin: {
+    meta: {
+        name: string;
+    };
+    rules: {
+        "single-behavior-per-test": {
+            meta: {
+                type: string;
+                docs: {
+                    description: string;
+                };
+                schema: never[];
+            };
+            create(context: RuleContext): Visitor;
+        };
+    };
+};
+export default plugin;

package/dist/index.js

@@ -0,0 +1,683 @@
+// ---------------------------------------------------------------------------
+// Shared AST helpers
+// ---------------------------------------------------------------------------
+// The callee identifiers whose callback bodies this rule treats as a test.
+const TEST_CALLEES = new Set(["test", "it"]);
+// Method names that conventionally mutate their receiver. A call to one of these
+// between assertions is treated as an Act regardless of the receiver.
+const MUTATING_METHODS = new Set([
+    "push",
+    "pop",
+    "shift",
+    "unshift",
+    "splice",
+    "sort",
+    "reverse",
+    "fill",
+    "copyWithin",
+    "set",
+    "delete",
+    "add",
+    "clear",
+    "dispatch",
+]);
+// Loop statements whose body, if it asserts, is a hand-rolled parametrized test.
+const LOOP_TYPES = new Set([
+    "ForStatement",
+    "ForOfStatement",
+    "ForInStatement",
+    "WhileStatement",
+    "DoWhileStatement",
+]);
+// Array iteration methods whose callback, if it asserts, is the same anti-pattern
+// as a loop (iterating assertions over data instead of using test.each).
+const ITER_METHODS = new Set([
+    "forEach",
+    "map",
+    "flatMap",
+    "filter",
+    "reduce",
+    "reduceRight",
+    "some",
+    "every",
+    "find",
+    "findIndex",
+]);
+// `await x` -> `x`; anything else is returned unchanged.
+const unwrapAwait = (node) => {
+    return node.type === "AwaitExpression"
+        ? node.argument
+        : node;
+};
+// `expect(actual)` and its dotted forms (`expect.soft(actual)`): a call whose
+// callee is the identifier `expect`, or a member access on it. This anchor is
+// what separates a real assertion from an unrelated `foo.toBe(...)`.
+const isExpectCall = (node) => {
+    if (node.type !== "CallExpression") {
+        return false;
+    }
+    const callee = node.callee;
+    if (callee.type === "Identifier") {
+        return callee.name === "expect";
+    }
+    if (callee.type === "MemberExpression") {
+        const object = callee.object;
+        return (object.type === "Identifier" && object.name === "expect");
+    }
+    return false;
+};
+// The identifier at the root of a call's callee, seen through member and call
+// layers: `test(...)` -> "test", `it.only(...)` -> "it", and
+// `test.each(table)(...)` -> "test". Returns null when the callee bottoms out in
+// something other than an identifier.
+const rootCalleeName = (call) => {
+    let current = call.callee;
+    while (true) {
+        if (current.type === "Identifier") {
+            return current.name;
+        }
+        if (current.type === "MemberExpression") {
+            current = current.object;
+            continue;
+        }
+        if (current.type === "CallExpression") {
+            current = current.callee;
+            continue;
+        }
+        return null;
+    }
+};
+// The first argument that is an arrow / function expression: the test body.
+// `test.each(table)(name, cb)` keeps the callback on the outer call, so this
+// finds it there too.
+const testCallback = (call) => {
+    for (const arg of call.arguments) {
+        if (arg.type === "ArrowFunctionExpression" ||
+            arg.type === "FunctionExpression") {
+            return arg;
+        }
+    }
+    return null;
+};
+// The deepest object identifier of a member chain: `a.b.c` -> "a", `a` -> "a".
+// Returns null when the chain bottoms out in something else (a call, `this`).
+const memberRoot = (node) => {
+    let current = node;
+    while (current.type === "MemberExpression") {
+        current = current.object;
+    }
+    return current.type === "Identifier" ? current.name : null;
+};
+const readableProperty = (node) => {
+    if (node.type === "Identifier") {
+        return node.name;
+    }
+    if (node.type === "Literal") {
+        const literal = node;
+        return literal.raw ?? String(literal.value);
+    }
+    return "#prop";
+};
+// A readable name for a callee / target: `foo` -> "foo", `obj.method` ->
+// "obj.method", `arr[0]` -> "arr[0]". Exotic forms collapse to "…".
+const readable = (node) => {
+    if (node.type === "Identifier") {
+        return node.name;
+    }
+    if (node.type === "MemberExpression") {
+        const member = node;
+        if (member.computed) {
+            return `${readable(member.object)}[${readableProperty(member.property)}]`;
+        }
+        return `${readable(member.object)}.${readableProperty(member.property)}`;
+    }
+    return "…";
+};
+// A structural fingerprint of a node. Literal *values* are dropped but
+// identifier and property *names* are kept, so `add(1, 2)` and `add(3, 4)` share
+// a key (same shape, different data) while `r.a` and `r.b` do not. With
+// `keepValues`, literal values are kept too, which distinguishes "same shape,
+// different values" from an exact duplicate.
+const nodeKey = (node, keepValues) => {
+    switch (node.type) {
+        case "Identifier": {
+            return `Id:${node.name}`;
+        }
+        case "Literal": {
+            const literal = node;
+            return keepValues ? `Lit:${literal.raw ?? String(literal.value)}` : "Lit";
+        }
+        case "TemplateLiteral": {
+            const template = node;
+            const parts = template.expressions
+                .map((expression) => nodeKey(expression, keepValues))
+                .join(",");
+            return `Tpl(${parts})`;
+        }
+        case "MemberExpression": {
+            const member = node;
+            const property = member.computed
+                ? `[${nodeKey(member.property, keepValues)}]`
+                : `.${readableProperty(member.property)}`;
+            return `${nodeKey(member.object, keepValues)}${property}`;
+        }
+        case "CallExpression": {
+            const call = node;
+            return `${nodeKey(call.callee, keepValues)}(${tupleKey(call.arguments, keepValues)})`;
+        }
+        case "ArrayExpression": {
+            const array = node;
+            const elements = array.elements
+                .map((element) => element === null ? "Hole" : nodeKey(element, keepValues))
+                .join(",");
+            return `[${elements}]`;
+        }
+        case "ObjectExpression": {
+            const object = node;
+            const properties = object.properties
+                .map((property) => nodeKey(property, keepValues))
+                .join(",");
+            return `{${properties}}`;
+        }
+        case "Property": {
+            const property = node;
+            const key = property.computed
+                ? `[${nodeKey(property.key, keepValues)}]`
+                : readableProperty(property.key);
+            return `${key}:${nodeKey(property.value, keepValues)}`;
+        }
+        case "SpreadElement": {
+            return `...${nodeKey(node.argument, keepValues)}`;
+        }
+        case "UnaryExpression": {
+            const unary = node;
+            return `${unary.operator}${nodeKey(unary.argument, keepValues)}`;
+        }
+        default: {
+            return node.type;
+        }
+    }
+};
+const tupleKey = (nodes, keepValues) => {
+    return nodes.map((node) => nodeKey(node, keepValues)).join(",");
+};
+const hasSpread = (nodes) => {
+    return nodes.some((node) => node.type === "SpreadElement");
+};
+// `items.forEach(...)`, `items.map(...)`, etc.: a call whose callee is one of the
+// iteration methods.
+const isIterationCall = (node) => {
+    if (node.type !== "CallExpression") {
+        return false;
+    }
+    const callee = node.callee;
+    if (callee.type !== "MemberExpression") {
+        return false;
+    }
+    const member = callee;
+    return (!member.computed &&
+        member.property.type === "Identifier" &&
+        ITER_METHODS.has(member.property.name));
+};
+// Whether an arbitrary AST subtree contains an `expect(...)` anchor. Walks the
+// real node objects generically (skipping the `parent` back-reference to avoid
+// cycles) so it works on nodes whose shape this file does not model.
+const containsExpectCall = (value) => {
+    if (value === null || typeof value !== "object") {
+        return false;
+    }
+    if (Array.isArray(value)) {
+        return value.some((item) => containsExpectCall(item));
+    }
+    const record = value;
+    if (typeof record["type"] === "string" && isExpectCall(value)) {
+        return true;
+    }
+    for (const key of Object.keys(record)) {
+        if (key === "parent") {
+            continue;
+        }
+        if (containsExpectCall(record[key])) {
+            return true;
+        }
+    }
+    return false;
+};
+// Whether the test body iterates assertions: a loop, or an iteration-method
+// callback, whose subtree contains an `expect(...)`. That is a hand-rolled
+// parametrized test and should become test.each.
+const hasLoopAssertion = (value) => {
+    if (value === null || typeof value !== "object") {
+        return false;
+    }
+    if (Array.isArray(value)) {
+        return value.some((item) => hasLoopAssertion(item));
+    }
+    const record = value;
+    const type = record["type"];
+    if (typeof type === "string") {
+        if (LOOP_TYPES.has(type) && containsExpectCall(value)) {
+            return true;
+        }
+        if (isIterationCall(value) && containsExpectCall(value)) {
+            return true;
+        }
+    }
+    for (const key of Object.keys(record)) {
+        if (key === "parent") {
+            continue;
+        }
+        if (hasLoopAssertion(record[key])) {
+            return true;
+        }
+    }
+    return false;
+};
+// The names of locally-declared functions whose body asserts (`const check =
+// (v) => expect(v)...`, `function check() { expect... }`). Calling such a helper
+// repeatedly is the same hand-rolled parametrization as a loop.
+const assertingHelperNames = (statements) => {
+    const names = new Set();
+    for (const statement of statements) {
+        if (statement.type === "FunctionDeclaration") {
+            const fn = statement;
+            if (fn.id !== null &&
+                fn.id.type === "Identifier" &&
+                containsExpectCall(statement)) {
+                names.add(fn.id.name);
+            }
+            continue;
+        }
+        if (statement.type === "VariableDeclaration") {
+            for (const declarator of statement
+                .declarations) {
+                if (declarator.type !== "VariableDeclarator") {
+                    continue;
+                }
+                const declared = declarator;
+                const init = declared.init;
+                if (init !== null &&
+                    (init.type === "ArrowFunctionExpression" ||
+                        init.type === "FunctionExpression") &&
+                    declared.id.type === "Identifier" &&
+                    containsExpectCall(init)) {
+                    names.add(declared.id.name);
+                }
+            }
+        }
+    }
+    return names;
+};
+// Whether an asserting local helper is invoked two or more times as direct
+// statements: the helper form of a parametrized test.
+const hasRepeatedHelperAssertion = (body) => {
+    const helpers = assertingHelperNames(body.body);
+    if (helpers.size === 0) {
+        return false;
+    }
+    const counts = new Map();
+    for (const statement of body.body) {
+        if (statement.type !== "ExpressionStatement") {
+            continue;
+        }
+        const expression = unwrapAwait(statement.expression);
+        if (expression.type !== "CallExpression") {
+            continue;
+        }
+        const callee = expression.callee;
+        if (callee.type !== "Identifier") {
+            continue;
+        }
+        const name = callee.name;
+        if (!helpers.has(name)) {
+            continue;
+        }
+        counts.set(name, (counts.get(name) ?? 0) + 1);
+    }
+    for (const count of counts.values()) {
+        if (count >= 2) {
+            return true;
+        }
+    }
+    return false;
+};
+const baseShapeOf = (base) => {
+    if (base === undefined) {
+        return { kind: "other" };
+    }
+    // `r?.a` parses as a ChainExpression wrapping the (optional) member access.
+    const node = base.type === "ChainExpression"
+        ? base.expression
+        : base;
+    if (node.type === "Identifier") {
+        return { kind: "identifier", root: node.name };
+    }
+    if (node.type === "CallExpression") {
+        const call = node;
+        return { kind: "call", calleeNode: call.callee, argsNode: call.arguments };
+    }
+    if (node.type === "MemberExpression") {
+        const accessPath = [];
+        let computed = false;
+        let current = node;
+        while (current.type === "MemberExpression") {
+            const member = current;
+            if (member.computed) {
+                // A dynamic field (`r[i]`) has no statically known name, so we cannot
+                // safely assert a consolidate; treat the whole base as unclassifiable.
+                computed = true;
+            }
+            else {
+                accessPath.unshift(readableProperty(member.property));
+            }
+            current = member.object;
+        }
+        if (current.type !== "Identifier" || computed) {
+            return { kind: "other" };
+        }
+        return { kind: "member", root: current.name, accessPath };
+    }
+    return { kind: "other" };
+};
+// Parse `expect(base).<not?>.<resolves|rejects?>.matcher(args)` into a record.
+// Returns null when the expression is not a matcher call anchored at expect
+// (e.g. a bare `expect(x)` with no matcher), so such a statement neither counts
+// as a direct assertion nor pollutes routing.
+const parseExpectChain = (expression) => {
+    const root = unwrapAwait(expression);
+    if (root.type !== "CallExpression") {
+        return null;
+    }
+    const matcherCall = root;
+    const callee = matcherCall.callee;
+    if (callee.type !== "MemberExpression") {
+        return null;
+    }
+    const matcherMember = callee;
+    let matcherName;
+    if (matcherMember.computed) {
+        matcherName = null;
+    }
+    else if (matcherMember.property.type === "Identifier") {
+        matcherName = matcherMember.property.name;
+    }
+    else {
+        matcherName = null;
+    }
+    let negation = false;
+    let modifier = null;
+    let current = matcherMember.object;
+    while (current.type === "MemberExpression") {
+        const member = current;
+        if (!member.computed && member.property.type === "Identifier") {
+            const name = member.property.name;
+            if (name === "not") {
+                negation = true;
+            }
+            else if (name === "resolves" || name === "rejects") {
+                modifier = name;
+            }
+        }
+        current = member.object;
+    }
+    if (!isExpectCall(current)) {
+        return null;
+    }
+    const base = current.arguments[0];
+    return {
+        matcherName,
+        negation,
+        modifier,
+        matcherCall,
+        baseShape: baseShapeOf(base),
+    };
+};
+// ---------------------------------------------------------------------------
+// Act detection (Step 0)
+// ---------------------------------------------------------------------------
+// A statement that changes observable state, used to detect "assert, act,
+// assert" inside one test. Conservative on calls: a bare function call is NOT an
+// Act (it may be pure logging), but a method call IS an Act when it either names
+// a known mutating method or is invoked on the value under test (e.g.
+// `counter.increment()` while the test asserts `counter.value`).
+const isActStatement = (statement, underTestRoots) => {
+    if (statement.type !== "ExpressionStatement") {
+        return false;
+    }
+    const expression = statement.expression;
+    if (expression.type === "AwaitExpression" ||
+        expression.type === "AssignmentExpression" ||
+        expression.type === "UpdateExpression") {
+        return true;
+    }
+    if (expression.type !== "CallExpression") {
+        return false;
+    }
+    const callee = expression.callee;
+    if (callee.type !== "MemberExpression") {
+        return false;
+    }
+    const member = callee;
+    if (!member.computed &&
+        member.property.type === "Identifier" &&
+        MUTATING_METHODS.has(member.property.name)) {
+        return true;
+    }
+    const root = memberRoot(member.object);
+    return root !== null && underTestRoots.has(root);
+};
+const actDescription = (statement) => {
+    const expression = statement.expression;
+    if (expression.type === "CallExpression") {
+        return `${readable(expression.callee)}()`;
+    }
+    if (expression.type === "AwaitExpression") {
+        const argument = expression.argument;
+        if (argument.type === "CallExpression") {
+            return `await ${readable(argument.callee)}()`;
+        }
+        return "an await";
+    }
+    if (expression.type === "AssignmentExpression") {
+        return `${readable(expression.left)} = …`;
+    }
+    if (expression.type === "UpdateExpression") {
+        const update = expression;
+        return `${readable(update.argument)}${update.operator}`;
+    }
+    return "a state change";
+};
+// ---------------------------------------------------------------------------
+// Messages: each carries the fix as a prompt for the reader (a coding agent),
+// an evaluable criterion, and a guard against the cheap dodge of deleting an
+// assertion to silence the rule.
+// ---------------------------------------------------------------------------
+const consolidateMessage = (root, fields) => {
+    return `This test asserts ${fields.length} fields of the same object '${root}' (${fields.join(", ")}) with separate expect() calls. Replace them with ONE exhaustive 'expect(${root}).toEqual({ ... })' that lists every field, and delete the individual expect() statements. A dotted field denotes nesting ('meta.id' becomes { meta: { id: ... } }). Do not use a partial-match matcher (toMatchObject etc.): a field you omit would go unchecked. This is not a split and not test.each — it is one object compared once.`;
+};
+const splitByActMessage = (description) => {
+    return `This test asserts state both before and after a change (${description}) in the same test, so it verifies two behaviors. Criterion: name what each side guarantees — the first the state before ${description}, the second its effect; if both guarantees matter, they are two tests. Split into separate test() calls at that boundary, giving the second its own Arrange/Act; never leave an empty test, and do not just delete the before-state assertion to silence this. The problem is not the number of expects but the Act between them. This is not a toEqual consolidation.`;
+};
+const splitByHeterogeneityMessage = (summary) => {
+    return `This test mixes assertions of different shapes (${summary}), so it verifies more than one contract. Criterion: each distinct shape is its own contract; give each its own test() with its own setup. Do not delete the odd assertion to make the shapes match — that silences the check instead of restoring single behavior. This is not a toEqual consolidation and not test.each.`;
+};
+const eachOrSplitMessage = (operation, caseCount) => {
+    return `This test calls the same operation '${operation}' ${caseCount} times with only the inputs changing. Syntax cannot decide the fix, so this is a question, not a verdict. Option 1: if these are the same logic with different data, rewrite as test.each. Option 2: if they assert different contracts (e.g. normal vs boundary/error), split into separate test() calls. Criterion: restate each case as one sentence — same sentence with different values means test.each, a different claim means split. Either way keep every case; do not clear this by deleting cases down to one. You, who know the intent, decide.`;
+};
+const genericMessage = (count) => {
+    return `This test makes ${count} top-level expect() assertions, but a test must verify a single behavior. The exit could not be named automatically, so keep the ban and pick the fix with this checklist: (1) Is there a state change (assignment, mutation, await, or a call on the value under test) between assertions? Split into separate tests at that boundary. (2) Do the matchers or asserted shapes differ? Split into one test per contract. (3) Are these different fields of the same object? Replace them with one exhaustive toEqual (no partial match). (4) Is it the same operation with only the inputs changing? Syntax cannot decide this one — restate each case as a sentence: the same sentence with different values suggests test.each, a different claim suggests split; ask, do not guess. Do not silence this by deleting an assertion.`;
+};
+const loopEachMessage = () => {
+    return `This test runs the same assertion logic over several inputs by hand — via a loop, an iteration callback, or a repeated call to a local assertion helper. That is a hand-rolled parametrized test. Rewrite it as test.each(cases)(name, (case) => { ... }) so every case becomes a named, independently-reported test — a loop or repeated call stops at the first failure and hides which input failed. This is parametrization, not a consolidation or a split.`;
+};
+// A human description of each occurrence's shape, used to explain a
+// heterogeneity split: "toEqual on parse() vs toThrow on errs".
+const shapeSummary = (occurrences) => {
+    const describe = (occurrence) => {
+        const matcher = `${occurrence.negation ? "not." : ""}${occurrence.modifier !== null ? `${occurrence.modifier}.` : ""}${occurrence.matcherName ?? "?"}`;
+        const shape = occurrence.baseShape;
+        let receiver;
+        if (shape.kind === "call") {
+            receiver = `${readable(shape.calleeNode)}()`;
+        }
+        else if (shape.kind === "member") {
+            receiver = [shape.root, ...shape.accessPath].join(".");
+        }
+        else if (shape.kind === "identifier") {
+            receiver = shape.root;
+        }
+        else {
+            receiver = "an expression";
+        }
+        return `${matcher} on ${receiver}`;
+    };
+    const seen = new Set();
+    const labels = [];
+    for (const occurrence of occurrences) {
+        const label = describe(occurrence);
+        if (!seen.has(label)) {
+            seen.add(label);
+            labels.push(label);
+        }
+    }
+    return labels.join(" vs ");
+};
+// ---------------------------------------------------------------------------
+// routeTest: the heuristic router. Returns the message to report, or null when
+// the test is not a violation (0 or 1 direct expect).
+// ---------------------------------------------------------------------------
+const routeTest = (body) => {
+    // A loop / iteration callback that asserts, or an asserting local helper
+    // called repeatedly, is a hand-rolled parametrized test; route it to test.each
+    // before counting direct expects.
+    if (hasLoopAssertion(body) || hasRepeatedHelperAssertion(body)) {
+        return loopEachMessage();
+    }
+    const statements = body.body;
+    const entries = [];
+    statements.forEach((statement, index) => {
+        if (statement.type !== "ExpressionStatement") {
+            return;
+        }
+        const occurrence = parseExpectChain(statement.expression);
+        if (occurrence !== null) {
+            entries.push({ index, occurrence });
+        }
+    });
+    const count = entries.length;
+    if (count <= 1) {
+        return null;
+    }
+    const occurrences = entries.map((entry) => entry.occurrence);
+    // The objects under direct test, used to recognize a mutation of the subject
+    // (e.g. `counter.increment()`) as an Act.
+    const underTestRoots = new Set();
+    for (const occurrence of occurrences) {
+        const shape = occurrence.baseShape;
+        if (shape.kind === "member" || shape.kind === "identifier") {
+            underTestRoots.add(shape.root);
+        }
+    }
+    // Step 0: an Act between the first and last assertion means the test observes
+    // two states; split at the boundary.
+    const expectIndices = new Set(entries.map((entry) => entry.index));
+    const first = entries[0]?.index ?? 0;
+    const last = entries[count - 1]?.index ?? 0;
+    for (let index = first + 1; index < last; index++) {
+        if (expectIndices.has(index)) {
+            continue;
+        }
+        const statement = statements[index];
+        if (statement === undefined) {
+            continue;
+        }
+        if (isActStatement(statement, underTestRoots)) {
+            return splitByActMessage(actDescription(statement));
+        }
+    }
+    // Guard: anything we cannot classify safely keeps the ban but falls back to
+    // the generic self-diagnosis message.
+    if (occurrences.some((occurrence) => occurrence.matcherName === null ||
+        occurrence.baseShape.kind === "other")) {
+        return genericMessage(count);
+    }
+    // Step 1: homogeneity of the assertion shape.
+    const signature = (occurrence) => {
+        return `${occurrence.matcherName}|${occurrence.negation}|${occurrence.modifier}|${occurrence.baseShape.kind}`;
+    };
+    if (new Set(occurrences.map(signature)).size > 1) {
+        return splitByHeterogeneityMessage(shapeSummary(occurrences));
+    }
+    // Step 2: where the variation lives.
+    const kind = occurrences[0]?.baseShape.kind;
+    if (kind === "member") {
+        const shapes = occurrences.map((occurrence) => occurrence.baseShape);
+        if (new Set(shapes.map((shape) => shape.root)).size > 1) {
+            return genericMessage(count);
+        }
+        const paths = shapes.map((shape) => shape.accessPath.join("."));
+        const distinct = [...new Set(paths)];
+        if (distinct.length >= 2) {
+            return consolidateMessage(shapes[0]?.root ?? "", distinct);
+        }
+        return genericMessage(count);
+    }
+    if (kind === "call") {
+        const shapes = occurrences.map((occurrence) => occurrence.baseShape);
+        if (new Set(shapes.map((shape) => nodeKey(shape.calleeNode, false))).size > 1) {
+            return splitByHeterogeneityMessage(shapeSummary(occurrences));
+        }
+        if (shapes.some((shape) => hasSpread(shape.argsNode))) {
+            return genericMessage(count);
+        }
+        if (new Set(shapes.map((shape) => tupleKey(shape.argsNode, false))).size > 1) {
+            return genericMessage(count);
+        }
+        // Same callee, same argument shape: an each candidate only if the input
+        // values actually differ. Identical inputs (only the expected value varies,
+        // or an exact duplicate) are not parameterizable.
+        if (new Set(shapes.map((shape) => tupleKey(shape.argsNode, true))).size <= 1) {
+            return genericMessage(count);
+        }
+        return eachOrSplitMessage(readable(shapes[0]?.calleeNode ?? { type: "" }), count);
+    }
+    return genericMessage(count);
+};
+// ---------------------------------------------------------------------------
+// Rule / Plugin
+// ---------------------------------------------------------------------------
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Disallow multiple top-level expect() assertions in a single test, and tell the author how to fix it (consolidate, split, or test.each).",
+        },
+        schema: [],
+    },
+    create(context) {
+        const checkCall = (node) => {
+            const root = rootCalleeName(node);
+            if (root === null || !TEST_CALLEES.has(root)) {
+                return;
+            }
+            const callback = testCallback(node);
+            if (callback === null || callback.body.type !== "BlockStatement") {
+                return;
+            }
+            const message = routeTest(callback.body);
+            if (message !== null) {
+                context.report({ message, node });
+            }
+        };
+        return {
+            CallExpression: checkCall,
+        };
+    },
+};
+const plugin = {
+    meta: { name: "crescware-single-behavior-per-test" },
+    rules: {
+        "single-behavior-per-test": rule,
+    },
+};
+export default plugin;

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@crescware/eslint-plugin-crescware-single-behavior-per-test",
+  "version": "0.0.1",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsgo -p tsconfig.build.json",
+    "check": "pnpm run check:types && pnpm run check:lint && pnpm run check:knip && pnpm run test",
+    "check:knip": "knip",
+    "check:lint": "oxlint && oxfmt --check",
+    "check:types": "tsgo -p tsconfig.json --noEmit",
+    "exec:fixtures": "oxlint -c fixtures/oxlintrc.default.json --no-ignore -f json fixtures/cases/",
+    "format": "oxlint --fix && oxfmt",
+    "prepublishOnly": "pnpm run build",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "24.12.2",
+    "@typescript/native-preview": "7.0.0-dev.20260422.1",
+    "knip": "6.7.0",
+    "oxfmt": "0.47.0",
+    "oxlint": "1.62.0",
+    "rimraf": "6.1.3",
+    "vitest": "4.1.5"
+  },
+  "packageManager": "pnpm@10.33.2"
+}