Chapter 9: Enhanced Analysis Reports

Chapter Status: ✅ 100% Working (8/8 examples)

Last updated: 2025-09-09
PMAT version: pmat 2.69.0
Test-Driven: All examples validated in tests/ch09/test_report.sh

Professional Analysis Reporting

The pmat report command generates comprehensive, professional-grade analysis reports that consolidate multiple analysis outputs into polished documents suitable for stakeholders, management, and technical teams. These reports provide executive summaries, detailed findings, and actionable recommendations.

Report Generation Basics

Standard Report Formats

Generate reports in multiple professional formats:

# JSON format (default) - machine-readable
pmat report .

# Markdown format - human-readable documentation
pmat report . --md

# CSV format - spreadsheet integration  
pmat report . --csv

# Plain text format - simple output
pmat report . --txt

Basic Report Structure

Every PMAT report includes:

1. Executive Summary - High-level overview and key metrics
2. Project Overview - File counts, languages, and basic statistics
3. Quality Metrics - Maintainability index, technical debt, coverage
4. Risk Assessment - Defect probability and critical issues
5. Detailed Analysis - Complexity, technical debt, duplication, dead code
6. Recommendations - Prioritized action items with estimates
7. Quality Trends - Historical data when available

JSON Report Format

Complete JSON Report Example

pmat report . --format=json

Generated Report Structure:

{
  "report_metadata": {
    "generated_at": "2025-09-09T10:30:00Z",
    "pmat_version": "2.69.0",
    "project_path": "/path/to/project",
    "analysis_duration_ms": 2847,
    "report_type": "comprehensive_analysis"
  },
  "executive_summary": {
    "project_overview": {
      "name": "my-application",
      "files_analyzed": 156,
      "total_lines": 12450,
      "languages": {
        "Rust": 9337,
        "JavaScript": 2490,
        "YAML": 623
      },
      "primary_language": "Rust"
    },
    "quality_metrics": {
      "overall_grade": "B+",
      "maintainability_index": 78,
      "technical_debt_ratio": 3.2,
      "test_coverage": 84.5,
      "code_duplication": 2.1
    },
    "risk_assessment": {
      "high_risk_files": 3,
      "defect_probability": 0.15,
      "critical_issues": 5,
      "security_concerns": 2
    }
  },
  "detailed_analysis": {
    "complexity": {
      "average_complexity": 6.8,
      "maximum_complexity": 22,
      "median_complexity": 4,
      "functions_over_threshold": 8,
      "high_complexity_functions": [
        {
          "file": "src/payment.rs",
          "function": "process_payment",
          "complexity": 22,
          "line": 45,
          "risk_level": "critical",
          "estimated_defect_probability": 0.34
        },
        {
          "file": "src/auth.rs",
          "function": "validate_token",
          "complexity": 18,
          "line": 123,
          "risk_level": "high",
          "estimated_defect_probability": 0.28
        }
      ]
    },
    "technical_debt": {
      "total_markers": 47,
      "categories": {
        "TODO": 23,
        "FIXME": 15,
        "HACK": 6,
        "XXX": 3
      },
      "estimated_hours": 18.5,
      "priority_distribution": {
        "critical": 3,
        "high": 12,
        "medium": 18,
        "low": 14
      },
      "priority_items": [
        {
          "file": "src/auth.rs",
          "line": 67,
          "type": "XXX",
          "message": "Security vulnerability in token validation",
          "priority": "critical",
          "estimated_effort": "3 hours"
        },
        {
          "file": "src/payment.rs",
          "line": 156,
          "type": "FIXME",
          "message": "Race condition in payment processing",
          "priority": "high",
          "estimated_effort": "2.5 hours"
        }
      ]
    },
    "code_duplication": {
      "duplication_percentage": 2.1,
      "total_duplicate_lines": 261,
      "duplicate_blocks": [
        {
          "files": ["src/validators/user.rs:45-67", "src/validators/admin.rs:23-45"],
          "similarity": 1.0,
          "lines": 23,
          "type": "exact_duplication",
          "refactoring_potential": "high"
        },
        {
          "files": ["src/utils/calc.rs:12-25", "src/helpers/math.rs:34-47"],
          "similarity": 0.95,
          "lines": 14,
          "type": "structural_duplication",
          "refactoring_potential": "medium"
        }
      ],
      "estimated_savings": {
        "lines": 187,
        "maintenance_hours": 4.2
      }
    },
    "dead_code": {
      "unused_functions": 7,
      "unused_variables": 23,
      "unused_imports": 12,
      "dead_code_percentage": 1.8,
      "findings": [
        {
          "file": "src/legacy/converter.rs",
          "function": "old_transform",
          "line": 234,
          "safe_to_remove": true,
          "last_modified": "2024-03-15"
        },
        {
          "file": "src/utils/helpers.rs",
          "function": "deprecated_formatter",
          "line": 45,
          "safe_to_remove": false,
          "reason": "might_be_used_dynamically"
        }
      ]
    },
    "architecture": {
      "patterns_detected": ["MVC", "Repository", "Service Layer"],
      "modularity_score": 0.82,
      "coupling": "moderate",
      "cohesion": "high",
      "dependency_analysis": {
        "total_dependencies": 15,
        "outdated_dependencies": 3,
        "security_vulnerabilities": 2
      }
    }
  },
  "recommendations": [
    {
      "id": "R001",
      "priority": "critical",
      "category": "security",
      "title": "Fix token validation vulnerability",
      "description": "Address XXX marker in src/auth.rs:67 - security vulnerability in token validation",
      "estimated_effort": "3 hours",
      "impact": "Prevents potential security breach",
      "files_affected": ["src/auth.rs"],
      "implementation_notes": "Review JWT validation logic and add proper signature verification"
    },
    {
      "id": "R002", 
      "priority": "high",
      "category": "complexity",
      "title": "Refactor payment processing function",
      "description": "Reduce complexity of process_payment from 22 to <10",
      "estimated_effort": "4 hours",
      "impact": "Reduced defect probability from 34% to ~5%",
      "files_affected": ["src/payment.rs"],
      "implementation_notes": "Extract validation, error handling, and business logic into separate functions"
    },
    {
      "id": "R003",
      "priority": "medium",
      "category": "duplication",
      "title": "Consolidate validation logic",
      "description": "Extract common validation into shared utilities",
      "estimated_effort": "2 hours",
      "impact": "Reduce duplication from 2.1% to ~1.2%",
      "files_affected": ["src/validators/*.rs"],
      "implementation_notes": "Create ValidationUtils trait with common methods"
    }
  ],
  "quality_trends": {
    "historical_data_available": true,
    "trend_period": "6_months",
    "metrics": {
      "maintainability_trend": "improving",
      "complexity_trend": "stable", 
      "technical_debt_trend": "increasing",
      "test_coverage_trend": "improving"
    },
    "monthly_snapshots": [
      {
        "month": "2025-03",
        "maintainability_index": 78,
        "technical_debt_ratio": 3.2,
        "complexity_average": 6.8
      }
    ]
  }
}

Markdown Report Format

Professional Markdown Reports

Generate polished documentation with:

pmat report . --md

Generated Markdown Report:

# Quality Analysis Report

**Project**: my-application  
**Generated**: 2025-09-09 10:30:00 UTC  
**PMAT Version**: 2.69.0  
**Analysis Duration**: 2.847 seconds

## Executive Summary

### Project Overview
- **Files Analyzed**: 156
- **Total Lines**: 12,450
- **Primary Language**: Rust (75%)
- **Overall Grade**: B+ (78/100)

### Key Metrics
- **Maintainability Index**: 78/100
- **Technical Debt Ratio**: 3.2%
- **Test Coverage**: 84.5%
- **Code Duplication**: 2.1%

### Risk Assessment
- **High-Risk Files**: 3
- **Critical Issues**: 5
- **Defect Probability**: 15%

## Detailed Analysis

### 🔧 Complexity Analysis

**Summary**: 8 functions exceed recommended complexity threshold

| Function | File | Complexity | Risk Level |
|----------|------|------------|------------|
| `process_payment` | src/payment.rs:45 | 22 | 🔴 Critical |
| `validate_token` | src/auth.rs:123 | 18 | 🔴 High |
| `generate_report` | src/reports.rs:67 | 15 | 🟡 Moderate |

**Recommendations**:
- **Immediate**: Refactor `process_payment` (defect probability: 34%)
- **Short-term**: Break down `validate_token` into smaller functions
- **Long-term**: Establish complexity monitoring in CI/CD

### 🏗️ Technical Debt Analysis

**SATD Markers**: 47 total (18.5 estimated hours)

| Priority | Type | Count | Est. Hours |
|----------|------|-------|------------|
| 🔴 Critical | XXX | 3 | 8.5 |
| 🔴 High | FIXME | 15 | 7.2 |
| 🟡 Medium | TODO | 23 | 2.8 |
| 🟢 Low | HACK | 6 | 0.5 |

**Priority Items**:
1. **🔴 CRITICAL**: Security vulnerability in token validation (src/auth.rs:67)
2. **🔴 HIGH**: Race condition in payment processing (src/payment.rs:156)
3. **🔴 HIGH**: Memory leak in session management (src/session.rs:234)

### 🔄 Code Duplication Analysis

**Duplication Rate**: 2.1% (261 lines)

**Major Duplications**:
- **Exact Match**: Validation logic (23 lines) - High refactoring potential
- **Structural**: Math utilities (14 lines) - Medium refactoring potential

**Refactoring Impact**: 
- Lines saved: 187
- Maintenance reduction: 4.2 hours annually

### 💀 Dead Code Analysis

**Unused Code**: 42 items (1.8% of codebase)

| Type | Count | Safe to Remove |
|------|-------|----------------|
| Functions | 7 | 5 |
| Variables | 23 | 23 |
| Imports | 12 | 12 |

**Cleanup Impact**: Reduce codebase by ~1.8%, improve build times

## Quality Recommendations

### 🔥 Immediate Actions (This Week)

1. **Fix Security Vulnerability** (Critical)
   - File: `src/auth.rs:67`
   - Effort: 3 hours
   - Impact: Prevent security breach

2. **Address Payment Race Condition** (High)
   - File: `src/payment.rs:156`
   - Effort: 2.5 hours  
   - Impact: Improve transaction reliability

### ⚡ Short-term Goals (This Month)

1. **Reduce Complexity** 
   - Refactor `process_payment` function
   - Effort: 4 hours
   - Impact: 34% → 5% defect probability

2. **Eliminate Duplication**
   - Extract common validation utilities
   - Effort: 2 hours
   - Impact: 2.1% → 1.2% duplication

### 📈 Long-term Strategy (This Quarter)

1. **Quality Automation**
   - Implement automated complexity monitoring
   - Set up technical debt tracking
   - Establish quality gates in CI/CD

2. **Preventive Measures**
   - Code review guidelines for complexity
   - Automated detection of duplication
   - Regular dead code cleanup

## Quality Trends

**6-Month Analysis**: Overall quality improving

- ✅ **Maintainability**: Trending upward (+12 points)
- ✅ **Test Coverage**: Steady improvement (+15%)
- ⚠️ **Technical Debt**: Slight increase (+0.8%)
- ✅ **Complexity**: Stable (well controlled)

## Conclusion

The project demonstrates **good overall quality** (B+) with specific areas requiring attention. The critical security issue and high-complexity payment function represent the primary risks. Addressing these issues will significantly improve the quality grade and reduce defect probability.

**Immediate Focus**: Security and complexity reduction  
**Success Metrics**: <10 average complexity, <2% technical debt ratio  
**Timeline**: 4-6 weeks for major improvements

---
*Generated by PMAT v2.69.0 - Professional Code Analysis Toolkit*

CSV Report Format

Data Export and Integration

Generate CSV reports for spreadsheet analysis:

pmat report . --csv

CSV Report Structure:

# PMAT Quality Report CSV Export
# Generated: 2025-09-09T10:30:00Z
# Project: my-application

# Summary Metrics
metric,value,unit,grade
files_analyzed,156,count,
total_lines,12450,lines,
overall_grade,78,score,B+
maintainability_index,78,score,B+
technical_debt_ratio,3.2,percentage,B
test_coverage,84.5,percentage,A-
code_duplication,2.1,percentage,A

# Complexity Analysis
file,function,line,complexity,risk_level,defect_probability
src/payment.rs,process_payment,45,22,critical,0.34
src/auth.rs,validate_token,123,18,high,0.28
src/reports.rs,generate_report,67,15,moderate,0.21
src/utils.rs,complex_transform,234,12,moderate,0.18

# Technical Debt Details  
file,line,type,message,priority,estimated_hours
src/auth.rs,67,XXX,Security vulnerability in token validation,critical,3.0
src/payment.rs,156,FIXME,Race condition in payment processing,high,2.5
src/session.rs,234,FIXME,Memory leak in session management,high,2.0
src/api.rs,89,TODO,Add rate limiting,medium,1.5

# Code Duplication
file1,lines1,file2,lines2,similarity,duplicate_lines,refactoring_potential
src/validators/user.rs,45-67,src/validators/admin.rs,23-45,1.0,23,high
src/utils/calc.rs,12-25,src/helpers/math.rs,34-47,0.95,14,medium

# Dead Code Analysis
file,item,type,line,safe_to_remove,last_modified
src/legacy/converter.rs,old_transform,function,234,true,2024-03-15
src/utils/helpers.rs,deprecated_formatter,function,45,false,2024-01-20
src/models/user.rs,unused_field,variable,67,true,2024-02-10

# Recommendations
id,priority,category,title,estimated_effort,files_affected
R001,critical,security,Fix token validation vulnerability,3 hours,src/auth.rs
R002,high,complexity,Refactor payment processing function,4 hours,src/payment.rs
R003,medium,duplication,Consolidate validation logic,2 hours,src/validators/*.rs

Advanced Report Features

Specific Analysis Types

Generate targeted reports focusing on specific analysis areas:

# Complexity-focused report
pmat report . --analyses=complexity --format=json

# Technical debt report only
pmat report . --analyses=technical_debt --md

# Multi-analysis report
pmat report . --analyses=complexity,dead_code,duplication --csv

Confidence Filtering

Filter findings by confidence level:

# High-confidence findings only (80%+)
pmat report . --confidence-threshold=80

# Medium-confidence and above (60%+)
pmat report . --confidence-threshold=60

# All findings (default: 50%+)
pmat report . --confidence-threshold=50

High-Confidence Report Example:

{
  "report_metadata": {
    "confidence_threshold": 80,
    "filtering_applied": true,
    "filtered_findings": {
      "included": 23,
      "excluded": 47,
      "exclusion_reason": "below_confidence_threshold"
    }
  },
  "detailed_analysis": {
    "complexity": {
      "note": "Only high-confidence complexity findings (>80%)",
      "high_complexity_functions": [
        {
          "function": "process_payment",
          "complexity": 22,
          "confidence": 95,
          "detection_method": "ast_analysis"
        }
      ]
    }
  }
}

Visualization Support

Include visualization data in reports:

pmat report . --include-visualizations --format=json

Visualization Data:

{
  "visualizations": {
    "complexity_distribution": {
      "type": "histogram",
      "data": {
        "bins": ["1-5", "6-10", "11-15", "16-20", "21+"],
        "counts": [89, 45, 15, 5, 2]
      },
      "config": {
        "title": "Function Complexity Distribution",
        "x_axis": "Complexity Range",
        "y_axis": "Function Count"
      }
    },
    "technical_debt_timeline": {
      "type": "line_chart",
      "data": {
        "dates": ["2024-09", "2024-10", "2024-11", "2024-12", "2025-01"],
        "todo_count": [18, 20, 22, 25, 23],
        "fixme_count": [12, 14, 15, 16, 15],
        "hack_count": [8, 7, 6, 7, 6]
      }
    },
    "quality_radar": {
      "type": "radar_chart",
      "data": {
        "metrics": ["Maintainability", "Complexity", "Coverage", "Duplication", "Debt"],
        "values": [78, 82, 85, 89, 68],
        "max_value": 100
      }
    }
  }
}

Executive Summary Control

Customize executive summary inclusion:

# Full report with executive summary (default)
pmat report . --include-executive-summary

# Technical report without executive summary
pmat report . --include-executive-summary=false

# Report with recommendations disabled
pmat report . --include-recommendations=false

Performance and Optimization

Performance Monitoring

Track report generation performance:

pmat report . --perf --format=json

Performance Output:

📊 PMAT Report Generation
=========================

Performance Metrics:
  Total Analysis Time: 4,523ms
  Files Processed: 156
  Lines Analyzed: 12,450
  Report Generation: 1,234ms

Timing Breakdown:
  • File Discovery: 156ms
  • AST Parsing: 2,234ms
  • Complexity Analysis: 1,067ms
  • Dead Code Detection: 445ms
  • Duplication Analysis: 621ms
  • Report Formatting: 1,234ms

Resource Usage:
  • Peak Memory: 67.3MB
  • Average CPU: 43%
  • Disk I/O: 234 reads, 12 writes

✅ Report saved to: analysis-report.json (47.2KB)

Large Repository Optimization

Optimize reports for large codebases:

# Streaming analysis for memory efficiency
pmat report . --stream --format=json

# Parallel processing
pmat report . --parallel-jobs=8

# Exclude large files
pmat report . --max-file-size=1MB

# Focus on specific directories
pmat report src/ --format=json

Integration and Automation

CI/CD Integration

GitHub Actions Example

name: Quality Report Generation

on: [push, pull_request]

jobs:
  quality-report:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install PMAT
        run: cargo install pmat
        
      - name: Generate Quality Reports
        run: |
          pmat report . --format=json --output=quality-report.json
          pmat report . --md --output=QUALITY_REPORT.md
          pmat report . --csv --output=quality-data.csv
          
      - name: Upload Reports
        uses: actions/upload-artifact@v3
        with:
          name: quality-reports
          path: |
            quality-report.json
            QUALITY_REPORT.md
            quality-data.csv
            
      - name: Comment PR with Report
        if: github.event_name == 'pull_request'
        run: |
          echo "## 📊 Quality Analysis Report" >> pr-comment.md
          echo "" >> pr-comment.md
          cat QUALITY_REPORT.md >> pr-comment.md

GitLab CI Integration

quality_report:
  stage: analysis
  script:
    - pmat report . --format=json --output=quality-report.json
    - pmat report . --md --output=quality-report.md
  artifacts:
    reports:
      quality: quality-report.json
    paths:
      - quality-report.json
      - quality-report.md
    expire_in: 30 days
  only:
    - main
    - merge_requests

Automated Report Distribution

Email Reports

#!/bin/bash
# generate-and-email-report.sh

# Generate report
pmat report . --md --output=weekly-quality-report.md

# Email to stakeholders
mail -s "Weekly Quality Report - $(date +%Y-%m-%d)" \
     -a weekly-quality-report.md \
     stakeholders@company.com < /dev/null

Slack Integration

#!/bin/bash
# slack-quality-report.sh

# Generate JSON report
pmat report . --format=json --output=report.json

# Extract key metrics
GRADE=$(jq -r '.executive_summary.quality_metrics.overall_grade' report.json)
ISSUES=$(jq -r '.executive_summary.risk_assessment.critical_issues' report.json)

# Post to Slack
curl -X POST -H 'Content-type: application/json' \
  --data "{\"text\":\"📊 Quality Report: Grade $GRADE, $ISSUES critical issues\"}" \
  $SLACK_WEBHOOK_URL

Report Customization

Custom Analysis Profiles

Create project-specific report configurations:

# .pmat/report.toml

[report]
default_format = "markdown"
include_visualizations = true
confidence_threshold = 70

[executive_summary]
include_trends = true
include_risk_assessment = true
highlight_critical_issues = true

[analyses]
enabled = ["complexity", "technical_debt", "duplication", "dead_code"]
disabled = []

[complexity]
threshold = 10
include_cognitive_complexity = true
risk_calculation = "advanced"

[technical_debt]
priority_keywords = {
    critical = ["SECURITY", "URGENT", "CRITICAL"],
    high = ["FIXME", "BUG", "IMPORTANT"],
    medium = ["TODO", "REFACTOR"],
    low = ["NOTE", "MAYBE"]
}

[output]
include_metadata = true
include_performance_metrics = false
compress_large_reports = true

Report Templates

Use custom report templates:

# Use built-in template
pmat report . --template=executive

# Use custom template file
pmat report . --template=templates/quarterly-report.json

# Available built-in templates
pmat report . --list-templates

Troubleshooting

Common Issues

Large Report Files

# Compress JSON output
pmat report . --format=json | gzip > report.json.gz

# Use streaming for large projects
pmat report . --stream --format=json

# Filter by confidence to reduce size
pmat report . --confidence-threshold=80

Performance Issues

# Use parallel processing
pmat report . --parallel-jobs=$(nproc)

# Focus on specific analysis types
pmat report . --analyses=complexity,technical_debt

# Exclude vendor directories
pmat report . --exclude="vendor/,node_modules/,target/"

Memory Usage

# Monitor memory usage
pmat report . --perf --debug

# Use streaming mode
pmat report . --stream

# Process in batches
pmat report src/ --format=json
pmat report tests/ --format=json

Best Practices

Report Generation Workflow

1. Regular Schedules: Generate reports weekly or bi-weekly
2. Version Control: Store reports in dedicated branch or external system
3. Trend Tracking: Maintain historical data for trend analysis
4. Stakeholder Distribution: Automated delivery to relevant teams
5. Action Items: Convert recommendations into tracked work items

Quality Standards

1. Baseline Establishment: Set quality baselines from initial reports
2. Improvement Targets: Define specific improvement goals
3. Regression Detection: Monitor for quality degradation
4. Review Cycles: Regular report review with development teams

Integration Best Practices

1. Automated Generation: Include in CI/CD pipelines
2. Multiple Formats: Generate both technical and executive formats
3. Actionable Content: Focus on specific, actionable recommendations
4. Historical Context: Maintain trend data for context

Summary

The pmat report command provides comprehensive analysis reporting capabilities:

• Professional Formats: JSON, Markdown, CSV, and plain text outputs
• Executive Summaries: High-level overviews for stakeholders and management
• Detailed Analysis: In-depth technical findings and metrics
• Actionable Recommendations: Prioritized improvement suggestions with estimates
• Visualization Support: Chart and graph data for visual reporting
• Performance Monitoring: Built-in timing and resource usage tracking
• Integration Ready: Seamless CI/CD and automation integration

Use reports to:

1. Communicate Quality: Share quality status with stakeholders
2. Track Improvements: Monitor quality trends over time
3. Prioritize Work: Focus development effort on high-impact areas
4. Document Progress: Maintain records of quality evolution
5. Enable Decision Making: Provide data-driven insights for technical decisions

Next Steps

• Chapter 5: Analyze Suite - Detailed analysis commands
• Chapter 7: Quality Gates - Automated quality enforcement
• Chapter 8: Interactive Demo - Interactive analysis demonstrations