@reasonabletech/eslint-config 0.1.0

package/dist/src/custom-rules/code-quality.js

@@ -0,0 +1,388 @@
+/**
+ * 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 { mergeRuleConfigurations } from "./utils.js";
+/**
+ * Default options for no-linter-disabling rule
+ */
+const DEFAULT_LINTER_DISABLING_OPTIONS = {
+    allowInTests: true,
+    requireJustification: true,
+    allowedRules: [],
+    allowedPatterns: ["**/*.test.ts", "**/*.test.tsx", "**/tests/**"],
+};
+/**
+ * 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 const noLinterDisablingRule = ESLintUtils.RuleCreator(() => "docs/standards/typescript-standards.md")({
+    name: "no-linter-disabling",
+    meta: {
+        type: "problem",
+        deprecated: true,
+        docs: {
+            description: "Prevents disabling linter rules without proper justification. Deprecated: use ESLint's built-in reportUnusedDisableDirectives and the native -- reason syntax instead.",
+        },
+        messages: {
+            noDisable: "❌ FORBIDDEN: Disabling linter rules is not allowed. Fix the underlying issue instead.",
+            noJustification: "❌ REQUIRED: Linter rule disabling requires a justification comment (// Reason: <explanation>).",
+            specificRule: "❌ FORBIDDEN: Disabling '{{rule}}' is not allowed. Fix the issue instead.",
+        },
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    allowInTests: { type: "boolean" },
+                    requireJustification: { type: "boolean" },
+                    allowedRules: { type: "array", items: { type: "string" } },
+                    allowedPatterns: { type: "array", items: { type: "string" } },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [DEFAULT_LINTER_DISABLING_OPTIONS],
+    create(context) {
+        const options = {
+            ...DEFAULT_LINTER_DISABLING_OPTIONS,
+            ...context.options[0],
+        };
+        const filename = typeof context.getFilename ===
+            "function"
+            ? context.getFilename()
+            : (context.filename ?? "<input>");
+        const sourceCode = typeof context
+            .getSourceCode === "function"
+            ? context.getSourceCode()
+            : (context.sourceCode ??
+                null);
+        if (sourceCode == null) {
+            return {};
+        }
+        // Check if file matches allowed patterns (e.g., test files)
+        if (options.allowInTests === true &&
+            isTestFile(filename, options.allowedPatterns ?? [])) {
+            return {};
+        }
+        return {
+            Program() {
+                const comments = sourceCode.getAllComments();
+                for (const comment of comments) {
+                    const text = comment.value.trim();
+                    // Detect linter-disable directives
+                    if (text.includes("eslint-disable") ||
+                        text.includes("@ts-ignore") ||
+                        text.includes("@ts-nocheck")) {
+                        const disabledRule = extractDisabledRule(text);
+                        // Check if this specific rule is allowed
+                        if (disabledRule !== null &&
+                            disabledRule !== "" &&
+                            options.allowedRules?.includes(disabledRule) === true) {
+                            continue;
+                        }
+                        // Check for justification if required
+                        if (options.requireJustification === true) {
+                            const hasJustification = checkJustification(comments, comment);
+                            if (!hasJustification) {
+                                context.report({
+                                    loc: comment.loc,
+                                    messageId: "noJustification",
+                                });
+                                continue;
+                            }
+                            if (disabledRule !== null && disabledRule !== "") {
+                                context.report({
+                                    loc: comment.loc,
+                                    messageId: "specificRule",
+                                    data: { rule: disabledRule },
+                                });
+                            }
+                            else {
+                                context.report({
+                                    loc: comment.loc,
+                                    messageId: "noDisable",
+                                });
+                            }
+                            continue;
+                        }
+                        // Report the violation (only reached when requireJustification is false)
+                        if (disabledRule !== null && disabledRule !== "") {
+                            context.report({
+                                loc: comment.loc,
+                                messageId: "specificRule",
+                                data: { rule: disabledRule },
+                            });
+                        }
+                        else {
+                            context.report({
+                                loc: comment.loc,
+                                messageId: "noDisable",
+                            });
+                        }
+                    }
+                }
+            },
+        };
+    },
+});
+/**
+ * Checks if a filename matches test file patterns
+ * @param filename File path to check
+ * @param _patterns Optional glob patterns to match against (reserved for future use)
+ * @returns True if the file is a test file
+ */
+function isTestFile(filename, _patterns = []) {
+    return (filename.includes(".test.") ||
+        filename.includes(".spec.") ||
+        filename.includes("/tests/") ||
+        filename.includes("/__tests__/"));
+}
+/**
+ * Extracts the specific rule name from an eslint disable comment
+ * @param comment Comment text to parse
+ * @returns Rule name if found, null otherwise
+ */
+function extractDisabledRule(comment) {
+    const match = comment.match(/eslint-disable(?:-next-line)?\s+([a-z-/@]+)/i);
+    return match !== null ? match[1] : null;
+}
+/**
+ * Checks if a justification comment exists before a disable comment
+ * @param allComments All comments in the file
+ * @param disableComment The disable comment to check
+ * @returns True if a justification comment is found
+ */
+function checkJustification(allComments, disableComment) {
+    // Look for comments within 3 lines before the disable comment
+    const precedingComments = allComments.filter((c) => c.loc.end.line >= disableComment.loc.start.line - 3 &&
+        c.loc.end.line < disableComment.loc.start.line);
+    return precedingComments.some((c) => {
+        const trimmedValue = c.value.trim().toLowerCase();
+        return trimmedValue.startsWith("reason:");
+    });
+}
+/**
+ * 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 const noBarrelExportsRule = ESLintUtils.RuleCreator(() => "docs/standards/typescript-standards.md")({
+    name: "no-barrel-exports",
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Prevents 'export *' barrel exports that create bloated namespaces",
+        },
+        messages: {
+            barrelExport: "Never use 'export *' barrel exports. Use explicit named exports or import from specific modules.",
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+    create(context) {
+        return {
+            ExportAllDeclaration(node) {
+                context.report({
+                    node,
+                    messageId: "barrelExport",
+                });
+            },
+        };
+    },
+});
+/**
+ * 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 function createBarrelExportRules() {
+    return {
+        "@reasonabletech/no-barrel-exports": "error",
+    };
+}
+/**
+ * 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 function createAsyncPatternRules(_options = {}) {
+    return {
+        "@typescript-eslint/no-misused-promises": "error",
+        "@typescript-eslint/no-floating-promises": "error",
+        "@typescript-eslint/await-thenable": "error",
+        "@typescript-eslint/promise-function-async": "error",
+    };
+}
+/**
+ * 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 function createCodeQualityRules() {
+    const barrelExportRules = createBarrelExportRules();
+    const asyncPatternRules = createAsyncPatternRules();
+    return mergeRuleConfigurations(barrelExportRules, asyncPatternRules);
+}
+/**
+ * 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 function createTerminologyRules(options = {}) {
+    const forbiddenTerms = options.forbiddenTerms ?? {};
+    if (Object.keys(forbiddenTerms).length === 0) {
+        return {};
+    }
+    const patterns = Object.entries(forbiddenTerms).map(([forbidden, required]) => ({
+        selector: `Identifier[name='${forbidden}']`,
+        message: `❌ Use '${required}' instead of '${forbidden}' for platform consistency.`,
+    }));
+    return {
+        "no-restricted-syntax": ["warn", ...patterns],
+    };
+}
+/**
+ * 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 function createMagicNumbersRules(options = {}) {
+    const allowed = options.allowedNumbers ?? [-1, 0, 1, 2];
+    return {
+        "no-magic-numbers": [
+            "warn",
+            {
+                ignore: allowed,
+                ignoreArrayIndexes: true,
+                ignoreDefaultValues: true,
+                enforceConst: true,
+                detectObjects: false, // Don't flag object property values
+            },
+        ],
+    };
+}
+/**
+ * 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 function createPlatformCodeQualityRules() {
+    return createCodeQualityRules();
+}
+//# sourceMappingURL=code-quality.js.map

package/dist/src/custom-rules/error-handling.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Error handling rule definitions for ReasonableTech projects
+ *
+ * These rules enforce safe error handling patterns and prevent dangerous
+ * error message parsing. They are designed to be reusable across different
+ * projects with configurable documentation references.
+ */
+import { ESLintUtils } from "@typescript-eslint/utils";
+import type { Linter } from "eslint";
+/**
+ * Configuration options for error handling rules
+ */
+export interface ErrorHandlingRuleOptions {
+    /** Base URL for documentation references */
+    docBaseUrl?: string;
+    /** Pattern for error type names (default: ".*Error$") */
+    errorTypePattern?: string;
+    /** Name of Result type to check for inline unions (default: "Result") */
+    resultTypeName?: string;
+    /** Whether to require JSDoc on error types (default: true) */
+    requireErrorTypeJSDoc?: boolean;
+}
+/**
+ * Custom ESLint rule that prevents parsing error messages with string methods
+ *
+ * Detects the following patterns on any `.message` property:
+ * - `error.message.includes(...)` / `.startsWith(...)` / `.endsWith(...)` / `.match(...)`
+ * - `error.message === "..."` / `error.message == "..."`
+ * - `/.../\.test(error.message)`
+ *
+ * All of these are fragile because error messages are not part of a stable API
+ * and may change without notice. Use `error.code`, `error.status`, or
+ * `instanceof` checks instead.
+ */
+export declare const noErrorMessageParsingRule: ESLintUtils.RuleModule<"stringMethod" | "directComparison" | "regexTest", [], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};
+/**
+ * Creates rules that prevent dangerous error message parsing patterns
+ *
+ * These rules block the use of string methods on error.message properties,
+ * enforcing the use of structured error detection instead.
+ * @param _options Configuration options for error handling rules (reserved for future use)
+ * @returns ESLint rules that prevent error message parsing
+ */
+export declare function createErrorMessageParsingRules(_options?: ErrorHandlingRuleOptions): Linter.RulesRecord;
+/**
+ * Creates rules that enforce JSDoc documentation on error types
+ *
+ * Requires comprehensive documentation on all exported error type aliases
+ * to ensure error codes are properly documented and understood.
+ * @param options Configuration options for error handling rules
+ * @returns ESLint rules that enforce JSDoc documentation on error types
+ */
+export declare function createErrorTypeDocumentationRules(options?: ErrorHandlingRuleOptions): Linter.RulesRecord;
+/**
+ * Creates rules that enforce consistent error type naming conventions
+ *
+ * Enforces PascalCase with "Error" suffix for error types and
+ * lowercase_with_underscores for error code literals.
+ * @param options Configuration options for error handling rules
+ * @returns ESLint rules that enforce consistent error type naming
+ */
+export declare function createErrorTypeNamingRules(options?: ErrorHandlingRuleOptions): Linter.RulesRecord;
+/**
+ * Custom ESLint rule that prevents inline error union types in Result types
+ *
+ * Detects inline union types (containing literal members) used as type
+ * arguments in `Result<T, E>` and `Promise<Result<T, E>>` type references.
+ * These should be extracted to documented named types for maintainability.
+ *
+ * ❌ `Result<User, "not_found" | "forbidden">`
+ * ✅ `Result<User, GetUserError>` where `GetUserError` is a named type
+ */
+export declare const noInlineErrorUnionsRule: ESLintUtils.RuleModule<"inlineUnion", [{
+    resultTypeName: string;
+}], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};
+/**
+ * Creates rules that detect inline error unions in Result types
+ *
+ * Prevents the use of inline union types in Result<T, E> signatures,
+ * enforcing extraction to documented named types.
+ * @param options Configuration options for error handling rules
+ * @returns ESLint rules that detect inline error unions in Result types
+ */
+export declare function createInlineErrorUnionRules(options?: ErrorHandlingRuleOptions): Linter.RulesRecord;
+/**
+ * Creates a complete set of error handling rules with all components
+ *
+ * This is the main function that combines all error handling rules
+ * into a single configuration object.
+ * @param options Configuration options for error handling rules
+ * @returns Complete set of error handling ESLint rules
+ */
+export declare function createErrorHandlingRules(options?: ErrorHandlingRuleOptions): Linter.RulesRecord;
+/**
+ * Preset for Platform-specific error handling rules
+ * @returns ESLint rules configured for platform projects
+ */
+export declare function createPlatformErrorHandlingRules(): Linter.RulesRecord;
+//# sourceMappingURL=error-handling.d.ts.map