Command

okulo refactor

Turn active debt into a function- and line-level refactor plan.

When to use it

After hotspots/debt, when you want concrete work items instead of a file list.

Usage

okulo refactor [repo] [options]

Options

Examples

Plan the top offenders

okulo refactor --top 5
okulo refactor --top 3 --hourly-rate 60

Focus on one known hotspot

okulo refactor --file src/billing/invoice.py

Two files that always change together

okulo refactor --file web/checkout/Cart.tsx --file web/checkout/Pay.tsx

Sample output

Illustrative terminal output (column layout matches the real CLI):

Refactoring plan  where to act first, and how

1. src/billing/invoice.py  health 3.1 · 840 LOC · waste 14.2h/mo · payback 1.5 months
   [high] complex-function: `calculate_totals` (L220–310) has cognitive complexity 65
         → Extract each independent branch into a well-named function…
   [high] deep-nesting: `calculate_totals` nests control structures 6 levels deep
         → Flatten with guard clauses / early returns…
   [medium] large-function: `apply_discounts` (L340–420) is 80 lines long
         → Split it into steps that each do one thing.

2. web/checkout/Cart.tsx  health 4.8 · 520 LOC · waste 7.1h/mo · payback 1.8 months
   [high] complex-function: `CheckoutProvider` (L88–205) has cognitive complexity 48
         → Extract sub-components and move state logic into hooks/services.

How to read it

• Files are ordered by active-debt priority (waste / payback), not alphabetically.
• Each finding names the function + line range and a concrete tactic — that is your ticket description.
• Start with [high] items inside file #1. Landing one function-level extract often moves health more than a vague “cleanup module” task.

Tips

• Create tickets from the top 1–2 files and the suggested functions — avoid full-module rewrites.
• Pair with check so refactors do not regress neighboring hot code.

Related