git-paoding 0.1.0__py3-none-any.whl

git_paoding/github/prbody.py

@@ -0,0 +1,281 @@
+"""Safe rendering and replacement of machine-managed PR body regions.
+
+Slice diffstats are supplied by callers from the reconciled atom set. Keeping
+that calculation outside this module avoids a second, Git-derived source of
+truth and preserves the boundary that only :mod:`git_paoding.gitio` invokes
+Git.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from git_paoding.core.model import DiffStat, SliceId
+
+MACHINE_REGION_START = "<!-- paoding-managed:start -->"
+MACHINE_REGION_END = "<!-- paoding-managed:end -->"
+LIFECYCLE_REGION_START = "<!-- paoding-lifecycle:start -->"
+LIFECYCLE_REGION_END = "<!-- paoding-lifecycle:end -->"
+SLICE_MARKER_PREFIX = "<!-- paoding-slice-id: "
+INTEGRATION_MARKER = "<!-- paoding-integration-pr -->"
+
+DO_NOT_MERGE_BANNER = (
+    "> [!CAUTION]\n"
+    "> **DO NOT MERGE — review projection only.** Final CI, approval, and merge belong to "
+    "the integration PR."
+)
+
+
+@dataclass(frozen=True, slots=True)
+class RelatedSliceLink:
+    """A published slice that overlaps the current slice by changed path."""
+
+    number: int
+    title: str
+    url: str
+    shared_paths: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class IntegrationSliceLink:
+    """One row in the integration PR's machine-managed slice index."""
+
+    slice_id: str
+    title: str
+    number: int | None
+    url: str | None
+
+
+def slice_marker(slice_id: SliceId | str) -> str:
+    """Return the stable, machine-readable PR identity marker for a slice."""
+
+    return f"{SLICE_MARKER_PREFIX}{slice_id} -->"
+
+
+def _escape_link_text(value: str) -> str:
+    return value.replace("\\", "\\\\").replace("[", "\\[").replace("]", "\\]")
+
+
+def _inline_code(value: str) -> str:
+    fence = "`" if "`" not in value else "``"
+    return f"{fence}{value}{fence}"
+
+
+def _pr_number_from_url(url: str) -> int | None:
+    match = re.search(r"/(?:pull|pulls)/(\d+)/?$", url)
+    return int(match.group(1)) if match is not None else None
+
+
+def _pr_link(*, number: int | None, title: str, url: str) -> str:
+    prefix = f"#{number} " if number is not None else ""
+    return f"[{prefix}{_escape_link_text(title)}]({url})"
+
+
+def render_diffstat(diffstat: DiffStat) -> str:
+    """Render an atoms-derived review-size summary."""
+
+    noun = "file" if diffstat.files_changed == 1 else "files"
+    return (
+        f"**Diffstat:** {diffstat.files_changed} {noun} changed, "
+        f"+{diffstat.additions} −{diffstat.deletions}"
+    )
+
+
+def render_slice_machine_content(
+    *,
+    slice_id: SliceId | str,
+    integration_pr_url: str,
+    diffstat: DiffStat | None = None,
+    related_slices: Sequence[RelatedSliceLink] = (),
+    currently_empty: bool = False,
+) -> str:
+    """Render the machine-owned metadata for a slice review pull request.
+
+    Callers may omit ``diffstat`` and ``related_slices`` to render only the
+    core metadata. Publication paths provide both from the same reconciled
+    atom set used to construct the projection.
+    """
+
+    integration_number = _pr_number_from_url(integration_pr_url)
+    parts = [
+        DO_NOT_MERGE_BANNER,
+        "Integration PR: "
+        + _pr_link(
+            number=integration_number,
+            title="integration change",
+            url=integration_pr_url,
+        ),
+    ]
+    if diffstat is not None:
+        parts.append(render_diffstat(diffstat))
+    if currently_empty:
+        parts.append("_This slice is currently empty._")
+    if related_slices:
+        related_lines = ["### Related slices sharing changed files"]
+        for related in related_slices:
+            paths = ", ".join(_inline_code(path) for path in related.shared_paths)
+            related_lines.append(
+                f"- {_pr_link(number=related.number, title=related.title, url=related.url)} — {paths}"
+            )
+        parts.append("\n".join(related_lines))
+    parts.append(slice_marker(slice_id))
+    return "\n\n".join(parts)
+
+
+def render_integration_machine_content(
+    slices: Sequence[IntegrationSliceLink],
+) -> str:
+    """Render the integration PR's machine-owned slice index."""
+
+    lines = ["## Review slices"]
+    if not slices:
+        lines.append("_No active review slices._")
+    for slice_ in slices:
+        if slice_.url is None:
+            lines.append(f"- `{slice_.slice_id}` — {slice_.title} _(currently empty)_")
+        else:
+            lines.append(
+                f"- {_pr_link(number=slice_.number, title=slice_.title, url=slice_.url)} "
+                f"(`{slice_.slice_id}`)"
+            )
+    lines.extend(("", INTEGRATION_MARKER))
+    return "\n".join(lines)
+
+
+def _region(content: str, *, start: str, end: str) -> str:
+    return f"{start}\n{content}\n{end}"
+
+
+def machine_region(content: str) -> str:
+    """Wrap managed content in the stable HTML-comment delimiters."""
+
+    return _region(content, start=MACHINE_REGION_START, end=MACHINE_REGION_END)
+
+
+def _rewrite_region(body: str, content: str, *, start_marker: str, end_marker: str) -> str:
+    """Replace the last complete named region, or append a healed region."""
+
+    start = body.rfind(start_marker)
+    end = body.find(end_marker, start + len(start_marker)) if start >= 0 else -1
+    replacement = _region(content, start=start_marker, end=end_marker)
+    if start >= 0 and end >= 0:
+        end += len(end_marker)
+        return body[:start] + replacement + body[end:]
+
+    if not body:
+        return replacement
+    separator = "\n" if body.endswith("\n") else "\n\n"
+    return body + separator + replacement
+
+
+def rewrite_machine_region(body: str, content: str) -> str:
+    """Rewrite only a complete managed region, or append one if it is missing.
+
+    The last start delimiter is used so a previously dangling delimiter cannot
+    capture human prose after a healed region is appended. Every byte outside
+    the selected delimiter pair is copied unchanged.
+    """
+
+    return _rewrite_region(
+        body,
+        content,
+        start_marker=MACHINE_REGION_START,
+        end_marker=MACHINE_REGION_END,
+    )
+
+
+def rewrite_slice_body(
+    body: str,
+    *,
+    slice_id: SliceId | str,
+    integration_pr_url: str,
+    diffstat: DiffStat | None = None,
+    related_slices: Sequence[RelatedSliceLink] = (),
+    currently_empty: bool = False,
+) -> str:
+    """Replace machine-owned slice metadata while preserving author narrative."""
+
+    return rewrite_machine_region(
+        body,
+        render_slice_machine_content(
+            slice_id=slice_id,
+            integration_pr_url=integration_pr_url,
+            diffstat=diffstat,
+            related_slices=related_slices,
+            currently_empty=currently_empty,
+        ),
+    )
+
+
+def rewrite_integration_body(
+    body: str,
+    *,
+    slices: Sequence[IntegrationSliceLink],
+) -> str:
+    """Refresh only the integration PR's machine-owned slice index."""
+
+    return rewrite_machine_region(body, render_integration_machine_content(slices))
+
+
+def render_removed_slice_note(slice_id: SliceId | str) -> str:
+    """Render the durable note left when a slice is removed."""
+
+    return (
+        "> [!NOTE]\n"
+        f"> Review slice `{slice_id}` was removed from the active decomposition and closed "
+        "without merging. Its discussion is retained for history."
+    )
+
+
+def render_archived_slice_note(
+    *,
+    integration_pr_number: int,
+    integration_pr_url: str,
+    merged_commit: str,
+    merged_commit_url: str,
+) -> str:
+    """Render the final note left after the integration change is merged."""
+
+    return (
+        "> [!NOTE]\n"
+        "> Archived after the integration change merged in "
+        f"[#{integration_pr_number}]({integration_pr_url}) at "
+        f"[{merged_commit[:12]}]({merged_commit_url}). This projection was closed without "
+        "merging and remains available as review history."
+    )
+
+
+def rewrite_removed_slice_body(body: str, *, slice_id: SliceId | str) -> str:
+    """Append or refresh the machine-owned removal note."""
+
+    return _rewrite_region(
+        body,
+        render_removed_slice_note(slice_id),
+        start_marker=LIFECYCLE_REGION_START,
+        end_marker=LIFECYCLE_REGION_END,
+    )
+
+
+def rewrite_archived_slice_body(
+    body: str,
+    *,
+    integration_pr_number: int,
+    integration_pr_url: str,
+    merged_commit: str,
+    merged_commit_url: str,
+) -> str:
+    """Append or refresh the machine-owned archive note."""
+
+    return _rewrite_region(
+        body,
+        render_archived_slice_note(
+            integration_pr_number=integration_pr_number,
+            integration_pr_url=integration_pr_url,
+            merged_commit=merged_commit,
+            merged_commit_url=merged_commit_url,
+        ),
+        start_marker=LIFECYCLE_REGION_START,
+        end_marker=LIFECYCLE_REGION_END,
+    )

git_paoding/gitio/__init__.py

@@ -0,0 +1,49 @@
+"""Git plumbing package."""
+
+from git_paoding.gitio.diffparse import RawDiffHunk, diff_trees, parse_diff
+from git_paoding.gitio.plumbing import (
+    GitIdentity,
+    RemoteRef,
+    TreeEntry,
+    cat_file,
+    commit_committer_date,
+    commit_tree,
+    hash_object,
+    ls_remote,
+    ls_tree,
+    mktree,
+    rev_parse,
+    update_ref,
+)
+from git_paoding.gitio.runner import (
+    GitCommandError,
+    GitError,
+    GitFailureKind,
+    GitResult,
+    GitUnavailableError,
+    run_git,
+)
+
+__all__ = [
+    "GitCommandError",
+    "GitError",
+    "GitFailureKind",
+    "GitIdentity",
+    "GitResult",
+    "GitUnavailableError",
+    "RawDiffHunk",
+    "RemoteRef",
+    "TreeEntry",
+    "cat_file",
+    "commit_committer_date",
+    "commit_tree",
+    "diff_trees",
+    "hash_object",
+    "ls_remote",
+    "ls_tree",
+    "mktree",
+    "parse_diff",
+    "rev_parse",
+    "run_git",
+    "update_ref",
+]

git_paoding/gitio/diffparse.py

@@ -0,0 +1,273 @@
+"""Parse zero-context Git diffs into raw, Base-anchored hunk records."""
+
+from __future__ import annotations
+
+import ast
+import re
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+
+from git_paoding.gitio.runner import run_git
+
+_DIFF_HEADER = re.compile(r'^diff --git (?P<base>"(?:\\.|[^"])*"|\S+) (?P<final>.+)$')
+_HUNK_HEADER = re.compile(
+    r"^@@ -(?P<base_start>\d+)(?:,(?P<base_len>\d+))? "
+    r"\+(?P<final_start>\d+)(?:,(?P<final_len>\d+))? @@"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class RawDiffHunk:
+    """One parsed hunk, or one sentinel record for a non-text file change."""
+
+    path: str
+    base_start: int
+    base_len: int
+    final_start: int
+    final_len: int
+    removed_lines: tuple[str, ...]
+    added_lines: tuple[str, ...]
+    is_add_file: bool = False
+    is_delete_file: bool = False
+    is_binary: bool = False
+    is_mode_change: bool = False
+    is_symlink: bool = False
+    no_newline_at_eof: bool = False
+    base_oid: str | None = None
+    final_oid: str | None = None
+    base_mode: str | None = None
+    final_mode: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class _RawFileChange:
+    """Object-database identity for one changed path."""
+
+    path: str
+    base_oid: str | None
+    final_oid: str | None
+    base_mode: str | None
+    final_mode: str | None
+
+
+@dataclass(slots=True)
+class _MutableHunk:
+    base_start: int
+    base_len: int
+    final_start: int
+    final_len: int
+    removed_lines: list[str] = field(default_factory=list)
+    added_lines: list[str] = field(default_factory=list)
+    no_newline_at_eof: bool = False
+    last_line_kind: str | None = None
+
+
+@dataclass(slots=True)
+class _FileDiff:
+    path: str
+    hunks: list[_MutableHunk] = field(default_factory=list)
+    is_add_file: bool = False
+    is_delete_file: bool = False
+    is_binary: bool = False
+    is_mode_change: bool = False
+    is_symlink: bool = False
+
+
+def _decode_header_path(value: str) -> str:
+    if value.startswith('"'):
+        decoded = ast.literal_eval(value)
+        if not isinstance(decoded, str):
+            raise ValueError(f"Invalid quoted Git path: {value}")
+        return decoded
+    return value
+
+
+def _strip_prefix(path: str) -> str:
+    if path.startswith(("a/", "b/")):
+        return path[2:]
+    return path
+
+
+def _finalize_file(file_diff: _FileDiff | None, records: list[RawDiffHunk]) -> None:
+    if file_diff is None:
+        return
+    hunks = file_diff.hunks or [_MutableHunk(0, 0, 0, 0)]
+    for hunk in hunks:
+        records.append(
+            RawDiffHunk(
+                path=file_diff.path,
+                base_start=hunk.base_start,
+                base_len=hunk.base_len,
+                final_start=hunk.final_start,
+                final_len=hunk.final_len,
+                removed_lines=tuple(hunk.removed_lines),
+                added_lines=tuple(hunk.added_lines),
+                is_add_file=file_diff.is_add_file,
+                is_delete_file=file_diff.is_delete_file,
+                is_binary=file_diff.is_binary,
+                is_mode_change=file_diff.is_mode_change,
+                is_symlink=file_diff.is_symlink,
+                no_newline_at_eof=hunk.no_newline_at_eof,
+            )
+        )
+
+
+def parse_diff(diff: bytes | str) -> tuple[RawDiffHunk, ...]:
+    """Parse output from ``git diff -U0 --no-renames``."""
+
+    text = diff.decode("utf-8", errors="surrogateescape") if isinstance(diff, bytes) else diff
+    records: list[RawDiffHunk] = []
+    current_file: _FileDiff | None = None
+    current_hunk: _MutableHunk | None = None
+
+    for line_with_end in text.splitlines(keepends=True):
+        line = line_with_end.removesuffix("\n")
+        header_match = _DIFF_HEADER.match(line)
+        if header_match is not None:
+            _finalize_file(current_file, records)
+            base_path = _decode_header_path(header_match.group("base"))
+            final_path = _decode_header_path(header_match.group("final"))
+            path = _strip_prefix(final_path if final_path != "/dev/null" else base_path)
+            current_file = _FileDiff(path=path)
+            current_hunk = None
+            continue
+        if current_file is None:
+            continue
+
+        if line.startswith("new file mode "):
+            current_file.is_add_file = True
+            current_file.is_symlink = line.endswith(" 120000")
+            continue
+        if line.startswith("deleted file mode "):
+            current_file.is_delete_file = True
+            current_file.is_symlink = line.endswith(" 120000")
+            continue
+        if line.startswith("old mode ") or line.startswith("new mode "):
+            current_file.is_mode_change = True
+            if line.endswith(" 120000"):
+                current_file.is_symlink = True
+            continue
+        if line.startswith("index ") and line.endswith(" 120000"):
+            current_file.is_symlink = True
+            continue
+        if line.startswith("Binary files ") or line == "GIT binary patch":
+            current_file.is_binary = True
+            continue
+
+        hunk_match = _HUNK_HEADER.match(line)
+        if hunk_match is not None:
+            current_hunk = _MutableHunk(
+                base_start=int(hunk_match.group("base_start")),
+                base_len=int(hunk_match.group("base_len") or "1"),
+                final_start=int(hunk_match.group("final_start")),
+                final_len=int(hunk_match.group("final_len") or "1"),
+            )
+            current_file.hunks.append(current_hunk)
+            continue
+        if current_hunk is None:
+            continue
+
+        if line.startswith("-"):
+            current_hunk.removed_lines.append(line_with_end[1:])
+            current_hunk.last_line_kind = "removed"
+        elif line.startswith("+"):
+            current_hunk.added_lines.append(line_with_end[1:])
+            current_hunk.last_line_kind = "added"
+        elif line == r"":
+            current_hunk.no_newline_at_eof = True
+            target = (
+                current_hunk.removed_lines
+                if current_hunk.last_line_kind == "removed"
+                else current_hunk.added_lines
+            )
+            if target and target[-1].endswith("\n"):
+                target[-1] = target[-1][:-1]
+
+    _finalize_file(current_file, records)
+    return tuple(records)
+
+
+def _optional_raw_value(value: bytes) -> str | None:
+    decoded = value.decode("ascii")
+    return None if not decoded.strip("0") else decoded
+
+
+def _parse_raw_changes(raw_diff: bytes) -> dict[str, _RawFileChange]:
+    """Parse ``git diff --raw -z`` metadata without losing unusual path bytes."""
+
+    fields = raw_diff.split(b"\0")
+    changes: dict[str, _RawFileChange] = {}
+    index = 0
+    while index < len(fields) and fields[index]:
+        metadata = fields[index]
+        if index + 1 >= len(fields):
+            raise ValueError("Raw Git diff ended before its path field")
+        raw_path = fields[index + 1]
+        parts = metadata.removeprefix(b":").split(b" ")
+        if len(parts) != 5:
+            raise ValueError(f"Unexpected raw Git diff metadata: {metadata!r}")
+        base_mode, final_mode, base_oid, final_oid, status = parts
+        if status.startswith((b"R", b"C")):
+            raise ValueError("Raw Git diff unexpectedly reported a rename or copy")
+        path = raw_path.decode("utf-8", errors="surrogateescape")
+        changes[path] = _RawFileChange(
+            path=path,
+            base_oid=_optional_raw_value(base_oid),
+            final_oid=_optional_raw_value(final_oid),
+            base_mode=_optional_raw_value(base_mode),
+            final_mode=_optional_raw_value(final_mode),
+        )
+        index += 2
+    return changes
+
+
+def diff_trees(repo: Path, base: str, final: str) -> tuple[RawDiffHunk, ...]:
+    """Read and parse a deterministic, zero-context tree diff."""
+
+    patch_output = run_git(
+        (
+            "-c",
+            "core.quotePath=false",
+            "diff",
+            "--no-color",
+            "--no-ext-diff",
+            "--no-textconv",
+            "--full-index",
+            "--unified=0",
+            "--no-renames",
+            base,
+            final,
+            "--",
+        ),
+        cwd=repo,
+    ).stdout
+    raw_output = run_git(
+        (
+            "diff",
+            "--raw",
+            "-z",
+            "--abbrev=40",
+            "--no-renames",
+            base,
+            final,
+            "--",
+        ),
+        cwd=repo,
+    ).stdout
+    changes = _parse_raw_changes(raw_output)
+    enriched: list[RawDiffHunk] = []
+    for hunk in parse_diff(patch_output):
+        try:
+            change = changes[hunk.path]
+        except KeyError as error:
+            raise ValueError(f"Patch path missing from raw Git diff: {hunk.path!r}") from error
+        enriched.append(
+            replace(
+                hunk,
+                base_oid=change.base_oid,
+                final_oid=change.final_oid,
+                base_mode=change.base_mode,
+                final_mode=change.final_mode,
+            )
+        )
+    return tuple(enriched)