🤖 Add ESLint rule to enforce absolute imports with @/ alias

[ammario]

Summary

Adds ESLint rule that enforces absolute imports with @/ alias for cross-directory imports while allowing pragmatic same-directory relative imports.

Changes

ESLint Configuration

Added no-restricted-imports rule to eslint.config.mjs:

• Blocks: ../*, ../../*, ../../../* (parent directory imports)
• Allows: ./foo (same-directory imports)
• Requires: @/types/foo (absolute imports for cross-directory)

Documentation

Updated CLAUDE.md with import guidelines explaining:

• When to use absolute imports
• When same-directory imports are acceptable
• Why this improves maintainability

What Gets Enforced

❌ Blocked (will fail ESLint):

import { foo } from "../types/foo";           // Use @/types/foo
import { bar } from "../../services/bar";     // Use @/services/bar

✅ Allowed:

import { helper } from "./helper";            // Same directory - OK
import { CmuxMessage } from "@/types/message"; // Absolute - required

Benefits

• Prevents regression: Can't accidentally add relative imports
• Immediate feedback: ESLint catches violations during development
• CI enforcement: Violations block PR merges
• Pragmatic: Allows same-directory imports for better code organization
• Consistency: Entire codebase follows the same pattern

Rationale for Same-Directory Exception

1. Cognitive simplicity: ./foo is clearer than @/utils/tokens/foo when already in utils/tokens/
2. File organization: Same-directory files are closely related
3. Refactoring: Moving directories is easier with internal relative imports
4. Industry practice: Common in large React codebases (Next.js, etc.)

Testing

• ✅ Rule is active and catches violations (tested on current codebase)
• ✅ Same-directory imports pass
• ✅ Cross-directory imports must use @/

Note

This rule will catch existing violations in files not yet converted to absolute imports. Those files will need to be updated in PR #34 or future PRs.

Generated with cmux