twgh 0.1.1__tar.gz

twgh-0.1.1/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: twgh
+Version: 0.1.1
+Summary: Read-only GitHub reviewer CLI: triage, re-review diffs, comment threads
+Author-email: sysid <sysid@gmx.de>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.15.1
+Requires-Dist: rich>=13.0.0
+
+# twgh
+
+Read-only GitHub reviewer CLI: triage what needs you, re-review only what changed
+since you last looked (force-push robust), and see which of your comments were
+addressed — across github.com and GitHub Enterprise.
+
+## Prerequisites
+
+- The GitHub CLI [`gh`](https://cli.github.com), authenticated for each host you
+  review on: `gh auth login --hostname <host>`. twgh borrows gh for auth, host
+  routing, and transport; it never handles your token.
+
+## Install
+
+```sh
+make install      # uv tool install -e . + bash completion
+```
+
+## Commands
+
+| Command | What |
+|---|---|
+| `twgh status` | Cross-repo rollup of PRs needing your review; ★ marks PRs that moved since your last run. |
+| `twgh diff <ref>` | Diff of the files you commented on, since your last review (`--all` for the whole PR). Force-push robust. |
+| `twgh comments <ref>` | All comments, chronological (`--by <user>`, `--mine`, `--all`). |
+| `twgh threads [<ref>]` | Open conversations with a resolved / changed / untouched verdict. No `<ref>` = global inbox across repos. |
+| `twgh open <ref>` | Open the PR in a browser (for the write-actions twgh stays out of). |
+
+`<ref>` is a PR URL, `host/owner/repo#N` (the form `status` prints — paste it
+straight back), `owner/repo#N`, `owner/repo/N`, or a bare number inside a repo.
+
+## Host selection
+
+`-H/--gh-host` overrides `$GH_HOST`, which defaults to `github.com`. Works as a
+global option (`twgh -H bmw.ghe.com status`) or per command.
+
+## The re-review verdict
+
+`twgh threads` classifies each open conversation by what GitHub knows:
+
+- `✓ resolved` — the thread is marked resolved
+- `~ changed` — your anchored code moved since you commented (look with `twgh diff`)
+- `· untouched` — your point still stands as written
+
+## Development
+
+```sh
+make test              # pytest + coverage (floor 85%)
+make static-analysis   # ruff lint-fix, format, ty
+```

twgh-0.1.1/README.md

@@ -0,0 +1,50 @@
+# twgh
+
+Read-only GitHub reviewer CLI: triage what needs you, re-review only what changed
+since you last looked (force-push robust), and see which of your comments were
+addressed — across github.com and GitHub Enterprise.
+
+## Prerequisites
+
+- The GitHub CLI [`gh`](https://cli.github.com), authenticated for each host you
+  review on: `gh auth login --hostname <host>`. twgh borrows gh for auth, host
+  routing, and transport; it never handles your token.
+
+## Install
+
+```sh
+make install      # uv tool install -e . + bash completion
+```
+
+## Commands
+
+| Command | What |
+|---|---|
+| `twgh status` | Cross-repo rollup of PRs needing your review; ★ marks PRs that moved since your last run. |
+| `twgh diff <ref>` | Diff of the files you commented on, since your last review (`--all` for the whole PR). Force-push robust. |
+| `twgh comments <ref>` | All comments, chronological (`--by <user>`, `--mine`, `--all`). |
+| `twgh threads [<ref>]` | Open conversations with a resolved / changed / untouched verdict. No `<ref>` = global inbox across repos. |
+| `twgh open <ref>` | Open the PR in a browser (for the write-actions twgh stays out of). |
+
+`<ref>` is a PR URL, `host/owner/repo#N` (the form `status` prints — paste it
+straight back), `owner/repo#N`, `owner/repo/N`, or a bare number inside a repo.
+
+## Host selection
+
+`-H/--gh-host` overrides `$GH_HOST`, which defaults to `github.com`. Works as a
+global option (`twgh -H bmw.ghe.com status`) or per command.
+
+## The re-review verdict
+
+`twgh threads` classifies each open conversation by what GitHub knows:
+
+- `✓ resolved` — the thread is marked resolved
+- `~ changed` — your anchored code moved since you commented (look with `twgh diff`)
+- `· untouched` — your point still stands as written
+
+## Development
+
+```sh
+make test              # pytest + coverage (floor 85%)
+make static-analysis   # ruff lint-fix, format, ty
+```

twgh-0.1.1/pyproject.toml

@@ -0,0 +1,86 @@
+[project]
+name = "twgh"
+version = "0.1.1"
+description = "Read-only GitHub reviewer CLI: triage, re-review diffs, comment threads"
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [{ name = "sysid", email = "sysid@gmx.de" }]
+dependencies = [
+    "typer>=0.15.1",
+    "rich>=13.0.0",
+]
+
+[project.scripts]
+twgh = "twgh.bin.cli:app"
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.uv]
+managed = true
+package = true
+
+[dependency-groups]
+dev = [
+    "ruff",
+    "ty",
+    "pytest",
+    "pytest-cov",
+    "pytest-mock",
+    "pytest-asyncio",
+    "bump-my-version",
+    "twine",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = [
+    "integration: hits the real gh CLI / network (opt-in)",
+    "experimentation: never runs in CI",
+]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["src/twgh"]
+branch = true
+omit = ["tests/*", "**/__main__.py"]
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 85
+
+[tool.ruff]
+line-length = 88
+indent-width = 4
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.bumpversion]
+current_version = "0.1.1"
+parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
+serialize = ["{major}.{minor}.{patch}"]
+tag = true
+tag_name = "v{new_version}"
+commit = true
+message = "Bump version: {current_version} → {new_version}"
+
+[[tool.bumpversion.files]]
+filename = "VERSION"
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = "version = \"{current_version}\""
+replace = "version = \"{new_version}\""
+[[tool.bumpversion.files]]
+filename = "src/twgh/__init__.py"
+search = "__version__ = \"{current_version}\""
+replace = "__version__ = \"{new_version}\""

twgh-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

twgh-0.1.1/src/twgh/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

twgh-0.1.1/src/twgh/bin/cli.py

@@ -0,0 +1,316 @@
+"""twgh — read-only GitHub reviewer CLI."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Annotated, Optional, cast
+
+import typer
+
+from twgh import __version__
+from twgh.lib import gh, render, snapshot
+from twgh.lib.domain import (
+    AnchorFresh,
+    PrRef,
+    PrRefError,
+    PullRequest,
+    SnapshotEntry,
+    classify_thread,
+    parse_pr_ref,
+    resolve_anchor,
+    review_state,
+    select_diff_paths,
+    snapshot_delta,
+)
+
+logger = logging.getLogger(__name__)
+
+app = typer.Typer(
+    help="twgh — read-only GitHub reviewer CLI (triage, re-review diffs, threads).",
+)
+
+# Shared option types
+HostOption = Annotated[
+    Optional[str],
+    typer.Option(
+        "--gh-host",
+        "-H",
+        help="GitHub host to query. Overrides $GH_HOST. Defaults to $GH_HOST, "
+        "then github.com.",
+    ),
+]
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"twgh {__version__}")
+        raise typer.Exit()
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            callback=_version_callback,
+            is_eager=True,
+            help="Show version and exit.",
+        ),
+    ] = False,
+    verbose: Annotated[
+        bool, typer.Option("--verbose", "-v", help="Enable DEBUG logging.")
+    ] = False,
+    gh_host: Annotated[
+        Optional[str],
+        typer.Option(
+            "--gh-host",
+            "-H",
+            help="GitHub host to query. Overrides $GH_HOST. Defaults to $GH_HOST, "
+            "then github.com.",
+        ),
+    ] = None,
+) -> None:
+    """Global options."""
+    logging.basicConfig(level=logging.DEBUG if verbose else logging.WARNING)
+    if gh_host:
+        # Subcommands inherit the host via gh.resolve_host, which reads $GH_HOST;
+        # setting it here makes the global flag flow down without threading it
+        # through every command's own resolution.
+        os.environ["GH_HOST"] = gh_host
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+        raise typer.Exit()
+
+
+def _cwd_remote() -> PrRef | None:
+    """Best-effort owner/repo/host from the current dir's gh repo context."""
+    try:
+        data = gh.run_gh_json(["repo", "view", "--json", "owner,name"])
+    except gh.GhError:
+        return None
+    if not isinstance(data, dict):
+        return None
+    data_map = cast("dict[str, object]", data)
+    owner_obj = data_map.get("owner")
+    owner = (
+        cast("dict[str, object]", owner_obj).get("login")
+        if isinstance(owner_obj, dict)
+        else None
+    )
+    name = data_map.get("name")
+    if not isinstance(owner, str) or not isinstance(name, str):
+        return None
+    return PrRef(host=gh.resolve_host(None), owner=owner, repo=name, number=0)
+
+
+def _resolve_ref(ref: str, host: str | None) -> PrRef:
+    try:
+        return parse_pr_ref(
+            ref, cwd_remote=_cwd_remote(), default_host=gh.resolve_host(host)
+        )
+    except PrRefError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(code=2) from exc
+
+
+@app.command()
+def open(  # noqa: A001 (shadowing builtin is fine for a CLI verb)
+    ref: str,
+    gh_host: HostOption = None,
+) -> None:
+    """Open a PR in the browser (for the write-actions twgh stays out of)."""
+    gh.browse(_resolve_ref(ref, gh_host))
+
+
+@app.command()
+def diff(
+    ref: str,
+    all_files: Annotated[
+        bool,
+        typer.Option("--all", help="Whole-PR diff, not just files you commented on."),
+    ] = False,
+    gh_host: HostOption = None,
+) -> None:
+    """Re-review diff: files you commented on, anchor→HEAD, force-push robust."""
+    pr_ref = _resolve_ref(ref, gh_host)
+    data = gh.fetch_pr_review_data(pr_ref)
+    me = gh.current_login(gh_host)
+    # Anchor on YOUR last review/comment, not anyone else's on the PR.
+    my_reviews = [r for r in data.reviews if r.author == me]
+    my_comments = [c for t in data.threads for c in t.comments if c.author == me]
+    anchor = resolve_anchor(my_reviews, my_comments)
+    if isinstance(anchor, AnchorFresh):
+        typer.echo("No prior review/comment anchor — showing whole PR (fresh).")
+        # Fresh: diff is a *re-review* tool; with no anchor there is nothing to
+        # re-diff. Guide the user to the browser and exit cleanly.
+        typer.echo("Tip: review this PR fresh in the browser with `twgh open`.")
+        raise typer.Exit()
+    files = gh.compare_files(pr_ref, base=anchor.oid, head=data.head_oid)
+    paths = select_diff_paths(my_comments)
+    if not all_files and paths:
+        files = [f for f in files if f.get("filename") in paths]
+    elif not all_files and not paths:
+        typer.echo("No inline comments → showing whole PR delta.")
+    patch_text = "\n".join(
+        f"### {f.get('filename')} ({f.get('status')})\n{f.get('patch', '')}"
+        for f in files
+    )
+    render.page_diff(patch_text)
+
+
+@app.command()
+def threads(
+    ref: Annotated[
+        Optional[str],
+        typer.Argument(
+            help="PR ref. Omit for a global inbox of your open threads across repos."
+        ),
+    ] = None,
+    by: Annotated[
+        Optional[str], typer.Option("--by", help="Filter by thread author.")
+    ] = None,
+    mine: Annotated[bool, typer.Option("--mine", help="Only your threads.")] = False,
+    all_threads: Annotated[
+        bool, typer.Option("--all", help="Include resolved.")
+    ] = False,
+    gh_host: HostOption = None,
+) -> None:
+    """Open review conversations with a resolved/changed/untouched verdict."""
+    if ref is None:
+        host = gh.resolve_host(gh_host)
+        me = gh.current_login(gh_host)
+        prs = gh.search_review_prs(host=host, me=me)
+        inbox_rows: list[dict] = []
+        for pr in prs:
+            data = gh.fetch_pr_review_data(pr.ref)
+            for t in data.threads:
+                if not all_threads and t.is_resolved:
+                    continue
+                who = me if mine else by
+                if who is not None and t.author != who:
+                    continue
+                inbox_rows.append(
+                    {
+                        "verdict": classify_thread(t),
+                        "path": (
+                            f"{pr.ref.owner}/{pr.ref.repo}#{pr.ref.number}:{t.path}"
+                        ),
+                        "author": t.author,
+                        "body": t.comments[0].body if t.comments else "",
+                    }
+                )
+        render.render_threads(inbox_rows)
+        raise typer.Exit()
+    pr_ref = _resolve_ref(ref, gh_host)
+    data = gh.fetch_pr_review_data(pr_ref)
+    who = gh.current_login(gh_host) if mine else by
+    rows: list[dict] = []
+    for t in data.threads:
+        if not all_threads and t.is_resolved:
+            continue
+        if who is not None and t.author != who:
+            continue
+        rows.append(
+            {
+                "verdict": classify_thread(t),
+                "path": t.path,
+                "author": t.author,
+                "body": t.comments[0].body if t.comments else "",
+            }
+        )
+    render.render_threads(rows)
+
+
+@app.command()
+def comments(
+    ref: str,
+    by: Annotated[
+        Optional[str], typer.Option("--by", help="Filter by comment author.")
+    ] = None,
+    mine: Annotated[bool, typer.Option("--mine", help="Only your comments.")] = False,
+    all_comments: Annotated[
+        bool,
+        typer.Option("--all", help="Include inline comments in resolved threads."),
+    ] = False,
+    gh_host: HostOption = None,
+) -> None:
+    """Catch-up stream of all comments on a PR, chronological."""
+    pr_ref = _resolve_ref(ref, gh_host)
+    data = gh.fetch_pr_review_data(pr_ref)
+    who = gh.current_login(gh_host) if mine else by
+
+    rows: list[dict] = []
+    # Issue/PR-level comments always show (no resolved state).
+    for c in data.issue_comments:
+        rows.append({"author": c.author, "body": c.body, "created_at": c.created_at})
+    # Inline comments; hide those in resolved threads unless --all.
+    for t in data.threads:
+        if t.is_resolved and not all_comments:
+            continue
+        for c in t.comments:
+            rows.append(
+                {"author": c.author, "body": c.body, "created_at": c.created_at}
+            )
+
+    if who is not None:
+        rows = [r for r in rows if r["author"] == who]
+    rows.sort(key=lambda r: r["created_at"])
+    render.render_comments(rows)
+
+
+def _pr_key(pr: PullRequest) -> str:
+    r = pr.ref
+    return f"{r.host}/{r.owner}/{r.repo}#{r.number}"
+
+
+@app.command()
+def status(
+    json_out: Annotated[
+        bool, typer.Option("--json", help="Machine-readable output.")
+    ] = False,
+    gh_host: HostOption = None,
+) -> None:
+    """Cross-repo rollup of PRs that need your review attention."""
+    host = gh.resolve_host(gh_host)
+    me = gh.current_login(gh_host)
+    prs = gh.search_review_prs(host=host, me=me)
+
+    current = {
+        _pr_key(pr): SnapshotEntry(pr.head_oid, pr.open_thread_count, pr.updated_at)
+        for pr in prs
+    }
+    prev = snapshot.load_snapshot()
+    new_keys = snapshot_delta(prev, current)
+    snapshot.save_snapshot(current)
+
+    rows = [
+        {
+            "ref": _pr_key(pr),
+            "title": pr.title,
+            "author": pr.author,
+            "review_state": review_state(pr.my_review, pr.head_oid),
+            "open_threads": pr.open_thread_count,
+            "is_new": _pr_key(pr) in new_keys,
+        }
+        for pr in prs
+    ]
+    if json_out:
+        render.render_json(
+            [
+                {
+                    "ref": _pr_key(pr),
+                    "title": pr.title,
+                    "author": pr.author,
+                    "review_state": review_state(pr.my_review, pr.head_oid).value,
+                    "open_threads": pr.open_thread_count,
+                    "is_new": _pr_key(pr) in new_keys,
+                }
+                for pr in prs
+            ]
+        )
+    else:
+        render.render_status(rows)

twgh-0.1.1/src/twgh/lib/domain.py

@@ -0,0 +1,215 @@
+"""Pure domain core for twgh: dataclasses and pure functions only.
+
+No I/O, no subprocess, stdlib only. This is where the force-push-robustness
+logic lives so it can be unit-tested without invoking `gh`.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import Enum
+
+
+class PrRefError(ValueError):
+    """Raised when a PR reference string cannot be resolved to a PrRef."""
+
+
+@dataclass(frozen=True)
+class PrRef:
+    host: str
+    owner: str
+    repo: str
+    number: int
+
+
+_URL_RE = re.compile(
+    r"^https?://(?P<host>[^/]+)/(?P<owner>[^/]+)/(?P<repo>[^/]+)/pull/(?P<number>\d+)"
+)
+# host/owner/repo#N (or /N) — the exact form `twgh status` prints, so a status
+# row pastes straight into diff/comments. Three path segments before the number.
+_HOST_OWNER_REPO_RE = re.compile(
+    r"^(?P<host>[^/]+)/(?P<owner>[^/]+)/(?P<repo>[^/#]+)[#/](?P<number>\d+)$"
+)
+_OWNER_REPO_RE = re.compile(r"^(?P<owner>[^/]+)/(?P<repo>[^/#]+)[#/](?P<number>\d+)$")
+_BARE_RE = re.compile(r"^(?P<number>\d+)$")
+
+
+def parse_pr_ref(
+    s: str,
+    cwd_remote: PrRef | None,
+    default_host: str = "github.com",
+) -> PrRef:
+    """Resolve a PR reference string.
+
+    Accepts a full pull URL, ``host/owner/repo#N`` (the form ``status``
+    prints), ``owner/repo#N``, ``owner/repo/N``, or a bare ``N`` (which
+    requires ``cwd_remote`` to supply host/owner/repo).
+    """
+    s = s.strip()
+    if m := _URL_RE.match(s):
+        return PrRef(m["host"], m["owner"], m["repo"], int(m["number"]))
+    if m := _HOST_OWNER_REPO_RE.match(s):
+        return PrRef(m["host"], m["owner"], m["repo"], int(m["number"]))
+    if m := _OWNER_REPO_RE.match(s):
+        return PrRef(default_host, m["owner"], m["repo"], int(m["number"]))
+    if m := _BARE_RE.match(s):
+        if cwd_remote is None:
+            raise PrRefError(
+                f"Bare PR number '{s}' needs a repo context; run inside a git "
+                "repo or use owner/repo#N or a full URL."
+            )
+        return PrRef(cwd_remote.host, cwd_remote.owner, cwd_remote.repo, int(s))
+    raise PrRefError(
+        f"Unrecognized PR reference '{s}'. Use a URL, host/owner/repo#N, "
+        "owner/repo#N, owner/repo/N, or a bare number inside a repo."
+    )
+
+
+@dataclass(frozen=True)
+class Review:
+    commit_oid: str | None
+    state: str  # APPROVED | CHANGES_REQUESTED | COMMENTED | PENDING | DISMISSED
+    submitted_at: str | None
+    author: str = ""  # login of the reviewer; used to scope the anchor to "me"
+
+
+@dataclass(frozen=True)
+class PullRequest:
+    ref: PrRef
+    title: str
+    author: str
+    head_oid: str
+    updated_at: str
+    my_review: Review | None
+    open_thread_count: int
+    review_decision: str | None
+    ci_state: str | None
+    mergeable: str | None
+
+
+@dataclass(frozen=True)
+class ReviewComment:
+    author: str
+    path: str | None
+    original_commit_oid: str | None
+    body: str
+    created_at: str
+    is_outdated: bool
+
+
+@dataclass(frozen=True)
+class AnchorSha:
+    oid: str
+    source: str  # "REVIEW" | "COMMENT"
+
+
+@dataclass(frozen=True)
+class AnchorFresh:
+    pass
+
+
+Anchor = AnchorSha | AnchorFresh
+
+
+def resolve_anchor(
+    reviews: list[Review],
+    comments: list[ReviewComment],
+) -> Anchor:
+    """Resolve the re-review anchor commit.
+
+    Priority: most recent *submitted* review with a commit, else most recent
+    comment with a commit, else fresh (never reviewed).
+    """
+    submitted = [
+        (r.commit_oid, r.submitted_at)
+        for r in reviews
+        if r.commit_oid and r.submitted_at
+    ]
+    if submitted:
+        oid, _ = max(submitted, key=lambda pair: pair[1])
+        return AnchorSha(oid=oid, source="REVIEW")
+    with_commit = [
+        (c.original_commit_oid, c.created_at) for c in comments if c.original_commit_oid
+    ]
+    if with_commit:
+        oid, _ = max(with_commit, key=lambda pair: pair[1])
+        return AnchorSha(oid=oid, source="COMMENT")
+    return AnchorFresh()
+
+
+@dataclass(frozen=True)
+class Thread:
+    author: str
+    path: str | None
+    is_resolved: bool
+    is_outdated: bool
+    comments: list[ReviewComment]
+
+
+class Verdict(Enum):
+    RESOLVED = "resolved"
+    CHANGED = "changed"
+    UNTOUCHED = "untouched"
+
+
+def classify_thread(thread: Thread) -> Verdict:
+    """Classify a review thread by what GitHub knows about it.
+
+    Resolved beats everything; otherwise a thread whose anchored code has
+    moved (any comment outdated, or the thread flagged outdated) is CHANGED;
+    otherwise the point still stands as written.
+    """
+    if thread.is_resolved:
+        return Verdict.RESOLVED
+    if thread.is_outdated or any(c.is_outdated for c in thread.comments):
+        return Verdict.CHANGED
+    return Verdict.UNTOUCHED
+
+
+class ReviewState(Enum):
+    UP_TO_DATE = "up_to_date"
+    NEEDS_REVIEW = "needs_review"
+    NEEDS_RE_REVIEW = "needs_re_review"
+
+
+def review_state(my_review: Review | None, head_oid: str) -> ReviewState:
+    """Determine whether the reviewer still owes a (re-)review of HEAD."""
+    if my_review is None or my_review.commit_oid is None:
+        return ReviewState.NEEDS_REVIEW
+    if my_review.commit_oid == head_oid:
+        return ReviewState.UP_TO_DATE
+    return ReviewState.NEEDS_RE_REVIEW
+
+
+def select_diff_paths(my_comments: list[ReviewComment]) -> set[str]:
+    """Distinct file paths the reviewer left inline comments on."""
+    return {c.path for c in my_comments if c.path}
+
+
+@dataclass(frozen=True)
+class SnapshotEntry:
+    head_oid: str
+    comment_count: int
+    seen_at: str
+
+
+def snapshot_delta(
+    prev: dict[str, SnapshotEntry],
+    current: dict[str, SnapshotEntry],
+) -> set[str]:
+    """Keys in ``current`` that are new or moved since ``prev``.
+
+    First run (empty ``prev``) deliberately flags nothing, so the first
+    `status` is not a wall of stars.
+    """
+    if not prev:
+        return set()
+    changed: set[str] = set()
+    for key, cur in current.items():
+        old = prev.get(key)
+        if old is None:
+            changed.add(key)
+        elif cur.head_oid != old.head_oid or cur.comment_count > old.comment_count:
+            changed.add(key)
+    return changed

twgh-0.1.1/src/twgh/lib/gh.py

@@ -0,0 +1,347 @@
+"""GitHub I/O boundary. The only module that shells out to the `gh` CLI.
+
+We borrow gh for auth, host routing, and transport; we own the query content.
+No token ever passes through this code — gh holds it.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import subprocess
+from dataclasses import dataclass
+from typing import cast
+
+from twgh.lib.domain import PrRef, PullRequest, Review, ReviewComment, Thread
+from twgh.lib.queries import PR_REVIEW_DATA, SEARCH_REVIEW_PRS
+
+logger = logging.getLogger(__name__)
+
+
+class GhError(RuntimeError):
+    """Base class for gh invocation failures."""
+
+
+class GhNotFoundError(GhError):
+    """The `gh` CLI is not installed / not on PATH."""
+
+
+class GhAuthError(GhError):
+    """Not authenticated for the target host."""
+
+
+class HostUnreachableError(GhError):
+    """The target host could not be reached (network / VPN)."""
+
+
+class GhApiError(GhError):
+    """gh returned a non-zero exit for an API call."""
+
+
+def resolve_host(flag: str | None) -> str:
+    """Resolve the GitHub host: flag > $GH_HOST > github.com."""
+    if flag:
+        return flag
+    return os.environ.get("GH_HOST") or "github.com"
+
+
+def _classify_stderr(stderr: str) -> type[GhError]:
+    low = stderr.lower()
+    if "auth" in low and ("login" in low or "not logged" in low or "token" in low):
+        return GhAuthError
+    if "could not resolve host" in low or "connection" in low or "timeout" in low:
+        return HostUnreachableError
+    return GhApiError
+
+
+def run_gh_json(args: list[str], host: str | None = None) -> object:
+    """Run `gh <args>` (optionally for a host) and parse JSON stdout.
+
+    Raises a typed GhError subclass on failure.
+    """
+    argv = ["gh", *args]
+    env = dict(os.environ)
+    if host:
+        env["GH_HOST"] = host
+    try:
+        proc = subprocess.run(argv, capture_output=True, text=True, env=env)
+    except FileNotFoundError as exc:
+        raise GhNotFoundError(
+            "gh CLI not found — install from https://cli.github.com"
+        ) from exc
+    if proc.returncode != 0:
+        err_cls = _classify_stderr(proc.stderr)
+        raise err_cls(proc.stderr.strip() or f"gh exited {proc.returncode}")
+    return json.loads(proc.stdout) if proc.stdout.strip() else None
+
+
+def graphql(
+    query: str, variables: dict[str, object], host: str | None = None
+) -> object:
+    """Run a GraphQL query via `gh api graphql`.
+
+    String variables are forced with ``-f`` so a value that merely *looks*
+    numeric/boolean (a repo named "123", a cursor) is not coerced into the
+    wrong GraphQL type; only real ints go through ``-F`` for numeric typing.
+    """
+    args = ["api", "graphql", "-f", f"query={query}"]
+    for key, value in variables.items():
+        if isinstance(value, bool):
+            args += ["-F", f"{key}={str(value).lower()}"]
+        elif isinstance(value, int):
+            args += ["-F", f"{key}={value}"]
+        else:
+            args += ["-f", f"{key}={value}"]
+    return run_gh_json(args, host=host)
+
+
+def compare_files(ref: PrRef, base: str, head: str) -> list[dict]:
+    """Return per-file patches from the REST compare endpoint, all pages.
+
+    Both SHAs resolve server-side, so a force-pushed-away ``base`` still works
+    as long as a comment references it. ``--paginate`` follows Link headers so
+    large PRs are not silently truncated; ``--slurp`` wraps the pages into a
+    JSON array we flatten.
+    """
+    path = f"repos/{ref.owner}/{ref.repo}/compare/{base}...{head}"
+    payload = run_gh_json(["api", "--paginate", "--slurp", path], host=ref.host)
+    pages = payload if isinstance(payload, list) else [payload]
+    files: list[dict] = []
+    for page in pages:
+        page_files = _as_dict(page).get("files")
+        if isinstance(page_files, list):
+            files += [f for f in page_files if isinstance(f, dict)]
+    return files
+
+
+def current_login(host: str | None = None) -> str:
+    """Return the authenticated user's login for the host."""
+    data = run_gh_json(["api", "user", "--jq", "{login: .login}"], host=host)
+    login = _as_dict(data).get("login")
+    if isinstance(login, str) and login:
+        return login
+    raise GhApiError("could not determine current gh user")
+
+
+def browse(ref: PrRef) -> None:
+    """Open the PR in a browser via `gh browse`."""
+    url = f"https://{ref.host}/{ref.owner}/{ref.repo}/pull/{ref.number}"
+    argv = ["gh", "browse", "--repo", f"{ref.owner}/{ref.repo}", str(ref.number)]
+    env = dict(os.environ)
+    env["GH_HOST"] = ref.host
+    try:
+        proc = subprocess.run(argv, capture_output=True, text=True, env=env)
+    except FileNotFoundError as exc:
+        raise GhNotFoundError("gh CLI not found") from exc
+    if proc.returncode != 0:
+        # Fall back to printing the URL the user can click.
+        print(url)
+
+
+@dataclass(frozen=True)
+class PrReviewData:
+    head_oid: str
+    reviews: list[Review]
+    threads: list[Thread]
+    issue_comments: list[ReviewComment]
+
+
+def _as_dict(value: object) -> dict[str, object]:
+    """Narrow an arbitrary JSON value to a dict (empty when it isn't one)."""
+    return cast("dict[str, object]", value) if isinstance(value, dict) else {}
+
+
+def _nodes(value: object) -> list[dict[str, object]]:
+    """Extract the ``nodes`` list of a GraphQL connection, dicts only."""
+    nodes = _as_dict(value).get("nodes")
+    if not isinstance(nodes, list):
+        return []
+    return [cast("dict[str, object]", n) for n in nodes if isinstance(n, dict)]
+
+
+def _str_or(value: object, default: str) -> str:
+    return value if isinstance(value, str) else default
+
+
+def _login(node: dict[str, object]) -> str:
+    return _str_or(_as_dict(node.get("author")).get("login"), "?")
+
+
+def _has_more(connection: object) -> bool:
+    """True if a GraphQL connection has an unfetched next page."""
+    return bool(_as_dict(_as_dict(connection).get("pageInfo")).get("hasNextPage"))
+
+
+def _comment_from_node(node: dict[str, object]) -> ReviewComment:
+    path = node.get("path")
+    oid = _as_dict(node.get("originalCommit")).get("oid")
+    return ReviewComment(
+        author=_login(node),
+        path=path if isinstance(path, str) else None,
+        original_commit_oid=oid if isinstance(oid, str) else None,
+        body=_str_or(node.get("body"), ""),
+        created_at=_str_or(node.get("createdAt"), ""),
+        is_outdated=bool(node.get("outdated", False)),
+    )
+
+
+def fetch_pr_review_data(ref: PrRef) -> PrReviewData:
+    """Fetch reviews, threads, and issue comments for one PR via GraphQL."""
+    raw = graphql(
+        PR_REVIEW_DATA,
+        {"owner": ref.owner, "repo": ref.repo, "number": ref.number},
+        host=ref.host,
+    )
+    pr = _as_dict(_as_dict(_as_dict(raw).get("data")).get("repository")).get(
+        "pullRequest"
+    )
+    pr_map = _as_dict(pr)
+
+    if (
+        _has_more(pr_map.get("reviews"))
+        or _has_more(pr_map.get("reviewThreads"))
+        or _has_more(pr_map.get("comments"))
+    ):
+        logger.warning(
+            "%s/%s#%s has more reviews/threads/comments than the 100 fetched; "
+            "results may be partial.",
+            ref.owner,
+            ref.repo,
+            ref.number,
+        )
+
+    reviews = [
+        Review(
+            commit_oid=(
+                oid
+                if isinstance(oid := _as_dict(n.get("commit")).get("oid"), str)
+                else None
+            ),
+            state=_str_or(n.get("state"), ""),
+            submitted_at=(sa if isinstance(sa := n.get("submittedAt"), str) else None),
+            author=_login(n),
+        )
+        for n in _nodes(pr_map.get("reviews"))
+    ]
+
+    threads: list[Thread] = []
+    for t in _nodes(pr_map.get("reviewThreads")):
+        comment_nodes = _nodes(t.get("comments"))
+        first = comment_nodes[0] if comment_nodes else {}
+        first_path = first.get("path")
+        threads.append(
+            Thread(
+                author=_login(first),
+                path=first_path if isinstance(first_path, str) else None,
+                is_resolved=bool(t.get("isResolved")),
+                is_outdated=bool(t.get("isOutdated")),
+                comments=[_comment_from_node(c) for c in comment_nodes],
+            )
+        )
+
+    issue_comments = [
+        ReviewComment(
+            author=_login(n),
+            path=None,
+            original_commit_oid=None,
+            body=_str_or(n.get("body"), ""),
+            created_at=_str_or(n.get("createdAt"), ""),
+            is_outdated=False,
+        )
+        for n in _nodes(pr_map.get("comments"))
+    ]
+
+    return PrReviewData(
+        head_oid=_str_or(pr_map.get("headRefOid"), ""),
+        reviews=reviews,
+        threads=threads,
+        issue_comments=issue_comments,
+    )
+
+
+_SEARCH_QUALIFIERS = (
+    "is:open is:pr review-requested:@me",
+    "is:open is:pr commenter:@me",
+    "is:open is:pr reviewed-by:@me",
+)
+
+
+def _str_or_none(value: object) -> str | None:
+    return value if isinstance(value, str) else None
+
+
+def _thread_author(thread: dict[str, object]) -> str:
+    """Login of the thread opener (its first comment's author), or '?'."""
+    comment_nodes = _nodes(thread.get("comments"))
+    return _login(comment_nodes[0]) if comment_nodes else "?"
+
+
+def _pr_from_search_node(node: dict[str, object], host: str, me: str) -> PullRequest:
+    owner_repo = _str_or(_as_dict(node.get("repository")).get("nameWithOwner"), "/")
+    owner, name = owner_repo.split("/", 1)
+    number = node.get("number")
+    ref = PrRef(
+        host=host,
+        owner=owner,
+        repo=name,
+        number=number if isinstance(number, int) else 0,
+    )
+    my_reviews = [
+        Review(
+            commit_oid=_str_or_none(_as_dict(r.get("commit")).get("oid")),
+            state=_str_or(r.get("state"), ""),
+            submitted_at=_str_or_none(r.get("submittedAt")),
+        )
+        for r in _nodes(node.get("reviews"))
+        if _login(r) == me
+    ]
+    my_review = max(my_reviews, key=lambda r: r.submitted_at or "", default=None)
+    # "Your open threads": unresolved threads YOU opened (first comment is yours),
+    # not every unresolved thread on the PR.
+    open_threads = sum(
+        1
+        for t in _nodes(node.get("reviewThreads"))
+        if not t.get("isResolved") and _thread_author(t) == me
+    )
+    commit_nodes = _nodes(node.get("commits"))
+    rollup = _as_dict(
+        _as_dict((commit_nodes[0] if commit_nodes else {}).get("commit")).get(
+            "statusCheckRollup"
+        )
+    )
+    return PullRequest(
+        ref=ref,
+        title=_str_or(node.get("title"), ""),
+        author=_login(node),
+        head_oid=_str_or(node.get("headRefOid"), ""),
+        updated_at=_str_or(node.get("updatedAt"), ""),
+        my_review=my_review,
+        open_thread_count=open_threads,
+        review_decision=_str_or_none(node.get("reviewDecision")),
+        ci_state=_str_or_none(rollup.get("state")),
+        mergeable=_str_or_none(node.get("mergeable")),
+    )
+
+
+def search_review_prs(host: str, me: str) -> list[PullRequest]:
+    """Find open PRs review-requested-from / commented-by / reviewed-by the user."""
+    found: dict[str, PullRequest] = {}
+    for qualifier in _SEARCH_QUALIFIERS:
+        after: str | None = None
+        while True:
+            variables: dict[str, object] = {"q": qualifier}
+            if after:
+                variables["after"] = after
+            raw = graphql(SEARCH_REVIEW_PRS, variables, host=host)
+            search = _as_dict(_as_dict(_as_dict(raw).get("data")).get("search"))
+            for node in _nodes(search):
+                pr = _pr_from_search_node(node, host, me)
+                key = f"{pr.ref.host}/{pr.ref.owner}/{pr.ref.repo}#{pr.ref.number}"
+                found[key] = pr
+            page = _as_dict(search.get("pageInfo"))
+            if page.get("hasNextPage"):
+                after = _str_or_none(page.get("endCursor"))
+            else:
+                break
+    return list(found.values())

twgh-0.1.1/src/twgh/lib/queries.py

@@ -0,0 +1,49 @@
+"""GraphQL query strings. The CLI owns the query content; gh owns transport."""
+
+SEARCH_REVIEW_PRS = """
+query($q: String!, $after: String) {
+  search(query: $q, type: ISSUE, first: 50, after: $after) {
+    pageInfo { hasNextPage endCursor }
+    nodes {
+      ... on PullRequest {
+        number title updatedAt mergeable reviewDecision
+        author { login }
+        repository { nameWithOwner }
+        headRefOid
+        commits(last: 1) { nodes { commit { statusCheckRollup { state } } } }
+        reviewThreads(first: 100) {
+          nodes { isResolved comments(first: 1) { nodes { author { login } } } }
+        }
+        reviews(first: 100) { nodes { author { login } state commit { oid } submittedAt } }
+      }
+    }
+  }
+}
+"""
+
+PR_REVIEW_DATA = """
+query($owner: String!, $repo: String!, $number: Int!) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $number) {
+      headRefOid
+      reviews(first: 100) {
+        pageInfo { hasNextPage }
+        nodes { author { login } state commit { oid } submittedAt }
+      }
+      reviewThreads(first: 100) {
+        pageInfo { hasNextPage }
+        nodes {
+          isResolved isOutdated
+          comments(first: 100) {
+            nodes { author { login } path originalCommit { oid } body createdAt outdated }
+          }
+        }
+      }
+      comments(first: 100) {
+        pageInfo { hasNextPage }
+        nodes { author { login } body createdAt }
+      }
+    }
+  }
+}
+"""

twgh-0.1.1/src/twgh/lib/render.py

@@ -0,0 +1,101 @@
+"""Rendering: Rich tables for humans, JSON for scripts. Only module using rich."""
+
+from __future__ import annotations
+
+import json as _json
+import os
+import shutil
+import subprocess
+import sys
+
+from rich.console import Console
+from rich.table import Table
+
+from twgh.lib.domain import ReviewState, Verdict
+
+VERDICT_GLYPH = {
+    Verdict.RESOLVED: "✓",
+    Verdict.CHANGED: "~",
+    Verdict.UNTOUCHED: "·",
+}
+
+_REVIEW_STATE_LABEL = {
+    ReviewState.UP_TO_DATE: "up to date",
+    ReviewState.NEEDS_REVIEW: "needs review",
+    ReviewState.NEEDS_RE_REVIEW: "needs re-review",
+}
+
+_default_console = Console()
+
+
+def render_json(data: object) -> None:
+    """Emit machine-readable JSON to stdout."""
+    print(_json.dumps(data, indent=2, default=str))
+
+
+def render_threads(rows: list[dict], console: Console | None = None) -> None:
+    """Render review threads with their three-state verdict glyph."""
+    console = console or _default_console
+    table = Table(show_header=True)
+    table.add_column("")
+    table.add_column("file")
+    table.add_column("by")
+    table.add_column("comment")
+    for row in rows:
+        glyph = VERDICT_GLYPH[row["verdict"]]
+        table.add_row(glyph, row.get("path") or "(PR)", row["author"], row["body"])
+    console.print(table)
+
+
+def render_status(rows: list[dict], console: Console | None = None) -> None:
+    """Render the cross-repo status rollup."""
+    console = console or _default_console
+    table = Table(show_header=True)
+    table.add_column("")  # ★ NEW marker
+    table.add_column("PR")
+    table.add_column("title")
+    table.add_column("author")
+    table.add_column("state")
+    table.add_column("threads", justify="right")
+    for row in rows:
+        marker = "★" if row.get("is_new") else ""
+        table.add_row(
+            marker,
+            row["ref"],
+            row["title"],
+            row["author"],
+            _REVIEW_STATE_LABEL[row["review_state"]],
+            str(row["open_threads"]),
+        )
+    console.print(table)
+
+
+def render_comments(rows: list[dict], console: Console | None = None) -> None:
+    """Render a chronological comment stream."""
+    console = console or _default_console
+    for row in rows:
+        console.print(f"[bold]{row['author']}[/bold] [dim]{row['created_at']}[/dim]")
+        console.print(row["body"])
+        console.print()
+
+
+def choose_pager(env: dict[str, str]) -> list[str]:
+    """Pick the diff pager: delta if installed, else $PAGER, else `less -R`."""
+    if shutil.which("delta"):
+        return ["delta"]
+    pager = env.get("PAGER")
+    if pager:
+        return pager.split()
+    return ["less", "-R"]
+
+
+def page_diff(patch_text: str, env: dict[str, str] | None = None) -> None:
+    """Send unified-diff text to the chosen pager, or stdout when not a TTY."""
+    env = env if env is not None else dict(os.environ)
+    if not sys.stdout.isatty():
+        print(patch_text)
+        return
+    pager = choose_pager(env)
+    proc = subprocess.run(pager, input=patch_text, text=True)
+    if proc.returncode not in (0, None):
+        print(patch_text)

twgh-0.1.1/src/twgh/lib/snapshot.py

@@ -0,0 +1,35 @@
+"""JSON snapshot persistence for the NEW-since-last-run highlight."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict
+from pathlib import Path
+
+from twgh.lib.domain import SnapshotEntry
+
+
+def snapshot_path() -> Path:
+    """Location of the snapshot file: $XDG_STATE_HOME/twgh or ~/.local/state/twgh."""
+    base = os.environ.get("XDG_STATE_HOME")
+    root = Path(base) if base else Path(os.environ["HOME"]) / ".local" / "state"
+    return root / "twgh" / "snapshot.json"
+
+
+def load_snapshot(path: Path | None = None) -> dict[str, SnapshotEntry]:
+    """Load the snapshot; missing or corrupt file → empty (first-run guard)."""
+    path = path or snapshot_path()
+    try:
+        raw = json.loads(path.read_text())
+    except (FileNotFoundError, json.JSONDecodeError):
+        return {}
+    return {k: SnapshotEntry(**v) for k, v in raw.items()}
+
+
+def save_snapshot(data: dict[str, SnapshotEntry], path: Path | None = None) -> None:
+    """Write the snapshot, creating parent dirs as needed."""
+    path = path or snapshot_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    serializable = {k: asdict(v) for k, v in data.items()}
+    path.write_text(json.dumps(serializable, indent=2))

twgh-0.1.1/src/twgh.egg-info/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: twgh
+Version: 0.1.1
+Summary: Read-only GitHub reviewer CLI: triage, re-review diffs, comment threads
+Author-email: sysid <sysid@gmx.de>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.15.1
+Requires-Dist: rich>=13.0.0
+
+# twgh
+
+Read-only GitHub reviewer CLI: triage what needs you, re-review only what changed
+since you last looked (force-push robust), and see which of your comments were
+addressed — across github.com and GitHub Enterprise.
+
+## Prerequisites
+
+- The GitHub CLI [`gh`](https://cli.github.com), authenticated for each host you
+  review on: `gh auth login --hostname <host>`. twgh borrows gh for auth, host
+  routing, and transport; it never handles your token.
+
+## Install
+
+```sh
+make install      # uv tool install -e . + bash completion
+```
+
+## Commands
+
+| Command | What |
+|---|---|
+| `twgh status` | Cross-repo rollup of PRs needing your review; ★ marks PRs that moved since your last run. |
+| `twgh diff <ref>` | Diff of the files you commented on, since your last review (`--all` for the whole PR). Force-push robust. |
+| `twgh comments <ref>` | All comments, chronological (`--by <user>`, `--mine`, `--all`). |
+| `twgh threads [<ref>]` | Open conversations with a resolved / changed / untouched verdict. No `<ref>` = global inbox across repos. |
+| `twgh open <ref>` | Open the PR in a browser (for the write-actions twgh stays out of). |
+
+`<ref>` is a PR URL, `host/owner/repo#N` (the form `status` prints — paste it
+straight back), `owner/repo#N`, `owner/repo/N`, or a bare number inside a repo.
+
+## Host selection
+
+`-H/--gh-host` overrides `$GH_HOST`, which defaults to `github.com`. Works as a
+global option (`twgh -H bmw.ghe.com status`) or per command.
+
+## The re-review verdict
+
+`twgh threads` classifies each open conversation by what GitHub knows:
+
+- `✓ resolved` — the thread is marked resolved
+- `~ changed` — your anchored code moved since you commented (look with `twgh diff`)
+- `· untouched` — your point still stands as written
+
+## Development
+
+```sh
+make test              # pytest + coverage (floor 85%)
+make static-analysis   # ruff lint-fix, format, ty
+```

twgh-0.1.1/src/twgh.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+src/twgh/__init__.py
+src/twgh.egg-info/PKG-INFO
+src/twgh.egg-info/SOURCES.txt
+src/twgh.egg-info/dependency_links.txt
+src/twgh.egg-info/entry_points.txt
+src/twgh.egg-info/requires.txt
+src/twgh.egg-info/top_level.txt
+src/twgh/bin/__init__.py
+src/twgh/bin/cli.py
+src/twgh/lib/__init__.py
+src/twgh/lib/domain.py
+src/twgh/lib/gh.py
+src/twgh/lib/queries.py
+src/twgh/lib/render.py
+src/twgh/lib/snapshot.py

twgh-0.1.1/src/twgh.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

twgh-0.1.1/src/twgh.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+twgh = twgh.bin.cli:app

twgh-0.1.1/src/twgh.egg-info/requires.txt

@@ -0,0 +1,2 @@
+typer>=0.15.1
+rich>=13.0.0

twgh-0.1.1/src/twgh.egg-info/top_level.txt

@@ -0,0 +1 @@
+twgh