Metadata-Version: 2.4
Name: repo-graph-kit
Version: 0.2.0
Summary: Python repo graph builder with AST parsing, SCC, centrality, graph diffing, dead-code candidates, JSON, and Mermaid export.
Author: Akash Birajdar
License: MIT
Keywords: static-analysis,repo-graph,ast,code-graph,python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# 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

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

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

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

## Python API

```python
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.
