Commit a5b75df
committed
docs(research): § 1.4 refactor-risk formula — orphan + NULL fixes + caveat
Grill-me Q12 outcome: § 1.4's "fan_in × (100 - coverage_pct)" formula
had two correctness bugs and one accepted modeling limitation:
CORRECTNESS FIXES (must ship):
- Orphans (fan_in=0) scored 0 → "no risk" → wrong (orphans are
high-risk: dead code or hidden-import targets we don't track).
Fix: `fan_in + 1` so orphans score on coverage alone.
- NULL coverage_pct propagated through the formula → 100 - NULL = NULL
→ row dropped from ORDER BY → unmeasured-coverage symbols silently
vanished from the ranking. Fix: COALESCE(coverage_pct, 0) treats
unmeasured as 0% (high risk).
ACCEPTED v1 TRADE-OFF:
- Linear-in-fan_in (fan_in 100 with 99% coverage = fan_in 1 with 0%
coverage in the score). Real, but not worth fixing in the bundled
recipe — users tune via project-local override.
Caveat block in refactor-risk-ranking.md (will accompany the recipe
when (a) ships) names tuning axes for project-local overrides:
- Log-scale fan_in (LOG(fan_in + 1) * 30) for hub-heavy codebases
- Visibility weight (if @public / @internal / @beta JSDoc tags are
used consistently)
- LOC weight (if test-density varies across files)
Why ship-with-caveat instead of multi-axis composite (Option B):
- Moat A says recipes are saved queries (starting points), not
authoritative verdicts. Bundled formula gets 80% right; users iterate.
- Anti-bloat meta-rule — every additional axis encodes more opinions;
shipping minimal forces explicit thought during tuning.
- Ecosystem-specific axes (visibility weight, LOC weight) shouldn't
be in the bundled default.
Effort stays XS. The .md caveat block lands in the (a) plan PR / impl
PR alongside the .sql; not part of THIS research-note PR's scope.1 parent 537cbb4 commit a5b75df
1 file changed
Lines changed: 12 additions & 12 deletions
0 commit comments