DepGraph

Python dependency conflict analyzer for monorepos. Detect version conflicts across microservices in < 1 second — before they break your CI/CD pipeline.

The Problem

In a monorepo with 15+ Python microservices, dependency version conflicts are discovered only after a 20-minute CI build fails. Team A upgrades pandas to 2.0, which requires numpy>=1.23.0 — but Team B's ML service pins numpy<1.23.0. DepGraph catches this instantly.

Features

• Scan — Parse pyproject.toml (Poetry + PEP 621) and poetry.lock / uv.lock files across all services
• Detect — Find version conflicts using semantic version constraint analysis (packaging library)
• Simulate — "What if I upgrade package X to version Y?" — see which services break before committing
• Visualize — Generate interactive D3.js dependency graphs with conflict highlighting
• CI/CD Ready — JSON export + exit codes (0 = clean, 1 = warnings, 2 = critical) for pipeline gating

Quick Start

# Install
pip install -e ".[dev]"

# Scan a monorepo for conflicts
depgraph scan ./my-monorepo

# Simulate upgrading a package
depgraph simulate ./my-monorepo --package requests --version 2.31.0

# Generate interactive dependency graph
depgraph visualize ./my-monorepo

# JSON output for CI/CD
depgraph scan ./my-monorepo --format json --output report.json

Example Output

Scan Results

┌─────────────────────────── DepGraph Scan Results ───────────────────────────┐
│                                                                             │
│  [!!] CONFLICTS DETECTED                                                    │
│                                                                             │
│    Services scanned:  3                                                     │
│    Total conflicts:   5                                                     │
│    Critical:          5                                                     │
│    Warnings:          0                                                     │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

   CRITICAL   requests

 Service       │ Version / Constraint
───────────────┼──────────────────────
 analytics-api │ 2.25.1
 auth-service  │ 2.28.0
 ml-service    │ 2.28.0

  >> No single version satisfies all constraints.

Upgrade Simulation

┌─────────────────────────────────────────────────────────────────────────────┐
│  Upgrade Simulation: requests -> 2.28.0                                     │
└─────────────────────────────────────────────────────────────────────────────┘

┌───────────────┬─────────────────┬────────────────────┬──────────────────────┐
│ Service       │     Status      │ Current Constraint │ Details              │
├───────────────┼─────────────────┼────────────────────┼──────────────────────┤
│ auth-service  │ [OK] Compatible │ -                  │ No changes needed    │
│ ml-service    │ [OK] Compatible │ -                  │ No changes needed    │
│ analytics-api │  [!!] Breaking  │ ==2.25.1           │ Does not satisfy     │
└───────────────┴─────────────────┴────────────────────┴──────────────────────┘

┌────────────────────────────── Recommendation ───────────────────────────────┐
│  [PARTIAL] 2 service(s) compatible, 1 would break.                          │
│  Update constraints in breaking services: analytics-api.                    │
└─────────────────────────────────────────────────────────────────────────────┘

Architecture

depgraph/
├── cli.py                 # Click CLI: scan, simulate, visualize
├── parser/
│   ├── models.py          # Dataclasses: Package, Service, Conflict
│   ├── toml_parser.py     # Parse pyproject.toml (Poetry + PEP 621)
│   └── lock_parser.py     # Parse poetry.lock / uv.lock
├── graph/
│   ├── builder.py         # Build NetworkX directed graph
│   ├── analyzer.py        # Conflict detection + circular dep checks
│   └── simulator.py       # "What-if" upgrade simulation
└── reporter/
    ├── console.py         # Rich terminal output (panels, tables, trees)
    ├── json_export.py     # Structured JSON for CI/CD
    └── visualizer.py      # Self-contained D3.js HTML graph

How It Works

1. Scan — Walks the monorepo directory, finds all pyproject.toml files, parses both Poetry and PEP 621 formats
2. Enrich — Reads poetry.lock / uv.lock lockfiles to get exact resolved versions and transitive dependency chains
3. Graph — Builds a NetworkX directed graph: services → packages → transitive packages
4. Analyze — Groups packages by name across services, checks version constraint overlap using packaging.specifiers.SpecifierSet
5. Report — Outputs conflicts with severity classification (critical vs warning) and actionable explanations

CI/CD Integration

# GitHub Actions example
- name: Check dependencies
  run: |
    pip install depgraph
    depgraph scan . --format json --output dep-report.json
  # Exit code 2 = critical conflicts → fails the pipeline
  # Exit code 1 = warnings only
  # Exit code 0 = all clear

Tech Stack

Library	Purpose
NetworkX	Directed dependency graph construction + cycle detection
Click	CLI framework
Rich	Premium terminal output (panels, tables, colored badges)
packaging	PEP 440 version specifier parsing + comparison
tomllib	TOML parsing (stdlib in Python 3.11+)

Running Tests

pip install -e ".[dev]"
pytest tests/ -v

53 passed in 0.43s

License

MIT