eslint-config-agent 3.0.4 → 3.1.0

package/configs/base-plugins.js

@@ -46,6 +46,37 @@ export const basePluginsConfig = [
       ],
     },
   },
+  // Require spec files for .tsx/.jsx source files too.
+  //
+  // `ddd/require-spec-file` only inspects `.js`/`.ts` files, so React/Preact
+  // components — the code this config primarily targets — were silently exempt
+  // from the spec requirement. This custom rule covers the JSX extensions with
+  // the same heuristic, completing the "spec file for every source file"
+  // promise. Its excludePatterns mirror the JSX-relevant entries of the `ddd`
+  // list above (index/stories files are exempt; the error/exception file
+  // patterns are exempt; `.spec`/`.test` files are skipped by the rule
+  // itself).
+  {
+    rules: {
+      'custom/require-spec-file-tsx': [
+        'error',
+        {
+          excludePatterns: [
+            '**/index.tsx',
+            '**/index.jsx',
+            '**/*.stories.{tsx,jsx}',
+            // Mirror the ddd error/exception exemptions for JSX extensions so
+            // an error component (e.g. an error boundary) is not singled out
+            // for a spec file when its `.ts` equivalent is exempt.
+            '**/*-error.{tsx,jsx}',
+            '**/*.error.{tsx,jsx}',
+            '**/errors/**',
+            '**/exceptions/**',
+          ],
+        },
+      ],
+    },
+  },
   // Disable DDD for config infrastructure files
   {
     files: [
@@ -60,6 +91,7 @@ export const basePluginsConfig = [
     ],
     rules: {
       'ddd/require-spec-file': 'off',
+      'custom/require-spec-file-tsx': 'off',
     },
   },
 ]

package/configs/config-files.js

@@ -1,16 +1,32 @@
 /**
  * Configuration for configuration files
  * Allows hardcoded values and default exports in config files
+ *
+ * The `*.config.*` and `eslint.config.*` globs are recursive (they are
+ * prefixed with a globstar) so the relaxations also reach config files that
+ * live below the repo root — e.g. `apps/web/vite.config.ts` or
+ * `packages/ui/eslint.config.mjs` in a monorepo. Previously these used
+ * root-only globs (`*.config.{...}`), so a nested `eslint.config.mjs` /
+ * `vite.config.ts` silently escaped the config-file relaxations and got hit
+ * with `default/no-localhost`, `default/no-hardcoded-urls`, `max-lines`, etc.
+ * — the same asymmetry the `.mjs`/`.cjs` coverage fix addressed for the
+ * JavaScript rule set. This now mirrors the recursive-glob convention every
+ * other config block already uses.
+ *
+ * `index.js` is intentionally left root-scoped: broadening it to a recursive
+ * glob would relax these rules for every barrel/entry file in a consumer's
+ * source tree, masking real issues. Only files whose names mark them as
+ * configuration (`*.config.*`, `eslint.config.*`) are matched recursively.
  */
 
 export const configFilesConfig = [
   // Configuration files - allow hardcoded values for configuration purposes
   {
     files: [
-      '*.config.{js,ts}',
-      'eslint.config.{js,ts}',
+      '**/*.config.{js,ts,mjs,cjs}',
+      '**/eslint.config.{js,ts,mjs,cjs}',
       'index.js',
-      '**/configs/**/*.{js,ts}',
+      '**/configs/**/*.{js,ts,mjs,cjs}',
     ],
     rules: {
       'default/no-localhost': 'off',

package/configs/examples.js

@@ -45,7 +45,7 @@ const sharedRestrictedSyntax = [
     message:
       'Exporting from external libraries is not allowed. Only re-export from relative paths or scoped packages.',
   },
-  allRules.noProcessEnvPropertiesConfig,
+  allRules.noProcessEnvironmentPropertiesConfig,
   allRules.noExportSpecifiersConfig,
   ...allRules.noDefaultClassExportRules,
 ]
@@ -83,10 +83,21 @@ export const examplesConfig = [
       // Relax file/function length limits for concise examples
       'max-lines-per-function': 'off',
       'max-lines': 'off',
+      // Example fixtures demonstrate rule behavior and use `console.log` as
+      // illustrative sample code, so the shared `no-console` ban does not apply.
+      'no-console': 'off',
       // Examples don't need JSDoc
       'jsdoc/require-jsdoc': 'off',
       'jsdoc/require-param': 'off',
       'jsdoc/require-returns': 'off',
     },
   },
+  {
+    // JavaScript example fixtures (the `.ts` block above only matches `.ts`).
+    // They likewise use `console.log` as sample code.
+    files: ['**/rules/**/examples/**/*.js'],
+    rules: {
+      'no-console': 'off',
+    },
+  },
 ]

package/configs/javascript.js

@@ -1,8 +1,14 @@
 /**
  * JavaScript File Configurations
  *
- * Handles all JavaScript (.js) file-specific rules.
+ * Handles all JavaScript (.js, .mjs, .cjs) file-specific rules.
  * Plugin registration removed - all plugins registered globally in index.js.
+ *
+ * The ESM/CommonJS extensions (`.mjs`/`.cjs`) are linted with the same rule set
+ * as plain `.js`, mirroring how the TypeScript config covers `.mts`/`.cts`
+ * alongside `.ts`. Previously these were ignored here, so `.mjs`/`.cjs` source
+ * files silently escaped the package's signature `no-restricted-syntax`,
+ * `single-export`, and `required-exports` rules.
  */
 
 import globals from 'globals'
@@ -10,15 +16,13 @@ import globals from 'globals'
 export const javascriptConfig = (sharedRules, sharedRestrictedSyntax) => [
   // JavaScript files (not JSX)
   {
-    files: ['**/*.js'],
+    files: ['**/*.js', '**/*.mjs', '**/*.cjs'],
     ignores: [
       '**/node_modules/**',
       '**/dist/**',
       '**/build/**',
       'pnpm-lock.yaml',
       '**/*.umd.js',
-      '**/*.cjs',
-      '**/*.mjs',
       '**/*.stories.{js,jsx,ts,tsx}',
       '**/rules/**/index.js',
     ],
@@ -70,6 +74,10 @@ export const javascriptConfig = (sharedRules, sharedRestrictedSyntax) => [
     },
     rules: {
       ...sharedRules,
+      // Build/CI tooling under `scripts/` is a console program: printing to
+      // stdout is its job, so the shared `no-console` ban (aimed at leftover
+      // debugging in shipped source) does not apply here.
+      'no-console': 'off',
       'no-restricted-syntax': ['error', ...sharedRestrictedSyntax],
     },
   },

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,
@@ -79,7 +80,7 @@ export const overridesConfig = (
             'Type assertions with indexed access types like "as (typeof X)[number]" are not allowed. Use a named type instead.',
         },
         allRules.noTypeAssertionsConfig,
-        allRules.noProcessEnvPropertiesConfig,
+        allRules.noProcessEnvironmentPropertiesConfig,
         allRules.noExportSpecifiersConfig,
       ],
     },
@@ -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/test-files.js

@@ -58,7 +58,7 @@ const sharedRestrictedSyntax = [
     message:
       'Exporting from external libraries is not allowed. Only re-export from relative paths or scoped packages.',
   },
-  allRules.noProcessEnvPropertiesConfig,
+  allRules.noProcessEnvironmentPropertiesConfig,
   allRules.noExportSpecifiersConfig,
   ...allRules.noDefaultClassExportRules,
 ]
@@ -101,13 +101,49 @@ export const testFilesConfig = [
     rules: {
       'max-lines-per-function': 'off',
       'max-lines': 'off', // Ignore file length limits in test and spec files
+      // The shared config bans bare `console.log` in shipped source, but test
+      // and rule-tester spec files use `console.log` legitimately to report
+      // progress and assertions (this package's own `*.test.js` runners do
+      // exactly that), and fixtures embed it as sample code. Keep the rule on
+      // for real source and off here so test logging is not flagged.
+      'no-console': 'off',
       'default/no-localhost': ['error', { allowInTests: true }],
       'default/no-hardcoded-urls': ['error', { allowInTests: true }],
       'default/no-default-params': 'off', // Allow default parameters in test files for demonstration purposes
+      // Test and rule-tester spec files routinely embed source snippets inside
+      // string literals as fixtures (e.g. `code: 'const x = `${y}`'`), where a
+      // literal `${...}` is the intended payload, not a mis-quoted template.
+      // Keep no-template-curly-in-string on for real source but off here so the
+      // fixtures are not flagged.
+      'no-template-curly-in-string': 'off',
       // Disable error plugin rules in test files
       'error/no-generic-error': 'off',
       'error/require-custom-error': 'off',
       'error/no-throw-literal': 'off',
+      // Relax the noisy `eslint-plugin-security` heuristics for test code.
+      //
+      // These rules exist to harden *shipped* code against attacker-controlled
+      // input, but their detection is purely syntactic and fires constantly on
+      // perfectly safe test setup: a fixture path built from a temp dir
+      // (`detect-non-literal-fs-filename`), indexing a lookup table by a loop
+      // variable (`detect-object-injection`), compiling a pattern from a test
+      // input (`detect-non-literal-regexp`), spawning a helper binary in an
+      // integration test (`detect-child-process`), or `require`-ing a module
+      // resolved at runtime in a fixture loader (`detect-non-literal-require`).
+      // None of these are vulnerabilities in test files — the inputs are the
+      // test's own literals, not untrusted data, and the code never reaches
+      // production — so they are false positives that force adopters to litter
+      // specs with `eslint-disable` comments (this package's own
+      // `scripts/test-runner.js` already does exactly that). Turning them off
+      // for tests mirrors the `error/*` relaxations above; the genuinely
+      // value-adding security rules (`detect-unsafe-regex` for ReDoS,
+      // `detect-eval-with-expression`, `detect-buffer-noassert`, the timing and
+      // bidi-character checks) stay enabled everywhere.
+      'security/detect-non-literal-fs-filename': 'off',
+      'security/detect-object-injection': 'off',
+      'security/detect-non-literal-regexp': 'off',
+      'security/detect-child-process': 'off',
+      'security/detect-non-literal-require': 'off',
       // Allow multiple exports in test files for testing import/export patterns
       'no-restricted-syntax': [
         'warn',
@@ -204,6 +240,9 @@ export const testFilesConfig = [
       'jsdoc/require-jsdoc': 'off',
       'jsdoc/require-param': 'off',
       'jsdoc/require-returns': 'off',
+      // Spec files act as CLI test runners and legitimately call process.exit()
+      // to report pass/fail status — the unicorn rule is for library code only.
+      'unicorn/no-process-exit': 'off',
     },
   },
 

package/configs/tsx.js

@@ -30,9 +30,19 @@ export const tsxConfig = (
       },
     },
     settings: {
+      react: {
+        version: 'detect',
+      },
       'import/resolver': {
         typescript: {},
       },
+      // Tell eslint-plugin-import to parse TypeScript dependency files with the
+      // TS parser. Without this, the resolver finds the file but the plugin
+      // cannot read its imports/exports, so cross-file rules like
+      // import/no-cycle silently never fire on .ts/.tsx code.
+      'import/parsers': {
+        '@typescript-eslint/parser': ['.ts', '.tsx', '.mts', '.cts'],
+      },
     },
     rules: {
       ...sharedRules,

package/configs/typescript.js

@@ -1,7 +1,7 @@
 /**
  * TypeScript File Configurations
  *
- * Handles all TypeScript (.ts) file-specific rules.
+ * Handles all TypeScript (.ts, .mts, .cts) file-specific rules.
  * Plugin registration removed - all plugins registered globally in index.js.
  */
 
@@ -15,7 +15,7 @@ export const typescriptConfig = (
 ) => [
   // TypeScript files - Base config
   {
-    files: ['**/*.ts'],
+    files: ['**/*.ts', '**/*.mts', '**/*.cts'],
     ignores: [
       '**/node_modules/**',
       '**/dist/**',
@@ -30,15 +30,57 @@ export const typescriptConfig = (
       },
     },
     settings: {
+      react: {
+        version: 'detect',
+      },
       'import/resolver': {
         typescript: {},
       },
+      // Tell eslint-plugin-import to parse TypeScript dependency files with the
+      // TS parser. Without this, the resolver finds the file but the plugin
+      // cannot read its imports/exports, so cross-file rules like
+      // import/no-cycle silently never fire on .ts/.tsx code.
+      'import/parsers': {
+        '@typescript-eslint/parser': ['.ts', '.tsx', '.mts', '.cts'],
+      },
     },
     rules: {
       ...sharedRules,
       ...allRules.typescriptEslintRules,
       'no-undef': 'off', // TypeScript handles this
+      'jsdoc/require-jsdoc': [
+        'error',
+        {
+          require: {
+            ClassDeclaration: true,
+            FunctionDeclaration: true,
+          },
+        },
+      ],
       '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/ddd.d.ts

@@ -0,0 +1,10 @@
+import type { Linter } from 'eslint'
+
+/**
+ * DDD preset. The DDD rules (`require-spec-file`) now ship in the base config,
+ * so this entry point is equivalent to the default `eslint-config-agent`
+ * export and is kept for backward compatibility.
+ */
+declare const config: Linter.Config[]
+
+export default config

package/exports/ddd.js

@@ -10,6 +10,4 @@
  * - import config from "eslint-config-agent/ddd" (same as above)
  */
 
-import config from '../index.js'
-
-export default config
+export { default } from '../index.js'

package/exports/incremental.d.ts

@@ -0,0 +1,11 @@
+import type { Linter } from 'eslint'
+
+/**
+ * Incremental adoption preset: the full `eslint-config-agent` ruleset with every
+ * error-level rule downgraded to a warning. `eslint` exits `0` so CI stays
+ * green while the complete backlog is still reported, letting a team burn it
+ * down before flipping back to errors.
+ */
+declare const config: Linter.Config[]
+
+export default config

package/exports/incremental.js

@@ -0,0 +1,39 @@
+/**
+ * Incremental adoption preset.
+ *
+ * Dropping the full strict ruleset onto an existing codebase surfaces a large
+ * backlog of pre-existing violations at once, so `eslint` exits non-zero and CI
+ * goes red on the very first run. Teams then either give up or copy-paste a
+ * helper that rewrites every `error` rule to `warn` — the exact same block,
+ * repeated in every repo that adopts this config.
+ *
+ * This entry point ships that pattern so it no longer has to be copy-pasted:
+ *
+ * ```js
+ * import incremental from 'eslint-config-agent/incremental'
+ *
+ * export default incremental
+ * ```
+ *
+ * `incremental` is the full `eslint-config-agent` ruleset with every
+ * error-level rule downgraded to a warning. `eslint` exits `0`, so `pnpm lint`
+ * (and CI) stays green, while the complete ruleset is still reported — letting a
+ * team burn the backlog down gradually and flip back to errors once it is clear.
+ *
+ * To enforce a rule as a hard error before the rest of the backlog is cleared,
+ * append your own override layer, which wins over the warned defaults:
+ *
+ * ```js
+ * import incremental from 'eslint-config-agent/incremental'
+ *
+ * export default [
+ *   ...incremental,
+ *   { rules: { eqeqeq: ['error', 'always'] } },
+ * ]
+ * ```
+ */
+
+import config from '../index.js'
+import { toWarnings } from './to-warnings.js'
+
+export default config.map(toWarnings)

package/exports/recommended-incremental.d.ts

@@ -0,0 +1,11 @@
+import type { Linter } from 'eslint'
+
+/**
+ * Recommended + incremental preset: the `recommended` config with every
+ * surviving error-level rule downgraded to a warning. The gentlest on-ramp —
+ * the noisiest rules are off and everything else warns, so `eslint` exits `0`
+ * while the remaining backlog is still reported.
+ */
+declare const config: Linter.Config[]
+
+export default config

package/exports/recommended-incremental.js

@@ -0,0 +1,46 @@
+/**
+ * Recommended + incremental (relaxed, warn-level) preset.
+ *
+ * The package already ships two adoption on-ramps, but each only solves half of
+ * what an existing codebase hits on the first lint run:
+ *
+ *   - `recommended` turns the most divisive rules **off** (spec files, single
+ *     export, custom `error/*`, optional chaining / nullish-coalescing bans,
+ *     and so on) — but every remaining rule still reports as an **error**, so a
+ *     real backlog still fails CI on the first run.
+ *   - `incremental` keeps **every** rule reporting but downgrades them all to
+ *     **warnings** — so CI stays green, yet the divisive rules keep firing as a
+ *     wall of warnings on idiomatic TypeScript and React/Preact + Tailwind code.
+ *
+ * The gentlest possible on-ramp is the combination of the two: relax the
+ * divisive rules entirely *and* downgrade everything else to a warning. That is
+ * exactly this preset — the `recommended` config with every surviving
+ * error-level rule rewritten to `warn`:
+ *
+ * ```js
+ * import recommendedIncremental from 'eslint-config-agent/recommended-incremental'
+ *
+ * export default recommendedIncremental
+ * ```
+ *
+ * `eslint` exits `0`, so `pnpm lint` (and CI) stays green, the noisiest rules
+ * are silent, and the remaining quality rules show up as warnings you can burn
+ * down before tightening back up.
+ *
+ * To enforce a rule as a hard error before the rest of the backlog is cleared,
+ * append your own override layer, which wins over the warned defaults:
+ *
+ * ```js
+ * import recommendedIncremental from 'eslint-config-agent/recommended-incremental'
+ *
+ * export default [
+ *   ...recommendedIncremental,
+ *   { rules: { eqeqeq: ['error', 'always'] } },
+ * ]
+ * ```
+ */
+
+import recommended from './recommended.js'
+import { toWarnings } from './to-warnings.js'
+
+export default recommended.map(toWarnings)

package/exports/recommended.d.ts

@@ -0,0 +1,14 @@
+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.
+ * `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[]
+
+export default config

package/exports/recommended.js

@@ -0,0 +1,110 @@
+/**
+ * Recommended (relaxed) preset.
+ *
+ * The default export is intentionally strict — it is tuned for greenfield
+ * projects that adopt every convention from day one (a spec file beside every
+ * source file, custom Error classes, no optional chaining / nullish
+ * coalescing, single export per module, and so on).
+ *
+ * Existing codebases usually cannot satisfy all of that at once, so they end
+ * up copying the same block of rule overrides into their own
+ * `eslint.config.js` just to get the config to load without a wall of errors.
+ *
+ * This preset bundles those common overrides so incremental adopters can opt
+ * into the core quality rules immediately while deferring the most opinionated
+ * ones:
+ *
+ * ```js
+ * import recommended from 'eslint-config-agent/recommended'
+ *
+ * export default recommended
+ * ```
+ *
+ * Re-enable any individual rule by appending your own override layer.
+ */
+
+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',
+  rules: {
+    // Don't require a `*.spec.*` file alongside every source file. The strict
+    // default splits this requirement across two rules: `ddd/require-spec-file`
+    // covers `.js`/`.ts` (the upstream `eslint-plugin-ddd` rule bails out on any
+    // other extension), and the bundled `custom/require-spec-file-tsx` covers
+    // `.tsx`/`.jsx` — i.e. the React/Preact components this config primarily
+    // targets. Relaxing only the first would still force a spec file beside
+    // every component, defeating the preset's purpose for its core audience, so
+    // both halves are disabled together here.
+    'ddd/require-spec-file': 'off',
+    'custom/require-spec-file-tsx': 'off',
+    // Allow multiple exports per module.
+    'single-export/single-export': 'off',
+    'required-exports/required-exports': 'off',
+    // Allow generic `Error` instead of mandating custom Error classes.
+    'error/no-generic-error': 'off',
+    'error/require-custom-error': 'off',
+    'error/no-literal-error-message': 'off',
+    // Don't require a JSDoc block on every exported function and class. The
+    // strict default enables `jsdoc/require-jsdoc` at `error` for every
+    // `FunctionDeclaration` and `ClassDeclaration` (see `index.js` and
+    // `configs/typescript.js`), so adopting the config on an existing codebase
+    // produces a wall of `Missing JSDoc comment` errors on day one. This is the
+    // third of the three highest-volume on-ramp rules the README calls out —
+    // alongside `ddd/require-spec-file` and `error/no-literal-error-message`,
+    // both already relaxed above — so relax it here to match the preset's
+    // stated incremental-adoption purpose. Only the "document everything"
+    // requirement is lifted: the jsdoc *content* rules (`check-param-names`,
+    // `require-returns`, ...) stay enabled, so any JSDoc that is actually
+    // written is still validated.
+    'jsdoc/require-jsdoc': 'off',
+    // Allow default parameter values.
+    'default/no-default-params': 'off',
+    // Allow `type` aliases, not just `interface` declarations.
+    '@typescript-eslint/consistent-type-definitions': 'off',
+    // Don't require a semantic `className` on every HTML element, and don't
+    // reject Tailwind-only class lists. The strict default enables
+    // `jsx-classname/require-classname` with `{ ignoreTailwind: true }`, which
+    // errors both on elements with no `className` and on elements whose
+    // `className` contains only Tailwind utilities (e.g.
+    // `<div className="flex gap-2" />`). That makes the config impossible to
+    // 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: 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],
+  },
+}
+
+// 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]