esys-gitlog 0.1.0__py3-none-any.whl

esys_gitlog/git_adapter.py

@@ -0,0 +1,370 @@
+"""Git process adapter: argument vector, no shell."""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Iterator, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import BinaryIO
+
+
+class GitError(Exception):
+    """Operational Git failure. Not an empty history and not a QA diagnostic."""
+
+    def __init__(self, message: str, *, stderr: str = "") -> None:
+        super().__init__(message)
+        self.stderr = stderr
+
+
+# Fixed framing for parse_git_log_output / iter_parse_git_log_stream.
+PRETTY_FORMAT = "--pretty=format:%H%x00%an%x00%ae%x00%aI%x00%B%x00"
+
+# Options that replace or break null-framed pretty output (or flood with diffs).
+# These are stripped with a warning; elog keeps its own pretty format.
+_IGNORED_GIT_LOG_OPTIONS = frozenset(
+    {
+        "--oneline",
+        "--graph",
+        "--patch",
+        "-p",
+        "-u",
+        "--name-only",
+        "--name-status",
+        "--stat",
+        "--numstat",
+        "--shortstat",
+        "--dirstat",
+        "--summary",
+        "--raw",
+        "--compact-summary",
+    }
+)
+
+
+def _is_ignored_git_log_option(arg: str) -> bool:
+    if arg in _IGNORED_GIT_LOG_OPTIONS:
+        return True
+    if arg.startswith("--pretty") or arg.startswith("--format"):
+        return True
+    if arg.startswith("-") and not arg.startswith("--") and "p" in arg[1:]:
+        letters = arg[1:]
+        if letters.isdigit() or letters.startswith("n"):
+            return False
+        return "p" in letters
+    return False
+
+
+def filter_git_log_args(args: Sequence[str]) -> tuple[list[str], list[str]]:
+    """Split passthrough args into forwarded tokens and ignore-warnings.
+
+    Pretty/diff format options are dropped (elog owns framing). Other ``git log``
+    filters and revisions are kept. Each ignored option yields one warning line.
+    """
+    forwarded: list[str] = []
+    warnings: list[str] = []
+    for arg in args:
+        if arg == "--":
+            forwarded.append(arg)
+            continue
+        if _is_ignored_git_log_option(arg):
+            warnings.append(
+                f"warning: ignoring {arg} "
+                "(git-elog owns pretty/diff format; not forwarded to git log)"
+            )
+            continue
+        forwarded.append(arg)
+    return forwarded, warnings
+
+
+def validate_git_log_args(args: Sequence[str]) -> list[str]:
+    """Return forwarded args (ignored pretty/diff options stripped).
+
+    Prefer :func:`filter_git_log_args` when callers need the warning texts.
+    """
+    forwarded, _warnings = filter_git_log_args(args)
+    return forwarded
+
+
+def build_git_log_argv(
+    git_executable: str,
+    git_log_args: Sequence[str] | None = None,
+) -> tuple[list[str], list[str]]:
+    """Build ``git log`` argv with elog pretty format first, then user args.
+
+    Returns ``(argv, warnings)`` where warnings describe ignored options.
+    """
+    extra, warnings = filter_git_log_args(git_log_args or ())
+    return [git_executable, "log", PRETTY_FORMAT, *extra], warnings
+
+
+@dataclass(frozen=True, slots=True)
+class RawCommit:
+    """One commit as returned by Git, before semantic analysis."""
+
+    id: str
+    subject: str
+    body: str
+    message: str = ""
+    author_name: str = ""
+    author_email: str = ""
+    authored_date: str = ""
+
+
+def split_commit_message(raw: str) -> tuple[str, str]:
+    """Split ``%B`` into subject and body."""
+    if not raw:
+        return "", ""
+    text = raw[:-1] if raw.endswith("\n") else raw
+    lines = text.splitlines()
+    subject = lines[0] if lines else ""
+    if len(lines) <= 1:
+        return subject, ""
+    rest = lines[1:]
+    if rest and rest[0] == "":
+        rest = rest[1:]
+    return subject, "\n".join(rest)
+
+
+def _raw_from_width2(commit_id: str, message: str) -> RawCommit | None:
+    commit_id = commit_id.strip()
+    if not commit_id:
+        return None
+    subject, body = split_commit_message(message)
+    return RawCommit(
+        id=commit_id,
+        subject=subject,
+        body=body,
+        message=message[:-1] if message.endswith("\n") else message,
+    )
+
+
+def _raw_from_width5(
+    commit_id: str,
+    author_name: str,
+    author_email: str,
+    authored_date: str,
+    message: str,
+) -> RawCommit | None:
+    commit_id = commit_id.strip()
+    if not commit_id:
+        return None
+    subject, body = split_commit_message(message)
+    return RawCommit(
+        id=commit_id,
+        subject=subject,
+        body=body,
+        message=message[:-1] if message.endswith("\n") else message,
+        author_name=author_name,
+        author_email=author_email,
+        authored_date=authored_date,
+    )
+
+
+def parse_git_log_output(data: bytes | str) -> list[RawCommit]:
+    """Parse null-framed ``%H %an %ae %aI %B`` records from ``git log``."""
+    if isinstance(data, bytes):
+        text = data.decode("utf-8", errors="surrogateescape")
+    else:
+        text = data
+    if not text:
+        return []
+    parts = text.split("\0")
+    while parts and parts[-1] == "":
+        parts.pop()
+    # New framing: id, author, email, date, message (5 fields)
+    if len(parts) % 5 == 0:
+        width = 5
+    elif len(parts) % 2 == 0:
+        # Backward-compatible %H%x00%B%x00 framing used by older tests
+        width = 2
+    else:
+        raise GitError("git log framing is incomplete")
+
+    commits: list[RawCommit] = []
+    for index in range(0, len(parts), width):
+        if width == 2:
+            raw = _raw_from_width2(parts[index], parts[index + 1])
+        else:
+            raw = _raw_from_width5(
+                parts[index],
+                parts[index + 1],
+                parts[index + 2],
+                parts[index + 3],
+                parts[index + 4],
+            )
+        if raw is not None:
+            commits.append(raw)
+    return commits
+
+
+def iter_parse_git_log_stream(
+    stream: BinaryIO,
+    *,
+    chunk_size: int = 65536,
+) -> Iterator[RawCommit]:
+    """Yield commits as null-framed records arrive on ``stream`` (5-field framing)."""
+    pending = ""
+    fields: list[str] = []
+    while True:
+        chunk = stream.read(chunk_size)
+        if not chunk:
+            break
+        pending += chunk.decode("utf-8", errors="surrogateescape")
+        while "\0" in pending:
+            field, pending = pending.split("\0", 1)
+            fields.append(field)
+            if len(fields) < 5:
+                continue
+            raw = _raw_from_width5(
+                fields[0],
+                fields[1],
+                fields[2],
+                fields[3],
+                fields[4],
+            )
+            fields = []
+            if raw is not None:
+                yield raw
+    if fields or pending.strip("\0"):
+        raise GitError("git log framing is incomplete")
+
+
+def resolve_git_executable() -> str:
+    """Return a usable ``git`` binary.
+
+    Prefer ``PATH``, then common install locations. VS Code's Extension Host on
+    Windows sometimes runs with a PATH that omits Git even when it is installed.
+    """
+    import os
+    import shutil
+
+    found = shutil.which("git")
+    if found:
+        return found
+    candidates: list[str]
+    if os.name == "nt":  # pragma: no cover
+        pf = os.environ.get("ProgramFiles", r"C:\Program Files")
+        pf86 = os.environ.get("ProgramFiles(x86)", r"C:\Program Files (x86)")
+        local = os.environ.get("LocalAppData", "")
+        candidates = [
+            str(Path(pf) / "Git" / "cmd" / "git.exe"),
+            str(Path(pf) / "Git" / "bin" / "git.exe"),
+            str(Path(pf86) / "Git" / "cmd" / "git.exe"),
+            str(Path(pf86) / "Git" / "bin" / "git.exe"),
+        ]
+        if local:
+            candidates.append(str(Path(local) / "Programs" / "Git" / "cmd" / "git.exe"))
+    else:
+        candidates = ["/usr/bin/git", "/usr/local/bin/git", "/opt/homebrew/bin/git"]
+    for candidate in candidates:
+        if Path(candidate).is_file():
+            return candidate
+    raise GitError("git executable not found on PATH")
+
+
+def _run_git(args: list[str], *, cwd: Path) -> subprocess.CompletedProcess[bytes]:
+    try:
+        return subprocess.run(
+            args,
+            cwd=cwd,
+            capture_output=True,
+            check=False,
+        )
+    except FileNotFoundError as exc:
+        raise GitError("git executable not found on PATH") from exc
+    except NotADirectoryError as exc:
+        raise GitError(f"not a directory: {cwd}") from exc
+
+
+def _ensure_git_repo(root: Path, *, git_executable: str) -> bool:
+    """Return True when HEAD exists; False when the repo has no commits.
+
+    Raises ``GitError`` when ``root`` is not a Git work tree.
+    """
+    if not root.is_dir():
+        raise GitError(f"not a directory: {root}")
+    probe = _run_git([git_executable, "rev-parse", "--git-dir"], cwd=root)
+    if probe.returncode != 0:
+        detail = probe.stderr.decode("utf-8", errors="replace").strip()
+        raise GitError(
+            detail or "not a git repository",
+            stderr=detail,
+        )
+    head = _run_git([git_executable, "rev-parse", "--verify", "HEAD"], cwd=root)
+    return head.returncode == 0
+
+
+def list_commits(
+    cwd: str | Path = ".",
+    *,
+    git_executable: str | None = None,
+    git_log_args: Sequence[str] | None = None,
+) -> list[RawCommit]:
+    """Return commits in ``git log`` order from the repository at ``cwd``.
+
+    ``git_log_args`` are forwarded to ``git log`` after the fixed pretty format
+    (revisions, pathspecs, ``--since``, ``--all``, ``-n``, …).
+    """
+    root = Path(cwd)
+    git = git_executable or resolve_git_executable()
+    if not _ensure_git_repo(root, git_executable=git):
+        return []
+
+    argv, _warnings = build_git_log_argv(git, git_log_args)
+    completed = _run_git(argv, cwd=root)
+    if completed.returncode != 0:
+        detail = completed.stderr.decode("utf-8", errors="replace").strip()
+        raise GitError(
+            detail or "git log failed",
+            stderr=detail,
+        )
+    return parse_git_log_output(completed.stdout)
+
+
+def iter_commits(
+    cwd: str | Path = ".",
+    *,
+    git_executable: str | None = None,
+    git_log_args: Sequence[str] | None = None,
+) -> Iterator[RawCommit]:
+    """Yield commits in ``git log`` order as Git writes them.
+
+    ``git_log_args`` are forwarded like :func:`list_commits`.
+    """
+    root = Path(cwd)
+    git = git_executable or resolve_git_executable()
+    if not _ensure_git_repo(root, git_executable=git):
+        return
+
+    argv, _warnings = build_git_log_argv(git, git_log_args)
+    try:
+        proc = subprocess.Popen(
+            argv,
+            cwd=root,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
+    except FileNotFoundError as exc:
+        raise GitError("git executable not found on PATH") from exc
+    except NotADirectoryError as exc:
+        raise GitError(f"not a directory: {cwd}") from exc
+
+    assert proc.stdout is not None
+    stderr = b""
+    code = 1
+    try:
+        yield from iter_parse_git_log_stream(proc.stdout)
+        stderr = proc.stderr.read() if proc.stderr is not None else b""
+        code = proc.wait()
+    finally:
+        if proc.poll() is None:
+            proc.kill()
+            proc.wait()
+
+    if code != 0:
+        detail = stderr.decode("utf-8", errors="replace").strip()
+        raise GitError(
+            detail or "git log failed",
+            stderr=detail,
+        )

esys_gitlog/identifiers.py

@@ -0,0 +1,46 @@
+"""Identifier family matchers for Refs tokens."""
+
+from __future__ import annotations
+
+import re
+
+# Jira key and the same shape used by YouTrack / Linear.
+_JIRA_KEY = re.compile(r"^[A-Za-z][A-Za-z0-9_]*-\d+$")
+
+# Shapes from references.md that any-id accepts beyond the Jira key.
+_ANY_EXTRA = (
+    re.compile(r"^#\d+$"),
+    re.compile(r"^GH-\d+$", re.IGNORECASE),
+    re.compile(r"^GL-\d+$", re.IGNORECASE),
+    re.compile(r"^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+#\d+$"),
+    re.compile(r"^AB#\d+$", re.IGNORECASE),
+    re.compile(r"^T\d+$"),
+    re.compile(r"^Bug\s+#?\d+$", re.IGNORECASE),
+    re.compile(r"^issue\s+#\d+$", re.IGNORECASE),
+    re.compile(r"^&\d+$"),
+    re.compile(r"^!\d+$"),
+    re.compile(r"^\[[a-z_]+:[^\]]+\]$", re.IGNORECASE),
+)
+
+
+def is_jira_id(token: str) -> bool:
+    return _JIRA_KEY.fullmatch(token) is not None
+
+
+def is_any_id(token: str) -> bool:
+    if is_jira_id(token):
+        return True
+    return any(pattern.fullmatch(token) for pattern in _ANY_EXTRA)
+
+
+def matches_family(token: str, family: str) -> bool:
+    if family == "jira-id":
+        return is_jira_id(token)
+    if family == "any-id":
+        return is_any_id(token)
+    raise ValueError(f"unknown identifier family: {family!r}")
+
+
+def ref_identity_key(token: str) -> str:
+    """Letter case does not make a different id."""
+    return token.casefold()