holt-cli 0.1.0__py3-none-any.whl

holt/tui/widgets/disclosure.py

@@ -0,0 +1,121 @@
+"""The tool's negative result about itself, and the ranking it qualifies.
+
+The reading order Holt prints was measured against the comparators that could
+make it unnecessary, and it did not beat them. That measurement is displayed
+here, above the ranking, in full.
+
+Three deliberate choices, because how this is presented is the claim:
+
+* **It is not an error.** No red, no warning icon. It is a considered disclosure
+  and it is styled like the rest of the prose, set off by a quiet rail.
+* **It is not collapsed.** There is no key to press to reveal it. A caveat filed
+  behind a keystroke is a caveat filed where nobody looks.
+* **It gets more room than the ranking.** The four precision figures are a table
+  rather than a sentence, because the point is that they sit on top of each
+  other, and a table shows that in one glance where prose hides it.
+
+Every number comes from `holt.agent.entry.MEASURED`, the same constant the
+report renders and the harness regenerates. There are no figures typed into this
+file, so the interface cannot drift from the measurement.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.text import Text
+from textual.app import ComposeResult
+from textual.widget import Widget
+
+from holt.agent.entry import MEASURED
+from holt.tui import theme
+from holt.tui.widgets.evidence import cite
+from holt.tui.visual import Line
+
+
+#: Display names for the comparators, in the order they are shown. Ours first,
+#: because the honest reading is "this one, against the ones that beat it".
+COMPARATORS: tuple[tuple[str, str], ...] = (
+    ("this ranking", "holt"),
+    ("good first issue", "good_first_issue"),
+    ("recency", "recency"),
+    ("random", "random"),
+)
+
+
+class MeasuredResult(Widget):
+    def compose(self) -> ComposeResult:
+        precision = MEASURED.get("precision_at_3", {})
+        repos = MEASURED.get("repositories")
+        issues = MEASURED.get("issues_ranked")
+        low, high = MEASURED.get("paired_ci_vs_label", (0.0, 0.0))
+        p_value = MEASURED.get("sign_test_p")
+        unlabelled = MEASURED.get("repos_with_no_labelled_issue")
+
+        yield Line(
+            Text(
+                "This ranking is not measurably better than picking at random.",
+                style="bold",
+            ),
+            classes="measured-lede",
+        )
+        yield Line(
+            f"Measured over {repos} repositories and {issues:,} issues held out "
+            "before the cutoff."
+        )
+        yield Line("")
+
+        for label, key in COMPARATORS:
+            if key not in precision:
+                continue
+            row = Text()
+            row.append(f"  {label:<20}", style="" if key == "holt" else theme.DIM)
+            row.append(f"{precision[key]:.3f}", style="" if key == "holt" else theme.DIM)
+            yield Line(row, classes="measured-row")
+
+        yield Line("")
+        yield Line(
+            f"Differences well inside noise — paired 95% CI [{low:+.2f}, {high:+.2f}], "
+            f"sign test p = {p_value}."
+        )
+        yield Line("")
+        yield Line(
+            f"Printed anyway because {unlabelled} of those {repos} repositories had no "
+            "beginner-labelled issue at all, so on half of them there is no free "
+            "signal to lose to. Read it as a reading order, not a recommendation."
+        )
+        yield Line("")
+        check = Text()
+        check.append("Check it yourself:  ", style=theme.DIM)
+        check.append("uv run python eval/pathfinder_harness.py --replay")
+        yield Line(check, classes="measured-check")
+
+
+class EntryPointRow(Widget):
+    """One suggested starting point.
+
+    Numbered, because here the order is the content — it is a reading order, and
+    the number is the only thing the ranking actually asserts. Nothing else in
+    the interface is a sequence, so nothing else is numbered.
+    """
+
+    def __init__(self, index: int, point: Any, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self.index = index
+        self.point = point
+
+    def compose(self) -> ComposeResult:
+        head = Text()
+        head.append(f"{self.index}  ", style=theme.FAINT)
+        head.append(" ".join(self.point.first_step.split()))
+        yield Line(head)
+
+        row = Text("   ")
+        row.append_text(cite(self.point.evidence_id, width=60))
+        yield Line(row)
+
+        if self.point.why:
+            yield Line(
+                Text(" ".join(self.point.why.split()), style=theme.FAINT),
+                classes="entry-why",
+            )

holt/tui/widgets/evidence.py

@@ -0,0 +1,121 @@
+"""Rendering an evidence id, and the record behind it.
+
+An evidence id is the load-bearing element of the whole report: a claim with one
+that resolves is checkable, and a claim without one never reaches the reader. So
+it gets the only underline in the interface, and the difference between resolving
+and not resolving is visible without reading a word.
+
+Ids are rendered through Rich `Text` spans rather than console markup. Ids
+contain brackets, colons and hashes, and markup would either mangle them or, at
+worst, let a repository name inject styling into the interface.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.text import Text
+from textual.app import ComposeResult
+from textual.widget import Widget
+
+from holt.tui import theme
+from holt.tui.visual import Line
+
+
+def elide(evidence_id: str, width: int) -> str:
+    """Shorten an id from the middle, never from the end.
+
+    Ids look like `pr:owner/name#172481:opened`. The owner and name repeat on
+    every row and the part that identifies the record — the number and the
+    event — is at the end, so cutting the tail would remove the only thing worth
+    reading. The middle goes instead.
+    """
+    if len(evidence_id) <= width:
+        return evidence_id
+    if width <= 3:
+        return evidence_id[:width]
+    keep_tail = max(width * 2 // 3, 1)
+    keep_head = width - keep_tail - 1
+    if keep_head <= 0:
+        return "…" + evidence_id[-(width - 1) :]
+    return evidence_id[:keep_head] + "…" + evidence_id[-keep_tail:]
+
+
+def cite(
+    evidence_id: str,
+    resolves: bool = True,
+    width: int | None = None,
+    repo: str | None = None,
+) -> Text:
+    """One evidence id, styled by whether the provider can resolve it.
+
+    Inside a report about a single repository the `owner/name` in every id is
+    the same, and on a long slug it crowds out the part that differs. Passing
+    `repo` folds it to an ellipsis for display. The inspector always shows the
+    id in full, so nothing is hidden from anyone checking a claim.
+    """
+    shown = evidence_id
+    if repo and repo in shown:
+        shown = shown.replace(repo, "…", 1)
+    if width:
+        shown = elide(shown, width)
+    style = f"{theme.CITE} underline" if resolves else f"{theme.DROP} strike"
+    return Text(shown, style=style, no_wrap=True, overflow="ellipsis")
+
+
+class EvidenceDetail(Widget):
+    """The record an id resolves to: where it came from, when, and what it says.
+
+    Renders whatever payload the record carries rather than a fixed set of
+    fields, because payloads differ by source and a hardcoded list would quietly
+    hide anything new.
+    """
+
+    def __init__(self, record: Any, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self.record = record
+
+    def compose(self) -> ComposeResult:
+        record = self.record
+        if record is None:
+            yield Line(
+                Text(
+                    "This id does not resolve. Stage D removed the claim that cited it.",
+                    style=theme.DROP,
+                ),
+                classes="empty",
+            )
+            return
+
+        yield Line(cite(record.evidence_id))
+        yield Line(
+            Text(f"{record.source} · {record.timestamp.isoformat()}", style=theme.FAINT),
+            classes="record-meta",
+        )
+        yield Line(
+            Text(record.url, style=theme.FAINT, no_wrap=True, overflow="ellipsis"),
+            classes="record-meta",
+        )
+        yield Line("")
+        for key, value in record.payload.items():
+            yield Line(_field(key, value))
+
+    @staticmethod
+    def _noop() -> None:  # pragma: no cover - placeholder for future actions
+        return None
+
+
+def _field(key: str, value: Any) -> Text:
+    text = Text()
+    text.append(f"{key:<17}", style=theme.DIM)
+    if isinstance(value, list):
+        for i, item in enumerate(value[:8]):
+            if i:
+                text.append("\n" + " " * 17)
+            text.append(str(item))
+        if len(value) > 8:
+            text.append("\n" + " " * 17)
+            text.append(f"+{len(value) - 8} more", style=theme.FAINT)
+    else:
+        text.append(str(value))
+    return text

holt/tui/widgets/masthead.py

@@ -0,0 +1,122 @@
+"""The cat, and the masthead it leads.
+
+Two widgets. `Cat` is one line that can be dropped anywhere — a masthead, a
+status bar, a chrome row — and changes mood when the run does. `Masthead` is the
+home screen's opening: the cat, the tool's own description of itself, and the
+three facts worth knowing before you type.
+
+The launch reveal is deliberately short. It exists to make the screen feel like
+it arrived rather than blinked into being, and it is over in about a quarter of
+a second. It never takes the keyboard: the input is focused from the first
+frame, so typing straight over the top of it works and the animation simply
+stops. An intro you have to sit through is a worse thing than no intro.
+"""
+
+from __future__ import annotations
+
+from rich.text import Text
+from textual.app import ComposeResult
+from textual.containers import Horizontal, Vertical
+from textual.widget import Widget
+
+from holt.tui import animation, mascot, theme
+from holt.tui.visual import Line
+
+
+def _version() -> str:
+    """The installed version, or nothing. Never a guess and never a crash."""
+    try:
+        from importlib.metadata import version
+
+        return version("holt")
+    except Exception:  # noqa: BLE001 - a masthead is not worth an exception
+        return ""
+
+
+class Cat(Widget):
+    """One line of cat. Blinks at rest, looks about while a run is going."""
+
+    def __init__(self, mood: str = "idle", **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._mood = mood
+        self._tick = 0
+        self._timer = None
+
+    def on_mount(self) -> None:
+        self._paint()
+        if animation.enabled():
+            self._timer = self.set_interval(mascot.TICK, self._advance)
+
+    def on_unmount(self) -> None:
+        self._stop()
+
+    def _stop(self) -> None:
+        if self._timer is not None:
+            self._timer.stop()
+            self._timer = None
+
+    def set_mood(self, mood: str) -> None:
+        if mood == self._mood:
+            return
+        self._mood = mood
+        # Restart the cycle so a mood change reads immediately rather than
+        # arriving part-way through the previous one's blink.
+        self._tick = 0
+        self._paint()
+
+    def _advance(self) -> None:
+        self._tick += 1
+        self._paint()
+
+    def _paint(self) -> None:
+        cycle = mascot.frames(self._mood)
+        frame = cycle[self._tick % len(cycle)] if animation.enabled() else cycle[0]
+        self.update(Text(frame, style=self.app.accent))
+
+    def update(self, renderable) -> None:
+        # `Cat` is a plain Widget so it can own a timer; rendering goes through
+        # the same conversion every other line uses.
+        self._renderable = renderable
+        self.refresh()
+
+    def render(self):
+        from holt.tui.visual import visual
+
+        return visual(getattr(self, "_renderable", ""))
+
+
+class Masthead(Widget):
+    def compose(self) -> ComposeResult:
+        with Horizontal(id="masthead"):
+            yield Cat(id="cat")
+            with Vertical(id="masthead-text"):
+                title = Text("holt", style="bold")
+                if _version():
+                    # Not a bare repeat of the title bar two lines above: the
+                    # version is the one thing here the chrome does not say.
+                    title.append(f"  {_version()}", style=theme.FAINT)
+                yield Line(title, id="masthead-title", classes="masthead-name")
+                yield Line(
+                    Text(mascot.TAGLINE, style=theme.DIM), id="masthead-tagline"
+                )
+                yield Line("")
+                for index, fact in enumerate(mascot.FACTS):
+                    yield Line(
+                        Text(f"· {fact}", style=theme.FAINT),
+                        id=f"masthead-fact-{index}",
+                        classes="masthead-fact",
+                    )
+
+    def on_mount(self) -> None:
+        """Reveal, briefly. Everything is already on screen and readable if
+        motion is off, so this only ever adds, never gates."""
+        if not animation.enabled():
+            return
+        for index, widget in enumerate(self.query(Line)):
+            animation.reveal(widget, delay=animation.stagger(index))
+
+    def set_mood(self, mood: str) -> None:
+        try:
+            self.query_one("#cat", Cat).set_mood(mood)
+        except Exception:  # noqa: BLE001 - the cat is never load-bearing
+            pass

holt/tui/widgets/recent.py

@@ -0,0 +1,167 @@
+"""The list of assessments you already have.
+
+Each row answers the three questions you actually have when you reopen the tool:
+what did it say, how old is it, and how was it produced. The verdict carries the
+only colour, because it is the only thing on the row you might act on.
+
+Age is shown on every row without exception. A stored assessment that does not
+say how old it is, is indistinguishable from a fresh one, and this list exists
+precisely so that nothing has to be re-run to be re-read.
+
+Runs still in flight appear in the same list, above the stored ones, marked and
+updating in place. They belong here rather than on a screen of their own for the
+same reason the stored ones do: the question on opening holt is "what is going
+on with the things I care about", and an answer split across two screens is one
+you have to go looking for. The gutter is two columns wide on every row so the
+two kinds line up under each other instead of drifting apart.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.text import Text
+from textual.widgets import ListItem, ListView
+
+from holt.report import VERDICT_HEADLINES, Verdict
+from holt.tui import store, theme
+from holt.tui.visual import Line
+from holt.tui.widgets.scrolling import KeepsHighlightVisible
+
+#: Every row starts with this many columns, so a running row and a stored one
+#: put their repository names in the same place.
+GUTTER = 2
+
+#: The mark on a run in flight. A filled dot rather than a spinner: the row is
+#: one line in a list, and a list of spinners is a light show.
+RUNNING_MARK = "●"
+
+
+#: Wide enough for the longest verdict the engine actually has, computed rather
+#: than guessed. It was hardcoded to 22, and "Not enough evidence to say" is 26,
+#: so that row rendered as "Not enough evidence to say8 hours ago".
+HEADLINE_WIDTH = max(len(h) for h in VERDICT_HEADLINES.values()) + 2
+
+
+def headline(verdict: Verdict) -> str:
+    """The engine's own words for a verdict, not a second vocabulary.
+
+    `holt.report` owns these. A verdict this build has not seen falls back to
+    its raw value rather than raising, so the list keeps working across an
+    engine that grows a fourth answer.
+    """
+    try:
+        return VERDICT_HEADLINES[verdict]
+    except (KeyError, TypeError):
+        return str(getattr(verdict, "value", verdict)).replace("_", " ")
+
+
+class RecentRow(ListItem):
+    def __init__(self, entry: Any, width_hint: int = 78, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self.entry = entry
+        self.width_hint = width_hint
+
+    def compose(self):
+        entry = self.entry
+        verdict = entry.assessment.verdict
+        value = getattr(verdict, "value", str(verdict))
+
+        row = Text()
+        row.append(" " * GUTTER)
+        row.append(f"{_repo(entry.repo):<32}", style="")
+        row.append(
+            f"{headline(verdict):<{HEADLINE_WIDTH}}",
+            style=theme.verdict_colour(value),
+        )
+        row.append(f"{store.describe_age(entry.age_seconds):<14}", style=theme.FAINT)
+        row.append(entry.mode, style=theme.FAINT)
+        yield Line(row)
+
+
+def _repo(repo: str, width: int = 31) -> str:
+    """Elide the owner first, then the name. The name is what you recognise.
+
+    `Sistema-de-certificacion-academica/Sistema-de-certificacion-academica`
+    truncated from the right is all owner and no name, which is the one part
+    that distinguishes it from its neighbours.
+    """
+    if len(repo) <= width:
+        return repo
+    owner, sep, name = repo.partition("/")
+    if not sep:
+        return repo[: width - 1] + "…"
+    if len(name) + 2 <= width:
+        return f"…/{name}"
+    return "…/" + name[: width - 3] + "…"
+
+
+class RunningRow(ListItem):
+    """A run in flight: what it is doing, for how long, and what it has spent.
+
+    Redrawn in place rather than rebuilt, because a list that reconstructs
+    itself twice a second loses the highlight under the reader's cursor and
+    restarts every reveal animation on the rows below.
+    """
+
+    def __init__(self, session: Any, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self.session = session
+
+    def compose(self):
+        yield Line(self.text(), classes="running-row")
+
+    def refresh_row(self) -> None:
+        try:
+            self.query_one(Line).update(self.text())
+        except Exception:  # noqa: BLE001 - a row mid-unmount is not an error
+            pass
+
+    def text(self) -> Text:
+        session = self.session
+        row = Text()
+        row.append(f"{RUNNING_MARK} ", style=theme.RAIL)
+        row.append(f"{_repo(session.options.repo):<32}", style="")
+        row.append(f"{status(session):<{HEADLINE_WIDTH}}", style=theme.DIM)
+        row.append(f"{elapsed(session.duration):<14}", style=theme.FAINT)
+        row.append(session.options.mode, style=theme.FAINT)
+        if session.cost_usd:
+            row.append(f"   ${session.cost_usd:.4f}", style=theme.FAINT)
+        return row
+
+
+def status(session: Any) -> str:
+    """What the run is doing, in the words the stage list already uses.
+
+    A stop that has been asked for but not yet landed says `stopping`, never
+    `stopped`: the worker is interrupted at its next model call, and a row that
+    claimed otherwise would be lying for as long as that call takes.
+    """
+    if session.stopping:
+        return "stopping…"
+    stage = getattr(session, "stage", "")
+    return f"running · {stage}" if stage else "starting"
+
+
+def elapsed(seconds: float) -> str:
+    minutes, whole = divmod(int(seconds), 60)
+    return f"{minutes}:{whole:02d}"
+
+
+class RecentList(KeepsHighlightVisible, ListView):
+    def __init__(self, entries: list, **kwargs) -> None:
+        super().__init__(*[RecentRow(e) for e in entries], **kwargs)
+        self.entries = entries
+
+    @property
+    def selected(self) -> Any | None:
+        """The stored assessment under the cursor, if that is what is there."""
+        return getattr(self.highlighted_child, "entry", None)
+
+    @property
+    def selected_session(self) -> Any | None:
+        """The run under the cursor, if the cursor is on a running row."""
+        return getattr(self.highlighted_child, "session", None)
+
+    def running_rows(self) -> list["RunningRow"]:
+        return [row for row in self.children if isinstance(row, RunningRow)]

holt/tui/widgets/scrolling.py

@@ -0,0 +1,38 @@
+"""Keeping the highlighted row where somebody can see it.
+
+Every list in the interface is laid out the same way: a `ListView` at
+`height: auto` inside an ancestor that scrolls. That is deliberate — the list
+should be as tall as it has rows, and the page around it should scroll — but it
+breaks the scrolling Textual gives a `ListView` for free. A `ListView` scrolls
+*itself* to keep its cursor visible, and one sized to its own content has
+nothing to scroll. So the highlight moved and the view did not: the cursor
+walked off the bottom of the pane and kept going, invisibly.
+
+It was worst on the finder, where the nine rejected candidates sit below the
+sixteen survivors. Rejections are the interesting result, the screen says so in
+its own docstring, and they were unreachable by keyboard — twenty presses of ↓
+left the list index at 20 and the scroll offset at 0. The only way to read them
+was a mouse wheel, in an interface whose whole claim is that it does not need
+one.
+
+The fix is to scroll the *ancestor*, which is what `scroll_visible` does. Mixed
+in rather than repeated, because all three lists have the layout and so would
+all three have the bug.
+"""
+
+from __future__ import annotations
+
+from textual.widgets import ListView
+
+
+class KeepsHighlightVisible:
+    """Scroll the highlighted row into view in whatever ancestor scrolls.
+
+    Mixed in *before* `ListView` so this handler runs on the widget itself.
+    Motion is off: the highlight is being driven by a key repeat, and animating
+    each step means the view lags several rows behind the cursor.
+    """
+
+    def on_list_view_highlighted(self, event: ListView.Highlighted) -> None:
+        if event.item is not None:
+            event.item.scroll_visible(animate=False)