{
  "item_type": "subsection",
  "chapter_id": "analysis-guide",
  "subsection_id": "complexity-metrics",
  "subsection_title": "Complexity Metrics",
  "subsection_file": "book/src/analysis-guide/complexity-metrics.md",
  "feature_mappings": [
    "complexity_analysis.metrics.measured_metrics",
    "complexity_analysis.metrics.estimated_metrics"
  ],
  "drift_detected": true,
  "severity": "medium",
  "quality_assessment": "Documentation is comprehensive with excellent coverage of all complexity metrics. Source line references are outdated due to code evolution, and there is a factual discrepancy regarding the entropy dampening minimum.",
  "issues": [
    {
      "type": "outdated_information",
      "severity": "medium",
      "section": "Entropy-Based Complexity Analysis - Dampening cap",
      "description": "Documentation states dampening factor minimum is 0.7 (max 30% reduction), but actual code in calculate_dampening_factor_pure uses clamp(0.5, 1.0), allowing up to 50% reduction. The config's max_combined_reduction (0.30) is separate from the clamping logic.",
      "current_content": "The dampening factor has a minimum of 0.7, ensuring no more than 30% reduction in complexity scores.",
      "should_be": "The dampening factor is clamped between 0.5 and 1.0. The configuration option max_combined_reduction (default 0.30) controls the maximum allowed reduction percentage separately.",
      "fix_suggestion": "Update the dampening cap description to accurately reflect the 0.5 minimum in the clamping function and explain how max_combined_reduction interacts with this limit",
      "source_reference": "src/complexity/entropy_core.rs:114 - repetition_dampening.clamp(0.5, 1.0)"
    },
    {
      "type": "outdated_information",
      "severity": "low",
      "section": "Cognitive Complexity - Calculation",
      "description": "Line reference 'src/complexity/cognitive.rs:151' for the nesting formula is outdated - the formula is at line 167",
      "current_content": "Formula: `complexity = 1 + nesting_level` (from src/complexity/cognitive.rs:151)",
      "should_be": "Formula: `complexity = 1 + nesting_level` (from src/complexity/cognitive.rs:167)",
      "fix_suggestion": "Update line reference to 167 or use a semantic reference instead of hardcoded line numbers",
      "source_reference": "src/complexity/cognitive.rs:167 - base_complexity: 1 + self.nesting_level"
    },
    {
      "type": "outdated_information",
      "severity": "low",
      "section": "Entropy-Based Complexity Analysis - Token Classification",
      "description": "Line reference 'src/complexity/entropy_core.rs:44-54' for token classification is outdated - TokenCategory enum is now at lines 267-277",
      "current_content": "Categorizes tokens by type with weighted importance (src/complexity/entropy_core.rs:44-54)",
      "should_be": "Categorizes tokens by type with weighted importance (src/complexity/entropy_core.rs:267-277)",
      "fix_suggestion": "Update line reference to point to current TokenCategory enum location",
      "source_reference": "src/complexity/entropy_core.rs:269 - pub enum TokenCategory"
    },
    {
      "type": "outdated_information",
      "severity": "low",
      "section": "Entropy-Based Complexity Analysis - Pattern detection",
      "description": "Line reference 'src/complexity/entropy_core.rs:56-85' for PatternMetrics is outdated - PatternMetrics is now at lines 279-300",
      "current_content": "**Pattern detection** (src/complexity/entropy_core.rs:56-85)",
      "should_be": "**Pattern detection** (src/complexity/entropy_core.rs:279-300)",
      "fix_suggestion": "Update line reference to reflect current PatternMetrics location",
      "source_reference": "src/complexity/entropy_core.rs:281 - pub struct PatternMetrics"
    },
    {
      "type": "outdated_information",
      "severity": "low",
      "section": "Entropy-Based Complexity Analysis - Note on metrics",
      "description": "Line reference 'src/complexity/entropy_core.rs:28-32' for EntropyScore distinction is outdated - EntropyScore is now at lines 228-265",
      "current_content": "**Note on metrics** (src/complexity/entropy_core.rs:28-32)",
      "should_be": "**Note on metrics** (src/complexity/entropy_core.rs:228-265)",
      "fix_suggestion": "Update line reference to current EntropyScore struct location",
      "source_reference": "src/complexity/entropy_core.rs:233 - pub struct EntropyScore"
    },
    {
      "type": "inconsistent_example",
      "severity": "low",
      "section": "Entropy-Based Complexity Analysis - Example",
      "description": "Example shows 67% dampening (from 15 to 5), but documentation states max 30% reduction. This contradicts the stated dampening cap.",
      "current_content": "// Without entropy: Cyclomatic = 15 (appears very complex)\n// With entropy: Effective = 5 (pattern-based, dampened 67%)",
      "should_be": "Either update example to show max 50% reduction per clamp limit, or explain why this example exceeds the stated cap",
      "fix_suggestion": "Update example to show more realistic dampening within stated limits, or clarify that older analysis may have used different settings",
      "source_reference": "Documentation internal consistency"
    }
  ],
  "positive_aspects": [
    "Excellent progressive structure from simple (cyclomatic) to advanced (entropy) metrics",
    "Clear threshold tables with practical interpretation guidance for each metric",
    "Strong examples showing before/after refactoring patterns for nesting depth",
    "Good distinction between cyclomatic and cognitive complexity explained with rationale",
    "Token categories and weights are now fully documented with all six categories",
    "PatternMetrics fields are documented (total_patterns, unique_patterns, repetition_ratio)",
    "Note on metrics clearly distinguishes token_entropy from effective_complexity",
    "Nesting weight multipliers are now explicitly stated (Formula: complexity = 1 + nesting_level)",
    "Constructor detection section is comprehensive with AST vs name-based detection comparison",
    "Configuration example for entropy analysis covers all key options",
    "EntropyScore output fields documented (unique_variables, max_nesting, dampening_applied)",
    "All code examples are syntactically correct Rust",
    "No broken internal markdown links detected"
  ],
  "improvement_suggestions": [
    "Replace hardcoded line number references with stable semantic references (struct/function names) to avoid drift",
    "Reconcile dampening cap documentation with actual clamp(0.5, 1.0) behavior in code",
    "Consider adding a diagram showing the entropy analysis pipeline flow",
    "Add cross-reference to 'advanced-features' subsection for semantic normalization (mentioned in cognitive.rs but not documented)",
    "Consider adding an example of how EntropyAnalysis aggregation works for file-level metrics"
  ],
  "cross_references": [
    "overview",
    "debt-patterns",
    "interpreting-results",
    "advanced-features",
    "risk-scoring"
  ],
  "metadata": {
    "analyzed_at": "2025-12-27T08:30:00Z",
    "feature_inventory": ".prodigy/book-analysis/features.json",
    "topics_covered": [
      "Cyclomatic complexity",
      "Cognitive complexity",
      "Entropy analysis",
      "Constructor detection",
      "Nesting depth",
      "Function length"
    ],
    "validation_focus": "Verify all complexity metric types are documented with examples",
    "internal_links_checked": 0,
    "broken_links_found": 0,
    "previous_analysis": "2025-12-04T22:02:00Z",
    "issues_resolved_since_last": [
      "Token categories now fully documented with weights",
      "PatternMetrics now mentioned with field descriptions",
      "Distinction between token_entropy and effective_complexity now clarified",
      "Nesting weight formula now explicitly stated"
    ]
  }
}
