blot-git 0.0.1__tar.gz → 0.2.0__tar.gz

{blot_git-0.0.1 → blot_git-0.2.0}/CONTRIBUTING.md

@@ -25,7 +25,7 @@ pytest
 ```
 
 ## Ground rules
-- Core stays **stdlib-only** and the `check` command stays **under 500 ms**.
+- Core stays **stdlib-only on Python 3.11+** (3.10 gets one small dependency, `tomli`, to read config) and the `check` command stays **under 500 ms**. New runtime dependencies need a strong reason.
 - Quiet beats clever: a new warning must not raise the false-alarm rate on the bench.
 
 ## Releasing (maintainers)

{blot_git-0.0.1 → blot_git-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: blot-git
-Version: 0.0.1
+Version: 0.2.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
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Topic :: Software Development :: Version Control :: Git
 Requires-Python: >=3.10
+Requires-Dist: tomli>=1.1.0; python_version < '3.11'
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == 'dev'
 Provides-Extra: github
@@ -34,6 +35,8 @@ Blot warns you *before you commit* when your change:
 
 It runs locally, needs no account or AI, and stays quiet unless the history gives it a real reason to speak.
 
+![Blot catching a real Flask regression](https://raw.githubusercontent.com/Sym-jay/Blot/main/assets/demo/demo.gif)
+
 ```bash
 pip install blot-git
 cd your-repo
@@ -41,6 +44,6 @@ blot index           # one-time, builds .git/blot.db
 blot install-hook    # adds Blot to your pre-commit hook
 ```
 
-> **Status:** pre-alpha. Indexing and the git hook work; the three checks arrive in the next milestone.
+> **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.
 
 Meet Sora the slime, read the docs, or contribute on GitHub: https://github.com/Sym-jay/Blot

{blot_git-0.0.1 → blot_git-0.2.0}/README.md

@@ -1,6 +1,6 @@
 # Blot
 
-[![CI](https://github.com/Sym-jay/Blot/actions/workflows/ci.yml/badge.svg)](https://github.com/Sym-jay/Blot/actions/workflows/ci.yml)
+[![CI](https://github.com/Sym-jay/Blot/actions/workflows/ci.yml/badge.svg)](https://github.com/Sym-jay/Blot/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/blot-git)](https://pypi.org/project/blot-git/)
 
 <img src="assets/sora/orange/walk.svg" width="480" alt="Sora, the Blot slime, sliding back and forth">
 
@@ -18,15 +18,11 @@ Blot warns you *before you commit* when your change:
 
 It runs locally, needs no account or AI, and stays quiet unless the history gives it a real reason to speak.
 
-```
-$ git commit -m "simplify static route"
-blot: 1 warning
-  ! removed-fix  src/flask/app.py:355
-    You're changing a line added by a bug fix:
-    8efea0cc "Break reference cycle created by default in Flask instances" (fixes #3761)
-```
+<img src="assets/demo/demo.gif" width="760" alt="Blot catching a real Flask regression: simplifying self_ref = weakref.ref(self) triggers a removed-fix warning that traces past a 2023 refactor to the 2020 reference-cycle fix">
+
+*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. Milestone M1 is done: `blot index` builds the history index (Flask's 3,800 commits in ~2 s) and `blot install-hook` wires up git. The three checks land in M2, so `blot check` doesn't warn yet. See the [roadmap in the 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–10% of commits; see [bench/RESULTS.md](bench/RESULTS.md). Roadmap: [PRD](docs/PRD.md#12-milestones-4-weeks-part-time).
 
 ## Meet Sora
 
@@ -50,15 +46,15 @@ Sora comes in four warm palettes:
 
 ## Quickstart
 
-Not on PyPI yet, so install from GitHub:
-
 ```bash
-pip install git+https://github.com/Sym-jay/Blot
+pip install blot-git  # the PyPI name is blot-git; the command is just `blot`
 cd your-repo
 blot index            # one-time, builds .git/blot.db (refreshes incrementally after that)
 blot install-hook     # adds Blot to .git/hooks/pre-commit without touching existing hooks
 ```
 
+For the latest unreleased code, use `pip install git+https://github.com/Sym-jay/Blot` instead.
+
 Remove it any time with `blot install-hook --uninstall`. Settings go in `[tool.blot]` in `pyproject.toml` or a `.blot.toml` file (see `src/blot/config.py`).
 
 Or with the [pre-commit](https://pre-commit.com) framework, see `.pre-commit-hooks.yaml`.

blot_git-0.2.0/assets/demo/make_demo.py

@@ -0,0 +1,142 @@
+"""Render the README / launch-post demo GIF: Blot catching a real Flask regression.
+
+Run:  pip install pillow && python assets/demo/make_demo.py [path/to/monospace.ttf]
+Out:  assets/demo/demo.gif
+
+Every line of tool output below was captured from a real run on pallets/flask (d086db85)
+with Blot's pre-commit hook installed. Only the typing animation is synthetic.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import sys
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageFont
+
+HERE = Path(__file__).parent
+W, H = 1080, 580
+PAD, LINE_H, FONT_SIZE = 28, 26, 18
+VISIBLE_LINES = 20
+COLORS = {
+    "bg": "#1F1B16", "bar": "#2A251E", "text": "#EDE3D3", "dim": "#8C8273", "prompt": "#A9BC8E",
+    "warn": "#E39A5B", "minus": "#E07A6A", "plus": "#9FCB8A", "sha": "#F4E2AE",
+}
+
+# (kind, text): "cmd" lines are typed, everything else appears at once.
+SCRIPT: list[tuple[str, str]] = [
+    ("cmd", "pip install blot-git"),
+    ("dim", "Successfully installed blot-git-0.1.0"),
+    ("cmd", "blot index"),
+    ("text", "blot: indexed 3829 commits (103 load-bearing fixes), full, in 2.0s"),
+    ("cmd", "blot install-hook"),
+    ("text", "blot: pre-commit hook installed (.git/hooks/pre-commit)"),
+    ("note", "# that weakref looks over-complicated... let's simplify it"),
+    ("cmd", "git diff -U0"),
+    ("dim", "@@ -355 +355 @@ class Flask(App):"),
+    ("minus", "-            self_ref = weakref.ref(self)"),
+    ("plus", "+            self_ref = self"),
+    ("cmd", 'git commit -am "Simplify static route"'),
+    ("warn", "blot: 1 warning"),
+    ("text", ""),
+    ("warn", "  ! removed-fix  src/flask/app.py:355"),
+    ("text", "    You're removing or changing a line that a bug fix added."),
+    ("text", "    Check that the bug it fixed can't come back."),
+    ("sha", '    8efea0c "Break reference cycle created by default in Flask instances." (2020-10-03)'),
+    ("dim", '    traced past refactor 0ec7f71 "Split the App and Blueprint into Sansio and IO parts"'),
+]
+SLEEPY_UNTIL = 3   # Sora dozes while the index builds
+ALERT_FROM = 12    # Sora jumps to alert when the warning prints
+
+
+def _sora():
+    spec = importlib.util.spec_from_file_location("build_sprites", HERE.parent / "sora" / "build_sprites.py")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def _font(path: str | None) -> ImageFont.FreeTypeFont:
+    candidates = [path] if path else []
+    candidates += ["C:/Windows/Fonts/consola.ttf", "/System/Library/Fonts/Menlo.ttc",
+                   "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf"]
+    for c in candidates:
+        if c and os.path.exists(c):
+            return ImageFont.truetype(c, FONT_SIZE)
+    sys.exit("no monospace font found; pass a .ttf path as the first argument")
+
+
+def _draw_sora(draw: ImageDraw.ImageDraw, sora, face: str, x: int, y: int, scale: int = 5) -> None:
+    palette = {**sora.PALETTES["orange"], **sora.FIXED}
+    cells = {}
+    for row_i, row in enumerate(sora.BODY):
+        for col_i, key in enumerate(row):
+            if key not in ".S":
+                cells[(col_i, row_i + sora.TOP)] = key
+    for col_i, row_i, key in sora.FACES[face]:
+        cells[(col_i, row_i + sora.TOP)] = key
+    for (cx, cy), key in cells.items():
+        draw.rectangle([x + cx * scale, y + cy * scale, x + cx * scale + scale - 1, y + cy * scale + scale - 1],
+                       fill=palette[key])
+
+
+def _frame(lines: list[tuple[str, str]], cursor: bool, face: str, font, sora) -> Image.Image:
+    img = Image.new("RGB", (W, H), COLORS["bg"])
+    d = ImageDraw.Draw(img)
+    d.rectangle([0, 0, W, 34], fill=COLORS["bar"])
+    for i, c in enumerate(("#E07A6A", "#E8A33B", "#9FCB8A")):
+        d.ellipse([16 + i * 22, 11, 28 + i * 22, 23], fill=c)
+    d.text((W // 2, 17), "blot demo: pallets/flask", font=font, fill=COLORS["dim"], anchor="mm")
+    shown = lines[-VISIBLE_LINES:]
+    for i, (kind, text) in enumerate(shown):
+        y = 50 + i * LINE_H
+        if kind == "cmd":
+            d.text((PAD, y), "$", font=font, fill=COLORS["prompt"])
+            d.text((PAD + 20, y), text, font=font, fill=COLORS["text"])
+        else:
+            color = COLORS.get(kind, COLORS["text"]) if kind != "note" else COLORS["dim"]
+            d.text((PAD, y), text, font=font, fill=color)
+    if cursor:
+        last_kind, last_text = shown[-1] if shown else ("cmd", "")
+        offset = 20 if last_kind == "cmd" else 0
+        cx = PAD + offset + int(font.getlength(last_text))
+        cy = 50 + (len(shown) - 1) * LINE_H
+        d.rectangle([cx + 2, cy + 2, cx + 11, cy + 20], fill=COLORS["text"])
+    _draw_sora(d, sora, face, W - 28 * 5 - 28, 40)  # top right: the early lines there are short
+    return img
+
+
+def main() -> None:
+    font = _font(sys.argv[1] if len(sys.argv) > 1 else None)
+    sora = _sora()
+    frames: list[Image.Image] = []
+    durations: list[int] = []
+    shown: list[tuple[str, str]] = []
+
+    def add(face: str, ms: int, cursor: bool = True) -> None:
+        frames.append(_frame(shown, cursor, face, font, sora))
+        durations.append(ms)
+
+    for step, (kind, text) in enumerate(SCRIPT):
+        face = "sleepy" if step < SLEEPY_UNTIL else ("alert" if step >= ALERT_FROM else "idle")
+        if kind == "cmd":
+            shown.append(("cmd", ""))
+            for n in range(0, len(text) + 1, 3):
+                shown[-1] = ("cmd", text[:n])
+                add(face, 45)
+            shown[-1] = ("cmd", text)
+            add(face, 450)
+        else:
+            shown.append((kind, text))
+            add(face, 1100 if step == len(SCRIPT) - 1 else 220, cursor=False)
+    add("alert", 4500, cursor=False)
+
+    out = HERE / "demo.gif"
+    frames[0].save(out, save_all=True, append_images=frames[1:], duration=durations, loop=0, optimize=True)
+    print(f"wrote {out} ({len(frames)} frames, {out.stat().st_size // 1024} KB)")
+
+
+if __name__ == "__main__":
+    main()

blot_git-0.2.0/bench/README.md

@@ -0,0 +1,42 @@
+# Bench
+
+How we keep Blot's warnings accurate and rare. Two tools, both in `blot bench`.
+
+## 1. Cases: known right answers
+
+`cases.json` lists real edits on public repos, each labeled with what Blot **should** say.
+
+```bash
+blot bench                      # clones case repos into ~/.cache/blot-bench, prints precision/recall
+blot bench --workdir D:\bench   # put the clones somewhere else (short paths help on Windows)
+```
+
+Each case:
+
+| Field | Meaning |
+|---|---|
+| `id` | short unique name |
+| `repo`, `at` | public repo URL and the commit to check out |
+| `file` | file to edit |
+| `replace` | `["old text", "new text"]`; the old text must appear **exactly once** in the file |
+| `expect.check` | which check is being tested: `removed-fix`, `readded-bug` or `forgot-related-file` |
+| `expect.warn` | `true` if it should warn, `false` if it must stay quiet |
+| `expect.commit` | (warn cases) the commit the warning must cite; a prefix is fine |
+| `notes` | why: link the PR or issue that explains the code |
+
+Add **quiet cases** (`"warn": false`) as often as warning cases. They protect against false alarms.
+
+## 2. Replay: how noisy is Blot on real history?
+
+```bash
+cd some-big-repo
+blot bench --replay 500 --json replay.json
+```
+
+Replay re-checks the last 500 non-merge commits as if each were being committed at that moment,
+using only the history that existed before it. It prints how many commits would have shown a warning
+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.
+
+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.2.0/bench/RESULTS.md

@@ -0,0 +1,73 @@
+# Bench results
+
+Measured 2026-10-22 with `blot bench`, on Windows 11, Python 3.12.
+
+## Cases: 9/9 correct
+
+| Check | Cases | Precision | Recall |
+|---|---|---|---|
+| removed-fix | 6 (3 warn, 3 quiet) | 100% | 100% |
+| readded-bug | 2 (2 warn) | 100% | 100% |
+| forgot-related-file | 1 (1 quiet) | n/a | n/a |
+
+Nine cases is a start, not a verdict. Each new case is a good first issue (see [README.md](README.md)).
+
+## Replay: last 500 non-merge commits of 5 repos
+
+Each commit is checked as if it were being committed at that moment, using only the history before
+it. "Before" is Blot 0.1.0's rules; "after" is this release.
+
+| Repo | Commits | Before: warnings / 10 commits | After | Commits with a warning (after) | Avg check time |
+|---|---|---|---|---|---|
+| pallets/flask | 500 | 1.96 | **0.10** | 5 (1.0%) | 106 ms |
+| psf/requests | 500 | 1.12 | **0.16** | 3 (0.6%) | 52 ms |
+| expressjs/express | 498 | 1.00 | **0.18** | 7 (1.4%) | 49 ms |
+| django/django | 497 | 26.30 | **1.29** | 50 (10.1%) | 479 ms |
+| facebook/react | 483 | 10.00 | **1.30** | 39 (8.1%) | 821 ms |
+
+Target from the PRD: at most 1 warning per 10 commits. Three repos are well under; Django and React are
+slightly over. Check times are in-process (no Python startup) and grow with the size of the change.
+The last rule change (type hints that insert `None`) was re-measured only on requests; it can only
+remove warnings, so the other four numbers are upper bounds.
+
+## Were the warnings worth reading?
+
+Labeled by hand: every warning for Flask, requests and Express; a sample for Django and React.
+
+- **Flask, 5 warnings, 3 useful.** The best: commit `cabda59` changed
+  `bp_subdomain is None` to `is not None` on a line from fix `d7b6c1f` (#4834); a later commit had to
+  fix `subdomain_matching=False` behavior. Noise: a line from a feature commit, a docstring.
+- **Express, 9 warnings, about 7 useful.** The best: commit `697547cd` **reverted the CVE-2024-51999
+  security patch**. Both `removed-fix` and `readded-bug` fired. Others: changes to code from fixes for
+  proxy handling (#2252), redirect encoding and charset handling.
+- **requests, 8 warnings, 1 useful** (dropping `chardet` from code added by fix #4102). The rest come
+  from one mass reformat and one typing commit, which still slip through in a few lines.
+- **Django, 64 warnings.** Mostly fixes and CVE follow-ups that touch code from earlier fixes, e.g.
+  `Fixed #37403 -- Fixed JSONField __in crash on SQLite` flagged for changing code from
+  `#37377 -- Fixed JSONField __in crash`. Useful context for a reviewer, though Django's maintainers
+  know their history well.
+- **React, 63 warnings.** About half are co-change warnings. Useful when a fix lands in one bundler
+  variant (`react-server-dom-webpack`) but not its mirrors (turbopack, parcel); noise for feature-flag
+  fork files, which are often edited separately on purpose.
+
+## What the replays changed
+
+Every noise pattern became a rule and, where possible, a bench case:
+
+| Noise | Fix |
+|---|---|
+| "This fixes #N" on features, refactors, docs (old Flask) | feature/refactor/docs subjects count as routine |
+| `Fixed #N -- Added ...` (Django's ticket-first style) | judge the text after `--` |
+| tests, docs, lock files, translations, CI config | skipped by default (`check-tests` / `check-docs` to opt in) |
+| code moved between files | not a removal or a re-add |
+| reformatting and type hints | a line whose tokens survive in order, with nothing logic-changing inserted, is kept |
+| imports, bare keywords, comments, docstrings | ignored |
+| co-change with hub files | the link must hold both ways (≥ 80% each direction) |
+| re-added lines matching fixes in other files | only fixes to the same file count |
+
+## Reproduce
+
+```bash
+git clone https://github.com/pallets/flask && cd flask
+blot bench --replay 500 --json replay.json
+```

blot_git-0.2.0/bench/cases.json

@@ -0,0 +1,83 @@
+[
+  {
+    "id": "flask-weakref-static-route",
+    "repo": "https://github.com/pallets/flask",
+    "at": "d086db85",
+    "file": "src/flask/app.py",
+    "replace": ["self_ref = weakref.ref(self)", "self_ref = self"],
+    "expect": {"check": "removed-fix", "warn": true, "commit": "8efea0cc"},
+    "notes": "The weakref breaks an app <-> view function reference cycle (#3761). Every git blame variant stops at the refactor 0ec7f713 (Split the App and Blueprint into Sansio and IO parts); the cited commit must be the 2020 fix."
+  },
+  {
+    "id": "flask-readd-bound-send-static-file",
+    "repo": "https://github.com/pallets/flask",
+    "at": "d086db85",
+    "file": "src/flask/app.py",
+    "replace": ["view_func=lambda **kw: self_ref().send_static_file(**kw),  # type: ignore", "view_func=self.send_static_file,"],
+    "expect": {"check": "readded-bug", "warn": true, "commit": "8efea0cc"},
+    "notes": "Restores the exact line 8efea0cc removed; the bound method is what created the reference cycle."
+  },
+  {
+    "id": "flask-quiet-feature-line",
+    "repo": "https://github.com/pallets/flask",
+    "at": "d086db85",
+    "file": "src/flask/app.py",
+    "replace": ["setattr(Flask, method.__name__, add_ctx(base_method))", "setattr(Flask, method.__name__, base_method)"],
+    "expect": {"check": "removed-fix", "warn": false},
+    "notes": "Line comes from 6a649690 (pass context through dispatch methods), a feature commit. Must stay quiet."
+  },
+  {
+    "id": "flask-quiet-cochange-app",
+    "repo": "https://github.com/pallets/flask",
+    "at": "d086db85",
+    "file": "src/flask/app.py",
+    "replace": ["self_ref = weakref.ref(self)", "self_ref = self"],
+    "expect": {"check": "forgot-related-file", "warn": false},
+    "notes": "app.py's strongest co-change partner is CHANGES.rst at ~45%, below the 80% threshold. Must stay quiet."
+  },
+  {
+    "id": "flask-subdomain-logic-edit",
+    "repo": "https://github.com/pallets/flask",
+    "at": "d7b6c1f6703df405c69da45e7e0ba3d1aed512ce",
+    "file": "src/flask/blueprints.py",
+    "replace": ["if state.subdomain is not None and bp_subdomain is None:", "if state.subdomain is not None and bp_subdomain is not None:"],
+    "expect": {"check": "removed-fix", "warn": true, "commit": "d7b6c1f"},
+    "notes": "Real history: cabda59 changed this line right after fix d7b6c1f (#4834); a later commit had to fix subdomain_matching=False behavior. Same tokens plus `not` is a logic edit, not a reformat."
+  },
+  {
+    "id": "express-cve-2024-51999-revert-removed",
+    "repo": "https://github.com/expressjs/express",
+    "at": "2f64f68c37c64ae333e41ff38032d21860f22255",
+    "file": "lib/utils.js",
+    "replace": ["plainObjects: true", "allowPrototypes: true"],
+    "expect": {"check": "removed-fix", "warn": true, "commit": "2f64f68c"},
+    "notes": "Real history: 697547cd reverted the CVE-2024-51999 patch the same day. Found by blot bench --replay."
+  },
+  {
+    "id": "express-cve-2024-51999-revert-readded",
+    "repo": "https://github.com/expressjs/express",
+    "at": "2f64f68c37c64ae333e41ff38032d21860f22255",
+    "file": "lib/utils.js",
+    "replace": ["plainObjects: true", "allowPrototypes: true"],
+    "expect": {"check": "readded-bug", "warn": true, "commit": "2f64f68c"},
+    "notes": "Same revert: `allowPrototypes: true` is the exact line the security patch removed."
+  },
+  {
+    "id": "requests-quiet-black-quotes",
+    "repo": "https://github.com/psf/requests",
+    "at": "2d5517682b3b38547634d153cea43d48fbc8cdb5",
+    "file": "requests/auth.py",
+    "replace": ["if _algorithm == 'MD5' or _algorithm == 'MD5-SESS':", "if _algorithm == \"MD5\" or _algorithm == \"MD5-SESS\":"],
+    "expect": {"check": "removed-fix", "warn": false},
+    "notes": "Black's quote change from 2a6f290b on a line added by fix 6931bd6. Formatting only: must stay quiet."
+  },
+  {
+    "id": "requests-quiet-type-hint",
+    "repo": "https://github.com/psf/requests",
+    "at": "8f6cda9969f4a98c45ea2922f6bcbefc02256202",
+    "file": "src/requests/models.py",
+    "replace": ["    def links(self):", "    def links(self) -> dict[str, dict[str, str]]:"],
+    "expect": {"check": "removed-fix", "warn": false},
+    "notes": "Adding a type hint (561e4b68) to a method added by fix d8dcd35 (#711). Must stay quiet."
+  }
+]

{blot_git-0.0.1 → blot_git-0.2.0}/docs/PRD.md

@@ -35,7 +35,7 @@ These mistakes are caught late (in CI, review or production) or never. AI coding
 **Goals (v0.1)**
 - G1. Catch the three mistakes above at commit time, locally, in under 500 ms.
 - G2. Stay **quiet**: on typical repos, at most 1 warning per 10 commits, and at least 80% of warnings judged useful on the bench.
-- G3. Install in one command on Windows, macOS and Linux. Stdlib-only Python.
+- G3. Install in one command on Windows, macOS and Linux. Stdlib-only Python on 3.11+ (3.10 also installs `tomli`).
 - G4. Every warning cites real evidence (commit SHA, and PR or issue when available). Nothing is made up.
 
 **Non-goals (v0.1)**
@@ -130,7 +130,7 @@ The user either reads the linked issue and adjusts the change, or commits anyway
 - NFR2. **Quiet:** false-alarm rate on the bench's quiet cases at most 10%.
 - NFR3. **Safety:** never exit non-zero unless `--strict`. Any internal error prints one line and exits 0.
 - NFR4. **Privacy:** no network access except `index --github`. Nothing leaves the machine.
-- NFR5. **Portability:** Python 3.10+, stdlib only. Windows, macOS and Linux tested in CI.
+- NFR5. **Portability:** Python 3.10+. No runtime dependencies on 3.11+; on 3.10, `tomli` reads config files (stdlib `tomllib` arrived in 3.11). Windows, macOS and Linux tested in CI.
 
 ## 8. Architecture
 

{blot_git-0.0.1 → blot_git-0.2.0}/docs/PYPI.md

@@ -10,6 +10,8 @@ Blot warns you *before you commit* when your change:
 
 It runs locally, needs no account or AI, and stays quiet unless the history gives it a real reason to speak.
 
+![Blot catching a real Flask regression](https://raw.githubusercontent.com/Sym-jay/Blot/main/assets/demo/demo.gif)
+
 ```bash
 pip install blot-git
 cd your-repo
@@ -17,6 +19,6 @@ blot index           # one-time, builds .git/blot.db
 blot install-hook    # adds Blot to your pre-commit hook
 ```
 
-> **Status:** pre-alpha. Indexing and the git hook work; the three checks arrive in the next milestone.
+> **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.
 
 Meet Sora the slime, read the docs, or contribute on GitHub: https://github.com/Sym-jay/Blot

{blot_git-0.0.1 → blot_git-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "blot-git"
-version = "0.0.1"
+version = "0.2.0"
 description = "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."
 readme = "docs/PYPI.md"  # text-only; the GitHub README's relative Sora images break on PyPI
 license = { text = "MIT" }
@@ -17,7 +17,8 @@ classifiers = [
   "Topic :: Software Development :: Quality Assurance",
   "Topic :: Software Development :: Version Control :: Git",
 ]
-dependencies = []  # core is stdlib-only: fast hook startup, trivial install
+# core is stdlib-only: fast hook startup, trivial install. 3.10 has no tomllib, so it gets tomli
+dependencies = ["tomli>=1.1.0; python_version < '3.11'"]
 
 [project.urls]
 Homepage = "https://github.com/Sym-jay/Blot"

{blot_git-0.0.1 → blot_git-0.2.0}/src/blot/__init__.py

@@ -1,3 +1,3 @@
 """blot: history-aware pre-commit checks."""
 
-__version__ = "0.0.1"
+__version__ = "0.2.0"