@sarj/eslint-plugin 11.0.0 → 11.1.0

package/README.md

@@ -1,379 +1,49 @@
 # @sarj/eslint-plugin
 
-## New in 9.11.0 — disabled test assertions
+Deterministic ESLint rules and presets for TypeScript, React, and modern Node.js
+applications. The plugin complements ESLint's core and TypeScript ESLint rules;
+it does not duplicate them.
 
-`no-comment-cruft` now recognizes commented-out `expect(...)` chains and
-`assert(...)` calls. A disabled assertion leaves a collected test passing while
-verifying nothing. JSDoc and assertion examples introduced by prose remain
-exempt, as do active assertions.
+## Use
 
-## New in 9.9.0 — static Next.js matchers
-
-`require-static-next-matcher` rejects runtime expressions in exported
-`middleware.ts` and `proxy.ts` matcher configuration. Next.js reads these values
-during static analysis, so identifiers, calls, concatenation, interpolated
-templates, and spreads can pass type checking but fail the production build.
-
-Custom ESLint rules for hypermodern TypeScript / React / Next.js projects.
-
-```bash
-pnpm add -D @sarj/eslint-plugin
-```
-
-```js
-// eslint.config.mjs
-import sarj from "@sarj/eslint-plugin";
-export default [sarj.configs.recommended];
-```
-
-66 rules. Each source under `src/rules/` states one concise claim and links to
-its paired tests. The definition and named test cases are the complete rule
-specification, and `meta.docs.url` points directly to those executable examples.
-
-Presets: `recommended` is a curated subset and `strict` contains every
-general-profile rule. Every active custom rule in both presets is an error;
-rules that cannot meet that bar are narrowed or retired instead of being left
-as permanent warning noise. Application-only rules are exported through
-`applicationOnlyRules` and are also errors when the application profile enables
-them. `style-guide` remains the formatting/naming subset.
-
-## New in 9.8.0 — application library policy adapters
-
-`no-restricted-library-load` extends a configured dependency policy to runtime
-loading forms that ESLint's `no-restricted-imports` does not cover: literal
-`import()`, unshadowed `require()` / `require.resolve()`, and TypeScript
-`import x = require(...)`. It matches a package and all of its subpaths, but
-deliberately ignores computed names and shadowed local `require` functions.
-
-`prefer-native-random-uuid` reports resolved, zero-argument UUID v4 calls from
-the `uuid` package and suggests `globalThis.crypto.randomUUID()`. The suggestion
-changes only the call; import cleanup remains explicit. Other UUID versions,
-custom-randomness arguments, re-exports, and function references are untouched.
-
-Neither rule is in the general presets. The application profile configures them
-for its Node 22.13+ runtime contract and supplies catalog entries to the loader
-rule:
-
-```js
-rules: {
-  "@sarj/no-restricted-library-load": [
-    "error",
-    {
-      libraries: [
-        {
-          id: "LIB101",
-          module: "axios",
-          replacement: "Ky",
-          note: "The APIs are not drop-in equivalents.",
-        },
-      ],
-    },
-  ],
-  "@sarj/prefer-native-random-uuid": "error",
-}
-```
-
-## Renamed in 7.0.0, aliases deleted in 9.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` |
-
-7.0.0 kept each old name registered as a deprecated alias. 9.0.0 deletes them, so
-the new names are the only names — and an old name left in a config, an
-`eslint-disable` comment or a suppressions baseline now makes ESLint exit 2 with
-`Could not find "@sarj/<rule>" in plugin "@sarj"` before it reads a file.
-
-Run `sarj-lint-configs doctor` before upgrading: it reads the shipped rule ledger
-and names every file holding an old name, with the replacement. The map is also
-exported for codemods:
-
-```js
-import { renamedRules } from "@sarj/eslint-plugin";
-```
-
-The rename map and migration behavior live in
-[`src/rules/_renames.ts`](src/rules/_renames.ts) and its tests.
-
-## New in 4.1.0 — `no-hand-rolled-sleep`
-
-`new Promise((resolve) => setTimeout(resolve, ms))` is `node:timers/promises`'s
-`setTimeout` rewritten by hand, minus the `AbortSignal` — so it is a capability
-loss, not verbosity. The hand-rolled sleep holds a live timer that nothing can
-clear, and its mirror image, the `Promise.race([work, rejectAfter(ms)])` timeout
-arm, leaks the timer the other way: when `work` wins, nothing clears it and it
-keeps the event loop alive until it fires.
-
-Shipped only after confirming nothing already enabled reports this position. The
-enabled set was resolved with `ESLint#calculateConfigForFile` against the shipped
-`eslint.strict.mjs` (204 rules before this one) and a file containing every
-shape was linted through it: no report. `eslint-plugin-unicorn` 72 has no
-promisified-timer rule among its 341; `unicorn/prefer-abort-signal-timeout` covers the
-`AbortController` + `setTimeout` idiom and not the race arm; core
-`no-promise-executor-return` fires on the concise-arrow spelling only and its
-remedy ("add braces") entrenches the hand-rolled sleep. The polling-loop variant
-(`while (!done) await sleep(ms)`) is deliberately absent — core `no-await-in-loop`
-is already enabled and reports that exact position.
-
-Measured over 1,471 files containing `setTimeout` across 15 OSS repos (hono,
-tRPC, drizzle-orm, undici, vitest, got, cal.com, documenso, dub, formbricks,
-midday, openstatus, papermark, unkey, zod) and seven internal ones: 85 + 11
-sleeps and 2 + 1 leaky race arms at the default settings, **0 false positives**.
-
-`checkClientModules` is the option that matters. A browser or React Native
-bundle cannot import `node:timers/promises` and the web platform ships no
-equivalent, so client modules are skipped by default — 79% of the internal
-corpus's occurrences live in `.tsx` components where the fix cannot be applied.
-Turn it on only in a tree where every file resolves `node:` builtins. The race
-message is reported everywhere regardless: `AbortSignal.timeout` is on the web
-platform too.
-
-| Rule | What it catches | Preset |
-|---|---|---|
-| `no-hand-rolled-spinner` | Intrinsic elements styled as Tailwind border-ring loading spinners outside the design system. | error / error |
-| `prefer-input-group-search` | Search icons and shared Input controls composed without the shared InputGroup primitive. | error / error |
-| `prefer-shadcn-primitives` | Deterministically visible raw JSX controls used instead of shared shadcn primitives. Unknown and hidden input types are excluded. | application profile: error |
-| `require-static-next-matcher` | Dynamic values in exported Next.js middleware and proxy matcher configuration. | error / error |
-| `no-hand-rolled-sleep` | `new Promise((r) => setTimeout(r, ms))` in any spelling, and an uncleared `Promise.race`/`Promise.any` timeout arm. Options: `checkClientModules` (default `false`), `allowIn`. | error / error |
-
-`prefer-shadcn-primitives` is application-only because generic plugin consumers
-may use another design system or intentionally expose native controls. The
-application profile enforces its measured, deterministic cases as errors while
-keeping it disabled inside `components/ui` and
-`components/design-system`, where shared primitives must wrap native elements.
-
-## New in 2.14.0 — `no-tautological-expect`
-
-The TS half of SARJ057. An `expect(...)` whose operands are all literals has
-already decided its outcome before the test runs — `expect(true).toBe(true)`
-passes if you delete the module under test.
-
-Python has caught the assertion-*free* test since 0.15.0 (`SARJ043
-zero-assertion-test`) and had no TypeScript counterpart, which is exactly how
-`expect(true).toBe(true); // placeholder` survived in an internal suite named for
-the behaviour it was supposed to check: the file *has* an assertion, so nothing
-was looking at it.
-
-| Rule | What it catches | Preset |
-|---|---|---|
-| `no-tautological-expect` | `expect(<literal>).toBe/toEqual/toStrictEqual(<textually identical literal>)`, and `expect(<literal>).toBeDefined()/toBeTruthy()/toBeNull()/…` — a zero-argument matcher on a literal receiver. | warn / error |
-
-**The narrowness is the rule.** The obvious generalisation — "flag a comparison
-of a thing with itself" — measures ~95% false positives:
-`expect(hash([o])).toEqual(hash([o]))` is a *determinism* test,
-`expect(memo(x)).toBe(memo(x))` a *memoization* test, `expect(a).toEqual(a)` on a
-value with custom equality a *reflexivity* test. All three can genuinely fail. So
-an identifier, member-expression or call operand is never enough: both sides must
-be literals, and textually identical ones. A modified chain (`.not`, `.resolves`,
-`.rejects`), a spread, an interpolated template literal, and two *different*
-literals are all left alone.
-
-Measured before shipping: **3 hits across 5,819 `.ts`/`.tsx` files** (1,003 of
-them test files, where the rule is active) — six internal repos plus `got`,
-`hono`, `swr` and `trpc`. 3 true positives, **0 false positives**; every hit is
-an abandoned placeholder.
-
-## New in 2.13.0 — the anti-comment-verbosity family
-
-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. Each paired test suite records the
-false-positive shapes guarded by the implementation.
-
-| 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 |
-| `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-declaration-comment-wall` | The same judgement for an ENUM BODY or a CLASS BODY, which the rule below structurally cannot see. | warn / error |
-| `no-union-in-comment` | `kind: string; // 'pending' \| 'approved'` — the comment IS the union; write it as one so the compiler enforces it. | 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
-
-Both distilled from two years of PR-review comments across ~1,065 PRs.
-
-| Rule | What it catches | Preset |
-|---|---|---|
-| `no-zod-native-enum` | `z.nativeEnum(...)` and `z.enum(SomeTsEnum)` — the schema-layer back door around `no-enum`. Autofixes an inline string-literal object to `z.enum([...])`. | warn / error |
-| `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` | A required array property or direct alias explicitly combined with `null`/`undefined`, creating two equivalent empty states. Optional API fields are excluded because omission can be meaningful. | warn / error |
-
-## Options
-
-### Declare your logger (`loggerNames` / `logFunctions`)
-
-Three rules decide whether a call writes to a log sink: `no-log-only-catch`,
-`no-sentinel-return-on-catch`, `no-secret-in-log`. Out of the box they recognise
-a log method on a logger *receiver* (`console.error`, `logger.warn`,
-`this.logger.info`). A structured logger is usually a free *function* taking a
-meta object, which has no receiver — declare it once and all of them see it:
+Sarj repositories should let `sarj-standards setup` install the tested peer set
+and generate the integration. Direct ESLint consumers can install the package
+and select a preset:
 
 ```js
-const logging = { logFunctions: ["logEvent"], loggerNames: ["obs"] };
-
-rules: {
-  "@sarj/no-log-only-catch": ["error", logging],
-  "@sarj/no-sentinel-return-on-catch": ["error", logging],
-  "@sarj/no-secret-in-log": ["error", logging],
-}
-```
-
-- `logFunctions` — free functions (or methods) that log: `logEvent("x", { err })`.
-- `loggerNames` — extra logger *receiver* names, added to the built-in set.
-
-This suppresses "swallows the error without logging it" on a correctly-logged
-degraded return, and — importantly — makes `no-secret-in-log` inspect those
-calls, which it could not do before: `logEvent("slack.auth", { botToken })` was
-previously never examined.
-
-### `zod-naming-convention`: `convention`
-
-`"either"` (default) accepts both the `Z`-prefix (`ZUser`) and the `Schema`
-suffix (`userSchema`) — the two conventions `require-zod-form-validation`
-already recognises. Set `"prefix"` or `"suffix"` to pin one:
-
-```js
-"@sarj/zod-naming-convention": ["error", { convention: "suffix" }]
-```
-
-### `prefer-zod-infer`: `requireIdenticalShape` / `ignoreTypeNames`
-
-By default the rule only reports a type whose members match its schema's keys
-one for one — same names, same optionality, same nullability, no `.transform()`
-anywhere in the pair. On a 30,759-file, 17-repo sweep that is 5 reports and 5
-true positives. Drop the shape comparison to report on name correlation alone
-(8 reports on the same corpus, 1 of them noise, and it catches twins that have
-already drifted):
-
-```js
-"@sarj/prefer-zod-infer": ["error", { requireIdenticalShape: false }]
-```
-
-`ignoreTypeNames` takes regex sources matched against the declared type name,
-for the pair that is genuinely meant to be maintained by hand:
-
-```js
-"@sarj/prefer-zod-infer": ["error", { ignoreTypeNames: ["^LegacyUser$"] }]
-```
-
-### `prefer-string-literal-union`: `ignoreFields`
-
-Field names whose value set is owned by a vendor and genuinely open (a Slack
-`event.subtype`, a Resend `bounceType`). Narrowing to a union you don't control
-would be wrong, not better:
-
-```js
-"@sarj/prefer-string-literal-union": ["warn", { ignoreFields: ["subtype", "bounceType"] }]
-```
-
-### `no-enum`: `ignoreFiles`
-
-Glob patterns whose files opt out (generated code already opts out by default).
-
-## Configurable rules
-
-Most rules take no options. These do, because they encode a codebase's
-architecture rather than a language fact — the defaults describe one convention
-and every repo gets to name its own.
-
-| Rule | Option | Default | Effect |
-|---|---|---|---|
-| `no-raw-fetch-outside-clients` | `allow` | client / vendor-wrapper path patterns | Extra files exempt from the "no bare `fetch`" rule (test files are exempt unconditionally) |
-| `no-dynamic-sql` | `methods` | `["prepare", "exec", "query"]` | Statement-taking methods to inspect |
-| `no-storage-in-stateless-modules` | `modules` | `[]` (rule off) | Directories declared stateless |
-| `no-storage-in-stateless-modules` | `methods` | `["prepare", "put", "getWithMetadata"]` | Storage methods to flag |
-| `no-hand-rolled-sleep` | `checkClientModules` | `false` | Also report the sleep form in browser/React Native modules |
-| `no-hand-rolled-sleep` | `allowIn` | `[]` | Glob patterns for a sanctioned sleep wrapper module |
-
-The path options on the first three rules are **regular-expression sources
-matched against the absolute filename**, not globs — so they can express both
-path separators. Test files no longer need to appear there: the rule delegates
-to the shared `isTestFile` predicate, so supplying `allow` replaces only the
-production exemptions and cannot accidentally un-exempt a test tree.
-`allowIn` is the exception, on `no-hand-rolled-sleep` as on
-`require-fetch-timeout`: it takes minimatch-ish **globs**, also matched against
-the absolute path, so anchor them with a `**/` prefix. Supplying an option
-**replaces** the default rather than extending it.
-
-`no-storage-in-stateless-modules` is a **no-op until `modules` is set**. The
-method names alone (`put`, `prepare`) carry no type information, so the rule is
-only meaningful once it is pointed at the directories a team has actually
-declared stateless.
-
-```js
-// eslint.config.mjs
 import sarj from "@sarj/eslint-plugin";
 
 export default [
   sarj.configs.strict,
-  {
-    rules: {
-      // This repo keeps its HTTP layer in `lib/api/`, not `clients/`.
-      "@sarj/no-raw-fetch-outside-clients": [
-        "error",
-        { allow: ["[\\\\/]lib[\\\\/]api[\\\\/]"] },
-      ],
-      // Declare which modules must stay stateless.
-      "@sarj/no-storage-in-stateless-modules": [
-        "error",
-        { modules: ["[\\\\/]engineer-digest[\\\\/]"] },
-      ],
-    },
-  },
 ];
-```
 
-Tiering: `no-dynamic-sql` is in both presets (an injection guard with a low
-false-positive rate, relevant to any repo touching SQL). The two architectural
-rules are **`strict`-only**, since they need per-repo configuration to say
-anything useful.
-
-`no-generic-single-export-module` warns when a `utils`, `helpers`, `common`,
-`constants`, or similarly generic module has one runtime export that already
-provides a precise filename. Ambiguous re-exports, type-only modules,
-conventional framework filenames, tests, generated files, and CommonJS modules
-are excluded. It is warning-first while corpus evidence accumulates.
+// For staged adoption:
+// export default [sarj.configs.recommended];
+```
 
-`stepdown` is likewise warning-first: measured adoption is intentionally broad,
-so it only owns ordering within a private-method band. The strict preset gives
-public/protected/private band ordering to `@typescript-eslint/member-ordering`
-and disables `perfectionist/sort-classes`, avoiding contradictory owners. The
-rule resolves module helpers, private methods, recursion and cycles, but leaves
-function-valued private fields and mutable receiver aliases alone.
+Available presets are `recommended` for staged adoption and `strict` for the
+full general policy. Application-only rules are exported separately because
+they depend on an explicit runtime and library policy.
 
-`no-positional-tuple-return` now rejects every fixed multi-field tuple on an
-exported TypeScript boundary—including homogeneous, labelled, tagged, readonly,
-hook-style, interface, function-type, declaration and abstract-method returns.
-The runtime alternative is a named object. Private/local implementation helpers
-and sequence-shaped arrays remain outside the public-boundary rule.
+Use `sarj-standards show peers` for the tested ESLint and parser dependency set.
+Do not combine independent `latest` versions and assume they are compatible.
 
-## Ported from `sarj_python_lint`
+## Rules and suppressions
 
-Several rules are ports of the Python linter's SARJ rules, retuned for TypeScript. The false-positive tuning documented in the Python docstrings is ported with them — that tuning is the valuable part.
+Every rule is registered in `src/index.ts`; its source under `src/rules/` and
+paired test under `tests/rules/` are the authoritative specification. Run
+`sarj-standards show rules` for the current machine-readable catalog.
 
-| TypeScript rule | Python | What it prevents |
-| --- | --- | --- |
-| `prefer-constant-time-secret-compare` | SARJ011 | Byte-by-byte secret recovery through the timing of a short-circuiting `===` on a token / signature / HMAC. On Workers the fix is `crypto.subtle.timingSafeEqual` over equal-length digests. |
-| `no-secret-in-log` | SARJ012 | Credentials persisted into log sinks. |
-| `store-insert-requires-on-conflict` | SARJ018 | Duplicate rows — or unique-constraint failures that re-trigger the handler — when a cron re-runs or a queue message is redelivered. |
-| `no-select-star` | SARJ021 | An implicit row contract that changes silently when a column is added or reordered. |
-| `no-offset-pagination` | SARJ025 | O(N)-per-page scans, and rows repeated or skipped when the offset window shifts under concurrent inserts. |
-| `no-repeated-string-literal` | SARJ024 | Copies of a structured literal (SQL, column lists, prompt templates) drifting apart when only one is edited. |
-| `no-positional-tuple-return` | SARJ026 | Public APIs exposing multi-field tuples—even labelled or hook-style tuples—instead of named objects. |
-| `no-sleep-in-test-body` | SARJ031 | Tests that assert on wall-clock time and flake under CI load. |
-| `no-fat-try-blocks` | SARJ007 | Over-broad `catch` handlers swallowing unrelated failures. |
-| `no-cors-wildcard-with-credentials` | SARJ008 | Credentialed cross-origin requests from any origin. |
-| `single-public-export` | SARJ022 | Modules with no single obvious entry point. |
-| `stepdown` | SARJ023 | A private helper placed above its only direct same-scope caller. Indirect references, callbacks, cycles, overloads, and multi-caller helpers are excluded. |
-| `prefer-string-literal-union` | SARJ006 | An open `string` where a closed set is intended. |
+Prefer the smallest line-scoped `eslint-disable-next-line @sarj/rule-name`
+suppression and explain why the exceptional code is intentional. Unknown or
+retired rule names are configuration errors.
 
-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.
+New rules must prove that upstream ESLint and TypeScript ESLint cannot express
+the policy and must pass focused tests plus the repository corpus evaluation
+described in the root contribution guide.
 
-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), `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`.
+Renamed rules fail closed. Replace `jsdoc-restates-signature` with
+`no-restated-jsdoc`, `no-async-callback-in-waitfor` with
+`no-async-callback-in-wait-for`, `strict-test-assertions` with
+`prefer-whole-object-assertion`, and `trailing-value-narration` with
+`no-trailing-value-narration`.