Metadata-Version: 2.4
Name: gitopsy
Version: 0.1.0
Summary: Dissect any codebase in seconds
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: pydantic>=2.0
Requires-Dist: jinja2>=3.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: license-file

# Gitopsy — Dissect any codebase in seconds

[![Gitopsy](https://img.shields.io/badge/gitopsy-A-44cc11)](https://github.com/UJameel/gitopsy)
[![PyPI](https://img.shields.io/pypi/v/gitopsy)](https://pypi.org/project/gitopsy/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

> One command. Instant codebase intelligence.

Gitopsy analyzes any repository and produces a **self-contained HTML report** covering architecture, tech debt, onboarding, dependencies, conventions, APIs, security surface, and setup — everything you need to understand an unfamiliar codebase.

## Install

```bash
pip install gitopsy
```

## Usage

```bash
gitopsy .                          # Analyze current directory
gitopsy /path/to/repo              # Analyze any repo
gitopsy --output report.html .     # Custom output path
gitopsy --analyzers arch,debt .    # Run specific analyzers
gitopsy --json .                   # Output raw JSON
gitopsy --badge .                  # Also write a grade SVG badge
gitopsy --save-json .              # Save JSON snapshot alongside HTML
```

### Subcommands

```bash
# Generate a grade badge SVG
gitopsy badge .
gitopsy badge /path/to/repo --output my-badge.svg

# Compare two JSON snapshots
gitopsy --save-json .              # capture snapshot.json
# ... make changes, then re-analyze ...
gitopsy --save-json --output new.html .
gitopsy diff gitopsy-report.json new.json --output diff-report.html
```

## What's in the report?

| Tab | What it tells you |
|-----|-------------------|
| Architecture | Project type, framework, entry points, dependency graph |
| Tech Debt | Score (A-F), hotspots, top 5 recommendations |
| Onboarding | Summary, key files, setup steps, contributors, gotchas |
| Dependencies | All deps with versions, licenses, outdated flags |
| Conventions | Naming, formatting, import style, consistency score |
| APIs | All HTTP routes, CLI commands, public exports |
| Security | Secrets, SQL injection, CORS, auth patterns, risk level |
| Setup | Prerequisites, install steps, env vars, run commands |

## GitHub Action

```yaml
- uses: UJameel/gitopsy@v1
  with:
    path: '.'
    output: 'gitopsy-report.html'
```

Full example workflow:

```yaml
name: Gitopsy Analysis
on: [push]
jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - uses: UJameel/gitopsy@v1
        with:
          path: '.'
          output: 'gitopsy-report.html'
          upload-artifact: 'true'
```

The action outputs `report-path` and `overall-grade` for use in downstream steps.

## Python API

```python
from gitopsy.orchestrator import analyze
from gitopsy.report.renderer import render
from gitopsy.report.badge import generate_badge

report = analyze("/path/to/repo")
render(report, "/tmp/report.html")

# Access structured data
print(report.architecture.framework)   # "flask"
print(report.tech_debt.grade)          # "B"
print(report.tech_debt.overall_score)  # 72

# Generate a badge
svg = generate_badge(report.tech_debt.grade, report.tech_debt.overall_score)
```

## As a Claude Code skill

The `skills/gitopsy/` directory ships a Claude Code skill. Copy it to your
`~/.claude/skills/` directory and run `/gitopsy` from any project.

## Example reports

Live example reports generated by Gitopsy on popular open-source projects:

- [Flask](docs/examples/gitopsy-report-flask.html)
- [FastAPI](docs/examples/gitopsy-report-fastapi.html)
- [Gitopsy itself](docs/examples/gitopsy-self-report.html)

## Design principles

- **Offline-first** — zero mandatory API calls
- **Fast** — <30s on a 10,000-file repo
- **Self-contained** — single HTML file, no external deps to view
- **Git-optional** — works on any directory
- **No AI required** — all analysis is deterministic

## Development

```bash
git clone https://github.com/UJameel/gitopsy
cd gitopsy
pip install -e ".[dev]"
pytest
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add new analyzers.

## License

MIT — see [LICENSE](LICENSE).
