AutoRepoReview

AI-powered git repository change analysis

Quick Start

Before running AutoRepoReview, you need to configure your API settings. The configuration step will prompt you to enter:

• API URL (e.g., https://api.openai.com/v1)
• Model name (optional, e.g., gpt-4)
• API key (hidden from display)

Option 1: Run via uvx (Recommended)

If you have uv installed, you can run AutoRepoReview directly:

1. Configure AutoRepoReview (first time setup):

   uvx autoreporeview configure
   

   You will be prompted to enter your API URL, model name (optional), and API key.

2. Run AutoRepoReview:

   uvx autoreporeview summary <path> <commit_a> <commit_b>
   

This will automatically download and run the latest version from PyPI.

Option 2: Download Pre-built Binary

1. Download the latest release from GitHub Releases

   • Windows: Download autoreporeview.exe
   • Linux: Download autoreporeview (Linux binary)
   • macOS: Download autoreporeview (macOS binary)

2. Make it executable (Linux/macOS):

   chmod +x autoreporeview
   

3. Configure AutoRepoReview (first time setup):

   # Windows
   .\autoreporeview.exe configure
   
   # Linux/macOS
   ./autoreporeview configure
   

   You will be prompted to enter your API URL, model name (optional), and API key.

4. Run AutoRepoReview:

   # Windows
   .\autoreporeview.exe summary <path> <commit_a> <commit_b>
   
   # Linux/macOS
   ./autoreporeview summary <path> <commit_a> <commit_b>
   

Option 3: Run from GitHub Sources via uvx

1. Configure AutoRepoReview (first time setup):

   uvx --from git+https://github.com/AutoRepoReviewITPD/AutoRepoReview autoreporeview configure
   

   You will be prompted to enter your API URL, model name (optional), and API key.

2. Run AutoRepoReview:

   uvx --from git+https://github.com/AutoRepoReviewITPD/AutoRepoReview autoreporeview summary <path> <commit_a> <commit_b>
   

This builds and runs the tool from the latest GitHub sources.

Option 4: Clone and Run Locally

1. Clone the repository:

   git clone https://github.com/AutoRepoReviewITPD/AutoRepoReview.git
   cd AutoRepoReview
   

2. Install uv (if you don't have it)

3. Configure AutoRepoReview (first time setup):

   # Using uv run
   uv run autoreporeview configure
   
   # Or if running directly (after making executable on Linux/macOS)
   chmod +x autoreporeview
   ./autoreporeview configure
   

   You will be prompted to enter your API URL, model name (optional), and API key.

4. Run AutoRepoReview:

   # Using uv run
   uv run autoreporeview summary <path> <commit_a> <commit_b>
   
   # Or run directly (Linux/macOS)
   ./autoreporeview summary <path> <commit_a> <commit_b>
   

Summary Modes

When running the summary or summary-by-time commands, you'll be prompted to choose a summary mode that focuses on specific aspects of the changes:

1. General summary - Provides an overview of all changes (default)
2. Documentation changes - Focuses specifically on documentation updates, README changes, comments, and docstrings
3. Features add/removed - Highlights new features, removed features, and enhancements to existing functionality
4. Breaking changes - Identifies breaking changes, API modifications, and migration requirements

Each mode uses specialized prompts to generate more focused and relevant summaries based on your specific needs.

Getting Help

You can get help about available commands and options:

• View all available commands:

  ./autoreporeview --help
  # Or with uv run
  uv run autoreporeview --help
  

• View help for a specific command:

  Example:

  autoreporeview summary --help
  # Or with uv run
  uv run autoreporeview summary --help
  

That's it!

Releases and Builds

Creating a Release

To create a new release with pre-built binaries and publish to PyPI:

1. Update version in pyproject.toml:

   # Update the version field in pyproject.toml
   # Example: version = "0.1.1"
   # Or use uv to bump version:
   uv version 0.1.1
   

2. Ensure your changes are committed and pushed:

   git add .
   git commit -m "Your commit message"
   git push origin main
   

3. Create and push a version tag:

   # Create a tag (use semantic versioning: vMAJOR.MINOR.PATCH)
   # Version should match pyproject.toml (with 'v' prefix)
   git tag v0.1.1
   
   # Push the tag to trigger the workflows
   git push origin v0.1.1
   

4. Monitor the workflows:

   • Go to the Actions tab to see the build progress
   • The Build Binaries workflow will automatically build binaries for Windows, Linux, and macOS
   • The Publish to PyPI workflow will automatically build the package and publish to PyPI
   • Both workflows will create/update a GitHub Release and attach their artifacts
   • Once complete, binaries and wheel files will be attached to the release, and the package will be available on PyPI

Important Notes:

• The tag name must start with v followed by a version number (e.g., v0.1.0, v1.2.3)
• The version in pyproject.toml should match the tag (without the v prefix)
• Both workflows trigger automatically on tag push, so no manual release creation is needed
• Before first publish to PyPI, you need to enable trusted publishing:
  1. Go to PyPI Account Settings
  2. Navigate to "Publishing" → "Add a pending publisher"
  3. Add your GitHub repository (e.g., AutoRepoReviewITPD/AutoRepoReview)
  4. Specify the workflow filename: .github/workflows/publish-pypi.yml
  5. Specify the environment: leave empty

Building Locally

For local development and testing, you can build the package and binaries manually.

Building the Package Locally

To build the Python package (wheel and source distribution):

# Build the package using uv
uv build --no-sources

The built packages will be in the dist/ directory.

Note: The --no-sources flag ensures the package builds correctly without tool.uv.sources, which is recommended when publishing.

After building, you can test installing the package locally:

# Install from the built wheel
pip install dist/autoreporeview-*.whl

# Or install from source distribution
pip install dist/autoreporeview-*.tar.gz

Building Binaries Locally

Build standalone executables for Windows, Linux, and macOS using PyInstaller.

Prerequisites: Install build dependencies:

uv sync --group dev

Building for Current Platform:

Build a binary for your current operating system:

uv run pyinstaller --clean --name autoreporeview --onefile autoreporeview_cli.py

The binary will be created in the dist/ directory:

• Windows: dist/autoreporeview.exe
• Linux/macOS: dist/autoreporeview

After building, test the binary:

# Windows
.\dist\autoreporeview.exe summary <path> <commit_a> <commit_b>

# Linux/macOS
./dist/autoreporeview summary <path> <commit_a> <commit_b>

Cross-Platform Building:

PyInstaller doesn't support cross-compilation. To build binaries for other platforms:

1. Using Docker (for Linux builds on Windows/macOS):

   docker run --rm -v "$(pwd):/src" python:3.13 bash -c "cd /src && pip install uv && uv sync --group dev && uv run pyinstaller --clean --name autoreporeview --onefile autoreporeview_cli.py"
   

2. Using WSL (for Linux builds on Windows):

   • Install WSL and Ubuntu
   • Follow the Linux build instructions inside WSL

3. Native builds:

   • Build Windows binaries on Windows
   • Build Linux binaries on Linux
   • Build macOS binaries on macOS

Project Goals

• Automate routine review of repository changes
• Learn about the health and development dynamics of a project
• Quickly discover hidden patterns and issues in code
• Explain complex changes in simple terms using AI

Description

This project develops a code summarizer tool that analyzes GitHub commits to generate concise summaries of code changes. It highlights key modifications, such as added/removed features, bug fixes, and the overall impact on functionality, enabling users to quickly understand what the new code can do without reviewing the entire diff.

Threshold of Success Diagram

The project is considered successful if it meets the following criteria:

• Accurately summarizes at least 80% of simple commits (e.g., single-file changes) based on manual evaluation.
• Processes commits from public GitHub repositories in under 1 minute per commit.
• Provides readable summaries that include change type, affected components, and functional implications.
• Handles common programming languages like Python, JavaScript, and Java.
• Has a user-friendly interface, similar to the command-line interface of Git.
• Easily installable on Linux.

Project Context

flowchart TD
    %% Define nodes with clean labels and subtitles
    A[GitHub Repository<br/><small>Commits & Diffs</small>] 
    B[AutoRepoReview<br/><small>Code Changes Summarizer</small>]
    C[User Interface<br/><small>View Summaries</small>]
    D[Summary Output<br/><small>Text Description</small>]
    E[LLM Provider<br/><small>External API</small>]

    %% Define data flows with arrows
    A -->|Provides commit diff| B
    B -->|Sends code changes| E
    E -->|Returns AI analysis| B
    B -->|Generates summary| C
    B -->|Produces| D

    %% Style the nodes for better readability
    classDef system fill:#4a90e2,stroke:#333,stroke-width:2px,color:white
    classDef output fill:#f39c12,stroke:#333,stroke-width:2px,color:white
    classDef input fill:#27ae60,stroke:#333,stroke-width:2px,color:white
    classDef ui fill:#9b59b6,stroke:#333,stroke-width:2px,color:white
    classDef external fill:#e74c3c,stroke:#333,stroke-width:2px,color:white,dashed

    class A input
    class B system
    class C ui
    class D output
    class E external

Features Roadmap

In Progress

• Commit difference summarization
• CLI for summary viewing

Planned

• PDF report generation for visualization
• Advanced pattern recognition (identify stable, volatile, and recurrently-changing code patterns)
• Contributors activity analysis

Documentation

View Documentation Site with sprint reports, meeting notes, and project documentation.

• ./docs/sprints — Contains scripts, meeting notes, sprint reports, and other iterative documentation reflecting project progress.
• ./docs/ai-usage.md — Details how AI tools have been used within the project.