@reasonabletech/eslint-config 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @reasonabletech/eslint-config
+
+## [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.*

package/README.md

@@ -0,0 +1,89 @@
+# @reasonabletech/eslint-config
+
+[![npm version](https://img.shields.io/npm/v/@reasonabletech/eslint-config.svg)](https://www.npmjs.com/package/@reasonabletech/eslint-config)
+[![npm downloads](https://img.shields.io/npm/dm/@reasonabletech/eslint-config.svg)](https://www.npmjs.com/package/@reasonabletech/eslint-config)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
+
+`@reasonabletech/eslint-config` provides opinionated, type-aware ESLint flat configs for TypeScript, React, and Next.js projects. Type-aware linting runs ESLint rules that require a TypeScript project reference — these rules catch issues like unsafe `any` assignments and incorrect promise handling that non-type-aware rules miss.
+
+## Installation
+
+```bash
+pnpm add -D @reasonabletech/eslint-config eslint typescript
+```
+
+## Peer Dependencies
+
+| Dependency | Version   | Required |
+| ---------- | --------- | -------- |
+| eslint     | >= 9.0    | Yes      |
+| typescript | >= 5.0    | Yes      |
+
+This package uses ESLint flat config format (introduced in ESLint 9.0) and requires TypeScript 5.0+ for type-aware linting. Legacy `.eslintrc` configuration is not supported.
+
+## Exported Entry Points
+
+| Import Path                           | Purpose                    | Main Exports                                         |
+| ------------------------------------- | -------------------------- | ---------------------------------------------------- |
+| `@reasonabletech/eslint-config`       | TypeScript baseline config | `createTypeAwareConfig`, `sharedReactComponentRules` |
+| `@reasonabletech/eslint-config/react` | React project config       | `createTypeAwareReactConfig`                         |
+| `@reasonabletech/eslint-config/next`  | Next.js project config     | `createTypeAwareNextConfig`                          |
+
+## Usage
+
+### TypeScript Project
+
+```ts
+// eslint.config.mjs
+import { createTypeAwareConfig } from "@reasonabletech/eslint-config";
+
+export default createTypeAwareConfig(import.meta.dirname);
+```
+
+### React Project
+
+```ts
+// eslint.config.mjs
+import { createTypeAwareReactConfig } from "@reasonabletech/eslint-config/react";
+
+export default createTypeAwareReactConfig(import.meta.dirname);
+```
+
+### Next.js Project
+
+```ts
+// eslint.config.mjs
+import { createTypeAwareNextConfig } from "@reasonabletech/eslint-config/next";
+
+export default createTypeAwareNextConfig(import.meta.dirname);
+```
+
+### Customize Rules for Your Project
+
+```ts
+// eslint.config.mjs
+import { createTypeAwareConfig } from "@reasonabletech/eslint-config";
+
+export default [
+  ...createTypeAwareConfig(import.meta.dirname),
+  {
+    rules: {
+      "@typescript-eslint/no-unused-vars": "warn",
+    },
+  },
+];
+```
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for release history.
+
+This package follows [Semantic Versioning](https://semver.org/). Breaking changes are documented with migration guides when applicable.
+
+## Additional References
+
+- [Usage Guide](./docs/guides/usage-guide.md)
+- [Package Docs](./docs/index.md)
+- [API Reference](./docs/reference/api-reference.md)
+- [Architecture](./docs/concepts/architecture.md)

package/dist/src/base-configs.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Base ESLint Configuration Builders - Foundation for consistent linting across the monorepo
+ *
+ * This module provides the core configuration builders used to create consistent ESLint
+ * configurations across all projects in the monorepo. It combines shared rules,
+ * ignore patterns, and TypeScript configurations into reusable base configurations
+ * that ensure consistency while reducing code duplication.
+ *
+ * The implementation follows several architectural principles:
+ * - Centralized base configuration to ensure consistency across all projects
+ * - Separation of concerns between basic and type-aware configurations
+ * - Modular composition using shared rules and ignore patterns
+ * - TypeScript-first approach with comprehensive type checking capabilities
+ * - Extensible design that supports framework-specific customizations
+ * Base ESLint configuration builders for the monorepo
+ * @author ReasonableTech Team
+ * @since 0.1.0
+ */
+import type { Linter } from "eslint";
+/**
+ * Creates a comprehensive type-aware ESLint configuration with TypeScript project analysis.
+ *
+ * This function generates the recommended ESLint configuration for all projects.
+ * It includes all base rules plus advanced type-aware rules that leverage TypeScript's
+ * type system to catch subtle bugs, unsafe operations, and logical inconsistencies
+ * that would be missed by syntax-only analysis. This is essential for AI-generated
+ * code safety and maintaining high code quality standards.
+ *
+ * The configuration includes:
+ * - JavaScript and TypeScript recommended rules
+ * - Prettier compatibility layer
+ * - TypeScript type-aware analysis rules
+ * - Comprehensive ignore patterns for build outputs and generated files
+ * - Strict type safety rules optimized for AI-generated code
+ * @param projectDir - The absolute path to the directory containing the TypeScript project.
+ *                     This is used to configure TypeScript's project references for type checking.
+ * @returns Array of ESLint configuration objects with full type-aware analysis enabled
+ * @example
+ * ```typescript
+ * import { createTypeAwareBaseConfig } from './base-configs.js';
+ *
+ * // For a standard project
+ * const config = createTypeAwareBaseConfig(import.meta.dirname);
+ *
+ * // For framework-specific projects, extend the base
+ * const reactConfig = [
+ *   ...createTypeAwareBaseConfig(import.meta.dirname),
+ *   // React-specific configurations
+ * ];
+ * ```
+ */
+export declare function createTypeAwareBaseConfig(projectDir: string): Linter.Config[];
+//# sourceMappingURL=base-configs.d.ts.map

package/dist/src/base-configs.js

@@ -0,0 +1,105 @@
+/**
+ * Base ESLint Configuration Builders - Foundation for consistent linting across the monorepo
+ *
+ * This module provides the core configuration builders used to create consistent ESLint
+ * configurations across all projects in the monorepo. It combines shared rules,
+ * ignore patterns, and TypeScript configurations into reusable base configurations
+ * that ensure consistency while reducing code duplication.
+ *
+ * The implementation follows several architectural principles:
+ * - Centralized base configuration to ensure consistency across all projects
+ * - Separation of concerns between basic and type-aware configurations
+ * - Modular composition using shared rules and ignore patterns
+ * - TypeScript-first approach with comprehensive type checking capabilities
+ * - Extensible design that supports framework-specific customizations
+ * Base ESLint configuration builders for the monorepo
+ * @author ReasonableTech Team
+ * @since 0.1.0
+ */
+import js from "@eslint/js";
+import eslintConfigPrettier from "eslint-config-prettier";
+import jsdoc from "eslint-plugin-jsdoc";
+import { configs as tsConfigs } from "typescript-eslint";
+import { defineConfig, globalIgnores } from "eslint/config";
+import { reasonableTechPlugin } from "./plugin.js";
+import { sharedIgnores } from "./shared-ignores.js";
+import { baseRules, typeAwareRules } from "./shared-rules.js";
+import { createPlatformRulePreset } from "./custom-rules/index.js";
+import { createNoTypeofInExpectRules } from "./custom-rules/test-quality.js";
+/**
+ * Creates a comprehensive type-aware ESLint configuration with TypeScript project analysis.
+ *
+ * This function generates the recommended ESLint configuration for all projects.
+ * It includes all base rules plus advanced type-aware rules that leverage TypeScript's
+ * type system to catch subtle bugs, unsafe operations, and logical inconsistencies
+ * that would be missed by syntax-only analysis. This is essential for AI-generated
+ * code safety and maintaining high code quality standards.
+ *
+ * The configuration includes:
+ * - JavaScript and TypeScript recommended rules
+ * - Prettier compatibility layer
+ * - TypeScript type-aware analysis rules
+ * - Comprehensive ignore patterns for build outputs and generated files
+ * - Strict type safety rules optimized for AI-generated code
+ * @param projectDir - The absolute path to the directory containing the TypeScript project.
+ *                     This is used to configure TypeScript's project references for type checking.
+ * @returns Array of ESLint configuration objects with full type-aware analysis enabled
+ * @example
+ * ```typescript
+ * import { createTypeAwareBaseConfig } from './base-configs.js';
+ *
+ * // For a standard project
+ * const config = createTypeAwareBaseConfig(import.meta.dirname);
+ *
+ * // For framework-specific projects, extend the base
+ * const reactConfig = [
+ *   ...createTypeAwareBaseConfig(import.meta.dirname),
+ *   // React-specific configurations
+ * ];
+ * ```
+ */
+export function createTypeAwareBaseConfig(projectDir) {
+    return defineConfig(js.configs.recommended, eslintConfigPrettier, jsdoc.configs["flat/recommended-typescript"], ...tsConfigs.recommendedTypeChecked, {
+        languageOptions: {
+            parserOptions: {
+                // projectService auto-discovers the correct tsconfig for each file and
+                // creates in-memory projects for files outside any tsconfig. This
+                // eliminates the need for separate .tsconfig.typeaware-tests.json files
+                // and the RT_ESLINT_PROJECT env var override.
+                projectService: true,
+                tsconfigRootDir: projectDir,
+            },
+        },
+    }, {
+        plugins: {
+            // Cast required: typescript-eslint's RuleModule types are structurally
+            // incompatible with @eslint/core's Plugin type used by defineConfig().
+            // The plugin works correctly at runtime; this is purely a type mismatch
+            // between the two type ecosystems.
+            "@reasonabletech": reasonableTechPlugin,
+        },
+    }, {
+        // Report unused ESLint disable directives across all projects
+        linterOptions: {
+            reportUnusedDisableDirectives: "error",
+        },
+    }, globalIgnores([...sharedIgnores, "**/*.mjs", "**/vitest.config.mts"]), {
+        rules: {
+            ...baseRules,
+            ...typeAwareRules,
+            ...createPlatformRulePreset(),
+        },
+    }, {
+        // Test-quality rules applied specifically to test files.
+        // These ban low-value patterns that AI agents use to inflate coverage
+        // without verifying real behaviour.
+        files: [
+            "**/*.test.ts",
+            "**/*.test.tsx",
+            "**/tests/**/*.ts",
+            "**/tests/**/*.tsx",
+        ],
+        rules: createNoTypeofInExpectRules(),
+    });
+}
+//# sourceMappingURL=base-configs.js.map

package/dist/src/custom-rules/architecture-patterns.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Architecture pattern rules for the platform
+ *
+ * These rules enforce architectural best practices and prevent common
+ * anti-patterns in service design and dependency injection.
+ */
+import { ESLintUtils } from "@typescript-eslint/utils";
+import type { Linter } from "eslint";
+/**
+ * Configuration options for architecture pattern rules
+ */
+export interface ArchitecturePatternRuleOptions {
+    /** Base URL for documentation references */
+    docBaseUrl?: string;
+    /** Whether to enforce individual dependency injection (default: true) */
+    enforceIndividualDependencies?: boolean;
+}
+/**
+ * Custom ESLint rule that prevents bundling service dependencies into objects
+ *
+ * This rule prevents the anti-pattern of wrapping service dependencies in
+ * container objects. The pattern itself is wrong - it doesn't matter if you
+ * bundle 1 service or 10 services, wrapping them breaks dependency injection.
+ *
+ * **Core Principle**: Services should receive dependencies as direct constructor
+ * parameters, not wrapped in objects. This makes dependencies explicit, improves
+ * testability, and prevents tight coupling.
+ *
+ * Detection is naming-based: interfaces and type aliases whose names end with
+ * "Dependencies" or "Deps" are flagged regardless of their contents.
+ *
+ * ❌ FORBIDDEN (ANY "*Dependencies" or "*Deps" naming):
+ * ```typescript
+ * // Wrong: Even ONE service wrapped is bad
+ * interface AuthDependencies {
+ *   apiKeyService: ApiKeyService;
+ * }
+ * function initializeAuth(deps: AuthDependencies) {
+ *   // Creates indirection, hides dependency
+ * }
+ *
+ * // Wrong: Multiple services bundled
+ * interface ServiceDeps {
+ *   logger: Logger;
+ *   database: Database;
+ *   cache: Cache;
+ * }
+ * class MyService {
+ *   constructor(private deps: ServiceDeps) {
+ *     // Tight coupling to the bundle structure
+ *   }
+ * }
+ * ```
+ *
+ * ✅ CORRECT (direct parameter injection):
+ * ```typescript
+ * // Right: Direct parameter
+ * function initializeAuth(apiKeyService: ApiKeyService) {
+ *   // Dependency is explicit and visible
+ * }
+ *
+ * // Right: Individual injection
+ * class MyService {
+ *   constructor(
+ *     private readonly logger: Logger,
+ *     private readonly database: Database,
+ *     private readonly cache: Cache,
+ *   ) {
+ *     // Each dependency is explicit and independently injectable
+ *   }
+ * }
+ * ```
+ *
+ * **Why this matters**:
+ * - Bundling hides which dependencies are actually used
+ * - Makes mocking harder (must mock entire bundle)
+ * - Creates coupling to the bundle structure
+ * - Prevents partial initialization for testing
+ * - Use naming like "*Config" or "*Options" for true configuration data (not services)
+ */
+export declare const noDependencyBundlingRule: ESLintUtils.RuleModule<"dependencyBundle", [{
+    docBaseUrl: string;
+}], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};
+/**
+ * Custom ESLint rule that prevents creating service dependencies inside constructors
+ *
+ * This rule detects `new PascalCase()` expressions inside class constructors and
+ * reports them as violations, since services should receive dependencies via
+ * constructor parameters rather than creating them internally.
+ *
+ * **Exceptions**:
+ * - Built-in constructors (Map, Set, Date, Error, etc.) are allowed because
+ *   they are standard data structures, not service dependencies.
+ * - `new` expressions inside default parameter values (AssignmentPattern) are
+ *   allowed because the dependency CAN still be injected — the `new` only runs
+ *   when no argument is provided.
+ * @example
+ * ```typescript
+ * // ❌ FORBIDDEN: creating a dependency inside a constructor
+ * class UserService {
+ *   constructor(config: Config) {
+ *     this.db = new Database(config); // Violation
+ *   }
+ * }
+ *
+ * // ✅ CORRECT: built-in constructors are fine
+ * class CacheService {
+ *   constructor() {
+ *     this.cache = new Map();
+ *   }
+ * }
+ *
+ * // ✅ CORRECT: default parameter values are fine
+ * class UserService {
+ *   constructor(private db: Database = new Database()) {}
+ * }
+ * ```
+ */
+export declare const noConstructorInstantiationRule: ESLintUtils.RuleModule<"constructorInstantiation", [], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};
+/**
+ * Creates rules that prevent wrapping service dependencies in container objects
+ *
+ * Uses the `@reasonabletech/no-dependency-bundling` custom rule which detects
+ * naming patterns (*Dependencies, *Deps) on interfaces and type aliases.
+ * @param options Configuration options for architecture pattern rules
+ * @returns ESLint rules that prevent dependency bundling
+ */
+export declare function createDependencyBundlingRules(options?: ArchitecturePatternRuleOptions): Linter.RulesRecord;
+/**
+ * Creates rules that enforce dependency injection patterns
+ *
+ * These rules prevent services from creating their own dependencies
+ * or using singleton patterns, enforcing proper dependency injection.
+ *
+ * Uses `no-restricted-syntax` to ban `getInstance()` singletons and the
+ * `@reasonabletech/no-constructor-instantiation` custom rule to detect
+ * `new` expressions inside constructors (with built-in and default-param
+ * exceptions).
+ *
+ * ❌ FORBIDDEN:
+ * ```typescript
+ * export class UserService {
+ *   static getInstance() { return instance; } // Singleton
+ *
+ *   constructor(config: Config) {
+ *     this.db = new Database(config); // Creates own dependency
+ *   }
+ * }
+ * ```
+ *
+ * ✅ CORRECT:
+ * ```typescript
+ * export class UserService {
+ *   constructor(
+ *     private db: Database,     // Injected dependency
+ *     private config: Config,
+ *   ) {}
+ * }
+ * ```
+ * @param _options Configuration options for architecture pattern rules (reserved for future use)
+ * @returns ESLint rules that enforce dependency injection
+ */
+export declare function createDependencyInjectionRules(_options?: ArchitecturePatternRuleOptions): Linter.RulesRecord;
+/**
+ * Creates rules that enforce proper service architecture patterns
+ *
+ * Enforces patterns like:
+ * - Individual dependency injection (no god objects)
+ * - Required dependencies must be required constructor parameters
+ * - Services should accept dependencies, not create them
+ * @param options Configuration options for architecture pattern rules
+ * @returns ESLint rules that enforce service architecture patterns
+ */
+export declare function createServiceArchitectureRules(options?: ArchitecturePatternRuleOptions): Linter.RulesRecord;
+/**
+ * Creates a complete set of architecture pattern rules
+ *
+ * This is the main function that combines all architecture pattern rules
+ * into a single configuration object.
+ * @param options Configuration options for architecture pattern rules
+ * @returns Complete set of architecture pattern ESLint rules
+ */
+export declare function createArchitecturePatternRules(options?: ArchitecturePatternRuleOptions): Linter.RulesRecord;
+/**
+ * Preset for platform architecture pattern rules
+ * @returns ESLint rules configured for platform projects
+ */
+export declare function createPlatformArchitecturePatternRules(): Linter.RulesRecord;
+//# sourceMappingURL=architecture-patterns.d.ts.map