shikiru-cli 0.2.0__py3-none-any.whl

shikiru/workspace/base_refs.py

@@ -0,0 +1,160 @@
+"""Where task roots start from: the local or the verified fetched remote base."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Protocol
+
+from shikiru.errors import CommandFailed, CommandTimeoutError, ShikiruError
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from shikiru.workspace.git import Git
+
+BASE_REF_PREFIX = "refs/shikiru/bases/"
+_HEADS_PREFIX = "refs/heads/"
+_REMOTE_TRACKING_PREFIX = "refs/remotes/"
+_MISSING_REF_SHA = "0" * 40
+_DIVERGED_REASON = "it has local commits the remote base does not contain"
+_NOT_MOVED_REASON = "git left the branch where it was"
+
+
+class MergedBaseUnavailable(ShikiruError):
+    """A merged pull request's commit is not on the fetched remote base."""
+
+    def __init__(self, base: str, commit: str | None) -> None:
+        """Name the base and the merge commit that could not be verified on it."""
+        super().__init__(f"merge commit {commit} is not on the fetched remote base {base}")
+
+
+class BaseFetchFailed(ShikiruError):
+    """The remote base could not be fetched: the remote is unreachable or the fetch timed out."""
+
+    def __init__(self, base: str, remote: str, cause: ShikiruError) -> None:
+        """Name the `base` and `remote` and say why the fetch failed."""
+        super().__init__(f"cannot fetch {base} from {remote}: {cause}")
+
+
+class LocalBaseBlocked(ShikiruError):
+    """The local base branch cannot fast-forward to the remote tip without losing work."""
+
+    def __init__(self, base: str, tip: str, reason: str) -> None:
+        """Name the `base`, the remote `tip` it could not reach and why."""
+        super().__init__(f"local base {base} cannot fast-forward to {tip}: {reason}")
+
+
+class BaseRefs(Protocol):
+    """The single rule choosing the git ref a task root starts from."""
+
+    async def resolve(self, base: str) -> str:
+        """Return the ref new task roots of `base` start from and rebase onto."""
+        ...
+
+
+class LocalBaseRefs:
+    """`integration = "merge"`: work lands on the local base branch, so it is the ref."""
+
+    async def resolve(self, base: str) -> str:
+        """Return `base` itself."""
+        return base
+
+
+class FetchedBaseRefs:
+    """`integration = "pr"`: work lands on the remote base, which the engine fetches.
+
+    Every root starts from the freshly fetched remote base, so local commits that were never
+    pushed are not in it.
+    """
+
+    def __init__(self, git: Git, project_root: Path, remote: str, *, fetch_timeout: float) -> None:
+        """Fetch from `remote` into Shikiru's own refs of the repository at `project_root`.
+
+        A fetch that takes longer than `fetch_timeout` seconds fails.
+        """
+        self._git = git
+        self._project_root = project_root
+        self._remote = remote
+        self._fetch_timeout = fetch_timeout
+
+    async def resolve(self, base: str) -> str:
+        """Fetch the remote `base` and return the ref it was fetched into.
+
+        Raises `BaseFetchFailed` when the fetch fails: a root is never built from a stale ref.
+        """
+        return await self._fetch(base)
+
+    async def sync(self, base: str, merge_commit: str | None) -> str:
+        """Fetch the remote `base` and return its tip, once it contains `merge_commit`.
+
+        The fetch updates Shikiru's ref and the remote-tracking ref of `base`; the local branch
+        is advanced separately by `LocalBaseSync`. Raises `BaseFetchFailed` when the fetch fails
+        and `MergedBaseUnavailable` when the merge commit is missing or not on the base.
+        """
+        ref = await self._fetch(base)
+        tip = await self._git.rev_parse(self._project_root, ref)
+        if merge_commit is None or not await self._git.merge_base_is_ancestor(
+            self._project_root, merge_commit, tip
+        ):
+            raise MergedBaseUnavailable(base, merge_commit)
+        return tip
+
+    async def _fetch(self, base: str) -> str:
+        ref = f"{BASE_REF_PREFIX}{base}"
+        tracking_ref = f"{_REMOTE_TRACKING_PREFIX}{self._remote}/{base}"
+        try:
+            await self._git.fetch(
+                self._project_root,
+                self._remote,
+                f"+{_HEADS_PREFIX}{base}:{ref}",
+                f"+{_HEADS_PREFIX}{base}:{tracking_ref}",
+                timeout=self._fetch_timeout,
+            )
+        except (CommandFailed, CommandTimeoutError) as error:
+            raise BaseFetchFailed(base, self._remote, error) from error
+        return ref
+
+
+class LocalBaseSync:
+    """Moves the local base branch to the verified remote tip, and only fast-forwards it.
+
+    A checked-out base advances in its own worktree, so git refuses any merge that would
+    overwrite uncommitted work. A base that is not checked out moves by compare-and-swap, so a
+    concurrent change makes the update fail. A local base holding commits the remote tip lacks
+    is never moved.
+    """
+
+    def __init__(self, git: Git, project_root: Path) -> None:
+        """Advance the branches of the repository at `project_root` through `git`."""
+        self._git = git
+        self._project_root = project_root
+        self._lock = asyncio.Lock()
+
+    async def advance(self, base: str, tip: str) -> None:
+        """Point the local `base` at `tip`, or raise `LocalBaseBlocked` when that is not safe.
+
+        The move is verified: a base that does not reach `tip` raises rather than reporting
+        success. Idempotent: a base already at `tip` is left alone, so retries and restarts
+        are safe.
+        """
+        async with self._lock:
+            current = await self._git.local_branch_sha(self._project_root, base)
+            if current == tip:
+                return
+            if current is not None and not await self._git.merge_base_is_ancestor(
+                self._project_root, current, tip
+            ):
+                raise LocalBaseBlocked(base, tip, _DIVERGED_REASON)
+            try:
+                await self._move(base, tip, current)
+            except (CommandFailed, CommandTimeoutError) as error:
+                raise LocalBaseBlocked(base, tip, str(error)) from error
+            if await self._git.local_branch_sha(self._project_root, base) != tip:
+                raise LocalBaseBlocked(base, tip, _NOT_MOVED_REASON)
+
+    async def _move(self, base: str, tip: str, current: str | None) -> None:
+        checkouts = await self._git.branch_checkouts(self._project_root, base)
+        if checkouts:
+            await self._git.fast_forward_checked_out(checkouts[0], base, tip)
+            return
+        await self._git.update_ref(self._project_root, base, tip, current or _MISSING_REF_SHA)

shikiru/workspace/caches.py

@@ -0,0 +1,136 @@
+"""Copy-on-write cache cloning into a task worktree."""
+
+from __future__ import annotations
+
+import asyncio
+import platform
+import shutil
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+from uuid import uuid4
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from shikiru.process import SubprocessRunner
+
+_STAGING_SUFFIX = ".cache-staging"
+_PROBE_PREFIX = ".shikiru-cow-probe-"
+_PROBE_DIRECTORY_PREFIX = ".shikiru-cow-check-"
+_PROBE_CONTENT = b"shikiru cow probe"
+
+CACHE_COW_UNSUPPORTED_WARNING = (
+    "copy-on-write copy is not supported on this filesystem; caches were not cloned"
+)
+
+_MACOS_COW_ARGS = ("cp", "-c", "-R")
+_LINUX_COW_ARGS = ("cp", "-a", "--reflink=always")
+_COW_ARGS_BY_SYSTEM = {"Darwin": _MACOS_COW_ARGS, "Linux": _LINUX_COW_ARGS}
+
+
+def default_cow_args() -> tuple[str, ...] | None:
+    """Return this platform's copy-on-write `cp` invocation, or `None` if none is known."""
+    return _COW_ARGS_BY_SYSTEM.get(platform.system())
+
+
+@dataclass(frozen=True, slots=True)
+class CacheCloneResult:
+    """The outcome of one `CacheCloner.clone` call."""
+
+    copied: tuple[Path, ...] = field(default_factory=tuple)
+    warning: str | None = None
+
+
+async def _remove_tree(path: Path) -> None:
+    if path.exists():
+        await asyncio.to_thread(shutil.rmtree, path)
+
+
+class CacheCloner:
+    """Clone `repo.caches` globs that are git-ignored, copy-on-write, into a worktree."""
+
+    def __init__(
+        self, runner: SubprocessRunner, *, cow_args: Sequence[str] | None, copy_timeout: float
+    ) -> None:
+        """Copy with `cow_args` (the platform's copy-on-write `cp` invocation), via `runner`.
+
+        One copy that takes longer than `copy_timeout` seconds fails.
+
+        `cow_args` is `None` when this platform has no known copy-on-write `cp` invocation
+        (see `default_cow_args`); cloning then reports the filesystem as unsupported outright.
+        """
+        self._runner = runner
+        self._cow_args = tuple(cow_args) if cow_args is not None else None
+        self._copy_timeout = copy_timeout
+
+    async def clone(
+        self,
+        repo_dir: Path,
+        worktree_dir: Path,
+        cache_globs: Sequence[str],
+        ignored: Sequence[Path],
+    ) -> CacheCloneResult:
+        """Copy every ignored path in `repo_dir` matching `cache_globs` into `worktree_dir`.
+
+        Only paths that exist and are in `ignored` are copied. If this filesystem does not
+        support copy-on-write, nothing is copied and exactly one warning is returned. Each copy
+        is made beside the worktree and moved into place only once complete, so a destination
+        that exists is always whole; a failed, timed-out or cancelled copy leaves nothing behind.
+        """
+        cow_args = self._cow_args
+        if cow_args is None or not await self._cow_supported(cow_args, worktree_dir):
+            return CacheCloneResult(warning=CACHE_COW_UNSUPPORTED_WARNING)
+        ignored_set = set(ignored)
+        copied: list[Path] = []
+        staging = worktree_dir.with_name(f"{worktree_dir.name}{_STAGING_SUFFIX}")
+        await _remove_tree(staging)
+        try:
+            for pattern in cache_globs:
+                for match in sorted(repo_dir.glob(pattern)):
+                    if match not in ignored_set or not match.exists():
+                        continue
+                    relative = match.relative_to(repo_dir)
+                    destination = worktree_dir / relative
+                    if destination.exists():
+                        continue
+                    staged = staging / relative
+                    staged.parent.mkdir(parents=True, exist_ok=True)
+                    await self._copy(cow_args, match, staged)
+                    destination.parent.mkdir(parents=True, exist_ok=True)
+                    staged.replace(destination)
+                    copied.append(relative)
+        finally:
+            await _remove_tree(staging)
+        return CacheCloneResult(copied=tuple(copied))
+
+    async def check_support(self, filesystem_root: Path) -> bool:
+        """Check copy-on-write using disposable probe files on `filesystem_root`."""
+        if self._cow_args is None:
+            return False
+        with tempfile.TemporaryDirectory(
+            prefix=_PROBE_DIRECTORY_PREFIX, dir=filesystem_root
+        ) as directory:
+            return await self._cow_supported(self._cow_args, Path(directory))
+
+    async def _cow_supported(self, cow_args: tuple[str, ...], worktree_dir: Path) -> bool:
+        probe_source = worktree_dir / f"{_PROBE_PREFIX}{uuid4().hex}"
+        probe_destination = worktree_dir / f"{_PROBE_PREFIX}{uuid4().hex}-copy"
+        probe_source.write_bytes(_PROBE_CONTENT)
+        try:
+            result = await self._runner.run(
+                [*cow_args, str(probe_source), str(probe_destination)],
+                timeout=self._copy_timeout,
+            )
+        finally:
+            probe_source.unlink(missing_ok=True)
+            probe_destination.unlink(missing_ok=True)
+        return result.returncode == 0
+
+    async def _copy(self, cow_args: tuple[str, ...], source: Path, destination: Path) -> None:
+        await self._runner.run(
+            [*cow_args, str(source), str(destination)],
+            timeout=self._copy_timeout,
+            check=True,
+        )

shikiru/workspace/facts.py

@@ -0,0 +1,118 @@
+"""Git facts for `facts.md`, outranking the Implementer's claims."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from shikiru.domain.briefing import (
+    FACTS_COMMITS_HEADING,
+    FACTS_DIFF_STAT_HEADING,
+    FACTS_NONE_MARKER,
+)
+from shikiru.domain.results import LiveWork
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+    from shikiru.domain.tasks import RepoState
+    from shikiru.workspace.git import Git
+
+_HEAD_REF = "HEAD"
+
+
+@dataclass(frozen=True, slots=True)
+class WorkspaceFacts:
+    """The facts computed for a task's worktree."""
+
+    head_branch: str | None = None
+    commits: tuple[str, ...] = field(default_factory=tuple)
+    diff_stat: str = ""
+    status: tuple[str, ...] = field(default_factory=tuple)
+    changed_trackers: tuple[str, ...] = field(default_factory=tuple)
+
+
+DETACHED_HEAD = "a detached HEAD"
+OFF_BRANCH_ISSUE = (
+    "The workspace is on {actual}, not its task branch {branch}, so its commits "
+    "({commits}) would never be integrated. Bring that work onto {branch}, switch back to it "
+    "and stay on it."
+)
+
+
+def describe_off_branch(branch: str, head_branch: str | None, commits: Sequence[str]) -> str:
+    """Describe a worktree whose `HEAD` is not on `branch`, naming the commits at risk."""
+    return OFF_BRANCH_ISSUE.format(
+        actual=head_branch or DETACHED_HEAD,
+        branch=branch,
+        commits="; ".join(commits) or "none ahead of the base",
+    )
+
+
+def render_facts(facts: WorkspaceFacts) -> str:
+    """Render `facts` as the markdown text a `verify`/`conflicts`/`handoff` prompt embeds.
+
+    These facts outrank the Implementer's claims, so they carry no interpretation, only the
+    raw `git` output `GitFacts.collect` gathered.
+    """
+    lines = [FACTS_COMMITS_HEADING]
+    lines.append("\n".join(facts.commits) if facts.commits else FACTS_NONE_MARKER)
+    lines.append(FACTS_DIFF_STAT_HEADING)
+    lines.append(facts.diff_stat or FACTS_NONE_MARKER)
+    lines.append("### git status --porcelain")
+    lines.append("\n".join(facts.status) if facts.status else "(clean)")
+    lines.append("### Changed trackers")
+    lines.append(", ".join(facts.changed_trackers) if facts.changed_trackers else "(none)")
+    return "\n\n".join(lines)
+
+
+class GitFacts:
+    """Computes `WorkspaceFacts` for a task's worktree, from real git state."""
+
+    def __init__(self, git: Git) -> None:
+        """Read git state through `git`."""
+        self._git = git
+
+    async def collect(
+        self, task_root: Path, repo: RepoState, trackers: Sequence[str]
+    ) -> WorkspaceFacts:
+        """Collect facts for the worktree at `task_root`, checked out as `repo`."""
+        head_branch = await self._git.head_branch(task_root)
+        diff_range = f"{repo.base_ref}...HEAD"
+        commits = await self._git.log_oneline(task_root, f"{repo.base_ref}..HEAD")
+        diff_stat = await self._git.diff_stat(task_root, diff_range)
+        status = await self._git.status_porcelain(task_root)
+        changed_paths = set(await self._git.diff_name_only(task_root, diff_range))
+        return WorkspaceFacts(
+            head_branch=head_branch,
+            commits=tuple(commits),
+            diff_stat=diff_stat,
+            status=tuple(status),
+            changed_trackers=tuple(tracker for tracker in trackers if tracker in changed_paths),
+        )
+
+
+class TaskWorkObserver:
+    """Reads a task's live work from its worktree, as it is now rather than as recorded."""
+
+    def __init__(self, git: Git) -> None:
+        """Read git state through `git`."""
+        self._git = git
+
+    async def observe(self, task_root: Path, base_ref: str) -> LiveWork:
+        """Return the commits past `base_ref` and the changes of `task_root` against their base.
+
+        Tracked edits, staged or not, are counted once against the merge base of `base_ref` and
+        `HEAD`, so committed work is never counted twice. Untracked and binary files count as
+        files, but contribute no line counts, because git gives none for them.
+        """
+        merge_base = await self._git.merge_base(task_root, base_ref, _HEAD_REF)
+        commits = await self._git.log_oneline(task_root, f"{base_ref}..{_HEAD_REF}")
+        changes = await self._git.working_tree_line_changes(task_root, against=merge_base)
+        return LiveWork.from_oneline(
+            commits,
+            files=changes.changed_paths,
+            insertions=changes.added_lines,
+            deletions=changes.deleted_lines,
+        )