expert-code-refactoring

1. Analyze Context: Read the file and its associated tests. Identify dependencies and usage patterns.
2. Verify Tests: Before any changes, run existing tests to ensure a stable baseline.
3. Identify Smells: Look for long methods, deep nesting, duplicate code, or tight coupling.
4. Incremental Changes: Apply transformations in small, verifiable steps.
5. Re-verify: Run tests after each significant change.

• Naming: Rename variables, functions, and classes to be descriptive and reveal intent. Avoid abbreviations.
• AHA Programming: Avoid Hasty Abstractions. Only abstract code when the duplication is clear and the abstraction doesn't make the code harder to follow.
• Functions: Keep functions small. Aim for a low number of parameters (prefer objects/records for many parameters).
• Cognitive Load: Reduce nesting levels (aim for max 2-3 deep). Use early returns to keep the "happy path" aligned to the left.

• Dependency Injection (DI): Replace hardcoded instances or static calls with injected dependencies (via constructor or parameters).
• Interface Segregation: If a class depends on a large interface but only uses one method, extract a smaller interface.
• Pure Functions: Extract business logic into pure functions that don't depend on external state or side effects, making them trivial to unit test.
• Mocking Boundaries: Identify "seams" where you can inject mocks (e.g., Database, Network, System Clock).

• Characterization Tests: If tests are missing, write "Golden Master" tests that record the current behavior before changing it.
• Sprout Method: When adding a feature to a messy method, write the new logic in a new, clean method and call it from the old one.
• Wrap Method: Add new behavior by creating a new method with the same signature that calls the old method and then adds the new logic.
• Break Dependencies: Use the "Extract and Override" pattern to isolate untestable static calls or constructors in a protected method that can be overridden in a test subclass.

| Smell | Description | Refactoring Pattern |

| :--- | :--- | :--- |

| Magic Literals | Hardcoded numbers/strings. | Extract Constant or Enum. |

| Long Method | Method does too many things. | Extract Method. |

| Large Class | Too many responsibilities. | Extract Class or Extract Interface. |

| Feature Envy | Method uses another object's data more. | Move Method. |

| Primitive Obsession | Using primitives for domain concepts. | Introduce Value Object. |

| Multi‑File Change Requirement | One change affects many files. | Move Field or Inline Class to centralize. |

Java

• SOLID & Modern Features: Use record (Java 14+), sealed classes (Java 17+), and Switch Pattern Matching.
• Streams & Optional: Replace imperative loops with Stream. Use Optional to eliminate null checks.
• Immutability: Use final and immutable collections (List.of, Map.of).
• Exception Handling: Use try-with-resources. Avoid catching Throwable or Exception generically.

JavaScript / TypeScript

• Modern Syntax: const by default, destructuring, spread/rest, arrow functions.
• TypeScript Advanced: Discriminated Unions, Utility Types (Pick, Omit), and Custom Type Guards.
• Data Integrity: Use Zod or similar for runtime validation at API/IO boundaries.
• Async Patterns: Prefer Promise.all for concurrency; avoid "async-await" inside loops where possible.

React

• Component Design: Decompose large components. Extract logic into Custom Hooks.
• State Management: Principle of Least Privilege (keep state local). Avoid Prop Drilling with Context or Composition.
• Performance: Use useMemo/useCallback for stable references. Avoid inline function definitions in props of memoized children.
• Testing: Focus on user behavior and accessible roles (getByRole) via React Testing Library.

• Input Validation: Sanitize and validate all external input.
• Secrets: Never hardcode keys; use environment variables.
• Dependencies: Update deprecated/vulnerable packages discovered during refactoring.

• Never change external APIs or public interfaces without explicit user permission.
• Always maintain or improve test coverage.
• Adhere to the project's existing linting and formatting rules.