Mapyr – Repository Insights for VS Code

Mapyr is a VS Code extension that provides comprehensive repository health insights through Git history analysis, code complexity metrics, duplication detection, and an interactive visualization graph. Designed to integrate seamlessly with VS Code's native UI, Mapyr helps development teams make data-driven decisions about code quality and maintenance.

Features

Repository Insights Dashboard

A comprehensive tree view in the VS Code sidebar displaying:

• Bus Factor Analysis: Identify knowledge concentration risks and key contributors
• Contributor Statistics: Track commits, insertions, deletions per developer
• Pull Request Metrics: Analyze PR size distribution, merge times, and review cycles
• Code Churn: Monitor recently modified code that may indicate instability
• Branch Lifetime: Track active branches and identify stale long-lived branches
• Code Hotspots: Discover frequently modified files that need attention
• Complexity Leaders: Surface files with high cyclomatic complexity
• Duplication Offenders: Identify files with the most code duplication

Interactive Code Graph

A Cytoscape-powered visualization that:

• Displays your repository structure as an interactive node graph
• Color-codes files by health metrics (Maintainability Index, Cyclomatic Complexity, Duplication)
• Shows import dependencies between files
• Auto-collapses directories for clean visualization
• Provides tooltips explaining each metric when hovering
• Allows direct file navigation by clicking nodes
• Features larger, more readable text for better UX
• Uses optimized spacing for clearer visualization

Detailed Metrics

Each file is analyzed for:

• Maintainability Index (0-100): Higher is better. Measures how easy code is to maintain

  • 85 = Excellent

  • 65-85 = Moderate
  • <65 = Difficult
• Cyclomatic Complexity: Lower is better. Counts independent code paths
  • 1-10 = Simple
  • 11-20 = Moderate

  • 20 = Complex

• Logical Lines of Code: Executable statements (excludes comments/blanks)
• Duplication Percentage: Amount of duplicated code
• File Ownership: Primary contributor based on git blame analysis

File Ownership Reports

Right-click any file to view:

• Line-by-line ownership breakdown
• Percentage contribution by each developer
• Historical contribution patterns

Usage

Getting Started

1. Open the Mapyr View

   • Click the graph icon in the Activity Bar (left sidebar)
   • Or run Mapyr: Open Metrics Graph from Command Palette

2. Refresh Metrics

   • Click the refresh icon in the view toolbar
   • Or run Mapyr: Refresh from Command Palette
   • Initial analysis may take 30-60 seconds depending on repository size

3. Explore the Graph

   • Single-click a file node to view detailed metrics
   • Double-click a file node to open the file in editor
   • Single-click a directory to reveal more files
   • Double-click a directory to collapse/expand
   • Hover over metrics to see explanations
   • Click X button to close the metrics panel
   • Double-click canvas to fit all visible nodes

4. Review Insights

   • Expand sections in the Repository Insights tree view
   • Examine bus factor, hotspots, and complexity leaders
   • Identify files that need refactoring or attention

Commands

Understanding the Graph

Node Colors:

• 🔵 Blue: Healthy code (low complexity, good maintainability)
• 🟠 Orange: Warning (moderate complexity or maintainability issues)
• 🔴 Red: At-risk (high complexity, low maintainability, or high duplication)
• 🟡 Yellow border: Hub files (index.js, index.ts, etc.)

Edges:

• 📍 Blue arrows: Import/dependency relationships

Metrics Tooltip: Hover over any metric in the selection panel to learn:

• What the metric measures
• How to interpret the values
• What ranges are healthy vs concerning

Metrics Explained

Bus Factor

The minimum number of team members that need to be "hit by a bus" before the project is in serious trouble. Calculated by finding how many developers account for 50% of code contributions.

• 1: Critical risk - one person knows everything
• 2-3: Moderate risk - small group controls most code
• 4+: Low risk - knowledge is well-distributed

Code Churn

Percentage of recently written code (last 3 weeks) that has been modified multiple times. High churn may indicate:

• Unclear requirements
• Design issues
• Insufficient planning
• Bugs in new code

Cyclomatic Complexity

Measures the number of linearly independent paths through code. Used to determine testing effort and maintainability.

Maintainability Index

A compound metric (0-100) combining:

• Cyclomatic complexity
• Lines of code
• Halstead volume
• Comment density

Acknowledgments

Built with:

• Cytoscape.js - Graph visualization
• escomplex - Complexity analysis
• jscpd - Duplication detection
• VS Code Extension API

Mapyr - Make your repository metrics visible and actionable.