Refactoring ("Then Make it Right")

Refactoring is the disciplined process of changing internal code structure without changing its external observable behavior. It follows the Red $\to$ Green minimal implementation ("Make it Work") to ensure code health, architectural integrity, and long-term maintainability across any programming language.

The Core Rule

1. Pin what the code does. Ensure existing tests (or characterization tests) cover the current behavior.
2. Change the structure. Refactor code toward cleaner abstractions, lower complexity, and single responsibility.
3. Prove the behavior did not change. All tests must stay green. A failing test during refactoring is a regression, not progress.

The Three Automated Quality Gates

To prevent subjective or superficial refactoring, enforce the three automated quality gates using the native tools of the target project's ecosystem:

1. risk-gate (Complexity & CRAP Score)

• Rule: Reduce each function under CRAP 10 by splitting it, by testing it, or both. Consider whether case statements are worth reducing.
• The Formula: $\text{CRAP} = \text{CC}^2 \times (1 - \text{coverage})^3 + \text{CC}$.
  • If Cyclomatic Complexity ($\text{CC}$) is $\ge 10$, the function will fail even with 100% test coverage—it must be decomposed.

2. clone-check (Structural Duplication)

• Rule: Eliminate structural duplication that ranks 0.8 or above (or $\ge 80%$).
• Extract repeated logic, algorithmic patterns, or mirrored workflows into clean, reusable functions or shared classes.

3. mutant-gate (Mutation Testing)

• Rule: Cover the uncovered. Kill the survivors. Delete dead code.
• Injects programmatic mutations (inverting comparison operators, arithmetic, or booleans) to verify that tests actually assert behavior.
  • Killed mutant: Test suite fails (Good—test verified behavior).
  • Surviving mutant: Test suite passes (Bad—weak assertion or dead code).

Native Tooling Matrix by Language

Execute the corresponding native CLI tool for the project being refactored:

Architectural Disciplines

Refactoring must drive the code toward the following architectural standards:

Model the Domain

• Put the domain in a structure that makes illegal states impossible to represent.
• Maintain a glossary of domain terms in documentation or domain models.
• If existing code is already clear and local, leave it alone.

Boundary Discipline

• Check data where it enters the system boundaries.
• Inside system boundaries, trust it.
• Keep business logic in pure, deterministic functions without side-effects.

Type System Discipline

• Make the illegal value impossible to write.
• Parse outside data once, where it comes in (parse, don't validate).
• Do not silence compiler, type-checker, or linter warnings with suppressions.

Make Operations Idempotent

• Ensure running an operation twice, or running it after a crash halfway through, results in the exact same state.

Separate Before Serializing Shared State

• If two components do not need the same mutable state, give each its own.
• If they do need shared state, allow only one writer, and enforce that single writer strictly in the structure.

Step-by-Step Refactoring Workflow

1. Verify Baseline Tests: Run the project's test suite. Ensure all tests pass. If tests do not exist for the code being refactored, write characterization tests to lock in current behavior before touching code.
2. Run Quality Gates: Execute the ecosystem's risk-gate and clone-check commands to identify high-risk functions ($\text{CRAP} \ge 10$) and structural duplicates ($\ge 0.8$).
3. Execute Surgical Refactorings:
   • Split complex methods into cohesive pure helper functions.
   • Eliminate duplication by extracting shared logic.
   • Apply domain and type system discipline.
4. Run mutant-gate: Verify that the refactored code and tests leave zero surviving mutants.
5. Prove Invariance: Run the full test suite and confirm 100% pass rate.