Omen

Omen

Call-graph reports expose call_resolutions (symbol) and input-wide resolution_summary (impact). These distinguish unique name candidates from ambiguous and unresolved calls. Unique candidates are not compiler-proven bindings; excluded edges do not establish that an edit is safe. See the improvement standard and measured results for limits and regression gates.

Your AI writes code without knowing where the landmines are.

Omen gives AI assistants the context they need: complexity hotspots, hidden dependencies, defect-prone files, and self-admitted debt. One command surfaces what's invisible.

Why "Omen"? An omen is a sign of things to come - good or bad. Your codebase is full of omens: low complexity and clean architecture signal smooth sailing ahead, while high churn, technical debt, and code clones warn of trouble brewing. Omen surfaces these signals so you can act before that "temporary fix" celebrates its third anniversary in production.

---

Features

Complexity Analysis - How hard your code is to understand and test

There are two types of complexity:

• Cyclomatic Complexity counts the number of different paths through your code. Every if, for, while, or switch creates a new path. A function with cyclomatic complexity of 10 means there are 10 different ways to run through it. The higher the number, the more test cases you need to cover all scenarios.

• Cognitive Complexity measures how hard code is for a human to read. It penalizes deeply nested code (like an if inside a for inside another if) more than flat code. Two functions can have the same cyclomatic complexity, but the one with deeper nesting will have higher cognitive complexity because it's harder to keep track of.

Why it matters: Research shows that complex code has more bugs and takes longer to fix. McCabe's original 1976 paper found that functions with complexity over 10 are significantly harder to maintain. SonarSource's cognitive complexity builds on this by measuring what actually confuses developers.

[!TIP]

Keep cyclomatic complexity under 10 and cognitive complexity under 15 per function.

Self-Admitted Technical Debt (SATD) - Comments where developers admit they took shortcuts

When developers write TODO: fix this later or HACK: this is terrible but works, they're creating technical debt and admitting it. Omen finds these comments and groups them by type:

Why it matters: Potdar and Shihab's 2014 study found that SATD comments often stay in codebases for years. The longer they stay, the harder they are to fix because people forget the context. Maldonado and Shihab (2015) showed that design debt is the most common and most dangerous type.

[!TIP]

Review SATD weekly. If a TODO is older than 6 months, either fix it or delete it.

Stubs Detection - Incomplete or placeholder implementations left unfinished

SATD is debt a developer chose to keep; a stub is work that was never finished - the kind of thing an agent or human leaves behind mid-task. Omen finds stubs via tree-sitter AST analysis (never plain string matching, so string literals containing trigger words are never false positives) and groups them by pattern type:

omen stubs

Fail CI if any stub is found

omen stubs --gate error

Only fail on high-severity stubs (todo!()-style idioms), warn on the rest

omen stubs --gate error --gate-severity high omen stubs --gate warn

Why it matters: Unfinished work that looks complete (it compiles, it's committed) is more dangerous than code that's obviously missing - nothing signals it needs attention until it's called in production. Stubs feed into the composite health score's debt component alongside SATD, so unresolved stubs lower your repo's score just like unresolved TODOs do.

[!TIP]

Add omen stubs --gate error to CI to block merges that leave todo!() or NotImplementedError behind.

Dead Code Detection - Code that exists but never runs

Dead code includes:

• Functions that are never called
• Variables that are assigned but never used
• Classes that are never instantiated
• Code after a return statement that can never execute

Why it matters: Dead code isn't just clutter. It confuses new developers who think it must be important. It increases build times and binary sizes. Worst of all, it can hide bugs - if someone "fixes" dead code thinking it runs, they've wasted time. Romano et al. (2020) found that dead code is a strong predictor of other code quality problems.

[!TIP]

Delete dead code. Version control means you can always get it back if needed.

Git Churn Analysis - How often files change over time

Churn looks at your git history and counts:

• How many times each file was modified
• How many lines were added and deleted
• Which files change together

Files with high churn are "hotspots" - they're constantly being touched, which could mean they're:

• Central to the system (everyone needs to modify them)
• Poorly designed (constant bug fixes)
• Missing good abstractions (features keep getting bolted on)

Why it matters: Nagappan and Ball's 2005 research at Microsoft found that code churn is one of the best predictors of bugs. Files that change a lot tend to have more defects. Combined with complexity data, churn helps you find the files that are both complicated AND frequently modified - your highest-risk code.

[!TIP]

If a file has high churn AND high complexity, prioritize refactoring it.

Code Clone Detection - Duplicated code that appears in multiple places

There are three types of clones:

Why it matters: When you fix a bug in one copy, you have to remember to fix all the other copies too. Juergens et al. (2009) found that cloned code has significantly more bugs because fixes don't get applied consistently. The more clones you have, the more likely you'll miss one during updates.

[!TIP]

Anything copied more than twice should probably be a shared function. Aim for duplication ratio under 5%.

Defect Prediction - The likelihood that a file contains bugs

Omen combines multiple signals to predict defect probability using PMAT-weighted metrics:

• Process metrics (churn frequency, ownership diffusion)
• Metrics (cyclomatic/cognitive complexity)
• Age (code age and stability)
• Total size (lines of code)

Each file gets a risk score from 0% to 100%.

Why it matters: You can't review everything equally. Menzies et al. (2007) showed that defect prediction helps teams focus testing and code review on the files most likely to have problems. Rahman et al. (2014) found that even simple models outperform random file selection for finding bugs.

[!TIP]

Prioritize code review for files with >70% defect probability.

Change Risk Analysis (JIT) - Predict which commits are likely to introduce bugs

Just-in-Time (JIT) defect prediction analyzes recent commits to identify risky changes before they cause problems. Unlike file-level prediction, JIT operates at the commit level using change-scope factors from Kamei et al. (2013), augmented with file-level risk signals from the software engineering research literature.

Change-scope factors (75% of score):

Weighted using Kamei's median logistic regression coefficients (relative ordering across projects):

File-level risk signals (25% of score):

| Signal | Weight | Sou