The scan engine turns a repository into a ranked action list. The evidence
engine, built on the version history of fifteen reference projects, is what makes that
ranking trustworthy: every weight is measured, every threshold has provenance, and the
directions that did not survive measurement were documented and not shipped.
INPUT
Any repository
Python, C and C++ at any scale. No instrumentation, no build, and the
code is never executed.
➞
CUPID · TWO ENGINES
Scan engine × evidence engine
The scan engine finds problems and ranks them; the evidence engine
proves, with the history of fifteen reference projects, that the ranking deserves
trust.
➞
OUTPUT
Defensible priorities
Every recommendation is four parts: what it is, why it matters, what to
do, and why it was flagged.
01 The scan & decision engine
A repository passes through five stages; each one removes a class of
mistakes that generic tools make.
STEP 1
Scan with a ledger
Every file is recorded as analysed or skipped, with the reason. Coverage is explainable; nothing is silently dropped.
➞
STEP 2
Frontends isolate syntax
Each language's grammar lives in its own frontend. Adding a language means adding one frontend; the rules never change.
➞
STEP 3 · CORE
The IR fact contract
Every language lowers into one neutral fact model. A rule never asks what language this is; it asks whether the facts it needs exist.
All sources converge on one finding schema, ranked by severity × leverage × removability. Never one opaque score.
02 The evidence & calibration engine
CUPID does not assume its rules are right. It measures them, and the
results feed straight back into the ranking.
FOUNDATION
Deterministic ground truth
What counts as a real refactor is decided by an algorithm aligned with RefactoringMiner (ICSE 2018), not by a model or a feeling.
➞
PILLAR 1
AUC-calibrated ranking
Which metrics actually predict code that later gets refactored is measured, and the result is written into the weights.
➞
PILLAR 2
Percentile norms
Every default threshold knows where it sits in the distribution of 42,021 reference functions. Profiles only raise the bar, never lower it.
➞
PILLAR 3
Evidence pipeline
Each smell family can cite a real grew ➞ fixed ➞ stayed case from a respected codebase. Offline, deterministic, zero LLM.
➞
PILLAR 4
Adversarial verification
Findings are tried as suspects: three-class verdicts, every false positive must name its cause in CUPID's own source — and a 60-case eval set over a pinned gold corpus replays both directions after every detector change before it may merge.
03 The measurements behind the weights
Cognitive and cyclomatic complexity lead; deep nesting is discounted to 0.7;
fan-in measured near random, so it enters only as a blast-radius argument, never as the
primary axis.An evidence case is confirmed end-to-end by algorithm: sustained growth, a
confirmed extract-method fix, and survival to the latest release. A mirror query finds
the debt that never got fixed.
De-risk, the same method pointed at ourselves: a future-defect model was measured at
0.744 AUC for size alone versus 0.737 with
every defect flag added; with size removed from the label, everything collapsed
to ≈0.50. So CUPID ships
calibrated rules instead of a predictive model, and the negative result is part of the
record.
04 The code-level map
The same two engines as concrete modules, with three depths: the card
concept, the module list behind each card, and the source-verified engineering details
located on the code map.