Core moves under green

Refactoring is behavior-preserving by definition — if observable behavior changed, it was not a refactor. The word has a precise meaning: a change to the internal structure of code that does not alter its external behavior. Same inputs, same outputs, same side effects, same errors. That is not a nice-to-have property you try to keep; it is the definition. The instant a “refactor” also fixes a bug or adds a feature, it has stopped being a refactor and become two changes wearing one name.

This precision is what lets the test suite be your safety net. If behavior is unchanged, a green suite before the edit must stay green after it. A red test therefore means exactly one thing: you broke the invariant — your step was not behavior-preserving. The narrower the step, the more precisely red points at the mistake.

The core catalog is a handful of small, named, reversible moves. You do not invent refactorings; you recognize the situation and apply the matching move. The everyday set:

// Extract Function: a named block becomes a function
// before
const tax = order.lines.reduce((s, l) => s + l.qty * l.price, 0) * 0.2;
// after
const tax = subtotal(order.lines) * 0.2;
function subtotal(lines: Line[]) {
  return lines.reduce((s, l) => s + l.qty * l.price, 0);
}

// Extract Variable: name a sub-expression
// before
if (order.total > 100 && order.lines.length > 3) { /* ... */ }
// after
const isBulkOrder = order.total > 100 && order.lines.length > 3;
if (isBulkOrder) { /* ... */ }

Inline Function and Inline Variable are the exact inverses — used when a name no longer earns its keep. Rename changes a name everywhere it binds. Move relocates a function/field to the module it actually belongs to. Each is reversible, which is what makes the whole process low-risk: any step you regret, you undo with its inverse, no detective work required.

Change Function Declaration and Encapsulate Variable are the two moves that touch a boundary — do them in micro-steps. Renaming a function, adding/removing a parameter, or reordering arguments (Change Function Declaration) ripples to every caller. The amateur version is one giant find-and-replace. The disciplined version, when callers are many, is the migration variant:

// 1. add the new shape alongside the old, old delegates to new
function chargeOld(cents: number) { return charge({ cents }); }
function charge(opts: { cents: number }) { /* real body */ }
// 2. migrate callers to `charge` one at a time, tests green after each
// 3. delete `chargeOld` when no caller remains

Encapsulate Variable does the same for data: wrap a bare exported field in a getter/setter so future access is funneled through one point, then migrate readers.

// before: bare mutable export — every reader is a caller you can't see
export let config = { region: "eu" };
// after: access funneled through functions you can later guard or memoize
let _config = { region: "eu" };
export const getConfig = () => _config;
export const setConfig = (c: Config) => { _config = c; };

Each numbered sub-step keeps the suite green, so you can stop and ship at any line.

The rhythm is a loop, not a sprint: tiny step → run tests → commit → repeat. This is the whole discipline. The commit is not bureaucracy; it is the ratchet tooth. After each green commit the previous good state is captured, so the cost of any mistake is bounded to one step — git reset --hard or revert that single commit and you are back to known-good. Skip the commits and one bad step contaminates an hour of work you now can’t cleanly separate.

loop:
  make ONE catalog move        # extract, rename, inline, move…
  run the test suite           # must be green (it was green before)
  green? -> git commit         # "refactor: extract subtotal()"  ← ratchet clicks
  red?   -> revert THIS step   # the step was not behavior-preserving; undo, retry smaller

Two failure modes this kills: the big-bang refactor (hours of edits, then a red suite with no idea which edit did it), and the irreversible refactor (you’ve changed so much you can’t get back to working code). Small reversible steps make both impossible — the suite can only ratchet forward.