Complete documentation for code churn analysis and correlation.

Location: callflow_tracer/code_churn.py (382 lines)

Overview

The Code Churn module analyzes code changes using git history and correlates them with quality and performance metrics to identify high-risk files.

Key Components

ChurnMetrics (Dataclass)

Measures code churn for files.

Attributes:

Hotspot Score Calculation:

ChurnCorrelation (Dataclass)

Correlates churn with quality/performance.

Attributes:

Classes

CodeChurnAnalyzer

Analyzes code churn using git history.

Methods:

Requirements: Git repository with history

ChurnCorrelationAnalyzer

Correlates churn with quality metrics.

Methods:

Risk Assessment:

Usage Examples

Analyze File Churn

from callflow_tracer.code_churn import CodeChurnAnalyzer

analyzer = CodeChurnAnalyzer(".")
metrics = analyzer.analyze_file_churn("src/main.py", days=90)

print(f"Commits: {metrics.total_commits}")
print(f"Lines modified: {metrics.lines_modified}")
print(f"Churn rate: {metrics.churn_rate:.2f} changes/day")
print(f"Hotspot score: {metrics.hotspot_score:.1f}")
print(f"Authors: {', '.join(metrics.authors)}")

Identify Hotspots

from callflow_tracer.code_churn import CodeChurnAnalyzer

analyzer = CodeChurnAnalyzer(".")
hotspots = analyzer.identify_hotspots(".", days=90, top_n=10)

for i, hotspot in enumerate(hotspots, 1):
    print(f"{i}. {hotspot.file_path}")
    print(f"   Hotspot Score: {hotspot.hotspot_score:.1f}")
    print(f"   Commits: {hotspot.total_commits}")
    print(f"   Churn Rate: {hotspot.churn_rate:.2f}")

Correlate with Quality

from callflow_tracer.code_churn import (
    CodeChurnAnalyzer, 
    ChurnCorrelationAnalyzer
)

analyzer = CodeChurnAnalyzer(".")
churn_metrics = analyzer.analyze_directory_churn(".", days=90)

correlator = ChurnCorrelationAnalyzer()
correlations = correlator.correlate_churn_with_quality(
    churn_metrics, 
    complexity_metrics, 
    performance_data
)

for corr in correlations:
    if corr.risk_assessment == "Critical":
        print(f"CRITICAL: {corr.file_path}")
        print(f"  Churn Score: {corr.churn_score:.1f}")
        print(f"  Complexity: {corr.complexity_score:.1f}")
        print(f"  Performance: {corr.performance_score:.1f}")
        print(f"  Bug Correlation: {corr.bug_correlation:.2f}")
        print(f"  Recommendations:")
        for rec in corr.recommendations:
            print(f"    - {rec}")

Generate Full Report

from callflow_tracer.code_churn import generate_churn_report

report = generate_churn_report(".", days=180)

print(f"Total files: {report['summary']['total_files']}")
print(f"Total commits: {report['summary']['total_commits']}")
print(f"Total changes: {report['summary']['total_changes']}")
print(f"Average churn rate: {report['summary']['average_churn_rate']:.2f}")
print(f"High risk files: {report['summary']['high_risk_files']}")

print("\nTop Hotspots:")
for hotspot in report['hotspots'][:5]:
    print(f"  - {hotspot['file_path']}: {hotspot['hotspot_score']:.1f}")

CLI Usage

# Analyze code churn
callflow-tracer churn . -o churn_report.html

# Custom time period
callflow-tracer churn . --days 180 -o churn_report.html

# JSON output
callflow-tracer churn . --format json -o churn_report.json

# Specific directory
callflow-tracer churn ./src -o src_churn.html

Output Format

{
  "churn_metrics": [
    {
      "file_path": "src/main.py",
      "function_name": null,
      "total_commits": 45,
      "lines_added": 320,
      "lines_deleted": 180,
      "lines_modified": 500,
      "churn_rate": 5.56,
      "last_modified": "2025-01-15",
      "authors": ["alice", "bob", "charlie"],
      "hotspot_score": 72.5
    }
  ],
  "hotspots": [
    {
      "file_path": "src/main.py",
      "hotspot_score": 72.5,
      "total_commits": 45,
      "lines_modified": 500
    }
  ],
  "correlations": [
    {
      "file_path": "src/main.py",
      "churn_score": 72.5,
      "complexity_score": 65.0,
      "performance_score": 45.0,
      "bug_correlation": 0.68,
      "quality_correlation": -0.55,
      "risk_assessment": "High",
      "recommendations": [
        "High churn detected - consider refactoring",
        "High complexity - simplify code structure",
        "Performance issues detected - profile and optimize"
      ]
    }
  ],
  "summary": {
    "total_files": 42,
    "total_commits": 1250,
    "total_changes": 15000,
    "average_churn_rate": 5.2,
    "analysis_period_days": 90,
    "high_risk_files": 8
  }
}

Interpretation Guide

Hotspot Scores

Churn Rate

Correlations

Recommendations