Concepts

The ideas behind Okulo’s rankings — enough to interpret results without treating them as absolute truth.

Time window

Most analyses look at a sliding window of history (default 12m). Use -w 6m, -w 90d, or -w all. A stale clone or a very short window can look empty — check with okulo log.

Hotspots

A hotspot is code that is both complex and frequently changed. Complex code nobody touches is inactive debt; it may be ugly, but it is not collecting interest every sprint.

• revisions — commits that touched the file in the window
• cognitive — control-flow complexity estimate (language-agnostic)
• health — 1–10 score (≥8 healthy, 4–8 warning, <4 alert)
• score — ranking signal combining change and complexity

Trend

okulo trend samples a file across its history and reports whether health is declining. Useful to separate “always messy” from “getting worse”.

Temporal coupling

Files (or components) that change in the same commits tend to be coupled — even when no import says so. Okulo reports shared changes, degree, and whether the pair crosses architecture boundaries.

Authors, ownership, bus factor

The same person often appears under multiple names/emails. Okulo unifies identities and can suggest more merges via okulo authors. Ownership and bus factor answer: who would we miss if they left, and how concentrated is knowledge?

Active vs inactive debt

okulo debt focuses cost on code that still changes. Refactoring inactive areas rarely pays back; refactoring hotspots often does. okulo refactor turns that into function-level suggestions.

Quality gate

okulo check compares before/after for a branch, staged changes, or the working tree. It fails (exit 1) when a change makes hot, unhealthy code worse — so you catch interest before merge.

Responsible use