semantic-code-review 0.24.2__py3-none-any.whl

semantic_code_review/review/pr_flow.py

@@ -0,0 +1,299 @@
+"""End-to-end GitHub PR review flow: resolve → fetch → serve → post.
+
+Drives `scr pr`: preflights ``gh``, resolves the PR number (picker or
+explicit), materialises a run directory, optionally runs the augment
+pipeline, serves the viewer until the reviewer is done. Posting is
+confirmed in the **viewer's modal**, not on the terminal — the
+reviewer reviews comments inline, clicks Done, ticks/unticks the
+final list, and confirms. The server fires the post callback on
+their behalf and reports the result back via ``ServeResult.posted``.
+
+The legacy terminal y/N flow lives behind ``--yes`` only as a way to
+skip the modal entirely: the server stays out of posting mode and
+the CLI posts after the viewer exits.
+
+The flow uses plain ``sys.stderr`` / ``sys.stdout`` for I/O so it's
+testable without a Typer dependency. ``cli/pr.py`` is the CLI wrapper
+that builds a :class:`PrFlowOptions` from command-line args and calls
+:func:`run_pr_flow`.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ..augment.agents import Client
+from ..fetch import GhFetchError, materialize_github_pr_run, preflight_gh
+from .comments import CommentStore, format_markdown
+from .github import (
+    GhError,
+    PostResult,
+    comments_to_github,
+    list_review_requested_prs,
+    pick_pr_interactive,
+)
+from .github_graphql import post_review_via_graphql
+from .runner import (
+    _build_console_task,
+    _build_fold_summary_task,
+    serve_review,
+)
+from .server import PostCallable
+
+
+@dataclass(frozen=True)
+class PrFlowOptions:
+    """All inputs the PR flow needs.
+
+    ``model`` and ``client`` are caller-resolved (typically via the CLI's
+    config + backend selection); ``extra_review_prompt`` is the
+    already-resolved prompt text (None means none). ``yes`` bypasses the
+    in-browser confirmation modal — the viewer's Done button stays a
+    plain exit and the CLI posts everything after it returns.
+    """
+
+    repo: str
+    number: int | None
+    runs_root: Path
+    augment: bool
+    model: str
+    concurrency: int
+    no_cache: bool
+    cache_dir: Path | None
+    open_browser: bool
+    port: int
+    timeout: int
+    extra_review_prompt: str | None
+    client: Client | None
+    yes: bool
+
+
+def run_pr_flow(opts: PrFlowOptions) -> int:
+    """Drive the PR review end-to-end. Returns the exit code.
+
+    Exit codes:
+      0 — review completed cleanly (no unresolved local comments).
+      1 — graceful user-abort (no PR picked, posting cancelled, etc.).
+      2 — error condition: missing ``gh``, fetch failed, post failed,
+          or review completed with unresolved local comments.
+    """
+    try:
+        preflight_gh()
+    except GhFetchError as e:
+        _err(f"scr pr: {e}")
+        return 2
+
+    number = opts.number
+    if number is None:
+        code, picked = _resolve_pr_number(opts.repo)
+        if picked is None:
+            return code or 1
+        number = picked
+
+    pr_url = f"https://github.com/{opts.repo}/pull/{number}"
+    try:
+        run_dir = materialize_github_pr_run(pr_url, opts.runs_root)
+    except GhFetchError as e:
+        _err(f"scr pr: {e}")
+        return 2
+
+    meta = json.loads((run_dir / "meta.json").read_text(encoding="utf-8"))
+    head_sha = meta.get("headRefOid", "")
+    if not head_sha:
+        _err("scr pr: meta.json is missing headRefOid; can't anchor review")
+        return 2
+
+    augment_task, fold_summary_task, console_task = _build_tasks(opts, run_dir)
+    if not opts.augment:
+        # Mirror cli/review.py's behaviour: copy raw → augmented so render
+        # has something to parse when augment is skipped.
+        (run_dir / "augmented.diff").write_text(
+            (run_dir / "raw.diff").read_text(encoding="utf-8"),
+            encoding="utf-8",
+        )
+
+    # `--yes` skips the modal entirely — server stays out of posting
+    # mode (Done = plain /exit) and the CLI does the post itself after
+    # serve_review returns. Default mode wires the callback + meta so
+    # the viewer's Done opens the confirm modal.
+    post_callback: PostCallable | None = None
+    post_meta: dict[str, Any] | None = None
+    if not opts.yes:
+        post_callback = _build_post_callback(opts.repo, number, run_dir)
+        post_meta = {
+            "repo": opts.repo,
+            "number": number,
+            "head_sha": head_sha,
+        }
+
+    result = serve_review(
+        run_dir,
+        augment=augment_task,
+        fold_summary=fold_summary_task,
+        console=console_task,
+        post=post_callback,
+        post_meta=post_meta,
+        port=opts.port,
+        timeout=opts.timeout,
+        open_browser=opts.open_browser,
+    )
+
+    posted: PostResult | None = result.posted
+
+    # CLI-side fallback for --yes: the server didn't post (we didn't
+    # wire it for that), so post everything ourselves now.
+    if posted is None and opts.yes:
+        mapped = comments_to_github(result.comments)
+        if not mapped:
+            _err(f"scr pr: no new local comments to post; comments are in {run_dir / 'comments.json'}.")
+            return 0 if result.clean else 2
+        try:
+            posted = post_review_via_graphql(opts.repo, number, mapped)
+        except GhError as e:
+            _err(f"scr pr: posting failed: {e}")
+            _err(f"comments are still in {run_dir / 'comments.json'} — re-run with --no-augment to retry.")
+            return 2
+
+    if posted is not None:
+        # Comments are on GitHub; the URL is the artefact. Keep stdout
+        # minimal so a slash command (or any downstream LLM) doesn't
+        # ingest the comment bodies and treat them as instructions.
+        sys.stdout.write(f"# Posted to {posted.review_url}\n")
+        word = "comment" if posted.posted == 1 else "comments"
+        sys.stdout.write(f"_{posted.posted} {word} posted._\n")
+        sys.stdout.flush()
+        _err(f"scr pr: posted {posted.posted} comment(s) — {posted.review_url}")
+        return 0 if result.clean else 2
+
+    # No post happened — modal cancelled, tab closed, --no-augment with
+    # no comments, etc. Dump the markdown so the user / a calling script
+    # has a record of what was being reviewed.
+    local_comments = [c for c in result.comments if c.source == "local"]
+    sys.stdout.write(format_markdown(local_comments, run_slug=run_dir.name))
+    sys.stdout.flush()
+    return 0 if result.clean else 2
+
+
+def _resolve_pr_number(repo: str) -> tuple[int | None, int | None]:
+    """Pick a PR number when the caller didn't supply one.
+
+    Returns ``(exit_code, number)``: on success ``(None, picked)``; on
+    a graceful early exit ``(code, None)`` so the caller can return
+    the code.
+    """
+    try:
+        prs = list_review_requested_prs(repo)
+    except GhError as e:
+        _err(f"scr pr: {e}")
+        return 1, None
+    if not prs:
+        _err(
+            f"scr pr: no open PRs in {repo} are requesting your review. "
+            "Pass an explicit PR number, or open the list on github.com."
+        )
+        return 1, None
+    if len(prs) == 1:
+        _err(f"scr pr: reviewing {repo}#{prs[0].number} — {prs[0].title}")
+        return None, prs[0].number
+    picked = pick_pr_interactive(repo, prs)
+    if picked is None:
+        _err("scr pr: no PR selected")
+        return 1, None
+    return None, picked
+
+
+def _build_tasks(
+    opts: PrFlowOptions,
+    run_dir: Path,
+) -> tuple[Callable | None, Callable | None, Callable | None]:
+    """Build the augment + fold-summary + console closures, or ``(None,
+    None, None)`` when augmentation is skipped (the console grounds its
+    answers in the augment sidecar, so it's unavailable without it).
+    """
+    if not opts.augment:
+        return None, None, None
+
+    # Imports inside: anthropic SDK + augment pipeline are lazy-loaded so
+    # `--no-augment` runs (and `scr --help`) don't pay the cost.
+    from ..augment.pipeline import augment_run_dir
+    from ..augment.prompts import PROMPT_VERSION
+    from ..cache.store import CacheStore
+
+    cache = (
+        None
+        if opts.no_cache
+        else CacheStore(
+            root=opts.cache_dir,
+            prompt_version=PROMPT_VERSION,
+        )
+    )
+
+    async def augment_task(rd: Path, publish: Callable[[str, dict[str, Any]], None]) -> None:
+        await augment_run_dir(
+            rd,
+            model=opts.model,
+            concurrency=opts.concurrency,
+            cache=cache,
+            client=opts.client,
+            extra_review_prompt=opts.extra_review_prompt,
+            # Page carries the progress display now; suppress the
+            # terminal meter to avoid duplicate noise and to keep
+            # the listening-URL / warning lines unobstructed.
+            show_progress=False,
+            on_event=publish,
+        )
+
+    fold_summary_task = _build_fold_summary_task(
+        client=opts.client,
+        model=opts.model,
+        cache=cache,
+        run_dir=run_dir,
+    )
+    # Console reuses the augment backend (SDK streams; CLI answers
+    # one-shot). When opts.client is None augment defaults to the
+    # Anthropic SDK, so mirror that for the console's client.
+    console_client = opts.client or Client(model=f"anthropic:{opts.model}")
+    console_task = _build_console_task(client=console_client, run_dir=run_dir)
+    return augment_task, fold_summary_task, console_task
+
+
+def _build_post_callback(
+    repo: str,
+    number: int,
+    run_dir: Path,
+) -> PostCallable:
+    """Closure the server fires on /post-review.
+
+    Reads the latest comments off ``comments.json`` (the store mutates
+    throughout the session), keeps every local comment whose id is in
+    ``selected_ids`` plus every non-local comment (needed for reply-
+    parent ``node_id`` lookups in :func:`comments_to_github`), maps,
+    and posts via GraphQL. Errors propagate; the server returns 500
+    to the modal so the reviewer sees the failure and can retry.
+    """
+
+    def post(selected_ids: list[str]) -> PostResult:
+        store = CommentStore(run_dir / "comments.json")
+        all_comments = store.all()
+        selected = set(selected_ids)
+        filtered = [c for c in all_comments if c.source != "local" or c.id in selected]
+        mapped = comments_to_github(filtered)
+        return post_review_via_graphql(repo, number, mapped)
+
+    return post
+
+
+def _err(msg: str) -> None:
+    """Write ``msg`` to stderr, appending a newline if missing, then flush."""
+    if not msg.endswith("\n"):
+        msg = msg + "\n"
+    sys.stderr.write(msg)
+    sys.stderr.flush()
+
+
+__all__ = ["PrFlowOptions", "run_pr_flow"]

semantic_code_review/review/runner.py

@@ -0,0 +1,407 @@
+"""Orchestrate a ``scr review`` session end-to-end.
+
+Given a git ref/range and optional spec markdown, synthesise a run
+directory compatible with the existing augment + render pipeline,
+optionally run the LLM augmentation, render the HTML, spawn the
+ephemeral server, and drain reviewer comments to stdout when the
+viewer signals done.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import sys
+import threading
+import webbrowser
+from collections.abc import Callable, Coroutine
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from ..augment.agents import Client
+from ..augment.prompts import PROMPT_VERSION
+from ..cache.store import CacheStore
+from ..fetch import materialize_local_diff_run
+from ..format.parse import parse_augmented_diff
+from ..paths import default_runs_root as _default_runs_root
+from ..viewer.build_json import build_pending_viewer_json, build_viewer_json
+from .comments import CommentStore, format_markdown
+from .github import PostResult
+from .server import PostCallable, ReviewServer
+
+log = logging.getLogger(__name__)
+
+
+#: Signature of the augment callable accepted by ``serve_review``. The
+#: second argument is the publisher bound to the live review server's
+#: SSE channel; pass it through to ``augment_run_dir(on_event=...)`` so
+#: the pipeline can stream overview / per-hunk events to the page.
+AugmentCallable = Callable[
+    [Path, Callable[[str, dict], None]],
+    Coroutine[Any, Any, None],
+]
+
+
+#: Signature of the on-demand fold-summary callable accepted by
+#: ``serve_review``. The closure resolves the sidecar, calls the LLM
+#: against the addressed file, persists the new ``FoldDescription``,
+#: and returns the broadcast payload (the dict the server fans out as
+#: an SSE event and sends back to the requesting tab). Wired up only
+#: when an LLM backend is available (``opts.augment is True``);
+#: ``--no-augment`` reviews leave this at ``None`` and the route
+#: returns 409 unconditionally.
+FoldSummaryCallable = Callable[
+    # (file_idx, context, right_range, left_range, qualified_name, kind)
+    [
+        int,
+        str,
+        "tuple[int, int] | None",
+        "tuple[int, int] | None",
+        "str | None",
+        "str | None",
+    ],
+    Coroutine[Any, Any, dict],
+]
+
+
+#: Signature of the streaming console turn driver accepted by
+#: ``serve_review``. Called as ``(question, history, on_delta, on_tool,
+#: cancel)`` and awaited to ``(answer_text, new_history)``:
+#: ``on_delta(str)`` / ``on_tool(str)`` stream text and tool activity,
+#: ``cancel`` is the ``threading.Event`` the driver polls between
+#: chunks. Wired only when augmentation runs on an SDK backend;
+#: ``--no-augment`` and CLI-subprocess reviews leave this ``None`` and
+#: /console/ask 409s (CLI support is Slice 5).
+ConsoleCallable = Callable[
+    [
+        str,
+        "list | None",
+        "Callable[[str], None]",
+        "Callable[[str], None]",
+        "threading.Event",
+    ],
+    Coroutine[Any, Any, "tuple[str, list]"],
+]
+
+
+@dataclass
+class ReviewOptions:
+    spec: str  # git ref or range, user-supplied
+    spec_markdown: Path | None = None
+    runs_root: Path = field(default_factory=_default_runs_root)
+    repo_root: Path | None = None
+    no_staged: bool = False
+    no_unstaged: bool = False
+    augment: bool = True
+    model: str = "claude-opus-4-7"
+    concurrency: int = 8
+    no_cache: bool = False
+    cache_dir: Path | None = None
+    open_browser: bool = True
+    port: int = 0
+    timeout: int = 3600
+    # Optional preselected backend handle. None → augment_run_dir
+    # defaults to a `Client` for the Anthropic SDK path.
+    client: Client | None = None
+    # Optional file-loaded text for the extra-review pass. When set,
+    # each hunk gets a second LLM call with this as the system prompt;
+    # the returned line-anchored notes merge into hunk.line_notes.
+    extra_review_prompt: str | None = None
+    show_progress: bool = True
+
+
+def run_review(opts: ReviewOptions) -> int:
+    """Run a full review session. Returns the process exit code."""
+    run_dir = materialize_local_diff_run(
+        opts.spec,
+        opts.runs_root,
+        repo_root=opts.repo_root,
+        no_staged=opts.no_staged,
+        no_unstaged=opts.no_unstaged,
+        spec_md_path=opts.spec_markdown,
+    )
+
+    augment_task: AugmentCallable | None = None
+    fold_summary_task: FoldSummaryCallable | None = None
+    console_task: ConsoleCallable | None = None
+    if opts.augment:
+        from ..augment.pipeline import augment_run_dir  # lazy: anthropic SDK
+
+        cache = None if opts.no_cache else CacheStore(root=opts.cache_dir, prompt_version=PROMPT_VERSION)
+
+        async def _run_augment(rd: Path, publish: Callable[..., None]) -> None:
+            await augment_run_dir(
+                rd,
+                model=opts.model,
+                concurrency=opts.concurrency,
+                cache=cache,
+                client=opts.client,
+                extra_review_prompt=opts.extra_review_prompt,
+                # The page now carries the progress display, so silence
+                # the terminal meter — its redraw line would just fight
+                # the listening-URL / per-hunk warning log lines.
+                show_progress=False,
+                on_event=publish,
+            )
+
+        augment_task = _run_augment
+
+        fold_summary_task = _build_fold_summary_task(
+            client=opts.client,
+            model=opts.model,
+            cache=cache,
+            run_dir=run_dir,
+        )
+
+        # The console reuses the augment backend — SDK backends stream
+        # token-by-token, CLI subprocess backends answer one-shot per turn
+        # (ADR 0002, Slice 5). When opts.client is None the augment path
+        # defaults to the Anthropic SDK, so we mirror that to construct
+        # the console's client.
+        console_client = opts.client or Client(model=f"anthropic:{opts.model}")
+        console_task = _build_console_task(
+            client=console_client,
+            run_dir=run_dir,
+        )
+    else:
+        # When augment is skipped, copy raw.diff to augmented.diff so render
+        # has something to parse. It'll have no annotations.
+        (run_dir / "augmented.diff").write_text(
+            (run_dir / "raw.diff").read_text(encoding="utf-8"),
+            encoding="utf-8",
+        )
+
+    result = serve_review(
+        run_dir,
+        augment=augment_task,
+        fold_summary=fold_summary_task,
+        console=console_task,
+        port=opts.port,
+        timeout=opts.timeout,
+        open_browser=opts.open_browser,
+    )
+    # The markdown dump is the reviewer's "new notes" feed — ingested
+    # upstream comments are already on GitHub and would crowd it out.
+    local_comments = [c for c in result.comments if c.source == "local"]
+    markdown = format_markdown(local_comments, run_slug=run_dir.name)
+    sys.stdout.write(markdown)
+    sys.stdout.flush()
+    return 0 if result.clean else 2
+
+
+@dataclass
+class ServeResult:
+    """Outcome of `serve_review`. Returned in addition to the side
+    effect of `comments.json` on disk so callers don't have to re-load
+    it (and so each caller can decide what to do with the comments —
+    `scr review` prints markdown, `scr pr` posts to GitHub).
+
+    ``posted`` is set when the viewer's confirmation modal fired a
+    successful /post-review (only possible when the caller supplied a
+    ``post`` callback to ``serve_review``). None means "no post
+    happened" — cancelled, no postable comments, or the caller wasn't
+    in posting mode at all.
+    """
+
+    comments: list  # list[Comment] — kept loose to avoid an import cycle
+    clean: bool  # True iff the viewer signalled Done within the timeout
+    posted: PostResult | None = None
+
+
+def serve_review(
+    run_dir: Path,
+    *,
+    augment: AugmentCallable | None = None,
+    fold_summary: FoldSummaryCallable | None = None,
+    console: ConsoleCallable | None = None,
+    post: PostCallable | None = None,
+    post_meta: dict | None = None,
+    port: int = 0,
+    timeout: int = 3600,
+    open_browser: bool = True,
+    on_ready: Callable[[str], None] | None = None,
+) -> ServeResult:
+    """Render the viewer for a populated run dir, host the back-channel
+    server, block on the user clicking Done, and return the comments
+    they left.
+
+    Both `cli.review` (local diff) and `cli.pr` (GitHub PR) call this
+    with a run dir whose `meta.json`, `raw.diff`, and worktrees are
+    already in place. If ``augment`` is supplied, the server starts
+    immediately with a pending viewer (file/hunk structure visible,
+    no annotations yet); the augmentation coroutine then runs while
+    the page is live, publishing per-hunk SSE events as completions
+    land. After the pass finishes, `update_viewer_json` swaps the
+    `/data.json` payload to the augmented state and a `done` event
+    flushes any still-pending placeholders. If ``augment`` is None,
+    the run dir is expected to already contain ``augmented.diff``
+    (the caller skipped augmentation upstream).
+    """
+    if augment is not None:
+        # Pre-augment: a file/hunk skeleton so the page is responsive
+        # while the LLM pass runs. The viewer JS sees `pending: true`
+        # and shows "analysing…" placeholders for each hunk.
+        viewer_json = build_pending_viewer_json(run_dir)
+    else:
+        viewer_json = _load_viewer_json(run_dir)
+    srv = ReviewServer(
+        run_dir=run_dir,
+        viewer_json=viewer_json,
+        port=port,
+        post_callback=post,
+        post_meta=post_meta,
+    )
+    srv.start()
+    try:
+        log.info("review server at %s", srv.url())
+        sys.stderr.write(f"scr review: listening on {srv.url()}\n")
+        sys.stderr.flush()
+        if on_ready is not None:
+            on_ready(srv.url())
+        if open_browser:
+            try:
+                webbrowser.open(srv.url())
+            except Exception as e:  # noqa: BLE001
+                log.warning("could not open browser: %s", e)
+
+        if augment is not None:
+            # Run augmentation while the server is live, streaming each
+            # overview / per-hunk completion to the page via SSE. After
+            # the pass returns, swap `/data.json` to the augmented state
+            # so any tab opened post-augment (or a manual reload) sees
+            # the final view, then publish `done` so connected viewers
+            # can finalise any still-pending placeholders.
+            augment_error: BaseException | None = None
+            try:
+                asyncio.run(augment(run_dir, srv.publish))
+            except BaseException as e:
+                augment_error = e
+                log.exception("augmentation failed; page stays on pending view")
+                sys.stderr.write(f"scr review: augment failed: {e}\n")
+            if (run_dir / "augmented.diff").exists():
+                final_json = _load_viewer_json(run_dir)
+                srv.update_viewer_json(final_json)
+                # Augmentation has emitted a sidecar, so the /fold-summary
+                # route can now resolve hunk_ids. Bind the summariser here
+                # rather than at start() to prevent races against a tab
+                # that opens before augmentation lands.
+                if fold_summary is not None:
+                    srv.set_fold_summariser(fold_summary)
+                # Same gate as the fold summariser: the console needs the
+                # sidecar on disk to ground its answers, so bind it here
+                # rather than at start(). Unset for --no-augment / CLI
+                # backends, where /console/ask stays 409.
+                if console is not None:
+                    srv.set_console_asker(console)
+                srv.publish("done", {"reason": "augment-complete"})
+            if augment_error is not None and not isinstance(augment_error, Exception):
+                # KeyboardInterrupt / SystemExit shouldn't be swallowed —
+                # re-raise after the page has its latest state pushed.
+                raise augment_error
+
+        clean = srv.wait_until_done(timeout=timeout)
+    finally:
+        srv.stop()
+
+    store = CommentStore(run_dir / "comments.json")
+    return ServeResult(
+        comments=store.all(),
+        clean=clean,
+        posted=srv.ctx.posted_result,
+    )
+
+
+def _build_fold_summary_task(
+    *,
+    client: Client | None,
+    model: str,
+    cache: CacheStore | None,
+    run_dir: Path,
+) -> FoldSummaryCallable:
+    """Construct the FoldSummaryCallable that ``serve_review`` installs
+    onto the review server once augmentation completes. The closure
+    captures the LLM backend + cache + run_dir so the server module
+    stays independent of the augment-side machinery.
+    """
+    # Lazy import: keeps the SDK / pydantic-ai dep out of the
+    # `--no-augment` path.
+    from ..augment.fold_summary import apply_fold_summary_to_run
+
+    async def task(
+        file_idx: int,
+        context: str,
+        right_range: tuple[int, int] | None,
+        left_range: tuple[int, int] | None,
+        qualified_name: str | None = None,
+        kind: str | None = None,
+    ) -> dict:
+        # client is None only when augment is False; in that path
+        # serve_review never wires this task up, so a None here would
+        # be a wiring bug — fail loudly.
+        assert client is not None, "fold-summary task called without an LLM backend"
+        return await apply_fold_summary_to_run(
+            client,
+            run_dir=run_dir,
+            file_idx=file_idx,
+            context=context,  # type: ignore[arg-type]
+            right_range=right_range,
+            left_range=left_range,
+            qualified_name=qualified_name,
+            kind=kind,
+            model=model,
+            cache=cache,
+        )
+
+    return task
+
+
+def _build_console_task(
+    *,
+    client: Client,
+    run_dir: Path,
+) -> ConsoleCallable:
+    """Construct the console turn driver ``serve_review`` installs once
+    augmentation completes. Captures the LLM backend + run_dir so the
+    server module stays independent of the augment-side machinery.
+    """
+    # Lazy import: keeps pydantic-ai off the `--no-augment` path.
+    from ..augment.console import stream_console_turn
+
+    async def task(
+        question: str,
+        history: list | None,
+        on_delta: Callable[[str], None],
+        on_tool: Callable[[str], None],
+        cancel: threading.Event,
+        selection: Any = None,
+    ) -> tuple[str, list]:
+        return await stream_console_turn(
+            client,
+            run_dir=run_dir,
+            question=question,
+            history=history,
+            on_delta=on_delta,
+            on_tool=on_tool,
+            cancel=cancel,
+            selection=selection,
+        )
+
+    return task
+
+
+def _load_viewer_json(run_dir: Path) -> dict:
+    meta = json.loads((run_dir / "meta.json").read_text(encoding="utf-8"))
+    augmented = run_dir / "augmented.diff"
+    if not augmented.exists():
+        return {"version": "1", "pr": {}, "files": []}
+    diff = parse_augmented_diff(augmented.read_text(encoding="utf-8"))
+    head_dir = run_dir / "head"
+    base_dir = run_dir / "base"
+    return build_viewer_json(
+        diff,
+        meta,
+        head_dir=head_dir if head_dir.exists() else None,
+        base_dir=base_dir if base_dir.exists() else None,
+    )