Metadata-Version: 2.4
Name: scrutin
Version: 0.1.4
Summary: Local pre-commit review briefs from your git diff — scrutinize changes, stage, and commit with confidence
Author: Scrutin contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/pramod5551/scrutin
Project-URL: Documentation, https://github.com/pramod5551/scrutin/blob/main/docs/USER_GUIDE.md
Project-URL: Repository, https://github.com/pramod5551/scrutin
Project-URL: Issues, https://github.com/pramod5551/scrutin/issues
Keywords: git,code-review,pull-request,pre-commit,developer-tools,diff
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.32.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: pydantic-settings>=2.6.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: python-dotenv>=1.0.0
Dynamic: license-file

# Scrutin

**Review local git changes before you commit** — risk highlights, file diffs, stage/unstage, and commit from the **browser**. Everything runs on your machine.

## Install with Python (PyPI)

### Step 1 — Check requirements

```bash
python3 --version
git --version
```

### Step 2 — Install from PyPI

```bash
pip install scrutin
scrutin --help
```

If `scrutin: command not found`, ensure pip’s script directory is on your `PATH`, or use `python3 -m scrutin.cli --help`.

### Step 3 — Start the server

```bash
cd /path/to/your-project
scrutin serve
```

Your browser should open **http://127.0.0.1:8787**. To start without opening a tab:

```bash
scrutin serve --no-open
```

To pin a specific repository on startup:

```bash
scrutin serve --repo /path/to/your-project
```

### Step 4 — Set the repository in the UI

In the left **Workspace** panel:

1. **Repository** — full path to your git root (e.g. `/Users/you/your-project`)
2. Click **◎ Detect repo** if the field is empty or wrong
3. Confirm the hint under **Compare** shows changed paths

### Step 5 — Choose compare mode and refresh

Use the **Compare** dropdown, then click **↻ Refresh brief**:

| Mode | What it shows |
|------|----------------|
| **working** | Staged + unstaged vs `HEAD` (default for pre-commit) |
| **staged** | Index vs `HEAD` only |
| **unstaged** | Working tree vs index only |
| **branch** | `base…head` (e.g. `main…HEAD`) — set Base and Head when selected |

### Step 6 — Review, stage, and commit

1. Read the dashboard (KPIs, risk overview, summary)
2. In **Files to scrutinize**, open **View diff** and click **Mark reviewed** on each flagged file
3. **Stage** per file or use **Stage all** in the Commit panel
4. Write a commit message or click **Suggest message**, then **Commit staged**

**Commit gate:** **Commit staged** stays disabled until every file in **Files to scrutinize** is marked reviewed *and* at least one change is staged. Files under **Other changed files** do not require “Mark reviewed” but can still be staged and committed.

More UI detail: [Browser guide (step by step)](#browser-guide-step-by-step) below.


## IDE plugins — coming soon

Sidebar plugins are **not listed on the Marketplace yet**. Until they ship, use the **browser UI** from the Python.

**Planned:**

- **VS Code** — Scrutin brief in the activity bar, connected to `scrutin serve` on port **8787**
- **Cursor** — same experience as the VS Code extension
- **IntelliJ** — JetBrains plugin for IDEA and compatible IDEs

All plugins will use the same local server — no cloud required.

---

## First run

1. Open a terminal and go to your project:

   ```bash
   cd ~/your-project
   ```

2. Make sure you have **something to review** (edit files, or stage them):

   ```bash
   git status
   ```

3. Start the server ([Python](#install-with-python-pypi))

4. Click **Refresh brief** after you change files

---

## Browser guide (step by step)

### Start the server

From your project directory (or any path; you can set the repo in the UI):

```bash
cd ~/your-project
scrutin serve
```

Alternative — brief in terminal, then open UI:

```bash
scrutin brief --open
```

### Read the dashboard

The main panel is your **pre-commit brief**:

- **KPIs** — files changed, review progress, lines added/removed, brief engine (Sharpen vs LLM)
- **Diff activity / File mix** — size and risk breakdown
- **Risk overview** — categories (secrets, CI/CD, migrations, etc.)
- **Summary / Why** — what changed and why it matters
- **Risk areas** — tags for the kinds of risk detected

### Review flagged files (“Files to scrutinize”)

1. Click **View diff** — side-by-side **Original** / **Modified** panes
2. In the diff modal:
   - **Stage** / **Unstage** — update the git index for that file
   - **Mark reviewed** — track that you have looked at this file (required before commit is enabled)
3. On the card you can also **Stage** / **Unstage** without opening the diff

The **File review** bar shows progress (e.g. `5 / 12 reviewed`).

### Handle all other changes (“Other changed files”)

Same actions: **View diff**, **Stage**, **Unstage**. These files do **not** require “Mark reviewed” for the commit button.

### Optional: configure LLM

Expand **LLM (optional)** in the sidebar → set provider, model, key → **Save LLM settings** → **Refresh brief**. See [Optional: LLM polish](#optional-llm-polish).

### Stage and commit

- Per file: **Stage** on a card or in the diff modal
- Bulk: **Stage all** in the **Commit** panel
- **Suggest message** → **Commit staged**

### Self-checks and rollback

- **Ask yourself — 5 self-checks** — prompts before you push
- **Rollback** — quick reference for `git restore`, `git revert`, etc.

---

## Compare modes

| Mode | Git equivalent | Typical use |
|------|----------------|-------------|
| **working** | `git diff HEAD` (+ untracked where supported) | “What am I about to commit?” |
| **staged** | `git diff --cached` | “What’s already in the index?” |
| **unstaged** | `git diff` | “What’s changed but not staged?” |
| **branch** | `git diff base...head` | Feature branch vs `main` |

Switch mode → **Refresh brief**.

---

## Review, stage, and commit

### What “scrutinize” means

Scrutin does **not** hide other files. It **prioritizes** a subset:

- Risky paths (secrets, config, migrations, CI/CD, large API surface, etc.)
- If nothing is risky, the **largest** edits in the current scope

Everything else appears under **Other changed files**.

### Review gate

**Commit staged** stays disabled until:

1. Every file in **Files to scrutinize** is **Mark reviewed** (or the list is empty), **and**
2. Git has **staged** changes (`git diff --cached` not empty)

### What gets committed

The button runs **`git commit`** with your message. It commits **whatever is staged in that repo** — including files you staged from “Other changed files” or from the terminal.

Suggested workflow:

```text
Edit files → Refresh brief → Review scrutinize list → Stage (per file or Stage all)
→ Suggest message → Commit staged
```

---

## Optional: LLM polish

Without a key, Scrutin uses **Sharpen heuristics** (local rules, no API calls).

With a key, summary, why, and self-checks can be enhanced. Configure via UI or `.env`:

| Provider | Environment variables |
|----------|------------------------|
| OpenAI | `OPENAI_API_KEY`, `OPENAI_MODEL` |
| Anthropic | `ANTHROPIC_API_KEY`, `ANTHROPIC_MODEL` |
| Google Gemini | `GOOGLE_API_KEY`, `GOOGLE_MODEL` |
| Groq | `GROQ_API_KEY`, `GROQ_MODEL` |
| Mistral | `MISTRAL_API_KEY`, `MISTRAL_MODEL` |

Active provider: `SCRUTIN_LLM_PROVIDER=openai` (or `none`).

**Env file locations** (first match wins):

1. `SCRUTIN_ENV` if set
2. `.env` in the repo
3. `~/.scrutin/.env` (legacy: `~/.reviewpack/.env` still read)

Copy [.env.example](../.env.example) to `.env` as a starting point.

**Privacy:** LLM calls send **metadata** (paths, stats, risk tags) — not full diff bodies.

---

## Optional: ignore noisy paths

Create **`.scrutinignore`** in the repo root (one pattern per line):

```gitignore
.venv/
node_modules/
dist/
*.egg-info/
```

Legacy name **`.reviewpackignore`** is still honored if `.scrutinignore` is missing.

---

## CLI reference

Terminal-only brief (no UI):

```bash
cd ~/your-project
scrutin brief
scrutin brief --json
```

Modes:

```bash
scrutin brief --mode working
scrutin brief --mode staged
scrutin brief --mode unstaged
scrutin brief --mode branch --base main --head HEAD
```

Server:

```bash
scrutin serve
scrutin serve --port 8788 --no-open
scrutin serve --repo /path/to/repo
```

From a saved diff file:

```bash
scrutin brief --diff changes.patch --repo .
```

---

## Troubleshooting

| Problem | What to do |
|---------|------------|
| `scrutin: command not found` | `pip install scrutin` from [PyPI](https://pypi.org/project/scrutin/) or activate the venv where you installed it |
| `Not inside a git repository` | `cd` to the repo root, or run `git init` |
| `No diff to analyze` | Save edits, `git add` some files, or switch compare mode |
| UI empty / wrong repo | Set **Repository** → **Detect repo** → **Refresh brief**; or `scrutin serve --repo /full/path` |
| Port **8787** in use | Stop old server (`Ctrl+C`), or `scrutin serve --port 8788` |
| Brief only in terminal | Use `scrutin serve` or `scrutin brief --open` |
| LLM panel missing / save fails | `pip install -U scrutin`; restart serve |
| Commit button disabled | Mark all scrutinize files reviewed **and** stage at least one file |

## Quick command cheat sheet

```bash
# Python (PyPI)
pip install scrutin
cd ~/your-project
scrutin serve
# → http://127.0.0.1:8787 → Detect repo → Refresh brief → review → Stage all → Commit staged

curl http://127.0.0.1:8787/health
scrutin brief --json
```

---
