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

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

@@ -0,0 +1,60 @@
+# 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, 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
+  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 30/30
+```
+- 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-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`).
+- 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).
+- 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.
+- Next: remaining noise (renames, API swaps, added arguments, docstrings) in bench/RESULTS.md.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: blot-git
-Version: 0.4.0
+Version: 0.5.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

{blot_git-0.4.0 → blot_git-0.5.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
 
@@ -91,7 +91,7 @@ jobs:
   blot:
     runs-on: ubuntu-latest
     steps:
-      - uses: Sym-jay/Blot@v0.4.0
+      - uses: Sym-jay/Blot@v0.5.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.5.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.5.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.5.0}/bench/README.md

@@ -38,5 +38,29 @@ 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.
+
 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/bench/RESULTS.md

@@ -0,0 +1,82 @@
+# Bench results
+
+Measured 2026-10-30 with `blot bench`, on Windows 11, Python 3.12.
+
+## Cases: 30/30 correct
+
+| Check | Cases | Precision | Recall |
+|---|---|---|---|
+| removed-fix | 24 (16 warn, 8 quiet) | 100% | 100% |
+| readded-bug | 3 (3 warn) | 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.
+
+## 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
+```