Chapter 16: Deep Context Analysis

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

Last updated: 2025-09-09
PMAT version: pmat 0.21.5

The Problem

While PMAT’s regular context command provides quick project overviews for AI assistants, development teams often need deeper, more comprehensive analysis for refactoring, architecture decisions, and quality assessment. Regular context generation focuses on basic metrics and structure, but complex codebases require multi-dimensional analysis combining complexity metrics, git history, dependency graphs, and quality assessments.

Traditional code analysis tools provide point-in-time snapshots or focus on single metrics. Teams need a comprehensive analysis that combines multiple dimensions—complexity, quality, churn, dependencies, and architecture—into a unified view that supports both human decision-making and automated quality gates.

Deep Context vs Regular Context

Regular Context (pmat context)

Purpose: Quick AI assistant integration and basic project understanding
Speed: Fast (seconds)
Output: Basic file structure, line counts, language detection
Use Cases: Documentation generation, AI prompts, quick overview
Token Optimization: Designed for LLM token limits

Example Output:

{
  "total_files": 45,
  "languages": {"python": 30, "javascript": 15},
  "total_lines": 5420,
  "project_structure": {
    "src/": {"files": 30},
    "tests/": {"files": 15}
  }
}

Deep Context (pmat analyze deep-context)

Purpose: Comprehensive multi-dimensional codebase analysis
Speed: Thorough (minutes for large projects, seconds with caching)
Output: AST analysis, complexity metrics, git churn, dependency graphs, quality assessment
Use Cases: Refactoring planning, architecture analysis, quality gates, technical debt assessment
Analysis Depth: Full AST parsing with language-specific insights

Example Output:

{
  "metadata": {
    "generated": "2024-06-09T10:30:45Z",
    "version": "0.21.5",
    "project_path": "/path/to/project",
    "analysis_duration": "2.34s",
    "cache_hit_rate": 0.75
  },
  "overview": {
    "total_files": 298,
    "total_lines": 45231,
    "test_coverage": 92.3,
    "languages": {
      "rust": {"files": 234, "lines": 35420, "percentage": 78.5}
    }
  },
  "complexity": {
    "summary": {
      "median_cyclomatic": 5,
      "p90_cyclomatic": 20,
      "max_cyclomatic": 75
    },
    "hotspots": [/* detailed complexity analysis */]
  },
  "quality": {
    "tdg_score": 1.45,
    "grade": "A-",
    "technical_debt_ratio": 0.05
  },
  "churn": {/* git history analysis */},
  "dependencies": {/* dependency graph analysis */}
}

Performance Comparison

Deep Context Command Interface

Basic Usage

# Basic deep context analysis
pmat analyze deep-context

# With specific output format
pmat analyze deep-context --format json
pmat analyze deep-context --format markdown
pmat analyze deep-context --format sarif

Comprehensive Analysis Options

# Full analysis with all features
pmat analyze deep-context \
  --full \
  --format json \
  --period-days 60 \
  --include "complexity,churn,dependencies,quality" \
  --cache-strategy normal \
  --parallel \
  --top-files 20 \
  --include-pattern "*.rs" \
  --include-pattern "*.py" \
  --exclude-pattern "*/target/*" \
  --exclude-pattern "*/node_modules/*" \
  --max-depth 10 \
  --output comprehensive_analysis.json

Core Command Options

File Filtering Options

Performance Options

Multi-Dimensional Analysis Components

1. Complexity Analysis

Deep context provides comprehensive complexity metrics beyond simple line counts.

Metrics Included:

• Cyclomatic Complexity: Decision point counting
• Cognitive Complexity: Human comprehension difficulty
• N-Path Complexity: Execution path counting
• Halstead Metrics: Software science metrics

Example Complexity Output:

{
  "complexity": {
    "summary": {
      "median_cyclomatic": 5,
      "p90_cyclomatic": 20,
      "max_cyclomatic": 75,
      "median_cognitive": 8,
      "high_complexity_functions": 23
    },
    "hotspots": [
      {
        "file": "cli/mod.rs",
        "function": "handle_analyze_graph",
        "line_start": 245,
        "line_end": 389,
        "cyclomatic_complexity": 75,
        "cognitive_complexity": 125,
        "recommendation": "Extract sub-functions for graph analysis",
        "effort_estimate": "4-6 hours"
      }
    ],
    "distribution": {
      "1-5": 120,    // Low complexity
      "6-10": 30,    // Medium complexity  
      "11-15": 5,    // High complexity
      "16+": 1       // Very high complexity
    }
  }
}

2. Quality Assessment

Comprehensive quality metrics combining multiple quality dimensions.

Quality Components:

• TDG Score: Technical Debt Grading
• Test Coverage: Unit and integration test coverage
• Code Smells: Anti-patterns and issues
• Security Issues: Vulnerability detection
• Maintainability Index: Composite maintainability score

Example Quality Output:

{
  "quality": {
    "tdg_score": 1.45,
    "grade": "A-",
    "confidence": 0.87,
    "test_coverage": 92.3,
    "code_smells": 23,
    "security_issues": 0,
    "technical_debt_ratio": 0.05,
    "maintainability_index": 87.2,
    "components": {
      "complexity": {"score": 8.2, "grade": "A-"},
      "duplication": {"score": 6.8, "grade": "B"},
      "security": {"score": 9.5, "grade": "A+"},
      "documentation": {"score": 8.4, "grade": "A-"}
    }
  }
}

3. Code Churn Analysis

Git history analysis identifying change patterns and risk areas.

Churn Metrics:

• File Change Frequency: How often files change
• Author Distribution: Number of developers per file
• Change Size: Lines added/removed over time
• Risk Score: Combination of complexity and churn

Example Churn Output:

{
  "churn": {
    "period_days": 30,
    "total_commits": 156,
    "active_authors": 8,
    "most_changed_files": [
      {
        "file": "cli/mod.rs",
        "changes": 45,
        "authors": 3,
        "lines_added": 234,
        "lines_removed": 123,
        "last_change": "2024-06-08T15:23:45Z"
      }
    ],
    "hotspot_risk": [
      {
        "file": "cli/mod.rs",
        "complexity_rank": 1,
        "churn_rank": 1,
        "risk_score": 0.95,
        "priority": "high",
        "recommendation": "Focus testing and code review on this file"
      }
    ]
  }
}

4. Dependency Analysis

Comprehensive dependency graph analysis and architectural insights.

Dependency Features:

• Import Graph: Module and package dependencies
• Circular Dependencies: Detection and analysis
• Dependency Depth: How deep dependency chains go
• External Dependencies: Third-party package analysis

Example Dependency Output:

{
  "dependencies": {
    "total_dependencies": 156,
    "direct_dependencies": 23,
    "circular_dependencies": 0,
    "dependency_graph": {
      "depth": 8,
      "strongly_connected_components": 1,
      "fan_out_max": 23,
      "fan_in_max": 45
    },
    "external_dependencies": [
      {
        "name": "serde",
        "version": "1.0.163",
        "usage_count": 45,
        "security_advisories": 0,
        "license": "MIT"
      }
    ],
    "architecture_layers": [
      {"name": "cli", "depth": 0, "dependencies": 5},
      {"name": "server", "depth": 1, "dependencies": 12},
      {"name": "core", "depth": 2, "dependencies": 8}
    ]
  }
}

5. Architecture Overview

High-level architectural insights and structural analysis.

Architecture Metrics:

• Module Organization: How code is structured
• Coupling Analysis: Inter-module dependencies
• Cohesion Analysis: Intra-module relationships
• Layer Architecture: Architectural pattern detection

Example Architecture Output:

{
  "architecture": {
    "modules": 23,
    "layers": ["cli", "server", "analyzer", "core"],
    "coupling_score": 0.23,
    "cohesion_score": 0.87,
    "architectural_patterns": [
      "layered_architecture",
      "dependency_injection",
      "repository_pattern"
    ],
    "design_quality": {
      "separation_of_concerns": "good",
      "single_responsibility": "excellent", 
      "dependency_inversion": "good"
    }
  }
}

Output Formats

JSON Format

Structured data format ideal for tool integration and programmatic processing.

Usage:

pmat analyze deep-context --format json --output analysis.json

Characteristics:

• Machine Readable: Easy to parse and process
• Complete Data: All analysis results included
• API Integration: Perfect for tool integration
• Size: Larger but complete

Markdown Format

Human-readable format ideal for documentation and reports.

Usage:

pmat analyze deep-context --format markdown --output report.md

Example Markdown Output:

# Deep Context Analysis Report

**Generated:** 2024-06-09 10:30:45 UTC  
**Project:** paiml-mcp-agent-toolkit  
**Analysis Duration:** 2.34s  

## Project Overview

- **Total Files:** 298
- **Lines of Code:** 45,231
- **Test Coverage:** 92.3%
- **Primary Language:** Rust (78.5%)
- **TDG Score:** 1.45 (Grade A-)

### Language Distribution

| Language   | Files | Lines | Coverage | Percentage |
|------------|-------|-------|----------|------------|
| Rust       | 234   | 35,420| 94.1%    | 78.5%      |
| TypeScript | 45    | 8,234 | 87.5%    | 18.2%      |
| Python     | 12    | 1,234 | 95.2%    | 2.7%       |

## Complexity Hotspots

### 🔥 Critical Priority
1. **cli/mod.rs:245-389** `handle_analyze_graph()`
   - **Cyclomatic:** 75, **Cognitive:** 125
   - **Recommendation:** Extract sub-functions
   - **Effort:** 4-6 hours

## Quality Assessment

| Metric | Score | Grade |
|--------|-------|-------|
| Overall TDG | 1.45 | A- |
| Test Coverage | 92.3% | A |
| Maintainability | 87.2 | A- |

## Recommendations

### Immediate Actions
1. **Refactor high-complexity functions**
2. **Address code churn hotspots**

### Medium Term  
3. **Improve documentation coverage**
4. **Monitor architectural coupling**

SARIF Format

Static Analysis Results Interchange Format for CI/CD integration.

Usage:

pmat analyze deep-context --format sarif --output security-report.sarif

SARIF Benefits:

• CI/CD Integration: GitHub, Azure DevOps, Jenkins support
• Tool Interoperability: Standard format across tools
• Security Focus: Optimized for security and quality issues
• Rich Metadata: Detailed issue descriptions and fixes

Example SARIF Output:

{
  "$schema": "https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "PMAT Deep Context",
          "version": "0.21.5"
        }
      },
      "results": [
        {
          "ruleId": "complexity/high-cyclomatic",
          "level": "warning",
          "message": {
            "text": "Function has high cyclomatic complexity (75)"
          },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": {"uri": "cli/mod.rs"},
                "region": {"startLine": 245, "endLine": 389}
              }
            }
          ],
          "fixes": [
            {
              "description": {"text": "Extract sub-functions to reduce complexity"}
            }
          ]
        }
      ]
    }
  ]
}

Performance Optimization and Caching

Intelligent Caching System

PMAT’s deep context analysis uses content-based caching for optimal performance.

Cache Strategy:

• Cache Key: SHA-256 hash of file content + analysis options
• Invalidation: Automatic when file content changes
• Storage Location: ~/.pmat/cache/deep-context/
• Retention: 30 days default, configurable

Cache Options:

# Normal caching (default) - use cache when available
pmat analyze deep-context --cache-strategy normal

# Force refresh - ignore existing cache
pmat analyze deep-context --cache-strategy force-refresh

# Offline mode - cache only, fail if not available
pmat analyze deep-context --cache-strategy offline

Incremental Analysis

Smart file change detection for faster subsequent analysis.

Incremental Features:

• Git Integration: Uses git status to identify changed files
• Dependency Tracking: Re-analyzes files when dependencies change
• Parallel Processing: Analyzes independent files concurrently
• Smart Invalidation: Cache invalidation based on file relationships

Example Performance Impact:

# Initial analysis (no cache)
$ time pmat analyze deep-context --format json
real    0m18.456s

# Incremental analysis (minor changes)  
$ time pmat analyze deep-context --format json
real    0m2.123s

# Cache hit (no changes)
$ time pmat analyze deep-context --format json  
real    0m0.089s

Parallel Processing

Multi-core analysis for improved performance on large projects.

Parallel Options:

# Use all available CPU cores
pmat analyze deep-context --parallel

# Specific parallelism level
pmat analyze deep-context --parallel=4

# Combined with other optimizations
pmat analyze deep-context \
  --parallel \
  --cache-strategy normal \
  --include "complexity,quality" \
  --top-files 10

Integration Patterns

Python Integration

Comprehensive Python client for deep context integration.

#!/usr/bin/env python3
"""
Deep Context Integration Examples
"""

import json
import subprocess
import os
from pathlib import Path
from typing import Dict, Any, Optional

class DeepContextAnalyzer:
    def __init__(self, project_path: str = "."):
        self.project_path = Path(project_path).absolute()
    
    def basic_analysis(self) -> Dict[str, Any]:
        """Run basic deep context analysis."""
        cmd = ["pmat", "analyze", "deep-context", "--format", "json"]
        result = subprocess.run(
            cmd, 
            cwd=self.project_path, 
            capture_output=True, 
            text=True,
            check=True
        )
        return json.loads(result.stdout)
    
    def comprehensive_analysis(self, output_file: str = "analysis.json") -> Dict[str, Any]:
        """Run comprehensive analysis with all features."""
        cmd = [
            "pmat", "analyze", "deep-context",
            "--full",
            "--format", "json", 
            "--period-days", "60",
            "--include", "complexity,churn,dependencies,quality",
            "--cache-strategy", "normal",
            "--parallel",
            "--top-files", "20",
            "--output", output_file
        ]
        
        subprocess.run(cmd, cwd=self.project_path, check=True)
        
        with open(self.project_path / output_file) as f:
            return json.load(f)
    
    def incremental_analysis(self) -> Dict[str, Any]:
        """Fast incremental analysis for CI/CD."""
        cmd = [
            "pmat", "analyze", "deep-context",
            "--cache-strategy", "normal",
            "--include", "complexity,quality",
            "--format", "json",
            "--top-files", "5"
        ]
        
        result = subprocess.run(
            cmd,
            cwd=self.project_path,
            capture_output=True,
            text=True,
            check=True
        )
        
        return json.loads(result.stdout)
    
    def quality_gate_check(self, min_grade: str = "B") -> Dict[str, Any]:
        """Perform quality gate analysis."""
        analysis = self.basic_analysis()
        
        quality = analysis.get("quality", {})
        current_grade = quality.get("grade", "F")
        
        # Grade comparison logic
        grade_values = {
            "A+": 12, "A": 11, "A-": 10,
            "B+": 9, "B": 8, "B-": 7,
            "C+": 6, "C": 5, "C-": 4,
            "D+": 3, "D": 2, "D-": 1, "F": 0
        }
        
        current_score = grade_values.get(current_grade, 0)
        required_score = grade_values.get(min_grade, 8)
        
        return {
            "passed": current_score >= required_score,
            "current_grade": current_grade,
            "required_grade": min_grade,
            "current_score": current_score,
            "required_score": required_score,
            "quality_metrics": quality,
            "recommendations": self._generate_recommendations(analysis)
        }
    
    def generate_markdown_report(self) -> str:
        """Generate human-readable markdown report."""
        output_file = "deep_context_report.md"
        cmd = [
            "pmat", "analyze", "deep-context",
            "--format", "markdown",
            "--full",
            "--output", output_file
        ]
        
        subprocess.run(cmd, cwd=self.project_path, check=True)
        
        with open(self.project_path / output_file) as f:
            return f.read()
    
    def _generate_recommendations(self, analysis: Dict[str, Any]) -> list:
        """Generate actionable recommendations based on analysis."""
        recommendations = []
        
        # Complexity recommendations
        complexity = analysis.get("complexity", {})
        if complexity.get("max_cyclomatic", 0) > 20:
            recommendations.append({
                "priority": "high",
                "category": "complexity",
                "action": "Refactor high-complexity functions",
                "details": f"Max complexity: {complexity.get('max_cyclomatic')}"
            })
        
        # Quality recommendations  
        quality = analysis.get("quality", {})
        if quality.get("test_coverage", 100) < 80:
            recommendations.append({
                "priority": "medium",
                "category": "testing",
                "action": "Increase test coverage",
                "details": f"Current coverage: {quality.get('test_coverage')}%"
            })
        
        # Churn recommendations
        churn = analysis.get("churn", {})
        hotspots = churn.get("hotspot_risk", [])
        high_risk_files = [h for h in hotspots if h.get("priority") == "high"]
        
        if high_risk_files:
            recommendations.append({
                "priority": "high", 
                "category": "maintenance",
                "action": "Review high-risk files",
                "details": f"Files: {[f['file'] for f in high_risk_files]}"
            })
        
        return recommendations

# Usage Examples
def main():
    analyzer = DeepContextAnalyzer("/path/to/project")
    
    print("🔍 Running basic deep context analysis...")
    basic_result = analyzer.basic_analysis()
    overview = basic_result.get("overview", {})
    print(f"Project: {overview.get('total_files')} files, {overview.get('total_lines')} lines")
    
    print("\n📊 Checking quality gate...")
    quality_result = analyzer.quality_gate_check("B+")
    status = "✅ PASSED" if quality_result["passed"] else "❌ FAILED"
    print(f"Quality Gate: {status}")
    print(f"Grade: {quality_result['current_grade']} (required: {quality_result['required_grade']})")
    
    if quality_result["recommendations"]:
        print("\n💡 Recommendations:")
        for rec in quality_result["recommendations"]:
            print(f"  {rec['priority'].upper()}: {rec['action']}")
    
    print("\n📄 Generating comprehensive report...")
    comprehensive_result = analyzer.comprehensive_analysis("full_analysis.json")
    print(f"Comprehensive analysis completed: {len(str(comprehensive_result))} characters of data")
    
    print("\n📝 Generating markdown report...")
    markdown_report = analyzer.generate_markdown_report()
    print(f"Markdown report generated: {len(markdown_report)} characters")

if __name__ == "__main__":
    main()

CI/CD Integration

Complete GitHub Actions workflow for deep context quality analysis.

name: Deep Context Quality Analysis

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

env:
  PMAT_VERSION: "0.21.5"

jobs:
  deep-context-analysis:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout Code
      uses: actions/checkout@v4
      with:
        fetch-depth: 0  # Full history for churn analysis
    
    - name: Setup Rust
      uses: actions-rs/toolchain@v1
      with:
        toolchain: stable
        profile: minimal
    
    - name: Install PMAT
      run: cargo install pmat --version ${{ env.PMAT_VERSION }}
    
    - name: Run Deep Context Analysis
      run: |
        echo "🔍 Running comprehensive deep context analysis..."
        pmat analyze deep-context \
          --full \
          --format json \
          --period-days 30 \
          --include "complexity,quality,churn,dependencies,security" \
          --cache-strategy force-refresh \
          --parallel \
          --top-files 20 \
          --output deep-context-analysis.json
    
    - name: Generate SARIF Report
      run: |
        echo "📊 Generating SARIF report for security dashboard..."
        pmat analyze deep-context \
          --format sarif \
          --include "quality,security" \
          --output security-report.sarif
    
    - name: Upload SARIF Results
      uses: github/codeql-action/upload-sarif@v3
      if: always()
      with:
        sarif_file: security-report.sarif
    
    - name: Quality Gate Enforcement
      run: |
        echo "🚪 Enforcing quality gate..."
        
        # Extract quality grade
        GRADE=$(jq -r '.quality.grade // "F"' deep-context-analysis.json)
        TDG_SCORE=$(jq -r '.quality.tdg_score // 0' deep-context-analysis.json)
        TEST_COVERAGE=$(jq -r '.quality.test_coverage // 0' deep-context-analysis.json)
        
        echo "📈 Quality Metrics:"
        echo "  Grade: $GRADE"
        echo "  TDG Score: $TDG_SCORE"
        echo "  Test Coverage: $TEST_COVERAGE%"
        
        # Define quality gate thresholds
        MIN_GRADE="B"
        MIN_COVERAGE=80
        MAX_TDG_SCORE=2.0
        
        # Grade check
        case "$GRADE" in
          "A+"|"A"|"A-"|"B+"|"B")
            echo "✅ Grade requirement met: $GRADE >= $MIN_GRADE"
            GRADE_PASS=true
            ;;
          *)
            echo "❌ Grade requirement failed: $GRADE < $MIN_GRADE"
            GRADE_PASS=false
            ;;
        esac
        
        # Coverage check
        if (( $(echo "$TEST_COVERAGE >= $MIN_COVERAGE" | bc -l) )); then
          echo "✅ Coverage requirement met: $TEST_COVERAGE% >= $MIN_COVERAGE%"
          COVERAGE_PASS=true
        else
          echo "❌ Coverage requirement failed: $TEST_COVERAGE% < $MIN_COVERAGE%"
          COVERAGE_PASS=false
        fi
        
        # TDG score check  
        if (( $(echo "$TDG_SCORE <= $MAX_TDG_SCORE" | bc -l) )); then
          echo "✅ TDG score requirement met: $TDG_SCORE <= $MAX_TDG_SCORE"
          TDG_PASS=true
        else
          echo "❌ TDG score requirement failed: $TDG_SCORE > $MAX_TDG_SCORE"
          TDG_PASS=false
        fi
        
        # Overall gate decision
        if [[ "$GRADE_PASS" == "true" && "$COVERAGE_PASS" == "true" && "$TDG_PASS" == "true" ]]; then
          echo "🎉 Quality gate PASSED - all requirements met"
          exit 0
        else
          echo "🚫 Quality gate FAILED - requirements not met"
          exit 1
        fi
    
    - name: Generate Markdown Report
      if: always()
      run: |
        echo "📝 Generating human-readable report..."
        pmat analyze deep-context \
          --format markdown \
          --full \
          --period-days 30 \
          --include "complexity,quality,churn" \
          --output quality-report.md
    
    - name: Upload Analysis Artifacts
      uses: actions/upload-artifact@v4
      if: always()
      with:
        name: deep-context-analysis
        path: |
          deep-context-analysis.json
          security-report.sarif
          quality-report.md
        retention-days: 30
    
    - name: Comment on PR
      if: github.event_name == 'pull_request' && always()
      uses: actions/github-script@v7
      with:
        script: |
          const fs = require('fs');
          
          // Read markdown report
          let report = '';
          try {
            report = fs.readFileSync('quality-report.md', 'utf8');
          } catch (error) {
            report = '❌ Report generation failed';
          }
          
          // Read quality metrics
          let metrics = {};
          try {
            const analysisData = fs.readFileSync('deep-context-analysis.json', 'utf8');
            const analysis = JSON.parse(analysisData);
            metrics = {
              grade: analysis.quality?.grade || 'Unknown',
              coverage: analysis.quality?.test_coverage || 0,
              tdgScore: analysis.quality?.tdg_score || 0,
              complexityHotspots: analysis.complexity?.hotspots?.length || 0
            };
          } catch (error) {
            console.log('Could not parse analysis results');
          }
          
          const comment = `## 🔍 Deep Context Analysis Report
          
          ### Quality Metrics
          - **Overall Grade:** ${metrics.grade}
          - **Test Coverage:** ${metrics.coverage}%
          - **TDG Score:** ${metrics.tdgScore}
          - **Complexity Hotspots:** ${metrics.complexityHotspots}
          
          ### Detailed Analysis
          <details>
          <summary>Click to expand full report</summary>
          
          ${report}
          
          </details>
          
          ---
          *Generated by PMAT Deep Context Analysis*`;
          
          await github.rest.issues.createComment({
            issue_number: context.issue.number,
            owner: context.repo.owner,
            repo: context.repo.repo,
            body: comment
          });

Language-Specific Deep Analysis

Rust Analysis Capabilities

PMAT provides specialized analysis for Rust projects with deep understanding of Rust-specific patterns.

Rust-Specific Features:

• Ownership Analysis: Borrow checker insights and lifetime complexity
• Trait Analysis: Trait implementations and bounds
• Macro Analysis: Macro usage and expansion complexity
• Unsafe Code: Unsafe block detection and analysis
• Error Handling: Result/Option usage patterns

Example Rust Analysis:

{
  "rust_analysis": {
    "functions": [
      {
        "name": "analyze_complexity",
        "signature": "fn analyze_complexity<'a, T: Analyzer>(input: &'a T) -> Result<Report, Error>",
        "generics": 1,
        "lifetime_params": 1,
        "trait_bounds": 1,
        "unsafe_blocks": 0,
        "macro_calls": 3,
        "error_handling": "result_based"
      }
    ],
    "modules": 23,
    "trait_implementations": 45,
    "unsafe_blocks": 2,
    "macro_definitions": 8,
    "ownership_complexity": {
      "average_lifetimes": 1.2,
      "complex_lifetimes": 5,
      "borrow_checker_insights": [
        "Most functions use simple lifetime patterns",
        "Complex lifetime relationships in parser module"
      ]
    }
  }
}

TypeScript Analysis Capabilities

Comprehensive TypeScript analysis with type system understanding.

TypeScript Features:

• Type System Analysis: Interface complexity and type coverage
• Generic Analysis: Type parameter usage and constraints
• Decorator Analysis: Angular/React decorators
• Import/Export: ES6 module dependency analysis

Example TypeScript Analysis:

{
  "typescript_analysis": {
    "interfaces": 234,
    "type_aliases": 89,
    "generic_types": 156,
    "any_usage": 12,
    "type_coverage": 94.3,
    "complexity_metrics": {
      "interface_complexity": {
        "average_properties": 6.7,
        "max_properties": 23,
        "inheritance_depth": 4
      },
      "generic_complexity": {
        "average_params": 1.8,
        "max_params": 5,
        "constraint_usage": 67
      }
    },
    "decorator_usage": [
      {"name": "@Component", "count": 45},
      {"name": "@Injectable", "count": 23},
      {"name": "@Input", "count": 89}
    ]
  }
}

Python Analysis Capabilities

Python-specific analysis with understanding of Python idioms and patterns.

Python Features:

• Type Hint Analysis: Type annotation coverage and complexity
• Class Analysis: Inheritance patterns and method complexity
• Decorator Analysis: Built-in and custom decorators
• Async Analysis: Coroutine and async/await patterns

Example Python Analysis:

{
  "python_analysis": {
    "classes": 89,
    "functions": 456,
    "modules": 23,
    "type_hint_coverage": 87.3,
    "async_functions": 34,
    "class_hierarchy": {
      "max_inheritance_depth": 5,
      "abstract_classes": 12,
      "multiple_inheritance": 3
    },
    "decorators": [
      {"name": "@property", "count": 67},
      {"name": "@staticmethod", "count": 23},
      {"name": "@classmethod", "count": 15},
      {"name": "@dataclass", "count": 34}
    ],
    "async_patterns": {
      "async_functions": 34,
      "await_expressions": 156,
      "async_generators": 5
    },
    "comprehensions": 145,
    "magic_methods": 78
  }
}

Cross-Language Analysis

For polyglot projects, deep context provides unified analysis across languages.

Multi-Language Features:

• Language Boundaries: Interface analysis across languages
• Build Integration: Unified build system analysis
• Shared Dependencies: Cross-language dependency tracking
• Architecture Consistency: Pattern consistency across languages

Example Cross-Language Analysis:

{
  "cross_language_analysis": {
    "primary_language": "rust",
    "language_distribution": {
      "rust": {"percentage": 78.5, "role": "core_implementation"},
      "typescript": {"percentage": 18.2, "role": "web_interface"},
      "python": {"percentage": 2.7, "role": "scripts_and_tooling"}
    },
    "interface_analysis": {
      "ffi_boundaries": 3,
      "api_endpoints": 23,
      "data_serialization": ["json", "bincode"]
    },
    "build_system_integration": {
      "cargo_toml": true,
      "package_json": true,
      "requirements_txt": true,
      "consistency_score": 0.89
    }
  }
}

Advanced Use Cases

Refactoring Planning

Use deep context analysis to plan large-scale refactoring efforts.

# Identify refactoring candidates
pmat analyze deep-context \
  --include "complexity,churn" \
  --format json \
  --top-files 30 \
  --output refactoring_candidates.json

# Analyze specific modules
pmat analyze deep-context \
  --include-pattern "src/complex_module/*" \
  --format markdown \
  --full \
  --output complex_module_analysis.md

Technical Debt Assessment

Comprehensive technical debt analysis for management reporting.

# Generate executive summary
pmat analyze deep-context \
  --include "quality,complexity" \
  --format markdown \
  --output technical_debt_summary.md

# Detailed assessment with historical data
pmat analyze deep-context \
  --full \
  --period-days 90 \
  --include "quality,churn,complexity" \
  --format json \
  --output debt_assessment.json

Architecture Analysis

Deep architectural insights for system design decisions.

# Comprehensive architecture analysis
pmat analyze deep-context \
  --include "dependencies,architecture" \
  --dag-type "full-dependency" \
  --format json \
  --output architecture_analysis.json

# Module coupling analysis
pmat analyze deep-context \
  --include "dependencies" \
  --dag-type "call-graph" \
  --format markdown \
  --output coupling_analysis.md

Troubleshooting and Best Practices

Performance Optimization Tips

For Large Projects (1M+ LOC):

# Use selective analysis
pmat analyze deep-context \
  --include "complexity,quality" \
  --exclude "churn" \
  --max-depth 5 \
  --parallel \
  --cache-strategy normal

# Exclude expensive directories
pmat analyze deep-context \
  --exclude-pattern "*/node_modules/*" \
  --exclude-pattern "*/target/*" \
  --exclude-pattern "*/vendor/*"

For CI/CD Environments:

# Fast incremental analysis
pmat analyze deep-context \
  --cache-strategy normal \
  --include "quality" \
  --top-files 5 \
  --format sarif \
  --output quick_quality_check.sarif

Common Issues and Solutions

Issue: Analysis takes too long Solution: Use selective analysis and caching

pmat analyze deep-context \
  --include "complexity" \
  --cache-strategy normal \
  --parallel

Issue: Out of memory on large projects Solution: Limit analysis scope and use streaming

pmat analyze deep-context \
  --max-depth 3 \
  --exclude-pattern "*/generated/*" \
  --top-files 10

Issue: Git history analysis fails Solution: Ensure full git history is available

# In CI/CD, use full checkout
git clone --depth=0 <repository>

Integration Best Practices

1. Start with Basic Analysis: Begin with simple analysis before adding complexity
2. Use Caching Effectively: Enable normal cache strategy for repeated analysis
3. Filter Appropriately: Exclude generated code and dependencies
4. Monitor Performance: Track analysis time and adjust scope as needed
5. Combine with Quality Gates: Integrate with CI/CD for automated quality enforcement

Summary

PMAT’s deep context analysis provides comprehensive, multi-dimensional codebase understanding that goes far beyond traditional static analysis tools. By combining complexity metrics, quality assessment, git history analysis, dependency graphs, and architectural insights, deep context enables teams to make informed decisions about refactoring, architecture, and technical debt management.

Key benefits of deep context analysis include:

• Comprehensive Understanding: Multi-dimensional analysis combining complexity, quality, churn, and architecture
• Performance Optimized: Intelligent caching and incremental analysis for fast repeated analysis
• Multiple Output Formats: JSON for tools, Markdown for humans, SARIF for CI/CD
• Language-Specific Insights: Specialized analysis for Rust, TypeScript, Python, and other languages
• Integration Ready: Built for CI/CD pipelines, quality gates, and development workflows

Whether you’re planning a major refactoring, assessing technical debt, analyzing system architecture, or implementing automated quality gates, PMAT’s deep context analysis provides the comprehensive insights needed to make data-driven decisions about your codebase’s health and evolution.