[![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 structural breaks that pass code review.**

## The catch

Flask changed `redirect()`'s default from 302 to 303 ([PR #5898](https://github.com/pallets/flask/pull/5898)). A reviewer sees a one-line diff. GitScope sees 7 callers that silently change behavior:

```
$ gitscope review eca5fd1d~1..eca5fd1d

⚠ GitScope: 2 changes need review

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

2. DEFAULT VALUE CHANGED: App.redirect(self, location, code=302) → App.redirect(self, location, code=303)
   File: src/flask/sansio/app.py:935
   Impact: 7 callers rely on the default
   Review: Verify callers expect the new default value
```

Based on real output from GitScope run against Flask commit `eca5fd1d`. Output lightly condensed for readability — run the command yourself to see the full version.

## What GitScope is

GitScope is a **verification layer** for code changes. Not a review tool — reviews give opinions, GitScope gives facts. It uses tree-sitter AST analysis to detect structural changes in git diffs and traces their impact through your codebase.

**What it catches:** Function signature changes, removed/renamed symbols, default value changes — and shows you every caller affected.

**What it doesn't catch:** Logic bugs, behavioral changes beyond signatures, performance issues, security vulnerabilities.

When there's nothing structural to report, it stays silent (exit code 0, no output).

## 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** — CodeRabbit reviews code on their servers for $15–30/seat/month. GitScope runs locally, is free, and does a different kind of analysis: structural verification rather than LLM-powered review. They're complementary — CodeRabbit reviews intent, GitScope verifies structure.

**vs GitHub Copilot / claude-code-action** — Complementary, not competitive. Run GitScope first as cheap, instant structural triage. Then let the expensive model focus on 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** (most mature — extensive real-world validation)
- TypeScript / JavaScript
- Go
- More planned (Rust, Java, C#)

## 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.
