@tsfpp/eslint-config 1.0.0

package/README.md

@@ -0,0 +1,116 @@
+# @tsfpp/eslint-config
+
+Shared ESLint flat configuration for [TSF++](../../spec/standards/TSFPP_CODING_STANDARD.md) projects.
+
+Enforces the machine-checkable subset of TSF++ rules via `@typescript-eslint` and `eslint-plugin-functional`. Every active rule references the spec rule it enforces.
+
+## Requirements
+
+- ESLint ≥ 9 (flat config format)
+- TypeScript ≥ 5.3
+- A `tsconfig.json` reachable from each linted file
+
+## Installation
+
+```sh
+pnpm add -D @tsfpp/eslint-config \
+  eslint \
+  typescript \
+  @typescript-eslint/parser \
+  @typescript-eslint/eslint-plugin \
+  eslint-plugin-functional
+```
+
+## Usage
+
+### Standalone
+
+```js
+// eslint.config.js
+import tsfpp from '@tsfpp/eslint-config'
+
+export default tsfpp
+```
+
+### With project-specific overrides
+
+```js
+// eslint.config.js
+import tsfpp from '@tsfpp/eslint-config'
+
+export default [
+  ...tsfpp,
+  {
+    // Relax console warnings in scripts
+    rules: { 'no-console': 'off' },
+  },
+]
+```
+
+### With `@tsfpp/tsconfig`
+
+```js
+// eslint.config.js
+import tsfpp from '@tsfpp/eslint-config'
+
+export default [
+  ...tsfpp,
+  {
+    languageOptions: {
+      parserOptions: {
+        // Point to your project tsconfig explicitly if needed
+        project: './tsconfig.json',
+      },
+    },
+  },
+]
+```
+
+## Enforced rules
+
+| ESLint rule | TSF++ rule | Level |
+|-------------|------------|-------|
+| `@typescript-eslint/no-explicit-any` | 1.5 | MUST |
+| `@typescript-eslint/no-non-null-assertion` | 1.6 | MUST |
+| `@typescript-eslint/consistent-type-assertions: never` | 1.6 | MUST |
+| `@typescript-eslint/switch-exhaustiveness-check` | 1.2 / 4.1 | MUST |
+| `@typescript-eslint/explicit-function-return-type` | 3.1 | MUST |
+| `@typescript-eslint/strict-boolean-expressions` | 4.5 | MUST |
+| `@typescript-eslint/no-floating-promises` | 6.4 | SHOULD |
+| `@typescript-eslint/prefer-readonly` | 2.2 | MUST |
+| `functional/no-let` | 2.1 | MUST |
+| `functional/no-loop-statements` | 4.2 | MUST |
+| `functional/no-throw-statements` | 6.2 | MUST |
+| `functional/prefer-readonly-type` | 2.2 | MUST |
+| `functional/immutable-data` | 2.3 | MUST |
+| `functional/no-classes` | 1.9 | MUST |
+| `functional/no-this-expressions` | 1.9 | MUST |
+| `complexity: 10` | 3.4 | MUST |
+| `max-depth: 4` | 3.4 | MUST |
+| `max-lines-per-function: 40` | 3.4 | MUST |
+| `eqeqeq: always` | 4.5 | MUST |
+| `no-param-reassign` | 2.3 | MUST |
+
+## Handling permitted deviations
+
+Some TSF++ rules permit deviations at specific boundaries. Use `eslint-disable-next-line` with a paired `DEVIATION` comment so deviations are explicit and auditable:
+
+```typescript
+// DEVIATION(1.6): `as` permitted inside smart constructor boundary
+// eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+return raw as NodeId
+```
+
+```typescript
+// DEVIATION(6.2): adapter boundary — wraps third-party throw in Result
+// eslint-disable-next-line functional/no-throw-statements
+throw new Error('unreachable')
+```
+
+This makes every deviation visible to the TSF++ Audit agent and during code review.
+
+## See also
+
+- [spec/standards/TSFPP_CODING_STANDARD.md §9](../../spec/standards/TSFPP_CODING_STANDARD.md#9--compiler-and-tooling-configuration) — normative rule reference
+- [spec/rationale/09-tooling.md](../../spec/rationale/09-tooling.md) — extended justification
+- [@tsfpp/tsconfig](../tsconfig/README.md) — companion TypeScript config presets

package/dist/api.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @tsfpp/eslint-config/api
+ *
+ * TSF++ ESLint configuration profile for HTTP API / Node.js server code.
+ * Extends the base config with rules that enforce stricter output hygiene,
+ * async correctness, and boundary discipline required by API_CODING_STANDARD.md.
+ *
+ * Rule references in this file are to API_CODING_STANDARD.md unless prefixed with "TSF++".
+ *
+ * Usage:
+ *   // eslint.config.js
+ *   import tsfppApi from '@tsfpp/eslint-config/api'
+ *   export default tsfppApi
+ *
+ * With project-specific overrides:
+ *   import tsfppApi from '@tsfpp/eslint-config/api'
+ *   export default [
+ *     ...tsfppApi,
+ *     { files: ['src/adapters/**'], rules: { 'no-console': 'off' } },
+ *   ]
+ *
+ * No additional devDependencies are required beyond the base package requirements.
+ */
+import type { Linter } from 'eslint';
+declare const config: Linter.Config[];
+export default config;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAGpC,QAAA,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EA6D1B,CAAA;AAED,eAAe,MAAM,CAAA"}

package/dist/api.js

@@ -0,0 +1,74 @@
+/**
+ * @tsfpp/eslint-config/api
+ *
+ * TSF++ ESLint configuration profile for HTTP API / Node.js server code.
+ * Extends the base config with rules that enforce stricter output hygiene,
+ * async correctness, and boundary discipline required by API_CODING_STANDARD.md.
+ *
+ * Rule references in this file are to API_CODING_STANDARD.md unless prefixed with "TSF++".
+ *
+ * Usage:
+ *   // eslint.config.js
+ *   import tsfppApi from '@tsfpp/eslint-config/api'
+ *   export default tsfppApi
+ *
+ * With project-specific overrides:
+ *   import tsfppApi from '@tsfpp/eslint-config/api'
+ *   export default [
+ *     ...tsfppApi,
+ *     { files: ['src/adapters/**'], rules: { 'no-console': 'off' } },
+ *   ]
+ *
+ * No additional devDependencies are required beyond the base package requirements.
+ */
+import base from './base.js';
+const config = [
+    // ── Inherit all base TSF++ rules ─────────────────────────────────────────────
+    ...base,
+    // ── API-specific overrides and additions ──────────────────────────────────────
+    {
+        files: ['**/*.ts'],
+        rules: {
+            // ── Output / logging hygiene ────────────────────────────────────────────
+            // API servers must never use console.* — structured logging only (withLogging from logger.ts).
+            // The base config sets this to 'warn'; API elevates to 'error'.
+            'no-console': 'error',
+            // ── Async correctness (Rules 6.x, TSF++ Rule 6.4) ──────────────────────
+            // Every async function must contain at least one await expression.
+            // Prevents accidentally marking synchronous handlers as async.
+            '@typescript-eslint/require-await': 'error',
+            // Returned promises must be awaited (catches fire-and-forget in handlers).
+            '@typescript-eslint/return-await': ['error', 'always'],
+            // ── Boundary strictness (Rules 1.x, 5.x) ───────────────────────────────
+            // API rule 5.1 — every request body / query param must pass through Zod (or equivalent).
+            // Enforced structurally; no ESLint rule maps cleanly without custom plugin.
+            // Document this at the code-review gate (API_CODING_STANDARD.md §10 checklist).
+            // Disallow usage of unsafe any-typed values passed to typed parameters.
+            // Belt-and-suspenders at parse/validate boundaries.
+            '@typescript-eslint/no-unsafe-argument': 'error',
+            '@typescript-eslint/no-unsafe-assignment': 'error',
+            '@typescript-eslint/no-unsafe-call': 'error',
+            '@typescript-eslint/no-unsafe-member-access': 'error',
+            '@typescript-eslint/no-unsafe-return': 'error',
+            // ── Error handling (TSF++ Rule 6.2; API Rule 4.x) ──────────────────────
+            // functional/no-throw-statements is already 'error' in base.
+            // No additional override required; adapter boundaries use DEVIATION(6.2).
+            // Prevent Promise rejection with non-Error values.
+            'prefer-promise-reject-errors': 'error',
+        },
+    },
+    // ── Adapter / boundary files — allow `new` and `throw` with deviation ─────────
+    // Projects that follow TSF++ boundary conventions will place all I/O adapters in
+    // a dedicated directory (e.g. src/adapters/, src/infrastructure/).
+    // Override per-project in the consuming eslint.config.js if needed:
+    //
+    //   {
+    //     files: ['src/adapters/**'],
+    //     rules: {
+    //       'no-restricted-syntax':           'off',  // allows `new` and `instanceof`
+    //       'functional/no-throw-statements': 'off',  // allows `throw` at boundary
+    //     },
+    //   },
+];
+export default config;
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,IAAI,MAAiB,WAAW,CAAA;AAEvC,MAAM,MAAM,GAAoB;IAE9B,gFAAgF;IAChF,GAAG,IAAI;IAEP,iFAAiF;IACjF;QACE,KAAK,EAAE,CAAC,SAAS,CAAC;QAClB,KAAK,EAAE;YAEL,2EAA2E;YAE3E,+FAA+F;YAC/F,gEAAgE;YAChE,YAAY,EAAE,OAAO;YAErB,0EAA0E;YAE1E,mEAAmE;YACnE,+DAA+D;YAC/D,kCAAkC,EAAE,OAAO;YAE3C,2EAA2E;YAC3E,iCAAiC,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC;YAEtD,0EAA0E;YAE1E,yFAAyF;YACzF,4EAA4E;YAC5E,gFAAgF;YAEhF,wEAAwE;YACxE,oDAAoD;YACpD,uCAAuC,EAAI,OAAO;YAClD,yCAAyC,EAAG,OAAO;YACnD,mCAAmC,EAAS,OAAO;YACnD,4CAA4C,EAAE,OAAO;YACrD,qCAAqC,EAAO,OAAO;YAEnD,0EAA0E;YAE1E,6DAA6D;YAC7D,0EAA0E;YAE1E,mDAAmD;YACnD,8BAA8B,EAAE,OAAO;SACxC;KACF;IAED,iFAAiF;IACjF,iFAAiF;IACjF,mEAAmE;IACnE,oEAAoE;IACpE,EAAE;IACF,MAAM;IACN,kCAAkC;IAClC,eAAe;IACf,mFAAmF;IACnF,gFAAgF;IAChF,SAAS;IACT,OAAO;CACR,CAAA;AAED,eAAe,MAAM,CAAA"}

package/dist/base.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @tsfpp/eslint-config — base
+ *
+ * Shared ESLint flat configuration for TSF++ projects (pure TypeScript targets).
+ * Enforces Rules 1.2–1.9, 2.1–2.3, 3.1–3.2, 3.4, 4.1, 4.2, 4.5, 6.2, 6.4, 11.2
+ * from CODING_STANDARD.md via @typescript-eslint and eslint-plugin-functional.
+ *
+ * Usage (base only):
+ *   // eslint.config.js
+ *   import tsfpp from '@tsfpp/eslint-config'
+ *   export default tsfpp
+ *
+ * Usage with project-specific overrides:
+ *   import tsfpp from '@tsfpp/eslint-config'
+ *   export default [
+ *     ...tsfpp,
+ *     { rules: { 'no-console': 'off' } },
+ *   ]
+ *
+ * For React projects, import '@tsfpp/eslint-config/react' instead.
+ * For API projects, import '@tsfpp/eslint-config/api' instead.
+ */
+import type { Linter } from 'eslint';
+declare const config: Linter.Config[];
+export default config;
+//# sourceMappingURL=base.d.ts.map

package/dist/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAO,QAAQ,CAAA;AAMrC,QAAA,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EA0L1B,CAAA;AAED,eAAe,MAAM,CAAA"}

package/dist/base.js

@@ -0,0 +1,179 @@
+/**
+ * @tsfpp/eslint-config — base
+ *
+ * Shared ESLint flat configuration for TSF++ projects (pure TypeScript targets).
+ * Enforces Rules 1.2–1.9, 2.1–2.3, 3.1–3.2, 3.4, 4.1, 4.2, 4.5, 6.2, 6.4, 11.2
+ * from CODING_STANDARD.md via @typescript-eslint and eslint-plugin-functional.
+ *
+ * Usage (base only):
+ *   // eslint.config.js
+ *   import tsfpp from '@tsfpp/eslint-config'
+ *   export default tsfpp
+ *
+ * Usage with project-specific overrides:
+ *   import tsfpp from '@tsfpp/eslint-config'
+ *   export default [
+ *     ...tsfpp,
+ *     { rules: { 'no-console': 'off' } },
+ *   ]
+ *
+ * For React projects, import '@tsfpp/eslint-config/react' instead.
+ * For API projects, import '@tsfpp/eslint-config/api' instead.
+ */
+import tsParser from '@typescript-eslint/parser';
+import tsPlugin from '@typescript-eslint/eslint-plugin';
+import functionalPlugin from 'eslint-plugin-functional';
+import { coercePlugin } from './plugin-compat.js';
+const config = [
+    // ── Global ignores ────────────────────────────────────────────────────────────
+    {
+        ignores: ['dist/**', 'coverage/**', 'node_modules/**', '**/*.d.ts'],
+    },
+    // ── TypeScript source files ───────────────────────────────────────────────────
+    {
+        files: ['**/*.ts', '**/*.tsx'],
+        languageOptions: {
+            parser: tsParser,
+            parserOptions: {
+                sourceType: 'module',
+                ecmaVersion: 'latest',
+                project: true, // resolves nearest tsconfig.json; override with projectService
+            },
+        },
+        plugins: {
+            '@typescript-eslint': coercePlugin(tsPlugin),
+            'functional': coercePlugin(functionalPlugin),
+        },
+        rules: {
+            // ── Type-system rules ─────────────────────────────────────────────────────
+            // Rule 1.2 / 4.1 — exhaustive switch via never (backed by @tsfpp/prelude absurd)
+            '@typescript-eslint/switch-exhaustiveness-check': 'error',
+            // Rule 1.4 — prefer `type` over `interface`; `interface` requires DEVIATION(1.4)
+            '@typescript-eslint/consistent-type-definitions': ['error', 'type'],
+            // Rule 1.5 — no `any`
+            '@typescript-eslint/no-explicit-any': 'error',
+            // Rule 1.6 — no `!`
+            '@typescript-eslint/no-non-null-assertion': 'error',
+            // Rule 1.6 — no `as` (DEVIATION(1.6) + eslint-disable required inside smart constructors)
+            '@typescript-eslint/consistent-type-assertions': ['error', {
+                    assertionStyle: 'never',
+                }],
+            // Rule 1.8 / 1.9 — forbidden language constructs (no ESLint plugin covers these directly)
+            'no-restricted-syntax': [
+                'error',
+                {
+                    // Rule 1.8 — no enum
+                    selector: 'TSEnumDeclaration',
+                    message: 'TSF++ Rule 1.8: Use string literal unions or `as const` objects instead of enum.',
+                },
+                {
+                    // Rule 1.9 — no namespace
+                    selector: "TSModuleDeclaration[kind='namespace']",
+                    message: 'TSF++ Rule 1.9: Namespace declarations are forbidden.',
+                },
+                {
+                    // Rule 1.9 — no instanceof (prefer discriminated unions and type-guard predicates)
+                    selector: 'BinaryExpression[operator="instanceof"]',
+                    message: 'TSF++ Rule 1.9: instanceof is forbidden; use discriminated unions or exported type-guard predicates.',
+                },
+                {
+                    // Rule 1.9 — no new (adapter boundaries require DEVIATION(1.9) comment + eslint-disable)
+                    selector: 'NewExpression',
+                    message: 'TSF++ Rule 1.9: new is forbidden outside adapter boundaries. Add DEVIATION(1.9) and an eslint-disable comment.',
+                },
+            ],
+            // ── Immutability & functional style ──────────────────────────────────────
+            // Rule 2.1 — no `let`
+            'functional/no-let': 'error',
+            // Rule 2.2 — readonly types (deep)
+            'functional/prefer-readonly-type': ['error', {
+                    allowLocalMutation: false,
+                    allowMutableReturnType: false,
+                    ignoreClass: false,
+                    ignoreInterface: false,
+                }],
+            // Rule 2.2 — prefer-readonly on (legacy) class properties (belt-and-suspenders)
+            '@typescript-eslint/prefer-readonly': 'error',
+            // Rule 2.3 — no mutation (property assignment, array mutation methods)
+            'functional/immutable-data': ['error', {
+                    ignoreImmediateMutation: true, // allows builder pattern inside same statement
+                    ignoreAccessorPattern: ['**.current', 'process.env.*'], // React refs + env edge cases
+                }],
+            // Rule 1.9 — no classes / no this
+            'functional/no-classes': 'error',
+            'functional/no-this-expressions': 'error',
+            // Rule 4.2 — no imperative loops
+            'functional/no-loop-statements': 'error',
+            // Rule 6.2 — no throw outside adapter boundaries
+            // Disable per-file with `// eslint-disable-next-line functional/no-throw-statements`
+            // accompanied by a `// DEVIATION(6.2)` comment at every adapter entry point.
+            'functional/no-throw-statements': 'error',
+            // ── Function rules ────────────────────────────────────────────────────────
+            // Rule 3.1 — explicit return type on every exported function
+            '@typescript-eslint/explicit-function-return-type': ['error', {
+                    allowExpressions: false,
+                    allowTypedFunctionExpressions: true,
+                    allowHigherOrderFunctions: true,
+                    allowDirectConstAssertionInArrowFunctions: true,
+                }],
+            // Rule 3.2 — arity ≤ 3; use a readonly record for ≥ 3 parameters
+            'max-params': ['error', { max: 3 }],
+            // Rule 3.4 — cyclomatic complexity ≤ 10
+            'complexity': ['error', { max: 10 }],
+            // Rule 3.4 — nesting depth ≤ 4
+            'max-depth': ['error', { max: 4 }],
+            // Rule 3.4 — 40-line function body limit
+            'max-lines-per-function': ['error', {
+                    max: 40,
+                    skipBlankLines: true,
+                    skipComments: true,
+                }],
+            // ── Async / promise safety ────────────────────────────────────────────────
+            // Rule 6.4 — no unhandled promise rejections
+            '@typescript-eslint/no-floating-promises': 'error',
+            '@typescript-eslint/no-misused-promises': 'error',
+            // ── Control-flow hygiene ──────────────────────────────────────────────────
+            // Rule 4.5 — no truthiness checks on non-booleans
+            '@typescript-eslint/strict-boolean-expressions': ['error', {
+                    allowString: false,
+                    allowNumber: false,
+                    allowNullableObject: false,
+                    allowNullableBoolean: false,
+                    allowNullableString: false,
+                    allowNullableNumber: false,
+                    allowAny: false,
+                }],
+            // ── Module hygiene ────────────────────────────────────────────────────────
+            // Prefer `import type` for type-only imports (verbatimModuleSyntax companion)
+            '@typescript-eslint/consistent-type-imports': ['error', {
+                    prefer: 'type-imports',
+                    fixStyle: 'inline-type-imports',
+                    disallowTypeAnnotations: false,
+                }],
+            // ── General hygiene ───────────────────────────────────────────────────────
+            // Accidental console.log in production code — warn in base; API profile overrides to error
+            'no-console': 'warn',
+            // Rule 2.1 — const only
+            'prefer-const': 'error',
+            'no-var': 'error',
+            // Rule 2.3 — no parameter reassignment
+            'no-param-reassign': 'error',
+            // Rule 4.5 — strict equality
+            'eqeqeq': ['error', 'always'],
+            // Rule 11.2 — file length ≤ 400 lines (800 absolute maximum via DEVIATION(11.2))
+            'max-lines': ['error', {
+                    max: 400,
+                    skipBlankLines: true,
+                    skipComments: true,
+                }],
+            // Unused vars — `_` prefix exempted (Rule 7.6)
+            '@typescript-eslint/no-unused-vars': ['error', {
+                    argsIgnorePattern: '^_',
+                    varsIgnorePattern: '^_',
+                    caughtErrorsIgnorePattern: '^_',
+                }],
+        },
+    },
+];
+export default config;
+//# sourceMappingURL=base.js.map

package/dist/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../base.ts"],"names":[],"mappings":"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"}

package/dist/plugin-compat.d.ts

@@ -0,0 +1,30 @@
+/**
+ * plugin-compat.ts
+ *
+ * Adapter boundary for third-party ESLint plugin type coercion.
+ *
+ * Problem: ESLint plugin packages frequently ship TypeScript types that lag
+ * behind the current @eslint/core `Plugin` interface. The structural mismatch
+ * (e.g. `null` in `parser` where `string | undefined` is expected, or `flat`
+ * keys in `configs` that don't satisfy the index signature) causes TS2322
+ * errors at plugin registration sites in flat config objects.
+ *
+ * Solution: Isolate the necessary `as` cast here, at this single adapter
+ * boundary. Every callsite in base.ts / react.ts / api.ts is auditable by
+ * grepping for `coercePlugin`.
+ *
+ * DEVIATION(1.6): `as` cast is intentional and confined to this module.
+ * Justification: third-party type incompatibility at an adapter boundary;
+ * no runtime effect — this is a pure type-level coercion with zero behavior.
+ * Reviewed and approved per TSF++ deviation procedure.
+ */
+import type { ESLint } from 'eslint';
+/**
+ * Coerces a third-party ESLint plugin object to the canonical `ESLint.Plugin`
+ * type accepted by flat config `plugins` records.
+ *
+ * Use exclusively at plugin registration sites. Never use to silence unrelated
+ * type errors.
+ */
+export declare const coercePlugin: (plugin: unknown) => ESLint.Plugin;
+//# sourceMappingURL=plugin-compat.d.ts.map

package/dist/plugin-compat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-compat.d.ts","sourceRoot":"","sources":["../plugin-compat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAEpC;;;;;;GAMG;AAEH,eAAO,MAAM,YAAY,GAAI,QAAQ,OAAO,KAAG,MAAM,CAAC,MAC7B,CAAA"}

package/dist/plugin-compat.js

@@ -0,0 +1,30 @@
+/**
+ * plugin-compat.ts
+ *
+ * Adapter boundary for third-party ESLint plugin type coercion.
+ *
+ * Problem: ESLint plugin packages frequently ship TypeScript types that lag
+ * behind the current @eslint/core `Plugin` interface. The structural mismatch
+ * (e.g. `null` in `parser` where `string | undefined` is expected, or `flat`
+ * keys in `configs` that don't satisfy the index signature) causes TS2322
+ * errors at plugin registration sites in flat config objects.
+ *
+ * Solution: Isolate the necessary `as` cast here, at this single adapter
+ * boundary. Every callsite in base.ts / react.ts / api.ts is auditable by
+ * grepping for `coercePlugin`.
+ *
+ * DEVIATION(1.6): `as` cast is intentional and confined to this module.
+ * Justification: third-party type incompatibility at an adapter boundary;
+ * no runtime effect — this is a pure type-level coercion with zero behavior.
+ * Reviewed and approved per TSF++ deviation procedure.
+ */
+/**
+ * Coerces a third-party ESLint plugin object to the canonical `ESLint.Plugin`
+ * type accepted by flat config `plugins` records.
+ *
+ * Use exclusively at plugin registration sites. Never use to silence unrelated
+ * type errors.
+ */
+// eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+export const coercePlugin = (plugin) => plugin; // DEVIATION(1.6): see module JSDoc above
+//# sourceMappingURL=plugin-compat.js.map

package/dist/plugin-compat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-compat.js","sourceRoot":"","sources":["../plugin-compat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH;;;;;;GAMG;AACH,yEAAyE;AACzE,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAAe,EAAiB,EAAE,CAC7D,MAAuB,CAAA,CAAE,yCAAyC"}

package/dist/react.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @tsfpp/eslint-config/react
+ *
+ * TSF++ ESLint configuration profile for React / TSX code.
+ * Extends the base config with React-, hooks-, accessibility-, and TanStack Query–specific rules.
+ *
+ * Enforces rules from REACT_CODING_STANDARD.md (a profile of CODING_STANDARD.md).
+ * Rule references in this file are to REACT_CODING_STANDARD.md unless prefixed with "TSF++".
+ *
+ * Usage:
+ *   // eslint.config.js
+ *   import tsfppReact from '@tsfpp/eslint-config/react'
+ *   export default tsfppReact
+ *
+ * With project-specific overrides:
+ *   import tsfppReact from '@tsfpp/eslint-config/react'
+ *   export default [
+ *     ...tsfppReact,
+ *     { rules: { 'react/display-name': 'off' } },
+ *   ]
+ *
+ * Required devDependencies (in addition to base requirements):
+ *   eslint-plugin-react
+ *   eslint-plugin-react-hooks
+ *   eslint-plugin-jsx-a11y
+ *   @tanstack/eslint-plugin-query
+ */
+import type { Linter } from 'eslint';
+declare const config: Linter.Config[];
+export default config;
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../react.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAS,QAAQ,CAAA;AASvC,QAAA,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAqG1B,CAAA;AAED,eAAe,MAAM,CAAA"}

package/dist/react.js

@@ -0,0 +1,115 @@
+/**
+ * @tsfpp/eslint-config/react
+ *
+ * TSF++ ESLint configuration profile for React / TSX code.
+ * Extends the base config with React-, hooks-, accessibility-, and TanStack Query–specific rules.
+ *
+ * Enforces rules from REACT_CODING_STANDARD.md (a profile of CODING_STANDARD.md).
+ * Rule references in this file are to REACT_CODING_STANDARD.md unless prefixed with "TSF++".
+ *
+ * Usage:
+ *   // eslint.config.js
+ *   import tsfppReact from '@tsfpp/eslint-config/react'
+ *   export default tsfppReact
+ *
+ * With project-specific overrides:
+ *   import tsfppReact from '@tsfpp/eslint-config/react'
+ *   export default [
+ *     ...tsfppReact,
+ *     { rules: { 'react/display-name': 'off' } },
+ *   ]
+ *
+ * Required devDependencies (in addition to base requirements):
+ *   eslint-plugin-react
+ *   eslint-plugin-react-hooks
+ *   eslint-plugin-jsx-a11y
+ *   @tanstack/eslint-plugin-query
+ */
+import reactPlugin from 'eslint-plugin-react';
+import reactHooksPlugin from 'eslint-plugin-react-hooks';
+// eslint-plugin-jsx-a11y ships no types — declared in declarations.d.ts
+import jsxA11yPlugin from 'eslint-plugin-jsx-a11y';
+import tanstackQueryPlugin from '@tanstack/eslint-plugin-query';
+import base from './base.js';
+import { coercePlugin } from './plugin-compat.js';
+const config = [
+    // ── Inherit all base TSF++ rules (applies to .ts and .tsx) ───────────────────
+    ...base,
+    // ── React / TSX layer ────────────────────────────────────────────────────────
+    {
+        files: ['**/*.tsx'],
+        plugins: {
+            'react': coercePlugin(reactPlugin),
+            'react-hooks': coercePlugin(reactHooksPlugin),
+            'jsx-a11y': coercePlugin(jsxA11yPlugin),
+            '@tanstack/query': coercePlugin(tanstackQueryPlugin),
+        },
+        settings: {
+            react: { version: 'detect' },
+        },
+        rules: {
+            // ── Component shape (Rules 1.1–1.2) ────────────────────────────────────
+            // Rule 1.1 — no function declarations for components (must be arrow const)
+            // `@typescript-eslint/explicit-function-return-type` already enforces the return type half;
+            // this prevents the function-declaration form.
+            'react/function-component-definition': ['error', {
+                    namedComponents: 'arrow-function',
+                    unnamedComponents: 'arrow-function',
+                }],
+            // JSX transform — no explicit React import required (React 17+)
+            'react/jsx-uses-react': 'off',
+            'react/react-in-jsx-scope': 'off',
+            // Rule core — JSX hygiene
+            'react/jsx-key': ['error', { checkFragmentShorthand: true }],
+            'react/jsx-no-leaked-render': 'error', // forbids `{count && <X />}` rendering "0"
+            'react/no-array-index-key': 'error', // index keys break diffing
+            'react/no-unstable-nested-components': 'error', // new component identity per render
+            'react/self-closing-comp': 'error',
+            'react/jsx-pascal-case': 'error',
+            'react/jsx-no-useless-fragment': 'error',
+            'react/display-name': 'error',
+            // ── Hooks (Rules 4.1–4.6, 14.1) ────────────────────────────────────────
+            // Rule 14.1 — hooks rules (conditional calls, top-level only)
+            'react-hooks/rules-of-hooks': 'error',
+            // Rule 4.6 — exhaustive deps (disabling this rule requires DEVIATION(4.6))
+            'react-hooks/exhaustive-deps': 'error',
+            // ── Props (Rules 2.1–2.4) ───────────────────────────────────────────────
+            // Rule 2.4 — no unrestricted rest-prop spread onto DOM elements
+            // Note: enforced structurally by Rule 2.1 (explicit Props types); no ESLint rule maps
+            // cleanly here without excessive false positives. Code review is the gate.
+            // ── Accessibility (Rule 16) ─────────────────────────────────────────────
+            // Rule 16.1 — no div/span with onClick; use semantic elements
+            'jsx-a11y/click-events-have-key-events': 'error',
+            'jsx-a11y/no-static-element-interactions': 'error',
+            // Rule 16.2 — accessible forms and images
+            'jsx-a11y/alt-text': 'error',
+            'jsx-a11y/anchor-has-content': 'error',
+            'jsx-a11y/label-has-associated-control': 'error',
+            // Rule 16 — ARIA correctness
+            'jsx-a11y/aria-props': 'error',
+            'jsx-a11y/aria-role': 'error',
+            // Autofocus is harmful to keyboard navigation (warn to allow deliberate UX decisions)
+            'jsx-a11y/no-autofocus': 'warn',
+            // ── TanStack Query (Rules 7.1–7.2) ─────────────────────────────────────
+            // Rule 7.2 — exhaustive query-key dependencies
+            '@tanstack/query/exhaustive-deps': 'error',
+            // Discourage rest-destructuring of query results (encourages explicit field selection)
+            '@tanstack/query/no-rest-destructuring': 'error',
+            // Stable query-client reference (no inline `new QueryClient()` in render)
+            '@tanstack/query/stable-query-client': 'error',
+            // ── React-specific functional overrides ─────────────────────────────────
+            // React refs are mutable by contract; immutable-data would false-positive on ref.current
+            // The base config already allowlists `**.current` via ignoreAccessorPattern — no override needed.
+        },
+    },
+    // ── React hooks in plain .ts files (custom hooks outside .tsx) ───────────────
+    {
+        files: ['**/use*.ts', '**/use*.tsx'],
+        rules: {
+            'react-hooks/rules-of-hooks': 'error',
+            'react-hooks/exhaustive-deps': 'error',
+        },
+    },
+];
+export default config;
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../react.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,WAAW,MAAa,qBAAqB,CAAA;AACpD,OAAO,gBAAgB,MAAQ,2BAA2B,CAAA;AAC1D,wEAAwE;AACxE,OAAO,aAAa,MAAW,wBAAwB,CAAA;AACvD,OAAO,mBAAmB,MAAM,+BAA+B,CAAA;AAC/D,OAAO,IAAI,MAAoB,WAAW,CAAA;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAQ,oBAAoB,CAAA;AAEnD,MAAM,MAAM,GAAoB;IAE9B,gFAAgF;IAChF,GAAG,IAAI;IAEP,gFAAgF;IAChF;QACE,KAAK,EAAE,CAAC,UAAU,CAAC;QACnB,OAAO,EAAE;YACP,OAAO,EAAc,YAAY,CAAC,WAAW,CAAC;YAC9C,aAAa,EAAQ,YAAY,CAAC,gBAAgB,CAAC;YACnD,UAAU,EAAW,YAAY,CAAC,aAAa,CAAC;YAChD,iBAAiB,EAAI,YAAY,CAAC,mBAAmB,CAAC;SACvD;QACD,QAAQ,EAAE;YACR,KAAK,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE;SAC7B;QACD,KAAK,EAAE;YAEL,0EAA0E;YAE1E,2EAA2E;YAC3E,4FAA4F;YAC5F,+CAA+C;YAC/C,qCAAqC,EAAE,CAAC,OAAO,EAAE;oBAC/C,eAAe,EAAK,gBAAgB;oBACpC,iBAAiB,EAAG,gBAAgB;iBACrC,CAAC;YAEF,gEAAgE;YAChE,sBAAsB,EAAO,KAAK;YAClC,0BAA0B,EAAG,KAAK;YAElC,0BAA0B;YAC1B,eAAe,EAAqB,CAAC,OAAO,EAAE,EAAE,sBAAsB,EAAE,IAAI,EAAE,CAAC;YAC/E,4BAA4B,EAAQ,OAAO,EAAI,2CAA2C;YAC1F,0BAA0B,EAAU,OAAO,EAAI,2BAA2B;YAC1E,qCAAqC,EAAE,OAAO,EAAE,oCAAoC;YACpF,yBAAyB,EAAW,OAAO;YAC3C,uBAAuB,EAAa,OAAO;YAC3C,+BAA+B,EAAK,OAAO;YAC3C,oBAAoB,EAAgB,OAAO;YAE3C,0EAA0E;YAE1E,8DAA8D;YAC9D,4BAA4B,EAAI,OAAO;YAEvC,2EAA2E;YAC3E,6BAA6B,EAAG,OAAO;YAEvC,2EAA2E;YAE3E,gEAAgE;YAChE,sFAAsF;YACtF,2EAA2E;YAE3E,2EAA2E;YAE3E,8DAA8D;YAC9D,uCAAuC,EAAG,OAAO;YACjD,yCAAyC,EAAE,OAAO;YAElD,0CAA0C;YAC1C,mBAAmB,EAAoB,OAAO;YAC9C,6BAA6B,EAAU,OAAO;YAC9C,uCAAuC,EAAE,OAAO;YAEhD,6BAA6B;YAC7B,qBAAqB,EAAG,OAAO;YAC/B,oBAAoB,EAAI,OAAO;YAE/B,sFAAsF;YACtF,uBAAuB,EAAE,MAAM;YAE/B,0EAA0E;YAE1E,+CAA+C;YAC/C,iCAAiC,EAAK,OAAO;YAE7C,uFAAuF;YACvF,uCAAuC,EAAE,OAAO;YAEhD,0EAA0E;YAC1E,qCAAqC,EAAE,OAAO;YAE9C,2EAA2E;YAE3E,yFAAyF;YACzF,kGAAkG;SACnG;KACF;IAED,gFAAgF;IAChF;QACE,KAAK,EAAE,CAAC,YAAY,EAAE,aAAa,CAAC;QACpC,KAAK,EAAE;YACL,4BAA4B,EAAG,OAAO;YACtC,6BAA6B,EAAE,OAAO;SACvC;KACF;CACF,CAAA;AAED,eAAe,MAAM,CAAA"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@tsfpp/eslint-config",
+  "version": "1.0.0",
+  "description": "Shared ESLint flat configuration for TSF++ projects",
+  "keywords": [
+    "eslint",
+    "eslint-config",
+    "typescript",
+    "tsfpp",
+    "functional",
+    "immutability"
+  ],
+  "homepage": "https://github.com/tsfpp/tsfpp#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tsfpp/tsfpp.git",
+    "directory": "packages/eslint-config"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".":              "./dist/base.js",
+    "./react":        "./dist/react.js",
+    "./api":          "./dist/api.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "scripts": {
+    "build":          "tsc --project tsconfig.build.json",
+    "prepublishOnly": "pnpm run build",
+    "lint":           "eslint dist/",
+    "test":           "node --input-type=module --eval \"import './dist/base.js'\""
+  },
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "peerDependencies": {
+    "@tanstack/eslint-plugin-query": ">=5.0.0",
+    "@typescript-eslint/eslint-plugin": ">=8.0.0",
+    "@typescript-eslint/parser": ">=8.0.0",
+    "eslint": ">=9.0.0",
+    "eslint-plugin-functional": "^9.0.0",
+    "eslint-plugin-jsx-a11y": ">=6.0.0",
+    "eslint-plugin-react": ">=7.0.0",
+    "eslint-plugin-react-hooks": ">=5.0.0",
+    "typescript": ">=5.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/eslint-plugin-query": { "optional": true },
+    "eslint-plugin-jsx-a11y":        { "optional": true },
+    "eslint-plugin-react":           { "optional": true },
+    "eslint-plugin-react-hooks":     { "optional": true }
+  },
+  "devDependencies": {
+    "@tanstack/eslint-plugin-query":    "^5.100.10",
+    "@typescript-eslint/eslint-plugin": "^8.59.3",
+    "@typescript-eslint/parser":        "^8.59.3",
+    "eslint":                           "^9.39.4",
+    "eslint-plugin-functional":         "^9.0.0",
+    "eslint-plugin-jsx-a11y":           "^6.10.2",
+    "eslint-plugin-react":              "^7.37.5",
+    "eslint-plugin-react-hooks":        "^7.1.1",
+    "typescript":                       "^5.9.3"
+  }
+}