crapkit 0.2.0__py3-none-any.whl

crapkit/gitio.py

@@ -0,0 +1,504 @@
+"""Git shell layer: the tracked-file universe and the current commit."""
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+import threading
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+from .errors import GitError
+
+_OBJECT_NAME = re.compile(r"[0-9a-f]{40}|[0-9a-f]{64}")
+
+
+def _git(root: Path, *args: str) -> str:
+    try:
+        res = subprocess.run(["git", *args], cwd=root, capture_output=True, text=True, encoding="utf-8")
+    except FileNotFoundError as exc:
+        raise GitError("git executable not found") from exc
+    if res.returncode != 0:
+        raise GitError(f"git {' '.join(args)} failed in {root}: {res.stderr.strip()}")
+    return res.stdout
+
+
+def _git_lines(root: Path, *args: str) -> Iterator[str]:
+    """Same contract as _git, streamed: the caller sees one line at a time.
+
+    A failing command yields nothing and raises at the end of iteration, so the
+    consumer never mistakes an empty stream for an empty history.
+    """
+    try:
+        proc = subprocess.Popen(["git", *args], cwd=root, stdout=subprocess.PIPE,
+                                stderr=subprocess.PIPE, text=True, encoding="utf-8")
+    except FileNotFoundError as exc:
+        raise GitError("git executable not found") from exc
+    with proc:
+        yield from proc.stdout
+        stderr = proc.stderr.read()
+    if proc.returncode != 0:
+        raise GitError(f"git {' '.join(args)} failed in {root}: {stderr.strip()}")
+
+
+def stage_path(root: Path, rel_path: str) -> None:
+    """git add one path — the hook override's ratchet debt must land IN the commit."""
+    _git(root, "add", "--", rel_path)
+
+
+def ls_files(root: Path) -> list[str]:
+    out = _git(root, "ls-files", "-z")
+    return [p for p in out.split("\0") if p]
+
+
+def untracked_files(root: Path) -> list[str]:
+    """Paths `git add` would pick up: untracked and not ignored.
+
+    git applies the ignore rules, so a build directory never reads as source
+    somebody forgot to add.
+    """
+    out = _git(root, "ls-files", "--others", "--exclude-standard", "-z")
+    return [p for p in out.split("\0") if p]
+
+
+def config_value(root: Path, key: str) -> str:
+    """One `git config` value, or "" when it is unset.
+
+    `git config --get` exits 1 on an unset key, which is an answer rather than a
+    failure — every caller here asks about a setting the repo need not have.
+    """
+    try:
+        return _git(root, "config", "--get", key).strip()
+    except GitError:
+        return ""
+
+
+def index_modes(root: Path, pathspec: str) -> dict[str, str]:
+    """path -> index mode for everything git tracks under `pathspec`.
+
+    `git ls-files -s` is the only place the executable bit is readable on
+    Windows, where the filesystem has no such bit and the working copy always
+    looks 0644.
+    """
+    out = _git(root, "ls-files", "-s", "-z", "--", pathspec)
+    modes = {}
+    for record in out.split("\0"):
+        if record:
+            meta, _, path = record.partition("\t")
+            modes[path.replace("\\", "/")] = meta.split(" ", 1)[0]
+    return modes
+
+
+def staged_diff(root: Path) -> str:
+    # --no-renames: a renamed file becomes delete+add, so a rename stays a
+    # touched file and its functions still face the gate (and the old ratchet
+    # entry's drop is matched by fresh gating at the new path).
+    return _git(root, "diff", "--cached", "-U0", "--no-renames")
+
+
+def unstaged_paths(root: Path) -> set[str]:
+    """Tracked files whose working-tree content differs from the index.
+
+    git decides it, through its own filters. Comparing a staged blob to the
+    file's raw bytes reads every file as different under `core.autocrlf=true` —
+    git-for-windows' installer default — because the blob holds LF and the
+    checkout holds CRLF by design.
+    """
+    out = _git(root, "diff", "--name-only", "--no-renames")
+    return {line.strip().replace("\\", "/") for line in out.splitlines() if line.strip()}
+
+
+def diff_since(root: Path, commit: str) -> str:
+    return _git(root, "diff", commit, "-U0", "--no-renames")
+
+
+def diff_names_since(root: Path, commit: str) -> list[str]:
+    """Files with committed changes between a commit and HEAD."""
+    out = _git(root, "diff", "--name-only", "--no-renames", commit, "HEAD")
+    return [line.strip().replace("\\", "/") for line in out.splitlines() if line.strip()]
+
+
+def _rename_pairs(fields: list[str]) -> dict[str, str]:
+    """Walk `--name-status -z` records: a status field, then one path — two for R and C.
+
+    Consuming one path per record would read a rename's destination as the next
+    record's status and shift every entry after it.
+    """
+    pairs: dict[str, str] = {}
+    i = 0
+    while i < len(fields) and fields[i]:
+        status = fields[i]
+        paths = 2 if status[0] in ("R", "C") else 1
+        if status[0] == "R":
+            pairs[fields[i + 1].replace("\\", "/")] = fields[i + 2].replace("\\", "/")
+        i += 1 + paths
+    return pairs
+
+
+def renamed_paths(root: Path, since: str, *, similarity: int = 50) -> dict[str, str]:
+    """old path -> new path for files git reads as renamed between `since` and HEAD.
+
+    Tree-to-tree, not a walk of history: a rename here is content similarity
+    between the two endpoints, so widening the window costs nothing extra and
+    cannot invent a pairing git does not already see. Copies are excluded — the
+    source still exists, so nothing about it moved.
+    """
+    out = _git(root, "diff", "--name-status", f"-M{similarity}", "-z", since, "HEAD")
+    return _rename_pairs(out.split("\0"))
+
+
+def status_names(root: Path) -> list[str]:
+    """Files with uncommitted (staged or unstaged) changes in the working tree."""
+    out = _git(root, "status", "--porcelain", "--untracked-files=no")
+    return [line[3:].strip().replace("\\", "/") for line in out.splitlines() if len(line) > 3]
+
+
+def merge_base(root: Path, ref: str) -> str:
+    """The commit REF and HEAD forked from — a branch's real diff basis, which
+    is what a mid-branch run's own commit is not."""
+    out = _git(root, "merge-base", ref, "HEAD").strip()
+    if not out:
+        raise GitError(f"no merge base between {ref} and HEAD in {root}")
+    return out
+
+
+def is_ancestor(root: Path, commit: str, other: str = "HEAD") -> bool:
+    """True when `commit` is at or behind `other`; git counts a commit as its own
+    ancestor, which is what "at or behind" needs."""
+    try:
+        res = subprocess.run(["git", "merge-base", "--is-ancestor", commit, other],
+                             cwd=root, capture_output=True)
+    except FileNotFoundError as exc:
+        raise GitError("git executable not found") from exc
+    return res.returncode == 0
+
+
+def _batch_stream(root: Path, requests: bytes) -> bytes:
+    try:
+        res = subprocess.run(["git", "cat-file", "--batch"], cwd=root,
+                             input=requests, capture_output=True)
+    except FileNotFoundError as exc:
+        raise GitError("git executable not found") from exc
+    if res.returncode != 0:
+        raise GitError(f"git cat-file --batch failed in {root}: "
+                       f"{res.stderr.decode('utf-8', 'replace').strip()}")
+    return res.stdout
+
+
+def _framed_blob(stream: bytes, pos: int) -> tuple[bytes, int]:
+    """One record: `<oid> blob <size>` header line, exactly size bytes, then LF.
+
+    Sliced by the declared byte count, never split on newlines — blobs are
+    binary. A path absent from the index gets a `<request> missing` line and a
+    zero exit, so the absent case is detected here, not from a return code.
+    """
+    end = stream.index(b"\n", pos)
+    header = stream[pos:end].decode("utf-8", "replace")
+    if header.endswith(" missing"):
+        raise GitError(f"git cat-file --batch: {header[:-len(' missing')]} is not in the index")
+    body_at = end + 1
+    size = int(header.rsplit(" ", 1)[1])
+    return stream[body_at:body_at + size], body_at + size + 1
+
+
+def _framed_blobs(stream: bytes, rel_paths: list[str]) -> dict[str, bytes]:
+    """The batch answer split back into one blob per requested path, in order."""
+    blobs: dict[str, bytes] = {}
+    pos = 0
+    for rel in rel_paths:
+        blobs[rel], pos = _framed_blob(stream, pos)
+    return blobs
+
+
+def staged_blobs(root: Path, rel_paths: list[str]) -> dict[str, bytes]:
+    """Every staged blob from one `git cat-file --batch` process.
+
+    One `git show` per path costs ~22ms of process spawn each and dominates the
+    hook; batching makes the fetch flat in file count.
+    """
+    if not rel_paths:
+        return {}
+    requests = "".join(f":{rel}\n" for rel in rel_paths).encode("utf-8")
+    return _framed_blobs(_batch_stream(root, requests), rel_paths)
+
+
+class _Started:
+    """A git process started now and read later.
+
+    communicate() writes the request and reads the answer in one call, so a
+    request stream larger than a pipe buffer cannot deadlock against the child's
+    own output. text=True mirrors _git exactly, universal newlines included: a
+    caller that switched to this must not start seeing CR at the end of every
+    diff line.
+    """
+
+    def __init__(self, root: Path, args: tuple[str, ...], *, text: bool, stdin: bool) -> None:
+        self._args, self._root, self._text = args, root, text
+        try:
+            self._proc = subprocess.Popen(
+                ["git", *args], cwd=root,
+                stdin=subprocess.PIPE if stdin else subprocess.DEVNULL,
+                stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                text=text, encoding="utf-8" if text else None)
+        except FileNotFoundError as exc:
+            raise GitError("git executable not found") from exc
+
+    def result(self, payload=None):
+        out, err = self._proc.communicate(payload)
+        if self._proc.returncode != 0:
+            text = err if self._text else err.decode("utf-8", "replace")
+            raise GitError(f"git {' '.join(self._args)} failed in {self._root}: {text.strip()}")
+        return out
+
+    def close(self) -> None:
+        """Shut down a process nothing ever read. A process already read to the
+        end has a return code, and closing that one is nothing at all."""
+        if self._proc.returncode is None:
+            self._proc.kill()
+            self._proc.communicate()
+
+
+class GitReads:
+    """Where the pre-commit gate's staged bytes come from: one git process each,
+    spawned at the moment the gate asks for it."""
+
+    def __init__(self, root: Path) -> None:
+        self.root = root
+
+    def staged_diff(self) -> str:
+        return staged_diff(self.root)
+
+    def staged_blobs(self, rel_paths: list[str]) -> dict[str, bytes]:
+        return staged_blobs(self.root, rel_paths)
+
+
+class _StartedReads:
+    """The same two answers, from processes that are already running.
+
+    The gate cannot use either one until lizard is imported, and that import
+    costs more than both spawns together, so the spawns belong underneath it.
+    """
+
+    def __init__(self, root: Path) -> None:
+        self._diff = _Started(root, ("diff", "--cached", "-U0", "--no-renames"),
+                              text=True, stdin=False)
+        self._batch = _Started(root, ("cat-file", "--batch"), text=False, stdin=True)
+
+    def staged_diff(self) -> str:
+        return self._diff.result()
+
+    def staged_blobs(self, rel_paths: list[str]) -> dict[str, bytes]:
+        if not rel_paths:
+            return {}
+        stream = self._batch.result("".join(f":{rel}\n" for rel in rel_paths).encode("utf-8"))
+        return _framed_blobs(stream, rel_paths)
+
+    def close(self) -> None:
+        self._diff.close()
+        self._batch.close()
+
+
+@contextmanager
+def staged_reads(root: Path):
+    """The gate's two git reads, started before the caller needs either.
+
+    Both processes are shut down on the way out, whichever of them the caller got
+    around to reading: a commit with nothing staged never asks for a blob, and a
+    machine with no lizard never asks for anything at all.
+    """
+    reads = _StartedReads(root)
+    try:
+        yield reads
+    finally:
+        reads.close()
+
+
+def file_log_patches(root: Path, rel_path: str) -> list[tuple[int, str]]:
+    """(commit timestamp, unified patch) per commit touching one file, oldest first.
+
+    -U0: the only reader is ratchet_report, which looks at +/- lines alone, so
+    context lines are pipe traffic that grows with the ratchet file.
+    No --follow: rename detection cost 0.6s of a 1.14s `ratchet report` on a
+    72k-commit history and found nothing. The cost is real, since --follow also
+    gives up the commit-graph path filtering the plain log gets (measured on a
+    30k-commit synthetic: 0.436s vs 0.257s, same events either way). The price
+    is that renaming the ratchet file restarts its burn-down history at the
+    rename.
+    """
+    out = _git(root, "log", "--reverse", "--format=%x01%at", "-p", "-U0", "--", rel_path)
+    patches = []
+    for block in out.split("\x01"):
+        if not block.strip():
+            continue
+        head, _, patch = block.partition("\n")
+        patches.append((int(head.strip()), patch))
+    return patches
+
+
+def churn_log_lines(root: Path, months: int) -> Iterator[str]:
+    """The churn window's log, streamed. On a big repo this is 21 MB of text and
+    the single most expensive call crapkit makes, so it is never held whole."""
+    return _git_lines(root, "log", f"--since={months} months ago",
+                      "--format=%x01%an%x02%at", "--name-only")
+
+
+def worktree_add(root: Path, path: Path) -> None:
+    """A detached checkout of HEAD at `path`: a second working tree that shares
+    the object store, so a worker can edit files without touching the real one."""
+    _git(root, "worktree", "add", "--detach", str(path))
+
+
+def worktree_remove(root: Path, path: Path) -> None:
+    """Teardown. --force because the worker's tree is dirty by construction, and
+    it never raises: a cleanup error must not mask the failure that caused it.
+    `prune` is the fallback that drops the admin entry a stuck directory leaves."""
+    try:
+        _git(root, "worktree", "remove", "--force", str(path))
+    except GitError:
+        shutil.rmtree(path, ignore_errors=True)
+        _prune_quietly(root)
+
+
+def _prune_quietly(root: Path) -> None:
+    try:
+        _git(root, "worktree", "prune")
+    except GitError:
+        pass
+
+
+def _git_dir(root: Path) -> Path | None:
+    """.git is a directory in a normal clone and a `gitdir:` pointer in a linked
+    worktree or a submodule. The pointer may be relative to the working tree."""
+    dot = root / ".git"
+    if dot.is_dir():
+        return dot
+    text = _file_text(dot)
+    if not text.startswith("gitdir:"):
+        return None
+    named = Path(text[len("gitdir:"):].strip())
+    return named if named.is_absolute() else (root / named)
+
+
+def _file_text(path: Path) -> str:
+    """A ref file's content, or "" when it is not there or not readable.
+
+    Unreadable is an answer here, not a failure: every caller's fallback is the
+    git process, which is what read the file correctly in the first place.
+    """
+    try:
+        return path.read_text(encoding="utf-8").strip()
+    except (OSError, UnicodeDecodeError):
+        return ""
+
+
+def _sha_or_none(text: str) -> str | None:
+    """Object names only: 40 hex for sha1 repos, 64 for sha256 ones."""
+    return text if _OBJECT_NAME.fullmatch(text) else None
+
+
+def _packed_sha(gitdir: Path, ref: str) -> str | None:
+    """The ref's line in packed-refs, where `git pack-refs` puts it once the
+    loose file is gone. `^`-prefixed lines are peeled tags and never a match."""
+    for line in _file_text(gitdir / "packed-refs").splitlines():
+        sha, _, name = line.partition(" ")
+        if name.strip() == ref:
+            return _sha_or_none(sha)
+    return None
+
+
+def _common_dir(gitdir: Path) -> Path:
+    """A linked worktree keeps HEAD in its own admin directory and shares
+    refs/heads with the repository it was made from."""
+    common = _file_text(gitdir / "commondir")
+    return (gitdir / common).resolve() if common else gitdir
+
+
+def _ref_sha(gitdir: Path, ref: str) -> str | None:
+    loose = _sha_or_none(_file_text(gitdir / ref))
+    if loose:
+        return loose
+    shared = _common_dir(gitdir)
+    return _sha_or_none(_file_text(shared / ref)) or _packed_sha(shared, ref)
+
+
+def head_from_refs(root: Path) -> str | None:
+    """HEAD read straight out of .git, or None meaning "ask git".
+
+    Every command opens by asking where HEAD is, and the answer is a 40-character
+    string in a file: on Windows the spawn that fetches it costs ~20ms. Anything
+    unexpected — a symref chain, a ref this does not find, a torn write — returns
+    None rather than a guess, and the caller pays for the process instead.
+    """
+    gitdir = _git_dir(root)
+    if gitdir is None:
+        return None
+    head = _file_text(gitdir / "HEAD")
+    if not head.startswith("ref: "):
+        return _sha_or_none(head)  # detached: HEAD holds the object name itself
+    return _ref_sha(gitdir, head[len("ref: "):].strip())
+
+
+def head_commit(root: Path) -> str:
+    fast = head_from_refs(root)
+    if fast:
+        return fast
+    out = _git(root, "rev-parse", "HEAD").strip()
+    if not out:
+        raise GitError(f"no HEAD commit in {root}")
+    return out
+
+
+class GitFacts:
+    """One command's answers to the three questions every lane asks.
+
+    HEAD, the dirty-file set and a diff against a stamp commit are the same for
+    every lane in a run, but each lane used to pay its own `git` spawn for all
+    three. Build one of these per command and pass it down.
+
+    Asking once also FIXES the answer at the moment the run started, which is
+    what the reuse decision wants: a lane command writes into the working tree,
+    so a later lane re-asking git would judge itself against another lane's
+    output. Errors are not memoized — GitError propagates on every call, so a
+    non-git sandbox keeps behaving like one.
+
+    Parallel lanes share one of these, so the lazy fills take a lock: the first
+    caller pays the spawn and the rest wait for its answer instead of racing to
+    ask git the same question again.
+    """
+
+    def __init__(self, root: Path) -> None:
+        self.root = root
+        self._lock = threading.Lock()
+        self._head: str | None = None
+        self._status: tuple[str, ...] | None = None
+        self._diffs: dict[str, tuple[str, ...]] = {}
+        self._ancestry: dict[tuple[str, str], bool] = {}
+
+    def head_commit(self) -> str:
+        with self._lock:
+            if self._head is None:
+                self._head = head_commit(self.root)
+            return self._head
+
+    def status_names(self) -> tuple[str, ...]:
+        with self._lock:
+            if self._status is None:
+                self._status = tuple(status_names(self.root))
+            return self._status
+
+    def diff_names_since(self, commit: str) -> tuple[str, ...]:
+        with self._lock:
+            if commit not in self._diffs:
+                self._diffs[commit] = tuple(diff_names_since(self.root, commit))
+            return self._diffs[commit]
+
+    def is_ancestor(self, commit: str, other: str = "HEAD") -> bool:
+        """Memoized per (commit, other) the way the diffs are: verify asks about
+        the same commit once per lane, once per open claim and once for the
+        baseline, and history does not move under a running command."""
+        with self._lock:
+            key = (commit, other)
+            if key not in self._ancestry:
+                self._ancestry[key] = is_ancestor(self.root, commit, other)
+            return self._ancestry[key]

crapkit/hook.py

@@ -0,0 +1,167 @@
+"""Pre-commit gate: min-CCN over the target on functions touched by the staged diff.
+
+Checks STAGED blobs, never the working tree, so unstaged noise cannot block a
+clean commit and a dirty checkout cannot sneak past one.
+
+The hook is a hot path measured in what a developer waits for at every `git
+commit`, so it holds three rules the batch commands do not:
+
+- One `git cat-file --batch` for all staged blobs, and each blob fetched once.
+  Per-file `git show` spawns cost ~22ms each and made the floor scale with the
+  commit size.
+- No repo-wide analysis cache. Loading and rewriting it cost a flat 0.45s on an
+  18 MB cache while the analysis it could save is milliseconds: a commit's worth
+  of blobs is cheaper to analyze outright than to look up.
+- A commit's worth of files is analyzed in this process, from the blobs already
+  in memory: no worker pool below the crossover, and no temp tree to read back.
+"""
+from __future__ import annotations
+
+import codecs
+import io
+import tempfile
+from pathlib import Path
+from typing import NamedTuple
+
+from .analyze import analyze_jobs, analyze_source
+from .config import Config
+from .diffparse import changed_ranges
+from .gitio import GitReads
+from .merge import FunctionRecord
+from .universe import _source_extensions, assign_files, exclude_matcher, excluded
+
+# A commit's worth of files, not an inventory's, and never more workers than a
+# commit can keep busy: each worker re-imports lizard, which is the whole cost of
+# a small pool. Measured here at 9 reps a point (serial vs pooled medians, ms):
+# 4 files 17/120, 8 files 52/158, 12 files 112/175, 16 files 178/191, 20 files
+# 197/184, 60 files 505/228. The arms only cross at 16, so that is the threshold;
+# below it the pool spends ~100ms of spawn to save single-digit milliseconds.
+_HOOK_POOL_THRESHOLD = 16
+_HOOK_MAX_WORKERS = 8
+
+
+class Violation(NamedTuple):
+    path: str
+    long_name: str
+    start: int
+    ccn: int
+
+
+class StagedGate(NamedTuple):
+    """The verdict on the staged blobs."""
+    violations: list[Violation]
+    unscoped: list[str] = []  # staged source files no scope claims: ungated, but never silently
+
+
+def _touches(record: FunctionRecord, ranges: list[tuple[int, int]]) -> bool:
+    return any(not (hi < record.start or lo > record.end) for lo, hi in ranges)
+
+
+def _materialized(tmp: Path, blobs: dict[str, bytes]) -> list[tuple[str, str]]:
+    """Write each staged blob under its own repo-relative path.
+
+    The repo path, not the basename: src/a/index.ts and src/b/index.ts are one
+    file at basename granularity, and analyzing one twice would gate the wrong
+    content.
+    """
+    jobs = []
+    for rel, blob in sorted(blobs.items()):
+        staged = tmp / rel
+        staged.parent.mkdir(parents=True, exist_ok=True)
+        staged.write_bytes(blob)
+        jobs.append((str(staged), rel))
+    return jobs
+
+
+def _text_of(blob: bytes) -> str:
+    """The blob as lizard's own auto_read would have read it back from a file.
+
+    Three things have to match or the records move: the UTF-8 BOM selects
+    utf-8-sig, everything else takes the same default encoding `io.open` takes,
+    and text mode translates line endings. A plain `blob.decode()` skips the
+    translation, so a CR-only file arrives as one line and lizard reports no
+    functions in it at all — the gate would then pass a file it never judged.
+    """
+    encoding = "utf-8-sig" if blob.startswith(codecs.BOM_UTF8) else None
+    return io.TextIOWrapper(io.BytesIO(blob), encoding=encoding, newline=None).read()
+
+
+def _decoded(blob: bytes) -> str:
+    """auto_read's last resort too: bytes no decoder accepts lose the bad ones
+    rather than failing the commit."""
+    try:
+        return _text_of(blob)
+    except UnicodeDecodeError:
+        return blob.decode("utf-8", "ignore")
+
+
+def staged_records(blobs: dict[str, bytes]) -> dict[str, list]:
+    """Records for the staged blobs, pooled once a commit touches enough files.
+
+    Below the pool threshold lizard is handed the blob text directly: the bytes
+    are already in memory from `git cat-file --batch`, and a temp tree only to
+    read them back costs a write and a read per file. The pooled arm still
+    materializes, because a worker process reads its own files.
+    """
+    if len(blobs) < _HOOK_POOL_THRESHOLD:
+        return {rel: analyze_source(rel, _decoded(blob)) for rel, blob in sorted(blobs.items())}
+    with tempfile.TemporaryDirectory() as tmp:
+        jobs = _materialized(Path(tmp), blobs)
+        return analyze_jobs(jobs, workers=min(len(jobs), _HOOK_MAX_WORKERS),
+                            pool_threshold=_HOOK_POOL_THRESHOLD, chunksize=1)
+
+
+def file_ceilings(cfg, in_scope, checked_files) -> dict[str, int]:
+    """The ccn ceiling each file is judged against: its scope's target, else the
+    repo's. `rescore --gate` decides on this same map, so a mid-session verdict
+    and the commit's cannot disagree."""
+    ceilings = cfg.scope_targets
+    scope_of = {f: scope for scope, files in in_scope.items() for f in files}
+    return {rel: ceilings.get(scope_of.get(rel, ""), cfg.target) for rel in checked_files}
+
+
+def _touched_over_ceiling(records_by_path, ranges_by_path, checked_files, cfg, in_scope) -> list[Violation]:
+    by_file = file_ceilings(cfg, in_scope, checked_files)
+    violations = []
+    for rel in checked_files:
+        ceiling = by_file[rel]
+        for rec in records_by_path[rel]:
+            if rec.ccn > ceiling and _touches(rec, ranges_by_path[rel]):
+                violations.append(Violation(rel, rec.long_name, rec.start, rec.ccn))
+    violations.sort(key=lambda v: (-v.ccn, v.path, v.start))
+    return violations
+
+
+def _gate_blind_to(path: str, checked: set[str], exts: tuple, match) -> bool:
+    """A staged file the gate cannot judge but a scope language claims by
+    extension. Files the config EXCLUDES (test trees, exclude globs) are
+    outside scopes on purpose and never a hole."""
+    return path not in checked and path.endswith(exts) and not excluded(path, match)
+
+
+def _unscoped_sources(staged: list[str], checked: set[str], cfg: Config) -> list[str]:
+    """The first new top-level directory a repo grows commits ungated; this is
+    how that hole stays visible instead of silent."""
+    exts = tuple(e for scope in cfg.scopes for e in _source_extensions(scope.languages))
+    match = exclude_matcher(cfg.exclude_globs)
+    return sorted(f for f in staged if _gate_blind_to(f, checked, exts, match))
+
+
+def gate_staged(root: Path, cfg: Config, reads=None) -> StagedGate:
+    """`reads` is where the staged bytes come from: git processes the caller
+    already started, or a spawn-on-demand pair when nobody did. The verdict is
+    the same either way."""
+    reads = reads or GitReads(root)
+    ranges_by_path = changed_ranges(reads.staged_diff())
+    if not ranges_by_path:
+        return StagedGate([])
+    in_scope = assign_files(sorted(ranges_by_path), cfg)
+    checked_files = sorted({f for files in in_scope.values() for f in files})
+    unscoped = _unscoped_sources(sorted(ranges_by_path), set(checked_files), cfg)
+    if not checked_files:
+        return StagedGate([], unscoped)
+    records_by_path = staged_records(reads.staged_blobs(checked_files))
+    return StagedGate(
+        _touched_over_ceiling(records_by_path, ranges_by_path, checked_files, cfg, in_scope),
+        unscoped
+    )