diffbutler 0.5.0__py3-none-any.whl

diffbutler/core/worker.py

@@ -0,0 +1,205 @@
+"""Worker orchestration for explicit requests, including native CLI execution."""
+
+import asyncio
+import logging
+import math
+from collections.abc import Awaitable, Callable
+from contextlib import suppress
+from typing import Protocol
+from uuid import UUID
+
+from diffbutler.core.review import AIRun, ReviewService
+from diffbutler.domain.review import ReviewConflict, RunClaim, RunRecord
+from diffbutler.reviewers.base import ReviewContext, ReviewOutput
+from diffbutler.reviewers.extraction import OutputFormat
+from diffbutler.reviewers.parsing import ResponseFormat, Severity
+
+
+class ReviewExecution(Protocol):
+    async def run(
+        self,
+        context: ReviewContext,
+        backend_session_id: str | None,
+        checkpoint: Callable[[str], Awaitable[None]],
+    ) -> ReviewOutput:
+        """Capture output under the configured native permission profile, never a terminal.
+
+        Implementations must await checkpoint when a backend identity is learned.
+        Creating the execution object must not start a process; only run may start
+        it. A native adapter must reassert its permission profile and durable ownership,
+        including resumes from formerly foreground conversations.
+        """
+        ...
+
+    def partial_output(self) -> ReviewOutput:
+        """Read captured bytes after stop_and_wait has established exit."""
+        ...
+
+    async def stop_and_wait(self) -> None:
+        """Establish whole process-tree exit, including a spawn still in progress.
+
+        Required on normal return too: protocol completion and EOF do not prove
+        exit. Raise if exit cannot be established, leaving durable ownership held.
+        This must also settle the run coroutine; no detached I/O may remain.
+        """
+        ...
+
+
+async def _settle[T](task: asyncio.Task[T]) -> tuple[T, bool]:
+    cancelled = False
+    while True:
+        try:
+            return await asyncio.shield(task), cancelled
+        except asyncio.CancelledError:
+            if task.done():
+                return task.result(), True
+            cancelled = True
+
+
+class ReviewWorker:
+    def __init__(
+        self,
+        reviews: ReviewService,
+        prepare: Callable[[RunRecord], Awaitable[ReviewContext]],
+        execution_factory: Callable[[RunClaim], ReviewExecution],
+        *,
+        before_prepare: Callable[[RunClaim], Awaitable[None]] | None = None,
+        output_format: OutputFormat | None = None,
+        response_format: ResponseFormat = "json",
+        poll_interval: float = 0.25,
+        min_confidence: float = 0.5,
+        findings_threshold: Severity = "minor",
+    ) -> None:
+        if not math.isfinite(poll_interval) or poll_interval <= 0:
+            raise ValueError("poll interval must be positive and finite")
+        self.reviews = reviews
+        self.before_prepare = before_prepare
+        self.prepare = prepare
+        self.execution_factory = execution_factory
+        self.output_format = output_format
+        self.response_format: ResponseFormat = response_format
+        self.poll_interval = poll_interval
+        self.min_confidence = min_confidence
+        self.findings_threshold: Severity = findings_threshold
+
+    async def execute_requested(
+        self,
+        run_id: UUID,
+        *,
+        capacity: int = 2,
+        paused: bool = False,
+    ) -> AIRun | None:
+        """Consume one already requested run, never create or requeue analysis.
+
+        Factory/prepare are trusted dependencies; native execution relies on the
+        installed agent sandbox and process-group lifecycle contract. Cancellation
+        releases ownership
+        only after stop_and_wait; stop failure deliberately retains the claim.
+        """
+        claim = await self.reviews.claim_review(run_id, capacity=capacity, paused=paused)
+        if claim is None:
+            return None
+        exited = True  # No execution object/process exists during preparation.
+        execution: ReviewExecution | None = None
+        context: ReviewContext | None = None
+        phase = "preparation"
+
+        try:
+            if self.before_prepare is not None:
+                await self.before_prepare(claim)
+            context = await self.prepare(claim.run)
+            if (context.run_id, context.session_id, context.pr.base_sha, context.pr.head_sha) != (
+                claim.run.id,
+                claim.run.session_id,
+                claim.run.base_sha,
+                claim.run.head_sha,
+            ):
+                raise ReviewConflict("Prepared context does not match worker ownership")
+            if context.diff_index is None or (
+                context.diff_index.base_sha,
+                context.diff_index.head_sha,
+            ) != (claim.run.base_sha, claim.run.head_sha):
+                raise ReviewConflict("Worker requires a pinned original diff index")
+            if not await self.reviews.claim_is_current(claim.token):
+                return await self.reviews.release_review(claim.token)
+            session = await self.reviews.get_session(claim.run.session_id)
+
+            async def checkpoint(identity: str) -> None:
+                await self.reviews.bind_backend_session(claim.token, identity)
+
+            phase = "agent execution"
+            execution = self.execution_factory(claim)
+            exited = False
+            running = asyncio.create_task(
+                execution.run(context, session.backend_session_id, checkpoint)
+            )
+            try:
+                async with asyncio.timeout(context.budget.timeout_s):
+                    while not running.done():
+                        await asyncio.wait((running,), timeout=self.poll_interval)
+                        if not await self.reviews.claim_is_current(claim.token):
+                            break
+                    if not running.done():
+                        output = None
+                    else:
+                        output = await running
+            finally:
+
+                async def stop() -> None:
+                    await execution.stop_and_wait()
+                    # Exit is established; settle the coroutine as well.
+                    running.cancel()
+                    await asyncio.gather(running, return_exceptions=True)
+
+                _, cancelled = await _settle(asyncio.create_task(stop()))
+                exited = True
+                if cancelled:
+                    raise asyncio.CancelledError
+            if output is None:
+                return await self.reviews.release_review(
+                    claim.token, reason="Review invalidated", output=execution.partial_output()
+                )
+            phase = "result processing"
+            result = await self.reviews.finalize_review(
+                claim.token,
+                output,
+                diff_index=context.diff_index,
+                output_format=self.output_format,
+                response_format=self.response_format,
+                min_confidence=self.min_confidence,
+                findings_threshold=self.findings_threshold,
+            )
+            if result.status_reason:
+                logging.getLogger(__name__).warning(
+                    "Review ended run=%s status=%s reason=%s",
+                    result.id,
+                    result.status,
+                    result.status_reason,
+                )
+            return result
+        except BaseException as exc:
+            if exited:
+                if isinstance(exc, asyncio.CancelledError):
+                    reason = "Review cancelled"
+                elif isinstance(exc, TimeoutError) and context is not None:
+                    seconds = context.budget.timeout_s
+                    duration = (
+                        f"{seconds // 60} minutes" if seconds % 60 == 0 else f"{seconds} seconds"
+                    )
+                    reason = f"Review timed out after {duration}"
+                else:
+                    # Exception messages may contain PR content, paths or credentials.
+                    reason = f"Review failed during {phase} ({type(exc).__name__})"
+                # An uncertain finalization commit may already have consumed this
+                # token. Never retry finalization or overwrite the retained result.
+                with suppress(ReviewConflict):
+                    await _settle(
+                        asyncio.create_task(
+                            self.reviews.release_review(
+                                claim.token,
+                                reason=reason,
+                                output=execution.partial_output() if execution else None,
+                            )
+                        )
+                    )
+            raise

diffbutler/core/workspaces.py

@@ -0,0 +1,139 @@
+"""Reconstructible snapshots; persistent native homes retain their identities."""
+
+import json
+from collections.abc import Callable
+from pathlib import Path
+from uuid import UUID, uuid4
+
+from diffbutler.core.repositories import file_lock
+from diffbutler.core.resources import save_json
+from diffbutler.core.snapshot import write_snapshot
+from diffbutler.domain.resources import OwnedDirectory
+from diffbutler.reviewers.resources import OwnedDirectories, settled_io
+from diffbutler.sources.fetch import git_fetch_command
+from diffbutler.sources.git import GitSourceReader
+
+
+class SnapshotWorkspaces:
+    def __init__(self, homes: OwnedDirectories, path: Path | None = None) -> None:
+        self.homes = homes
+        self.path = path
+
+    async def directories(self, *, create: bool) -> OwnedDirectories | None:
+        record = self.homes.path / ".snapshot-location.json"
+        async with file_lock(self.homes.path / ".snapshot-lock"):
+            if record.exists():
+                data = json.loads(await settled_io(record.read_text))
+                path = Path(data["path"])
+                identity = UUID(data["root_id"])
+                if not path.is_absolute():
+                    raise ValueError("Invalid snapshot root")
+                if self.path is not None and self.path.absolute() != path:
+                    raise ValueError("Snapshot root cannot change while using this managed home")
+            elif self.path is None or not create:
+                return None
+            else:
+                path = self.path.absolute()
+                identity = uuid4()
+                # Do not adopt preexisting directories, even if they have a marker.
+                if path.exists() or path.is_symlink():
+                    raise ValueError("Snapshot root must be a new private directory")
+
+                await save_json(record, {"path": str(path), "root_id": str(identity)})
+            if not path.exists() and not path.is_symlink():
+                if not create:
+                    return None
+                await settled_io(lambda: path.parent.mkdir(parents=True, exist_ok=True))
+                return await OwnedDirectories.initialize(path, root_id=identity)
+            directories = await OwnedDirectories.reopen(path)
+            if directories.root_id != identity:
+                raise ValueError("Snapshot root identity mismatch")
+            return directories
+
+    @staticmethod
+    def resource(directories: OwnedDirectories, home: OwnedDirectory) -> OwnedDirectory:
+        return OwnedDirectory(directories.root_id, home.session_id, home.resource_id)
+
+    async def session_path(self, home: OwnedDirectory) -> Path:
+        directories = await self.directories(create=True)
+        if directories is None:
+            return self.homes.path / home.name
+        resource = self.resource(directories, home)
+        path = directories.path / resource.name
+        if path.is_symlink():
+            raise ValueError("Snapshot workspace was replaced by a symlink")
+        if not path.exists():
+            await directories.create(resource)
+        return path
+
+    async def cleanup(self, home: OwnedDirectory) -> None:
+        directories = await self.directories(create=False)
+        if directories is not None:
+            await directories.delete(self.resource(directories, home))
+
+
+async def materialize(
+    reader: GitSourceReader,
+    destination: Path,
+    *,
+    progress: Callable[[str], None] | None = None,
+) -> None:
+    """Publish only complete snapshots; an interrupted preparation is reconstructible."""
+    temporary = destination.with_name(f".{destination.name}-{uuid4().hex}.tmp")
+    await settled_io(lambda: destination.parent.mkdir(mode=0o700, parents=True, exist_ok=True))
+    await write_snapshot(reader, temporary, progress=progress)
+    await settled_io(lambda: temporary.rename(destination))
+
+
+async def materialize_checkout(
+    reader: GitSourceReader,
+    destination: Path,
+    *,
+    progress: Callable[[str], None] | None = None,
+) -> None:
+    """Create a private head checkout backed by the session-pinned object cache."""
+    temporary = destination.with_name(f".{destination.name}-{uuid4().hex}.tmp")
+    common = await reader.common_directory()
+    if progress is not None:
+        progress("Checking out PR sources…")
+    await settled_io(lambda: temporary.mkdir(mode=0o700, parents=True))
+    await git_fetch_command(
+        temporary,
+        "init",
+        "--template=",
+        f"--object-format={'sha256' if len(reader.head_sha) == 64 else 'sha1'}",
+        local=True,
+    )
+
+    def configure() -> None:
+        gitdir = temporary / ".git"
+        # Quote the alternate path using Git's C-style path syntax.
+        (gitdir / "objects/info/alternates").write_text(
+            json.dumps(str(common / "objects"), ensure_ascii=False) + "\n"
+        )
+        with (gitdir / "config").open("a") as config:
+            config.write(
+                "\n[core]\n\thooksPath = /dev/null\n\tfsmonitor = false\n\tautocrlf = false\n"
+            )
+
+    await settled_io(configure)
+    await git_fetch_command(
+        temporary, "update-ref", "refs/heads/diffbutler-base", reader.base_sha, local=True
+    )
+    await git_fetch_command(
+        temporary,
+        "update-ref",
+        "refs/heads/diffbutler-merge-base",
+        reader.comparison_base_sha,
+        local=True,
+    )
+    await git_fetch_command(
+        temporary,
+        "checkout",
+        "--no-recurse-submodules",
+        "-b",
+        "diffbutler-pr",
+        reader.head_sha,
+        local=True,
+    )
+    await settled_io(lambda: temporary.rename(destination))

diffbutler/domain/__init__.py

@@ -0,0 +1 @@
+"""Pure domain entities and workflow rules."""

diffbutler/domain/dashboard.py

@@ -0,0 +1,63 @@
+"""Local workflow and historical cycle values, without rendering or I/O."""
+
+from dataclasses import dataclass
+from datetime import datetime
+from uuid import UUID
+
+from diffbutler.domain.forge import Account, PullRequest
+from diffbutler.domain.review import RunRecord, SessionRecord
+from diffbutler.domain.sync import CommentEvent, ReviewEvent
+
+
+@dataclass(frozen=True)
+class CycleRecord:
+    task_id: UUID
+    account: Account
+    pull_request: PullRequest
+    cycle: int
+    state: str
+    completed_at: datetime | None
+    completion_reason: str | None
+    completed_head_sha: str | None
+    cleanup_status: str
+    cleanup_error: str | None
+    opened_at: datetime | None
+    runs: tuple[RunRecord, ...]
+    sessions: tuple[SessionRecord, ...]
+    receipts: tuple[ReviewEvent | CommentEvent, ...]
+
+
+COLUMN_IDS = (
+    "state",
+    "attention",
+    "repo",
+    "number",
+    "title",
+    "author",
+    "ai_status",
+    "findings",
+    "max_severity",
+    "age",
+    "updated",
+    "branch",
+    "draft",
+    "reviewers",
+    "unverified",
+    "url",
+    "additions",
+    "deletions",
+    "files",
+    "labels",
+    "ci",
+)
+
+STATE_LABELS = {
+    "PENDING_AI_REVIEW": "pending",
+    "QUEUED": "queued",
+    "AI_RUNNING": "running",
+    "PENDING_HUMAN_REVIEW": "approve",
+    "FINDINGS_TRIAGE": "check",
+    "PENDING_AUTHOR_CHANGES": "author",
+    "DONE": "done",
+    "DONE_PLUS": "done+",
+}

diffbutler/domain/diff.py

@@ -0,0 +1,285 @@
+"""Forge-neutral anchors and validation outcomes; no source text is retained."""
+
+import re
+from dataclasses import dataclass, replace
+from typing import Literal
+
+from diffbutler.domain.review import Side, SourceFile
+
+
+@dataclass(frozen=True)
+class DiffAnchor:
+    path: str
+    line: int
+    side: Side
+    start_line: int | None = None
+    old_path: str | None = None
+    base_sha: str = ""
+    head_sha: str = ""
+
+    def __post_init__(self) -> None:
+        SourceFile(self.path, self.side)
+        if self.old_path is not None:
+            SourceFile(self.old_path, Side.BASE)
+        if self.line < 1 or (self.start_line is not None and not 1 <= self.start_line <= self.line):
+            raise ValueError("anchor lines must be positive and ordered")
+
+
+@dataclass(frozen=True)
+class AnchorValidation:
+    original: DiffAnchor
+    anchor: DiffAnchor | None
+    status: Literal["exact", "snapped", "demoted"]
+
+
+_HUNK = re.compile(r"@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@(?: .*)?")
+_BINARY = re.compile(
+    r'Binary files ("(?:[^"\\]|\\.)*"|a/.+?|/dev/null)'
+    r' and ("(?:[^"\\]|\\.)*"|b/.+|/dev/null) differ'
+)
+
+
+class InvalidDiff(ValueError):
+    def __init__(self) -> None:
+        super().__init__("Malformed or unsupported unified diff")
+
+
+def _path(value: str, prefix: str) -> str | None:
+    if value == "/dev/null":
+        return None
+    # Git quotes tabs, newlines, non-ASCII bytes and backslashes using C escapes.
+    if value.startswith('"'):
+        if not value.endswith('"'):
+            raise InvalidDiff()
+        raw = bytearray()
+        text = value[1:-1]
+        offset = 0
+        escapes = {"a": 7, "b": 8, "t": 9, "n": 10, "v": 11, "f": 12, "r": 13, '"': 34, "\\": 92}
+        while offset < len(text):
+            char = text[offset]
+            offset += 1
+            if char != "\\":
+                raw.extend(char.encode("utf-8"))
+                continue
+            if offset == len(text):
+                raise InvalidDiff()
+            char = text[offset]
+            if char in escapes:
+                raw.append(escapes[char])
+                offset += 1
+            elif re.fullmatch(r"[0-3][0-7]{2}", text[offset : offset + 3]):
+                raw.append(int(text[offset : offset + 3], 8))
+                offset += 3
+            else:
+                raise InvalidDiff()
+        try:
+            value = raw.decode("utf-8")
+        except UnicodeDecodeError:
+            raise InvalidDiff() from None
+    else:
+        value = value.removesuffix("\t")
+    if not value.startswith(prefix):
+        raise InvalidDiff()
+    path = value[len(prefix) :]
+    try:
+        SourceFile(path, Side.HEAD)
+    except ValueError:
+        raise InvalidDiff() from None
+    return path
+
+
+@dataclass(frozen=True)
+class _Hunk:
+    path: str
+    old_path: str | None
+    base_start: int
+    base_count: int
+    head_start: int
+    head_count: int
+
+    def bounds(self, side: Side) -> tuple[int, int]:
+        start, count = (
+            (self.base_start, self.base_count)
+            if side == Side.BASE
+            else (self.head_start, self.head_count)
+        )
+        return start, start + count - 1
+
+
+@dataclass(frozen=True)
+class DiffIndex:
+    """Index the original diff before redaction. No source text is stored.
+
+    Paths use the head name, or the base name for a deletion. Context lines are
+    commentable on both sides. Ranges must fit a single hunk on one side. Snapping
+    clips a range overlapping exactly one hunk, within the endpoint window; it
+    never guesses a hunk for a location wholly outside the diff or crosses sides.
+    """
+
+    hunks: tuple[_Hunk, ...]
+    base_sha: str = ""
+    head_sha: str = ""
+
+    @classmethod
+    def parse(cls, diff: str, *, base_sha: str = "", head_sha: str = "") -> DiffIndex:
+        if "\x00" in diff:
+            raise InvalidDiff()
+        lines = diff.split("\n")
+        if lines[-1] == "":
+            lines.pop()
+        hunks: list[_Hunk] = []
+        old: str | None = None
+        new: str | None = None
+        in_file = headers = has_hunk = False
+        seen: set[str] = set()
+        offset = 0
+        while offset < len(lines):
+            line = lines[offset]
+            offset += 1
+            if line.startswith("diff --git "):
+                if headers and not has_hunk:
+                    raise InvalidDiff()
+                in_file, headers, has_hunk = True, False, False
+                old = new = None
+            elif (
+                line.startswith(
+                    (
+                        "index ",
+                        "old mode ",
+                        "new mode ",
+                        "new file mode ",
+                        "deleted file mode ",
+                        "similarity index ",
+                        "rename from ",
+                        "rename to ",
+                    )
+                )
+                and in_file
+                and not headers
+            ):
+                continue
+            elif (binary := _BINARY.fullmatch(line)) is not None and in_file and not headers:
+                old = _path(binary[1], "a/")
+                new = _path(binary[2], "b/")
+                path = new or old
+                if path is None or path in seen:
+                    raise InvalidDiff()
+                seen.add(path)
+                # A summary has no commentable lines and ends this file.
+                in_file = False
+            elif line.startswith("--- ") and in_file and not headers:
+                if offset >= len(lines) or not lines[offset].startswith("+++ "):
+                    raise InvalidDiff()
+                old = _path(line[4:], "a/")
+                new = _path(lines[offset][4:], "b/")
+                offset += 1
+                if old is None and new is None:
+                    raise InvalidDiff()
+                path = new or old
+                assert path is not None
+                if path in seen:
+                    raise InvalidDiff()
+                seen.add(path)
+                headers = True
+            elif (match := _HUNK.fullmatch(line)) is not None and headers:
+                bs, bc, hs, hc = (
+                    int(match[1]),
+                    int(match[2] or 1),
+                    int(match[3]),
+                    int(match[4] or 1),
+                )
+                if (bc and bs < 1) or (hc and hs < 1) or not bc + hc:
+                    raise InvalidDiff()
+                if (old is None and bc) or (new is None and hc):
+                    raise InvalidDiff()
+                path = new or old
+                assert path is not None
+                hunk = _Hunk(path, old, bs, bc, hs, hc)
+                if hunks and hunks[-1].path == path:
+                    prev = hunks[-1]
+                    if (
+                        bs < prev.base_start + prev.base_count
+                        or hs < prev.head_start + prev.head_count
+                    ):
+                        raise InvalidDiff()
+                b = h = 0
+                marker_allowed = False
+                while b < bc or h < hc:
+                    if offset >= len(lines):
+                        raise InvalidDiff()
+                    body = lines[offset]
+                    offset += 1
+                    if body == "\" and marker_allowed:
+                        marker_allowed = False
+                        continue
+                    if not body or body[0] not in " +-":
+                        raise InvalidDiff()
+                    b += body[0] in " -"
+                    h += body[0] in " +"
+                    if b > bc or h > hc:
+                        raise InvalidDiff()
+                    marker_allowed = True
+                if offset < len(lines) and lines[offset] == "\":
+                    offset += 1
+                hunks.append(hunk)
+                has_hunk = True
+            else:
+                raise InvalidDiff()
+        if headers and not has_hunk:
+            raise InvalidDiff()
+        return cls(tuple(hunks), base_sha, head_sha)
+
+    def _matching(self, anchor: DiffAnchor) -> tuple[_Hunk, ...]:
+        if (anchor.base_sha and anchor.base_sha != self.base_sha) or (
+            anchor.head_sha and anchor.head_sha != self.head_sha
+        ):
+            return ()
+        return tuple(
+            hunk
+            for hunk in self.hunks
+            if hunk.path == anchor.path
+            and (anchor.old_path is None or anchor.old_path == hunk.old_path)
+        )
+
+    def is_commentable(self, anchor: DiffAnchor) -> bool:
+        start = anchor.start_line or anchor.line
+        return any(
+            low <= start <= anchor.line <= high
+            for low, high in (hunk.bounds(anchor.side) for hunk in self._matching(anchor))
+        )
+
+    def snap(self, anchor: DiffAnchor, *, window: int = 3) -> DiffAnchor | None:
+        if window < 0:
+            raise ValueError("snapping window must be nonnegative")
+        start = anchor.start_line or anchor.line
+        matches = [
+            hunk
+            for hunk in self._matching(anchor)
+            if (bounds := hunk.bounds(anchor.side))[0] <= bounds[1]
+            and start <= bounds[1]
+            and anchor.line >= bounds[0]
+        ]
+        if len(matches) != 1:
+            return None
+        hunk = matches[0]
+        low, high = hunk.bounds(anchor.side)
+        first, last = max(start, low), min(anchor.line, high)
+        if first - start > window or anchor.line - last > window:
+            return None
+        return replace(
+            anchor,
+            line=last,
+            start_line=first if anchor.start_line else None,
+            old_path=hunk.old_path,
+            base_sha=self.base_sha,
+            head_sha=self.head_sha,
+        )
+
+    def validate(self, anchor: DiffAnchor, *, window: int = 3) -> AnchorValidation:
+        snapped = self.snap(anchor, window=window)
+        status = (
+            "demoted"
+            if snapped is None
+            else ("exact" if self.is_commentable(anchor) else "snapped")
+        )
+        return AnchorValidation(anchor, snapped, status)