@reasonabletech/eslint-config 0.1.0

package/dist/src/custom-rules/error-handling.js

@@ -0,0 +1,349 @@
+/**
+ * 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 { AST_NODE_TYPES, ESLintUtils, } from "@typescript-eslint/utils";
+import { mergeRuleConfigurations } from "./utils.js";
+/**
+ * Default configuration for ReasonableTech error handling rules
+ */
+const DEFAULT_OPTIONS = {
+    docBaseUrl: "docs/standards/error-handling.md",
+    errorTypePattern: ".*Error$",
+    resultTypeName: "Result",
+    requireErrorTypeJSDoc: true,
+};
+/** Set of string methods that are forbidden on `.message` properties */
+const MESSAGE_STRING_METHODS = new Set([
+    "includes",
+    "startsWith",
+    "endsWith",
+    "match",
+]);
+/**
+ * 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 const noErrorMessageParsingRule = ESLintUtils.RuleCreator(() => "docs/standards/error-handling.md")({
+    name: "no-error-message-parsing",
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Prevents parsing error messages with string methods or direct comparisons",
+        },
+        messages: {
+            stringMethod: "Never parse error messages with .{{method}}(). Use error.code, error.status, or instanceof checks instead.",
+            directComparison: "Never compare error messages directly. Use error.code, error.status, or instanceof checks instead.",
+            regexTest: "Never use regex test on error messages. Use error.code, error.status, or instanceof checks instead.",
+        },
+        schema: [],
+    },
+    defaultOptions: [],
+    create(context) {
+        /**
+         * Checks if a MemberExpression's object ends with `.message`
+         * (i.e. `<something>.message`).
+         * @param node The member expression node to check
+         * @returns Whether the node accesses a `.message` property
+         */
+        function isMessageAccess(node) {
+            return (node.property.type === AST_NODE_TYPES.Identifier &&
+                node.property.name === "message");
+        }
+        return {
+            // Detect: error.message.includes/startsWith/endsWith/match(...)
+            CallExpression(node) {
+                if (node.callee.type !== AST_NODE_TYPES.MemberExpression) {
+                    return;
+                }
+                const callee = node.callee;
+                const methodName = callee.property.type === AST_NODE_TYPES.Identifier
+                    ? callee.property.name
+                    : null;
+                if (methodName === null) {
+                    return;
+                }
+                // Case 1: error.message.<method>(...)
+                if (MESSAGE_STRING_METHODS.has(methodName) &&
+                    callee.object.type === AST_NODE_TYPES.MemberExpression &&
+                    isMessageAccess(callee.object)) {
+                    context.report({
+                        node,
+                        messageId: "stringMethod",
+                        data: { method: methodName },
+                    });
+                    return;
+                }
+                // Case 2: /regex/.test(error.message) — callee is regex.test,
+                // and the first argument is a `.message` member expression
+                if (methodName === "test" &&
+                    node.arguments.length > 0 &&
+                    node.arguments[0].type === AST_NODE_TYPES.MemberExpression &&
+                    isMessageAccess(node.arguments[0])) {
+                    context.report({ node, messageId: "regexTest" });
+                }
+            },
+            // Detect: error.message === "..." / error.message == "..."
+            BinaryExpression(node) {
+                if (node.operator !== "===" && node.operator !== "==") {
+                    return;
+                }
+                if (node.left.type === AST_NODE_TYPES.MemberExpression &&
+                    isMessageAccess(node.left)) {
+                    context.report({ node, messageId: "directComparison" });
+                }
+            },
+        };
+    },
+});
+/**
+ * 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 function createErrorMessageParsingRules(_options = {}) {
+    return {
+        "@reasonabletech/no-error-message-parsing": "error",
+    };
+}
+/**
+ * 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 function createErrorTypeDocumentationRules(options = {}) {
+    const config = { ...DEFAULT_OPTIONS, ...options };
+    if (!config.requireErrorTypeJSDoc) {
+        return {};
+    }
+    return {
+        "jsdoc/require-jsdoc": [
+            "error",
+            {
+                require: {
+                    FunctionDeclaration: false,
+                    MethodDefinition: false,
+                    ClassDeclaration: false,
+                    ArrowFunctionExpression: false,
+                    FunctionExpression: false,
+                },
+                contexts: [
+                    // Enforce JSDoc on all exported type aliases that match the error pattern
+                    `ExportNamedDeclaration > TSTypeAliasDeclaration[id.name=/${config.errorTypePattern}/]`,
+                ],
+            },
+        ],
+    };
+}
+/**
+ * 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 function createErrorTypeNamingRules(options = {}) {
+    const config = { ...DEFAULT_OPTIONS, ...options };
+    return {
+        "@typescript-eslint/naming-convention": [
+            "error",
+            {
+                // Enforce PascalCase with "Error" suffix for error types
+                selector: "typeAlias",
+                filter: {
+                    regex: config.errorTypePattern,
+                    match: true,
+                },
+                format: ["PascalCase"],
+                suffix: ["Error"],
+            },
+        ],
+    };
+}
+/**
+ * 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 const noInlineErrorUnionsRule = ESLintUtils.RuleCreator(() => "docs/standards/error-handling.md")({
+    name: "no-inline-error-unions",
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Prevents inline error union types in Result type parameters",
+        },
+        messages: {
+            inlineUnion: "Never use inline error unions in {{typeName}} types. Extract to a documented named type.",
+        },
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    resultTypeName: { type: "string" },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [{ resultTypeName: "Result" }],
+    create(context) {
+        const resultTypeName = context.options[0].resultTypeName;
+        /**
+         * Checks if a TSUnionType contains at least one TSLiteralType member.
+         * @param union The union type node to inspect
+         * @returns Whether the union contains a literal type member
+         */
+        function hasLiteralMember(union) {
+            return union.types.some((t) => t.type === AST_NODE_TYPES.TSLiteralType);
+        }
+        /**
+         * Checks if a TSTypeReference refers to the configured Result type name.
+         * @param node The type reference node to check
+         * @returns Whether the node references the Result type
+         */
+        function isResultReference(node) {
+            return (node.typeName.type === AST_NODE_TYPES.Identifier &&
+                node.typeName.name === resultTypeName);
+        }
+        /**
+         * Walks TSUnionType nodes that are descendants of a given type parameter
+         * list, returning any that contain literal members.
+         * @param params The type parameter instantiation to search
+         * @returns Array of union type nodes containing literal members
+         */
+        function findInlineUnions(params) {
+            const results = [];
+            function walk(node) {
+                if (node.type === AST_NODE_TYPES.TSUnionType &&
+                    hasLiteralMember(node)) {
+                    results.push(node);
+                    return; // Don't recurse into nested unions of the same node
+                }
+                for (const key of Object.keys(node)) {
+                    if (key === "parent") {
+                        continue;
+                    }
+                    const value = node[key];
+                    if (Array.isArray(value)) {
+                        for (const item of value) {
+                            if (item !== null &&
+                                typeof item === "object" &&
+                                typeof item.type === "string") {
+                                walk(item);
+                            }
+                        }
+                    }
+                    else if (value !== null &&
+                        typeof value === "object" &&
+                        typeof value.type === "string") {
+                        walk(value);
+                    }
+                }
+            }
+            for (const param of params.params) {
+                walk(param);
+            }
+            return results;
+        }
+        return {
+            TSTypeReference(node) {
+                if (!isResultReference(node)) {
+                    return;
+                }
+                if (node.typeArguments === undefined) {
+                    return;
+                }
+                // Determine the display name: if the Result reference is nested inside
+                // a Promise<...>, display "Promise<Result<T, E>>".
+                let displayName = resultTypeName;
+                const parentRef = node.parent;
+                if (parentRef.type === AST_NODE_TYPES.TSTypeParameterInstantiation) {
+                    const grandparent = parentRef.parent;
+                    if (grandparent.type === AST_NODE_TYPES.TSTypeReference &&
+                        grandparent.typeName.type === AST_NODE_TYPES.Identifier &&
+                        grandparent.typeName.name === "Promise") {
+                        displayName = `Promise<${resultTypeName}<T, E>>`;
+                    }
+                }
+                const inlineUnions = findInlineUnions(node.typeArguments);
+                for (const union of inlineUnions) {
+                    context.report({
+                        node: union,
+                        messageId: "inlineUnion",
+                        data: { typeName: displayName },
+                    });
+                }
+            },
+        };
+    },
+});
+/**
+ * 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 function createInlineErrorUnionRules(options = {}) {
+    const config = { ...DEFAULT_OPTIONS, ...options };
+    return {
+        "@reasonabletech/no-inline-error-unions": [
+            "error",
+            {
+                resultTypeName: config.resultTypeName,
+            },
+        ],
+    };
+}
+/**
+ * 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 function createErrorHandlingRules(options = {}) {
+    const messageParsingRules = createErrorMessageParsingRules(options);
+    const documentationRules = createErrorTypeDocumentationRules(options);
+    const namingRules = createErrorTypeNamingRules(options);
+    const inlineUnionRules = createInlineErrorUnionRules(options);
+    return mergeRuleConfigurations(messageParsingRules, documentationRules, namingRules, inlineUnionRules);
+}
+/**
+ * Preset for Platform-specific error handling rules
+ * @returns ESLint rules configured for platform projects
+ */
+export function createPlatformErrorHandlingRules() {
+    return createErrorHandlingRules({
+        docBaseUrl: "docs/standards/error-handling.md",
+        errorTypePattern: ".*Error$",
+        resultTypeName: "Result",
+        requireErrorTypeJSDoc: true,
+    });
+}
+//# sourceMappingURL=error-handling.js.map

package/dist/src/custom-rules/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Custom ESLint rules for ReasonableTech projects
+ *
+ * This module provides a collection of reusable ESLint rule configurations
+ * designed to enforce best practices for TypeScript development, with a focus
+ * on type safety, error handling, and maintainable code patterns.
+ *
+ * The rules are designed to be:
+ * - Configurable for different project contexts
+ * - Reusable across different organizations and projects
+ * - Focused on preventing common bugs and anti-patterns
+ * - Easy to extract into a standalone ESLint plugin
+ * Main entry point for custom ESLint rules
+ */
+export { noErrorMessageParsingRule, noInlineErrorUnionsRule, createErrorHandlingRules, createErrorMessageParsingRules, createErrorTypeDocumentationRules, createErrorTypeNamingRules, createInlineErrorUnionRules, createPlatformErrorHandlingRules, type ErrorHandlingRuleOptions, } from "./error-handling.js";
+export { noNullUndefinedChecksRule, createNullUndefinedChecksRules, } from "./null-undefined-checks.js";
+export { createArchitecturePatternRules, createDependencyBundlingRules, createDependencyInjectionRules, createServiceArchitectureRules, createPlatformArchitecturePatternRules, noConstructorInstantiationRule, type ArchitecturePatternRuleOptions, } from "./architecture-patterns.js";
+export { noAsAnyRule, createNoAnyRules, createTypeSafetyRules, createPlatformTypeSafetyRules, type TypeSafetyRuleOptions, } from "./type-safety.js";
+export { noLinterDisablingRule, noBarrelExportsRule, createBarrelExportRules, createAsyncPatternRules, createTerminologyRules, createMagicNumbersRules, createCodeQualityRules, createPlatformCodeQualityRules, type NoLinterDisablingOptions, type TerminologyOptions, type MagicNumbersOptions, } from "./code-quality.js";
+export { createPlatformConventionRules, createResultHelperRules, createUIBarrelImportRules, createPlatformConventionPresetRules, type PlatformConventionRuleOptions, } from "./platform-conventions.js";
+export { createUILibraryImportRules, type UILibraryImportRuleOptions, } from "./ui-library-imports.js";
+export { createNoTypeofInExpectRules } from "./test-quality.js";
+export { mergeRuleConfigurations, createConditionalRules, createExportedTypeSelector, createTypeReferenceSelector, createResultInlineUnionSelector, createPromiseResultInlineUnionSelector, createDocReference, isRuleEnabled, AST_SELECTORS, ERROR_MESSAGES, type BaseRuleOptions, } from "./utils.js";
+import type { Linter } from "eslint";
+import { type ErrorHandlingRuleOptions } from "./error-handling.js";
+import { type ArchitecturePatternRuleOptions } from "./architecture-patterns.js";
+import { type TypeSafetyRuleOptions } from "./type-safety.js";
+/**
+ * Configuration options for all ReasonableTech custom rules
+ */
+export interface ReasonableTechRuleOptions {
+    /** Error handling rule options */
+    errorHandling?: Partial<ErrorHandlingRuleOptions>;
+    /** Architecture pattern rule options */
+    architecturePatterns?: Partial<ArchitecturePatternRuleOptions>;
+    /** Type safety rule options */
+    typeSafety?: Partial<TypeSafetyRuleOptions>;
+    /** Base URL for all documentation references */
+    docBaseUrl?: string;
+}
+/**
+ * Creates a complete set of ReasonableTech custom rules
+ *
+ * This function combines all available rule sets into a single configuration,
+ * making it easy to apply consistent standards across projects.
+ * @param options Configuration options for customizing rule behavior
+ * @returns Complete ESLint rule configuration
+ * @example
+ * ```typescript
+ * import { createReasonableTechRules } from './custom-rules';
+ *
+ * const rules = createReasonableTechRules({
+ *   docBaseUrl: 'docs/standards/',
+ *   errorHandling: {
+ *     resultTypeName: 'Result',
+ *     requireErrorTypeJSDoc: true,
+ *   },
+ * });
+ * ```
+ */
+export declare function createReasonableTechRules(options?: ReasonableTechRuleOptions): Linter.RulesRecord;
+/**
+ * Preset configuration for platform projects
+ *
+ * This preset provides all the custom rules configured specifically
+ * for platform project conventions and documentation structure.
+ * @returns ESLint rule configuration for platform projects
+ */
+export declare function createPlatformRulePreset(): Linter.RulesRecord;
+/**
+ * Preset configuration for generic ReasonableTech projects
+ *
+ * This preset provides sensible defaults that work well for most
+ * TypeScript projects following ReasonableTech conventions.
+ * @param docBaseUrl Base URL for documentation references
+ * @returns ESLint rule configuration for generic projects
+ */
+export declare function createGenericRulePreset(docBaseUrl?: string): Linter.RulesRecord;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/custom-rules/index.js

@@ -0,0 +1,119 @@
+/**
+ * Custom ESLint rules for ReasonableTech projects
+ *
+ * This module provides a collection of reusable ESLint rule configurations
+ * designed to enforce best practices for TypeScript development, with a focus
+ * on type safety, error handling, and maintainable code patterns.
+ *
+ * The rules are designed to be:
+ * - Configurable for different project contexts
+ * - Reusable across different organizations and projects
+ * - Focused on preventing common bugs and anti-patterns
+ * - Easy to extract into a standalone ESLint plugin
+ * Main entry point for custom ESLint rules
+ */
+// Re-export all error handling functionality
+export { noErrorMessageParsingRule, noInlineErrorUnionsRule, createErrorHandlingRules, createErrorMessageParsingRules, createErrorTypeDocumentationRules, createErrorTypeNamingRules, createInlineErrorUnionRules, createPlatformErrorHandlingRules, } from "./error-handling.js";
+// Re-export null/undefined checks rule
+export { noNullUndefinedChecksRule, createNullUndefinedChecksRules, } from "./null-undefined-checks.js";
+// Re-export architecture pattern rules
+export { createArchitecturePatternRules, createDependencyBundlingRules, createDependencyInjectionRules, createServiceArchitectureRules, createPlatformArchitecturePatternRules, noConstructorInstantiationRule, } from "./architecture-patterns.js";
+// Re-export type safety rules
+export { noAsAnyRule, createNoAnyRules, createTypeSafetyRules, createPlatformTypeSafetyRules, } from "./type-safety.js";
+// Re-export code quality rules
+export { noLinterDisablingRule, noBarrelExportsRule, createBarrelExportRules, createAsyncPatternRules, createTerminologyRules, createMagicNumbersRules, createCodeQualityRules, createPlatformCodeQualityRules, } from "./code-quality.js";
+// Re-export platform convention rules
+export { createPlatformConventionRules, createResultHelperRules, createUIBarrelImportRules, createPlatformConventionPresetRules, } from "./platform-conventions.js";
+// Re-export UI import boundary rules
+export { createUILibraryImportRules, } from "./ui-library-imports.js";
+// Re-export test quality rules
+export { createNoTypeofInExpectRules } from "./test-quality.js";
+// Re-export utilities
+export { mergeRuleConfigurations, createConditionalRules, createExportedTypeSelector, createTypeReferenceSelector, createResultInlineUnionSelector, createPromiseResultInlineUnionSelector, createDocReference, isRuleEnabled, AST_SELECTORS, ERROR_MESSAGES, } from "./utils.js";
+import { createErrorHandlingRules, } from "./error-handling.js";
+import { createArchitecturePatternRules, } from "./architecture-patterns.js";
+import { createTypeSafetyRules, } from "./type-safety.js";
+import { createCodeQualityRules } from "./code-quality.js";
+import { mergeRuleConfigurations } from "./utils.js";
+/**
+ * Creates a complete set of ReasonableTech custom rules
+ *
+ * This function combines all available rule sets into a single configuration,
+ * making it easy to apply consistent standards across projects.
+ * @param options Configuration options for customizing rule behavior
+ * @returns Complete ESLint rule configuration
+ * @example
+ * ```typescript
+ * import { createReasonableTechRules } from './custom-rules';
+ *
+ * const rules = createReasonableTechRules({
+ *   docBaseUrl: 'docs/standards/',
+ *   errorHandling: {
+ *     resultTypeName: 'Result',
+ *     requireErrorTypeJSDoc: true,
+ *   },
+ * });
+ * ```
+ */
+export function createReasonableTechRules(options = {}) {
+    const errorHandlingOptions = {
+        docBaseUrl: options.docBaseUrl ?? "docs/standards/error-handling.md",
+        ...options.errorHandling,
+    };
+    const architecturePatternOptions = {
+        docBaseUrl: options.docBaseUrl ?? "docs/standards/architecture-principles.md",
+        ...options.architecturePatterns,
+    };
+    const typeSafetyOptions = {
+        docBaseUrl: options.docBaseUrl ?? "docs/standards/typescript-standards.md",
+        ...options.typeSafety,
+    };
+    const errorHandlingRules = createErrorHandlingRules(errorHandlingOptions);
+    const architecturePatternRules = createArchitecturePatternRules(architecturePatternOptions);
+    const typeSafetyRules = createTypeSafetyRules(typeSafetyOptions);
+    const codeQualityRules = createCodeQualityRules();
+    return mergeRuleConfigurations(errorHandlingRules, architecturePatternRules, typeSafetyRules, codeQualityRules);
+}
+/**
+ * Preset configuration for platform projects
+ *
+ * This preset provides all the custom rules configured specifically
+ * for platform project conventions and documentation structure.
+ * @returns ESLint rule configuration for platform projects
+ */
+export function createPlatformRulePreset() {
+    return createReasonableTechRules({
+        docBaseUrl: "docs/standards/error-handling.md",
+        errorHandling: {
+            errorTypePattern: ".*Error$",
+            resultTypeName: "Result",
+            requireErrorTypeJSDoc: true,
+        },
+        architecturePatterns: {
+            enforceIndividualDependencies: true,
+        },
+        typeSafety: {
+            docBaseUrl: "docs/standards/typescript-standards.md",
+            allowInTests: false,
+        },
+    });
+}
+/**
+ * Preset configuration for generic ReasonableTech projects
+ *
+ * This preset provides sensible defaults that work well for most
+ * TypeScript projects following ReasonableTech conventions.
+ * @param docBaseUrl Base URL for documentation references
+ * @returns ESLint rule configuration for generic projects
+ */
+export function createGenericRulePreset(docBaseUrl = "docs/") {
+    return createReasonableTechRules({
+        docBaseUrl: `${docBaseUrl}error-handling.md`,
+        errorHandling: {
+            errorTypePattern: ".*Error$",
+            resultTypeName: "Result",
+            requireErrorTypeJSDoc: true,
+        },
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/src/custom-rules/null-undefined-checks.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Custom ESLint rule: no-null-undefined-checks
+ *
+ * Flags code that checks for both null and undefined on the same value,
+ * which indicates a type mismatch. null and undefined are different types
+ * in TypeScript, and you should only check for what's in your type union.
+ */
+import { ESLintUtils } from "@typescript-eslint/utils";
+/**
+ * Creates the no-null-undefined-checks rule
+ */
+export declare const noNullUndefinedChecksRule: ESLintUtils.RuleModule<"checksBoth", [], unknown, ESLintUtils.RuleListener> & {
+    name: string;
+};
+/**
+ * Creates the rule configuration for the null/undefined checks rule
+ * @returns ESLint rule configuration
+ */
+export declare function createNullUndefinedChecksRules(): Record<string, string>;
+//# sourceMappingURL=null-undefined-checks.d.ts.map