git2xml 0.1.0__py3-none-any.whl

git2xml/git_scanner.py

@@ -0,0 +1,708 @@
+"""GitScanner: the only place that talks to the git binary.
+
+Every git invocation goes through ``run_git`` (async, no shell, ``--`` before
+paths), so this module is the project's entire subprocess surface. Methods are
+stateless per call - they read configuration from ``self.config`` and take the
+data they need as arguments - and return plain data (ScanResult, ChangedFile,
+metadata maps, blobs), never XML. Concurrency is imposed by the caller in
+``core``; the scanner knows nothing about the orchestrator's budget.
+"""
+
+import asyncio
+import logging
+import subprocess
+from pathlib import Path
+from typing import Any, Dict, Iterator, List, Literal, Optional, Tuple, overload
+
+from .constants import LS_TREE_PATH_BUDGET
+from .models import (
+    ChangedFile,
+    FileStatus,
+    Git2xmlConfig,
+    GitCommandError,
+    GitNotInstalledError,
+    NameStatusEntry,
+    NotAGitRepositoryError,
+    PRCommit,
+    ScanResult,
+    StagingState,
+)
+
+logger = logging.getLogger(__name__)
+
+# Suppress console flash on Windows.
+_SUBPROCESS_FLAGS = getattr(subprocess, "CREATE_NO_WINDOW", 0)
+
+# Fixed prefix on every git invocation: no pager, no color, no path quoting,
+# so output is stable and machine-parseable.
+_GIT_PREFIX = ["git", "--no-pager", "-c", "color.ui=false", "-c", "core.quotepath=false"]
+
+# Chunk size for streaming reads of a subprocess pipe.
+_STREAM_CHUNK = 64 * 1024
+
+# Read this many bytes beyond max_diff_size before giving up on a diff. The
+# slack guarantees the returned (truncated) text still measures strictly over
+# max_diff_size once decoded - a cut trailing multi-byte sequence collapses to a
+# single U+FFFD, shrinking the re-encoded length by at most a few bytes - so the
+# engine's diff_exceeds_limit check reliably drops it. Tiny next to the diffs
+# this guards against, so it costs nothing in the common case.
+_DIFF_CAP_SLACK = 8
+
+
+async def _read_capped(stream: asyncio.StreamReader, ceiling: int) -> Tuple[bytes, bool]:
+    """Read ``stream`` until EOF or ``ceiling`` bytes, whichever comes first.
+
+    Returns ``(data, truncated)`` where ``truncated`` is True iff the ceiling was
+    hit before EOF - i.e. there was more to read. Bounds buffered memory to
+    ``ceiling + _STREAM_CHUNK``.
+    """
+    chunks: List[bytes] = []
+    total = 0
+    while total < ceiling:
+        chunk = await stream.read(_STREAM_CHUNK)
+        if not chunk:
+            return b"".join(chunks), False
+        chunks.append(chunk)
+        total += len(chunk)
+    return b"".join(chunks), True
+
+
+async def _drain(stream: asyncio.StreamReader) -> None:
+    """Read a pipe to EOF and discard the bytes. Run concurrently with the stdout read so a chatty git
+    can't deadlock by filling its stderr pipe while we're capped on stdout."""
+    while True:
+        chunk = await stream.read(_STREAM_CHUNK)
+        if not chunk:
+            return
+
+
+def _parse_name_status(raw: str) -> Dict[str, NameStatusEntry]:
+    """Parse NUL-delimited output from ``git diff --name-status -z``.
+
+    Token sequence per entry:
+    - normal (M/A/D/T/…): STATUS NUL PATH NUL
+    - rename/copy (R/C):   STATUS NUL OLD_PATH NUL NEW_PATH NUL
+    """
+    files: Dict[str, NameStatusEntry] = {}
+    tokens = [t for t in raw.split("\0") if t]
+    i = 0
+    while i < len(tokens):
+        status_code = tokens[i]
+        i += 1
+        if not status_code:
+            continue
+        if status_code[0] in ("R", "C"):
+            if i + 1 >= len(tokens):
+                break
+            old_path = tokens[i]
+            new_path = tokens[i + 1]
+            i += 2
+            files[new_path] = {
+                "status": FileStatus.RENAMED if status_code[0] == "R" else FileStatus.COPIED,
+                "old_path": old_path,
+            }
+        else:
+            if i >= len(tokens):
+                break
+            path = tokens[i]
+            i += 1
+            files[path] = {"status": FileStatus.from_code(status_code)}
+    return files
+
+
+def _normalize_git_path(path: str) -> str:
+    """Converts a path to a POSIX-style relative path suitable for git tree lookups."""
+    return path.replace("\\", "/")
+
+
+def _chunk_paths(paths: List[str], budget: int) -> Iterator[List[str]]:
+    """Split POSIX paths into batches whose rendered command-line cost fits ``budget``.
+
+    Counts 3 chars/path for quote wrapping plus the argument separator; the fixed
+    git prefix and exe path are covered by the reserve baked into the budget. A
+    single path longer than the budget is emitted alone rather than dropped --
+    still safe, since POSIX MAX_ARG_STRLEN (128 KiB) dwarfs any real path.
+    """
+    batch: List[str] = []
+    size = 0
+    for raw in paths:
+        p = _normalize_git_path(raw)
+        # UTF-16 units, matching LS_TREE_PATH_BUDGET's Windows-derived cap (astral
+        # chars = 2 units). See constants.py before changing the budget per-platform.
+        plen = len(p.encode("utf-16-le")) // 2 + 3
+        if batch and size + plen > budget:
+            yield batch
+            batch, size = [], 0
+        batch.append(p)
+        size += plen
+    if batch:
+        yield batch
+
+
+class GitScanner:
+    config: Git2xmlConfig
+    cwd: str
+
+    def __init__(self, config: Git2xmlConfig):
+        self.config = config
+        self.cwd = str(Path(config.repo).resolve())
+
+    @overload
+    async def run_git(
+        self, args: List[str], binary: Literal[False] = False
+    ) -> "subprocess.CompletedProcess[str]": ...
+    @overload
+    async def run_git(
+        self, args: List[str], binary: Literal[True]
+    ) -> "subprocess.CompletedProcess[bytes]": ...
+
+    async def run_git(
+        self, args: List[str], binary: bool = False
+    ) -> "subprocess.CompletedProcess[Any]":
+        """Run a git command asynchronously using instance-scoped configuration.
+
+        Prepends ``--no-pager`` and disables color/quotepath so output is stable
+        and machine-parseable. Decodes stdout/stderr as UTF-8 unless ``binary`` is
+        set, in which case raw bytes are returned (used for blob fetches).
+
+        Typed via ``@overload`` so the return is ``CompletedProcess[bytes]`` when
+        ``binary=True`` and ``CompletedProcess[str]`` otherwise - callers get the
+        right ``stdout``/``stderr`` type without a cast.
+
+        Raises:
+            GitNotInstalledError: if the git executable is not on PATH.
+            GitCommandError: if the command exceeds the configured git timeout.
+        """
+
+        base_cmd = _GIT_PREFIX + args
+        process = await self._spawn(base_cmd)
+
+        # communicate() manages stream consumption in the background. If cancelled or
+        # timed out, it is safe to wait() after kill() without manual pipe draining.
+        try:
+            stdout_bytes, stderr_bytes = await asyncio.wait_for(
+                process.communicate(), timeout=self.config.git_timeout
+            )
+        except asyncio.TimeoutError:
+            process.kill()
+            await (
+                process.wait()
+            )  # reap the killed child; avoids zombie + "event loop closed" warnings
+            raise GitCommandError(
+                command=" ".join(base_cmd),
+                returncode=-1,
+                stderr=f"Command timed out after {self.config.git_timeout}s.",
+            ) from None
+        except asyncio.CancelledError:
+            # Task aborted mid-await (agent/host cancelled the coroutine). communicate()
+            # being cancelled does not kill the child, so kill+reap to avoid an orphan,
+            # then let the cancellation propagate.
+            if process.returncode is None:
+                process.kill()
+                await process.wait()
+            raise
+
+        # communicate() guarantees the process has terminated; satisfy type checkers.
+        return_code = process.returncode if process.returncode is not None else -1
+
+        stdout = stdout_bytes if binary else stdout_bytes.decode("utf-8", errors="replace")
+        stderr = stderr_bytes if binary else stderr_bytes.decode("utf-8", errors="replace")
+
+        return subprocess.CompletedProcess(
+            args=base_cmd, returncode=return_code, stdout=stdout, stderr=stderr
+        )
+
+    async def _spawn(self, cmd: List[str]) -> "asyncio.subprocess.Process":
+        """Spawn a git process with the standard pipes/flags (no shell, no stdin)."""
+        try:
+            return await asyncio.create_subprocess_exec(
+                *cmd,
+                cwd=self.cwd,
+                stdin=asyncio.subprocess.DEVNULL,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                creationflags=_SUBPROCESS_FLAGS,
+            )
+        except FileNotFoundError:
+            raise GitNotInstalledError() from None
+
+    async def _run_git_capped(self, args: List[str]) -> Tuple[int, str, bool]:
+        """Run a diff-producing git command, bounding buffered stdout in memory.
+
+        Unlike content (whose size git reports before we load it), a diff has no
+        size until git computes it, and ``communicate()`` would buffer the whole
+        thing - a modified-but-tracked multi-megabyte file produces a diff just as
+        large, and these fetches run ``diff_semaphore_limit``-wide, so the naive
+        path can balloon to (limit x diff size) of RAM. Here stdout is streamed and
+        abandoned once it passes ``max_diff_size`` (there's no point buffering bytes
+        the engine will drop), while stderr is drained concurrently to avoid a
+        pipe-buffer deadlock.
+
+        Returns ``(returncode, stdout_text, truncated)``. When ``truncated`` is
+        True the child was killed mid-diff and ``returncode`` is meaningless (the
+        text is already over-limit and the engine drops it). ``max_diff_size <= 0``
+        means uncapped (honors ``--max-diff-size 0``) and defers to ``run_git``.
+        """
+        max_diff_size = self.config.max_diff_size
+        if max_diff_size <= 0:
+            res = await self.run_git(args)
+            return res.returncode, res.stdout, False
+
+        process = await self._spawn(_GIT_PREFIX + args)
+        assert process.stdout is not None
+        assert process.stderr is not None
+        ceiling = max_diff_size + _DIFF_CAP_SLACK
+        stderr_task = asyncio.create_task(_drain(process.stderr))
+
+        try:
+            try:
+                stdout_bytes, truncated = await asyncio.wait_for(
+                    _read_capped(process.stdout, ceiling),
+                    timeout=self.config.git_timeout,
+                )
+            except asyncio.TimeoutError:
+                # Child is still running and blocked; kill so the finally can reap it.
+                process.kill()
+                raise GitCommandError(
+                    command=" ".join(_GIT_PREFIX + args),
+                    returncode=-1,
+                    stderr=f"Command timed out after {self.config.git_timeout}s.",
+                ) from None
+            if truncated:
+                # Cap reached mid-diff: kill to stop further output and to EOF the
+                # child's stderr so the concurrent _drain can finish.
+                process.kill()
+        except asyncio.CancelledError:
+            # Coroutine cancelled mid-read; the child outlives the await unless killed.
+            process.kill()
+            raise
+        except Exception:
+            # Unexpected stream/transport error: don't leave the child running.
+            process.kill()
+            raise
+        finally:
+            # On every path the child must be reaped, and on Windows' Proactor loop
+            # process.wait() hangs while a pipe holds unread bytes - so drain both
+            # pipes to EOF first. A clean read leaves the child exiting on its own;
+            # it is reaped here without a kill.
+            await asyncio.gather(_drain(process.stdout), stderr_task, return_exceptions=True)
+            await process.wait()
+
+        return_code = process.returncode if process.returncode is not None else -1
+        return return_code, stdout_bytes.decode("utf-8", errors="replace"), truncated
+
+    def check_git_result(self, result: subprocess.CompletedProcess, command: str) -> None:
+        """Raise GitCommandError if ``result`` is a non-zero exit, else do nothing.
+
+        ``command`` is a human-readable label for the failing call, used in the
+        error message. A convenience guard for callers that treat any non-zero
+        git exit as fatal (unlike the lookup helpers, which interpret specific
+        codes themselves).
+        """
+
+        if result.returncode != 0:
+            raise GitCommandError(
+                command=command, returncode=result.returncode, stderr=result.stderr
+            )
+
+    async def validate_repository(self) -> None:
+        """Verify ``self.cwd`` exists and is inside a git work tree.
+
+        Raises NotAGitRepositoryError if the path is not a directory, or if
+        ``git rev-parse --is-inside-work-tree`` does not confirm a work tree
+        (covers a non-repo directory and a bare repository alike).
+        """
+
+        if not Path(self.cwd).is_dir():
+            raise NotAGitRepositoryError(self.cwd)
+        result = await self.run_git(["rev-parse", "--is-inside-work-tree"])
+        if result.returncode != 0 or result.stdout.strip() != "true":
+            raise NotAGitRepositoryError(self.cwd)
+
+    async def resolve_base_ref(self) -> str:
+        """Resolve the configured base ref, trying it as-is before falling back to refs/heads/.
+
+        Reads ``self.config.base`` as the user-supplied input and returns the form
+        that resolved successfully. Supports remote refs (origin/main), tags,
+        commit SHAs, and bare branch names.
+        """
+        # A leading '-' would be parsed by git as an option, not a ref (option
+        # injection). No legitimate ref a user passes starts with '-': branch
+        # names forbid it, and refs/tags/SHAs/remote refs never lead with it.
+        # A dash mid-string (feature/-x, my-branch) is fine - only the first
+        # character is rejected. A pathologically dash-named branch is still
+        # reachable via its fully-qualified refs/heads/-name form.
+        if self.config.base.startswith("-"):
+            raise GitCommandError(
+                command=f"rev-parse --verify {self.config.base}",
+                returncode=-1,
+                stderr=(
+                    f"Invalid base ref '{self.config.base}': cannot start with '-'. "
+                    "If you have a branch named this way, pass its full ref "
+                    "(e.g. refs/heads/...)."
+                ),
+            )
+
+        result = await self.run_git(["rev-parse", "--verify", self.config.base])
+        if result.returncode == 0:
+            return self.config.base
+        if not self.config.base.startswith("refs/"):
+            qualified = f"refs/heads/{self.config.base}"
+            result2 = await self.run_git(["rev-parse", "--verify", qualified])
+            if result2.returncode == 0:
+                return qualified
+        raise GitCommandError(
+            command=f"rev-parse --verify {self.config.base}",
+            returncode=result.returncode,
+            stderr=f"Base branch '{self.config.base}' not found in repository.",
+        )
+
+    async def scan_commit_changes(self) -> ScanResult:
+        """Scan the working tree for changes against HEAD, returning a ScanResult.
+
+        Runs git queries concurrently: staged changes
+        (``diff --name-status --staged``) and, unless ``self.config.staged`` is set,
+        also unstaged changes (``diff --name-status``) and untracked files
+        (``ls-files --others --exclude-standard``). Each changed file becomes a
+        ChangedFile with a derived StagingState - a path present in both the staged
+        and unstaged sets is STAGED_AND_MODIFIED, staged-only is STAGED,
+        unstaged-only is UNSTAGED, and untracked files are UNTRACKED.
+
+        Under ``self.config.staged`` the unstaged and untracked scans are skipped
+        (their results would be discarded by the caller's ``--staged`` filter anyway),
+        so every staged file is reported as plain STAGED. The STAGED_AND_MODIFIED
+        label is not derivable without the unstaged scan, but it is unused in
+        ``--staged`` mode - it does not affect the filter, the XML output, or
+        ``has_staged``.
+
+        ``has_staged`` reports whether anything was staged, so the caller can give a
+        precise message when ``--staged`` finds nothing.
+        """
+        staged_task = self.run_git(["diff", "--name-status", "-z", "--staged"])
+
+        if self.config.staged:
+            staged_res = await staged_task
+            self.check_git_result(staged_res, "diff staged")
+            staged = _parse_name_status(staged_res.stdout)
+            all_files = [
+                ChangedFile(path, info["status"], StagingState.STAGED, info.get("old_path"))
+                for path, info in staged.items()
+            ]
+            return ScanResult(files=all_files, has_staged=len(staged) > 0)
+
+        unstaged_task = self.run_git(["diff", "--name-status", "-z"])
+        untracked_task = self.run_git(["ls-files", "-z", "--others", "--exclude-standard"])
+
+        staged_res, unstaged_res, untracked_res = await asyncio.gather(
+            staged_task, unstaged_task, untracked_task
+        )
+
+        self.check_git_result(staged_res, "diff staged")
+        self.check_git_result(unstaged_res, "diff unstaged")
+        self.check_git_result(untracked_res, "ls-files untracked")
+
+        staged = _parse_name_status(staged_res.stdout)
+        unstaged = _parse_name_status(unstaged_res.stdout)
+        untracked = [p for p in untracked_res.stdout.split("\0") if p]
+
+        all_files = []
+        for path, info in staged.items():
+            staging = StagingState.STAGED_AND_MODIFIED if path in unstaged else StagingState.STAGED
+            all_files.append(ChangedFile(path, info["status"], staging, info.get("old_path")))
+        for path, info in unstaged.items():
+            if path not in staged:
+                all_files.append(ChangedFile(path, info["status"], StagingState.UNSTAGED))
+        for path in untracked:
+            all_files.append(ChangedFile(path, FileStatus.UNTRACKED, StagingState.UNTRACKED))
+
+        return ScanResult(files=all_files, has_staged=len(staged) > 0)
+
+    async def scan_pr_changes(self, base_branch: str) -> ScanResult:
+        """Scan the branch's changes against ``base_branch``, returning a ScanResult.
+
+        Uses ``diff --name-status <base>...HEAD`` (the merge-base diff), so the
+        result reflects what the branch added relative to where it forked from, not
+        the raw tip-to-tip diff. These are committed changes, so per-file
+        StagingState and ``has_staged`` are benign placeholders, never read in PR
+        mode (see the inline note).
+        """
+
+        diff_result = await self.run_git(["diff", "--name-status", "-z", f"{base_branch}...HEAD"])
+        self.check_git_result(diff_result, f"diff {base_branch}...HEAD")
+
+        files_dict = _parse_name_status(diff_result.stdout)
+        # Staging state is meaningless in PR mode (these are committed branch changes,
+        # not working-tree/index states). Both the per-file StagingState.STAGED and
+        # has_staged=True below are benign placeholders - the commit-mode code paths
+        # that read these fields (staging filter, --staged guard) never run in PR
+        # mode - not real claims about staging.
+        all_files = [
+            ChangedFile(path, info["status"], StagingState.STAGED, info.get("old_path"))
+            for path, info in files_dict.items()
+        ]
+        return ScanResult(files=all_files, has_staged=True)
+
+    async def get_single_diff(
+        self,
+        file: ChangedFile,
+        base_ref: str,
+        untracked: bool = False,
+    ) -> Tuple[str, str]:
+        """Fetch the diff for one changed file and return ``(path, diff_text)``.
+
+        Args:
+            file: The file whose diff is to be fetched.
+            base_ref: Base ref for the diff (e.g. ``"HEAD"`` or ``"main...HEAD"``).
+            untracked: If True, synthesize an add-diff for a not-yet-tracked file
+                via ``git diff --no-index -- /dev/null <path>``. ``--no-index``
+                exits 1 when the files differ (the normal case), so rc 0 and 1
+                are both accepted.
+
+        The staged/unstaged distinction is read from ``self.config.staged``.
+
+        Git commands are called with ``--no-ext-diff`` and ``--no-textconv`` to
+        neutralize repo-configured external diff and textconv drivers on
+        untrusted repos (``--no-index`` honors textconv too, so the untracked
+        path needs the guard as well).
+        """
+        if untracked:
+            # Untracked files are invisible to plain `git diff`; synthesize an
+            # add-diff against an empty input. "/dev/null" gives git's canonical
+            # creation header identically across platforms (see prior note).
+            diff_args = [
+                "diff",
+                "--no-ext-diff",
+                "--no-textconv",
+                "--no-index",
+                "--",
+                "/dev/null",
+                _normalize_git_path(file.path),
+            ]
+            rc, out, truncated = await self._run_git_capped(diff_args)
+            if truncated:
+                return file.path, out  # over-limit; the engine drops it
+            if rc not in (0, 1):
+                logger.debug("no-index diff for %s exited %d", file.path, rc)
+                return file.path, ""
+            return file.path, out.strip()
+
+        paths = [file.path] if not file.old_path else [file.path, file.old_path]
+        diff_args = ["diff", "--no-ext-diff", "--no-textconv", "-M"]
+        if self.config.staged:
+            diff_args.append("--cached")
+        diff_args += [base_ref, "--"] + paths
+        rc, out, truncated = await self._run_git_capped(diff_args)
+        if truncated:
+            return file.path, out  # over-limit; the engine drops it
+        if rc != 0:
+            logger.debug("diff for %s exited %d", file.path, rc)
+            return file.path, ""
+        return file.path, out.strip()
+
+    async def get_current_branch(self) -> str:
+        """Gets the name of the current active branch."""
+        result = await self.run_git(["rev-parse", "--abbrev-ref", "HEAD"])
+        return result.stdout.strip() if result.returncode == 0 else "HEAD"
+
+    async def get_pr_commits(self, base_branch: str) -> List[PRCommit]:
+        """Fetches structured commit history for a PR.
+
+        Records are NUL-separated via ``git log -z`` (NUL cannot appear in commit
+        content, making record splitting unambiguous). Fields within a record are
+        separated by %x1e (ASCII Record Separator). A literal RS byte in a field
+        (author/subject) would misalign that one record - accepted as negligible,
+        since RS does not occur in organic commit metadata.
+        """
+        # %h short hash, %an author, %aI ISO-8601 date, %s subject, %b body
+        format_str = "%h%x1e%an%x1e%aI%x1e%s%x1e%b"
+        args = ["log", "-z", f"{base_branch}..HEAD", f"--format={format_str}"]
+
+        result = await self.run_git(args)
+        commits: List[PRCommit] = []
+
+        if result.returncode == 0 and result.stdout:
+            for raw_commit in result.stdout.split("\x00"):
+                if not raw_commit.strip():
+                    continue
+                parts = raw_commit.split("\x1e", 4)
+                if len(parts) == 5:
+                    commits.append(
+                        {
+                            "hash": parts[0].strip(),
+                            "author": parts[1].strip(),
+                            "date": parts[2].strip(),
+                            "subject": parts[3].strip(),
+                            "body": parts[4].strip(),
+                        }
+                    )
+
+        return commits
+
+    async def has_uncommitted_changes(self) -> bool:
+        """Checks if the working directory is dirty."""
+        result = await self.run_git(["status", "--porcelain"])
+        return bool(result.stdout.strip())
+
+    async def get_blob_size_at_index(self, path: str) -> int:
+        """Return the byte size of a staged blob in the index, or -1 if unavailable.
+
+        Reads the index entry via ``git cat-file -s :<path>``. Lets the caller
+        enforce the size limit *before* fetching the blob into memory, so an
+        oversized staged file is never fully buffered. Returns -1 if the path is not
+        in the index or the size can't be parsed.
+        """
+        posix_path = _normalize_git_path(path)
+        result = await self.run_git(["cat-file", "-s", f":{posix_path}"])
+        if result.returncode != 0:
+            return -1
+        try:
+            return int(result.stdout.strip())
+        except ValueError:
+            return -1
+
+    async def _ls_tree_meta(
+        self, ref: str, paths: Optional[List[str]] = None
+    ) -> Dict[str, Tuple[int, bool]]:
+        """Run one ``ls-tree -r -l -z`` (optionally scoped to ``paths``) and parse it.
+
+        ``paths`` are assumed already POSIX-normalized and small enough for one
+        command line (chunking is the caller's job). The ``-l`` record format is::
+
+            <mode> SP <type> SP <object> SP <size> TAB <path>
+
+        so we partition once on TAB to isolate the path (which may contain spaces),
+        then whitespace-split the metadata half. Size is -1 for entries git reports
+        without one (the '-' placeholder for non-blobs). Empty map on non-zero exit.
+        """
+        args = ["ls-tree", "-r", "-l", "-z", ref]
+        if paths:
+            args += ["--", *paths]
+
+        result = await self.run_git(args)
+        if result.returncode != 0:
+            logger.debug(
+                "ls-tree for %s exited %d: %s", ref, result.returncode, result.stderr.strip()
+            )
+            return {}
+
+        meta: Dict[str, Tuple[int, bool]] = {}
+        for record in result.stdout.split("\0"):
+            if not record:
+                continue
+            head, tab, path = record.partition("\t")
+            if not tab:
+                continue
+            fields = head.split()
+            if len(fields) < 4:
+                continue
+            mode, size_str = fields[0], fields[3]
+            try:
+                size = int(size_str)
+            except ValueError:
+                size = -1  # '-' placeholder for non-blob entries
+            meta[path] = (size, mode == "120000")
+        return meta
+
+    async def get_tree_metadata(
+        self, ref: str, paths: Optional[List[str]] = None
+    ) -> Dict[str, Tuple[int, bool]]:
+        """Return ``{path: (size, is_symlink)}`` for blobs in ``ref``'s tree.
+
+        With ``paths``, the listing is always scoped to them, chunked only so the
+        argument list never exceeds the platform command-line limit (see
+        LS_TREE_PATH_BUDGET). Batches run concurrently; because they partition the
+        paths into disjoint sets, merging their maps is order-independent. There is
+        no full-tree performance fallback: scoping fetches P entries, full-tree
+        fetches every entry (N >= P) to save only spawns -- a bad trade in exactly
+        the large repos where scoping matters most. ``paths=None`` lists the whole
+        tree, for callers that explicitly want it.
+
+        Callers only ever look up changed paths and never iterate the map, so a
+        scoped map behaves identically to the full tree. Empty map if ``ref`` can't
+        be listed; callers treat a missing path as size -1.
+        """
+        if not paths:
+            return await self._ls_tree_meta(ref)
+
+        sem = asyncio.Semaphore(self.config.diff_semaphore_limit)
+
+        async def _scoped(batch: List[str]) -> Dict[str, Tuple[int, bool]]:
+            async with sem:
+                return await self._ls_tree_meta(ref, batch)
+
+        coros = [_scoped(batch) for batch in _chunk_paths(paths, LS_TREE_PATH_BUDGET)]
+        meta: Dict[str, Tuple[int, bool]] = {}
+        for partial in await asyncio.gather(*coros):  # concurrent; disjoint, so order is moot
+            meta.update(partial)
+        return meta
+
+    async def get_blob_at_head(self, path: str) -> Optional[bytes]:
+        """Fetches the raw bytes of a file at HEAD. Returns None if not found, b'' if empty."""
+        posix_path = _normalize_git_path(path)
+        result = await self.run_git(["show", f"HEAD:{posix_path}"], binary=True)
+        return result.stdout if result.returncode == 0 else None
+
+    async def get_blob_at_index(self, path: str) -> Optional[bytes]:
+        """Fetches the raw bytes of a file from the Git index. Returns None if not found, b'' if empty."""
+        posix_path = _normalize_git_path(path)
+        result = await self.run_git(["show", f":{posix_path}"], binary=True)
+        return result.stdout if result.returncode == 0 else None
+
+    async def is_symlink_at_index(self, path: str) -> bool:
+        """Returns True iff the path is stored as a symlink (mode 120000) in the Git index."""
+        posix_path = _normalize_git_path(path)
+        result = await self.run_git(["ls-files", "-s", "--", posix_path])
+        if result.returncode != 0 or not result.stdout.strip():
+            return False
+        try:
+            return result.stdout.split()[0] == "120000"
+        except IndexError:
+            return False
+
+    async def get_index_metadata(
+        self, paths: Optional[List[str]] = None
+    ) -> Dict[str, Tuple[int, bool]]:
+        """Return ``{path: (size, is_symlink)}`` for blobs in the git index.
+
+        The index analogue of ``get_tree_metadata``: ``git write-tree`` writes the
+        current index to a tree object (read-only w.r.t. index/working tree/HEAD --
+        it only adds loose objects, reclaimed later by ``git gc``), which is then
+        listed via ``get_tree_metadata``, inheriting its scoping/chunking. Replaces
+        the per-file ``cat-file -s`` + ``ls-files -s`` probe that --staged rendering
+        would otherwise issue per file.
+
+        Empty map if the index can't be written as a tree (e.g. an unmerged index);
+        callers treat a missing path as size -1 and fall back to per-file probes.
+        """
+        result = await self.run_git(["write-tree"])
+        if result.returncode != 0:
+            logger.debug("write-tree failed (%d): %s", result.returncode, result.stderr.strip())
+            return {}
+        tree_sha = result.stdout.strip()
+        if not tree_sha:
+            return {}
+        return await self.get_tree_metadata(tree_sha, paths)
+
+    async def new_file_size(self, f: ChangedFile, tree_meta: Dict[str, Tuple[int, bool]]) -> int:
+        """Return the byte size of a new file from the same source the render path uses.
+
+        Reads size from the working tree (stat), the git index (cat-file on
+        ``:<path>``), or - in PR mode - the batched HEAD tree map, mirroring
+        exactly what ``_render_file_xml`` does. This keeps the diff-side guard
+        and the content-side guard in agreement so a large new file is never
+        fully read as a diff under --no-content when it would be omitted in
+        normal mode.
+        """
+        mode = self.config.command
+        staged_only = self.config.staged
+        if f.status == FileStatus.UNTRACKED or (mode == "commit" and not staged_only):
+            try:
+                return (Path(self.cwd) / f.path).stat().st_size
+            except OSError:
+                return -1
+        if mode == "pr":
+            return tree_meta.get(f.path, (-1, False))[0]
+        size = tree_meta.get(f.path, (-1, False))[0]  # commit + --staged
+        if size < 0:
+            size = await self.get_blob_size_at_index(f.path)
+        return size