diffbutler 0.5.0__py3-none-any.whl

diffbutler/domain/forge.py

@@ -0,0 +1,123 @@
+"""Forge-neutral, immutable read results. No persistence or workflow side effects."""
+
+import re
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Literal
+
+
+def identity_part(value: str) -> str:
+    if not re.fullmatch(r"[A-Za-z0-9_.-]+", value) or value in {".", ".."}:
+        raise ValueError("repository, user, and team names must be simple identity components")
+    return value
+
+
+@dataclass(frozen=True)
+class Account:
+    forge: str
+    login: str
+    display_name: str
+
+
+@dataclass(frozen=True)
+class PRRef:
+    forge: str
+    namespace: str
+    repository: str
+    number: int
+
+    def __post_init__(self) -> None:
+        identity_part(self.namespace)
+        identity_part(self.repository)
+        if self.number < 1:
+            raise ValueError("PR number must be positive")
+
+
+@dataclass(frozen=True)
+class PullRequest:
+    ref: PRRef
+    title: str
+    author: str
+    url: str
+    state: Literal["open", "closed", "merged"]
+    head_sha: str
+    base_sha: str
+    head_ref: str
+    base_ref: str
+    is_draft: bool
+    created_at: datetime
+    updated_at: datetime
+    requested_users: tuple[str, ...]
+    requested_teams: tuple[str, ...]
+    additions: int | None = None
+    deletions: int | None = None
+    files: int | None = None
+    labels: tuple[str, ...] = ()
+    ci: str = "unknown"
+    assignees: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class PRQuery:
+    repository: str | None = None
+    author: str | None = None
+    state: Literal["open", "closed", "merged", "all"] = "open"
+    text: str = ""
+    page_size: int = 30
+
+    def __post_init__(self) -> None:
+        if self.repository is not None:
+            parts = self.repository.split("/")
+            if len(parts) != 2:
+                raise ValueError("repository must be namespace/name")
+            for part in parts:
+                identity_part(part)
+        if self.author is not None:
+            identity_part(self.author)
+        if self.state not in {"open", "closed", "merged", "all"}:
+            raise ValueError("state must be open, closed, merged, or all")
+        if not 1 <= self.page_size <= 100:
+            raise ValueError("page_size must be between 1 and 100")
+
+
+@dataclass(frozen=True)
+class PRPage:
+    items: tuple[PullRequest, ...]
+    next_cursor: str | None
+    complete: bool = True
+    warnings: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class RequestedPR:
+    pull_request: PullRequest
+    sources: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class Discovery:
+    items: tuple[RequestedPR, ...]
+    complete: bool
+    warnings: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class TeamMembership:
+    teams: tuple[str, ...]
+    complete: bool
+    warnings: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class RateLimit:
+    resource: str
+    remaining: int
+    limit: int
+    reset_at: datetime
+
+
+@dataclass(frozen=True)
+class ForgeHealth:
+    account: Account
+    limits: tuple[RateLimit, ...]
+    teams: TeamMembership | None

diffbutler/domain/lifecycle.py

@@ -0,0 +1,51 @@
+"""Immutable ownership and cleanup records, independent of processes and storage."""
+
+from dataclasses import dataclass
+from datetime import datetime
+from uuid import UUID
+
+
+@dataclass(frozen=True)
+class ForegroundLease:
+    token: UUID
+    session_id: UUID
+    backend_session_id: str
+    head_sha: str
+    task_version: int
+    acquired_at: datetime
+
+
+@dataclass(frozen=True)
+class CleanupSession:
+    id: UUID
+    reviewer_id: str
+    backend_session_id: str | None
+    transcript_ref: str | None
+    resources: tuple[tuple[tuple[str, str], ...], ...]
+
+
+@dataclass(frozen=True)
+class CleanupClaim:
+    token: UUID
+    job_id: UUID
+    sessions: tuple[CleanupSession, ...]
+
+
+@dataclass(frozen=True)
+class HeldOperation:
+    token: UUID
+    kind: str
+    resource_id: UUID
+    acquired_at: datetime
+
+
+class ForegroundExitUncertain(RuntimeError):
+    """Ownership must stay held when child exit cannot be established."""
+
+
+@dataclass(frozen=True)
+class CleanupStatus:
+    succeeded: int = 0
+    pending: int = 0
+    running: int = 0
+    failed: int = 0

diffbutler/domain/polling.py

@@ -0,0 +1,92 @@
+"""Pure quota budgeting for read-only polling; timestamps are supplied by the caller."""
+
+from dataclasses import dataclass
+
+from diffbutler.domain.forge import RateLimit
+
+
+@dataclass(frozen=True)
+class PollQuota:
+    host: str
+    login: str
+    quota: RateLimit
+    requests: int
+    observed_at: float
+
+    @property
+    def key(self) -> tuple[str, str, str]:
+        return self.host, self.login.casefold(), self.quota.resource
+
+
+class QuotaBudget:
+    """One account/resource's conservative cost estimate and threshold hysteresis."""
+
+    def __init__(self, minimum: float) -> None:
+        self.minimum = minimum
+        self.interval = minimum
+        self.sample: PollQuota | None = None
+        self.average_cost = 0.0
+        self.cost = 0.0
+        self.external_rate = 0.0
+        self.low = False
+        self.high_samples = 0
+        self.wait_for_reset = False
+
+    def update(self, sample: PollQuota, *, successful: bool, now: float) -> None:
+        previous = self.sample
+        quota = sample.quota
+        reset = quota.reset_at.timestamp()
+        if previous is not None and previous.quota.reset_at != quota.reset_at:
+            # Keep workload estimates, but never carry old-window depletion forward.
+            self.external_rate = 0
+            self.interval = self.minimum
+            self.low = False
+            self.high_samples = 0
+        elif previous is not None and sample.observed_at > previous.observed_at:
+            elapsed = sample.observed_at - previous.observed_at
+            external = max(0, previous.quota.remaining - quota.remaining - sample.requests)
+            self.external_rate = 0.3 * external / elapsed + 0.7 * self.external_rate
+        self.sample = sample
+        if not self.average_cost:
+            self.average_cost = max(1, sample.requests)
+        elif successful:
+            self.average_cost = 0.3 * sample.requests + 0.7 * self.average_cost
+        else:
+            # An incomplete refresh is not evidence that the queue became cheaper.
+            self.average_cost = max(self.average_cost, sample.requests)
+        estimated_cost = 1.25 * max(1, sample.requests, self.average_cost)
+        self.cost = estimated_cost if successful else max(self.cost, estimated_cost)
+
+        fraction = quota.remaining / quota.limit
+        if fraction < 0.2:
+            if not self.low:
+                self.interval *= 1.5
+            self.high_samples = 0
+        elif fraction > 0.8 and successful:
+            self.high_samples += 1
+            if self.high_samples >= 2:
+                self.interval *= 0.8
+                self.high_samples = 0
+        else:
+            self.high_samples = 0
+        self.low = fraction < 0.2
+
+        remaining_time = max(0, reset - now)
+        available = (
+            quota.remaining
+            - 0.1 * quota.limit
+            - self.external_rate * max(0, reset - sample.observed_at)
+        )
+        self.wait_for_reset = available < self.cost and remaining_time > 0
+        budget_interval = self.cost * remaining_time / available if available > 0 else 0
+        self.interval = max(self.minimum, self.interval, budget_interval)
+
+    def next_start(self, started: float, now: float) -> float:
+        assert self.sample is not None
+        reset = self.sample.quota.reset_at.timestamp() + 1
+        if now >= reset:
+            # Wake to get fresh headers, even if the previous interval was very long.
+            return started + self.minimum
+        if self.wait_for_reset:
+            return reset
+        return min(started + self.interval, reset)

diffbutler/domain/process.py

@@ -0,0 +1,29 @@
+"""Durable launch intent; a launcher PID alone never proves process-tree exit."""
+
+from dataclasses import dataclass
+from typing import Literal
+from uuid import UUID
+
+OperationKind = Literal["background", "foreground", "cleanup"]
+
+
+@dataclass(frozen=True)
+class HostBoot:
+    host_id: UUID
+    boot_id: UUID
+
+
+@dataclass(frozen=True)
+class ProcessLaunch:
+    token: UUID
+    kind: OperationKind
+    origin: HostBoot
+    launcher_pid: int | None = None
+
+    def __post_init__(self) -> None:
+        if self.launcher_pid is not None and self.launcher_pid < 1:
+            raise ValueError("Launcher PID must be positive")
+
+    def ended_by_reboot(self, current: HostBoot) -> bool:
+        # A different machine may still have the original process running.
+        return self.origin.host_id == current.host_id and self.origin.boot_id != current.boot_id

diffbutler/domain/redaction.py

@@ -0,0 +1,61 @@
+"""Conservative credential heuristics, not a guarantee that source has no secrets."""
+
+import math
+import re
+from collections import Counter
+from dataclasses import dataclass
+
+# Prefix matches are masked even for low-entropy example credentials. Assignment
+# matches require entropy to avoid hiding ordinary configuration and prose.
+_PREFIXED = re.compile(
+    rb"(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}"
+    rb"|(?:AKIA|ASIA)[A-Z0-9]{16}|sk-[A-Za-z0-9_-]{20,}"
+    rb"|xox[baprs]-[A-Za-z0-9-]{20,})"
+)
+_ASSIGNMENT = re.compile(
+    rb"(?i)(?<![A-Za-z0-9_])"
+    rb"[A-Za-z0-9_]*(?:token|password|passwd|secret|api[_-]?key|access[_-]?key)"
+    rb"[A-Za-z0-9_]*[\"']?[ \t]*[:=][ \t]*[\"']?"
+    rb"(?P<value>[A-Za-z0-9_./+=~-]{16,})"
+)
+_PRIVATE_KEY = re.compile(
+    rb"-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY-----"
+    rb"[\s\S]*?-----END (?:[A-Z0-9]+ )*PRIVATE KEY-----"
+)
+
+
+@dataclass(frozen=True)
+class RedactedSource:
+    content: bytes
+    count: int
+
+
+def redact_source(content: bytes) -> RedactedSource:
+    """Mask matching spans without changing byte offsets or CR/LF positions.
+
+    Counts describe merged occurrences, not unique credentials. No original value,
+    hash, or source location is included in diagnostics. Works on arbitrary bytes.
+    """
+    spans = [
+        match.span() for pattern in (_PREFIXED, _PRIVATE_KEY) for match in pattern.finditer(content)
+    ]
+    for match in _ASSIGNMENT.finditer(content):
+        value = match.group("value")
+        entropy = -sum(
+            (count / len(value)) * math.log2(count / len(value))
+            for count in Counter(value).values()
+        )
+        if entropy >= 3.5:
+            spans.append(match.span("value"))
+    merged: list[tuple[int, int]] = []
+    for start, end in sorted(spans):
+        if merged and start < merged[-1][1]:
+            merged[-1] = (merged[-1][0], max(end, merged[-1][1]))
+        else:
+            merged.append((start, end))
+    result = bytearray(content)
+    for start, end in merged:
+        for index in range(start, end):
+            if result[index] not in (10, 13):
+                result[index] = ord("*")
+    return RedactedSource(bytes(result), len(merged))

diffbutler/domain/resources.py

@@ -0,0 +1,50 @@
+"""Manifest identities are independent of filesystem paths and backend IDs."""
+
+from dataclasses import dataclass
+from typing import Literal, cast
+from uuid import UUID
+
+
+@dataclass(frozen=True)
+class OwnedDirectory:
+    root_id: UUID
+    session_id: UUID
+    resource_id: UUID
+    purpose: Literal["artifact", "codex_home", "claude_home"] = "artifact"
+
+    def manifest(self) -> dict[str, str]:
+        return {
+            "kind": "owned_directory_v1",
+            "root_id": str(self.root_id),
+            "session_id": str(self.session_id),
+            "resource_id": str(self.resource_id),
+            "purpose": self.purpose,
+        }
+
+    @classmethod
+    def from_manifest(cls, value: dict[str, str]) -> OwnedDirectory:
+        if (
+            set(value)
+            not in (
+                {"kind", "root_id", "session_id", "resource_id"},
+                {"kind", "root_id", "session_id", "resource_id", "purpose"},
+            )
+            or value.get("kind") != "owned_directory_v1"
+        ):
+            raise ValueError("Unsupported resource manifest")
+        purpose = value.get("purpose", "artifact")
+        if purpose not in {"artifact", "codex_home", "claude_home"}:
+            raise ValueError("Unsupported resource purpose")
+        try:
+            return cls(
+                UUID(value["root_id"]),
+                UUID(value["session_id"]),
+                UUID(value["resource_id"]),
+                cast(Literal["artifact", "codex_home", "claude_home"], purpose),
+            )
+        except ValueError:
+            raise ValueError("Invalid resource identity") from None
+
+    @property
+    def name(self) -> str:
+        return f"{self.session_id.hex}-{self.resource_id.hex}"

diffbutler/domain/review.py

@@ -0,0 +1,167 @@
+"""Immutable identities and source descriptions for background analysis; no I/O."""
+
+import hashlib
+import json
+from dataclasses import dataclass
+from datetime import datetime
+from enum import StrEnum
+from pathlib import PurePosixPath
+from uuid import UUID
+
+
+class RunStatus(StrEnum):
+    QUEUED = "queued"
+    RUNNING = "running"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+    STALE = "stale"
+
+
+class SessionStatus(StrEnum):
+    READY = "ready"
+    SUSPENDED = "suspended"
+    CLEANED = "cleaned"
+
+
+@dataclass(frozen=True)
+class SessionRecord:
+    id: UUID
+    task_id: UUID
+    reviewer_id: str
+    generation: int
+    display_name: str
+    backend_session_id: str | None
+    status: SessionStatus
+    created_at: datetime
+
+
+class Side(StrEnum):
+    BASE = "base"
+    HEAD = "head"
+
+
+@dataclass(frozen=True)
+class SourceFile:
+    """A repository-relative file at one of the reviewed revisions."""
+
+    path: str
+    side: Side
+
+    def __post_init__(self) -> None:
+        path = PurePosixPath(self.path)
+        if (
+            not self.path
+            or path.is_absolute()
+            or any(part in {"", ".", ".."} for part in self.path.split("/"))
+            or "\\" in self.path
+            or "\x00" in self.path
+        ):
+            raise ValueError("source path must be a normalized relative repository path")
+
+
+@dataclass(frozen=True)
+class ChangedFile:
+    path: str
+    old_path: str | None = None
+
+    def __post_init__(self) -> None:
+        SourceFile(self.path, Side.HEAD)
+        if self.old_path is not None:
+            SourceFile(self.old_path, Side.BASE)
+
+
+@dataclass(frozen=True)
+class AnalysisIdentity:
+    """Task identity includes the account and cycle; retries share a key."""
+
+    task_id: UUID
+    head_sha: str
+    reviewer_id: str
+    prompt_version: str
+    config_hash: str
+
+    def __post_init__(self) -> None:
+        if not all((self.head_sha, self.reviewer_id, self.prompt_version, self.config_hash)):
+            raise ValueError("analysis identity components must be nonempty")
+
+    @property
+    def key(self) -> str:
+        payload = json.dumps(
+            [
+                str(self.task_id),
+                self.head_sha,
+                self.reviewer_id,
+                self.prompt_version,
+                self.config_hash,
+            ],
+            separators=(",", ":"),
+            ensure_ascii=True,
+        )
+        return hashlib.sha256(payload.encode()).hexdigest()
+
+
+@dataclass(frozen=True)
+class ComparisonCheck:
+    base_sha: str
+    matches: bool
+
+
+class ComparisonChanged(Exception):
+    """The target moved while its comparison was being checked; recheck it."""
+
+
+class ReviewConflict(ValueError):
+    """The requested task or run no longer permits this action."""
+
+
+@dataclass(frozen=True)
+class RunRecord:
+    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
+    status: RunStatus
+    requested_at: datetime
+    started_at: datetime | None
+    finished_at: datetime | None
+    status_reason: str | None = None
+
+
+@dataclass(frozen=True)
+class RunClaim:
+    """Exclusive worker ownership, retained until the worker acknowledges exit."""
+
+    token: UUID
+    run: RunRecord
+
+
+@dataclass(frozen=True)
+class ReviewPolicy:
+    reviewer_ids: frozenset[str]
+    disabled_repositories: frozenset[str] = frozenset()
+
+
+@dataclass(frozen=True)
+class ReviewResultRecord:
+    """Captured result and retained analysis; no adapter or ORM objects cross stores."""
+
+    exit_code: int
+    stdout: bytes | None
+    stderr: bytes | None
+    document_json: str | None
+    parse_tier: str | None
+    error: str | None
+    notes: tuple[str, ...]
+    selected_indices: tuple[int, ...]
+    min_confidence: float
+    findings_threshold: str
+    anchors_json: str | None = None
+    anchor_base_sha: str | None = None
+    anchor_head_sha: str | None = None