Debtmap GitHub Action

Analyze code complexity and identify high-risk areas in your Rust codebase. Debtmap helps you prioritize refactoring and testing efforts by identifying complex code and correlating it with test coverage to find genuinely risky functions.

Features

• 📊 Complexity Analysis: Identifies overly complex code using cyclomatic and cognitive complexity metrics
• 🎯 Risk Prioritization: Combines complexity with test coverage to find high-risk code (high complexity + low coverage)
• 🔍 God Object Detection: Finds classes and modules with too many responsibilities
• 📉 False Positive Reduction: Uses entropy analysis to distinguish genuine complexity from repetitive patterns
• 📋 Actionable Recommendations: Specific guidance on what to refactor or test first
• 🚀 Fast: Uses pre-built Rust binaries, no compilation required
• ⚙️ Configurable: Use .debtmap.toml in your repo for custom thresholds and settings

Quick Start

Basic Analysis (No Coverage)

- name: Analyze Code Complexity
  uses: iepathos/debtmap-action@v1
  with:
    path: .

With Coverage (Recommended)

# Generate coverage data first
- name: Generate Coverage
  run: cargo llvm-cov --lcov --output-path lcov.info

# Analyze with risk correlation
- name: Analyze Code Complexity
  uses: iepathos/debtmap-action@v1
  with:
    lcov-file: lcov.info

Inputs

Input	Description	Required	Default
lcov-file	Path to LCOV coverage file (enables risk correlation)	No	-
coverage-file	Alias for lcov-file (for compatibility)	No	-
path	Path to the project to analyze	No	.
debtmap-version	Debtmap version to use (e.g., latest, v0.1.0)	No	latest
command	Command to run: analyze (show issues) or validate (enforce thresholds)	No	analyze
format	Output format: markdown, json, or text	No	markdown
output-file	Output file path (auto-generated if not specified)	No	-
fail-on-threshold	Fail job if tech debt exceeds thresholds (validate mode only)	No	false

Outputs

Output	Description
report-path	Path to the generated markdown report

Configuration

For advanced configuration (thresholds, filters, etc.), create a .debtmap.toml file in your repository root. See the debtmap documentation for all available options.

Usage Examples

Complete CI Workflow

name: Code Quality Analysis
on: [push, pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Rust
        uses: dtolnay/rust-toolchain@stable

      - name: Install cargo-llvm-cov
        uses: taiki-e/install-action@cargo-llvm-cov

      - name: Generate Coverage
        run: cargo llvm-cov --lcov --output-path lcov.info

      - name: Analyze Complexity
        uses: iepathos/debtmap-action@v1
        with:
          lcov-file: lcov.info

      - name: View Report
        run: cat debtmap-report.md

Without Coverage

name: Complexity Check
on: [push]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Analyze Complexity
        uses: iepathos/debtmap-action@v1

With Custom Configuration

# .debtmap.toml in your repo
[thresholds]
complexity = 15
duplication = 100

[god_object]
max_methods = 25
max_fields = 10

name: Custom Analysis
on: [push]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Generate Coverage
        run: cargo llvm-cov --lcov --output-path lcov.info

      - name: Analyze with Custom Config
        uses: iepathos/debtmap-action@v1
        with:
          lcov-file: lcov.info
          # Config comes from .debtmap.toml

Tech Debt Quality Gate (Validate Mode)

Use validate command to enforce thresholds and fail CI if tech debt exceeds limits:

name: Tech Debt Quality Gate
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Rust
        uses: dtolnay/rust-toolchain@stable

      - name: Install cargo-llvm-cov
        uses: taiki-e/install-action@cargo-llvm-cov

      - name: Generate Coverage
        run: cargo llvm-cov --lcov --output-path lcov.info

      # Show analysis for visibility
      - name: Analyze Tech Debt
        uses: iepathos/debtmap-action@v1
        with:
          coverage-file: lcov.info
          command: analyze

      # Enforce thresholds (fails if exceeded)
      - name: Validate Thresholds
        uses: iepathos/debtmap-action@v1
        with:
          coverage-file: lcov.info
          command: validate
          format: json
          fail-on-threshold: true

Configure thresholds in .debtmap.toml:

[thresholds]
complexity = 15
cognitive_complexity = 10
max_debt_density = 0.25  # Fail if >25% of code is high-risk

Different Output Formats

# JSON output for programmatic processing
- uses: iepathos/debtmap-action@v1
  with:
    format: json
    output-file: tech-debt.json

# Plain text for simple reports
- uses: iepathos/debtmap-action@v1
  with:
    format: text
    output-file: tech-debt.txt

# Markdown (default) for GitHub summaries
- uses: iepathos/debtmap-action@v1
  with:
    format: markdown

Alternative Coverage Tools

Debtmap accepts any LCOV-format coverage file. Here are common ways to generate it:

# With cargo-tarpaulin (Linux only)
- name: Generate Coverage
  run: |
    cargo install cargo-tarpaulin
    cargo tarpaulin --out Lcov --output-dir ./coverage
- uses: iepathos/debtmap-action@v1
  with:
    lcov-file: ./coverage/lcov.info

# With grcov
- name: Generate Coverage
  run: |
    cargo install grcov
    export CARGO_INCREMENTAL=0
    export RUSTFLAGS="-Cinstrument-coverage"
    cargo build
    cargo test
    grcov . -s . --binary-path ./target/debug/ -t lcov --branch --ignore-not-existing -o lcov.info
- uses: iepathos/debtmap-action@v1
  with:
    lcov-file: lcov.info

# With cargo-llvm-cov (Recommended)
- uses: taiki-e/install-action@cargo-llvm-cov
- name: Generate Coverage
  run: cargo llvm-cov --lcov --output-path lcov.info
- uses: iepathos/debtmap-action@v1
  with:
    lcov-file: lcov.info

Understanding the Analysis

Debtmap identifies and prioritizes technical debt using:

• Complexity Metrics: Cyclomatic and cognitive complexity to find hard-to-maintain code
• Coverage Correlation: Combines complexity with test coverage to identify high-risk areas
• God Object Detection: Finds classes/modules with too many responsibilities
• Pattern Recognition: Reduces false positives from repetitive but simple code
• Actionable Recommendations: Tells you exactly what to refactor or test first

Two Operating Modes

Analyze Mode (Default): Shows detailed tech debt analysis with recommendations. Great for visibility and understanding where issues are. Does not fail the job.

Validate Mode: Enforces quality gates by checking if tech debt exceeds configured thresholds. Use with fail-on-threshold: true to block merges that introduce excessive debt.

Binary Releases

The action automatically downloads pre-built binaries from the debtmap releases. Supported platforms:

• Linux x86_64
• Linux aarch64
• macOS x86_64
• macOS aarch64 (Apple Silicon)

Troubleshooting

Coverage File Not Found

If using coverage, ensure your coverage generation step completes successfully:

- name: Generate Coverage
  run: cargo llvm-cov --lcov --output-path lcov.info

- name: Verify Coverage File
  run: ls -la lcov.info

- name: Run Debtmap
  uses: iepathos/debtmap-action@v1
  with:
    lcov-file: lcov.info

Analysis Takes Too Long

For very large projects:

• Use --max-files in a .debtmap.toml config to limit analysis
• Disable expensive features like call graph analysis if not needed
• Consider analyzing only changed files in PRs

High Memory Usage

For large projects, ensure adequate runner resources:

runs-on: ubuntu-latest  # 7GB RAM
# or
runs-on: ubuntu-latest-16-core  # More resources

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

License

This action is distributed under the MIT License. See LICENSE for details.

Support

• 🐛 Report issues
• 💡 Request features
• 📖 Read debtmap docs