@reasonabletech/eslint-config 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -1,9 +1,36 @@
 # @reasonabletech/eslint-config
 
+## 0.2.1
+
+### Patch Changes
+
+- - Automated release.
+
+## 0.2.0
+
+### Minor Changes
+
+- [`f862453`](https://github.com/ReasonableTech/core-utils/commit/f86245352ba4ef8df56a124c8f17bf8605ac9085) Thanks [@WillieCubed](https://github.com/WillieCubed)! - Audit and fix custom ESLint rules for correctness, false-positive reduction, and API consistency.
+
+  #### Breaking changes — action required
+  - `no-linter-disabling` is deprecated and no longer enabled by default. If you relied on it, use ESLint's built-in `reportUnusedDisableDirectives` option and the native `-- reason` inline syntax instead. The rule remains in the plugin if you need to opt in explicitly.
+  - `no-dependency-bundling` no longer flags interfaces based on property types. Only interfaces and type aliases named `*Dependencies` or `*Deps` are flagged. If you had false-positive suppressions for domain models, you can remove them.
+  - `createTerminologyRules()` no longer includes default forbidden terms. Pass `forbiddenTerms` explicitly: `createTerminologyRules({ forbiddenTerms: { toolCall: "action" } })`.
+  - `createBarrelExportRules()` and `createCodeQualityRules()` no longer accept options (the parameters were no-ops). Remove any arguments at the call site.
+  - `createResultTypeRules()` has been removed (it returned an empty object). Remove any imports.
+
+  #### New rule
+  - `no-constructor-instantiation` replaces the previous `no-restricted-syntax` selector that flagged all `new PascalCase()` calls in constructors. The new rule allows built-in constructors (`Map`, `Date`, `Set`, etc.) and default parameter values (`db: Database = new Database()`). No config changes needed — `createDependencyInjectionRules()` uses it automatically.
+
+  #### Bug fixes
+  - `no-error-message-parsing` now correctly detects `/regex/.test(error.message)` patterns (previously only caught `error.message.test()`, which nobody writes).
+  - `mergeRuleConfigurations` no longer silently escalates `"warn"` severity to `"error"` when merging `no-restricted-syntax` patterns.
+  - `no-null-undefined-checks` error message now provides actionable guidance on simplifying `T | null | undefined` types.
+
 ## [Unreleased]
 
 Initial release preparation. See [README.md](./README.md) for usage.
 
 ---
 
-*Changelog entries are automatically generated from [changesets](https://github.com/changesets/changesets) on release.*
+_Changelog entries are automatically generated from [changesets](https://github.com/changesets/changesets) on release._

package/docs/concepts/ai-code-safety.md

@@ -0,0 +1,268 @@
+# AI Code Safety Through Strict Linting
+
+## Philosophy
+
+The the codebase is predominantly AI-generated, which presents unique challenges and opportunities for code quality management. Our ESLint configuration is designed with this reality in mind, emphasizing strict rules that force both human developers and AI tools to produce safer, more maintainable code.
+
+## Core Principles
+
+### 1. **Strict Rules, No Warnings**
+
+We have a zero-tolerance policy for ESLint warnings in our codebase:
+
+- **All rules are set to `"error"`** - no warnings that can be ignored
+- **Builds fail on any linting violation** - forcing immediate resolution
+- **No `eslint-disable` comments** - rules must be followed, not bypassed
+
+**Rationale**: Warnings are too easy to ignore. In a large codebase with frequent AI-generated changes, deferred issues accumulate quickly and become technical debt.
+
+### 2. **"Rip the Band-Aid Off Early"**
+
+Issues are caught and resolved immediately during development, not during code review:
+
+- **Fail fast development cycles** - problems surface during writing, not review
+- **Reduced cognitive load** - developers focus on logic, not style cleanup
+- **Consistent quality gates** - every commit meets the same high standards
+
+### 3. **Type Safety is Non-Negotiable**
+
+Type-aware ESLint rules are mandatory across all projects:
+
+```typescript
+// Canonical setup (required)
+import { createTypeAwareConfig } from "@reasonabletech/eslint-config";
+export default createTypeAwareConfig(import.meta.dirname);
+```
+
+**Why type-aware rules matter**:
+
+- Catch more runtime errors during development
+- Force explicit type annotations that improve readability
+- Prevent common AI-generated code issues (implicit any, unsafe assignments)
+- Enable better IDE support and refactoring safety
+
+### 4. **Explicit Behavior Over Implicit**
+
+We prefer explicit code patterns that make intent clear:
+
+```typescript
+// ❌ Implicit, unclear behavior
+if (process.env.DATABASE_URL) {
+  connect(process.env.DATABASE_URL);
+}
+
+// ✅ Explicit, safe behavior
+const config = getEnvironmentConfig();
+if (config.database.url) {
+  connect(config.database.url);
+}
+```
+
+### 5. **Avoid Silent Errors**
+
+Code should fail loudly and predictably rather than silently producing incorrect results:
+
+```typescript
+// ❌ Silent failure potential
+const result = data?.user?.profile?.name || "Unknown";
+
+// ✅ Explicit error handling
+const result = getUserProfile(data);
+if (!result.success) {
+  logger.error("Failed to get user profile", { error: result.error });
+  return { success: false, error: "Profile unavailable" };
+}
+```
+
+## Type Safety Requirements
+
+### Strict Null/Undefined Handling
+
+We minimize nullable types and prefer explicit error handling:
+
+```typescript
+// ❌ Nullable return types
+function getUser(id: string): User | null {
+  // Silent failure case
+}
+
+// ✅ Result types for explicit error handling
+function getUser(id: string): Result<User, "not_found" | "database_error"> {
+  try {
+    const user = database.findUser(id);
+    if (!user) {
+      return { success: false, error: "not_found" };
+    }
+    return { success: true, data: user };
+  } catch (error) {
+    return { success: false, error: "database_error" };
+  }
+}
+```
+
+### Environment Variable Safety
+
+Raw `process.env` access is discouraged. Use configuration wrappers:
+
+```typescript
+// ❌ Direct environment access
+if (process.env.NODE_ENV === "production") {
+  // Complex conditional logic
+}
+
+// ✅ Wrapped configuration
+const config = getEnvironmentConfig();
+if (config.isProduction) {
+  // Clear intent
+}
+```
+
+### Result Types for Domain Logic
+
+Use `Result<T, E>` from `@reasonabletech/utils/result` for operations that can fail:
+
+```typescript
+import type { Result } from "@reasonabletech/utils/result";
+
+// Domain operations that can fail should return Results
+async function processPayment(
+  amount: number,
+): Promise<Result<PaymentConfirmation, PaymentError>> {
+  // Implementation with explicit error cases
+}
+
+// Consumers handle all cases explicitly
+const result = await processPayment(100);
+if (result.success) {
+  console.log("Payment processed:", result.data);
+} else {
+  handlePaymentError(result.error);
+}
+```
+
+## AI-Specific Benefits
+
+### 1. **Forces Better AI Output**
+
+Strict linting rules compel AI tools to generate higher-quality code:
+
+- **Type annotations**: AI must provide explicit return types
+- **Error handling**: AI cannot ignore potential failure cases
+- **Null safety**: AI must handle undefined/null cases explicitly
+
+### 2. **Prevents Common AI Mistakes**
+
+- **Unused variables**: AI often generates variables it doesn't use
+- **Unsafe type assertions**: AI may use `any` types inappropriately
+- **Missing await**: AI sometimes forgets async/await patterns
+- **Template literal safety**: AI must handle potentially undefined values in strings
+
+### 3. **Consistent Code Patterns**
+
+AI learns to follow consistent patterns across the codebase:
+
+- Result types for error handling
+- Explicit type annotations
+- Safe environment variable access
+- Structured logging with context
+
+## Configuration Details
+
+### Key Strict Rules
+
+```typescript
+{
+  // Type safety (errors, not warnings)
+  "@typescript-eslint/explicit-function-return-type": "error",
+  "@typescript-eslint/no-explicit-any": "error",
+  "@typescript-eslint/strict-boolean-expressions": "error",
+  "@typescript-eslint/prefer-nullish-coalescing": "error",
+  "@typescript-eslint/no-non-null-assertion": "error",
+
+  // Runtime safety
+  "@typescript-eslint/no-floating-promises": "error",
+  "@typescript-eslint/no-misused-promises": "error",
+  "@typescript-eslint/await-thenable": "error",
+
+  // Code quality
+  "@typescript-eslint/no-unused-vars": "error",
+  "prefer-const": "error",
+  "no-throw-literal": "error"
+}
+```
+
+### Non-Null Assertion Safety
+
+The non-null assertion operator (`!`) is disabled because it completely bypasses TypeScript's null safety checks, potentially causing runtime crashes:
+
+```typescript
+// ❌ Dangerous - bypasses type safety
+const token = createAuthToken(user!.id, user!.email);
+const result = dangerousFunction()!.someProperty;
+
+// ✅ Safe alternatives - explicit null checking
+if (!user) {
+  throw new Error("User is required");
+}
+const token = createAuthToken(user.id, user.email);
+
+// ✅ Safe alternatives - optional chaining with defaults
+const token = user?.id ? createAuthToken(user.id, user.email) : null;
+
+// ✅ Safe alternatives - type guards
+function isValidUser(user: User | null): user is User {
+  return user !== null && user.id !== undefined;
+}
+
+if (isValidUser(user)) {
+  const token = createAuthToken(user.id, user.email);
+}
+```
+
+**Why this matters for AI-generated code**: AI tools often use non-null assertions as shortcuts when they encounter nullable types. By disabling this feature, we force AI to implement proper null checking, leading to more robust code that handles edge cases explicitly.
+
+### Canonical Setup Pattern
+
+All projects should use one of the package configuration factories:
+
+```typescript
+import { createTypeAwareConfig } from "@reasonabletech/eslint-config";
+
+export default createTypeAwareConfig(import.meta.dirname);
+```
+
+## Benefits
+
+### For Human Developers
+
+- **Immediate feedback** on code quality issues
+- **Consistent standards** across the entire codebase
+- **Reduced review overhead** - linting catches issues before review
+- **Better IDE support** with comprehensive type information
+
+### For AI-Generated Code
+
+- **Higher quality output** - AI tools adapt to strict requirements
+- **Consistent patterns** - AI learns project conventions
+- **Fewer runtime errors** - type-aware rules catch more issues
+- **Explicit error handling** - AI is forced to handle edge cases
+
+### for the Codebase
+
+- **Predictable builds** - all code meets the same quality bar
+- **Reduced technical debt** - issues are resolved immediately
+- **Better maintainability** - explicit patterns are easier to understand
+- **Safer refactoring** - comprehensive type information enables confident changes
+
+## Conclusion
+
+Our strict ESLint configuration is not about making development harder—it's about making development **safer** and more **predictable** in an AI-first codebase. By enforcing high standards immediately, we ensure that both human and AI contributors produce code that is reliable, maintainable, and explicit in its intent.
+
+The investment in strict linting pays dividends in reduced debugging time, fewer production issues, and a codebase that remains comprehensible as it scales.
+
+## Related Documentation
+
+- [Architecture](./architecture.md) — Package design principles and configuration composition
+- [API Reference](../reference/api-reference.md) — All exported functions and plugin rules
+- [Usage Guide](../guides/usage-guide.md) — Setup instructions and troubleshooting
+- [Custom Rules](../../src/custom-rules/README.md) — Rule catalog and contributing guide

package/docs/concepts/architecture.md

@@ -0,0 +1,394 @@
+# Architecture
+
+This document outlines the architectural design and principles behind `@reasonabletech/eslint-config`, explaining the decisions made to create a maintainable, modular, and consistent ESLint configuration system for the monorepo.
+
+## Design Principles
+
+### 1. Type-Aware First
+
+**Principle:** All configurations prioritize TypeScript type-aware rules as the primary approach.
+
+**Rationale:** AI-generated code requires comprehensive static analysis to catch subtle runtime errors that syntax-only rules would miss. Type-aware rules leverage TypeScript's type system to detect:
+
+- Unsafe type operations
+- Floating promises
+- Incorrect async/await usage
+- Type assertion issues
+- Boolean expression strictness
+
+**Implementation:** The `createTypeAwareConfig()` function is the primary export for all greenfield TypeScript projects.
+
+### 2. Modular Composition
+
+**Principle:** All configurations are built from composable, shared modules to eliminate duplication.
+
+**Rationale:** The original monolithic configuration contained 400+ lines with massive duplication across base, type-aware, React, and Next.js configurations. This led to:
+
+- Maintenance overhead when updating rules
+- Inconsistencies between configurations
+- Difficulty understanding rule origins
+- Code bloat
+
+**Architecture:**
+
+```
+src/
+├── index.ts                    # Base TypeScript configuration
+├── react.ts                   # React configuration entry point
+├── next.ts                    # Next.js configuration entry point
+├── base-configs.ts            # Core TypeScript configuration logic
+├── react/                     # React-specific modules
+│   ├── config.ts              # React configuration builder
+│   ├── plugins.ts             # React plugin setups
+│   └── rules.ts               # React rule definitions
+├── next/                      # Next.js-specific modules
+│   ├── config.ts              # Next.js configuration builder
+│   ├── ignores.ts             # File ignore patterns
+│   ├── plugins.ts             # Plugin loading and fallbacks
+│   ├── rules.ts               # Rule configurations
+│   └── settings.ts            # Plugin settings
+├── shared/                    # Shared utilities
+│   └── react-rules.ts         # Common React rules for both React and Next.js
+├── shared-ignores.ts          # Centralized ignore patterns
+└── shared-rules.ts            # Shared TypeScript rule sets
+```
+
+### 3. Explicit Over Implicit
+
+**Principle:** All rules and patterns are explicitly defined rather than relying on defaults.
+
+**Rationale:** AI-generated code analysis requires predictable, explicit rule sets. Implicit defaults can lead to:
+
+- Inconsistent behavior across projects
+- Difficulty debugging rule conflicts
+- Unclear rule inheritance chains
+
+**Implementation:** Each rule is explicitly set with clear documentation of its purpose and behavior.
+
+### 4. Framework-Specific Customization
+
+**Principle:** Framework configurations extend the base rather than replacing it entirely.
+
+**Rationale:** Frameworks like React and Next.js have specific patterns that conflict with strict TypeScript rules, but they should still maintain the core safety guarantees.
+
+**Implementation:** Framework overrides are isolated in separate rule sets that can be composed with the base configuration.
+
+## Package Structure
+
+### Core Components
+
+#### 1. Shared Ignore Patterns (`src/shared-ignores.ts`)
+
+**Purpose:** Centralized file exclusion patterns for all project types.
+
+**Categories:**
+
+- Build outputs (`dist/`, `build/`, `.next/`)
+- Dependencies (`node_modules/`, `.pnp.*`)
+- Generated files (`*.d.ts`, `*.generated.*`)
+- Development tooling (`scripts/`, config files)
+- Test infrastructure and coverage
+- IDE and OS-specific files
+
+**Design Decision:** Single array with comprehensive patterns rather than categorized objects to maintain ESLint compatibility and simplicity.
+
+#### 2. Modular Rule Organization
+
+**Purpose:** Framework-specific rule modules that eliminate duplication.
+
+**React Module (`src/react/`):**
+
+- `rules.ts`: React-specific rule definitions using shared React rules
+- `plugins.ts`: React and React Hooks plugin configurations
+- `config.ts`: Complete React configuration builder
+
+**Next.js Module (`src/next/`):**
+
+- `rules.ts`: Next.js rule definitions with React rule inheritance
+- `plugins.ts`: Plugin loading with graceful fallbacks
+- `ignores.ts`: Next.js-specific file ignore patterns
+- `settings.ts`: Plugin settings for React and Next.js
+- `config.ts`: Complete Next.js configuration orchestrator
+
+**Shared Module (`src/shared/`):**
+
+- `react-rules.ts`: Common React rules shared between React and Next.js configs
+
+**Design Decision:** Focused modules with single responsibilities rather than monolithic rule objects to improve maintainability and enable better code organization.
+
+#### 3. Base Configuration Builders (`src/base-configs.ts`)
+
+**Purpose:** Factory functions that compose shared components into complete configurations.
+
+**Functions:**
+
+- `createTypeAwareBaseConfig()`: Type-aware foundation
+
+**Design Decision:** Factory functions rather than static objects to enable parameterization (project directory) and better TypeScript integration.
+
+### Framework Configurations
+
+#### React Configuration (`react.ts`)
+
+**Extends:** Base configuration + React-specific rules
+
+**Additions:**
+
+- React Hooks plugin with recommended rules
+- JSX transform compatibility (no React import required)
+- Browser and service worker globals
+- Relaxed parameter typing for component props
+
+**Design Decision:** Separate file to enable selective imports and clear framework boundaries.
+
+#### Next.js Configuration (`next.ts`)
+
+**Extends:** Base configuration + React rules + Next.js-specific rules
+
+**Additions:**
+
+- Next.js Core Web Vitals rules via FlatCompat
+- Server action support (allows async without explicit await)
+- Service worker globals for PWA features
+
+**Design Decision:** Uses FlatCompat for Next.js integration to maintain compatibility with Next.js's ESLint plugin ecosystem.
+
+## Architectural Patterns
+
+### 1. Composition Over Inheritance
+
+The package uses functional composition rather than class inheritance:
+
+```typescript
+// ✅ Composition approach
+const config = [
+  ...createTypeAwareBaseConfig(projectDir),
+  reactPlugin.configs.flat.recommended,
+  { rules: reactRuleOverrides },
+];
+
+// ❌ Inheritance approach (avoided)
+class ReactConfig extends BaseConfig {
+  // Complex inheritance chain
+}
+```
+
+**Benefits:**
+
+- Clear data flow and dependencies
+- Easy to understand rule sources
+- No hidden inheritance behavior
+- Better TypeScript inference
+
+### 2. Configuration as Data
+
+All configurations are plain JavaScript objects/arrays rather than classes:
+
+```typescript
+// ✅ Data-driven approach
+export const baseRules: Linter.RulesRecord = {
+  "no-throw-literal": "error",
+  // ...
+};
+
+// ❌ Class-based approach (avoided)
+class RuleManager {
+  getRules() {
+    /* complex logic */
+  }
+}
+```
+
+**Benefits:**
+
+- Serializable and inspectable
+- No runtime dependencies
+- Easy to merge and extend
+- Compatible with ESLint's flat config system
+
+### 3. Explicit Dependencies
+
+All imports are explicit and traceable:
+
+```typescript
+// ✅ Explicit imports
+import { sharedIgnores } from "./shared-ignores.js";
+import { baseRules, typeAwareRules } from "./shared-rules.js";
+
+// ❌ Implicit dependencies (avoided)
+import * as config from "./monolithic-config.js";
+```
+
+**Benefits:**
+
+- Clear dependency relationships
+- Better tree-shaking
+- Easier refactoring
+- Explicit API boundaries
+
+## Rule Philosophy
+
+### Error Handling Standards
+
+**Principle:** Never parse error messages; always use structured error detection.
+
+**Implementation:**
+
+```typescript
+"no-throw-literal": "error",
+"prefer-promise-reject-errors": "error",
+"@typescript-eslint/only-throw-error": "error",
+```
+
+**Rationale:** AI-generated code often includes error handling patterns. Parsing error messages leads to brittle code that breaks when error messages change.
+
+### TypeScript Safety
+
+**Principle:** Maximize type safety while maintaining practical development experience.
+
+**Implementation:**
+
+```typescript
+"@typescript-eslint/no-explicit-any": "error",
+"@typescript-eslint/no-non-null-assertion": "error",
+"@typescript-eslint/strict-boolean-expressions": "error",
+```
+
+**Rationale:** AI-generated code can introduce subtle type safety issues. Strict rules catch these early in development.
+
+### Framework Accommodations
+
+**Principle:** Relax rules only where framework patterns make strict rules impractical.
+
+**Example - React:**
+
+```typescript
+"@typescript-eslint/prefer-readonly-parameter-types": "off", // Component props
+"@typescript-eslint/require-await": "off",                   // Event handlers
+"@typescript-eslint/unbound-method": "off",                  // React patterns
+```
+
+**Important Change: Strict Boolean Expressions in React**
+
+As of the latest architecture revision, **`@typescript-eslint/strict-boolean-expressions` is no longer disabled for React projects**. This maintains consistent architectural patterns across the platform and prevents subtle rendering bugs.
+
+**Rationale:**
+
+- **Consistency**: All TypeScript code follows the same strict patterns
+- **Bug Prevention**: Prevents rendering of `0`, `""`, or `[object Object]` in React components
+- **Better Architecture**: Encourages explicit conditional logic over implicit truthiness
+- **AI Code Safety**: Maintains strict type checking even in React contexts
+
+React components should use explicit boolean checks:
+
+```tsx
+// ❌ Previously allowed, now flagged as error
+{
+  items && <ItemList items={items} />;
+}
+
+// ✅ Required explicit pattern
+{
+  items.length > 0 && <ItemList items={items} />;
+}
+```
+
+## Implementation Approach
+
+The current architecture standardizes configuration through a modular design:
+
+1. **Shared rule and ignore modules** provide a single source of truth.
+2. **Factory functions** compose complete project-specific configurations.
+3. **Framework adapters** apply React and Next.js behavior without duplicating the base.
+4. **Documentation and examples** define the canonical setup for new packages and apps.
+
+## Performance Considerations
+
+### Configuration Size
+
+**Goal:** Minimize configuration object size while maintaining comprehensive rule coverage.
+
+**Implementation:**
+
+- Shared ignore patterns reduce duplication
+- Rule objects are composed rather than merged at runtime
+- TypeScript inference eliminates need for runtime type checking
+
+### Type Checking Performance
+
+**Goal:** Balance comprehensive type checking with reasonable performance.
+
+**Implementation:**
+
+- Type-aware rules are opt-in via `createTypeAwareConfig()`
+- Project directory parameterization for efficient TypeScript project loading
+- Comprehensive ignore patterns reduce files processed
+
+## Extensibility
+
+### Adding New Framework Support
+
+To add support for a new framework:
+
+1. **Create framework-specific rules** in `src/shared-rules.ts`
+2. **Create framework configuration file** (e.g., `svelte.ts`)
+3. **Compose base configuration** with framework-specific additions
+4. **Document usage patterns** in the usage guide
+
+### Custom Rule Integration
+
+Projects can extend configurations:
+
+```typescript
+export default [
+  ...createTypeAwareConfig(import.meta.dirname),
+  {
+    rules: {
+      // Project-specific overrides
+      "@typescript-eslint/no-unused-vars": "warn",
+    },
+  },
+];
+```
+
+## Quality Assurance
+
+### Testing Strategy
+
+**Configuration packages are exempt** from comprehensive testing per UIDE-126 standards because:
+
+- They contain declarative configuration objects, not business logic
+- Their "testing" happens naturally when consumed by other packages
+- Configuration errors are caught during actual linting operations
+
+### Validation Approach
+
+**Runtime validation:**
+
+- ESLint validates configuration structure when loaded
+- TypeScript ensures configuration object types are correct
+- Consumer packages validate rule effectiveness through linting
+
+**Documentation validation:**
+
+- All examples are tested in real projects
+- API documentation matches actual exports
+
+## Future Considerations
+
+### Planned Enhancements
+
+1. **Additional framework support** (Svelte, Astro, etc.)
+2. **Rule set customization** for different project types
+3. **Performance optimization** for large monorepos
+4. **Integration improvements** with development tools
+
+### Versioning Policy
+
+Public exports and behavior follow semantic versioning. Breaking changes are introduced only in major releases with updated package documentation.
+
+## Related Documentation
+
+- [API Reference](../reference/api-reference.md) - Complete API documentation
+- [Usage Guide](../guides/usage-guide.md) - Detailed usage instructions
+- [Examples](../../examples/) - Configuration examples