Code Quality Metrics Overview

Supported Languages: Rust, TypeScript/JavaScript (TSX/JSX), Python, C, C++, Go, Java, Ruby, PHP, Tcl

Key Features:

• Real-time complexity analysis with severity classification
• Hash-based duplication detection with comment filtering
• Semantic code search using AI embeddings
• Impact analysis for change risk assessment
• Automated refactoring opportunity detection
• Multi-format reporting (JSON, Markdown, HTML, CSV)

Stellarion Metrics Analysis Categories

1. Complexity Metrics

Cyclomatic Complexity (CC)

• Measurement: Counts independent paths through code using control flow graph analysis
• Formula: CC = E - N + 2P (edges - nodes + 2×components) or (decision points) + 1
• Calculation: AST traversal counting if, while, for, switch, case, &&, ||, ternary operators, exception handlers
• Range: 1 to infinity (practically 1-100)

Stellarion Severity Classification:

Cognitive Complexity

• Measurement: Human-perceived difficulty to understand code, weighted by nesting depth
• Calculation: Increments for decision points + additional increments per nesting level
• Philosophy: Measures maintainability from developer perspective (not just testability)
• Range: 0 to infinity (practically 0-100)

Stellarion Severity Classification:

Key Difference: Cognitive complexity penalizes deeply nested structures more heavily than cyclomatic complexity. A function with CC=10 but deep nesting may have Cognitive=25.

Nesting Depth

• Measurement: Maximum level of nested control structures (if/for/while/try blocks)
• Calculation: Tree depth analysis from AST
• Stellarion Threshold: Flags functions with depth >4 as refactoring candidates

2. Maintainability Metrics

Maintainability Index (MI)

• Formula: MI = MAX(0, (171 - 5.2×ln(HV) - 0.23×CC - 16.2×ln(LOC)) × 100/171)
• Components:
  • Halstead Volume (HV): Information content and program size
  • Cyclomatic Complexity (CC): Control flow paths
  • Lines of Code (LOC): Physical size metric
• Scale: 0-100 (higher is better)

Stellarion Rating System:

Example from agoran-stellarion-project:

• content_hash.c: MI=35.5 (Poor), CC=33, Cognitive=48 → Critical priority refactoring

3. Code Duplication Metrics

Duplicate Code Detection

• Method: Hash-based code block comparison with AI-powered comment filtering
• Minimum Block Size: 5 lines (configurable)
• Intelligence: Filters multi-line comments (/* */), Python docstrings (""" """), JSDoc (/** */)
• Measurement: Percentage of codebase with duplicated blocks

Stellarion Thresholds:

Priority Calculation:

• High Priority: >5 occurrences of same block
• Medium Priority: 2-5 occurrences
• Effort: Medium-high if >5 occurrences, medium otherwise

4. Structural Metrics

Dependency Analysis

• Afferent Coupling (Ca): Number of modules depending on this module (incoming dependencies)
• Efferent Coupling (Ce): Number of modules this module depends on (outgoing dependencies)
• Calculation: Graph traversal using KuzuDB with import/export analysis
• Graph Edges:
  • Import edges: Module-level dependencies
  • Call edges: Function-level relationships
  • Instantiation edges: Object creation dependencies

Stellarion Metrics (from agoran-stellarion-project):

• 34 import edges (module dependencies)
• 221 call edges (function relationships)
• Depth configurable: 1-10 levels (default: 5)

Circular Dependencies

• Detection: Graph cycle detection using BFS/DFS algorithms
• Classification: By cycle length (minimum 2 files)
• Severity:
  • 0 cycles: Excellent
  • 1-3 cycles: Warning

  • 3 cycles: Critical architectural problem

Stellarion Threshold: Zero tolerance for circular dependencies in production code

5. Size Metrics

Lines of Code (LOC)

• SLOC (Source LOC): Non-comment, non-blank lines
• Total LOC: All lines including comments and blanks
• Logical Statements: Language-specific executable statements

Stellarion Recommendations:

• Functions: <50 SLOC (warning at 50-100, critical >100)
• Files: <500 SLOC (warning at 500-1000, critical >1000)
• Classes: <300 SLOC (warning at 300-500, critical >500)

6. Quality Scoring

Test Coverage Integration

• Line Coverage: Percentage of lines executed by tests
• Branch Coverage: Percentage of decision paths tested
• Recommendation: Coverage ≥ (CC × 5%) with minimum 80%

Technical Debt Calculation

• Formula: Debt = (CC - 10) × 100 + (100 - MI) + (Duplication% × 10)
• High Priority: Debt Score >500
• Effort Estimation:
  • Complexity: High if CC >30, Medium-high if CC >20
  • Duplication: Medium-high if >5 occurrences
  • Organization: Low
  • Interfaces: Medium

Stellarion Recommended Actions by Metric

Complexity Actions

When CC > 20 (Critical):

1. Extract Method: Break large functions into smaller, focused units
2. Guard Clauses: Use early returns to reduce nesting
3. Replace Conditionals: Apply strategy pattern or lookup tables
4. Simplify Logic: Apply De Morgan's laws to boolean expressions
5. Test Coverage: Create CC × 1.5 test cases minimum

When Cognitive Complexity > 25 (Critical):

1. Reduce Nesting: Invert conditionals, flatten structure
2. Extract Complex Conditions: Create named boolean variables/functions
3. Decompose Loops: Separate filtering, mapping, reducing operations
4. Single Responsibility: Ensure each function does one thing well

Example Action (from agoran-stellarion-project):

• content_hash.c (CC=33, Cognitive=48) → Split into 5 smaller functions, target CC <10 per function

Maintainability Actions

When MI < 30 (Poor):

1. Immediate: Reduce cyclomatic complexity (primary driver)
2. Secondary: Decrease function length (LOC component)
3. Tertiary: Simplify expressions (Halstead Volume component)
4. Target: Achieve MI ≥70 after refactoring

When MI 30-50 (Fair):

1. Moderate Refactoring: Extract complex sections
2. Add Documentation: Improve code comments
3. Simplify Logic: Reduce operator/operand variety
4. Target: Achieve MI ≥60

Effort Estimation:

• MI <30: High effort (16+ hours per file)
• MI 30-50: Medium effort (4-16 hours per file)

Duplication Actions

When Duplication > 5% (High):

1. Extract Shared Functions: Create utility modules for repeated code
2. Apply DRY Principle: Don't Repeat Yourself
3. Create Abstract Classes: For object-oriented patterns
4. Use Composition: Build complex behavior from simple components
5. Template Methods: For similar algorithms with variations

Example Action (from agoran-stellarion-project):

• RegisterPage.tsx ↔ LoginPage.tsx: 13 duplicate blocks → Extract useAuthForm hook, reduce to 3% duplication

Structural Actions

When Coupling > 10 (High):

1. Dependency Injection: Remove hard-coded dependencies
2. Interface Segregation: Create focused interfaces
3. Facade Pattern: Simplify complex subsystem interactions
4. Event-Driven: Reduce direct coupling with pub-sub patterns

When Circular Dependencies > 0:

1. Dependency Inversion: Introduce abstractions to break cycles
2. Extract Interface: Create common interface for circular dependencies
3. Move Code: Refactor to establish clear dependency hierarchy
4. Architecture Review: May indicate design flaw

Organization Actions

When File Size > 500 LOC:

1. Split Files: Create separate modules by responsibility
2. Extract Classes: Separate concerns into different files
3. Create Submodules: Organize related functionality

When Directory Has >20 Files:

1. Group by Feature: Create subdirectories by domain
2. Layer Architecture: Separate by technical layers (models, views, controllers)

Stellarion Comprehensive Metrics Reference Table

Stellarion Quality Thresholds

Critical Violations

• ❌ Any function with CC >20
• ❌ Any file with MI <20
• ❌ Circular dependencies >3
• ❌ Critical code with test coverage <80%
• ❌ New code duplication >10%

Warning Violations

• ⚠️ Function CC >15
• ⚠️ File MI <50
• ⚠️ Code duplication >5%
• ⚠️ Nesting depth >4
• ⚠️ Coupling (Ce or Ca) >10

Recommended Best Practices

• ✅ Function CC ≤10
• ✅ File MI ≥70
• ✅ Code duplication ≤3%
• ✅ Nesting depth ≤3
• ✅ Test coverage ≥85%
• ✅ Zero circular dependencies

Case Study: agoran-stellarion-project

Initial Analysis Results

• Total files: 40 (TypeScript: 24, Python: 14, C: 2)
• Average CC: 12.3
• Average Cognitive: 21
• Critical files: 6 (CC >20 or MI <50)
• Refactoring opportunities: 89 (73 duplication, 16 complexity)

Stellarion Recommended Actions

1. Critical Priority: Refactor content_hash.c (CC=33, Cognitive=48, MI=35.5)
   • Action: Split into 5 smaller functions
   • Target: CC <10 per function, MI >70
   • Effort: 24 hours
   • Impact: 15 dependent modules
2. High Priority: Consolidate auth duplication (13 blocks between RegisterPage/LoginPage)
   • Action: Extract useAuthForm hook
   • Target: Reduce duplication from 73 to <10 instances
   • Effort: 16 hours
   • Impact: -96% duplication
3. Medium Priority: Simplify AuthContext.tsx (Cognitive=41)
   • Action: Extract nested logic into separate functions
   • Target: Cognitive <20
   • Effort: 8 hours

Projected Improvements

• Average CC: 12.3 → 8.5 (-31%)
• Average Cognitive: 21 → 12 (-43%)
• Critical files: 6 → 0 (-100%)
• Code duplication: 73 → 3 instances (-96%)
• Overall MI: 45 → 68 (+51%)

Summary

Stellarion provides production-ready code analysis with real metrics, intelligent insights, and actionable recommendations. Its AI-powered approach combines traditional software engineering metrics (cyclomatic complexity, maintainability index) with modern techniques (semantic search, graph analysis) to deliver comprehensive quality assessment.

Key Benefits:

• Detect high-risk code before production
• Prioritize refactoring by impact and effort
• Track technical debt quantitatively
• Improve team code quality awareness

Recommended Usage: Integrate Stellarion into your development workflow for continuous quality monitoring, use it during code reviews to identify complex sections, and leverage its reporting capabilities for stakeholder communication about code health.

Document Version: 1.0 | Last Updated: December 18, 2025 |