Metadata-Version: 2.4
Name: ruth-code
Version: 0.1.0
Summary: Interactive codebase topology visualizer — Google Maps for your repo
Project-URL: Homepage, https://github.com/kossisoroyce/ruth
Project-URL: Repository, https://github.com/kossisoroyce/ruth
Project-URL: Issues, https://github.com/kossisoroyce/ruth/issues
Author: Electric Sheep Africa
License-Expression: MIT
License-File: LICENSE
Keywords: architecture,code-analysis,code-quality,codebase,dependency-graph,developer-tools,topology,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: rich>=13.0
Requires-Dist: tree-sitter>=0.21.0
Requires-Dist: uvicorn[standard]>=0.27.0
Requires-Dist: watchfiles>=0.21.0
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Description-Content-Type: text/markdown

# Ruth

**Google Maps for your codebase.**

Ruth parses your codebase, builds a dependency graph, detects landmarks (entry points, orchestrators, hubs), overlays code quality metrics, and renders it as an explorable visual map in the browser.

## Install

```bash
pip install ruth-code
```

## Quick Start

```bash
ruth serve ./your-project
```

Open `http://localhost:4150` and explore.

## What You Get

**Landmarks & Points of Interest** — Ruth auto-detects the key files in your codebase:
- **Entry Points** — `main.py`, `index.ts`, `cli.py` — where execution begins
- **Orchestrators** — files that import many modules, wiring your app together
- **Hubs** — core dependencies imported by everyone
- **Islands** — disconnected files that may be dead code

**Dependency Path Tracing** — Click two nodes to trace the import chain between them, like getting directions on a map.

**Traffic Lanes** — Import edges scale in thickness based on how heavily two files are connected.

**Overlays** — Switch between views like map layers:
- **Complexity** — cyclomatic complexity heatmap (green to red)
- **Security** — vulnerability overlay (Semgrep/OSV integration)
- **Coverage** — test coverage mapping (lcov/coverage.json)

**Multi-Language** — Python, TypeScript, JavaScript, Rust, Go, Java, Ruby, C/C++.

**Live** — WebSocket-powered real-time updates. Edit a file, see the graph change.

## Commands

```bash
# Start the visualization dashboard
ruth serve /path/to/project

# Analyze and output graph as JSON
ruth analyze /path/to/project -o graph.json

# Quick project scan
ruth scan /path/to/project
```

## Keyboard Shortcuts

| Key | Action |
|-----|--------|
| `Cmd+K` | Command palette — search and jump to any node |
| `/` | Focus search filter |

## Requirements

- Python 3.10+
- Node.js (for development only — the frontend is pre-built)

## License

MIT — Electric Sheep Africa
