Skip to main content

RepoRamp Logo

RepoRamp

Scan. Understand. Improve.
Python Codebase Intelligence


Python License Tests

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

  1. Scan — discover Python source files.
  2. Parse — use Python's AST to inspect source structure without running the source code.
  3. Analyze — resolve internal imports and build a dependency graph.
  4. Evaluate — apply the available quality rules.
  5. 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)

Source distribution for reporamp 0.1.0
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)

Table of built distributions (wheels) for reporamp 0.1.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page