Metadata-Version: 2.4
Name: reposcope-ai
Version: 0.10.0
Summary: Deterministic CLI that audits a Git repository and generates actionable documentation
Project-URL: Homepage, https://github.com/Siggmond/reposcope-ai
Project-URL: Repository, https://github.com/Siggmond/reposcope-ai
Project-URL: Issues, https://github.com/Siggmond/reposcope-ai/issues
Author: RepoScope AI
License: MIT License
        
        Copyright (c) 2026 RepoScope AI
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.
License-File: LICENSE
Keywords: analysis,cli,code-review,developer-tools,github,onboarding,repo-audit,repository
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# RepoScope AI

![PyPI](https://img.shields.io/pypi/v/reposcope-ai)
![Python](https://img.shields.io/pypi/pyversions/reposcope-ai)
![License](https://img.shields.io/github/license/Siggmond/reposcope-ai)
![GitHub Actions](https://img.shields.io/github/actions/workflow/status/Siggmond/reposcope-ai/reposcope.yml)
![GitHub stars](https://img.shields.io/github/stars/Siggmond/reposcope-ai?style=social)
![CLI](https://img.shields.io/badge/interface-CLI-blue)
![GitHub Action](https://img.shields.io/badge/GitHub-Action-2088FF)



**RepoScope AI** is a fast, deterministic **CLI + GitHub Action** that audits a Git repository and generates
**clear, actionable documentation** — so you can understand any codebase in minutes, not hours.

It is designed for **developers, contributors, freelancers, and maintainers** who need to answer one question quickly:

> *“What am I looking at, and where should I start?”*

---

## 🚨 The Problem

Opening an unfamiliar repository usually means wasting time figuring out:
- Where is the entry point?
- How is the project structured?
- Which files are risky or too large?
- Where can I safely make changes?
- What should a new contributor know first?

Most repositories **do not document these answers**.

---

## ✅ The Solution

RepoScope analyzes a repository (local path or GitHub URL) and generates a small set of **opinionated, human‑readable reports**:

- **ARCHITECTURE.md** — high‑level project structure and layout
- **RISKS.md** — large files, missing tests, structural smells
- **ONBOARDING.md** — guidance for new contributors
- **SUMMARY.md / SUMMARY.json** — concise, shareable snapshot

All outputs are:
- Deterministic by default
- Versionable (plain Markdown / JSON)
- Designed to be read by humans, not dashboards

---

## 👥 Who This Is For

- **Contributors** — get context before opening a PR  
- **Freelancers / consultants** — audit a repo quickly and surface risk areas  
- **New team members** — know where to start and what to avoid  
- **Maintainers** — document repo shape and obvious smells automatically  

If you’ve ever said *“I need 30 minutes just to understand this repo”*, this tool is for you.

---

## 📦 Installation

```bash
pip install reposcope-ai
```

Development install (editable):
```bash
pip install -e .
```

Install dev dependencies (tests):
```bash
pip install -e ".[dev]"
```

---

## ⚡ 30‑Second Repo Audit

Analyze a GitHub repository:
```bash
reposcope analyze https://github.com/user/repo
```

Analyze a local repository:
```bash
reposcope analyze .
```

Generated output:
```text
.reposcope/
├── ARCHITECTURE.md
├── RISKS.md
├── ONBOARDING.md
├── SUMMARY.md
└── SUMMARY.json
```

---

## 🧠 Optional AI Explanations (Opt‑In)

RepoScope supports an **AI explanations mode** that adds explanations **only** to existing findings.

```bash
set REPOSCOPE_OPENAI_API_KEY=YOUR_KEY
reposcope analyze . --ai
```

### AI design rules (important):
- AI **never discovers new issues**
- AI receives **structured findings only**
- All AI text is clearly labeled as **AI‑assisted explanation**
- If AI fails, RepoScope silently falls back to non‑AI output

AI is **disabled by default**.

---

## 🤖 GitHub Action (PR Integration)

RepoScope ships with a first‑class GitHub Action.

Create `.github/workflows/reposcope.yml`:

```yaml
name: RepoScope

on:
  pull_request:
  workflow_dispatch:

permissions:
  contents: read
  pull-requests: write

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Siggmond/reposcope-ai@v0.1.0
        with:
          post-comment: "true"
          github-token: ${{ secrets.GITHUB_TOKEN }}
```

The workflow:
- Runs RepoScope on the repo
- Uploads `.reposcope/` as artifacts
- Optionally comments top risks on the PR (opt‑in)

---

## 🏷️ One‑Shot Badge

```md
[![RepoScope](https://img.shields.io/badge/RepoScope-Analyzed-blue)](https://github.com/OWNER/REPO/actions)
```

---

## 📄 Example Output

Excerpt from `RISKS.md`:

```text
## God files (very high line count)
- src/core/big_file.py (1203 lines)
```

---

## ⚠️ Limitations (Honest)

- Analysis is heuristic, not static analysis
- Circular import detection is best‑effort
- Build/run instructions are inferred and may be incomplete
- Very large repos may take longer depending on file count

---

## 🔐 Trust & Safety

- Deterministic output by default
- AI is optional and clearly labeled
- No hallucinated findings
- No black‑box scoring

---

## 📜 License

MIT License

---

If you maintain repositories, review pull requests, or onboard developers,
RepoScope AI is built to save you time.
