eslint-config-agent 3.0.5 → 3.1.0

package/CHANGELOG.md

@@ -4,6 +4,52 @@ All notable changes to this project will be documented in this file. See [Conven
 
 
 
+## [3.1.0](https://github.com/tupe12334/eslint-config-agent/compare/v3.0.5...v3.1.0) (2026-07-02)
+
+### Features
+
+* **config:** enable @typescript-eslint/explicit-function-return-type for .ts ([#257](https://github.com/tupe12334/eslint-config-agent/issues/257)) ([7469e06](https://github.com/tupe12334/eslint-config-agent/commit/7469e06503157f838071cbdaa8216065ccce9975)), closes [#255](https://github.com/tupe12334/eslint-config-agent/issues/255)
+* **config:** enable @typescript-eslint/method-signature-style in the shared rule set ([#313](https://github.com/tupe12334/eslint-config-agent/issues/313)) ([e261d06](https://github.com/tupe12334/eslint-config-agent/commit/e261d06e8724702fb763a11e24f922d51156a66c))
+* **config:** enable @typescript-eslint/no-misused-promises in the shared rule set ([#285](https://github.com/tupe12334/eslint-config-agent/issues/285)) ([0fba9f0](https://github.com/tupe12334/eslint-config-agent/commit/0fba9f0ecabe89368cb1ffa6dcd2c6e983815472))
+* **config:** enable @typescript-eslint/no-mixed-enums in the shared rule set ([#317](https://github.com/tupe12334/eslint-config-agent/issues/317)) ([51ee52b](https://github.com/tupe12334/eslint-config-agent/commit/51ee52b991516730db6bb3a9c5014a3a780af911))
+* **config:** enable @typescript-eslint/no-unnecessary-condition in the shared rule set ([#352](https://github.com/tupe12334/eslint-config-agent/issues/352)) ([d8449f5](https://github.com/tupe12334/eslint-config-agent/commit/d8449f57600a60afd37e35a171e772371583219b)), closes [#351](https://github.com/tupe12334/eslint-config-agent/issues/351)
+* **config:** enable @typescript-eslint/no-use-before-define in the shared rule set ([#338](https://github.com/tupe12334/eslint-config-agent/issues/338)) ([4079061](https://github.com/tupe12334/eslint-config-agent/commit/407906131981054bddb05fbfc531bf54839484e9)), closes [#337](https://github.com/tupe12334/eslint-config-agent/issues/337)
+* **config:** enable @typescript-eslint/prefer-enum-initializers ([#289](https://github.com/tupe12334/eslint-config-agent/issues/289)) ([630f36f](https://github.com/tupe12334/eslint-config-agent/commit/630f36fa6c79b8cbfed1187cb4192b7118b786dd))
+* **config:** enable @typescript-eslint/prefer-optional-chain for .ts/.tsx files ([#260](https://github.com/tupe12334/eslint-config-agent/issues/260)) ([45d6423](https://github.com/tupe12334/eslint-config-agent/commit/45d6423d18a4778aed6f5391c8fe12f02b1f31e2))
+* **config:** enable consistent-return in the shared rule set ([#331](https://github.com/tupe12334/eslint-config-agent/issues/331)) ([4f7f522](https://github.com/tupe12334/eslint-config-agent/commit/4f7f5221e17b031efd2ca1a96202ca40de8ad88b))
+* **config:** enable logical-assignment-operators in the shared rule set ([#295](https://github.com/tupe12334/eslint-config-agent/issues/295)) ([5cec4f8](https://github.com/tupe12334/eslint-config-agent/commit/5cec4f87a32817fa005488deb39fb773a09c4690))
+* **config:** enable n/prefer-node-protocol in the shared rule set ([#291](https://github.com/tupe12334/eslint-config-agent/issues/291)) ([cc8c47a](https://github.com/tupe12334/eslint-config-agent/commit/cc8c47a621f5d71f5847d35d3ce69f4f9c043070))
+* **config:** enable no-alert in the shared rule set ([#297](https://github.com/tupe12334/eslint-config-agent/issues/297)) ([f7cc412](https://github.com/tupe12334/eslint-config-agent/commit/f7cc4129f40e59669f284e0f683186992f4bb937))
+* **config:** enable no-constant-binary-expression in the shared rule set ([#354](https://github.com/tupe12334/eslint-config-agent/issues/354)) ([310deb6](https://github.com/tupe12334/eslint-config-agent/commit/310deb6b0f08c0872b810a0c4c31020b34603352))
+* **config:** enable no-constructor-return in the shared rule set ([#332](https://github.com/tupe12334/eslint-config-agent/issues/332)) ([79357a3](https://github.com/tupe12334/eslint-config-agent/commit/79357a3a699c6bd66287c2f8a02d66ee7bf93716))
+* **config:** enable no-debugger in the shared rule set ([#254](https://github.com/tupe12334/eslint-config-agent/issues/254)) ([d941604](https://github.com/tupe12334/eslint-config-agent/commit/d941604ecb43ba02cd570af9d49f3f7861791f39))
+* **config:** enable no-extend-native in the shared rule set ([#330](https://github.com/tupe12334/eslint-config-agent/issues/330)) ([138006b](https://github.com/tupe12334/eslint-config-agent/commit/138006b480e69752e16e2c80f34c675ab0b9c594))
+* **config:** enable no-new-wrappers in the shared rule set ([#125](https://github.com/tupe12334/eslint-config-agent/issues/125)) ([2cdc1c2](https://github.com/tupe12334/eslint-config-agent/commit/2cdc1c2143b288c38e41cbad0c2267522b6d912d)), closes [#124](https://github.com/tupe12334/eslint-config-agent/issues/124)
+* **config:** enable no-script-url in the shared rule set ([#251](https://github.com/tupe12334/eslint-config-agent/issues/251)) ([18147fc](https://github.com/tupe12334/eslint-config-agent/commit/18147fc5c5a6e37177f8c1c0599250a0b816c255)), closes [#250](https://github.com/tupe12334/eslint-config-agent/issues/250)
+* **config:** enable no-sequences in the shared rule set ([#267](https://github.com/tupe12334/eslint-config-agent/issues/267)) ([6d45085](https://github.com/tupe12334/eslint-config-agent/commit/6d450854eac3cba29f6fb6715fd4477954c48666)), closes [#81](https://github.com/tupe12334/eslint-config-agent/issues/81)
+* **config:** enable no-undef-init in the shared rule set ([#344](https://github.com/tupe12334/eslint-config-agent/issues/344)) ([8521b73](https://github.com/tupe12334/eslint-config-agent/commit/8521b73062acd82e608088dcb2541dde509fb5b0)), closes [#343](https://github.com/tupe12334/eslint-config-agent/issues/343)
+* **config:** enable no-unmodified-loop-condition in the shared rule set ([#96](https://github.com/tupe12334/eslint-config-agent/issues/96)) ([acd21b7](https://github.com/tupe12334/eslint-config-agent/commit/acd21b7940ea8b675f207da464d198c631a9ddde)), closes [#95](https://github.com/tupe12334/eslint-config-agent/issues/95)
+* **config:** enable no-unreachable-loop in the shared rule set ([#274](https://github.com/tupe12334/eslint-config-agent/issues/274)) ([a18fcf2](https://github.com/tupe12334/eslint-config-agent/commit/a18fcf271a05ec9aa3865b220feaf23b59257863)), closes [#87](https://github.com/tupe12334/eslint-config-agent/issues/87)
+* **config:** enable no-useless-call in the shared rule set ([#301](https://github.com/tupe12334/eslint-config-agent/issues/301)) ([3edf7aa](https://github.com/tupe12334/eslint-config-agent/commit/3edf7aaf1e553342892ef42382bb8acc7e8ab37e))
+* **config:** enable no-useless-constructor in the shared rule set ([#312](https://github.com/tupe12334/eslint-config-agent/issues/312)) ([76808e2](https://github.com/tupe12334/eslint-config-agent/commit/76808e2ee038d5ba6094b75e6bc0ecb456a279ae)), closes [#311](https://github.com/tupe12334/eslint-config-agent/issues/311)
+* **config:** enable no-useless-rename in the shared rule set ([#336](https://github.com/tupe12334/eslint-config-agent/issues/336)) ([f1fa2e4](https://github.com/tupe12334/eslint-config-agent/commit/f1fa2e41a4fd467b601c194b3f860c4c50c3848e)), closes [#113](https://github.com/tupe12334/eslint-config-agent/issues/113)
+* **config:** enable prefer-named-capture-group in the shared rule set ([#308](https://github.com/tupe12334/eslint-config-agent/issues/308)) ([75877f9](https://github.com/tupe12334/eslint-config-agent/commit/75877f9bde9614a3c311343f11a5b55fbf31cb28))
+* **config:** enable react/jsx-no-useless-fragment in the shared rule set ([#272](https://github.com/tupe12334/eslint-config-agent/issues/272)) ([de076fc](https://github.com/tupe12334/eslint-config-agent/commit/de076fc52107878dca23cfa491ef19a48a99be6d)), closes [#271](https://github.com/tupe12334/eslint-config-agent/issues/271)
+* **config:** enable react/self-closing-comp in the shared rule set ([#269](https://github.com/tupe12334/eslint-config-agent/issues/269)) ([20d15b6](https://github.com/tupe12334/eslint-config-agent/commit/20d15b6891ea88df2df2b31d75b0a70ce1b88587))
+* **config:** enable yoda rule in the shared rule set ([#273](https://github.com/tupe12334/eslint-config-agent/issues/273)) ([b7ebd29](https://github.com/tupe12334/eslint-config-agent/commit/b7ebd29351475549581c72ec09f55dc968abcf54)), closes [#61](https://github.com/tupe12334/eslint-config-agent/issues/61)
+* **react:** enable react/hook-use-state in the shared rule set ([#319](https://github.com/tupe12334/eslint-config-agent/issues/319)) ([bb23979](https://github.com/tupe12334/eslint-config-agent/commit/bb23979d479e0af64b4eba550b30a7c6aa2bf7bb))
+* **react:** enable react/jsx-key in the shared rule set ([#342](https://github.com/tupe12334/eslint-config-agent/issues/342)) ([297c706](https://github.com/tupe12334/eslint-config-agent/commit/297c7067cdb1ed9db5a2065e53b60885420dbddb))
+* **react:** enable react/no-object-type-as-default-prop in the shared rule set ([#323](https://github.com/tupe12334/eslint-config-agent/issues/323)) ([4d43920](https://github.com/tupe12334/eslint-config-agent/commit/4d439201b343cf9aebb3c702a2d99b74b723ab71))
+
+### Bug Fixes
+
+* **ci:** publish directly from scheduled-release.yml ([#356](https://github.com/tupe12334/eslint-config-agent/issues/356)) ([ac2db7b](https://github.com/tupe12334/eslint-config-agent/commit/ac2db7b9e911d58fd422e0d5461a8f4b1ec0efea))
+* **config:** disable prefer-nullish-coalescing to resolve ?? contradiction ([#321](https://github.com/tupe12334/eslint-config-agent/issues/321)) ([13a18d4](https://github.com/tupe12334/eslint-config-agent/commit/13a18d48068448289f36698a7e000f4252ef309a))
+* publish rule helper modules, not just index.js ([#270](https://github.com/tupe12334/eslint-config-agent/issues/270)) ([4e81453](https://github.com/tupe12334/eslint-config-agent/commit/4e81453914fc4e1bd8ca048ba03054a272b168e3))
+* **recommended:** downgrade max-lines rules from error to warn ([#335](https://github.com/tupe12334/eslint-config-agent/issues/335)) ([b69ccb3](https://github.com/tupe12334/eslint-config-agent/commit/b69ccb34ede4f7ede1a49d72b1e35ab52d2e9023)), closes [#85](https://github.com/tupe12334/eslint-config-agent/issues/85)
+* **recommended:** keep process.env property guard in the relaxed preset ([#281](https://github.com/tupe12334/eslint-config-agent/issues/281)) ([a99f00c](https://github.com/tupe12334/eslint-config-agent/commit/a99f00c13639c191650c8c7f15df3e84bd969b46))
+* **ts:** disable no-throw-literal for TS files; let only-throw-error handle it ([#299](https://github.com/tupe12334/eslint-config-agent/issues/299)) ([c0c9b28](https://github.com/tupe12334/eslint-config-agent/commit/c0c9b28afc2436573e90b87316415569f3e44ff7))
+
 ## [3.0.5](https://github.com/tupe12334/eslint-config-agent/compare/v3.0.4...v3.0.5) (2026-06-24)
 
 ### Features

package/README.md

@@ -483,6 +483,14 @@ This ESLint configuration prioritizes **explicit code** over convenient shortcut
   `default` that omits `break` silently falls through into the cases below it.
   Pinning `default` to the end keeps its order-independent meaning legible. Not
   auto-fixable: moving a clause that omits `break` could change behavior.
+- **`consistent-return`**: Requires every `return` statement in a function to
+  either always specify a value or never specify one. A function that returns
+  a value on one branch and falls through (or hits a bare `return;`) on another
+  silently yields `undefined` on the unhandled paths — a quiet,
+  plausible-but-wrong mistake the type checker does not reliably catch, since
+  an inferred `T | undefined` return type checks cleanly either way. Not
+  auto-fixable: only the author knows whether the missing branch should return
+  a value or the value-returning branch should stop returning one.
 - **`no-extra-bind`**: Forbids `.bind()` on a function that never references
   `this` (and binds no arguments) — `(() => x).bind(obj)`,
   `function () { return 1 }.bind(this)`, `handler.bind(this)` where `handler`
@@ -540,6 +548,13 @@ This ESLint configuration prioritizes **explicit code** over convenient shortcut
   `verbatimModuleSyntax` / `isolatedModules`. Splitting type and value
   re-exports keeps the emitted module graph honest and a barrel file's
   value-vs-type surface legible. Auto-fixable.
+- **`no-useless-rename`**: Forbids renaming an import, export, or destructured
+  binding to the exact name it already has — `import { foo as foo } from
+'./foo'`, `export { bar as bar }`, `const { baz: baz } = obj`. The `as`/`:`
+  clause reads as if it transforms the binding, so a reader stops to compare
+  both sides only to discover they are identical: pure punctuation noise that
+  adds nothing. Exactly the ceremony an AI assistant spells out mechanically
+  for an alias it never needed. Auto-fixable with `eslint --fix`.
 
 ### Bundled Custom Rules
 

package/configs/length-rule-scope.js

@@ -0,0 +1,27 @@
+/**
+ * Function/File Length Rule Scope
+ *
+ * `files`/`ignores` scope shared by the strict (error-level)
+ * `max-lines-per-function`/`max-lines` block in `configs/overrides.js` and the
+ * `recommended` preset's warn-level equivalent (`exports/recommended.js`).
+ * Extracted to its own module so the two can never drift apart — the preset
+ * only needs to relax the *severity*, not widen or narrow which files the
+ * rules apply to (tests, stories, config files, and this package's own
+ * `index.js` stay exempt either way).
+ */
+
+export const lengthRuleFileMatch = {
+  files: ['**/*.{ts,tsx,js,jsx}'],
+  ignores: [
+    '**/*.stories.{js,jsx,ts,tsx}',
+    '**/*.test.{js,jsx,ts,tsx}',
+    '**/*.spec.{js,jsx,ts,tsx}',
+    '**/test/**/*.{js,jsx,ts,tsx}',
+    '**/tests/**/*.{js,jsx,ts,tsx}',
+    '**/__tests__/**/*.{js,jsx,ts,tsx}',
+    '**/configs/**/*.{js,ts}',
+    '*.config.{js,ts}',
+    'eslint.config.{js,ts}',
+    'index.js',
+  ],
+}

package/configs/overrides.js

@@ -7,6 +7,7 @@
 
 import globals from 'globals'
 import allRules from '../rules/index.js'
+import { lengthRuleFileMatch } from './length-rule-scope.js'
 
 export const overridesConfig = (
   sharedRestrictedSyntax,
@@ -87,19 +88,7 @@ export const overridesConfig = (
 
   // Function and file length rules - strict error thresholds
   {
-    files: ['**/*.{ts,tsx,js,jsx}'],
-    ignores: [
-      '**/*.stories.{js,jsx,ts,tsx}',
-      '**/*.test.{js,jsx,ts,tsx}',
-      '**/*.spec.{js,jsx,ts,tsx}',
-      '**/test/**/*.{js,jsx,ts,tsx}',
-      '**/tests/**/*.{js,jsx,ts,tsx}',
-      '**/__tests__/**/*.{js,jsx,ts,tsx}',
-      '**/configs/**/*.{js,ts}',
-      '*.config.{js,ts}',
-      'eslint.config.{js,ts}',
-      'index.js',
-    ],
+    ...lengthRuleFileMatch,
     rules: {
       'max-lines-per-function': allRules.maxFunctionLinesError,
       'max-lines': allRules.maxFileLinesError,

package/configs/typescript.js

@@ -58,6 +58,29 @@ export const typescriptConfig = (
         },
       ],
       'custom/no-default-class-export': 'error',
+      // Require an explicit return type on every function, not just the
+      // exported ones `explicit-module-boundary-types` would cover. Inferred
+      // return types are computed bottom-up from the body, so a refactor deep
+      // inside a helper can silently widen or change what it returns — a `null`
+      // branch added here, a `Promise` introduced there — and nothing flags it
+      // until that drift surfaces far away at a call site (or type-checks fine
+      // and ships as a runtime bug). Writing the type down inverts the check:
+      // the function body is now verified against the contract the author
+      // declared, so the mistake fails at the function itself instead of
+      // leaking outward. This is exactly the shortcut an AI assistant takes
+      // when it emits a helper and lets inference "figure out" the return type,
+      // which puts it squarely in this config's explicit-over-clever,
+      // fail-locally stance. It is type-aware but cheap (it reads the function
+      // signature, no whole-program analysis) and is in neither
+      // `eslint:recommended` nor typescript-eslint's `strictTypeChecked` /
+      // `stylisticTypeChecked` presets this config extends, so it must be
+      // enabled explicitly — which is why `tools-view` re-adds it by hand on
+      // top of the base config. It is scoped to `.ts`/`.mts`/`.cts` (this
+      // file's `files`) and deliberately NOT applied to `.tsx`: requiring an
+      // explicit return type on every JSX component is high-noise for little
+      // gain, so React function components stay exempt, matching how
+      // `tools-view` enables it on `src/**/*.ts` only.
+      '@typescript-eslint/explicit-function-return-type': 'error',
       'single-export/single-export': 'error',
       'required-exports/required-exports': [
         'error',

package/exports/recommended.d.ts

@@ -3,8 +3,11 @@ import type { Linter } from 'eslint'
 /**
  * Recommended (relaxed) preset: the default config with the most divisive rules
  * turned off (spec files, single export, custom `error/*`, optional chaining /
- * nullish-coalescing bans, and so on) for incremental adoption. Every surviving
- * rule still reports as an error.
+ * nullish-coalescing bans, and so on) for incremental adoption.
+ * `max-lines-per-function`/`max-lines` are downgraded to `warn` (same 70/100
+ * line thresholds as the strict default) so a real codebase's legacy long
+ * functions/files surface as backlog instead of failing CI. Every other
+ * surviving rule still reports as an error.
  */
 declare const config: Linter.Config[]
 

package/exports/recommended.js

@@ -24,6 +24,10 @@
  */
 
 import config from '../index.js'
+import { noProcessEnvironmentPropertiesConfig } from '../rules/no-process-env-properties/index.js'
+import { errorOptions as maxFunctionLinesErrorOptions } from '../rules/max-function-lines/index.js'
+import { errorOptions as maxFileLinesErrorOptions } from '../rules/max-file-lines/index.js'
+import { lengthRuleFileMatch } from '../configs/length-rule-scope.js'
 
 const relaxedOverrides = {
   name: 'eslint-config-agent/recommended-overrides',
@@ -71,11 +75,36 @@ const relaxedOverrides = {
     // adopt incrementally in any React/Preact + Tailwind codebase — by far the
     // most common modern setup — so relax it for the recommended preset.
     'jsx-classname/require-classname': 'off',
-    // The most divisive layer: this is where optional chaining (`?.`),
-    // nullish coalescing (`??`), type assertions and switch-default bans live.
-    // Relaxing it lets idiomatic TypeScript through during adoption.
-    'no-restricted-syntax': 'off',
+    // The most divisive layer: optional chaining (`?.`), nullish coalescing
+    // (`??`), type assertions, switch-default bans, and inline union/record
+    // type restrictions. Removing them lets idiomatic TypeScript through during
+    // adoption. The process.env guard (`no-process-env-properties`) is NOT in
+    // this group: scattered `process.env.FOO` access is a configuration smell
+    // regardless of adoption stage, so it is kept as the one surviving
+    // no-restricted-syntax check.
+    'no-restricted-syntax': ['error', noProcessEnvironmentPropertiesConfig],
   },
 }
 
-export default [...config, relaxedOverrides]
+// The strict default promotes function/file length to hard errors in its
+// final override layer (`configs/overrides.js`'s "Function and file length
+// rules" block) — at >70 lines per function and >100 lines per file — which
+// blocks incremental adoption: an existing codebase pointing `recommended` at
+// its real source tree still gets fatal errors on every long legacy
+// function/file, exactly the "wall of errors" this preset exists to avoid
+// (see issue #85). Downgrade both to `warn` while keeping the same 70/100
+// thresholds — and the same file scope (`lengthRuleFileMatch`, shared with
+// the strict block) — so the signal still surfaces in `eslint` output and the
+// backlog can be burned down, but it no longer fails a CI run that treats
+// errors as fatal. Consumers can re-enable these as errors with their own
+// override layer once they are ready.
+const lengthWarningOverrides = {
+  name: 'eslint-config-agent/recommended-length-warnings',
+  ...lengthRuleFileMatch,
+  rules: {
+    'max-lines-per-function': ['warn', maxFunctionLinesErrorOptions],
+    'max-lines': ['warn', maxFileLinesErrorOptions],
+  },
+}
+
+export default [...config, relaxedOverrides, lengthWarningOverrides]

package/index.js

@@ -26,6 +26,19 @@ const sharedRules = {
   ...allRules.pluginRules,
   'object-curly-newline': 'off',
   'no-shadow': 'off',
+  // The core `no-use-before-define` rule is intentionally left `off`: it
+  // false-positives on TypeScript type/interface declarations and enum
+  // members referenced before their textual position, which are hoisted and
+  // safe. `@typescript-eslint/no-use-before-define` below is the documented
+  // replacement — see that rule's comment for the full rationale.
+  'no-use-before-define': 'off',
+  // The core `no-unused-private-class-members` rule is intentionally left
+  // `off`: it only understands ECMAScript `#hashPrivate` fields, not
+  // TypeScript's `private` keyword, which is the actual dead-code surface in
+  // this codebase. `@typescript-eslint/no-unused-private-class-members` is
+  // the documented replacement — see that rule's comment for the full
+  // rationale.
+  'no-unused-private-class-members': 'off',
   'comma-dangle': 'off',
   'function-paren-newline': 'off',
   quotes: 'off',
@@ -84,6 +97,20 @@ const sharedRules = {
   // no-await-in-loop`. It is not in `eslint:recommended`, so it is enabled
   // explicitly here.
   'no-await-in-loop': 'error',
+  // Disallow loop conditions that reference a variable that is never modified
+  // inside the loop body. A loop whose condition tests a value that nothing
+  // inside the body ever updates is almost always a bug: either an unintended
+  // infinite loop or a forgotten increment / mutation. TypeScript does not
+  // catch this because the code is well-typed — the variable simply keeps its
+  // initial value and the condition never changes truth-value. This is exactly
+  // the kind of quiet, wrong-behavior bug AI assistants emit when they
+  // scaffold a loop body and lose track of what actually advances it. It is
+  // not in `eslint:recommended`, so it must be enabled explicitly here. The
+  // rule has a very low false-positive rate (genuine cases where an outer scope
+  // change is intended are rare and easy to suppress with a comment) and is not
+  // auto-fixable because only the author knows which variable was meant to
+  // change.
+  'no-unmodified-loop-condition': 'error',
   // Disallow an `else`/`else if` block when the preceding `if` already exits
   // the function via `return`. The `else` is dead weight: once the `if` branch
   // returns, the code after it is unreachable from that path, so wrapping the
@@ -116,6 +143,22 @@ const sharedRules = {
   // behind. The rule is auto-fixable, so consumers can adopt it with
   // `eslint --fix`.
   'no-useless-return': 'error',
+  // Require every `return` statement in a function to either always specify a
+  // value or never specify one. A function that returns a value on one branch
+  // and falls through — or hits a bare `return;` — on another silently yields
+  // `undefined` on the unhandled paths, and the caller then receives
+  // `undefined` where it expected the value. The bug surfaces far downstream as
+  // a "cannot read property of undefined" crash rather than at the offending
+  // branch, and the type checker does not reliably catch it: an inferred
+  // `T | undefined` return type type-checks cleanly even though the
+  // fall-through was accidental. This is exactly the quiet, plausible-but-wrong
+  // control-flow mistake an AI assistant emits when it adds an early-exit
+  // branch and forgets to carry a value through it. Not in `eslint:recommended`,
+  // so it must be enabled explicitly here. The rule is intentionally not
+  // auto-fixable — only the author knows whether the missing branch should
+  // return a value or the value-returning branch should stop returning one —
+  // so adoption surfaces the call sites rather than silently rewriting them.
+  'consistent-return': 'error',
   // Disallow a value assigned to a variable that is never read before the
   // variable is overwritten or its scope ends — a "dead store". Writing
   // `let total = compute()` and then unconditionally reassigning `total = 0`
@@ -181,6 +224,17 @@ const sharedRules = {
   // prevent. Enforcing it in the shared config means consumers no longer have
   // to re-add it on top of the package.
   eqeqeq: ['error', 'always'],
+  // Require the natural reading order in comparisons: the variable (or
+  // expression) on the left, the literal on the right — `count === 0`, never
+  // `0 === count`. The reversed "Yoda" form exists only to guard against the
+  // assignment typo `if (count = 0)`, but `eqeqeq` (directly above) already
+  // forces `===`/`!==` everywhere, and TypeScript flags accidental assignment
+  // in a condition as a type error, so the Yoda workaround is pure readability
+  // tax. `exceptRange` keeps the clearer range idiom (`0 <= x && x < limit`)
+  // which reads as a natural number-line comparison and is harder to express in
+  // the canonical order. The rule is auto-fixable, so consumers can adopt it
+  // with `eslint --fix`.
+  yoda: ['error', 'never', { exceptRange: true }],
   // Disallow reassigning function parameters and mutating their properties.
   // Reassigning a parameter decouples it from the caller's argument and hides the
   // function's real inputs; mutating a parameter's properties causes
@@ -275,6 +329,30 @@ const sharedRules = {
   // with `eslint --fix`; it is not in `eslint:recommended`, so it is enabled
   // explicitly here.
   'no-extra-bind': 'error',
+  // Disallow `.call()` and `.apply()` when the first argument (the `this`
+  // binding) is `undefined` or `null` and the result is identical to a
+  // direct call. `fn.call(null, a, b)` behaves exactly like `fn(a, b)` in
+  // non-strict mode and almost always in strict mode: the wrapper only adds
+  // noise and an extra property lookup. `fn.apply(undefined, [a, b])` is the
+  // same deadweight applied to a spread. The two are the direct-invocation
+  // counterpart of the `no-extra-bind` rule just above, which catches
+  // `.bind()` that never changes `this` — together they close the "look up
+  // the prototype chain to call the function" footgun an AI assistant emits
+  // when it wants to forward arguments or detach a method without realizing
+  // a direct call suffices. The rule is auto-fixable (`eslint --fix`) and is
+  // not in `eslint:recommended`, so it is enabled explicitly here.
+  'no-useless-call': 'error',
+  // Disallow renaming an import, export, or destructured binding to the exact
+  // name it already has — `import { foo as foo } from './foo'`,
+  // `export { bar as bar }`, `const { baz: baz } = obj`. The `as`/`:` clause
+  // reads as if it transforms the binding, so a reader stops to compare both
+  // sides only to discover they are identical: pure punctuation noise that
+  // adds nothing. It is the binding-alias sibling of `no-useless-call` just
+  // above — both look meaningful and are dead — and exactly the ceremony an
+  // AI assistant spells out mechanically for an alias it never needed. The
+  // rule is auto-fixable (`eslint --fix`) and is not in `eslint:recommended`,
+  // so it is enabled explicitly here.
+  'no-useless-rename': 'error',
   // Require `Object.hasOwn(obj, key)` over the legacy ways of asking the same
   // question. The two forms it replaces are each a footgun: calling
   // `obj.hasOwnProperty(key)` directly breaks the moment `obj` has a `null`
@@ -299,6 +377,18 @@ const sharedRules = {
   // explicit-over-clever, AI-safety stance. It is also the foundation the
   // `prefer-const` rule builds on. The rule is auto-fixable.
   'no-var': 'error',
+  // Disallow explicitly initializing a variable to `undefined` —
+  // `let value = undefined` instead of the equivalent, shorter `let value`.
+  // Every declared-but-unassigned binding is already `undefined`, so the
+  // initializer adds a token that looks like it is doing something (choosing
+  // a starting value) while actually doing nothing; a reader has to stop and
+  // confirm that `undefined` really is the intended value rather than a
+  // half-finished assignment the author forgot to fill in. It is exactly the
+  // no-op an AI assistant emits when it scaffolds a variable before deciding
+  // what to assign to it. Not in `eslint:recommended`, so it must be enabled
+  // explicitly here. The rule is auto-fixable (`eslint --fix` deletes the
+  // redundant initializer), so adoption costs nothing.
+  'no-undef-init': 'error',
   // Require object literal shorthand for properties and methods, so
   // `{ value: value }` collapses to `{ value }` and `{ run: function () {} }`
   // to `{ run() {} }`. The longhand forms carry no extra meaning — they are
@@ -324,6 +414,32 @@ const sharedRules = {
   // also exactly what an AI assistant trained on older code reaches for. The
   // rule is auto-fixable, so consumers can adopt it with `eslint --fix`.
   'operator-assignment': ['error', 'always'],
+  // Require the logical-assignment shorthand (`x ||= y`, `x &&= y`, `x ??= y`)
+  // wherever a binding is reassigned by a logical expression over itself. A
+  // longhand `x = x || defaultValue` names the target twice — once as the left
+  // operand of `||` and once as the assignment destination — which is the same
+  // duplicated-name typo site the `operator-assignment` rule directly above
+  // already catches for arithmetic operators. Writing `x ||= defaultValue`
+  // removes the second spelling of the name entirely so the assignment-by-typo
+  // footgun disappears, and it states the intent — "set this variable only if it
+  // is currently falsy / nullish / truthy" — in fewer characters and with the
+  // exact same semantics. The three forms map directly onto the boolean and
+  // nullish operators the config already steers code toward (`eqeqeq`,
+  // `@typescript-eslint/prefer-nullish-coalescing`): `&&=` for "assign only when
+  // truthy", `||=` for "assign only when falsy", `??=` for "assign only when null
+  // or undefined". `enforceForIfStatements: true` extends the check to the
+  // equivalent `if`-guarded form (`if (!x) x = y`, `if (x == null) x = y`), so
+  // both the expression and the statement spelling of the pattern are caught. The
+  // longhand `x = x || y` is also exactly what an AI assistant trained on
+  // pre-ES2021 code reaches for, which puts it squarely in this config's
+  // AI-safety scope alongside `operator-assignment`. The rule is auto-fixable
+  // (`eslint --fix`), so adoption is free, and it is not in `eslint:recommended`,
+  // so it must be enabled explicitly here.
+  'logical-assignment-operators': [
+    'error',
+    'always',
+    { enforceForIfStatements: true },
+  ],
   // Disallow chained assignment expressions such as `a = b = c = 0`. Chaining
   // collapses several writes into one expression: the value flows right-to-left
   // through bindings that have nothing to do with each other, so a reader has to
@@ -361,6 +477,21 @@ const sharedRules = {
   // explicit-over-clever, AI-safety scope. The rule is auto-fixable, so
   // consumers can adopt it with `eslint --fix`.
   'no-object-constructor': 'error',
+  // Disallow the primitive-wrapper constructors `new String()`, `new Number()`,
+  // and `new Boolean()`. These do the opposite of what they look like: instead of
+  // converting to a primitive they produce a **boxed object**, so
+  // `typeof new Number(5)` is `'object'` (not `'number'`),
+  // `new Boolean(false)` is always truthy (the object is truthy), and
+  // `new String('x') === 'x'` is `false`. The caller typically expects a
+  // primitive and the wrong type is a quiet, wrong-result trap that the type
+  // checker will not always catch when the boxed type is widened to `object`.
+  // For conversion use the unadorned call form (`Number(str)`, `String(n)`,
+  // `Boolean(x)`) — that is what `no-implicit-coercion` already pushes code
+  // toward, and these two rules are complementary: `no-implicit-coercion` bans
+  // the shorthand coercions (`!!x`, `+str`), `no-new-wrappers` bans the
+  // constructor path to the same wrong object. The rule is auto-fixable, so
+  // consumers can adopt it with `eslint --fix`.
+  'no-new-wrappers': 'error',
   // Require object spread (`{ ...a, ...b }`) over `Object.assign({}, a, b)` when
   // the call is building a brand-new object (its first argument is an object
   // literal). The `Object.assign({}, ...)` form is a more indirect, punctuation-
@@ -392,6 +523,25 @@ const sharedRules = {
     'error',
     { allowImplicit: false, checkForEach: true },
   ],
+  // Disallow a loop whose body always exits on the first iteration — a `for`,
+  // `while`, or `do...while` where every control-flow path ends in `return`,
+  // `break`, or `throw`. Such a loop can never reach a second pass: it reads
+  // as "iterate every element" but actually runs at most once, collapsing what
+  // the author probably meant as a search into a single-element check. The
+  // classic form is a misplaced `return` inside a `for-of`:
+  //   `for (const item of list) { if (cond(item)) return item; return null }`
+  // The unconditional `return null` exits on the first iteration regardless of
+  // the condition, so every element after the first is silently ignored. This
+  // is a wrong-result correctness bug that type checking cannot catch (the
+  // types are fine; only the data flow is broken) and exactly the shape AI
+  // assistants emit when they flatten a "find the first match" pattern into a
+  // loop and lose track of which exit belongs where. It is the loop-level
+  // sibling of `array-callback-return` directly above: both catch the "loop
+  // body was supposed to visit every element, but silently doesn't" class of
+  // mistake. The rule is not in `eslint:recommended`, so it is enabled
+  // explicitly. It is not auto-fixable because only the author knows whether
+  // the loop or the misplaced exit is wrong.
+  'no-unreachable-loop': 'error',
   // Only allow throwing real `Error` objects — reject `throw 'boom'`,
   // `throw { code: 500 }`, `throw 42` and any other non-Error value. A thrown
   // string or plain object carries no stack trace, so the failure surfaces with
@@ -423,6 +573,26 @@ const sharedRules = {
   // keeps the check legible. The rule is not auto-fixable because only the
   // author knows which operand was meant.
   'no-self-compare': 'error',
+  // Disallow a binary or logical expression whose result is provably
+  // constant regardless of a variable operand: a `&&`/`||` whose left side
+  // is already a statically known boolean (`true || sideEffect()`, `false
+  // && sideEffect()` — the right side, and any side effect in it, never
+  // runs, yet reads as if it were conditional), a loose-equality check
+  // against `null`/`undefined` where the other side can never be nullish
+  // (`null == undefined` — always `true`), or a `===`/`!==` comparison
+  // between two freshly constructed objects (`new Error() === new
+  // Error()` — two distinct object references can never be `===`-equal, so
+  // the comparison always evaluates the same way no matter what either
+  // constructor does). Each of these type-checks and runs without error, so
+  // the constant result hides behind what reads like a real, live
+  // condition. This is exactly the family `no-self-compare` and
+  // `no-unsafe-optional-chaining` above already guard against: a condition
+  // that looks meaningful but is defeated by its own operands, and
+  // precisely the copy-paste slip an AI assistant leaves behind when it
+  // stubs out a condition with a literal or duplicates a `new` expression on
+  // both sides of a comparison. Not auto-fixable: only the author knows
+  // which operand was meant.
+  'no-constant-binary-expression': 'error',
   // Disallow optional chaining in positions where a short-circuit to
   // `undefined` is immediately used in a way that throws at runtime — member
   // access, a call, arithmetic, spread, `instanceof`, `in`, or destructuring on
@@ -473,6 +643,24 @@ const sharedRules = {
   // and not the `Function` constructor). The rule is not auto-fixable because
   // only the author can restate the string body as real code.
   'no-new-func': 'error',
+  // Disallow monkey-patching the prototype of a built-in object —
+  // `Array.prototype.last = function () { ... }`,
+  // `Object.prototype.keysOf = function () { ... }`, `String.prototype.foo = ...`.
+  // The patch mutates global state every module and dependency shares: the
+  // effect is invisible at the call site, order-dependent (whoever loads first
+  // wins, so two libraries patching the same prototype clash silently), and an
+  // enumerable addition to `Object.prototype` / `Array.prototype` leaks into
+  // every `for...in` loop and `in` check in the program, quietly breaking
+  // unrelated code. A safe, explicit equivalent always exists — a standalone
+  // helper (`last(arr)`) or a local wrapper — so the patch buys a little
+  // call-site sugar at the cost of a global hazard, and it is exactly the
+  // shortcut an AI assistant reaches for when asked to "add a method to
+  // arrays." This is the prototype-mutation sibling of the `no-new-func` ban
+  // directly above. It is not in `eslint:recommended`, so it must be enabled
+  // explicitly. Not auto-fixable: only the author can move the behavior into a
+  // standalone function. Extending a user-defined class is unaffected — the
+  // rule only flags built-in globals.
+  'no-extend-native': 'error',
   // Disallow `eval(...)`. It hands a string to the JavaScript engine to parse
   // and run at runtime: the body is opaque to the parser, the type checker and
   // every reader, it can reach and mutate the surrounding scope, and feeding it
@@ -526,6 +714,35 @@ const sharedRules = {
   // guard. The rule is not auto-fixable because only the author knows whether a
   // given `console.log` should be deleted or promoted to a real log channel.
   'no-console': ['error', { allow: ['warn', 'error'] }],
+  // Disallow the `debugger` statement. A `debugger` left in source pauses
+  // execution under an attached devtools/inspector and is otherwise a no-op, so
+  // it is purely a debugging artifact that should never reach a commit — the
+  // statement-shaped sibling of the throwaway `console.log` that `no-console`
+  // directly above already bans. It is invisible to the type checker and most
+  // code review, ships silently, and is exactly the leftover an AI assistant
+  // emits while "stepping through" a problem. `eslint-config-agent` does not
+  // extend `eslint:recommended` (where this rule lives), so it must be enabled
+  // explicitly. The rule is auto-fixable — `eslint --fix` deletes the
+  // statement — so adoption is cheap. Several of my repos (e.g.
+  // `tupe12334/animals-shop`) re-add `no-debugger: 'error'` by hand on top of
+  // the shared config; porting it here removes that copy-paste.
+  'no-debugger': 'error',
+  // Disallow `alert()`, `confirm()`, and `prompt()`. These browser dialog APIs
+  // are exclusively debugging artifacts: `alert(value)` is the browser-native
+  // counterpart of `console.log` — a quick "did I reach here / what is this
+  // value?" check — but one that blocks the UI thread and cannot be silenced in
+  // production without a runtime patch to `window.alert`. Like `no-console` and
+  // `no-debugger` directly above, the rule exists to prevent leftover debugging
+  // scaffolding from reaching a commit: the three rules together guard every
+  // major "quick check" channel that AI assistants reach for when they want to
+  // inspect state or get user input inline without wiring a real UI or log
+  // channel. `confirm` and `prompt` are included because they carry the same
+  // blocking, production-hostile behavior and are equally likely to appear in
+  // AI-generated event handlers ("just pop a confirm dialog for now"). The rule
+  // is not in `eslint:recommended`, so it must be enabled explicitly. It is not
+  // auto-fixable because only the author knows whether the call should be
+  // deleted, replaced with a proper log, or wired to a real modal component.
+  'no-alert': 'error',
   // Require a regex literal (`/\d+/`) instead of the `RegExp` constructor with
   // a string argument (`new RegExp('\\d+')`, `RegExp('\\d+')`) when the pattern
   // is a static string. The string form forces every backslash to be escaped
@@ -547,6 +764,78 @@ const sharedRules = {
   // runtime, is left untouched. The rule is auto-fixable for the simple cases,
   // so consumers can adopt much of it with `eslint --fix`.
   'prefer-regex-literals': ['error', { disallowRedundantWrapping: true }],
+  // Require named capture groups (`(?<year>\d{4})`) instead of positional ones
+  // (`(\d{4})`). An unnamed capture group is referenced by a fragile positional
+  // index — `match[1]`, `match[2]` — whose meaning evaporates the moment a
+  // group is added, removed, or reordered: `match[1]` silently shifts to a
+  // different piece of the string with no type error and no runtime warning.
+  // Named groups surface the intent in the regex itself (`(?<year>\d{4})`) and
+  // are accessed by key (`match.groups.year`), so the code stays readable and
+  // correct even as the pattern evolves. This is the regex-shaped sibling of
+  // the explicit-over-clever stance this config already enforces in the rest of
+  // the rule set: an unnamed group is exactly the "I'll remember what index 2
+  // means" shortcut that doesn't age and that AI assistants emit by default
+  // whenever they scaffold a regex. Non-capturing groups (`(?:...)`) are
+  // unaffected — only groups that capture and expose a match need a name. The
+  // rule is not in `eslint:recommended` and is not covered by
+  // `unicorn.configs.all`, so it is enabled explicitly here. It is not
+  // auto-fixable because only the author knows what name to give each group.
+  'prefer-named-capture-group': 'error',
+  // Disallow the comma operator — `a = 1, b = 2`, `for (i = 0, j = 0; ...)`,
+  // `return a++, b`. The comma operator evaluates both operands left-to-right
+  // and returns the *right-hand* value, silently discarding the left. That is
+  // almost never intentional: in almost every real occurrence the author either
+  // meant a semicolon (two separate statements), an array literal, or a
+  // destructuring assignment — the comma operator just lets the mistake compile
+  // without error. It is the hidden-mutation sibling of the assignment
+  // discipline rules already here (`no-multi-assign`, `no-return-assign`,
+  // `no-useless-assignment`): all of them surface values that look meaningful
+  // but are silently discarded or overwritten, exactly the "clever but wrong"
+  // pattern this config exists to prevent and one AI assistants emit when
+  // packing multiple side effects onto a single expression. The one legitimate
+  // use — `for` loop initializers and updates with multiple variables — is
+  // carved out by the `allowInParentheses: false` default (the option only
+  // affects the parenthesized `(a, b)` form used to suppress some parsers).
+  // For `for` loop heads that genuinely need two counters, a destructuring
+  // `let [i, j] = [0, 0]` states the intent clearly. The rule is not in
+  // `eslint:recommended`, so it is enabled explicitly here. It is not
+  // auto-fixable because only the author knows whether to split into separate
+  // statements or rewrite the expression entirely.
+  'no-sequences': 'error',
+  // Disallow empty constructors (`class Foo { constructor() {} }`) and
+  // constructors whose only statement forwards all arguments to `super`
+  // (`class Foo extends Bar { constructor(...args) { super(...args); } }`). In
+  // both cases the constructor adds nothing: JavaScript already synthesizes an
+  // implicit empty constructor for base classes and an implicit forwarding
+  // constructor for subclasses, so writing them out is pure dead weight — visual
+  // noise that looks load-bearing but changes nothing. They are boilerplate an
+  // AI assistant reflexively emits when scaffolding a class from a template,
+  // putting them squarely in this config's explicit-over-clever, "dead code is
+  // not free" stance: the class-declaration siblings of `no-useless-return`,
+  // `no-useless-assignment`, and `no-extra-bind` already active here. The rule
+  // is auto-fixable, so adopters get a one-shot `eslint --fix`. The core rule
+  // is enabled here for JavaScript files; TypeScript files get the same
+  // behavior via `@typescript-eslint/no-useless-constructor` enabled by the
+  // `strictTypeChecked` preset (which extends `recommended`), so the core rule
+  // is turned off in `typescriptEslintRules` to avoid double-reporting.
+  'no-useless-constructor': 'error',
+  // Disallow returning a value from a class constructor (`return someObject`,
+  // `return 5`). `new Thing()` has a contract every caller relies on: the
+  // expression evaluates to the instance that was just constructed. Returning
+  // an object from the constructor silently overrides that — `new Thing()`
+  // hands back a *different* object than the class body initialized, so
+  // `instanceof Thing` no longer holds for the value the rest of the program
+  // sees. Returning a primitive is the opposite trap: the return value is
+  // ignored outright by the `new` semantics, so the statement is dead code
+  // that reads as if it does something. Both are exactly the kind of silent,
+  // contract-breaking footgun this config exists to catch, and the sort of
+  // misplaced `return` an AI assistant emits when it treats a constructor
+  // like an ordinary function. A bare early `return;` with no value to bail
+  // out of the constructor is unaffected — only returning a value is flagged.
+  // The rule is not in `eslint:recommended`, so it is enabled explicitly. It
+  // is not auto-fixable because only the author knows whether the returned
+  // value or the constructor itself is wrong.
+  'no-constructor-return': 'error',
 }
 
 // Shared no-restricted-syntax rules for both JS and TS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-config-agent",
-  "version": "3.0.5",
+  "version": "3.1.0",
   "description": "ESLint configuration package with TypeScript support",
   "main": "index.js",
   "types": "./index.d.ts",
@@ -40,7 +40,7 @@
     "configs/",
     "plugins/",
     "exports/",
-    "rules/**/index.js",
+    "rules/**/*.js",
     "!rules/**/examples/",
     "!rules/**/*.spec.js",
     "!rules/**/*.test.js"
@@ -68,6 +68,7 @@
     "test:recommended": "node scripts/test-recommended.js",
     "test:recommended-incremental": "node scripts/test-recommended-incremental.js",
     "test:exports": "node scripts/test-exports.js",
+    "test:pack": "node scripts/verify-pack.js",
     "test:incremental": "node scripts/test-incremental.js",
     "test:types": "tsc -p test/types/tsconfig.json",
     "test:edge": "eslint test/edge-cases.tsx",

package/rules/plugin/n/index.js

@@ -2,4 +2,18 @@ import { noProcessEnvironmentConfig } from './no-process-env/index.js'
 
 export const nRules = {
   'n/no-process-env': noProcessEnvironmentConfig,
+  // Require the `node:` protocol prefix on every import of a Node.js built-in
+  // module (e.g. `import fs from 'node:fs'` instead of `import fs from 'fs'`).
+  // The bare form (`'fs'`, `'path'`, `'crypto'`) is ambiguous: without the
+  // protocol, a reader (and a bundler) must consult package.json to confirm
+  // that the name is not a userland npm package shadowing the built-in. The
+  // `node:` prefix is unambiguous at a glance, is supported since Node 14.18.0
+  // (the minimum already required by this package's `engines` field), and is
+  // the form the package itself uses in all its own scripts and custom rules
+  // (e.g. `import { existsSync } from 'node:fs'`). Shipping the rule in the
+  // shared set means consuming projects inherit the same convention
+  // automatically. The rule is auto-fixable (`eslint --fix`), so adoption is
+  // free. It fires only when a built-in module is actually imported — browser
+  // and React code that imports nothing from Node.js is unaffected.
+  'n/prefer-node-protocol': 'error',
 }

package/rules/plugin/react/index.js

@@ -1,5 +1,19 @@
 export const reactRules = {
-  'react/self-closing-comp': 'off',
+  // Require self-closing tags for JSX components and HTML elements that have
+  // no children. `<Button></Button>` and `<div></div>` become `<Button />` and
+  // `<div />` respectively. An explicit open/close tag pair is meaningful only
+  // when it contains children; without children it is pure noise — it adds an
+  // extra close tag the reader has to scan past to confirm nothing is inside,
+  // and it is exactly the verbose form AI assistants emit when scaffolding
+  // components from a template. The single-tag form states "this element has
+  // no children" directly, which is the explicit, low-noise style this config
+  // favors throughout. The rule is auto-fixable, so `eslint --fix` collapses
+  // every violating element in one pass. `component: true` covers React
+  // components (`<MyComp></MyComp>`) and `html: true` covers intrinsic
+  // elements (`<div></div>`, `<span></span>`), so both surfaces stay
+  // consistent. `oss-il` already enforces this manually on top of the base
+  // config; promoting it here removes that copy-paste.
+  'react/self-closing-comp': ['error', { component: true, html: true }],
   'react/destructuring-assignment': 'off',
   'react/jsx-props-no-spreading': 'off',
   'react/button-has-type': 'off',
@@ -12,7 +26,16 @@ export const reactRules = {
   'react/require-default-props': 'off',
   'react/jsx-wrap-multilines': 'off',
   'react/jsx-closing-bracket-location': 'off',
-  'react/jsx-no-useless-fragment': 'off',
+  // Forbid fragments that wrap a single child: `<><MyComponent /></>` adds DOM
+  // overhead and a return-type mismatch (`React.ReactElement` vs `JSX.Element`)
+  // without buying anything. It is exactly the kind of dead-weight an AI
+  // assistant emits when scaffolding a component. `allowExpressions: false`
+  // also covers `<>{value}</>` — if you need a fragment solely for a JSX
+  // expression, wrap it in a parent instead. The rule is auto-fixable, so
+  // `eslint --fix` rewrites `<><X /></>` to `<X />` with zero manual work.
+  // oss-il already enables this by hand on top of the base config; promoting
+  // it here removes the per-repo copy-paste.
+  'react/jsx-no-useless-fragment': ['error', { allowExpressions: false }],
   // Guard against React's "leaked render" bug: a short-circuit like
   // `{count && <List />}` renders the literal `0` (or `NaN`) when the left
   // operand is a falsy *non-boolean*, and `{name && <h1>{name}</h1>}` renders
@@ -62,6 +85,23 @@ export const reactRules = {
   // intentional decision visible in code review. The rule is not auto-fixable,
   // so each suppression is a deliberate act.
   'react/no-danger': 'error',
+  // Enforce the `[value, setValue]` naming convention for `useState` pairs.
+  // When `useState` is destructured with a setter that does not match
+  // `set<Capitalize(stateName)>` — e.g. `const [data, handleUpdate] = useState()`
+  // instead of `const [data, setData] = useState()` — the mismatch signals a
+  // naming mistake that often means the wrong setter was wired up: the right
+  // value is read but a misnamed variable is written on update, a class of
+  // silent state-management bug that type-checking cannot catch (both names are
+  // just `Dispatch<SetStateAction<T>>`). AI assistants introduce exactly this
+  // slip when stitching a component from multiple snippets — emitting
+  // `const [user, setCurrentUser] = useState()` or
+  // `const [loading, handleLoadingChange] = useState(false)`, each of which
+  // compiles fine but breaks the per-component naming contract that makes state
+  // variables identifiable at a glance. The rule is not auto-fixable because
+  // only the author knows whether the state name or the setter name is the
+  // intended canonical one. It fires only on `.tsx`/`.jsx` files, so pure
+  // TypeScript packages are unaffected.
+  'react/hook-use-state': 'error',
   // Forbid a freshly-constructed value as the `value` of a Context Provider:
   // `<Ctx.Provider value={{ user, setUser }}>` or `value={[state, dispatch]}`
   // or `value={() => ...}`. The object/array/function literal is rebuilt on
@@ -82,4 +122,43 @@ export const reactRules = {
   // is why a downstream repo (`oss-il`) already re-adds it by hand on top of the
   // base config.
   'react/jsx-no-constructed-context-values': 'error',
+  // Forbid using an object type (`{}`, `[]`, or a function literal) as the
+  // default value for a prop in function-component destructuring:
+  //
+  //   function List({ items = [], onSelect = () => {} }) { ... }
+  //
+  // Each call to the component creates a fresh object/array/function literal
+  // for the default, so the reference changes on every render even when the
+  // prop is not actually provided. Any child that is `React.memo`-ed on that
+  // prop, or any `useEffect`/`useCallback`/`useMemo` that lists it as a
+  // dependency, will re-run unnecessarily — a silent performance bug the type
+  // checker cannot detect. The fix is to hoist the constant outside the
+  // component or memoize it:
+  //
+  //   const DEFAULT_ITEMS: string[] = []
+  //   function List({ items = DEFAULT_ITEMS }) { ... }
+  //
+  // This is exactly the shortcut an AI assistant reaches for when a prop is
+  // optional and the model doesn't want to add a module-level constant. The
+  // rule sits on the same correctness/perf-not-style bar as `jsx-no-leaked-
+  // render`, `no-array-index-key`, and `jsx-no-constructed-context-values`
+  // above — all of which catch silent reference-equality bugs that are
+  // invisible to the type checker. Like the other react rules this only fires
+  // on `.jsx`/`.tsx` files, so non-React TypeScript packages are unaffected.
+  'react/no-object-type-as-default-prop': 'error',
+  // Require a `key` prop on every element created inside an array/iterator
+  // (`.map()`, a spread of JSX literals, etc.). `key` is React's per-child
+  // identity across renders; without it React falls back to matching children
+  // by position, so as soon as the list is reordered, filtered, or gains/loses
+  // an item, state and DOM nodes "smear" onto the wrong element — text typed
+  // into one row's input jumps to another, the wrong checkbox stays checked,
+  // an animation plays on the wrong item. The JSX is perfectly typed either
+  // way, so this is a real rendering bug invisible to the type checker, and
+  // exactly the shortcut an AI assistant reaches for when it renders a list
+  // without pausing to think about identity. It sits on the same
+  // correctness-not-style bar as `no-array-index-key`, `jsx-no-leaked-render`,
+  // and `jsx-no-constructed-context-values` above. Like the other react rules
+  // it only applies to `.jsx`/`.tsx` files, so non-React TypeScript packages
+  // are unaffected.
+  'react/jsx-key': 'error',
 }

package/rules/plugin/typescript-eslint/index.js

@@ -2,8 +2,58 @@ import { noExplicitAnyConfig } from './no-explicit-any/index.js'
 
 export const typescriptEslintRules = {
   ...noExplicitAnyConfig,
+  // `strictTypeChecked` (which this config extends) enables
+  // `@typescript-eslint/only-throw-error` — the type-aware replacement for the
+  // core `no-throw-literal` rule that catches additional cases (e.g. throwing a
+  // variable typed as `string | Error`). The core rule is still active in
+  // `sharedRules` and, because `sharedRules` is spread into the TypeScript
+  // config *after* the preset, it overrides the preset's own `no-throw-literal:
+  // 'off'`. Turning the core rule off here (in `typescriptEslintRules`, which
+  // is spread after `sharedRules`) ensures TypeScript files are checked only by
+  // the type-aware rule so there is no double-reporting of the same violation.
+  // The core rule remains active for `.js`/`.jsx` files via `sharedRules`,
+  // where the type-aware version does not run.
+  'no-throw-literal': 'off',
+  // `strictTypeChecked` (which this config extends) includes `recommended`,
+  // which enables `@typescript-eslint/no-useless-constructor` for TypeScript
+  // files. The core `no-useless-constructor` rule is active in `sharedRules`
+  // for JavaScript files. Turning the core rule off here ensures TypeScript
+  // files are covered only by the TypeScript-aware variant, preventing
+  // double-reporting on the same constructor.
+  'no-useless-constructor': 'off',
+  // `stylisticTypeChecked` (which this config extends) enables
+  // `@typescript-eslint/prefer-nullish-coalescing`, recommending `??` over `||`
+  // for nullable-type checks. However, this config deliberately bans the `??`
+  // operator via a `no-restricted-syntax` rule (see `noNullishCoalescingConfig`)
+  // in favour of explicit `!== null && !== undefined` checks. With both active,
+  // a user writing `x || 'default'` (where `x` is nullable) gets
+  // `prefer-nullish-coalescing` telling them to use `??`, and then
+  // `no-restricted-syntax` forbidding the `??` they just added — an
+  // unresolvable contradiction. Turning this rule off here lets
+  // `no-restricted-syntax` be the single, authoritative constraint: reach for
+  // explicit null checks, not `??`.
+  '@typescript-eslint/prefer-nullish-coalescing': 'off',
   '@typescript-eslint/consistent-type-assertions': 'off',
   '@typescript-eslint/consistent-type-definitions': ['error', 'interface'],
+  // Force the **property style** (`foo: (x: number) => void`) for every method
+  // member of an interface or object type, and forbid the **method shorthand**
+  // (`foo(x: number): void`). The two forms look interchangeable but are not:
+  // TypeScript deliberately exempts method-shorthand signatures from
+  // `strictFunctionTypes` and checks them *bivariantly* (a documented language
+  // unsoundness), while property-style signatures are checked *contravariantly*
+  // (sound). In practice a method-shorthand declaration silently accepts an
+  // incompatible callback or override that the property style would reject —
+  // the incompatibility passes type-checking and only surfaces as a wrong call
+  // at runtime. That is exactly the "looks typed, fails at runtime" gap this
+  // config exists to close, and it is the signature-side companion of the
+  // already-enabled `no-non-null-assertion` and `require-array-sort-compare`
+  // rules. The rule is *not* in typescript-eslint's `strictTypeChecked` preset
+  // this config extends, so it must be turned on explicitly. It is
+  // **auto-fixable** (`eslint --fix`), so adoption costs nothing. Both
+  // `tupe12334/zod-utils` and `tupe12334/tools-view` already re-add it by hand
+  // on top of the shared config; promoting it here removes that copy-paste and
+  // covers every downstream consumer.
+  '@typescript-eslint/method-signature-style': ['error', 'property'],
   // Require a `case` for every member of the union/enum a `switch` discriminates
   // on. This is the type-aware completion of the `no-restricted-syntax` ban on
   // `default` cases this config already ships ("Default cases are not allowed in
@@ -139,6 +189,37 @@ export const typescriptEslintRules = {
   // by hand on top of the base config — promoting it into the shared rule set
   // removes that copy-paste.
   '@typescript-eslint/no-shadow': 'error',
+  // Forbid referencing a `let`/`const`/`class` binding before its textual
+  // declaration. Thanks to the Temporal Dead Zone, an early reference to such
+  // a binding does not read `undefined` — it throws a `ReferenceError` at
+  // runtime, so the file can type-check and look correct while a particular
+  // code path (a closure invoked before its outer scope finishes
+  // initializing, a module-level `const` referenced by another before both
+  // have run) blows up only when actually executed. That looks-right-fails-
+  // at-runtime gap is exactly what this config exists to close. Declaration
+  // order should be a reliable signal of evaluation order; this rule makes
+  // violations a lint error instead of a surprise crash.
+  //
+  // The core `no-use-before-define` rule is intentionally left `off` (see
+  // `sharedRules` in `index.js`): it does not understand TypeScript's hoisted
+  // type-level declarations (`interface`, `type`, and `enum` members are safe
+  // to reference before their textual position) and would false-positive on
+  // them. The typescript-eslint version understands those cases, so it is the
+  // documented replacement rather than a second rule fighting the first. It
+  // needs no type information, so it adds no parser cost.
+  //
+  // `functions: false` exempts function declarations, which are fully
+  // hoisted (including their body) and safe to call before their textual
+  // definition — flagging them would only add noise, not catch a real bug.
+  // `classes` and `variables` stay `true` because those bindings are hoisted
+  // but left uninitialized (the TDZ), so referencing them early is the actual
+  // runtime hazard this rule exists to catch. This mirrors how downstream repo
+  // `ameliso-io/web` already configures the rule by hand on top of the base
+  // config — promoting it into the shared rule set removes that copy-paste.
+  '@typescript-eslint/no-use-before-define': [
+    'error',
+    { functions: false, classes: true, variables: true },
+  ],
   // Forbid declaring a function inside a loop when that function closes over a
   // binding that changes between iterations. A function created in a loop
   // captures its outer variables *by reference*, not by value, so every closure
@@ -162,6 +243,19 @@ export const typescriptEslintRules = {
   // signal without the false positives the core rule raises in typed code. It
   // needs no type information, so it adds no parser cost.
   '@typescript-eslint/no-loop-func': 'error',
+  // Prefer optional chaining (`a?.b?.c`) over a chain of `&&` null-guards
+  // (`a && a.b && a.b.c`). The `&&`-chain form evaluates the base expression
+  // repeatedly and handles `0`, `""`, and `false` as "missing" — a falsy-value
+  // coercion bug the type checker cannot catch because the operator is
+  // perfectly typed. Optional chaining short-circuits on `null`/`undefined`
+  // only, evaluates the base once, and is the form TypeScript was designed to
+  // express. It is also shorter and reads left-to-right with no repeated
+  // sub-expressions. The rule is auto-fixable (`eslint --fix`), so adoption is
+  // cheap. It lives in typescript-eslint's `stylistic-type-checked` preset but
+  // NOT in `strict-type-checked`, which is why this config (extending
+  // `strictTypeChecked`) must enable it explicitly — and why a downstream repo
+  // (`tools-view`) already re-adds it by hand on top of the base config.
+  '@typescript-eslint/prefer-optional-chain': 'error',
   // Require any function that returns a `Promise` to be declared `async`. A
   // plain (non-`async`) function that returns a promise can still throw
   // *synchronously* — anything that runs before the promise is constructed (an
@@ -208,4 +302,112 @@ export const typescriptEslintRules = {
   // running under the `projectService` parser options already configured for
   // `.ts`/`.tsx`.
   '@typescript-eslint/return-await': ['error', 'in-try-catch'],
+  // Flag Promises used in positions where their resolution value cannot be
+  // observed — the fourth side of the async-hygiene quadrant already in this
+  // config (`no-floating-promises`, `promise-function-async`, `return-await`).
+  //
+  // Three patterns are caught:
+  //
+  // 1. `checksVoidReturn` (default `true`): an async function passed where the
+  //    callback's return type is `void` — the textbook case is
+  //    `array.forEach(async item => { await work(item) })`. The returned
+  //    `Promise<void>` is structurally assignable to `void`, so TypeScript's
+  //    own type-checker never flags it, but the Promise is silently dropped and
+  //    its rejection becomes an unhandled rejection crash. The fix is an
+  //    explicit `for...of` loop with `await`, or an `async` wrapper that is
+  //    then awaited by the caller.
+  //
+  // 2. `checksConditionals` (default `true`): a Promise used directly in a
+  //    boolean context — `if (fetchData())` or `while (poll())`. The Promise
+  //    object itself is always truthy, so the condition never reflects the
+  //    resolved value; this is almost always a missing `await`.
+  //
+  // 3. `checksSpreads` (default `true`): `{...asyncFn()}` spreads the Promise
+  //    object's own properties (none meaningful) instead of the resolved
+  //    object's properties — a silent data-loss bug.
+  //
+  // All three are silent: TypeScript does not flag them, the code runs without
+  // a syntax error, and the bug surfaces at runtime as either a missing
+  // side-effect, an always-true conditional, or an empty object spread. They
+  // are exactly the "looks correct, fails at runtime" shortcuts an AI assistant
+  // produces when it wraps async work in a sync-looking callback or forgets an
+  // `await`. The rule is type-aware, so it runs under the `projectService`
+  // parser options already configured for `.ts`/`.tsx` files. Downstream repos
+  // (`book-processor`) already promote this rule to `error` on top of the base
+  // config — promoting it into the shared rule set removes that copy-paste.
+  '@typescript-eslint/no-misused-promises': 'error',
+  // Require an explicit initializer for every enum member. Without one,
+  // TypeScript assigns implicit numeric values (0, 1, 2, …) based on the
+  // member's position in the declaration. Reordering members or inserting a
+  // new one in the middle silently changes every subsequent member's numeric
+  // value — a breaking API change for any caller that stored or compared the
+  // raw numbers. The type-checker cannot flag this: the values are still typed
+  // as the enum, not as literal `0`/`1`/`2`, so the mismatch only surfaces at
+  // runtime. Writing an explicit initializer (`= 'Up'`, `= 1`) makes the
+  // assigned value visible and independent of position: adding or reordering
+  // members is now safe by construction, and the intent is legible without
+  // counting indices. It is exactly the "looks stable, breaks on extension"
+  // footgun AI assistants introduce when they generate an enum and leave the
+  // compiler to decide the values — the enum counterpart of the
+  // `array-callback-return` and `switch-exhaustiveness-check` rules this
+  // config already ships for other "silent missing value" bugs. The rule is
+  // not in `strictTypeChecked` or `stylisticTypeChecked`, so it must be
+  // enabled explicitly. It is not auto-fixable: only the author knows what
+  // each member's value should be.
+  '@typescript-eslint/prefer-enum-initializers': 'error',
+  // Forbid enum declarations that mix numeric and string member values. TypeScript
+  // allows both `Status.Active = 0` (number) and `Status.Name = 'active'`
+  // (string) in the same declaration, but the resulting type widens in
+  // surprising ways: a mixed enum has no reverse-mapping for string members,
+  // exhaustiveness checks over it behave differently depending on TypeScript
+  // version, and `Object.values(Status)` returns `[0, 'active']` — a
+  // heterogeneous array the caller rarely expects. Combined with the existing
+  // `prefer-enum-initializers` rule (which makes every member's value
+  // explicit), this rule makes the *kind* of value explicit too: all numbers or
+  // all strings, never both. It is exactly the implicit ambiguity an AI
+  // assistant introduces when it scaffolds an enum from a mixed-type spec ("id
+  // is 0, label is 'active'") without deciding which kind to use. The rule is
+  // not in `strictTypeChecked` or `stylisticTypeChecked`, so it must be enabled
+  // explicitly. It is not auto-fixable: only the author knows whether to
+  // normalize to numbers or strings.
+  '@typescript-eslint/no-mixed-enums': 'error',
+  // Flag a condition, `&&`/`||` operand, or optional-chain (`?.`) link whose
+  // type proves it can never be anything but truthy or never be anything but
+  // falsy. A guard like `if (value)` where `value`'s type is a non-nullable
+  // object looks like a real null/undefined check, but the type checker has
+  // already proven it always passes — the "guard" is dead code that silently
+  // hides the fact the author expected a case (`null`, `undefined`, `false`)
+  // the type no longer allows, usually because an earlier refactor narrowed
+  // the type and left a now-redundant check behind. The inverse (a condition
+  // that is always falsy) is worse: the guarded branch is unreachable dead
+  // code that looks live. Both are exactly the "looks like a safety check,
+  // does nothing" gap this config exists to close, and the type-aware
+  // completion of the same always-true/false class of bug
+  // `no-self-compare` and `no-constant-binary-expression` already catch by
+  // syntax alone. The rule is type-aware, so it runs under the
+  // `projectService` parser options already configured for `.ts`/`.tsx`
+  // files, and it is why downstream repo `block-no-verify` already re-adds
+  // it by hand on top of the base config.
+  '@typescript-eslint/no-unnecessary-condition': 'error',
+  // Forbid a `private` (TypeScript keyword) or `#hashPrivate` class field or
+  // method that is declared and never read or called anywhere in the class
+  // body. Because the member is private, there is no legitimate external
+  // caller to account for — an unused one is dead code: a leftover from a
+  // refactor that forgot to delete it, or worse, a member the author meant to
+  // wire up but a typo or missed call site left orphaned, silently doing
+  // nothing while the reader assumes it does something.
+  //
+  // The core `no-unused-private-class-members` rule (already enabled via
+  // `eslint:recommended`) only understands ECMAScript `#hashPrivate` fields —
+  // it has no notion of TypeScript's `private` keyword, which is the actual
+  // dead-code surface in a TypeScript-heavy codebase. The typescript-eslint
+  // version is a strict superset (flags both forms) and needs no type
+  // information, so it adds no parser cost. This mirrors how
+  // `@typescript-eslint/no-shadow` and `@typescript-eslint/no-use-before-define`
+  // above already replace their core counterparts. Downstream repo
+  // `ameliso-io/web` already re-adds both the core and typescript-eslint
+  // variants by hand on top of the base config — promoting the
+  // typescript-eslint version into the shared rule set removes that
+  // copy-paste.
+  '@typescript-eslint/no-unused-private-class-members': 'error',
 }

package/rules/require-spec-file-tsx/helpers.js

@@ -0,0 +1,93 @@
+/* eslint-disable single-export/single-export */
+// Helpers for the require-spec-file-tsx rule.
+//
+// Logic detection and pattern matching mirror eslint-plugin-ddd so the
+// .tsx/.jsx half of the spec-file requirement behaves like the .js/.ts half.
+
+export const JSX_EXTENSIONS = ['.tsx', '.jsx']
+
+const FUNC_TYPES = new Set([
+  'FunctionDeclaration',
+  'FunctionExpression',
+  'ArrowFunctionExpression',
+])
+
+// Arrow bodies that are a bare value (not a block) and carry no real logic.
+const SIMPLE_BODIES = new Set([
+  'Literal',
+  'Identifier',
+  'ObjectExpression',
+  'ArrayExpression',
+])
+
+// Whether a node introduces real logic that warrants a spec file.
+export const hasLogicInNode = node => {
+  if (!node) {
+    return false
+  }
+  if (FUNC_TYPES.has(node.type) && node.body) {
+    if (
+      node.type === 'ArrowFunctionExpression' &&
+      node.body.type !== 'BlockStatement'
+    ) {
+      return !SIMPLE_BODIES.has(node.body.type)
+    }
+    return true
+  }
+  if (node.type === 'ClassDeclaration' || node.type === 'ClassExpression') {
+    return node.body.body.some(
+      member =>
+        member.type === 'MethodDefinition' && member.value && member.value.body
+    )
+  }
+  return false
+}
+
+const checkSinglePattern = (filename, pattern) => {
+  if (pattern.startsWith('**/') && pattern.endsWith('/**')) {
+    return filename.includes(`/${pattern.slice(3, -3)}/`)
+  }
+  if (pattern.includes('**/')) {
+    const suffix = pattern.replace('**/', '')
+    if (suffix.startsWith('*')) {
+      return filename.endsWith(suffix.slice(1))
+    }
+    if (suffix.includes('*')) {
+      const basename = filename.split('/').pop()
+      return suffix.split('*').every(part => basename.includes(part))
+    }
+    return filename.endsWith(`/${suffix}`)
+  }
+  return filename.includes(pattern)
+}
+
+// Test a filename against glob-ish exclude patterns, supporting the same
+// double-star prefix and brace-expansion forms accepted by the ddd plugin.
+export const checkExcludePatterns = (filename, excludePatterns) => {
+  const normalized = filename.replaceAll('\\', '/')
+  return excludePatterns.some(pattern => {
+    const braceMatch = pattern.match(/\{(?<content>[^}]+)\}/)
+    if (braceMatch) {
+      return braceMatch.groups.content
+        .split(',')
+        .some(alt =>
+          checkSinglePattern(normalized, pattern.replace(/\{[^}]+\}/, alt))
+        )
+    }
+    return checkSinglePattern(normalized, pattern)
+  })
+}
+
+export const DEFAULT_EXCLUDE_PATTERNS = [
+  '**/index.tsx',
+  '**/index.jsx',
+  '**/*.stories.{tsx,jsx}',
+  '**/*.d.ts',
+  // Error/exception files mirror the ddd/require-spec-file exemptions so a
+  // React/Preact error component (e.g. an error boundary) is treated the same
+  // as its `.ts` counterpart instead of being singled out for a spec file.
+  '**/*-error.{tsx,jsx}',
+  '**/*.error.{tsx,jsx}',
+  '**/errors/**',
+  '**/exceptions/**',
+]