blot-git 0.0.1__py3-none-any.whl

blot/__init__.py

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

blot/__main__.py

@@ -0,0 +1,3 @@
+from blot.cli import main
+
+raise SystemExit(main())

blot/checks/__init__.py

@@ -0,0 +1,18 @@
+"""Check registry."""
+
+from __future__ import annotations
+
+from blot.checks.base import Check, Finding
+from blot.checks.cochange import ForgotRelatedFile
+from blot.checks.readded_bug import ReaddedBug
+from blot.checks.removed_fix import RemovedFix
+from blot.config import Config
+
+REGISTRY: list[type[Check]] = [RemovedFix, ReaddedBug, ForgotRelatedFile]
+
+
+def all_checks(config: Config) -> list[Check]:
+    return [cls() for cls in REGISTRY if cls.id not in config.disabled_checks]
+
+
+__all__ = ["REGISTRY", "Check", "Finding", "all_checks"]

blot/checks/base.py

@@ -0,0 +1,31 @@
+"""The interface every check implements. Adding a check = one new file + one registry line."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from blot.config import Config
+    from blot.diff import FileChange
+    from blot.store import Store
+
+
+@dataclass
+class Finding:
+    check: str  # check id, e.g. "removed-fix"
+    path: str
+    line: int | None  # None for file-level findings (forgot-related-file)
+    message: str  # one or two plain-English sentences
+    evidence: list[str] = field(default_factory=list)  # 'abc1234 "subject" (date, fixes #12)'
+    severity: int = 2
+
+
+class Check(ABC):
+    id: str = ""
+    description: str = ""
+
+    @abstractmethod
+    def run(self, changes: list[FileChange], store: Store, config: Config) -> list[Finding]:
+        """Return findings for the staged changes. Must not call the network; target < 100 ms."""

blot/checks/cochange.py

@@ -0,0 +1,24 @@
+"""Check 3: you changed A, but B almost always changes with A, and B isn't staged.
+
+Algorithm (association rules over commit history):
+    support(A, B)    = number of commits touching both A and B
+    confidence(A→B)  = support(A, B) / commits touching A
+    warn when confidence >= config.cochange_min_confidence
+          and support    >= config.cochange_min_support
+          and B exists at HEAD and is not part of the change
+Commits touching more than config.cochange_max_files_per_commit files are ignored
+(mass reformatting and renames would otherwise link everything to everything).
+"""
+
+from __future__ import annotations
+
+from blot.checks.base import Check, Finding
+
+
+class ForgotRelatedFile(Check):
+    id = "forgot-related-file"
+    description = "Changed a file without the file that usually changes with it"
+
+    def run(self, changes, store, config) -> list[Finding]:
+        # TODO(M2): implement the algorithm above; at most 1 finding per staged file
+        return []

blot/checks/readded_bug.py

@@ -0,0 +1,23 @@
+"""Check 2: you're adding back a line that a load-bearing bug fix deliberately removed.
+
+Algorithm:
+    1. normalize each added line (strip whitespace and trailing comments)
+    2. skip trivial lines: shorter than 12 chars, only brackets/keywords, imports
+    3. look up its hash in fix_removed_lines (same path, or any path if it was renamed)
+    4. skip if an identical line still exists elsewhere in the file at HEAD
+       (then the fix did not remove the idea, only one copy)
+    5. warn with the fix commit that removed it
+"""
+
+from __future__ import annotations
+
+from blot.checks.base import Check, Finding
+
+
+class ReaddedBug(Check):
+    id = "readded-bug"
+    description = "Re-adding a line that a bug fix removed"
+
+    def run(self, changes, store, config) -> list[Finding]:
+        # TODO(M2): implement the algorithm above
+        return []

blot/checks/removed_fix.py

@@ -0,0 +1,22 @@
+"""Check 1: you're deleting or editing lines that a load-bearing bug fix added.
+
+Algorithm:
+    1. for each file, take the removed lines (old line numbers)
+    2. `git blame -w -M -C --porcelain -L a,b HEAD -- <old_path>` for those ranges
+    3. if the blamed commit is a refactor (classify.is_refactor), re-blame at its parent
+       on the original path, up to 3 hops
+    4. warn if the final commit's severity >= config.min_severity
+"""
+
+from __future__ import annotations
+
+from blot.checks.base import Check, Finding
+
+
+class RemovedFix(Check):
+    id = "removed-fix"
+    description = "Changing code that a bug fix added"
+
+    def run(self, changes, store, config) -> list[Finding]:
+        # TODO(M2): implement the algorithm above. Batch blame per file to stay fast.
+        return []

blot/classify.py

@@ -0,0 +1,88 @@
+"""Decide what kind of commit something is. Most of Blot's precision comes from here.
+
+Fix severity:
+    0  not a fix (feature, docs, chore)
+    1  routine fix ("fix typo", "fix lint", a bare "fix stuff")
+    2  load-bearing fix: a fix verb pointing at an issue ("fixes #12"), or a commit that names
+       a real defect (crash, leak, race, regression, CVE, injection, deadlock, data loss, ...)
+
+`is_refactor` flags commits that move code without changing what it does (file splits,
+renames, mass reformatting). When blame lands on one of these, Blot traces further
+back. That is how it finds the 2020 Flask fix behind the 2023 "Split the App..." commit.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass
+class CommitInfo:
+    sha: str
+    subject: str
+    body: str
+    files_changed: int
+    lines_added: int
+    lines_removed: int
+    renames: int
+
+
+_ISSUE = r"(?:#\d+|gh-\d+|[A-Z][A-Z0-9]+-\d+)"
+# "fixes #12" means the commit is the fix; "closes #12" is often just housekeeping.
+_FIX_ISSUE = re.compile(rf"\b(?:fix(?:e[sd])?|resolve[sd]?)\b[:\s]+{_ISSUE}", re.IGNORECASE)
+_ANY_ISSUE = re.compile(rf"(?<![\w/]){_ISSUE}\b")
+_FIX_WORD = re.compile(r"\b(?:fix(?:e[sd]|ing)?|bug(?:fix)?|hotfix|patch(?:e[sd])?|repair(?:e[sd])?|workaround)\b", re.IGNORECASE)
+# Strong defect words make a commit load-bearing on their own; weak ones need a fix verb too.
+_DEFECT = re.compile(
+    r"\b(?:crash(?:e[sd])?|segfault|panic|leak(?:s|ing)?|race(?: condition)?|deadlock|regression|"
+    r"cve-\d{4}-\d+|vulnerab\w*|injection|xss|csrf|ssrf|overflow|underflow|corrupt\w*|"
+    r"data loss|infinite loop|null pointer|use-after-free|reference cycle|off-by-one)\b",
+    re.IGNORECASE,
+)
+_WEAK_DEFECT = re.compile(r"\b(?:hang(?:s|ing)?|timeout|broken|incorrect(?:ly)?|wrong|security)\b", re.IGNORECASE)
+_ROUTINE = re.compile(
+    r"\b(?:typo|typos|lint|linter|flake8|pylint|mypy|ruff|eslint|format(?:ting)?|style|"
+    r"whitespace|spelling|docs?|document\w*|docstring|comment|readme|changelog|warning|ci|build|"
+    r"examples?|tutorial|tests?|testing|translation|note|mention\w*|advice|wording|sentence|links?|gramma\w*)\b",
+    re.IGNORECASE,
+)
+_REFACTOR = re.compile(
+    r"\b(?:move[sd]?|moving|split|splits|splitting|rename[sd]?|renaming|reorganiz\w*|"
+    r"restructur\w*|refactor\w*|reformat\w*|extract(?:ed)?|black|prettier|isort|clang-format)\b",
+    re.IGNORECASE,
+)
+
+
+def fix_severity(commit: CommitInfo, issue_labels: list[str] | None = None) -> int:
+    subject, text = commit.subject, f"{commit.subject}\n{commit.body}"
+    if issue_labels and any("bug" in label.lower() or "security" in label.lower() for label in issue_labels):
+        return 2
+    fixish = bool(_FIX_WORD.search(subject) or _FIX_ISSUE.search(text))
+    if _ROUTINE.search(subject):  # docs/tests/style work, even when it mentions a defect word
+        return 1 if fixish else 0
+    if _DEFECT.search(subject):
+        return 2
+    if _FIX_ISSUE.search(text) or (_WEAK_DEFECT.search(subject) and _FIX_WORD.search(subject)):
+        return 2
+    return 1 if fixish else 0
+
+
+def is_refactor(commit: CommitInfo) -> bool:
+    if _FIX_WORD.search(commit.subject) or _DEFECT.search(commit.subject):
+        return False
+    if _REFACTOR.search(commit.subject):
+        return True
+    if commit.files_changed and commit.renames * 2 >= commit.files_changed:
+        return True
+    big = min(commit.lines_added, commit.lines_removed) >= 50
+    balanced = abs(commit.lines_added - commit.lines_removed) <= 0.1 * max(commit.lines_added, commit.lines_removed, 1)
+    return big and balanced
+
+
+def linked_issues(commit: CommitInfo) -> list[str]:
+    """Issue references in the message, in order, without duplicates."""
+    seen: dict[str, None] = {}
+    for ref in _ANY_ISSUE.findall(f"{commit.subject}\n{commit.body}"):
+        seen.setdefault(ref, None)
+    return list(seen)

blot/cli.py

@@ -0,0 +1,108 @@
+"""blot: history-aware pre-commit checks.
+
+Commands:
+    index         build or refresh the local history index (.git/blot.db)
+    check         run all checks against staged changes (pre-commit) or a commit range
+    why           show the history behind a line: fix commits, PR, linked issues
+    install-hook  add blot to .git/hooks/pre-commit
+    bench         score the checks against bench/cases.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from blot import __version__
+from blot.checks import all_checks
+from blot.config import load_config
+from blot.report import render
+
+
+def _cmd_index(args: argparse.Namespace) -> int:
+    from blot.index import build_index
+
+    result = build_index(args.repo, full=args.full, github=args.github)
+    if not args.quiet:
+        kind = "full" if result.full else "incremental"
+        print(f"blot: indexed {result.commits} commits ({result.fixes} load-bearing fixes), "
+              f"{kind}, in {result.seconds:.1f}s")
+    return 0
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    from blot.diff import read_changes
+    from blot.store import Store
+
+    try:
+        config = load_config(args.repo)
+        store = Store.open(args.repo)
+        if store is None:
+            # Never break a commit because the index is missing; just say how to fix it.
+            print("blot: no index yet, run `blot index` (commit allowed)", file=sys.stderr)
+            return 0
+        changes = read_changes(args.repo, rev_range=args.range)
+        findings = [f for check in all_checks(config) for f in check.run(changes, store, config)]
+    except Exception as exc:  # Blot's own failures must never block a commit
+        print(f"blot: internal error, skipping checks ({exc.__class__.__name__}: {exc})", file=sys.stderr)
+        return 0
+    print(render(findings, fmt=args.format), end="")
+    return 1 if (args.strict and findings) else 0
+
+
+def _cmd_why(args: argparse.Namespace) -> int:
+    raise NotImplementedError("TODO(M3): trace a line to its explaining commits")
+
+
+def _cmd_install_hook(args: argparse.Namespace) -> int:
+    from blot import hooks
+
+    if args.uninstall:
+        print(f"blot: pre-commit hook {hooks.uninstall(args.repo)}")
+        return 0
+    status = hooks.install(args.repo)
+    print(f"blot: pre-commit hook {status} ({hooks.hook_path(args.repo)})")
+    if status != "already installed":
+        print("blot: run `blot index` once so the checks have history to work with")
+    return 0
+
+
+def _cmd_bench(args: argparse.Namespace) -> int:
+    raise NotImplementedError("TODO(M4): run bench/cases.json and print precision/recall per check")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="blot", description="History-aware pre-commit checks.")
+    parser.add_argument("--version", action="version", version=f"blot {__version__}")
+    parser.add_argument("--repo", default=".", help="path to the git repository (default: .)")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("index", help="build or refresh the local history index")
+    p.add_argument("--full", action="store_true", help="rebuild from scratch instead of incrementally")
+    p.add_argument("--github", action="store_true", help="add PR/issue data via the gh CLI (milestone M3)")
+    p.add_argument("--quiet", action="store_true", help="print nothing on success (for git hooks)")
+    p.set_defaults(func=_cmd_index)
+
+    p = sub.add_parser("check", help="run history checks on staged changes or a commit range")
+    p.add_argument("--staged", action="store_true", help="check staged changes (the default)")
+    p.add_argument("--range", metavar="A..B", help="check a commit range instead, e.g. origin/main..HEAD")
+    p.add_argument("--strict", action="store_true", help="exit 1 when there are findings (blocks the commit)")
+    p.add_argument("--format", choices=["text", "json"], default="text")
+    p.set_defaults(func=_cmd_check)
+
+    p = sub.add_parser("why", help="show the history behind a line")
+    p.add_argument("location", metavar="FILE:LINE")
+    p.set_defaults(func=_cmd_why)
+
+    p = sub.add_parser("install-hook", help="add blot to .git/hooks/pre-commit")
+    p.add_argument("--uninstall", action="store_true", help="remove blot's lines from the hook")
+    p.set_defaults(func=_cmd_install_hook)
+
+    p = sub.add_parser("bench", help="score checks against bench/cases.json")
+    p.set_defaults(func=_cmd_bench)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)

blot/config.py

@@ -0,0 +1,71 @@
+"""Settings, read from `[tool.blot]` in pyproject.toml and/or a `.blot.toml` file.
+
+`.blot.toml` wins over pyproject.toml. Keys may use dashes or underscores:
+
+    [tool.blot]
+    min-severity = 2
+    cochange-min-confidence = 0.8
+    disabled-checks = ["forgot-related-file"]
+    ignore-paths = ["docs/*", "*.lock"]
+
+TOML parsing needs Python 3.11+ (stdlib `tomllib`). On 3.10 the defaults are used.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass, field, fields
+
+
+@dataclass
+class Config:
+    # removed-fix / re-added-bug: only warn for commits classified at or above this severity
+    min_severity: int = 2
+    # forgot-related-file: confidence that B changes when A changes, and minimum joint commits
+    cochange_min_confidence: float = 0.8
+    cochange_min_support: int = 5
+    # skip commits touching more files than this when mining co-change (mass reformat, renames)
+    cochange_max_files_per_commit: int = 30
+    disabled_checks: list[str] = field(default_factory=list)
+    ignore_paths: list[str] = field(default_factory=list)
+
+
+def _read_toml(path: str) -> dict:
+    try:
+        import tomllib
+    except ModuleNotFoundError:  # Python 3.10
+        return {}
+    try:
+        with open(path, "rb") as f:
+            return tomllib.load(f)
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        print(f"blot: ignoring {os.path.basename(path)}: {exc}", file=sys.stderr)
+        return {}
+
+
+def load_config(repo: str) -> Config:
+    raw: dict = {}
+    pyproject = os.path.join(repo, "pyproject.toml")
+    if os.path.exists(pyproject):
+        raw.update(_read_toml(pyproject).get("tool", {}).get("blot", {}))
+    own = os.path.join(repo, ".blot.toml")
+    if os.path.exists(own):
+        raw.update(_read_toml(own))
+
+    config = Config()
+    known = {f.name: f for f in fields(Config)}
+    for key, value in raw.items():
+        name = key.replace("-", "_")
+        if name not in known:
+            print(f"blot: unknown config key {key!r} (ignored)", file=sys.stderr)
+            continue
+        default = getattr(config, name)
+        expected = type(default)
+        if expected is float and isinstance(value, int):
+            value = float(value)
+        if not isinstance(value, expected) or (expected is int and isinstance(value, bool)):
+            print(f"blot: config key {key!r} should be {expected.__name__} (ignored)", file=sys.stderr)
+            continue
+        setattr(config, name, value)
+    return config

blot/diff.py

@@ -0,0 +1,68 @@
+"""Turn `git diff` output into per-file added and removed lines with line numbers."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass, field
+
+from blot.git import run_git
+
+_HUNK = re.compile(r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@")
+_TRAILING_COMMENT = re.compile(r"\s+(?:#|//)\s.*$")
+_TRIVIAL = re.compile(r"^(?:[\s{}()\[\];,.:]*|(?:import|from|#include|using|package|require)\b.*|(?:return|pass|break|continue|else|end|try|finally)\b\W*)$")
+
+
+def normalize_line(text: str) -> str:
+    """Collapse whitespace and drop trailing comments so cosmetic edits still match."""
+    return " ".join(_TRAILING_COMMENT.sub("", text).split())
+
+
+def is_trivial_line(normalized: str) -> bool:
+    """Lines too generic to mean anything on their own: brackets, imports, bare keywords."""
+    return len(normalized) < 12 or bool(_TRIVIAL.match(normalized))
+
+
+def line_hash(normalized: str) -> str:
+    return hashlib.blake2b(normalized.encode("utf-8"), digest_size=8).hexdigest()
+
+
+@dataclass
+class FileChange:
+    path: str  # path after the change (old path for deleted files)
+    old_path: str | None  # path before the change (None for new files)
+    removed: list[tuple[int, str]] = field(default_factory=list)  # (old line number, text)
+    added: list[tuple[int, str]] = field(default_factory=list)  # (new line number, text)
+
+
+def parse_unified_diff(text: str) -> list[FileChange]:
+    """Parse `git diff -U0` output. Binary files and mode-only changes produce no lines."""
+    changes: list[FileChange] = []
+    current: FileChange | None = None
+    old_path: str | None = None
+    old_no = new_no = 0
+    for line in text.splitlines():
+        if line.startswith("--- "):
+            old_path = None if line == "--- /dev/null" else line[6:]  # strip "--- a/"
+        elif line.startswith("+++ "):
+            new_path = old_path if line == "+++ /dev/null" else line[6:]  # strip "+++ b/"
+            current = FileChange(path=new_path or "", old_path=old_path)
+            changes.append(current)
+        elif current is None:
+            continue
+        elif m := _HUNK.match(line):
+            old_no, new_no = int(m.group(1)), int(m.group(3))
+        elif line.startswith("-"):
+            current.removed.append((old_no, line[1:]))
+            old_no += 1
+        elif line.startswith("+"):
+            current.added.append((new_no, line[1:]))
+            new_no += 1
+    return changes
+
+
+def read_changes(repo: str, rev_range: str | None = None) -> list[FileChange]:
+    """Staged changes by default, or the changes in a commit range like `origin/main..HEAD`."""
+    args = ["diff", "-U0", "--no-color", "--no-ext-diff", "-M"]
+    args.append(rev_range if rev_range else "--cached")
+    return parse_unified_diff(run_git(repo, *args))

blot/git.py

@@ -0,0 +1,17 @@
+"""Thin wrapper around the git CLI. All git access goes through here so tests can fake it."""
+
+from __future__ import annotations
+
+import subprocess
+
+
+def run_git(repo: str, *args: str) -> str:
+    result = subprocess.run(
+        ["git", "-C", repo, *args],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        check=True,
+    )
+    return result.stdout

blot/hooks.py

@@ -0,0 +1,77 @@
+"""Install and remove Blot's git pre-commit hook without clobbering existing hooks.
+
+Blot's lines live between two markers, so we can append to a hook someone else wrote and
+later remove exactly what we added. The hook calls this Python interpreter by absolute path,
+so it works from IDEs whose PATH lacks your virtualenv, and it skips itself (never blocks a
+commit) if that interpreter disappears.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import sys
+
+from blot.git import run_git
+
+BEGIN, END = "# >>> blot >>>", "# <<< blot <<<"
+
+
+def hook_path(repo: str, name: str = "pre-commit") -> str:
+    path = run_git(repo, "rev-parse", "--git-path", f"hooks/{name}").strip()
+    return path if os.path.isabs(path) else os.path.join(repo, path)
+
+
+def _block(python: str) -> str:
+    py = python.replace("\\", "/")
+    return (
+        f"{BEGIN}\n"
+        f'if [ -x "{py}" ]; then "{py}" -m blot check || exit $?; fi\n'
+        f"{END}\n"
+    )
+
+
+def install(repo: str, python: str | None = None) -> str:
+    """Add Blot to the pre-commit hook. Returns 'installed', 'appended' or 'already installed'."""
+    path = hook_path(repo)
+    block = _block(python or sys.executable)
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    if os.path.exists(path):
+        with open(path, encoding="utf-8") as f:
+            current = f.read()
+        if BEGIN in current:
+            return "already installed"
+        with open(path, "a", encoding="utf-8", newline="\n") as f:
+            f.write(("" if current.endswith("\n") else "\n") + block)
+        result = "appended"
+    else:
+        with open(path, "w", encoding="utf-8", newline="\n") as f:
+            f.write("#!/bin/sh\n" + block)
+        result = "installed"
+    os.chmod(path, os.stat(path).st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    return result
+
+
+def uninstall(repo: str) -> str:
+    """Remove Blot's block. Deletes the hook file only if nothing else is left in it."""
+    path = hook_path(repo)
+    if not os.path.exists(path):
+        return "not installed"
+    with open(path, encoding="utf-8") as f:
+        lines = f.read().splitlines(keepends=True)
+    if not any(line.strip() == BEGIN for line in lines):
+        return "not installed"
+    kept, inside = [], False
+    for line in lines:
+        if line.strip() == BEGIN:
+            inside = True
+        elif line.strip() == END:
+            inside = False
+        elif not inside:
+            kept.append(line)
+    if "".join(kept).strip() in ("", "#!/bin/sh"):
+        os.remove(path)
+    else:
+        with open(path, "w", encoding="utf-8", newline="\n") as f:
+            f.writelines(kept)
+    return "removed"

blot/index.py

@@ -0,0 +1,144 @@
+"""Build or incrementally refresh the history index.
+
+Steps:
+    1. walk `git log --numstat -M` from the last indexed sha to HEAD (no merges)
+    2. classify each commit (classify.py), store severity and refactor flags
+    3. for load-bearing fixes, hash the lines they removed   -> fix_removed_lines
+    4. count file pairs changed together (skip huge commits) -> file_commits / cochange
+Targets: under 60 s for 50k commits on a laptop; incremental refresh under 1 s.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import time
+from dataclasses import dataclass
+
+from blot.classify import CommitInfo, fix_severity, is_refactor, linked_issues
+from blot.config import Config, load_config
+from blot.diff import is_trivial_line, line_hash, normalize_line, parse_unified_diff
+from blot.git import run_git
+from blot.store import CommitRow, Store
+
+_RECORD, _FIELD = "\x1e", "\x1f"
+_BRACE_RENAME = re.compile(r"\{([^{}]*) => ([^{}]*)\}")
+_SHOW_BATCH = 200
+
+
+@dataclass
+class IndexResult:
+    commits: int
+    fixes: int
+    seconds: float
+    full: bool
+
+
+def _new_path(numstat_path: str) -> tuple[str, bool]:
+    """Resolve rename notation (`a/{x => y}/b` or `old => new`) to the new path."""
+    if "=>" not in numstat_path:
+        return numstat_path, False
+    if "{" in numstat_path:
+        path = _BRACE_RENAME.sub(lambda m: m.group(2), numstat_path)
+        return path.replace("//", "/"), True
+    return numstat_path.split(" => ", 1)[1], True
+
+
+def _parse_log(text: str) -> list[tuple[CommitInfo, str, list[str]]]:
+    """Parse our custom `git log --numstat` format into (info, date, paths)."""
+    commits = []
+    for record in text.split(_RECORD)[1:]:
+        sha, date, subject, rest = record.split(_FIELD, 3)
+        body, _, numstat = rest.partition(_FIELD)
+        added = removed = renames = 0
+        paths: list[str] = []
+        for line in numstat.strip().splitlines():
+            parts = line.split("\t")
+            if len(parts) != 3:
+                continue
+            a, r, raw_path = parts
+            path, renamed = _new_path(raw_path)
+            renames += renamed
+            added += int(a) if a.isdigit() else 0
+            removed += int(r) if r.isdigit() else 0
+            paths.append(path)
+        info = CommitInfo(sha, subject, body.strip(), len(paths), added, removed, renames)
+        commits.append((info, date, paths))
+    return commits
+
+
+def _is_ancestor(repo: str, older: str, newer: str) -> bool:
+    try:
+        subprocess.run(
+            ["git", "-C", repo, "merge-base", "--is-ancestor", older, newer],
+            capture_output=True, check=True,
+        )
+        return True
+    except subprocess.CalledProcessError:
+        return False
+
+
+def _head(repo: str) -> str | None:
+    try:
+        return run_git(repo, "rev-parse", "--verify", "-q", "HEAD").strip() or None
+    except subprocess.CalledProcessError:
+        return None
+
+
+def _removed_lines(repo: str, shas: list[str]) -> list[tuple[str, str, str]]:
+    """(line_hash, path, sha) for every meaningful line the given commits deleted."""
+    rows: list[tuple[str, str, str]] = []
+    for i in range(0, len(shas), _SHOW_BATCH):
+        batch = shas[i : i + _SHOW_BATCH]
+        out = run_git(repo, "show", f"--format={_RECORD}%H", "-U0", "--no-color", "--no-ext-diff", "-M", *batch)
+        for chunk in out.split(_RECORD)[1:]:
+            sha, _, diff_text = chunk.partition("\n")
+            for change in parse_unified_diff(diff_text):
+                path = change.old_path or change.path
+                for _, text in change.removed:
+                    norm = normalize_line(text)
+                    if not is_trivial_line(norm):
+                        rows.append((line_hash(norm), path, sha.strip()))
+    return rows
+
+
+def build_index(repo: str, full: bool = False, github: bool = False, config: Config | None = None) -> IndexResult:
+    start = time.perf_counter()
+    config = config or load_config(repo)
+    head = _head(repo)
+
+    store = Store.open(repo)
+    last = store.get_meta("last_sha") if store else None
+    if store:
+        store.close()
+    rebuild = full or not last or (head is not None and not _is_ancestor(repo, last, head))
+    store = Store.create(repo, fresh=rebuild)
+
+    if head is None or (not rebuild and last == head):
+        store.set_meta("last_sha", head or "")
+        store.commit()
+        store.close()
+        return IndexResult(0, 0, time.perf_counter() - start, rebuild)
+
+    rev = head if rebuild else f"{last}..{head}"
+    fmt = f"--format={_RECORD}%H{_FIELD}%aI{_FIELD}%s{_FIELD}%b{_FIELD}"
+    log = run_git(repo, "log", "--no-merges", "-M", "--numstat", fmt, rev)
+    parsed = _parse_log(log)
+
+    fix_shas = []
+    for info, date, paths in parsed:
+        severity = fix_severity(info)
+        row = CommitRow(info.sha, date, info.subject, severity, is_refactor(info), info.files_changed, linked_issues(info))
+        store.add_commit(row)
+        if severity >= 2:
+            fix_shas.append(info.sha)
+        if 0 < len(paths) <= config.cochange_max_files_per_commit:
+            store.add_cochange(paths)
+
+    store.add_fix_removed_lines(_removed_lines(repo, fix_shas))
+    store.set_meta("last_sha", head)
+    store.commit()
+    store.close()
+    if github:
+        print("blot: --github enrichment arrives in milestone M3; indexed git history only.")
+    return IndexResult(len(parsed), len(fix_shas), time.perf_counter() - start, rebuild)

blot/report.py

@@ -0,0 +1,24 @@
+"""Render findings for people (text) or tools (json)."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+
+from blot.checks.base import Finding
+
+
+def render(findings: list[Finding], fmt: str = "text") -> str:
+    if fmt == "json":
+        return json.dumps([asdict(f) for f in findings], indent=2) + "\n"
+    if not findings:
+        return ""
+    plural = "s" if len(findings) != 1 else ""
+    lines = [f"blot: {len(findings)} warning{plural}", ""]
+    for f in findings:
+        where = f"{f.path}:{f.line}" if f.line else f.path
+        lines.append(f"  ! {f.check}  {where}")
+        lines.extend(f"    {text}" for text in f.message.splitlines())
+        lines.extend(f"    {ref}" for ref in f.evidence)
+        lines.append("")
+    return "\n".join(lines) + "\n"

blot/store.py

@@ -0,0 +1,163 @@
+"""Local SQLite index stored at .git/blot.db. Never committed, never leaves the machine.
+
+Tables:
+    meta(key, value)                           schema version, last indexed sha
+    commits(sha, date, subject, severity, is_refactor, files, issues)
+    fix_removed_lines(line_hash, path, sha)    normalized lines deleted by load-bearing fixes
+    file_commits(path, count)                  how many indexed commits touched each file
+    cochange(path_a, path_b, support)          commits touching both files (path_a < path_b)
+"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+from dataclasses import dataclass
+
+from blot.git import run_git
+
+SCHEMA_VERSION = 1
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT);
+CREATE TABLE IF NOT EXISTS commits (
+    sha TEXT PRIMARY KEY, date TEXT, subject TEXT,
+    severity INTEGER, is_refactor INTEGER, files INTEGER, issues TEXT
+);
+CREATE TABLE IF NOT EXISTS fix_removed_lines (line_hash TEXT, path TEXT, sha TEXT);
+CREATE INDEX IF NOT EXISTS fix_removed_lines_hash ON fix_removed_lines (line_hash);
+CREATE TABLE IF NOT EXISTS file_commits (path TEXT PRIMARY KEY, count INTEGER);
+CREATE TABLE IF NOT EXISTS cochange (
+    path_a TEXT, path_b TEXT, support INTEGER, PRIMARY KEY (path_a, path_b)
+);
+"""
+
+
+@dataclass
+class CommitRow:
+    sha: str
+    date: str
+    subject: str
+    severity: int
+    is_refactor: bool
+    files: int
+    issues: list[str]
+
+
+class Store:
+    def __init__(self, conn: sqlite3.Connection):
+        self.conn = conn
+
+    @staticmethod
+    def db_path(repo: str) -> str:
+        git_dir = run_git(repo, "rev-parse", "--absolute-git-dir").strip()
+        return os.path.join(git_dir, "blot.db")
+
+    @classmethod
+    def open(cls, repo: str) -> Store | None:
+        """Return the index, or None if `blot index` has never been run (or it is outdated)."""
+        path = cls.db_path(repo)
+        if not os.path.exists(path):
+            return None
+        store = cls(sqlite3.connect(path))
+        if store.get_meta("schema_version") != str(SCHEMA_VERSION):
+            store.close()
+            return None
+        return store
+
+    @classmethod
+    def create(cls, repo: str, fresh: bool = False) -> Store:
+        path = cls.db_path(repo)
+        if fresh and os.path.exists(path):
+            os.remove(path)
+        store = cls(sqlite3.connect(path))
+        if store._table_exists("meta") and store.get_meta("schema_version") != str(SCHEMA_VERSION):
+            store.close()
+            os.remove(path)
+            store = cls(sqlite3.connect(path))
+        store.conn.executescript(_SCHEMA)
+        store.set_meta("schema_version", str(SCHEMA_VERSION))
+        return store
+
+    def close(self) -> None:
+        self.conn.close()
+
+    def _table_exists(self, name: str) -> bool:
+        row = self.conn.execute("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (name,)).fetchone()
+        return row is not None
+
+    # --- meta ---------------------------------------------------------------------------
+
+    def get_meta(self, key: str) -> str | None:
+        try:
+            row = self.conn.execute("SELECT value FROM meta WHERE key=?", (key,)).fetchone()
+        except sqlite3.OperationalError:
+            return None
+        return row[0] if row else None
+
+    def set_meta(self, key: str, value: str) -> None:
+        self.conn.execute("INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)", (key, value))
+
+    # --- writes (used by index.py) ------------------------------------------------------
+
+    def add_commit(self, row: CommitRow) -> None:
+        self.conn.execute(
+            "INSERT OR REPLACE INTO commits VALUES (?, ?, ?, ?, ?, ?, ?)",
+            (row.sha, row.date, row.subject, row.severity, int(row.is_refactor), row.files, ",".join(row.issues)),
+        )
+
+    def add_fix_removed_lines(self, rows: list[tuple[str, str, str]]) -> None:
+        self.conn.executemany("INSERT INTO fix_removed_lines VALUES (?, ?, ?)", rows)
+
+    def add_cochange(self, paths: list[str]) -> None:
+        """Record one commit touching `paths` (already filtered for huge commits)."""
+        self.conn.executemany(
+            "INSERT INTO file_commits VALUES (?, 1) ON CONFLICT(path) DO UPDATE SET count = count + 1",
+            [(p,) for p in paths],
+        )
+        ordered = sorted(set(paths))
+        pairs = [(a, b) for i, a in enumerate(ordered) for b in ordered[i + 1 :]]
+        self.conn.executemany(
+            "INSERT INTO cochange VALUES (?, ?, 1) ON CONFLICT(path_a, path_b) DO UPDATE SET support = support + 1",
+            pairs,
+        )
+
+    def commit(self) -> None:
+        self.conn.commit()
+
+    # --- reads (used by checks) ---------------------------------------------------------
+
+    def get_commit(self, sha: str) -> CommitRow | None:
+        row = self.conn.execute("SELECT * FROM commits WHERE sha=?", (sha,)).fetchone()
+        if row is None:
+            return None
+        sha, date, subject, severity, refactor, files, issues = row
+        return CommitRow(sha, date, subject, severity, bool(refactor), files, [i for i in issues.split(",") if i])
+
+    def fixes_that_removed(self, line_hash: str) -> list[tuple[str, str]]:
+        """(path, sha) of load-bearing fixes that deleted a line with this hash."""
+        return self.conn.execute("SELECT path, sha FROM fix_removed_lines WHERE line_hash=?", (line_hash,)).fetchall()
+
+    def partners(self, path: str, min_support: int, min_confidence: float) -> list[tuple[str, int, float]]:
+        """Files that usually change with `path`: (partner, support, confidence path→partner)."""
+        row = self.conn.execute("SELECT count FROM file_commits WHERE path=?", (path,)).fetchone()
+        if not row or row[0] == 0:
+            return []
+        total = row[0]
+        rows = self.conn.execute(
+            "SELECT CASE WHEN path_a=? THEN path_b ELSE path_a END, support FROM cochange "
+            "WHERE (path_a=? OR path_b=?) AND support >= ?",
+            (path, path, path, min_support),
+        ).fetchall()
+        result = [(p, s, s / total) for p, s in rows if s / total >= min_confidence]
+        return sorted(result, key=lambda r: (-r[2], -r[1], r[0]))
+
+    def stats(self) -> dict[str, int]:
+        q = lambda sql: self.conn.execute(sql).fetchone()[0]  # noqa: E731
+        return {
+            "commits": q("SELECT COUNT(*) FROM commits"),
+            "fixes": q("SELECT COUNT(*) FROM commits WHERE severity >= 2"),
+            "refactors": q("SELECT COUNT(*) FROM commits WHERE is_refactor = 1"),
+            "fix_lines": q("SELECT COUNT(*) FROM fix_removed_lines"),
+            "pairs": q("SELECT COUNT(*) FROM cochange"),
+        }

blot_git-0.0.1.dist-info/METADATA

@@ -0,0 +1,46 @@
+Metadata-Version: 2.5
+Name: blot-git
+Version: 0.0.1
+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
+Author: Shyam
+License: MIT
+License-File: LICENSE
+Keywords: code-review,developer-tools,git,git-history,pre-commit
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: github
+Description-Content-Type: text/markdown
+
+# Blot
+
+**A pre-commit check that has read your project's history.**
+
+Blot warns you *before you commit* when your change:
+
+- **removes a fix**: deletes or edits code that was added to fix a bug
+- **re-adds a bug**: brings back a line that a bug fix deliberately removed
+- **forgets a related file**: changes `A` but not `B`, when the two almost always change together
+
+It runs locally, needs no account or AI, and stays quiet unless the history gives it a real reason to speak.
+
+```bash
+pip install blot-git
+cd your-repo
+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.
+
+Meet Sora the slime, read the docs, or contribute on GitHub: https://github.com/Sym-jay/Blot

blot_git-0.0.1.dist-info/RECORD

@@ -0,0 +1,21 @@
+blot/__init__.py,sha256=SsqM85lr7OEfS7nXudvei3DFahDzZ5Glb4FYpzI0qDY,68
+blot/__main__.py,sha256=oyNZ2-GkzpZ38XfikRpyYxm3t3mzYqJGbALzIrNX5y4,52
+blot/classify.py,sha256=bJ7P8nG9y1Oj2FfQK2L1Gw5nUf5ncQL61VzPh-Gilo8,3883
+blot/cli.py,sha256=SUhSVNXoF3Ir-aUd5UHUIwgf8zHNig1XuhMQ7NXtVD8,4611
+blot/config.py,sha256=ODXJ80Z29awuu88m78xZoWDBehZTvrQf8hlIXhlT_tk,2494
+blot/diff.py,sha256=dEnm7h3ZEvlma76MpoTC9VtlPMPq6UNaw0TbXee73sc,2789
+blot/git.py,sha256=lmmhM2mJQ2ouN3MxvhnTBqWtD39x28JVadsM3q3Dnkk,410
+blot/hooks.py,sha256=7keSL3VxotCl3740hvB_3QHAQeuKDYk0oYJx2oDCdyI,2669
+blot/index.py,sha256=i7u7SGpyx19nBVR5GErzq1ZxEzgLjiTwPV1FWr4JqN0,5436
+blot/report.py,sha256=jKTxWdmFOr9yHoySOhRiw6v38_vCxYYwAApG7brAYPc,799
+blot/store.py,sha256=F99MFNviCLAjfdzNmO4UPbcoWrm6bqLmosxRlqnlTdA,6683
+blot/checks/__init__.py,sha256=GPt2jo5SXwv62FRFpvoRQjKWxWiIn9bMx9W4ZHnhNds,541
+blot/checks/base.py,sha256=J7Xm9GQ1GAQSGklknB3tr4BNH6Q7bXkh2UubGa9oNls,977
+blot/checks/cochange.py,sha256=Ru38RkHeV6q-YU8sPioEan9LPC84j7_xnVMIg12eXJQ,990
+blot/checks/readded_bug.py,sha256=v2dnRkhzzdenq8Q2Mgoq1dCd-tOUx8x9AQbqnoCfIRE,853
+blot/checks/removed_fix.py,sha256=hjduW6vX8vbaguvbBt8ZEjiy8NzhFq3u7AW3s9Eck4M,791
+blot_git-0.0.1.dist-info/METADATA,sha256=uAz9LFisdxy9CpX8SAGRQrqN5q53JmDc_Shvfl_jOsQ,1834
+blot_git-0.0.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+blot_git-0.0.1.dist-info/entry_points.txt,sha256=7V9oo1pus8MDkPa_48M7jRFokfz291bySD2a_iART40,39
+blot_git-0.0.1.dist-info/licenses/LICENSE,sha256=IDNp7cs4d4lB1xwgGPf4W5Zp3yUNa3REMjw2T4bM-Gs,1062
+blot_git-0.0.1.dist-info/RECORD,,

blot_git-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

blot_git-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+blot = blot.cli:main

blot_git-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shyam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.