codebase-hygiene

Codebase Hygiene (Duplicate Detection + Module Deepening)

Advisory and read-heavy. Diagnoses and proposes; does not refactor. Any actual change goes through BUILD with full gates.

Mode: DUPLICATE DETECTION

Semantic duplicates: functions serving the same purpose but implemented independently under different names. Copy-paste detectors catch syntactic duplicates; this finds "same intent, different implementation."

Method

1. Scope before you scan — take the user's named target; else git log --oneline for hot spots and weight recently-changed code — deepening pays off in proportion to future change.
2. Extract catalog — Grep/Glob for exported functions. Record name | file:line | signature.
3. Categorize by domain (cheap tier) — validation, formatting, path manipulation, HTTP shaping, date handling. Mechanical bucketing to shrink comparison space.
4. Drop categories with <3 functions — can't hide a meaningful duplication pattern.
5. Detect duplicates per category (capable tier) — read implementations, decide which share intent. Never use cheap tier for detection — it anchors on names and rubber-stamps "these look different."
6. Emit findings — group by confidence, highest first. Each finding: what is duplicated, why it matters, the fix, file:line evidence. Route through code-reviewer finding contract.

High-Risk Zones

Zone	Why it duplicates
utils/, helpers/, lib/	Catch-all dumping grounds
Validation code	"Is this a valid email/id/url" rewritten per feature
Error formatting	Every module invents its own Error → string
Path manipulation	Join/normalize/relativize reimplemented
String formatting	Truncate, slugify, titlecase, pad re-rolled
Date formatting	Parse/format/diff scattered
API response shaping	Envelope/pagination/error-body copied per endpoint

Consolidation Discipline

Never delete a duplicate until all three hold:

1. Survivor has tests — pick the implementation with real coverage. If neither has tests, write the test against the chosen survivor first.
2. All callers updated — Grep to enumerate callers. Missing one is a silent break.
3. Re-run after consolidation — test suite + build/typecheck pass. Green tests on the survivor license the deletion.