diffbutler 0.5.0__py3-none-any.whl

diffbutler/core/repositories.py

@@ -0,0 +1,260 @@
+"""Persistent, owned Git object storage with cross-process serialization and pins."""
+
+import asyncio
+import fcntl
+import json
+import logging
+import os
+import stat
+import time
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Literal
+from uuid import NAMESPACE_URL, UUID, uuid5
+
+from diffbutler.core.resources import save_json
+from diffbutler.domain.forge import PRRef
+from diffbutler.domain.resources import OwnedDirectory
+from diffbutler.reviewers.resources import OwnedDirectories, settled_io
+from diffbutler.sources.diagnostics import debug_event
+from diffbutler.sources.fetch import fetch_repository, git_fetch_command
+from diffbutler.sources.git import GitSourceReader, SourceError
+
+
+@asynccontextmanager
+async def file_lock(path: Path) -> AsyncGenerator[None]:
+    """Cancellation never leaves a background thread waiting on an advisory lock."""
+    await settled_io(lambda: path.parent.mkdir(parents=True, exist_ok=True))
+    fd = os.open(path, os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW, 0o600)
+    try:
+        info = os.fstat(fd)
+        if not stat.S_ISREG(info.st_mode) or info.st_uid != os.getuid():
+            raise ValueError("Invalid managed storage lock")
+        while True:
+            try:
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                break
+            except BlockingIOError:
+                await asyncio.sleep(0.05)
+        yield
+    finally:
+        os.close(fd)
+
+
+async def open_directories(path: Path) -> OwnedDirectories:
+    marker = path / ".diffbutler-repositories"
+    if path.exists() or path.is_symlink():
+        directories = await OwnedDirectories.reopen(path)
+        if marker.is_symlink() or await settled_io(marker.read_text) != "1\n":
+            raise ValueError("Invalid shared repository root")
+        return directories
+    await settled_io(lambda: path.parent.mkdir(parents=True, exist_ok=True))
+    directories = await OwnedDirectories.initialize(path)
+    await settled_io(lambda: marker.write_text("1\n"))
+    return directories
+
+
+class RepositoryCache:
+    def __init__(self, path: Path, retention_days: int = 30) -> None:
+        self.path = path
+        self.retention_seconds = retention_days * 86400
+
+    @property
+    def lock_path(self) -> Path:
+        # Outside the root so initialization, deletion, and replacement share a lock.
+        return self.path.parent / f".{self.path.name}.lock"
+
+    @staticmethod
+    def resource(directories: OwnedDirectories, ref: PRRef) -> OwnedDirectory:
+        identity = json.dumps([ref.forge, ref.namespace, ref.repository])
+        key = uuid5(NAMESPACE_URL, identity)
+        return OwnedDirectory(directories.root_id, key, key)
+
+    async def existing(self, ref: PRRef) -> Path | None:
+        if not self.path.exists():
+            return None
+        directories = await open_directories(self.path)
+        path = self.path / self.resource(directories, ref).name
+        return path if path.is_dir() and not path.is_symlink() else None
+
+    async def prepare(
+        self,
+        ref: PRRef,
+        session_id: UUID,
+        run_id: UUID,
+        base_sha: str,
+        head_sha: str,
+        *,
+        local_path: Path | None = None,
+        transport: Literal["auto", "https", "ssh"] = "auto",
+    ) -> tuple[Path, Literal["https", "ssh"] | None]:
+        async with file_lock(self.lock_path):
+            directories = await open_directories(self.path)
+            resource = self.resource(directories, ref)
+            path = self.path / resource.name
+            debug_event(
+                logging.getLogger(__name__),
+                "Preparing source context",
+                repository=path,
+                local_path=local_path,
+                ref=ref,
+                base_sha=base_sha,
+                head_sha=head_sha,
+                transport=transport,
+                session_id=session_id,
+                run_id=run_id,
+            )
+            if not path.exists():
+                await directories.create(resource)
+            if path.is_symlink():
+                raise SourceError("Managed repository was replaced by a symlink")
+            # Register before any fetch, including failed/interrupted preparations.
+            pin = path / "pins" / f"{session_id.hex}-{run_id.hex}.json"
+
+            def register() -> None:
+                pin.parent.mkdir(mode=0o700, exist_ok=True)
+                (path / "last-used").touch()
+
+            await settled_io(register)
+            await save_json(pin, {"base": base_sha, "head": head_sha})
+            learned: Literal["https", "ssh"] | None = None
+            try:
+                await GitSourceReader.open(path, base_sha=base_sha, head_sha=head_sha)
+            except SourceError as exc:
+                debug_event(logging.getLogger(__name__), "Cached source unavailable", reason=exc)
+                imported = False
+                if local_path is not None:
+                    try:
+                        await GitSourceReader.open(local_path, base_sha=base_sha, head_sha=head_sha)
+                    except SourceError as exc:
+                        debug_event(
+                            logging.getLogger(__name__), "Local source unavailable", reason=exc
+                        )
+                        # Even without the PR head, a local commit can supply most blobs.
+                        # Retain a ref so the remote fetch can negotiate from this commit.
+                        await git_fetch_command(path, "init", "--bare", "--template=")
+                        logging.getLogger(__name__).info(
+                            "Seeding PR object cache from local commits"
+                        )
+                        for revision in (base_sha, "HEAD"):
+                            try:
+                                await git_fetch_command(
+                                    path,
+                                    "fetch",
+                                    *(("--unshallow",) if (path / "shallow").is_file() else ()),
+                                    "--no-tags",
+                                    "--no-recurse-submodules",
+                                    "--",
+                                    str(local_path.absolute()),
+                                    f"+{revision}:refs/diffbutler/local-seed",
+                                    local=True,
+                                )
+                                break
+                            except SourceError as seed_error:
+                                logging.getLogger(__name__).info(
+                                    "Local cache seed unavailable: %s", seed_error
+                                )
+                    else:
+                        await git_fetch_command(path, "init", "--bare", "--template=")
+                        await git_fetch_command(
+                            path,
+                            "fetch",
+                            *(("--unshallow",) if (path / "shallow").is_file() else ()),
+                            "--no-tags",
+                            "--no-recurse-submodules",
+                            "--",
+                            str(local_path.absolute()),
+                            "+refs/heads/*:refs/remotes/local/*",
+                            base_sha,
+                            head_sha,
+                            local=True,
+                        )
+                        imported = True
+                if not imported:
+                    learned = await fetch_repository(
+                        path, ref, base_sha, head_sha, transport=transport
+                    )
+            reader = await GitSourceReader.open(path, base_sha=base_sha, head_sha=head_sha)
+            await save_json(
+                pin,
+                {
+                    "base": base_sha,
+                    "head": head_sha,
+                    "merge-base": reader.comparison_base_sha,
+                },
+            )
+            for side, sha in (
+                ("base", base_sha),
+                ("head", head_sha),
+                ("merge-base", reader.comparison_base_sha),
+            ):
+                await git_fetch_command(
+                    path, "update-ref", f"refs/diffbutler/{session_id.hex}/{run_id.hex}/{side}", sha
+                )
+            return path, learned
+
+    async def release(self, session_id: UUID) -> None:
+        if not self.path.exists():
+            return
+        async with file_lock(self.lock_path):
+            directories = await open_directories(self.path)
+            for resource in await self._resources(directories):
+                path = self.path / resource.name
+                pins = await settled_io(
+                    lambda path=path: list((path / "pins").glob(f"{session_id.hex}-*.json"))
+                )
+                for pin in pins:
+                    run_id = UUID(pin.stem.split("-")[1])
+                    if (path / "HEAD").exists():
+                        for side in ("base", "head", "merge-base"):
+                            await git_fetch_command(
+                                path,
+                                "update-ref",
+                                "-d",
+                                f"refs/diffbutler/{session_id.hex}/{run_id.hex}/{side}",
+                            )
+                    await settled_io(pin.unlink)
+                    await settled_io(lambda path=path: (path / "last-used").touch())
+
+    async def prune(self) -> None:
+        """Evict whole inactive repositories; never expire a live session's pins."""
+        if not self.path.exists():
+            return
+        async with file_lock(self.lock_path):
+            directories = await open_directories(self.path)
+            for resource in await self._resources(directories):
+                path = self.path / resource.name
+
+                def expired(path: Path = path) -> bool:
+                    if any((path / "pins").glob("*.json")):
+                        return False
+                    marker = path / "last-used"
+                    modified = marker.stat().st_mtime if marker.exists() else path.stat().st_mtime
+                    return time.time() - modified >= self.retention_seconds
+
+                if await settled_io(expired):
+                    await directories.delete(resource)
+
+    async def _resources(self, directories: OwnedDirectories) -> list[OwnedDirectory]:
+        def read() -> list[OwnedDirectory]:
+            result: list[OwnedDirectory] = []
+            for path in directories.path.iterdir():
+                if path.name in {".diffbutler-root", ".diffbutler-repositories"}:
+                    continue
+                try:
+                    left, right = path.name.split("-")
+                    resource = OwnedDirectory(directories.root_id, UUID(left), UUID(right))
+                except ValueError:
+                    raise ValueError("Unrecognized managed repository resource") from None
+                if (
+                    resource.name != path.name
+                    or resource.session_id != resource.resource_id
+                    or path.is_symlink()
+                    or not path.is_dir()
+                ):
+                    raise ValueError("Invalid managed repository resource")
+                result.append(resource)
+            return result
+
+        return await settled_io(read)

diffbutler/core/reset.py

@@ -0,0 +1,34 @@
+"""Explicit removal of local application directories without loading configuration."""
+
+import asyncio
+import shutil
+from pathlib import Path
+
+from diffbutler.config.diagnostics import state_path
+from diffbutler.config.settings import ConfigError, config_path, data_path
+
+
+def reset_paths() -> tuple[Path, ...]:
+    return tuple(
+        dict.fromkeys(
+            (config_path().parent.absolute(), data_path().absolute(), state_path().absolute())
+        )
+    )
+
+
+def remove_directory(path: Path) -> None:
+    """Remove the directory tree, unlinking rather than following symbolic links."""
+    try:
+        if path.is_symlink() or path.is_file():
+            path.unlink()
+        else:
+            shutil.rmtree(path)
+    except FileNotFoundError:
+        pass
+    except OSError:
+        raise ConfigError(f"reset: could not remove {path}; check permissions and retry") from None
+
+
+async def reset_directories(paths: tuple[Path, ...]) -> None:
+    for path in dict.fromkeys(paths):
+        await asyncio.to_thread(remove_directory, path)

diffbutler/core/resources.py

@@ -0,0 +1,50 @@
+"""Persist resource ownership before filesystem preparation, under a worker claim."""
+
+import json
+import os
+from dataclasses import replace
+from pathlib import Path
+from typing import Literal, Protocol
+from uuid import UUID, uuid4
+
+from diffbutler.domain.resources import OwnedDirectory
+from diffbutler.reviewers.resources import settled_io
+from diffbutler.store.base import ReviewStore
+
+
+async def save_json(path: Path, data: dict[str, str]) -> None:
+    """Publish a complete ownership/source record before creating dependent resources."""
+
+    def write() -> None:
+        temporary = path.with_name(f".{path.name}-{uuid4().hex}.tmp")
+        with temporary.open("x") as stream:
+            json.dump(data, stream)
+            stream.flush()
+            os.fsync(stream.fileno())
+        temporary.replace(path)
+        fd = os.open(path.parent, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
+        try:
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+
+    await settled_io(write)
+
+
+class DirectoryProvisioner(Protocol):
+    def reserve(self, session_id: UUID) -> OwnedDirectory: ...
+    async def create(self, resource: OwnedDirectory) -> Path: ...
+
+
+async def provision_directory(
+    store: ReviewStore,
+    directories: DirectoryProvisioner,
+    *,
+    token: UUID,
+    session_id: UUID,
+    purpose: Literal["artifact", "codex_home", "claude_home"] = "artifact",
+) -> Path:
+    """Failures retain the manifest; ordinary completion can clean absent resources."""
+    resource = replace(directories.reserve(session_id), purpose=purpose)
+    await store.register_resource(token, resource)
+    return await directories.create(resource)

diffbutler/core/review.py

@@ -0,0 +1,331 @@
+"""Immutable public review records. Explicit starts and worker claims never launch a process."""
+
+import asyncio
+import math
+from collections.abc import Awaitable, Callable
+from datetime import datetime
+from typing import cast
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, TypeAdapter
+
+from diffbutler.domain.diff import AnchorValidation, DiffAnchor, DiffIndex
+from diffbutler.domain.review import (
+    AnalysisIdentity,
+    ComparisonChanged,
+    ComparisonCheck,
+    ReviewPolicy,
+    ReviewResultRecord,
+    RunClaim,
+    RunRecord,
+    RunStatus,
+    SessionStatus,
+    Side,
+)
+from diffbutler.reviewers.base import ReviewOutput
+from diffbutler.reviewers.extraction import OutputFormat
+from diffbutler.reviewers.parsing import (
+    DraftReview,
+    ResponseFormat,
+    ReviewDocument,
+    Severity,
+    parse_review,
+)
+from diffbutler.store.base import ReviewStore
+
+
+class ReviewSession(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    id: UUID
+    task_id: UUID
+    reviewer_id: str
+    generation: int = Field(ge=1)
+    display_name: str
+    backend_session_id: str | None
+    status: SessionStatus
+    created_at: datetime
+
+
+class AIRun(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    id: UUID
+    task_id: UUID
+    session_id: UUID
+    reviewer_id: str
+    head_sha: str
+    base_sha: str
+    prompt_version: str
+    config_hash: str
+    analysis_key: str
+    attempt: int = Field(ge=1)
+    status: RunStatus
+    requested_at: datetime
+    started_at: datetime | None
+    finished_at: datetime | None
+    status_reason: str | None = None
+
+
+_ANCHORS = TypeAdapter(tuple[AnchorValidation, ...])
+
+
+class ReviewResult(BaseModel):
+    model_config = ConfigDict(frozen=True, ser_json_bytes="base64", val_json_bytes="base64")
+
+    run_id: UUID
+    exit_code: int
+    stdout: bytes | None
+    stderr: bytes | None
+    document: ReviewDocument | None
+    markdown: str | None = None
+    parse_tier: str | None
+    error: str | None
+    notes: tuple[str, ...]
+    selected_indices: tuple[int, ...]
+    min_confidence: float
+    findings_threshold: Severity
+    anchors: tuple[AnchorValidation, ...] | None = None
+
+
+async def _store_call[T](operation: Awaitable[T]) -> T:
+    """Settle short store operations before propagating cancellation.
+
+    Comparison fetches stay cancellable; only database operations are shielded.
+    """
+    task = asyncio.ensure_future(operation)
+    cancelled = False
+    try:
+        while not task.done():
+            try:
+                await asyncio.shield(task)
+            except asyncio.CancelledError:
+                cancelled = True
+        return task.result()
+    finally:
+        if cancelled:
+            # Retrieve an exception before cancellation wins, avoiding orphan tasks.
+            if task.done() and not task.cancelled():
+                task.exception()
+            raise asyncio.CancelledError
+
+
+class ReviewService:
+    """Internal scheduling seam; callers map explicit UI actions to requests.
+
+    The native executor selects the installed agent CLI permission profile. Worker
+    claims are durable and never expire automatically: process death must be
+    established before releasing ownership or finalizing a captured result.
+    """
+
+    def __init__(
+        self,
+        store: ReviewStore,
+        policy: ReviewPolicy,
+        compare_base: Callable[[RunRecord, str], Awaitable[bool]] | None = None,
+    ) -> None:
+        self.store = store
+        self.policy = policy
+        self.compare_base = compare_base
+
+    async def _comparison(self, token: UUID) -> ComparisonCheck:
+        run, base = await _store_call(self.store.comparison_snapshot(token))
+        matches = base == run.base_sha
+        if not matches and run.status == RunStatus.RUNNING and self.compare_base is not None:
+            matches = await self.compare_base(run, base)
+        return ComparisonCheck(base, matches)
+
+    async def get_run(self, run_id: UUID) -> AIRun:
+        return AIRun.model_validate(await self.store.get_run(run_id), from_attributes=True)
+
+    async def get_session(self, session_id: UUID) -> ReviewSession:
+        """Read durable conversation metadata; does not resume or start a process."""
+        return ReviewSession.model_validate(
+            await self.store.get_session(session_id), from_attributes=True
+        )
+
+    async def bind_backend_session(self, token: UUID, backend_session_id: str) -> ReviewSession:
+        """Checkpoint a backend identity while the caller still owns its worker claim."""
+        return ReviewSession.model_validate(
+            await self.store.bind_backend_session(token, backend_session_id), from_attributes=True
+        )
+
+    async def suspend_session(self, session_id: UUID) -> ReviewSession:
+        """Mark an idle conversation suspended; never stop a process or delete data."""
+        return ReviewSession.model_validate(
+            await self.store.suspend_session(session_id), from_attributes=True
+        )
+
+    async def request_review(self, identity: AnalysisIdentity) -> AIRun:
+        return AIRun.model_validate(
+            await self.store.request_review(identity, self.policy), from_attributes=True
+        )
+
+    async def claim_review(
+        self, run_id: UUID, *, capacity: int = 2, paused: bool = False
+    ) -> RunClaim | None:
+        if capacity < 1:
+            raise ValueError("capacity must be positive")
+        if paused:
+            return None
+        return await self.store.claim_review(run_id, capacity=capacity, policy=self.policy)
+
+    async def claim_is_current(self, token: UUID) -> bool:
+        while True:
+            comparison = await self._comparison(token)
+            try:
+                return await _store_call(
+                    self.store.claim_is_current(token, self.policy, comparison)
+                )
+            except ComparisonChanged:
+                continue
+
+    async def cancel_review(self, run_id: UUID) -> AIRun:
+        return AIRun.model_validate(await self.store.cancel_review(run_id), from_attributes=True)
+
+    async def release_review(
+        self, token: UUID, *, reason: str | None = None, output: ReviewOutput | None = None
+    ) -> AIRun:
+        """Acknowledge worker exit and retain safe diagnostics and available output."""
+        failure = (
+            None
+            if reason is None
+            else ReviewResultRecord(
+                output.exit_code if output else -1,
+                output.stdout if output else None,
+                output.stderr if output else None,
+                None,
+                None,
+                reason,
+                (),
+                (),
+                0.5,
+                "minor",
+            )
+        )
+        return AIRun.model_validate(
+            await self.store.release_review(token, failure), from_attributes=True
+        )
+
+    async def get_result(self, run_id: UUID) -> ReviewResult | None:
+        result = await self.store.get_result(run_id)
+        if result is None:
+            return None
+        return ReviewResult(
+            run_id=run_id,
+            exit_code=result.exit_code,
+            stdout=result.stdout,
+            stderr=result.stderr,
+            document=(
+                ReviewDocument.model_validate_json(result.document_json)
+                if result.document_json is not None and result.parse_tier != "markdown"
+                else None
+            ),
+            markdown=(
+                DraftReview.model_validate_json(result.document_json).markdown
+                if result.document_json is not None and result.parse_tier == "markdown"
+                else None
+            ),
+            parse_tier=result.parse_tier,
+            error=result.error,
+            notes=result.notes,
+            selected_indices=result.selected_indices,
+            min_confidence=result.min_confidence,
+            findings_threshold=cast(Severity, result.findings_threshold),
+            anchors=_ANCHORS.validate_json(result.anchors_json)
+            if result.anchors_json is not None
+            else None,
+        )
+
+    async def finalize_review(
+        self,
+        token: UUID,
+        output: ReviewOutput,
+        *,
+        diff_index: DiffIndex | None = None,
+        output_format: OutputFormat | None = None,
+        response_format: ResponseFormat = "json",
+        min_confidence: float = 0.5,
+        findings_threshold: Severity = "minor",
+    ) -> AIRun:
+        """Acknowledge verified worker exit and finalize already-extracted text.
+
+        A future executor must establish process-tree death before calling this.
+        Supply the original pinned context index to retain anchor validation.
+        Missing indexes are explicitly unvalidated. No forge is contacted.
+        """
+        ranks = {"question": 0, "nit": 1, "minor": 2, "important": 3, "blocking": 4}
+        if not math.isfinite(min_confidence) or not 0 <= min_confidence <= 1:
+            raise ValueError("minimum confidence must be finite and between zero and one")
+        if findings_threshold not in ranks:
+            raise ValueError("unknown findings threshold")
+        parsed = parse_review(
+            output,
+            output_format=output_format,
+            response_format=response_format,
+        )
+        selected = (
+            tuple(
+                index
+                for index, finding in enumerate(parsed.document.findings)
+                if finding.confidence >= min_confidence
+                and ranks[finding.severity] >= ranks[findings_threshold]
+            )
+            if parsed.document is not None
+            else ()
+        )
+        anchors = (
+            tuple(
+                diff_index.validate(
+                    DiffAnchor(
+                        path=finding.path,
+                        line=finding.line,
+                        start_line=finding.start_line,
+                        side=Side.BASE if finding.side == "LEFT" else Side.HEAD,
+                        base_sha=diff_index.base_sha,
+                        head_sha=diff_index.head_sha,
+                    )
+                )
+                for finding in parsed.document.findings
+            )
+            if parsed.document is not None and diff_index is not None
+            else None
+        )
+        result = ReviewResultRecord(
+            output.exit_code,
+            output.stdout,
+            output.stderr,
+            parsed.draft.model_dump_json()
+            if parsed.draft is not None
+            else parsed.document.model_dump_json()
+            if parsed.document is not None
+            else None,
+            parsed.tier,
+            parsed.error,
+            parsed.notes,
+            selected,
+            min_confidence,
+            findings_threshold,
+            _ANCHORS.dump_json(anchors).decode() if anchors is not None else None,
+            diff_index.base_sha if diff_index is not None else None,
+            diff_index.head_sha if diff_index is not None else None,
+        )
+        while True:
+            comparison = await self._comparison(token)
+            try:
+                return AIRun.model_validate(
+                    await self.store.finalize_review(
+                        token,
+                        result,
+                        backend_session_id=parsed.output.backend_session_id,
+                        no_findings=(
+                            parsed.draft.no_findings
+                            if parsed.draft is not None
+                            else parsed.document is not None and not parsed.document.findings
+                        ),
+                        comparison=comparison,
+                    ),
+                    from_attributes=True,
+                )
+            except ComparisonChanged:
+                continue