A GitHub check that turns ticket labels into hard diff budgets.

Download | Install | Quickstart | Contribute

Why Scalpel?

A three-line bug fix should not arrive as a three-thousand-line rewrite. Add a surgical label and Scalpel blocks unrelated growth before it reaches review.

  SCALPEL  scope guard
  Files  ################--------  2/3
  Lines  #####################---  69/80

  PASS  surgical

Features

• Label-driven budgets: map any PR label to maximum changed files and lines.
• Surgical mode: keep small fixes small by default.
• Hard GitHub check: over-budget PRs fail until reduced or relabeled.
• Audited override: maintainers can apply scalpel-approved after a justification.
• Strictest label wins: overlapping scopes cannot loosen a tighter budget.
• Zero dependencies: one Python file, JSON, and the standard library.
• Readable terminal UI: colored progress bars in local and GitHub logs.

Download

Download the latest checker directly:

curl -fsSLO https://raw.githubusercontent.com/ASVLCII/Scalpel/main/scalpel.py

Or clone the complete template:

git clone https://github.com/ASVLCII/Scalpel.git

Installation

Copy these three files into your repository:

.scalpel.json
scalpel.py
.github/workflows/scalpel.yml

Scalpel needs Python 3.9 or newer and no packages.

Quickstart

1. Set a budget in .scalpel.json:

{
  "surgical": { "files": 3, "lines": 80 }
}

2. Create the matching surgical repository label.
3. Label a pull request. Scalpel runs on open, update, reopen, label, and unlabel events.
4. Require Scalpel scope guard / scope in branch protection.

Usage

Every changed text line, addition or deletion, counts toward lines. Binary changes count as one file and zero lines because Git does not expose binary line counts.

Add as many scopes as your team uses:

{
  "surgical": { "files": 3, "lines": 80 },
  "patch": { "files": 8, "lines": 250 },
  "refactor": { "files": 30, "lines": 1500 }
}

If several configured labels are present, Scalpel applies the lowest file limit and lowest line limit. Unconfigured labels are ignored.

Exceeding a budget

Choose one honest path:

1. Reduce the diff to the ticket's scope.
2. Relabel the PR to reflect its real scope.
3. Explain why the exception is necessary and ask a maintainer to apply scalpel-approved.

The override is intentionally a label, not magic text in a commit message: repository permissions decide who can approve it.

Colors

Set NO_COLOR=1 to disable ANSI colors. Set FORCE_COLOR=1 to force them in CI.

Tests

Run the complete stdlib test suite:

python -m unittest -v
python -m py_compile scalpel.py test_scalpel.py

CI runs it on Linux, Windows, and macOS with Python 3.9 and 3.13.

Contributing

Small, focused pull requests are welcome. Read CONTRIBUTING.md, open an issue for behavioral changes, and keep Scalpel dependency-free unless the standard library cannot solve the problem cleanly.

License

MIT Copyright (c) 2026 ASVLCII.