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

semantic_code_review/augment/progress.py

@@ -0,0 +1,223 @@
+"""Per-hunk progress meter, rendered to stderr in truecolor TTYs.
+
+Shows a single redrawn line:
+
+    overview ✓  hunks 7/24  ●●●●●●●■■····  03s
+
+Each in-flight hunk is one block character coloured by elapsed time —
+cyan when fresh, yellow around 15 s, red past ~30 s. A 429 retry sleep
+naturally pushes a hunk's elapsed time higher, so the colour reflects
+back-pressure without us having to attribute httpx events to the
+right concurrent hunk.
+
+Completed hunks fade from green to dim grey over a couple of seconds
+but stay visible so the cumulative progress impression is preserved.
+
+Disabled when stderr isn't a TTY, when the terminal doesn't advertise
+truecolor, or when the caller passes `enabled=False` (we use this to
+suppress the meter under `--verbose`, where it would fight the log
+stream).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import os
+import sys
+import time
+import types
+from dataclasses import dataclass
+from typing import Self, TextIO
+
+# ANSI helpers ---------------------------------------------------------------
+
+ESC = "\x1b["
+HIDE_CURSOR = ESC + "?25l"
+SHOW_CURSOR = ESC + "?25h"
+CLEAR_LINE = ESC + "2K"
+RESET = ESC + "0m"
+DIM = ESC + "2m"
+
+
+def _rgb(r: int, g: int, b: int) -> str:
+    return f"{ESC}38;2;{r};{g};{b}m"
+
+
+def _lerp(a: tuple[int, int, int], b: tuple[int, int, int], t: float) -> tuple[int, int, int]:
+    return (
+        int(a[0] + (b[0] - a[0]) * t),
+        int(a[1] + (b[1] - a[1]) * t),
+        int(a[2] + (b[2] - a[2]) * t),
+    )
+
+
+# Heat curve stops. Cool when fresh, hot when stale.
+COOL = (96, 200, 240)  # cyan
+WARM = (240, 200, 80)  # yellow
+HOT = (240, 80, 60)  # red
+
+DONE_FRESH = (100, 220, 120)  # green
+DONE_FADED = (90, 90, 90)  # dim grey
+FAILED = (220, 80, 60)  # red
+
+HEAT_FULL_SECONDS = 30.0  # ~p99 hunk latency target.
+DONE_FADE_SECONDS = 4.0  # how long a closed square stays prominent.
+
+
+def _heat_color(heat: float) -> tuple[int, int, int]:
+    """Heat ∈ [0,1] → RGB along COOL → WARM → HOT."""
+    h = max(0.0, min(1.0, heat))
+    if h < 0.5:
+        return _lerp(COOL, WARM, h * 2)
+    return _lerp(WARM, HOT, (h - 0.5) * 2)
+
+
+def is_truecolor_tty(stream: TextIO | None = None) -> bool:
+    """True if `stream` is a TTY *and* the terminal advertises truecolor.
+
+    Uses the de-facto-standard `COLORTERM=truecolor|24bit` signal, plus
+    a fallback for terminals known to support it but inconsistent about
+    advertising (kitty, alacritty, iTerm).
+    """
+    s = stream if stream is not None else sys.stderr
+    if not getattr(s, "isatty", lambda: False)():
+        return False
+    if os.environ.get("NO_COLOR"):
+        return False
+    colorterm = os.environ.get("COLORTERM", "").lower()
+    if colorterm in ("truecolor", "24bit"):
+        return True
+    term = os.environ.get("TERM_PROGRAM", "") or os.environ.get("TERM", "")
+    return any(t in term.lower() for t in ("kitty", "alacritty", "iterm"))
+
+
+@dataclass
+class _HunkState:
+    started: float | None = None
+    finished: float | None = None
+    ok: bool = True
+
+
+class ProgressMeter:
+    """Live per-hunk progress meter. Render-only; safe to drive from
+    one asyncio loop.
+    """
+
+    def __init__(
+        self,
+        total: int,
+        *,
+        stream: TextIO | None = None,
+        enabled: bool | None = None,
+    ) -> None:
+        self.total = total
+        self.stream = stream if stream is not None else sys.stderr
+        self.enabled = is_truecolor_tty(self.stream) if enabled is None else enabled
+        self.start_time = time.monotonic()
+        self.hunks: list[_HunkState] = [_HunkState() for _ in range(total)]
+        self.overview_started: float | None = None
+        self.overview_finished: float | None = None
+        self.overview_ok: bool = True
+        self._task: asyncio.Task | None = None
+
+    # ---- lifecycle -------------------------------------------------------
+
+    async def __aenter__(self) -> Self:
+        if self.enabled:
+            self.stream.write(HIDE_CURSOR)
+            self.stream.flush()
+            self._task = asyncio.create_task(self._tick())
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: types.TracebackType | None,
+    ) -> None:
+        if self._task is not None:
+            self._task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._task
+        if self.enabled:
+            # One final paint with current state, then advance to the
+            # next line so any subsequent stderr writes don't overwrite.
+            self._render()
+            self.stream.write("\n" + SHOW_CURSOR)
+            self.stream.flush()
+
+    async def _tick(self) -> None:
+        try:
+            while True:
+                self._render()
+                await asyncio.sleep(0.25)
+        except asyncio.CancelledError:
+            return
+
+    # ---- events ----------------------------------------------------------
+
+    def start_overview(self) -> None:
+        self.overview_started = time.monotonic()
+
+    def finish_overview(self, ok: bool = True) -> None:
+        self.overview_finished = time.monotonic()
+        self.overview_ok = ok
+
+    def start_hunk(self, idx: int) -> None:
+        if 0 <= idx < self.total:
+            self.hunks[idx].started = time.monotonic()
+
+    def finish_hunk(self, idx: int, ok: bool = True) -> None:
+        if 0 <= idx < self.total:
+            self.hunks[idx].finished = time.monotonic()
+            self.hunks[idx].ok = ok
+
+    # ---- render ----------------------------------------------------------
+
+    def render_line(self) -> str:
+        """Build the line as it would be drawn. Public for testing."""
+        now = time.monotonic()
+        parts: list[str] = []
+
+        # Overview indicator.
+        if self.overview_finished is not None:
+            mark = "✓" if self.overview_ok else "✗"
+            parts.append(f"overview {mark}")
+        elif self.overview_started is not None:
+            r, g, b = _heat_color((now - self.overview_started) / HEAT_FULL_SECONDS)
+            parts.append(f"overview {_rgb(r, g, b)}■{RESET}")
+        else:
+            parts.append(f"overview {DIM}·{RESET}")
+
+        # Hunks.
+        done = sum(1 for h in self.hunks if h.finished is not None)
+        squares: list[str] = []
+        for h in self.hunks:
+            if h.finished is not None:
+                if h.ok:
+                    fade = max(0.0, min(1.0, (now - h.finished) / DONE_FADE_SECONDS))
+                    r, g, b = _lerp(DONE_FRESH, DONE_FADED, fade)
+                    squares.append(f"{_rgb(r, g, b)}■{RESET}")
+                else:
+                    squares.append(f"{_rgb(*FAILED)}■{RESET}")
+            elif h.started is not None:
+                r, g, b = _heat_color((now - h.started) / HEAT_FULL_SECONDS)
+                squares.append(f"{_rgb(r, g, b)}■{RESET}")
+            else:
+                squares.append(f"{DIM}·{RESET}")
+        parts.append(f"hunks {done}/{self.total}  {''.join(squares)}")
+
+        elapsed = int(now - self.start_time)
+        parts.append(f"{elapsed:02d}s")
+        return "  ".join(parts)
+
+    def _render(self) -> None:
+        if not self.enabled:
+            return
+        # \r + clear-line + line. No trailing newline (we redraw in place).
+        self.stream.write(f"\r{CLEAR_LINE}{self.render_line()}")
+        self.stream.flush()
+
+
+__all__ = ["ProgressMeter", "is_truecolor_tty"]

semantic_code_review/augment/prompts.py

@@ -0,0 +1,93 @@
+"""System prompts for the two LLM passes.
+
+Bump `PROMPT_VERSION` when a prompt changes — the cache layer keys on
+it so a bump forces a full re-run.
+
+The wire format the model emits is constrained by the Pydantic models
+in `schemas.py` (`OverviewSubmission`, `HunkAnnotations`) via
+pydantic-ai's `output_type=ToolOutput(...)`. The prompts describe
+*what* fields to populate; the schema enforces *how* they're shaped.
+"""
+
+from __future__ import annotations
+
+from .schemas import SMELL_TAGS_TEXT
+
+PROMPT_VERSION = "p11"
+
+
+OVERVIEW_SYSTEM = (
+    "You are preparing a structured overview of a pull request (or a local diff) to "
+    "help a human reviewer understand its shape at a glance.\n\n"
+    "You receive the PR title and body, a diffstat, and the hunk headers of each "
+    "changed file (no bodies), each numbered by its `hunk_index` within its file. "
+    "Produce a concise overview.\n\n"
+    "Guidelines:\n"
+    "- Lead with WHY, not WHAT.\n"
+    "- Symbol kinds are: function, method, class, constant.\n"
+    "- If the user prompt has a `# Symbols changed` section, it is a deterministic "
+    "  parse of what actually changed. Populate `symbols_added`/`symbols_modified`/"
+    "  `symbols_removed` from it verbatim — that list is ground truth; do not invent, "
+    "  drop, or rename entries. With no such section, infer symbols from the hunk "
+    "  headers as before.\n"
+    "- `callgraph_edges` are introduced or modified calls (best-effort — omit if unsure).\n"
+    "- `themes` are short keyword tags (e.g. 'pagination', 'api-surface').\n"
+    "- Per-file `summary` is one sentence; `lang` only when the extension is ambiguous.\n"
+    "- `files` must include one entry per changed file in the diff.\n"
+    "- Favour clarity over completeness: the reviewer uses this to decide where to look.\n"
+    "- If the PR body contains a specification markdown block (look for a `# Spec` "
+    "  heading or similar), treat it as GROUND TRUTH for what the change was meant to "
+    "  accomplish. Call out in `summary` and `themes` any parts of the spec that look "
+    "  under-implemented, not implemented at all, or diverged from. Do not invent spec "
+    "  requirements that aren't in the body.\n\n"
+    "Groups — semantic clusters for reviewer navigation:\n"
+    "- Aim for 2–6 groups on a typical PR; larger changes can justify more. A group "
+    "  should represent ONE concrete purpose (e.g. 'annotation arrow geometry', "
+    "  'node toolchain setup'), not a whole file or a whole theme.\n"
+    "- A hunk can appear in multiple groups when it genuinely serves multiple "
+    "  purposes. Don't force every hunk into a group — a hunk that stands alone is "
+    "  fine and should simply be omitted.\n"
+    "- Cite members by `{path, hunk_index}` using the indices shown in the "
+    "  `# Hunk headers` section of the user prompt.\n"
+    "- Titles are lowercase noun phrases, ≤ 6 words, no trailing period.\n"
+    "- `rationale` is one sentence naming what the grouped hunks together accomplish. "
+    "  Not the mechanics — the reviewer already sees the hunks.\n"
+)
+
+
+HUNK_SYSTEM = (
+    "You are reviewing one hunk of a pull request. Your FIRST job is to help a human "
+    "reviewer UNDERSTAND what this change does and why. Critique (smells, risks) is "
+    "SECONDARY — only raise concerns when you can name a concrete risk.\n\n"
+    "BEFORE ANYTHING ELSE: read the hunk body. The full `- ...` / `+ ...` diff is in "
+    "the user prompt. Your `intent` must name what the hunk ACTUALLY does, grounded "
+    "in what you see — not what it plausibly does given the file path or header. "
+    "If the hunk is one line, quote the before/after tokens. If you're unsure, call "
+    "tools (`read_file`, `read_file_at`, `grep`). If you're still unsure after using "
+    "tools, lower `confidence` below 50 and state the exact missing piece in "
+    "`context`. Never write 'likely', 'probably', 'appears to', 'seems to', "
+    "'looks like' — those are signals you're guessing from the header instead of "
+    "reading the body or investigating.\n\n"
+    "You have tools to read other files in the head worktree and at the base SHA, to "
+    "grep, to list directories, and to check git history. Use them when the hunk depends "
+    "on code outside the diff; skip them if the hunk is self-contained.\n\n"
+    "Populate the following fields:\n"
+    "- `intent`: 1-2 sentences. MOTIVE, not mechanics. Name the exact change (what was "
+    "X, is now Y), not 'probably'. Bad: 'one-line tweak to the compose file (likely an "
+    "image bump)'. Good: 'bumps the postgres image tag from 15.3 to 15.5'.\n"
+    "- `segments`: when the hunk contains semantically distinct edits (e.g. a refactor "
+    "plus an unrelated fix, or a changed if-branch alongside a new else-branch), split "
+    "them. Each segment has POST-IMAGE `new_start`/`new_count` and its own intent. Omit "
+    "segments if the hunk is single-intent.\n"
+    "- `smells`: list of {tag, note}. Tags are from the closed vocabulary: "
+    f"{SMELL_TAGS_TEXT}. Attach each smell to a segment when it's segment-local, or to the "
+    "hunk when it spans the whole change.\n"
+    "- `context`: cross-file dependencies the reviewer can't see from the diff.\n"
+    "- `refs`: {path, line, reason} for other files the reviewer should look at.\n"
+    "- `confidence`: 0-100 integer. Low is fine and honest.\n"
+    "- `line_notes`: {line, body} for notes too specific for intent. `line` is post-image.\n\n"
+    "Fold-region summaries (indent-based collapsed blocks inside the diff) are NOT "
+    "produced here — the review server fires a focused one-shot call for each region "
+    "the reviewer actually collapses. Leave `fold_descriptions` empty.\n\n"
+    "Tone: explanatory, not evaluative. Comprehension first."
+)