@reasonabletech/eslint-config 0.1.0 → 0.2.1

package/docs/guides/migration.md

@@ -0,0 +1,47 @@
+# Migration Guide
+
+This guide documents breaking changes and how to migrate between major versions of @reasonabletech/eslint-config.
+
+## Current Version
+
+The current major version is **0.x** (pre-1.0). The API is stabilizing but may have breaking changes before 1.0.
+
+## Future Migration Notes
+
+_No breaking changes documented yet. This section will be updated when breaking changes are released._
+
+---
+
+## Migration Template
+
+When documenting a breaking change, use this structure:
+
+### Migrating from X.x to Y.0
+
+#### Breaking Changes
+
+1. **Change description** - Brief explanation of what changed
+   
+   **Before:**
+   ```typescript
+   // Old usage
+   ```
+   
+   **After:**
+   ```typescript
+   // New usage
+   ```
+
+2. **Another change** - Description
+
+#### Deprecations
+
+- `oldFunction()` is deprecated in favor of `newFunction()`
+
+#### New Features
+
+- Feature description
+
+---
+
+_Last updated: [date]_

package/docs/guides/usage-guide.md

@@ -0,0 +1,236 @@
+# Usage Guide
+
+## Quick Start
+
+### 1. Installation
+
+```bash
+pnpm add -D @reasonabletech/eslint-config
+```
+
+### 2. Basic Setup
+
+Create an `eslint.config.mjs` file in your project root:
+
+```typescript
+// eslint.config.mjs
+import { createTypeAwareConfig } from "@reasonabletech/eslint-config";
+
+export default createTypeAwareConfig(import.meta.dirname);
+```
+
+### 3. Add Scripts
+
+Update your `package.json`:
+
+```json
+{
+  "scripts": {
+    "lint": "eslint . --fix",
+    "lint:check": "eslint ."
+  }
+}
+```
+
+### 4. Verify Setup
+
+```bash
+pnpm lint
+```
+
+## Framework-Specific Configurations
+
+### React Projects
+
+```typescript
+// eslint.config.mjs
+import { createTypeAwareReactConfig } from "@reasonabletech/eslint-config/react";
+
+export default createTypeAwareReactConfig(import.meta.dirname);
+```
+
+Adds React Hooks rules, JSX transform support, browser globals, and relaxed parameter typing for component props.
+
+### Next.js Applications
+
+```typescript
+// eslint.config.mjs
+import { createTypeAwareNextConfig } from "@reasonabletech/eslint-config/next";
+
+export default createTypeAwareNextConfig(import.meta.dirname);
+```
+
+Adds Next.js Core Web Vitals rules, server action support (async without explicit `await`), and Next.js-specific ignores.
+
+## Custom Rule Overrides
+
+Spread the config and add overrides after it:
+
+```typescript
+// eslint.config.mjs
+import { createTypeAwareConfig } from "@reasonabletech/eslint-config";
+
+export default [
+  ...createTypeAwareConfig(import.meta.dirname),
+  {
+    rules: {
+      "@typescript-eslint/no-unused-vars": "warn",
+      "prefer-const": "error",
+    },
+  },
+];
+```
+
+### File-Specific Overrides
+
+```typescript
+// eslint.config.mjs
+import { createTypeAwareReactConfig } from "@reasonabletech/eslint-config/react";
+
+export default [
+  ...createTypeAwareReactConfig(import.meta.dirname),
+  {
+    files: ["**/*.test.tsx"],
+    rules: {
+      "@typescript-eslint/no-non-null-assertion": "off",
+    },
+  },
+];
+```
+
+## Monorepo Usage
+
+### Package-Specific Configurations
+
+Each package can have its own `eslint.config.mjs`:
+
+```typescript
+// packages/my-package/eslint.config.mjs
+import { createTypeAwareReactConfig } from "@reasonabletech/eslint-config/react";
+
+export default createTypeAwareReactConfig(import.meta.dirname);
+```
+
+### Workspace Root Configuration
+
+```typescript
+// eslint.config.mjs (root)
+import { createTypeAwareConfig } from "@reasonabletech/eslint-config";
+
+export default createTypeAwareConfig(import.meta.dirname);
+```
+
+## Ignored Files & Patterns
+
+The configuration automatically ignores files that would cause TypeScript project conflicts or are not worth linting.
+
+### Automatically Ignored Categories
+
+- **Build outputs** — `dist/`, `build/`, `.next/`, `out/`, `coverage/`
+- **Dependencies** — `node_modules/`
+- **Generated files** — `*.d.ts`, `*.generated.*`, `generated/`
+- **Config files** — `*.config.*`, `tsconfig*.json`, `package*.json` (prevents "file not in tsconfig" errors)
+- **IDE/cache** — `.vscode/`, `.idea/`, `.turbo/`, `.cache/`
+- **Lock files** — `pnpm-lock.yaml`, `yarn.lock`
+- **Examples** — `examples/`
+
+### Adding Custom Ignores
+
+```typescript
+// eslint.config.mjs
+import { createTypeAwareConfig } from "@reasonabletech/eslint-config";
+
+export default [
+  ...createTypeAwareConfig(import.meta.dirname),
+  {
+    ignores: ["archived-code/**", "*.special.js"],
+  },
+];
+```
+
+## Integration with Development Tools
+
+### VS Code
+
+Create `.vscode/settings.json`:
+
+```json
+{
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  }
+}
+```
+
+### Pre-commit Hooks
+
+Using lint-staged:
+
+```json
+{
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx}": ["eslint --fix"]
+  }
+}
+```
+
+### CI/CD
+
+```yaml
+- run: pnpm lint:check
+- run: pnpm typecheck
+```
+
+## Troubleshooting
+
+### "Parsing error: Cannot read file 'tsconfig.json'"
+
+Your `tsconfig.json` must be in the project directory passed to the config function:
+
+```bash
+npx tsc --showConfig
+```
+
+### "Rule requires type checking to be enabled"
+
+Make sure you're using a `createTypeAware*` function, not manually constructing config:
+
+```typescript
+// Correct
+export default createTypeAwareConfig(import.meta.dirname);
+```
+
+### "Cannot resolve module" errors
+
+Verify the package is installed:
+
+```bash
+pnpm list @reasonabletech/eslint-config
+```
+
+### Performance on Large Projects
+
+Type-aware linting is slower than syntax-only linting. For large projects:
+
+```bash
+# Use ESLint cache
+pnpm eslint . --cache
+
+# Increase memory if needed
+NODE_OPTIONS="--max-old-space-size=4096" pnpm lint
+```
+
+### Debugging Configuration
+
+```bash
+# See which rules are active for a file
+npx eslint --print-config src/index.ts
+
+# Check if a specific file is ignored
+npx eslint path/to/file.ts --debug
+```
+
+## Related Documentation
+
+- [API Reference](../reference/api-reference.md) — All exported functions and plugin rules
+- [Architecture](../concepts/architecture.md) — Design decisions and internal structure

package/docs/index.md

@@ -0,0 +1,29 @@
+# @reasonabletech/eslint-config Documentation
+
+For quick setup, see the [README](../README.md).
+
+## Guides
+
+- **[Usage Guide](./guides/usage-guide.md)** — Setup instructions, custom overrides, monorepo patterns, troubleshooting, and ignored file patterns
+
+## Reference
+
+- **[API Reference](./reference/api-reference.md)** — All exported functions, the `@reasonabletech` plugin, and custom rule documentation
+- **[Base Configuration](./reference/base-config.md)** — Core configuration specifications and rule details
+- **[Framework Configurations](./reference/frameworks/)** — React and Next.js specific configuration details
+
+## Concepts
+
+- **[Architecture](./concepts/architecture.md)** — Design principles, configuration composition, and internal structure
+- **[AI Code Safety](./concepts/ai-code-safety.md)** — Why strict type-aware linting matters for AI-generated code
+
+## Tutorials
+
+- **[Refactoring React for Type Safety](./tutorials/refactoring-react-for-type-safety.md)** — Fixing `strict-boolean-expressions` violations in React components
+
+## Monorepo Context
+
+- [Package README](../README.md)
+- [Architecture](../../../docs/architecture.md) — How packages relate
+- [Tooling](../../../docs/tooling.md) — Turbo, Changesets, ESLint details
+- [Contributing](../../../CONTRIBUTING.md)

package/docs/reference/api-reference.md

@@ -0,0 +1,230 @@
+# API Reference
+
+## Package Exports
+
+The package exposes three entry points. All internal modules (`base-configs`, `shared-rules`, `shared-ignores`, etc.) are **not** part of the public API.
+
+### `@reasonabletech/eslint-config`
+
+```typescript
+import { createTypeAwareConfig } from "@reasonabletech/eslint-config";
+```
+
+#### `createTypeAwareConfig(projectDir: string): Linter.Config[]`
+
+Creates a comprehensive type-aware ESLint configuration for TypeScript projects.
+
+**Parameters:**
+
+- `projectDir` — Absolute path to the project root (use `import.meta.dirname`)
+
+**Returns:** Array of ESLint flat config objects
+
+**Includes:**
+
+- ESLint recommended rules
+- TypeScript-ESLint recommended + type-checked rules
+- Prettier compatibility
+- JSDoc enforcement
+- Turbo monorepo rules
+- `@reasonabletech` custom plugin rules (see below)
+- Comprehensive ignore patterns
+- Test file relaxation (`tests/**`, `examples/**`)
+
+**Also exports:** `sharedReactComponentRules` (shared React rules for use in custom configurations)
+
+---
+
+### `@reasonabletech/eslint-config/react`
+
+```typescript
+import { createTypeAwareReactConfig } from "@reasonabletech/eslint-config/react";
+```
+
+#### `createTypeAwareReactConfig(projectDir: string): Linter.Config[]`
+
+Creates a type-aware ESLint configuration for React projects.
+
+**Parameters:**
+
+- `projectDir` — Absolute path to the project root
+
+**Includes everything in the base config plus:**
+
+- React Hooks plugin (`rules-of-hooks`, `exhaustive-deps`)
+- React Refresh plugin for HMR
+- JSX transform compatibility (no React import required)
+- Browser and service worker globals
+- Relaxed parameter typing for component props
+
+---
+
+### `@reasonabletech/eslint-config/next`
+
+```typescript
+import { createTypeAwareNextConfig } from "@reasonabletech/eslint-config/next";
+```
+
+#### `createTypeAwareNextConfig(projectDir: string): Linter.Config[]`
+
+Creates a type-aware ESLint configuration for Next.js applications.
+
+**Parameters:**
+
+- `projectDir` — Absolute path to the project root
+
+**Includes everything in the React config plus:**
+
+- Next.js Core Web Vitals rules
+- Server action support (async functions without explicit `await`)
+- Next.js-specific ignore patterns (`.next/`, `out/`)
+
+---
+
+## `@reasonabletech` ESLint Plugin
+
+All configurations automatically register the `@reasonabletech` ESLint plugin, which provides 4 custom rules implemented with `ESLintUtils.RuleCreator`:
+
+### `@reasonabletech/no-dependency-bundling`
+
+Prevents dependency "god object" patterns where multiple services are bundled into a single `Dependencies` object.
+
+```typescript
+// Triggers lint error
+class UserService {
+  constructor(private deps: Dependencies) {} // "Dependencies" suffix detected
+}
+
+// Correct: inject dependencies individually
+class UserService {
+  constructor(
+    private db: DatabaseClient,
+    private logger: Logger,
+  ) {}
+}
+```
+
+### `@reasonabletech/no-linter-disabling`
+
+Requires justification comments when disabling ESLint rules. Bare `eslint-disable` comments without explanation are flagged.
+
+```typescript
+// Triggers lint error
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+
+// Correct: provide justification
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- Required by framework callback signature
+```
+
+### `@reasonabletech/no-null-undefined-checks`
+
+Catches null/undefined checks that don't match the variable's declared type union. For example, checking `=== null` when the type is `T | undefined` (not `T | null`).
+
+```typescript
+function process(value: string | undefined) {
+  // Triggers lint error: null is not in the type union
+  if (value === null) {
+    return;
+  }
+
+  // Correct: check for what's actually in the type
+  if (value === undefined) {
+    return;
+  }
+}
+```
+
+### `@reasonabletech/use-result-helpers`
+
+Enforces use of `ok()` and `err()` helper functions from `@reasonabletech/utils` instead of manually constructing Result objects.
+
+```typescript
+// Triggers lint error
+return { success: true, data: user };
+
+// Correct: use helpers
+return ok(user);
+```
+
+---
+
+## Additional Rule Enforcement
+
+Beyond the 4 plugin rules, configurations also enforce patterns via `no-restricted-syntax` AST selectors. These are organized as factory functions in `src/custom-rules/`:
+
+| Factory Function                   | What It Enforces                                                     |
+| ---------------------------------- | -------------------------------------------------------------------- |
+| `createErrorHandlingRules()`       | No error message parsing, documented error types, naming conventions |
+| `createTypeSafetyRules()`          | No `as any` casts, no double casts through `any`                     |
+| `createArchitecturePatternRules()` | Service architecture patterns, DI enforcement                        |
+| `createCodeQualityRules()`         | No `export *` (barrel exports), no mixed async patterns              |
+| `createPlatformConventionRules()`  | UI barrel import restrictions                                        |
+| `createNullUndefinedChecksRules()` | Additional null/undefined pattern enforcement                        |
+
+### Preset Functions
+
+Two preset functions combine these rule sets:
+
+#### `createPlatformRulePreset(): Linter.RulesRecord`
+
+All rules with platform-specific defaults (strict settings, platform documentation URLs).
+
+#### `createGenericRulePreset(docBaseUrl?: string): Linter.RulesRecord`
+
+Subset of rules suitable for non-projects. Accepts a custom documentation base URL.
+
+---
+
+## Usage Patterns
+
+### Standard project
+
+```typescript
+// eslint.config.mjs
+import { createTypeAwareConfig } from "@reasonabletech/eslint-config";
+
+export default createTypeAwareConfig(import.meta.dirname);
+```
+
+### With custom overrides
+
+```typescript
+// eslint.config.mjs
+import { createTypeAwareConfig } from "@reasonabletech/eslint-config";
+
+export default [
+  ...createTypeAwareConfig(import.meta.dirname),
+  {
+    rules: {
+      "@typescript-eslint/no-unused-vars": "warn",
+    },
+  },
+];
+```
+
+### File-specific overrides
+
+```typescript
+// eslint.config.mjs
+import { createTypeAwareReactConfig } from "@reasonabletech/eslint-config/react";
+
+export default [
+  ...createTypeAwareReactConfig(import.meta.dirname),
+  {
+    files: ["**/*.test.tsx"],
+    rules: {
+      "@typescript-eslint/no-non-null-assertion": "off",
+    },
+  },
+];
+```
+
+## TypeScript Integration
+
+All configurations use `projectService: true` for automatic `tsconfig.json` discovery. Your project must have a valid `tsconfig.json` in the project root.
+
+## Related Documentation
+
+- [Usage Guide](../guides/usage-guide.md) — Setup and troubleshooting
+- [Architecture](../concepts/architecture.md) — Design decisions
+- [Custom Rules README](../../src/custom-rules/README.md) — Rule implementation details and contributing guide

package/docs/reference/base-config.md

@@ -0,0 +1,118 @@
+# Base ESLint Configuration
+
+The base configuration (`@reasonabletech/eslint-config`) provides fundamental linting rules suitable for all TypeScript projects in the monorepo.
+
+## Features
+
+- ESLint recommended rules for code quality
+- Prettier integration to avoid conflicts with code formatting
+- TypeScript-ESLint recommended rules for type safety
+- Turbo rules for monorepo health
+- Error handling best practices
+- Consistent type annotations
+
+## Installation
+
+This package is installed as a workspace dependency:
+
+```bash
+pnpm add -D @reasonabletech/eslint-config
+```
+
+## Usage
+
+Create an `eslint.config.js` file in your project root:
+
+```javascript
+// eslint.config.js
+import { config } from "@reasonabletech/eslint-config";
+
+export default config;
+```
+
+## Configuration Details
+
+The base configuration includes:
+
+### Core Rules
+
+- ESLint recommended rules from `@eslint/js`
+- Prettier compatibility via `eslint-config-prettier`
+- TypeScript-ESLint recommended rules
+
+### Plugins
+
+- `turbo` - Enforces monorepo best practices
+
+### Key Rules
+
+- `turbo/no-undeclared-env-vars`: Errors when using undeclared environment variables
+- `no-throw-literal`: Enforces throwing Error objects instead of literals
+- `prefer-promise-reject-errors`: Ensures consistent error handling in Promises
+- `no-new-native-nonconstructor`: Prevents using the global Error constructor directly
+- `@typescript-eslint/explicit-function-return-type`: Enforces return types on functions
+
+### Ignored Patterns
+
+- `dist/**` - Ignores build output
+- `scripts/**` - Ignores script files
+- `**/scripts/**` - Ignores nested script directories
+
+## Philosophy: Warnings as Errors
+
+### Design Decision
+
+All ESLint warnings are treated as errors in the the codebase. This design choice reflects our commitment to code quality and developer experience.
+
+### Rationale
+
+- **Fail Fast**: Issues are caught immediately rather than accumulating
+- **CI/CD Reliability**: Builds fail on any code quality issues, preventing problematic code from reaching production
+- **Developer Discipline**: Encourages addressing issues immediately rather than deferring them
+- **Consistent Standards**: No distinction between "minor" and "major" issues - all violations block progress
+- **Agentic Code Quality**: Forces AI coding tools to write higher quality code by preventing warning tolerance
+
+### Implementation
+
+- Removed `eslint-plugin-only-warn` that converted errors to warnings
+- Updated rule configurations from `"warn"` to `"error"` severity
+- All ESLint violations now cause build failures in CI/CD
+
+### Benefits
+
+1. **Improved Code Quality**: No ignored warnings that could lead to bugs
+2. **Cleaner Codebase**: Zero tolerance for code quality violations
+3. **Better Developer Habits**: Immediate feedback loop encourages best practices
+4. **Predictable Builds**: CI failures are deterministic and actionable
+5. **Enhanced AI Development**: Agentic coding tools are compelled to generate cleaner, more maintainable code
+
+## Example
+
+```javascript
+// eslint.config.js
+import { config as baseConfig } from "@reasonabletech/eslint-config";
+
+export default [
+  ...baseConfig,
+  {
+    // Project-specific rules
+    rules: {
+      "no-console": ["warn", { allow: ["warn", "error"] }],
+    },
+  },
+  {
+    // File-specific rules
+    files: ["**/*.test.ts"],
+    rules: {
+      "@typescript-eslint/no-explicit-any": "off",
+    },
+  },
+];
+```
+
+## Related Documentation
+
+- [API Reference](./api-reference.md) — Complete function documentation
+- [Framework Configurations](./frameworks/) — React and Next.js specific configurations
+- [Usage Guide](../guides/usage-guide.md) — Setup instructions and troubleshooting
+- [Architecture](../concepts/architecture.md) — Design principles and decisions