[![PyPI](https://img.shields.io/pypi/v/gitscope)](https://pypi.org/project/gitscope/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org/project/gitscope/)

# GitScope

**Catches the bugs that pass code review.**

## The catch

Flask PR #5898 changed `redirect()`'s default from 302 to 303. Here's what GitScope finds:

```
$ gitscope review main..feature

⚠ GitScope: 2 changes need review

1. DEFAULT VALUE CHANGED: redirect(location, code=302) → redirect(location, code=303)
   File: src/flask/helpers.py:241
   Impact: 5 callers rely on the default:
     auth.py:25  `return redirect(url_for("auth.login"))`
     auth.py:77  `return redirect(url_for("index"))`
     blog.py:81  `return redirect(url_for("blog.index"))`
   Review: Verify callers expect HTTP 303 instead of 302

2. BREAKING CHANGE: dispatch_request(self) → dispatch_request(self, ctx: AppContext)
   File: src/flask/app.py:965
   Impact: 3 external callers need updating:
     views.py:78   `return current_app.dispatch_request()`
     views.py:110  `rv = self.dispatch_request()`
   Review: These callers will break — missing required argument
```

A code reviewer sees `302 → 303`. GitScope sees 5 callers that silently break.

## What GitScope is

GitScope is a **verification layer** for code changes, not a review tool. Reviews give opinions — GitScope gives facts. It uses AST-powered structural analysis of git diffs to catch signature changes, removed symbols, and default value changes, then shows you exactly which callers are affected. 100% precision: when it speaks, it's right. When there's nothing to say, it stays silent.

## Quick Start

```bash
pip install gitscope
gitscope review main..feature
```

Exit codes: `0` = nothing noteworthy, `1` = findings, `2` = error.

## How It Works

1. **Parses the diff** using tree-sitter AST analysis (not regex)
2. **Extracts symbols** — functions, classes, signatures
3. **Detects high-signal changes** — signature changes, removed symbols, default value changes
4. **Scans for callers** — finds files that reference changed symbols
5. **Outputs actionable context** — or stays silent if nothing matters

## Why not X?

**vs CodeRabbit** — They review your code on their servers for $15–30/seat/month. GitScope runs locally, is free, and catches the structural breaks their LLM misses. They comment on every PR; GitScope only speaks when something is actually wrong.

**vs GitHub Copilot / claude-code-action** — Complementary, not competitive. Run GitScope first as cheap, instant triage. If it finds nothing, the diff is structurally safe. Then let the expensive model review what actually matters.

**vs Aider repo-map** — Aider's repo-map uses tree-sitter too, but it's locked inside Aider. GitScope works with any agent, any workflow, any CI pipeline.

## Agent Integration

Add to your `CLAUDE.md`, `.cursorrules`, or equivalent:

```
Before reviewing PRs, run: gitscope review <ref-range> --format json
Exit code 1 means findings — read the JSON output.
Exit code 0 means nothing noteworthy — proceed normally.
```

JSON output for programmatic consumption:

```bash
gitscope review main..feature --format json
```

## Languages

- Python
- TypeScript / JavaScript
- Go
- More coming (Rust, Java, C# planned)

## Philosophy

1. **Silence is a feature.** No findings? No output. Most diffs don't need structural analysis.
2. **Local-first.** Your code never leaves your machine. No SaaS, no API keys, no accounts.
3. **Agent-native.** CLI + JSON output. `pip install` and go. Works with any agent or workflow.
4. **Precision over recall.** We'd rather miss a minor issue than cry wolf on every PR.

## Roadmap

- **v0.2** — GitHub Action, TypeScript/JS improvements
- **v0.3** — Persistent symbol graph (`.gitscope/` directory)
- **v0.4** — `gitscope callers`, `gitscope deps`, `gitscope impact` queries
- **Future** — 8 language support, review rules engine

## License

Apache 2.0 — see [LICENSE](LICENSE) for details.
