repo-graph-kit

A small Python-first repo graph package.

It parses Python repositories with ast, builds a directed graph of modules, imports, classes, functions, methods, and calls, then exports the result as JSON or Mermaid.

Features

• Python AST repo graph builder
• Modules, imports, classes, functions, methods, inheritance, and calls
• Better local symbol and import alias call resolution
• DFS traversal
• BFS shortest path
• Strongly Connected Components using Tarjan's algorithm
• Topological sort for dependency ordering
• Degree centrality for blast-radius and hotspot detection
• Graph diffing for CI and PR tracking
• Dead-code candidate detection
• JSON export
• Mermaid export
• CLI command: repo-graph

Install locally

pip install -e .

Publish to PyPI

This project is ready for standard PyPI packaging:

• build backend: setuptools
• package layout: src/
• CLI entry point: repo-graph

To release a version:

1. Update version in pyproject.toml.
2. Install release tools with python -m pip install --upgrade build twine.
3. Build distributions with python -m build.
4. Verify them with python -m twine check dist/*.
5. Upload to TestPyPI first, then to PyPI.

For automated releases, configure PyPI Trusted Publishing and use the GitHub Actions workflow in .github/workflows/publish.yml.

Build a graph

repo-graph scan ./examples/sample_project \
  --json out/repo-graph.json \
  --mermaid out/repo-graph.mmd \
  --findings out/findings.json \
  --metrics out/metrics.json

Diff two graphs

repo-graph diff previous/repo-graph.json current/repo-graph.json \
  --json out/graph-diff.json

Python API

from repo_graph_kit import build_python_repo_graph
from repo_graph_kit.algorithms import (
    strongly_connected_components,
    top_central_nodes,
    diff_graphs,
)

graph = build_python_repo_graph("examples/sample_project")

print(len(graph.nodes))
print(len(graph.edges))

print(strongly_connected_components(graph, edge_types={"imports"}))
print(top_central_nodes(graph, limit=5, edge_types={"imports", "calls"}))

Current limitations

This is intentionally static-analysis-first. It will not perfectly resolve dynamic imports, monkey patching, dependency injection, framework magic, or runtime-generated calls.

Treat findings like dead-code candidates as review hints, not automatic deletion instructions.