codebase-refactoring

A guided pass over a codebase's three biggest maintenance costs, duplicated code, dead code, and complexity, using jscpd to find each and a strategy to fix it. Use this skill when asked to "clean up", "improve", "refactor" or "pay down tech debt in" a codebase, rather than to fix one specific bug.

Start here: measure, then prioritize

npx jscpd --health --reporters ai <path>

health 74 B (duplication 75, dead-code 72, complexity 76; 93 code lines)

The health score is a weighted mix of three sub-scores, each a share of the code lines, high is good, 100 is clean. The lowest of the three names where the codebase actually hurts most; if it isn't the order below, do that dimension first instead. n/a on a dimension (e.g. dead code n/a) means jscpd could not measure it, dead-code detection needs JavaScript, TypeScript or Python to be a real share of the code, skip that step rather than treating it as clean.

For the full picture behind that score, largest duplicated formats, most complex files, largest dead-code findings, all in one screen, run npx jscpd --dashboard instead. Its console output (the default) is the only reporter with that per-file detail; --reporters ai on --dashboard prints the same one-line summary shown above, not the breakdown, so don't reach for it expecting more than the score. Use --reporters json on --dashboard if you need the detail in a parseable form.

The three passes below are otherwise independent and safe to run in any order; duplication → dead code → complexity is the default because fixing duplication first means step 2 isn't wasting effort tracing call sites that a later extract-function pass will move anyway, and clearing dead code before step 3 means the files ranked for simplification are ones actually worth simplifying, not ones about to be deleted.

Step 1, Duplicated code

npx jscpd --reporters ai --summary <path>