complexity-and-code-health-analyzer

Analyze structural complexity, code churn, and static connascence to identify high-risk hotspots. Use when auditing complexity thresholds, refactoring candidates, or CI gating for code health.

Complexity and Code Health Analyzer

Identify structural hotspots by combining complexity, connascence, and churn data.

When to Use

  • Routine code quality audits
  • Pre-refactor planning
  • CI gates for complexity thresholds
  • Volatility and technical-debt reviews

Scope

  • Scans: public methods and classes, cross-module call sites, static connascence signals, and version-control churn for hotspot detection.
  • Exclusions: generated files, vendor code, and intentionally large benchmark or load-test scripts unless they also show material structural risk.
  • Fallback: if complexity and churn signals disagree, fall back to the shared conventions scoring order and downgrade to warning when confidence is low.
  • Routing: defer public-interface coupling to Integration Strength and Micro-Coupling Evaluator and module-level dependency health to Structural Coupling and Volatility Analyzer.

Workflow

  1. Calculate complexity.
    • Compute cyclomatic and cognitive complexity for public methods and classes.
    • Flag god classes and threshold violations.
  2. Evaluate static connascence.
    • Detect position, meaning, and type coupling.
    • Flag magic numbers, brittle argument ordering, and dynamic typing across boundaries.
  3. Overlay churn.
    • Compute separate scores for structural complexity and version-control volatility.
    • Flag critical hotspots only when both scores are materially high or when one score is extreme and the other is non-trivial.
    • Treat large but stable benchmark/load scripts as operational hotspots, not automatically as architectural debt.
  4. Report findings.
    • Return the most complex methods and classes.
    • Include both complexity and volatility scores, plus a combined hotspot classification.

Rules

  • Use static analysis, AST parsing, and version-control logs only.
  • Keep the analysis deterministic and language-agnostic.
  • Use team-defined thresholds when available.
  • Do not label a file as a critical hotspot from size alone.
  • If a file is large but historically stable, downgrade to warning unless the code is also structurally complex.

Shared Conventions

  • Follow the repository-wide conventions in shared-skill-conventions.
  • Use the canonical output contract, severity levels, confidence rubric, routing rules, and false-positive downgrades defined there.
  • If this skill is not the closest match, defer to the routing guidance in the shared conventions file.

Output

Return:

  • Top complex methods and classes
  • Critical hotspots from complexity/churn overlay
  • Static connascence findings
  • CI-ready pass or fail output