RepoRamp
Scan. Understand. Improve.
Python Codebase Intelligence
Turn complex Python repositories into clear, actionable architecture insights.
RepoRamp scans Python source code, maps internal dependencies, identifies architectural issues, and generates Markdown and JSON reports—all without executing the analyzed source files.
Overview
Understanding an unfamiliar Python repository can be difficult. Dependencies are spread across files, circular imports can complicate maintenance, and structural issues are not always obvious.
RepoRamp helps developers understand a codebase through static analysis and actionable quality findings.
Features
| Feature | Description |
|---|---|
| Repository scanning | Discover Python files while excluding common generated and environment directories. |
| AST-based parsing | Extract imports, classes, functions, and methods from Python source. |
| Dependency analysis | Build an internal dependency graph and identify circular dependencies. |
| Quality analysis | Detect empty modules, excessive internal dependencies, and dependency cycles. |
| Markdown reports | Generate readable architecture and quality reports. |
| JSON reports | Export structured analysis data for automation and integrations. |
| CLI | Analyze repositories directly from your terminal. |
Quality Rules
| Rule ID | Finding | Default severity |
|---|---|---|
| QR001 | Module contains no meaningful statements | Warning |
| QR002 | Module has too many distinct internal dependencies | Warning |
| QR003 | Circular dependency detected | Warning |
The excessive-dependency rule uses a default threshold of five distinct dependencies. A warning is a signal to investigate, not proof that the code is defective.
Quick Start
Requirements
- Python version supported by the project configuration
- Git
- Windows PowerShell, macOS, or Linux terminal
Installation
git clone https://github.com/launchforgedev/RepoRamp.git
cd RepoRamp
python -m venv .venv
Activate the environment on Windows PowerShell:
.venv\Scripts\Activate.ps1
Install RepoRamp in editable mode:
pip install -e .
Analyze a repository
Display the available commands:
reporamp --help
Analyze the current repository:
reporamp analyze . --output reporamp-report
Analyze another repository:
reporamp analyze "C:\path\to\your\project" --output reporamp-report
Generated Reports
RepoRamp generates two files in the selected output directory:
report.md— human-readable architecture analysis, dependencies, cycles, and quality findings.report.json— structured analysis data suitable for scripts and other tools.
Example JSON quality finding:
{
"rule_id": "QR002",
"severity": "warning",
"message": "Module depends on 6 internal modules",
"module": "reporamp.cli",
"suggestion": "Review the module's responsibilities and consider splitting it into smaller modules"
}
The example illustrates the output format; actual findings depend on the repository being analyzed.
How It Works
- Scan — discover Python source files.
- Parse — use Python's AST to inspect source structure without running the source code.
- Analyze — resolve internal imports and build a dependency graph.
- Evaluate — apply the available quality rules.
- Report — export architecture information and findings to Markdown and JSON.
Development
Clone the repository and install it in a virtual environment as described above.
Run the test suite:
pytest
Run an analysis against the repository itself:
reporamp analyze . --output test-report
Contributions and bug reports are welcome through the repository's GitHub page.
Roadmap
Potential future improvements include additional quality rules, richer architecture visualizations, configurable rule thresholds, and optional AI-assisted explanations.
License
RepoRamp is licensed under the Apache License 2.0. See LICENSE for details.
Built for developers who want to understand their codebases better.
Metadata
Release files for reporamp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| reporamp-0.1.0.tar.gz | 708.5 kB | Without provenance | Details for reporamp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| reporamp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for reporamp-0.1.0-py3-none-any.whl |
Total release size: 722.2 kB
Release files / reporamp-0.1.0.tar.gz
| Download URL | reporamp-0.1.0.tar.gz |
|---|---|
| Size | 708.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c046a5d98752d570b2d9337ca31fb4bb874e7cddf228246021d9eaad03149207
|
|
BLAKE2b-256 checksum How to use checksums |
8e6e547709b7a5b4bca4abcfa98929fd24ba065ed6a797f8a43e3a880156c25a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.0
|
Release files / reporamp-0.1.0-py3-none-any.whl
| Download URL | reporamp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 13.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
64711b80688010a0b0c5421a2cc48e9d060b207198bfcc52d64ab3950b6eb4d0
|
|
BLAKE2b-256 checksum How to use checksums |
01694359c9a2774ae3ee4f401b507c49e615c38894d00db8117f31382d36a61a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.0
|
Security for reporamp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.