depscope 0.1.0

Architecture observation tool — interactive dependency graph for any codebase

repo-graph

Architecture observation tool — scan any code repository and get a self-contained interactive HTML file showing the full module-level dependency graph.

pip install repo-graph
repo-graph scan /path/to/your/project

Opens in your browser instantly. No server, no config required.

---

Features

• Multi-language — Python, TypeScript, TSX, JavaScript, JSX
• AST-accurate — tree-sitter parsing (regex fallback when unavailable)
• Cycle detection — highlights strongly-connected components in red
• Method-level detail — click an edge to see exactly which functions/methods are called and how many times
• Git churn enrichment — commit frequency (last 90 days) per module
• Interactive viewer built with D3.js:
  • Force-directed layout with zoom, pan, drag-to-pin
  • Click nodes/edges for detail panels
  • Search by module name
  • Focus mode — double-click a node to isolate its 1-hop neighborhood
  • Find path — trace the shortest import path between any two modules
  • Orphan detection — surface modules nothing imports
  • Boundary drawing — draw named regions on the canvas; edges that cross them are highlighted
  • Layout persistence — positions and boundaries auto-save to localStorage; export to .repo-graph.yml so the next scan opens in the same layout
  • Export SVG — download the current graph as a vector image
• Watch mode — repo-graph watch auto-regenerates on file changes

---

Installation

pip install repo-graph

Requires Python 3.10+.

---

Quick start

# Scan the current directory, open result in browser
repo-graph scan

# Scan a specific project
repo-graph scan /path/to/myproject

# Write output to a custom path
repo-graph scan /path/to/myproject --output ~/Desktop/graph.html

# Don't open the browser automatically
repo-graph scan --no-open

# Skip git history (faster for large repos)
repo-graph scan --no-git

# Also emit a JSON summary to stdout
repo-graph scan --json

---

Watch mode

repo-graph watch /path/to/myproject

Polls every 3 seconds and regenerates the HTML whenever any source file changes. Use --interval N to change the poll period. Ctrl+C to stop.

---

Graph viewer — controls

Action	How
Pan	Drag the background
Zoom	Scroll wheel / pinch
Reset zoom	Double-click background
Pin a node	Drag it — it stays where you drop it
Unpin + re-layout	Click Reset layout
Node detail	Single-click a node
Edge detail	Click an edge (shows called methods + counts)
Focus neighborhood	Double-click a node — shows only direct neighbors
Exit focus	"Exit focus" button or Escape
Find shortest path	Click Find path, then click two nodes
Filter to orphans	Click Orphans only
Filter to cycles	Click Show cycles only
Draw a boundary	Click Draw boundary, drag a rectangle, name it
Rename boundary	Click the dotted-underline name in the boundaries bar
Remove boundary	Click × on a boundary pill
Search	Type in the search box
Export SVG	Click Export SVG
Save layout to YAML	Click Export layout in the boundaries bar
Close detail panel	Click ✕ or press Escape

---

Node colours

Colour	Meaning
Blue	Python module
Green	TypeScript / TSX module
Yellow	JavaScript module
Red	In a dependency cycle
Gold	High-fan-in hub (5+ importers)
Dashed orange border	Orphan — nothing imports this module

Node radius scales with fan-in, so architectural hubs are immediately obvious.

---

Configuration

Run repo-graph init to create a .repo-graph.yml in your project root:

# Architectural boundary prefixes — edges crossing them are highlighted orange
boundaries:
  - src/api
  - src/core
  - src/infra

# File globs to include/exclude (defaults shown)
include:
  - "**/*.py"
  - "**/*.ts"
  - "**/*.tsx"
  - "**/*.js"
  - "**/*.jsx"
exclude:
  - node_modules/**
  - .venv/**
  - dist/**

Layout persistence

After arranging the graph, click Export layout in the boundaries bar. It downloads a YAML snippet — merge it into your .repo-graph.yml:

saved_boundaries:
  - name: "API layer"
    rect: {x: 100, y: 200, w: 300, h: 150}

node_positions:
  src/api/routes.py: {x: 250, y: 180}
  src/core/models.py: {x: 400, y: 320}

The next repo-graph scan embeds these positions into the new HTML so the graph opens exactly where you left it.

---

Edge detail panel

Click any edge to see:

• Which functions and methods are imported from the target module
• The call count for each (how many times it's called in the source file)
• Which class a method belongs to (e.g. TTLCache.get, not just get)
• Any symbols that are imported but never called

---

Architecture

src/repo_graph/
  cli.py              — Typer CLI (scan, watch, init)
  config.py           — .repo-graph.yml read/write
  cache.py            — SHA-256-keyed JSON AST cache
  paths.py            — path helpers
  scanner/
    walker.py         — .gitignore-aware file walker
    parser.py         — ParsedFile / ImportRecord / SymbolRecord
    languages/
      python.py       — tree-sitter Python extractor + regex fallback
      typescript.py   — tree-sitter TS/TSX extractor + regex fallback
  graph/
    builder.py        — ModuleGraph, import resolution, symbol refs
    cycles.py         — SCC cycle detection
    metrics.py        — fan-in/out, in_cycle, commit_count_90d
  history/
    git.py            — gitpython commit-frequency enrichment
  viewer/
    generator.py      — Jinja2 HTML renderer
    templates/
      base.html       — self-contained D3 interactive viewer (~1400 lines)

---

Development

git clone https://github.com/sunilkumarjha/repo-graph
cd repo-graph
pip install -e ".[dev]"
pytest tests/

---

License

MIT