holt-cli 0.1.0__py3-none-any.whl

holt/report.py

@@ -0,0 +1,157 @@
+"""The shared output shape.
+
+The baseline solution and the full pipeline must produce the same thing, or the
+comparison is not the same task. Both emit an Assessment; only the method of
+arriving at one differs.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+
+
+class Verdict(str, Enum):
+    """Deliberately three-valued.
+
+    A repository nobody has tried to contribute to is not the same as one that
+    turns contributors away, and flattening them would hide the distinction the
+    whole project is about. Saying so is a valid answer, not a failure.
+    """
+
+    VIABLE = "viable"
+    NOT_VIABLE = "not_viable"
+    INSUFFICIENT_EVIDENCE = "insufficient_evidence"
+
+
+# The verdict word alone tells a reader almost nothing. These say what it means
+# for the decision they are actually making.
+VERDICT_HEADLINES = {
+    Verdict.VIABLE: "Worth your time",
+    Verdict.NOT_VIABLE: "Not worth your time",
+    Verdict.INSUFFICIENT_EVIDENCE: "Not enough evidence to say",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class Claim:
+    """A statement with the evidence id that backs it.
+
+    Stage D drops any claim whose id does not resolve. A claim without a
+    resolvable id never reaches the reader.
+    """
+
+    text: str
+    evidence_id: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class EntryPoint:
+    """One suggested place to start, with the issue it points at.
+
+    Carried separately from `Claim` because it is a *suggestion* rather than a
+    statement of fact, and the two must not be rendered as if they had the same
+    standing. Claims are verified against evidence; this is a ranking whose
+    measured precision is printed next to it.
+    """
+
+    evidence_id: str
+    first_step: str
+    why: str = ""
+
+
+@dataclass(slots=True)
+class Assessment:
+    repo: str
+    verdict: Verdict
+    summary: str
+    claims: list[Claim] = field(default_factory=list)
+    method: str = "holt"
+    replayed: bool = False
+    entry_points: list[EntryPoint] = field(default_factory=list)
+    # Added, never replacing: `summary` still holds the prose. A reader deciding
+    # where to spend a week needs the answer before the reasoning, and the rules
+    # are printed because "which rule fired" is a question a chat answer cannot
+    # be asked.
+    bottom_line: str = ""
+    limits: str = ""
+    rules: list[str] = field(default_factory=list)
+    contributor_days: int = 7
+    # Rendered markdown lines from `holt.agent.landing`. Arithmetic over the file
+    # lists we already crawl; the model never sees or writes this section.
+    landing: list[str] = field(default_factory=list)
+    # The date evidence was cut at. Stated in the output because a reader cannot
+    # otherwise tell a quiet repository from one whose recent months were excluded.
+    as_of: datetime | None = None
+    # How many claims were removed before the reader saw them, by either check
+    # in Stage D. Carried so the report can tell two situations apart that look
+    # identical on the page: a run that found nothing to say, and a run whose
+    # every statement was thrown out. `psf/requests` was the second one, and it
+    # read like the first.
+    dropped_claims: int = 0
+    # The models that actually answered, in first-use order. Printed because the
+    # model-written sections degrade with the model behind them while the counts
+    # and the verdict do not, and a report that does not name its model leaves a
+    # reader unable to tell those two halves apart. On a replay these are the ids
+    # from the recording.
+    models: list[str] = field(default_factory=list)
+
+    def render(self) -> str:
+        lines = [f"# {self.repo}", ""]
+        if self.replayed:
+            lines += [
+                "> Replaying recorded model output. No model was called for this run.",
+                "",
+            ]
+        budget = f"for a contributor with {self.contributor_days} day"
+        budget += "" if self.contributor_days == 1 else "s"
+        lines += [f"**{VERDICT_HEADLINES[self.verdict]}** — {budget}.", ""]
+        if self.as_of:
+            lines += [f"*Evidence up to {self.as_of.date().isoformat()}.*", ""]
+        if not self.claims and self.dropped_claims:
+            # Above the prose, not below it. A reader who is told at the bottom
+            # of the page that nothing on it was backed has already read it.
+            lines += [
+                f"> **No claim in this report survived verification.** All "
+                f"{self.dropped_claims} were dropped: the evidence cited did not "
+                "resolve, or the thread did not say what the claim said. The "
+                "verdict and the counts below are computed without a model and "
+                "still stand; nothing written in prose here is backed by a "
+                "record you can check.",
+                "",
+            ]
+        if self.bottom_line:
+            lines += [self.bottom_line, ""]
+        if self.summary:
+            lines += ["## What the evidence shows", "", self.summary, ""]
+        if self.rules:
+            # The deterministic part, shown rather than described. `verdict.py`
+            # decided this and the prose above could not have changed it.
+            lines += ["## What decided it", ""]
+            lines += [f"- {rule}" for rule in self.rules]
+            lines.append("")
+        if self.limits:
+            lines += ["## What could not be determined", "", self.limits, ""]
+        if self.landing:
+            lines += self.landing + [""]
+        if self.claims:
+            lines += ["## Evidence", ""]
+            for claim in self.claims:
+                where = f" — `{claim.evidence_id}`" if claim.evidence_id else ""
+                lines.append(f"- {claim.text}{where}")
+        if self.entry_points:
+            # The disclaimer is emitted by the renderer, not by the caller, so
+            # there is no code path that prints a ranking without the number that
+            # says how well it works. A test holds this.
+            from holt.agent.entry import DISCLAIMER
+
+            lines += ["", "## Where to start", "", DISCLAIMER, ""]
+            for point in self.entry_points:
+                lines.append(f"- **{point.first_step}** — `{point.evidence_id}`")
+                if point.why:
+                    lines.append(f"  {point.why}")
+        lines += ["", f"*{self.method}*"]
+        if self.models:
+            lines += [f"*Model output from {', '.join(self.models)}.*"]
+        return "\n".join(lines).rstrip() + "\n"

holt/tui/animation.py

@@ -0,0 +1,84 @@
+"""Motion, kept to the two things it is actually good at.
+
+The rule this module exists to enforce: **animation reports state, or it does
+not run.** A spinner means work is happening right now and you cannot know how
+long it will take. A reveal means this line is new since you last looked. There
+is nothing here that decorates, pulses, bounces or draws attention to something
+that has not changed.
+
+That rules out the obvious temptation, a progress bar. The number of threads a
+stage will read is not known until it has read them, so a bar would have to
+invent a denominator, and a bar that fills at a rate unrelated to the work is a
+lie told smoothly.
+
+Everything can be switched off in one place. `HOLT_TUI_NO_ANIMATION=1` disables
+motion for people who do not want it, for terminals that render it badly, and
+for the tests — which assert on text and should not race a fade.
+"""
+
+from __future__ import annotations
+
+import os
+
+#: Braille dots. Eight frames, all the same width, no baseline jitter as it
+#: turns — the reason this shape is used everywhere rather than an ASCII
+#: pinwheel, which visibly wobbles.
+SPINNER_FRAMES = "⠋⠙⠹⠸⠼⠴⠦⠧"
+
+#: Fast enough to read as continuous, slow enough not to strobe.
+SPINNER_INTERVAL = 0.08
+
+#: A new line arrives at 40% opacity and comes up to full. Short: this is meant
+#: to be noticed peripherally, not watched.
+REVEAL_DURATION = 0.18
+REVEAL_FROM = 0.4
+
+#: Recent rows come in one after another rather than all at once, which makes a
+#: list read as a list. Capped so a long history does not turn into a slow
+#: cascade the user waits through.
+STAGGER_STEP = 0.03
+STAGGER_MAX = 0.18
+
+
+def enabled() -> bool:
+    return os.environ.get("HOLT_TUI_NO_ANIMATION", "") in ("", "0", "false", "False")
+
+
+def frame(tick: int) -> str:
+    return SPINNER_FRAMES[tick % len(SPINNER_FRAMES)]
+
+
+def reveal(widget, delay: float = 0.0) -> None:
+    """Bring a freshly mounted widget up from dim.
+
+    Silent about failure on purpose. Motion is the least important thing on the
+    screen; if a widget is gone before its animation starts, that is not worth
+    an exception in an interface whose job is to render an assessment.
+    """
+    if not enabled():
+        return
+    try:
+        widget.styles.opacity = REVEAL_FROM
+        widget.styles.animate(
+            "opacity", value=1.0, duration=REVEAL_DURATION, delay=delay
+        )
+    except Exception:  # noqa: BLE001 - never let decoration break a screen
+        try:
+            widget.styles.opacity = 1.0
+        except Exception:  # noqa: BLE001
+            pass
+
+
+def stagger(index: int) -> float:
+    """The delay for the nth item in a revealed list."""
+    return min(index * STAGGER_STEP, STAGGER_MAX)
+
+
+def elapsed(seconds: float) -> str:
+    """A running clock that never claims more precision than it has."""
+    if seconds < 10:
+        return f"{seconds:.1f}s"
+    if seconds < 60:
+        return f"{seconds:.0f}s"
+    minutes, rest = divmod(int(seconds), 60)
+    return f"{minutes}m{rest:02d}s"

holt/tui/app.py

@@ -0,0 +1,294 @@
+"""The application shell.
+
+It owns five things and nothing else: the screen registry, the global
+keybindings, the store of past assessments, the runs currently in flight, and
+the session being looked at. It contains no rendering and no engine knowledge,
+so a new view is a new file plus one line in `holt.tui.screens.REGISTRY`.
+
+Navigation is deliberately shallow. Home holds everything you have; a run or a
+stored result is one push deep; the evidence behind a claim is two. There is no
+state you can get into where the way back is unclear, because every screen binds
+escape to the thing above it.
+
+**A run belongs to the app, not to the screen watching it.** The pump that
+drains every in-flight session lives here and ticks whether or not anyone is
+looking, so walking away from a run leaves it running. It used to live on the
+live screen, which meant popping that screen stopped the only thing consuming
+the run's events: the worker thread carried on spending, its result was never
+absorbed, and the assessment it produced was silently thrown away. A run now
+ends for exactly one reason — it finished, it failed, or someone stopped it.
+"""
+
+from __future__ import annotations
+
+from textual.app import App
+from textual.await_complete import AwaitComplete
+from textual.screen import Screen
+
+from holt.cli import normalise
+from holt.tui import mascot, store, theme
+from holt.tui.commands import HoltCommands
+from holt.tui.screens import REGISTRY
+from holt.tui.screens.assessment import AssessmentScreen
+from holt.tui.screens.confirm import ConfirmScreen
+from holt.tui.screens.inspector import InspectorScreen
+from holt.tui.screens.live import LiveScreen
+from holt.tui.session import RunOptions, Session
+
+#: How often the app absorbs what the running sessions have emitted. The same
+#: interval the live screen redraws on: the screen renders what this has already
+#: collected, so a slower pump here would show as a laggy stream.
+PUMP_SECONDS = 0.05
+
+
+class HoltApp(App):
+    CSS = theme.CSS
+    SCREENS = REGISTRY
+    TITLE = "holt"
+
+    #: One provider, not a union with `App.COMMANDS`. It yields holt's commands
+    #: and then the framework's, so the order is written down rather than
+    #: decided by set iteration and a race between concurrent providers.
+    COMMANDS = {HoltCommands}
+
+    BINDINGS = [
+        ("ctrl+c", "quit", "quit"),
+        # `q` quits every screen that has no text box on it. Home does have
+        # one, and the input takes the key as a character, so a bare `q` never
+        # arrives there — which left the front screen as the only one in the
+        # app with no visible way out. `ctrl+q` works everywhere, including
+        # while you are typing, and being app-level it is on every footer.
+        ("ctrl+q", "quit", "quit"),
+    ]
+
+    def __init__(
+        self,
+        options: RunOptions | None = None,
+        assessments: store.Store | None = None,
+    ) -> None:
+        super().__init__()
+        #: Chosen once, at launch, and worn only by the cat and the masthead.
+        #: The colours that mean something -- verdict, evidence, drops -- are
+        #: fixed in `theme`, so a different accent each session changes how the
+        #: interface looks and never what it says.
+        self.accent = mascot.pick_accent()
+        self.store = assessments or store.Store()
+        #: Set when the interface was launched with a repository to assess.
+        #: Without one it opens on home, which is the ordinary case.
+        self.initial = options
+        self.session: Session | None = None
+        #: Runs in flight, keyed by repository. One run per repository: asking
+        #: for one that is already running reattaches to it rather than paying
+        #: twice for the same answer.
+        self.runs: dict[str, Session] = {}
+
+    def on_mount(self) -> None:
+        self.set_interval(PUMP_SECONDS, self.pump)
+        self.push_screen("home")
+        if self.initial is not None:
+            self.start_run(self.initial)
+
+    # ─── the pump ───────────────────────────────────────────────────────────
+
+    def pump(self) -> None:
+        """Absorb what every in-flight run has emitted, and keep its result.
+
+        Runs regardless of which screen is up. A session that has produced an
+        outcome is stored and unregistered here — never by a screen, because a
+        screen that has been popped cannot store anything.
+        """
+        for repo, session in list(self.runs.items()):
+            session.drain()
+            if session.finished:
+                self.remember(session)
+                self.runs.pop(repo, None)
+
+    @property
+    def in_flight(self) -> list[Session]:
+        """Runs that are still working, newest last."""
+        return [s for s in self.runs.values() if not s.finished]
+
+    def running_for(self, repo: str) -> Session | None:
+        return self.runs.get(normalise(repo))
+
+    # ─── navigation ─────────────────────────────────────────────────────────
+
+    def push_screen(self, screen, *args, **kwargs):
+        """Open a screen — or go back to it, when it is already open.
+
+        A screen opened by name is the *installed instance*: `push_screen(
+        "discover")` hands back the same object every time. Pushing one that is
+        already in the stack therefore puts a single `Screen` at two depths at
+        once, and that is not merely untidy. Every screen here is
+        `background: transparent`, so Textual renders the whole stack beneath
+        the current screen as its background — and a screen that appears twice
+        in that stack renders itself inside itself until Python runs out of
+        stack. The interface died with a `RecursionError` out of the
+        compositor, from a path as ordinary as ctrl+f, ctrl+o, and then "find a
+        repository" off the palette.
+
+        Going back to it is also what the key meant. `go_home` already pops
+        rather than pushing a second home, for the same reason: one screen, one
+        place in the stack.
+        """
+        open_already = self._open_already(screen)
+        if open_already is None:
+            return super().push_screen(screen, *args, **kwargs)
+        return self._return_to(open_already)
+
+    def _open_already(self, screen) -> Screen | None:
+        """The instance this push would open, if the stack already holds it.
+
+        Identity, not type. Two `AssessmentScreen`s are two reports and both
+        belong on the stack; what cannot happen is one object appearing twice.
+        """
+        if isinstance(screen, str):
+            try:
+                screen = self.get_screen(screen)
+            except KeyError:
+                return None
+        if not isinstance(screen, Screen):
+            return None
+        return screen if any(open_ is screen for open_ in self.screen_stack) else None
+
+    def _return_to(self, screen: Screen) -> AwaitComplete:
+        """Pop back down to a screen already open. A no-op if it is on top."""
+        popped: AwaitComplete | None = None
+        while self.screen is not screen and len(self.screen_stack) > 1:
+            popped = self.pop_screen()
+        return popped if popped is not None else AwaitComplete()
+
+    def start_run(self, options: RunOptions) -> None:
+        """Assess a repository, and watch it happen.
+
+        Reattaches if that repository is already being assessed. Two runs of the
+        same repository would produce two answers to one question, and on live
+        they would be paid for separately.
+        """
+        repo = normalise(options.repo)
+        existing = self.runs.get(repo)
+        if existing is not None:
+            self.watch_run(existing)
+            return
+        session = Session(options)
+        self.runs[repo] = session
+        self.session = session
+        session.start()
+        self.push_screen(LiveScreen())
+
+    def watch_run(self, session: Session) -> None:
+        """Reopen the live view on a run already in progress.
+
+        The screen rebuilds from the session's log, so a run joined half way
+        through shows everything it has done, not only what happens next.
+        """
+        self.session = session
+        self.push_screen(LiveScreen())
+
+    def open_stored(self, entry) -> None:
+        """Open an assessment that has already been produced. Nothing runs."""
+        self.session = Session.restored(entry)
+        self.push_screen(AssessmentScreen())
+
+    def show_assessment(self) -> None:
+        if self.session is not None and self.session.assessment is not None:
+            self.push_screen(AssessmentScreen())
+
+    def inspect(self, evidence_id: str) -> None:
+        """Resolve an id and show the record behind it.
+
+        The lookup goes through the session's own evidence — the provider the
+        run used, or, for an assessment reopened out of the store, the fixture
+        that run read, opened again. Either way the interface cannot show a
+        reader something Stage D did not have access to.
+
+        When there is nothing to look an id up in at all, the screen says that
+        and why, rather than claiming the id does not resolve — a very
+        different statement, and only one of them would be true.
+        """
+        session = self.session
+        record = session.resolve(evidence_id) if session else None
+        note = session.evidence_note if session else ""
+        self.push_screen(
+            InspectorScreen(
+                evidence_id,
+                record,
+                resolvable=not note,
+                note=note,
+                provenance=session.evidence_provenance if session else "",
+            )
+        )
+
+    def go_home(self) -> None:
+        """Back to the list, however deep the current screen is.
+
+        Leaves any run alone. Escape means "stop looking at this", never "stop
+        doing this" — stopping has its own key and its own confirmation.
+        """
+        # Home sits at index 1, above Textual's own base screen. Popping to
+        # exactly that leaves home on top however deep the stack got.
+        while len(self.screen_stack) > 2:
+            self.pop_screen()
+        home = self.screen
+        if hasattr(home, "refresh_entries"):
+            # Coroutine: scheduled rather than awaited, because the caller is a
+            # key binding and the list catching up a frame later is invisible.
+            home.call_later(home.refresh_entries)
+
+    # ─── stopping ───────────────────────────────────────────────────────────
+
+    def confirm_stop(self, session: Session) -> None:
+        """Ask before stopping. A stopped run keeps nothing it had computed."""
+        if session is None or session.finished:
+            return
+        self.push_screen(
+            ConfirmScreen(
+                f"stop {session.options.repo}?",
+                _spent(session),
+                yes="y stop",
+                no="n keep running",
+            ),
+            lambda confirmed: self._stop(session, bool(confirmed)),
+        )
+
+    def _stop(self, session: Session, confirmed: bool) -> None:
+        if confirmed:
+            session.cancel()
+
+    def action_quit(self) -> None:
+        """Quit, but never silently discard a run that is still working."""
+        running = self.in_flight
+        if not running:
+            self.exit()
+            return
+        detail = "   ".join(f"{s.options.repo} {_spent(s)}" for s in running)
+        self.push_screen(
+            ConfirmScreen(
+                f"{len(running)} run{'s' if len(running) > 1 else ''} still in flight",
+                f"{detail}\nquitting stops {'them' if len(running) > 1 else 'it'}.",
+                yes="y quit",
+                no="n go back",
+            ),
+            lambda confirmed: self.exit() if confirmed else None,
+        )
+
+    # ─── persistence ────────────────────────────────────────────────────────
+
+    def remember(self, session: Session) -> None:
+        """Keep a finished assessment so the next launch opens on it."""
+        entry = session.to_entry()
+        if entry is not None:
+            self.store.save(entry)
+
+
+def _spent(session: Session) -> str:
+    """Elapsed, and money if any was actually spent."""
+    minutes, seconds = divmod(int(session.duration), 60)
+    text = f"{minutes}:{seconds:02d}"
+    if session.cost_usd:
+        text += f"   ${session.cost_usd:.4f}"
+    return text
+
+
+def run(options: RunOptions | None = None) -> None:
+    HoltApp(options).run()

holt/tui/clipboard.py

@@ -0,0 +1,89 @@
+"""Getting the report out of the terminal and into somewhere it can be used.
+
+The assessment is markdown before it is anything else — `Assessment.render()`
+writes the file that `holt assess` produces — so what leaves here is that exact
+text, evidence ids and all. Copying a re-typeset version of a report would mean
+the thing you paste into an issue is not the thing the tool committed.
+
+Copying from a terminal is genuinely uncertain, and this module refuses to
+pretend otherwise. Two mechanisms, tried together:
+
+* **A local clipboard tool** (`wl-copy`, `pbcopy`, `xclip`, …). When one runs
+  successfully the text is definitely on the clipboard, and we can say so.
+* **OSC 52**, the escape sequence that asks the terminal emulator itself to take
+  the text. It is the only thing that works over ssh or inside tmux without a
+  local display, and it is also *unacknowledged* — the terminal may honour it,
+  ignore it, or have it switched off, and nothing comes back either way.
+
+So the caller is handed a sentence describing what actually happened rather than
+a boolean, and that sentence is shown to the user. "Copied" when a tool
+confirmed it; "asked your terminal to copy it" when only OSC 52 was available.
+Claiming success we cannot observe is the one thing not on offer.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+
+#: How long a clipboard tool may take before we give up on it and try the next.
+#: Generous for a local process, short enough that a wedged one does not hold
+#: the interface while somebody waits for a keypress to do something.
+TIMEOUT_S = 2.0
+
+
+#: name, argv, and the environment variable that has to be set for the tool to
+#: have anything to talk to. `wl-copy` outside a Wayland session and `xclip`
+#: with no `DISPLAY` both exist on a lot of machines and fail on all of them;
+#: skipping those is faster than timing them out.
+COMMANDS: tuple[tuple[str, tuple[str, ...], str], ...] = (
+    ("pbcopy", ("pbcopy",), ""),
+    ("wl-copy", ("wl-copy",), "WAYLAND_DISPLAY"),
+    ("xclip", ("xclip", "-selection", "clipboard"), "DISPLAY"),
+    ("xsel", ("xsel", "--clipboard", "--input"), "DISPLAY"),
+    ("clip.exe", ("clip.exe",), ""),
+)
+
+
+def native(text: str) -> str:
+    """Write to the system clipboard. Returns the tool that did it, or `""`."""
+    for name, argv, needs in COMMANDS:
+        if needs and not os.environ.get(needs):
+            continue
+        if shutil.which(argv[0]) is None:
+            continue
+        try:
+            subprocess.run(
+                argv,
+                input=text.encode(),
+                timeout=TIMEOUT_S,
+                check=True,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+        except (OSError, subprocess.SubprocessError):
+            continue
+        return name
+    return ""
+
+
+def copy(app, text: str) -> str:
+    """Put `text` on the clipboard, and say in words what actually happened.
+
+    Both mechanisms are used, not one as a fallback for the other. A local tool
+    reports success but only reaches the machine holt is running on; OSC 52
+    reports nothing but is the one that reaches the terminal you are sitting in
+    front of when that is somewhere else.
+    """
+    tool = native(text)
+    try:
+        app.copy_to_clipboard(text)
+    except Exception:  # noqa: BLE001 - never let a copy attempt close the report
+        pass
+    if tool:
+        return f"Copied as markdown ({tool})."
+    return (
+        "Asked your terminal to copy it as markdown (OSC 52). "
+        "Not every terminal honours that, and none of them say."
+    )