@reasonabletech/eslint-config 0.1.0

package/dist/src/custom-rules/architecture-patterns.js

@@ -0,0 +1,344 @@
+/**
+ * Architecture pattern rules for the platform
+ *
+ * These rules enforce architectural best practices and prevent common
+ * anti-patterns in service design and dependency injection.
+ */
+import { AST_NODE_TYPES, ESLintUtils, } from "@typescript-eslint/utils";
+import { mergeRuleConfigurations } from "./utils.js";
+/**
+ * Built-in constructor names that are safe to use inside constructors
+ *
+ * These are standard JavaScript/Web API data structures and value types
+ * that do not represent service dependencies and therefore do not need
+ * to be injected.
+ */
+const BUILTIN_CONSTRUCTORS = new Set([
+    "Map",
+    "Set",
+    "Date",
+    "Error",
+    "URL",
+    "RegExp",
+    "WeakMap",
+    "WeakSet",
+    "Promise",
+    "Array",
+    "Object",
+    "Headers",
+    "Request",
+    "Response",
+    "FormData",
+    "Blob",
+    "AbortController",
+    "URLSearchParams",
+    "TextEncoder",
+    "TextDecoder",
+]);
+/**
+ * Default configuration for architecture pattern rules
+ */
+const DEFAULT_OPTIONS = {
+    docBaseUrl: "docs/standards/architecture-principles.md",
+    enforceIndividualDependencies: true,
+};
+/**
+ * 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 const noDependencyBundlingRule = ESLintUtils.RuleCreator(() => "docs/standards/architecture-principles.md")({
+    name: "no-dependency-bundling",
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Prevents wrapping service dependencies in container objects (ANY count)",
+        },
+        messages: {
+            dependencyBundle: "❌ FORBIDDEN: Never create '{{name}}' interfaces. The pattern itself is wrong - inject dependencies as direct constructor parameters, not wrapped in objects. Use '*Config' or '*Options' for true configuration data (not services).",
+        },
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    docBaseUrl: {
+                        type: "string",
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [
+        {
+            docBaseUrl: "docs/standards/architecture-principles.md",
+        },
+    ],
+    create(context) {
+        return {
+            TSInterfaceDeclaration(node) {
+                const name = node.id.name;
+                // Naming-based check: interfaces ending with "Dependencies" or "Deps"
+                if (name.endsWith("Dependencies") || name.endsWith("Deps")) {
+                    context.report({
+                        node: node.id,
+                        messageId: "dependencyBundle",
+                        data: { name },
+                    });
+                }
+            },
+            TSTypeAliasDeclaration(node) {
+                const name = node.id.name;
+                // Check type aliases ending with "Dependencies" or "Deps"
+                if (name.endsWith("Dependencies") || name.endsWith("Deps")) {
+                    context.report({
+                        node: node.id,
+                        messageId: "dependencyBundle",
+                        data: { name },
+                    });
+                }
+            },
+        };
+    },
+});
+/**
+ * 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 const noConstructorInstantiationRule = ESLintUtils.RuleCreator(() => "docs/standards/architecture-principles.md")({
+    name: "no-constructor-instantiation",
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Prevents creating service dependencies inside constructors instead of injecting them",
+        },
+        messages: {
+            constructorInstantiation: "Services should not create dependencies in constructor. Inject them via constructor parameters instead. Use default parameter values (e.g., `db: Database = new Database()`) if you need a default implementation.",
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+    create(context) {
+        return {
+            NewExpression(node) {
+                const ancestors = context.sourceCode.getAncestors(node);
+                // Check if we are inside a constructor MethodDefinition
+                const constructorIndex = ancestors.findIndex((ancestor) => ancestor.type === AST_NODE_TYPES.MethodDefinition &&
+                    ancestor.kind === "constructor");
+                if (constructorIndex === -1) {
+                    return;
+                }
+                // Check if the callee is a built-in constructor
+                if (node.callee.type === AST_NODE_TYPES.Identifier &&
+                    BUILTIN_CONSTRUCTORS.has(node.callee.name)) {
+                    return;
+                }
+                // Check if the NewExpression is inside an AssignmentPattern (default param)
+                const ancestorsAfterConstructor = ancestors.slice(constructorIndex + 1);
+                const isInDefaultParam = ancestorsAfterConstructor.some((ancestor) => ancestor.type === AST_NODE_TYPES.AssignmentPattern);
+                if (isInDefaultParam) {
+                    return;
+                }
+                context.report({
+                    node,
+                    messageId: "constructorInstantiation",
+                });
+            },
+        };
+    },
+});
+/**
+ * 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 function createDependencyBundlingRules(options = {}) {
+    const config = { ...DEFAULT_OPTIONS, ...options };
+    if (!config.enforceIndividualDependencies) {
+        return {};
+    }
+    return {
+        "@reasonabletech/no-dependency-bundling": [
+            "error",
+            {
+                docBaseUrl: config.docBaseUrl,
+            },
+        ],
+    };
+}
+/**
+ * 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 function createDependencyInjectionRules(_options = {}) {
+    return {
+        "no-restricted-syntax": [
+            "error",
+            {
+                selector: "MethodDefinition[static=true][key.name='getInstance']",
+                message: `❌ FORBIDDEN: Never use singleton pattern with getInstance(). Use dependency injection instead.`,
+            },
+        ],
+        "@reasonabletech/no-constructor-instantiation": "error",
+    };
+}
+/**
+ * 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 function createServiceArchitectureRules(options = {}) {
+    const dependencyInjectionRules = createDependencyInjectionRules(options);
+    return mergeRuleConfigurations(dependencyInjectionRules);
+}
+/**
+ * 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 function createArchitecturePatternRules(options = {}) {
+    const dependencyBundlingRules = createDependencyBundlingRules(options);
+    const serviceArchitectureRules = createServiceArchitectureRules(options);
+    return mergeRuleConfigurations(dependencyBundlingRules, serviceArchitectureRules);
+}
+/**
+ * Preset for platform architecture pattern rules
+ * @returns ESLint rules configured for platform projects
+ */
+export function createPlatformArchitecturePatternRules() {
+    return createArchitecturePatternRules({
+        docBaseUrl: "docs/standards/architecture-principles.md",
+        enforceIndividualDependencies: true,
+    });
+}
+//# sourceMappingURL=architecture-patterns.js.map

package/dist/src/custom-rules/code-quality.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Code quality rule definitions for ReasonableTech projects
+ *
+ * These rules prevent technical debt accumulation by detecting patterns
+ * that bypass code quality tools or create maintainability issues.
+ */
+import { ESLintUtils } from "@typescript-eslint/utils";
+import type { Linter } from "eslint";
+/**
+ * Configuration options for linter disabling detection
+ */
+export interface NoLinterDisablingOptions {
+    /** Whether to allow disabling linters in test files (default: true) */
+    allowInTests?: boolean;
+    /** Whether to require justification comments (default: true) */
+    requireJustification?: boolean;
+    /** List of rules that are allowed to be disabled (default: []) */
+    allowedRules?: string[];
+    /** Glob patterns for files where disabling is allowed (default: test patterns) */
+    allowedPatterns?: string[];
+}
+/**
+ * Custom ESLint rule that prevents disabling linter rules without justification
+ *
+ * This rule detects and blocks the use of:
+ * - `eslint disable` comments
+ * - TypeScript ignore directives (for example, `ts-ignore`)
+ * - TypeScript no-check directives (for example, `ts-nocheck`)
+ *
+ * Unless:
+ * - The file matches allowed patterns (e.g., test files)
+ * - A justification comment is provided (// Reason: ...)
+ * - The specific rule is in the allowed list
+ *
+ * ❌ FORBIDDEN:
+ * ```typescript
+ * /* eslint disable *\/ // No justification
+ * // `@ts ignore` // No justification
+ * ```
+ *
+ * ✅ CORRECT:
+ * ```typescript
+ * // Reason: Testing error message parsing - legitimate use case
+ * /* eslint disable no-restricted-syntax *\/
+ * const hasMatch = items.some(x => x.message?.includes("pattern"));
+ * /* eslint enable no-restricted-syntax *\/
+ * ```
+ */
+export declare const noLinterDisablingRule: ESLintUtils.RuleModule<"noDisable" | "noJustification" | "specificRule", [NoLinterDisablingOptions], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};
+/**
+ * Custom ESLint rule that prevents barrel exports (`export *`)
+ *
+ * Barrel exports create bloated namespaces and make it harder to track
+ * what's exported from a module. This rule flags all `export * from "..."`
+ * declarations, enforcing explicit named exports instead.
+ *
+ * ❌ `export * from "./user-service";`
+ * ✅ `export { UserService, type CreateUserError } from "./user-service";`
+ */
+export declare const noBarrelExportsRule: ESLintUtils.RuleModule<"barrelExport", [], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};
+/**
+ * Creates rules for detecting barrel exports (export *)
+ *
+ * These rules prevent the use of `export *` patterns, which create
+ * bloated namespaces and make it harder to track what's exported.
+ *
+ * ❌ FORBIDDEN:
+ * ```typescript
+ * export * from "./user-service"; // Exports all 30 items
+ * export * from "./workspace-service"; // Exports all 25 items
+ * ```
+ *
+ * ✅ CORRECT:
+ * ```typescript
+ * // Import directly from implementation
+ * import { UserService } from "@reasonabletech/platform/user-service";
+ *
+ * // Or use explicit named exports
+ * export { UserService, type CreateUserError } from "./user-service";
+ * ```
+ * @returns ESLint rules that prevent barrel exports
+ */
+export declare function createBarrelExportRules(): Linter.RulesRecord;
+/**
+ * Creates rules preventing mixed async/await and Promise patterns
+ *
+ * These rules prevent mixing `.then()` chains with `async/await` in
+ * the same function, enforcing consistent async patterns.
+ *
+ * ❌ FORBIDDEN:
+ * ```typescript
+ * async function fetchAndProcess() {
+ *   const user = await getUser();  // async/await
+ *   return saveUser(user)
+ *     .then(result => result);     // .then() chain
+ * }
+ * ```
+ *
+ * ✅ CORRECT:
+ * ```typescript
+ * async function fetchAndProcess() {
+ *   const user = await getUser();
+ *   const result = await saveUser(user);
+ *   return result;
+ * }
+ * ```
+ * @param _options Configuration options (reserved for future use)
+ * @returns ESLint rules preventing mixed async patterns
+ */
+export declare function createAsyncPatternRules(_options?: Record<string, never>): Linter.RulesRecord;
+/**
+ * Creates rules for enforcing code quality standards
+ *
+ * This function combines multiple code quality rules including:
+ * - no-barrel-exports (prevents bloated namespaces)
+ * - async pattern consistency (prevents mixing await and .then())
+ * @returns Complete set of code quality ESLint rules
+ */
+export declare function createCodeQualityRules(): Linter.RulesRecord;
+/**
+ * Configuration options for terminology enforcement
+ */
+export interface TerminologyOptions {
+    /** Map of forbidden terms to preferred terms */
+    forbiddenTerms?: Record<string, string>;
+}
+/**
+ * Creates rules for enforcing platform-specific terminology
+ *
+ * Enforces consistent terminology across the codebase to prevent confusion
+ * and maintain clear communication patterns.
+ *
+ * ❌ FORBIDDEN:
+ * ```typescript
+ * interface ActionSchema {
+ *   toolCall: string;  // Wrong terminology
+ * }
+ * ```
+ *
+ * ✅ CORRECT:
+ * ```typescript
+ * interface ActionSchema {
+ *   action: string;  // Correct platform terminology
+ * }
+ * ```
+ * @param options Configuration options for terminology rules
+ * @param options.forbiddenTerms Map of forbidden terms to preferred alternatives
+ * @returns ESLint rules enforcing terminology standards
+ */
+export declare function createTerminologyRules(options?: TerminologyOptions): Linter.RulesRecord;
+/**
+ * Configuration options for magic numbers detection
+ */
+export interface MagicNumbersOptions {
+    /** Numbers that are allowed without constants (default: [-1, 0, 1, 2]) */
+    allowedNumbers?: number[];
+    /** File patterns where magic numbers are allowed */
+    allowedPatterns?: string[];
+}
+/**
+ * Creates rules for detecting magic numbers and strings
+ *
+ * Prevents hardcoded values that should be extracted to named constants,
+ * improving maintainability and reducing duplication.
+ *
+ * ❌ FORBIDDEN:
+ * ```typescript
+ * const client = http.createClient("https://api.example.com/v1");  // Hardcoded URL
+ * setTimeout(() => retry(), 5000);  // Magic timeout
+ * if (retryCount > 3) { ... }       // Magic retry limit
+ * ```
+ *
+ * ✅ CORRECT:
+ * ```typescript
+ * const API_ENDPOINT = "https://api.example.com/v1";
+ * const RETRY_DELAY_MS = 5000;
+ * const MAX_RETRIES = 3;
+ *
+ * const client = http.createClient(API_ENDPOINT);
+ * setTimeout(() => retry(), RETRY_DELAY_MS);
+ * if (retryCount > MAX_RETRIES) { ... }
+ * ```
+ * @param options Configuration options for magic numbers detection
+ * @param options.allowedNumbers Numbers that don't require constants
+ * @param options.allowedPatterns File patterns where magic numbers are allowed
+ * @returns ESLint rules detecting magic numbers
+ */
+export declare function createMagicNumbersRules(options?: MagicNumbersOptions): Linter.RulesRecord;
+/**
+ * Preset for platform code quality rules
+ *
+ * This preset provides all code quality rules configured specifically
+ * for platform project conventions.
+ * @returns ESLint rules configured for platform projects
+ */
+export declare function createPlatformCodeQualityRules(): Linter.RulesRecord;
+//# sourceMappingURL=code-quality.d.ts.map