blot-git 0.4.0__tar.gz → 0.6.0__tar.gz

{blot_git-0.4.0 → blot_git-0.6.0}/.pre-commit-hooks.yaml

@@ -1,6 +1,6 @@
 # Lets users of the pre-commit framework add blot with:
 #   - repo: https://github.com/Sym-jay/Blot
-#     rev: v0.4.0
+#     rev: v0.6.0
 #     hooks: [{id: blot}]
 # The first commit indexes the repo's history; later commits refresh the index incrementally.
 - id: blot

blot_git-0.6.0/CLAUDE.md

@@ -0,0 +1,68 @@
+# Blot: notes for Claude
+
+Blot is a pre-commit check that has read a repo's git history. It warns (never blocks) when a commit
+removes a fix (`removed-fix`), re-adds a line a fix removed (`readded-bug`), or forgets a file that
+always changes with another (`forgot-related-file`). Mascot: Sora the slime. Owner: Shyam (GitHub
+`Sym-jay`). PyPI name `blot-git`, command `blot`. Repo: https://github.com/Sym-jay/Blot
+
+## Layout
+- `src/blot/`: stdlib-only on Python 3.11+ (3.10 also needs `tomli`; keep it that way)
+  - `cli.py` commands: index, check, why, install-hook, guard, install-agent-hook, bench. `check`/`why` build/refresh the index themselves.
+  - `index.py` builds `.git/blot.db` (parallel `git log` slices for 2000+ commits); `store.py` SQLite schema v2
+  - `classify.py` fix severity 0/1/2 + refactor detection: most precision lives here
+  - `checks/` one file per check; `trace.py` blame that follows lines past refactor commits
+  - `guard.py` (Claude Code hook; installer in `hooks.py`), `why.py`, `github.py` (`index --github` via `gh api graphql`), `bench.py` (cases + `--replay N`)
+- `bench/cases.json` scripted real-world cases (32/32); `bench/labels/` hand verdicts for every replay
+  warning on the 5 reference repos; `bench/RESULTS.md` replay numbers and precision
+- `action.yml` GitHub Action; `.github/workflows/blot.yml` runs it on Blot's own PRs
+- `assets/sora/build_sprites.py` and `assets/demo/make_demo.py` regenerate the mascot and demo GIF
+- `docs/PRD.md` roadmap; `docs/PYPI.md` is the PyPI page (no relative images there)
+
+## Develop
+```bash
+python -m venv .venv && .venv/Scripts/python -m pip install -e ".[dev]"
+.venv/Scripts/python -m pytest -q
+.venv/Scripts/blot bench --workdir <short path>     # must stay 32/32
+```
+- Any change to `classify.py` or a check: on each of the 5 clones, checked out at the `head` in its
+  labels file, run `blot bench --replay 500 --labels bench/labels/<repo>.json --update-labels`. Keep a
+  rule only if precision rises and no `useful` warning disappears; label any new `null` verdicts
+  (rules in bench/README.md). Targets: ≤ 1 warning / 10 commits, precision ≥ 80%.
+- Clones live in `%LOCALAPPDATA%\Temp\wl\replay\` (labelled heads) and `...\wl\bench\` (case runs).
+- `blot check` must stay under ~500 ms and never fail a commit because of Blot's own errors.
+
+## Release (each release so far followed this)
+1. Branch, bump `version` in `pyproject.toml` and `src/blot/__init__.py`, PR, wait for CI (6 jobs + "blot").
+2. Squash-merge, then `gh release create vX.Y.Z --target main`: `.github/workflows/release.yml`
+   publishes to PyPI via trusted publishing. PyPI/pip can lag a minute or two after publish.
+3. Verify: fresh venv, `pip install blot-git==X.Y.Z`, run `blot why src/flask/app.py:355` on a Flask clone.
+
+## Conventions
+- Work on a branch, open a PR, merge only when the owner says so. Squash-merge.
+- No `Co-Authored-By` trailer in commits or PRs (the owner's choice); PR bodies end with the Claude Code line.
+- Contributors (e.g. O1sumitkumar) should comment on the issue before starting a PR.
+- Never claim results that weren't run; label replay findings honestly (e.g. the Express
+  CVE-2024-51999 advisory was later withdrawn, so its revert was deliberate).
+
+## Windows gotchas (this machine)
+- Long paths: clone big repos and make venvs under a short path like `%LOCALAPPDATA%\Temp\wl\`.
+- The user folder has a space ("N Jayasankar"): quote paths; don't word-split commands in loops.
+- Writing code through bash heredocs mangles `\b`, `\n`, `\s`: use the Edit tool for regexes/strings.
+- `gh api` paths: no leading slash (Git Bash rewrites it).
+
+## State (2026-11-06)
+- Released 0.6.0: checks, `why`, `--github`, agent guard (`blot guard` / `install-agent-hook`, tested
+  live in Claude Code 2026-11-06), bench/replay with labels, parallel indexing, pre-commit framework
+  support (`rev: v0.6.0`), GitHub Action (`uses: Sym-jay/Blot@v0.6.0`).
+- Launch: dev.to post published 2026-10-24; the CVE sentence there should mention the withdrawn advisory.
+- Open issues: #2–#4, #6 (bench cases); #33 (live guard report), #34 (quiet readded-bug case), #35–#36 (noise).
+- Precision (0.5.0, measured 2026-10-30): 57/109 useful (52%); Django 1.19 / 10 commits, others ≤ 0.6.
+  `forgot-related-file` has 0 useful warnings in 45 labelled; candidate to become opt-in.
+- `--github` measured (2026-11-01): precision unchanged (52.5%), +7 useful warnings, almost no demotions.
+- Tried and dropped (2026-11-01): "fix word + PR number" as an offline fix rule: +85 warnings at 22%
+  useful. Don't retry it without a narrower signal (see bench/RESULTS.md).
+- Agent guard (2026-11-04, branch `agent-guard`, unreleased): `blot guard` is a Claude Code PreToolUse
+  hook (`src/blot/guard.py`) running removed-fix + readded-bug on a proposed Edit/Write/MultiEdit;
+  `blot install-agent-hook` edits `.claude/settings.json`. Flask edit of `self_ref` warns in ~450 ms.
+  Not yet tried in a live Claude Code session.
+- Next: remaining noise (renames, API swaps, added arguments, docstrings) in bench/RESULTS.md.

{blot_git-0.4.0 → blot_git-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: blot-git
-Version: 0.4.0
+Version: 0.6.0
 Summary: A pre-commit check that has read your project's history: warns when a change removes a fix, re-adds a fixed bug, or forgets a file that always changes too.
 Project-URL: Homepage, https://github.com/Sym-jay/Blot
 Project-URL: Issues, https://github.com/Sym-jay/Blot/issues
@@ -46,6 +46,10 @@ blot why src/app.py:42   # which commit explains this line, skipping refactors
 blot index --github  # optional: issue/PR titles and labels via the gh CLI
 ```
 
-> **Status:** pre-alpha. All three checks work. Replayed on 500 recent commits each of Flask, requests, Express, Django and React, Blot warns on 0.6–10% of commits; see the bench results on GitHub. Please report false alarms.
+**Guard coding agents.** `blot install-agent-hook` adds a Claude Code hook that runs the same checks on
+an edit an agent is about to make, so the agent sees "this line exists because of fix 8efea0c" before
+it "simplifies" it away. It warns by default; `--ask` makes Claude Code ask you first.
+
+> **Status:** pre-alpha. All three checks work. Replayed on 500 recent commits each of Flask, requests, Express, Django and React, Blot warns on 0.6–9.5% of commits, and about half of its warnings (labelled by hand) are worth a reviewer's time; see the bench results on GitHub. Please report false alarms.
 
 Meet Sora the slime, read the docs, or contribute on GitHub: https://github.com/Sym-jay/Blot

{blot_git-0.4.0 → blot_git-0.6.0}/README.md

@@ -22,7 +22,7 @@ It runs locally, needs no account or AI, and stays quiet unless the history give
 
 *A real run on Flask. Plain `git blame` points to a 2023 commit that only moved this line; Blot traces past it to the 2020 fix that explains it. (Regenerate with `python assets/demo/make_demo.py`.)*
 
-> **Status:** pre-alpha. Milestones M1 and M2 are done: `blot index` builds the history index (Flask's 3,800 commits in ~2 s), `blot install-hook` wires up git, and `blot check` runs the three checks. On Flask it traces an edit to `self_ref = weakref.ref(self)` past the 2023 file split to the 2020 fix, in under 500 ms. Replayed on the last 500 commits of Flask, requests, Express, Django and React, it warns on 0.6–10% of commits; see [bench/RESULTS.md](bench/RESULTS.md). Roadmap: [PRD](docs/PRD.md#12-milestones-4-weeks-part-time).
+> **Status:** pre-alpha. Milestones M1 and M2 are done: `blot index` builds the history index (Flask's 3,800 commits in ~2 s), `blot install-hook` wires up git, and `blot check` runs the three checks. On Flask it traces an edit to `self_ref = weakref.ref(self)` past the 2023 file split to the 2020 fix, in under 500 ms. Replayed on the last 500 commits of Flask, requests, Express, Django and React, it warns on 0.6–9.5% of commits, and about half of its warnings (57 of 109, each labelled by hand) are worth a reviewer's time; see [bench/RESULTS.md](bench/RESULTS.md). Roadmap: [PRD](docs/PRD.md#12-milestones-4-weeks-part-time).
 
 ## Meet Sora
 
@@ -71,6 +71,42 @@ src/flask/app.py:355
 
 `blot why FILE:LINE` (or `FILE:START-END`) finds the commit that explains a line, skipping commits that only moved it. Plain `git blame` stops at the refactor.
 
+## Guard coding agents
+
+Coding agents are the most likely to "clean up" a line they don't understand. `blot guard` is a
+[Claude Code](https://code.claude.com/docs/en/hooks) `PreToolUse` hook on `Edit`, `Write` and `MultiEdit`:
+it runs the `removed-fix` and `readded-bug` checks on the edit the agent is about to make, and hands any
+finding to the agent as context:
+
+```
+blot: 1 warning
+
+  ! removed-fix  src/flask/app.py:355
+    You're removing or changing a line that a bug fix added.
+    Check that the bug it fixed can't come back.
+    8efea0c "Break reference cycle created by default in Flask instances." (2020-10-03)
+    traced past refactor 0ec7f71 "Split the App and Blueprint into Sansio and IO parts"
+Run `blot why FILE:LINE` for the full history before you change it.
+```
+
+```bash
+blot install-agent-hook           # adds the hook to .claude/settings.json and builds the index
+blot install-agent-hook --local   # or .claude/settings.local.json, which isn't committed
+blot install-agent-hook --ask     # also ask you to approve edits that touch a fix
+```
+
+The hook command names this machine's Python by absolute path (like `install-hook`), so prefer `--local`
+if your team commits `.claude/settings.json`. Remove it with `blot install-agent-hook --uninstall`
+(add `--local` if you installed it there); other hooks in the file are left alone.
+
+By default the guard only warns: Claude Code adds the warning to the agent's context with the edit's
+result, and the normal permission flow is unchanged. With `--ask`, Claude Code stops before the edit and
+asks you, showing the warning. The guard prints nothing when it has nothing to say, stays quiet for
+files outside a git repo or not tracked at HEAD, and never blocks an edit because of its own errors. It
+doesn't build a first index (that can take a minute): `install-agent-hook` does, or run `blot index`.
+After that it refreshes the index incrementally. On Flask a guarded edit takes about 450 ms.
+`forgot-related-file` is left out: it had no useful warnings among the 45 labelled in replays.
+
 ## Issue and PR titles (optional)
 
 ```bash
@@ -91,7 +127,7 @@ jobs:
   blot:
     runs-on: ubuntu-latest
     steps:
-      - uses: Sym-jay/Blot@v0.4.0
+      - uses: Sym-jay/Blot@v0.6.0
 ```
 
 The action checks out the pull request with its full history, installs Blot, runs `blot index` and

{blot_git-0.4.0 → blot_git-0.6.0}/action.yml

@@ -1,6 +1,6 @@
 # Run Blot on a pull request and show its findings as warning annotations.
 # Usage (in a workflow triggered by pull_request):
-#   - uses: Sym-jay/Blot@v0.4.0
+#   - uses: Sym-jay/Blot@v0.6.0
 # See "Use in CI" in README.md.
 name: Blot
 description: History-aware checks on the commits of a pull request, shown as warning annotations

{blot_git-0.4.0 → blot_git-0.6.0}/bench/README.md

@@ -38,5 +38,32 @@ using only the history that existed before it. It prints how many commits would
 and lists every warning, so you can label each one as useful or noise. Noise patterns become fixes in
 `classify.py` or the checks, plus a quiet case here so they never come back.
 
+### Labels: precision you can re-measure
+
+```bash
+cd ~/wl/flask && git checkout <head from the labels file>
+blot bench --replay 500 --labels path/to/Blot/bench/labels/pallets-flask.json
+```
+
+`bench/labels/` holds a hand verdict for every replay warning on the five reference repos. With
+`--labels`, replay prints `precision: X useful / Y labelled` and marks each warning `[useful]`,
+`[noise]` or `[?]`. Add `--update-labels` to append new, unlabelled warnings (`"verdict": null`) to the
+file, then fill them in. Labels match on commit, check, path and the commit the warning cites, so
+they survive small line-number drift. Replay at the `head` the file records, or the commits differ.
+
+How to label:
+
+- **useful**: the cited commit really fixed a bug, and the change touches what that fix did, so a
+  reviewer would want to know. This holds even if the change turned out fine (Express's deliberate
+  revert of the CVE-2024-51999 patch is useful). For co-change: the partner file really should have
+  been looked at.
+- **noise**: the cited commit isn't a real fix (a feature, a refactor, docs), or the change doesn't
+  touch what the fix did (formatting, comments, a rename, unrelated code nearby).
+
+Write a short `reason` either way; grouping noise by reason shows which rule to fix next.
+
+Add `--github` to replay with issue and PR labels too, as after `blot index --github` (needs the
+GitHub CLI logged in and a GitHub `origin` or `upstream` remote).
+
 Target: **at most 1 warning per 10 commits**, and most of those should be worth reading.
 See [RESULTS.md](RESULTS.md) for the latest numbers.

blot_git-0.6.0/bench/RESULTS.md

@@ -0,0 +1,113 @@
+# Bench results
+
+Measured 2026-10-30 with `blot bench`, on Windows 11, Python 3.12.
+
+## Cases: 32/32 correct
+
+| Check | Cases | Precision | Recall |
+|---|---|---|---|
+| removed-fix | 24 (16 warn, 8 quiet) | 100% | 100% |
+| readded-bug | 5 (4 warn, 1 quiet) | 100% | 100% |
+| forgot-related-file | 3 (3 quiet) | n/a | n/a |
+
+A quiet case now fails if its scripted edit can't be applied (it used to pass without running).
+
+The 21 cases added in this round are real commits from the labelled replays below: each one replays
+that commit's own hunk on its parent. Quiet cases pin the noise patterns fixed here so they stay fixed.
+
+## Replay: last 500 non-merge commits of 5 repos, every warning labelled
+
+Each commit is checked as if it were being committed at that moment, using only the history before
+it. Every warning was then labelled by hand as **useful** or **noise** (rules in
+[README.md](README.md#labels-precision-you-can-re-measure)); the labels live in [`labels/`](labels/),
+so these numbers can be re-measured after any rule change. "Before" is Blot 0.4.0; "after" is this
+release.
+
+| Repo | Labelled at | Commits | Warnings / 10 commits, before → after | Precision, before → after |
+|---|---|---|---|---|
+| pallets/flask | `d086db856` | 500 | 0.10 → **0.08** | 3/5 (60%) → **3/4 (75%)** |
+| psf/requests | `611c6162c` | 500 | 0.16 → **0.16** | 2/8 (25%) → **2/8 (25%)** |
+| expressjs/express | `0dee2c52c` | 498 | 0.18 → **0.18** | 5/9 (56%) → **5/9 (56%)** |
+| django/django | `79502d084` | 497 | 1.29 → **1.19** | 40/64 (63%) → **40/59 (68%)** |
+| facebook/react | `9ffcb463b` | 483 | 1.26 → **0.60** | 7/61 (11%) → **7/29 (24%)** |
+| **All** | | 2,478 | 0.59 → **0.44** | 57/147 (39%) → **57/109 (52%)** |
+
+The rule changes removed 38 warnings, all of them labelled noise; no useful warning was lost.
+
+**Against the PRD targets:** at most 1 warning per 10 commits is met everywhere except Django (1.19).
+Precision of 80% is **not** met: 52% overall, 68% on Django, where most warnings are fixes touching
+code from earlier fixes and CVEs.
+
+### What a useful warning looks like
+
+- Django `8fd29079e` relaxed the POST permission check that the CVE-2019-19118 fix added.
+- Django `7ff7fcc05` redid the `parse_header_parameters` simplification that an earlier commit had
+  reverted as a bug (#36520). Both `removed-fix` and `readded-bug` fired.
+- Flask `cabda59` changed `bp_subdomain is None` to `is not None` on a line from fix #4834; a later
+  commit had to fix the behaviour.
+- Express `697547cd` reverted the CVE-2024-51999 patch. That revert was deliberate (the advisory,
+  GHSA-pj86-cfqh-vqx6, was later withdrawn), so it is useful as "a security fix is being undone",
+  not as a caught regression.
+
+### Noise this release removed
+
+| Noise (warnings) | Fix |
+|---|---|
+| React feature-flag forks, per-bundler and per-platform copies of one file (27) | co-change skips variants: same name stem and extension (`ReactFeatureFlags.native-fb.js` ↔ `ReactFeatureFlags.js`); `foo.c` ↔ `foo.h` still pair |
+| deleting a whole file (4) | `removed-fix` skips deleted files |
+| commits cited as fixes that weren't: `Fixed #21189: Cleaned up ...`, `Fixed #12882 - Moved ...`, `[DevTools] upgrade to Manifest V3`, `Change Flask.__init__ to accept ...`, error-message wording (6) | `Fixed #N:` / `Fixed #N -` ticket styles judged by their description; cleanups count as refactors; `[Tag]` prefixes and "change" subjects count as features; error messages are routine |
+| docstrings with `backticks` or (asides) (1) | they count as prose |
+
+### Noise still there (52 warnings)
+
+| Pattern | Warnings | Why there's no rule yet |
+|---|---|---|
+| co-change partner not needed (React) | 9 | **0 of 45 co-change warnings across all five repos were useful.** See below. |
+| renames, equivalent API swaps (`substr` → `slice`, `req.connection` → `req.socket`) | 11 | a rename and a switch to a different variable look the same on one line |
+| new argument or keyword argument on a fix's call | 3 | adding an argument can change behaviour |
+| formatter reflows with f-strings or joined lines (requests' Black commit) | 4 | dropping parentheses can change precedence |
+| deleting a legacy module or feature in pieces (React) | 6 | intentional, but only the commit message says so |
+| docstring lines that still read as code | 3 | needs to know it's inside a docstring, not just how the line looks |
+| other: code moved to another file, fix behaviour kept while restructuring, generic re-added lines | 16 | case by case |
+
+**`forgot-related-file` has shown no useful warning yet**: 0/45 before this release, 0/9 after. It
+stays on, because the remaining warnings are rare (React only), but it is the first candidate to
+become opt-in if real-world reports agree.
+
+## Does `--github` help? (measured 2026-11-01)
+
+`blot bench --replay 500 --github` reads issue and PR labels the way `blot index --github` does.
+Flask, requests, Express and React track bugs on GitHub; Django's GitHub Issues are off (it uses
+Trac), so it is unchanged. New warnings were labelled with the same rules.
+
+| Repo | Without `--github` | With `--github` | Commits re-judged by labels |
+|---|---|---|---|
+| pallets/flask | 3/4 (75%) | 3/4 (75%) | 0 |
+| psf/requests | 2/8 (25%) | **4/10 (40%)** | 15 upgraded |
+| expressjs/express | 5/9 (56%) | 5/9 (56%) | 25 upgraded |
+| facebook/react | 7/29 (24%) | **12/40 (30%)** | 154 upgraded, 4 demoted |
+| **All five, with Django** | 57/109 (52.3%) | **64/122 (52.5%)** | |
+
+**`--github` doesn't raise precision; it finds more useful warnings** (7 more, with 5 more noise).
+Labels almost never demote a commit (4 of ~3,200 issues and PRs looked up). What they do is
+upgrade commits like `ReactDOM: Fix missing form data ... (#28056)`, which Blot rates as unclear
+without labels: "Fix" isn't at the start, and there's no "fixes #N" or strong defect word. 
+
+Caveat: labels are read as they are today, so a label added after a commit was made counts too.
+
+### Tried and dropped: "a fix word plus a PR number" (2026-11-01)
+
+Could a rule do offline what the `bug` label does? Rule tried: a fix word anywhere in the subject
+plus an issue or PR number makes a commit a fix. It added **85 warnings** (React went from 0.60 to
+1.95 per 10 commits), because almost every React and Express subject ends in its PR number. Of 46
+labelled (all of requests' and Express's, 20 of React's), **10 were useful (22%)**. Most were
+`fix(deps): …@^2.0.0` bumps, "Fix Flow type" commits and import lines. Overall precision would fall
+from 52% to about 39%, so the rule was not kept. Its 46 labels stay in `labels/` for any narrower
+attempt. A label written by a maintainer says more than a keyword can.
+
+## Reproduce
+
+```bash
+git clone https://github.com/pallets/flask && cd flask && git checkout d086db856
+blot bench --replay 500 --labels path/to/Blot/bench/labels/pallets-flask.json
+```