Skip to content

Latest commit

 

History

History
163 lines (120 loc) · 4.3 KB

COMPLEXITY_REQUIREMENTS.md

File metadata and controls

163 lines (120 loc) · 4.3 KB

Complexity Requirements

Overview

GitVoyant tracks multiple complexity metrics over time to build a comprehensive picture of code evolution.

Primary Metrics

1. Cyclomatic Complexity

Definition: Number of linearly independent paths through code

Calculation:

Complexity = 1 + number_of_decision_points

Decision Points:

  • if, elif, else
  • while, for loops
  • try, except blocks
  • Boolean operators (and, or)
  • Ternary operators

Interpretation:

  • 1-10: Simple, easy to test
  • 11-20: Moderate complexity
  • 21-50: High complexity, consider refactoring
  • 50+: Very high risk, immediate attention needed

2. Lines of Code (LOC)

Definition: Total number of non-empty lines

Significance:

  • Correlates with maintenance effort
  • Growth rate indicates development velocity
  • Sudden spikes suggest rushed development

3. Function Count

Definition: Number of function definitions

Usage:

  • Tracks code organization patterns
  • Helps identify monolithic growth
  • Correlates with modularity

4. Class Count

Definition: Number of class definitions

Purpose:

  • Measures architectural complexity
  • Tracks object-oriented design evolution
  • Identifies abstraction patterns

Temporal Evaluation Metrics

1. Complexity Tenor Slope

Definition: Rate of complexity change per time unit

Calculation:

slope = linear_regression(time_points, complexity_values)

Interpretation:

  • Positive slope: Increasing complexity (risk)
  • Negative slope: Decreasing complexity (refactoring)
  • Zero slope: Stable complexity (ideal)

2. Volatility Rank

Definition: Standard deviation of complexity changes

Purpose:

  • Measures consistency of development
  • High volatility indicates unstable development
  • Low volatility suggests controlled evolution

3. Growth Rate

Definition: Percentage change in complexity over time

Formula:

growth_rate = (current_complexity - initial_complexity) / initial_complexity

Quality Decay Indicators

1. Complexity Acceleration

Definition: Rate of change in complexity growth

Significance:

  • Detects when complexity growth is accelerating
  • Early warning of decay patterns
  • Predicts maintenance crisis points

2. Author Diversity Impact

Definition: How complexity correlates with number of contributors

Evaluation:

  • More authors often correlates with complexity growth
  • Measures coordination overhead
  • Identifies files needing better documentation

3. Modification Frequency

Definition: Number of commits per time period

Correlation:

  • High frequency + complexity growth = high risk
  • High frequency + stable complexity = healthy iteration
  • Low frequency + complexity growth = technical debt accumulation

Risk Assessment Formula

GitVoyant combines metrics into a unified risk rank:

risk_score = (
    0.4 * normalized_complexity_tenor +
    0.3 * normalized_volatility +
    0.2 * normalized_growth_rate +
    0.1 * modification_frequency_factor
)

Risk Categories

  • 0.0 - 0.3: Low Risk(Green)
  • 0.3 - 0.7: Medium Risk (Yellow)
  • 0.7 - 1.0: High Risk (Red)

Validation

Metrics are being validated against open source projects (alpha research)

  • Known refactoring events in open source projects
  • Bug introduction patterns
  • Developer reported maintenance pain points
  • Code review feedback correlations

Implementation Notes

Handling Edge Cases

  • New files: Minimum 5 commits required
  • Refactoring events: Detected and handled separately
  • Syntax errors: Graceful degradation to line-based metrics
  • Binary files: Automatically excluded

Performance Considerations

  • Incremental evaluation: Only evaluate new commits
  • Caching: Store computed metrics to avoid recomputation
  • Sampling: For very large repositories, sample commit history

Future Metrics

Planned additions:

  • Semantic complexity: Understanding code meaning, not just structure
  • Test coverage correlation: How testing affects complexity evolution
  • Documentation density: Comments and docstring evaluation
  • API surface complexity: Public interface evolution tracking

🔮 GitVoyant by Jesse Moses (@Cre4T3Tiv3) at ByteStack Labs