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

{blot_git-0.5.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.5.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.5.0 → blot_git-0.6.0}/CLAUDE.md

@@ -7,12 +7,12 @@ always changes with another (`forgot-related-file`). Mascot: Sora the slime. Own
 
 ## 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, bench. `check`/`why` build/refresh the index themselves.
+  - `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
-  - `why.py`, `github.py` (`index --github` via `gh api graphql`), `bench.py` (cases + `--replay N`)
-- `bench/cases.json` scripted real-world cases (30/30); `bench/labels/` hand verdicts for every replay
+  - `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
@@ -22,7 +22,7 @@ always changes with another (`forgot-related-file`). Mascot: Sora the slime. Own
 ```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 30/30
+.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
@@ -50,11 +50,19 @@ python -m venv .venv && .venv/Scripts/python -m pip install -e ".[dev]"
 - 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-10-28)
-- Released 0.5.0: checks, `why`, `--github`, bench/replay with labels, parallel indexing, pre-commit
-  framework support (`rev: v0.5.0`), GitHub Action (`uses: Sym-jay/Blot@v0.5.0`).
+## 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–#6 (bench cases for Django, Express, React, requests, Flask).
+- 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.5.0 → blot_git-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: blot-git
-Version: 0.5.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.5.0 → blot_git-0.6.0}/README.md

@@ -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.5.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.5.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.5.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.5.0 → blot_git-0.6.0}/bench/README.md

@@ -62,5 +62,8 @@ How to label:
 
 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.5.0 → blot_git-0.6.0}/bench/RESULTS.md

@@ -2,12 +2,12 @@
 
 Measured 2026-10-30 with `blot bench`, on Windows 11, Python 3.12.
 
-## Cases: 30/30 correct
+## Cases: 32/32 correct
 
 | Check | Cases | Precision | Recall |
 |---|---|---|---|
 | removed-fix | 24 (16 warn, 8 quiet) | 100% | 100% |
-| readded-bug | 3 (3 warn) | 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).
@@ -74,6 +74,37 @@ code from earlier fixes and CVEs.
 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

{blot_git-0.5.0 → blot_git-0.6.0}/bench/cases.json

@@ -408,5 +408,36 @@
       "commit": "db8cb31"
     },
     "notes": "Changes load_dotenv's return behaviour that fix #2937 made consistent."
+  },
+  {
+    "id": "requests-readd-verify-https-condition",
+    "repo": "https://github.com/psf/requests",
+    "at": "af66521381d9e6806ca80b7e297b704e6a4966c9",
+    "file": "requests/adapters.py",
+    "replace": [
+      "        if url.lower().startswith('https'):",
+      "        if url.lower().startswith('https') and verify:"
+    ],
+    "expect": {
+      "check": "readded-bug",
+      "warn": true,
+      "commit": "af66521"
+    },
+    "notes": "Re-adds the condition removed by fix #4025; this mirrors the later 00c6ad58 simplification. See https://github.com/psf/requests/issues/4025."
+  },
+  {
+    "id": "requests-quiet-black-auth-strip-formatting",
+    "repo": "https://github.com/psf/requests",
+    "at": "2d5517682b3b38547634d153cea43d48fbc8cdb5",
+    "file": "requests/sessions.py",
+    "replace": [
+      "        if (not changed_scheme and old_parsed.port in default_port\n                and new_parsed.port in default_port):",
+      "        if (\n            not changed_scheme\n            and old_parsed.port in default_port\n            and new_parsed.port in default_port\n        ):"
+    ],
+    "expect": {
+      "check": "readded-bug",
+      "warn": false
+    },
+    "notes": "Black's formatting change from 2a6f290b in should_strip_auth. Formatting only: must stay quiet."
   }
 ]

blot_git-0.6.0/bench/labels/expressjs-express.json

@@ -0,0 +1,246 @@
+{
+ "repo": "C:\\Users\\N Jayasankar\\AppData\\Local/Temp/wl/replay/express",
+ "head": "0dee2c52c7c873498f8ed7d8ee4ddd0a04d3ada8",
+ "labels": [
+  {
+   "sha": "a0276c6c9",
+   "subject": "Use mime-types for file to content type mapping",
+   "check": "removed-fix",
+   "path": "lib/response.js",
+   "line": 642,
+   "cited": "ae0b630",
+   "verdict": "useful",
+   "reason": "replaces the charset logic from fix #3303 with mime.contentType"
+  },
+  {
+   "sha": "490f1a173",
+   "subject": "lint: remove deprecated String.prototype.substr",
+   "check": "removed-fix",
+   "path": "lib/router/index.js",
+   "line": 291,
+   "cited": "99a369f",
+   "verdict": "noise",
+   "reason": "equivalent API swap (substr -> slice)"
+  },
+  {
+   "sha": "0def9bb65",
+   "subject": "Add \"root\" option to res.download",
+   "check": "removed-fix",
+   "path": "lib/response.js",
+   "line": 585,
+   "cited": "1150ca7",
+   "verdict": "useful",
+   "reason": "changes the path resolution that fix #2284 relied on"
+  },
+  {
+   "sha": "0867302dd",
+   "subject": "Prevent open redirect allow list bypass due to encodeurl",
+   "check": "removed-fix",
+   "path": "lib/response.js",
+   "line": 915,
+   "cited": "76eaa32",
+   "verdict": "useful",
+   "reason": "changes the URL encoding from fix #2897 (security follow-up)"
+  },
+  {
+   "sha": "89f198c6a",
+   "subject": "lib: use req.socket over deprecated req.connection (#6705)",
+   "check": "removed-fix",
+   "path": "lib/request.js",
+   "line": 285,
+   "cited": "11c74d7",
+   "verdict": "noise",
+   "reason": "equivalent API swap (req.connection -> req.socket)"
+  },
+  {
+   "sha": "89f198c6a",
+   "subject": "lib: use req.socket over deprecated req.connection (#6705)",
+   "check": "removed-fix",
+   "path": "lib/request.js",
+   "line": 290,
+   "cited": "20aa126",
+   "verdict": "noise",
+   "reason": "equivalent API swap (req.connection -> req.socket)"
+  },
+  {
+   "sha": "697547cde",
+   "subject": "Revert \"sec: security patch for CVE-2024-51999\"",
+   "check": "removed-fix",
+   "path": "lib/utils.js",
+   "line": 269,
+   "cited": "2f64f68",
+   "verdict": "useful",
+   "reason": "reverts the CVE-2024-51999 patch (deliberate; advisory later withdrawn)"
+  },
+  {
+   "sha": "697547cde",
+   "subject": "Revert \"sec: security patch for CVE-2024-51999\"",
+   "check": "readded-bug",
+   "path": "lib/utils.js",
+   "line": 269,
+   "cited": "2f64f68",
+   "verdict": "useful",
+   "reason": "reverts the CVE-2024-51999 patch (deliberate; advisory later withdrawn)"
+  },
+  {
+   "sha": "a08da78e6",
+   "subject": "deps: bump qs minimum to 6.15.2 (#7305)",
+   "check": "removed-fix",
+   "path": "package.json",
+   "line": 55,
+   "cited": "925a1df",
+   "verdict": "noise",
+   "reason": "raises the dependency floor past the fix's version, keeping the fix"
+  },
+  {
+   "sha": "9482b82d0",
+   "subject": "Invoke default with same arguments as types in res.format",
+   "check": "removed-fix",
+   "path": "lib/response.js",
+   "line": 700,
+   "cited": "1311f2a",
+   "verdict": "useful",
+   "reason": "changes how res.format calls the default handler from fix 1311f2a"
+  },
+  {
+   "sha": "b3906cbdd",
+   "subject": "fix(deps): serve-static@^2.1.0",
+   "check": "removed-fix",
+   "path": "package.json",
+   "line": 57,
+   "cited": "65b6206",
+   "verdict": "noise",
+   "reason": "dependency floor raised past the cited version"
+  },
+  {
+   "sha": "0c49926a9",
+   "subject": "fix(deps): send@^1.1.0",
+   "check": "removed-fix",
+   "path": "package.json",
+   "line": 56,
+   "cited": "ecf762f",
+   "verdict": "noise",
+   "reason": "dependency floor raised past the cited version"
+  },
+  {
+   "sha": "9f8589e31",
+   "subject": "cleanup: remove unnecessary require for global Buffer",
+   "check": "removed-fix",
+   "path": "lib/response.js",
+   "line": 15,
+   "cited": "c70197a",
+   "verdict": "noise",
+   "reason": "removes a require made unnecessary by Node's global Buffer"
+  },
+  {
+   "sha": "9f8589e31",
+   "subject": "cleanup: remove unnecessary require for global Buffer",
+   "check": "removed-fix",
+   "path": "lib/utils.js",
+   "line": 15,
+   "cited": "c70197a",
+   "verdict": "noise",
+   "reason": "removes a require made unnecessary by Node's global Buffer"
+  },
+  {
+   "sha": "d2de128a3",
+   "subject": "fix (deps): update deps (#6337)",
+   "check": "removed-fix",
+   "path": "package.json",
+   "line": 65,
+   "cited": "6a40af8",
+   "verdict": "noise",
+   "reason": "dependency range loosened, cited commit was a dev-deps bump"
+  },
+  {
+   "sha": "9e9714422",
+   "subject": "feat(deps): finalhandler@2.1.0 (#6373)",
+   "check": "removed-fix",
+   "path": "package.json",
+   "line": 45,
+   "cited": "accafc6",
+   "verdict": "noise",
+   "reason": "dependency floor raised past the cited version"
+  },
+  {
+   "sha": "f1a2dc884",
+   "subject": "deps: type-is@^2.0.1 (#6420)",
+   "check": "removed-fix",
+   "path": "package.json",
+   "line": 60,
+   "cited": "402e7f6",
+   "verdict": "noise",
+   "reason": "dependency floor raised past the cited version"
+  },
+  {
+   "sha": "00bb633ca",
+   "subject": "deps: qs@^6.14.1",
+   "check": "removed-fix",
+   "path": "package.json",
+   "line": 55,
+   "cited": "1e359f5",
+   "verdict": "noise",
+   "reason": "dependency floor raised past the cited version"
+  },
+  {
+   "sha": "f5c159b11",
+   "subject": "ci: build express with node.js v26 (#7218)",
+   "check": "removed-fix",
+   "path": "package.json",
+   "line": 75,
+   "cited": "d2de128",
+   "verdict": "noise",
+   "reason": "dev dependency bump; cited commit was a deps bump"
+  },
+  {
+   "sha": "cb19f0417",
+   "subject": "Upgrade `content-type` (#7234)",
+   "check": "removed-fix",
+   "path": "package.json",
+   "line": 38,
+   "cited": "d2de128",
+   "verdict": "noise",
+   "reason": "dependency bump; cited commit was a deps bump"
+  },
+  {
+   "sha": "59e205a57",
+   "subject": "Upgrade `content-disposition` (#7233)",
+   "check": "removed-fix",
+   "path": "package.json",
+   "line": 37,
+   "cited": "05f40f4",
+   "verdict": "noise",
+   "reason": "dependency bump past the cited version"
+  },
+  {
+   "sha": "9a34acf03",
+   "subject": "fix(res.send): preserve ETag generation with Transfer-Encoding (#7459)",
+   "check": "removed-fix",
+   "path": "lib/response.js",
+   "line": 168,
+   "cited": "18e5985",
+   "verdict": "useful",
+   "reason": "changes the Transfer-Encoding condition from fix #4893"
+  },
+  {
+   "sha": "9a34acf03",
+   "subject": "fix(res.send): preserve ETag generation with Transfer-Encoding (#7459)",
+   "check": "readded-bug",
+   "path": "lib/response.js",
+   "line": 166,
+   "cited": "18e5985",
+   "verdict": "useful",
+   "reason": "re-adds the condition that fix #4893 replaced"
+  },
+  {
+   "sha": "6d2df035a",
+   "subject": "build(deps-dev): bump supertest from 6.3.0 to 7.3.0 (#7494)",
+   "check": "removed-fix",
+   "path": "package.json",
+   "line": 79,
+   "cited": "d2de128",
+   "verdict": "noise",
+   "reason": "dev dependency bump; cited commit was a deps bump"
+  }
+ ]
+}