@sarj/eslint-plugin 6.0.0 → 7.0.0

package/README.md

@@ -12,10 +12,37 @@ import sarj from "@sarj/eslint-plugin";
 export default [...sarj.configs.recommended];
 ```
 
-51 rules. Each rule's source under `src/rules/` carries its own `@fileoverview` rationale plus `meta.docs.description` + `meta.messages` — read the file for the full reasoning, including the false positives it deliberately does not fire on.
+51 rules. Each rule's source under `src/rules/` opens with a one-line claim and
+two links: its tests, which are the examples, and `docs/rules/<rule>.md`, which
+holds the measurements, the false-positive family behind every guard, and the
+alternatives that were rejected. `meta.docs.url` points at the same document, so
+`--format=stylish` prints it. Both links are derived from the rule's name, so a
+rename moves them.
 
 Presets: `recommended` (warn-first), `strict` (every rule at error), `style-guide` (formatting/naming subset).
 
+## Renamed in 7.0.0 (breaking)
+
+| Old name | New name |
+| --- | --- |
+| `@sarj/jsdoc-restates-signature` | `@sarj/no-restated-jsdoc` |
+| `@sarj/no-async-callback-in-waitfor` | `@sarj/no-async-callback-in-wait-for` |
+| `@sarj/strict-test-assertions` | `@sarj/prefer-whole-object-assertion` |
+| `@sarj/trailing-value-narration` | `@sarj/no-trailing-value-narration` |
+
+Every old name is still REGISTERED, as a deprecated alias of the same rule, so a
+config entry, an `eslint-disable` comment or a suppressions baseline naming it
+keeps working while you migrate; ESLint reports the deprecation and names the
+replacement. Neither preset wires an alias, so nothing double-reports. The map is
+exported for codemods:
+
+```js
+import { renamedRules } from "@sarj/eslint-plugin";
+```
+
+Migration steps, the reasoning behind each name, and why the old keys are kept
+rather than dropped: [`docs/rules/_renames.md`](../../docs/rules/_renames.md).
+
 ## New in 4.1.0 — `no-hand-rolled-sleep`
 
 `new Promise((resolve) => setTimeout(resolve, ms))` is `node:timers/promises`'s
@@ -88,14 +115,14 @@ an abandoned placeholder.
 
 From a 37,918-comment, nine-repo measurement study. All three are
 deletion-class, so each was validated against zod / swr / zustand / TanStack
-Query as well as the maintained repos. Read the `@fileoverview` in each rule for
-the hit counts and the false-positive class every guard was built from.
+Query as well as the maintained repos. `docs/rules/<rule>.md` carries the hit
+counts and the false-positive class every guard was built from.
 
 | Rule | What it catches | Preset |
 |---|---|---|
 | `no-restated-comment` | A single-line comment whose every content word already appears on the statement below it. Defers to `no-comment-cruft` for the verb-led shape, so a comment is never reported twice. | warn / error |
-| `jsdoc-restates-signature` | A JSDoc block whose description and `@param`/`@returns` only re-spell the signature. Offers a delete SUGGESTION, never an auto-`--fix`. | warn / error |
-| `trailing-value-narration` | `staleTime: 5 * 60 * 1000, // 5 minutes` — the unit belongs in the name, where it cannot drift. | warn / error |
+| `no-restated-jsdoc` | A JSDoc block whose description and `@param`/`@returns` only re-spell the signature. Offers a delete SUGGESTION, never an auto-`--fix`. | warn / error |
+| `no-trailing-value-narration` | `staleTime: 5 * 60 * 1000, // 5 minutes` — the unit belongs in the name, where it cannot drift. | warn / error |
 | `no-type-member-comment-wall` | An object type whose member comments mostly re-spell the members' own names and types — the VOLUME arm of the family, reported once for the type. | warn / error |
 
 ## New in 2.9.0
@@ -108,6 +135,7 @@ Both distilled from two years of PR-review comments across ~1,065 PRs.
 | `prefer-zod-enum` | `z.union([z.literal("a"), z.literal("b")])` — autofixes closed string choices to the shorter, equivalent `z.enum(["a", "b"])`. | warn / error |
 | `prefer-zod-infer` | An `interface`/`type` that restates a Zod schema declared in the same module instead of deriving it with `z.infer`. Options: `ignoreTypeNames`, `requireIdenticalShape` (default `true`). | warn / error |
 | `prefer-module-level-constant` | A literal-only `const` collection (array, object, `Set`, `Map`, `Object.freeze`) or non-global regex declared inside a function body, never mutated and never escaping — hoist it to module scope. Options: `minElements` (default 3), `checkRegex`, `ignoreTestFiles`. | warn / error |
+| `prefer-module-level-schema` | A Zod schema built inside a function body that closes over nothing the function owns — hoist it to module scope instead of rebuilding it per call, per request, per render. Silent when it references a parameter, local, type parameter, local type, or `this` (that is a schema FACTORY), when it is already memoized, and inside `z.lazy`. Options: `factories` (default: the object-like composites), `minProperties` (default 1), `ignoreTestFiles`. | warn / error |
 | `prefer-non-nullable-collection` | An array type explicitly combined with `null`/`undefined`, creating two equivalent empty states. | warn / error |
 
 ## Options
@@ -259,6 +287,6 @@ Several rules are ports of the Python linter's SARJ rules, retuned for TypeScrip
 | `single-public-export` | SARJ022 | Modules with no single obvious entry point. |
 | `prefer-string-literal-union` | SARJ006 | An open `string` where a closed set is intended. |
 
-Shared helpers live in `src/rules/_*.ts` (`_secret_names.ts`, `_sql.ts`, `_logging.ts`, `_paths.ts`, `_tailwind.ts`) so related rules cannot diverge on what counts as a secret, a SQL statement, a logging call, or a test file.
+Shared helpers live in `src/rules/_*.ts` (`_secret-names.ts`, `_sql.ts`, `_logging.ts`, `_paths.ts`, `_tailwind.ts`) so related rules cannot diverge on what counts as a secret, a SQL statement, a logging call, or a test file.
 
 Deliberately **not** ported: `no-unreachable-after-terminal` (SARJ010) is already covered by `allowUnreachableCode: false` in `@sarj/tsconfig` plus ESLint core `no-unreachable`; `no-aggregation-in-store-query` (SARJ020) assumes a Postgres-OLTP / columnar-mirror split that D1 does not have; `no-query-with-many-joins` (SARJ019), `stepdown` (SARJ023), `prefer-class-row`, `prefer-struct-over-namedtuple`, `prefer-timedelta-for-durations`, and `no-fstring-in-log` have no TypeScript defect class or target API; `prefer-str-enum` is covered by `prefer-string-literal-union` + `no-enum`.