Metadata-Version: 2.4
Name: depscope
Version: 0.1.0
Summary: Architecture observation tool — interactive dependency graph for any codebase
Project-URL: Homepage, https://github.com/sunilkumarjha/repo-graph
Project-URL: Repository, https://github.com/sunilkumarjha/repo-graph
Project-URL: Issues, https://github.com/sunilkumarjha/repo-graph/issues
Author-email: Sunil Kumar Jha <pkjrockzz@gmail.com>
License: MIT
License-File: LICENSE
Keywords: architecture,ast,dependency-graph,static-analysis,visualization
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: gitpython>=3.1
Requires-Dist: jinja2>=3.1
Requires-Dist: networkx>=3.2
Requires-Dist: pathspec>=0.12
Requires-Dist: platformdirs>=4.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13
Requires-Dist: tree-sitter-python>=0.21
Requires-Dist: tree-sitter-typescript>=0.21
Requires-Dist: tree-sitter>=0.21
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# repo-graph

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

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

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

![repo-graph screenshot](https://raw.githubusercontent.com/sunilkumarjha/repo-graph/main/docs/screenshot.png)

---

## 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

```bash
pip install repo-graph
```

Requires Python 3.10+.

---

## Quick start

```bash
# 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

```bash
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:

```yaml
# 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`:

```yaml
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

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

---

## License

MIT
