gh-prlist 0.2.0__tar.gz

gh_prlist-0.2.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: gh-prlist
+Version: 0.2.0
+Summary: Configurable GitHub PR monitor with macOS notifications
+Author: Foad Kesheh
+Keywords: github,pull-request,cli,notification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# gh-prlist
+
+Configurable GitHub pull-request monitoring with clickable macOS
+notifications. The PyPI package is **`gh-prlist`** (`prlist` and `pr-list`
+are taken or blocked as too similar). The installed commands are `gh-prlist`,
+`pr-list`, and `prlist`. It requires the GitHub CLI (`gh`) to be installed and
+authenticated.
+
+```console
+uvx gh-prlist setup
+uvx gh-prlist list
+uvx gh-prlist monitor
+uvx gh-prlist monitor --own
+uvx gh-prlist monitor --team
+uvx gh-prlist monitor --own --team
+```
+
+`setup` writes TOML configuration to `~/.prlist`. Command-line options
+override that file; run `prlist <command> --help` for all overrides.
+
+The default policies show your open non-draft PRs with failing CI and
+non-draft team-review requests with green CI and no explicit merge conflict.
+`monitor` checks every ten minutes and writes a clickable report to
+`~/.cache/prlist/prs.html`.
+
+Each source can independently filter CI (`green`, `failing`, `any`) and
+mergeability (`not_conflicting`, `conflicting`, `any`). Notifications can
+include own PRs, team PRs, or both. Change-only notification state persists
+across monitor restarts.
+
+For clickable notification actions on macOS, install `terminal-notifier`.
+Without it, notifications fall back to `osascript`.

gh_prlist-0.2.0/README.md

@@ -0,0 +1,32 @@
+# gh-prlist
+
+Configurable GitHub pull-request monitoring with clickable macOS
+notifications. The PyPI package is **`gh-prlist`** (`prlist` and `pr-list`
+are taken or blocked as too similar). The installed commands are `gh-prlist`,
+`pr-list`, and `prlist`. It requires the GitHub CLI (`gh`) to be installed and
+authenticated.
+
+```console
+uvx gh-prlist setup
+uvx gh-prlist list
+uvx gh-prlist monitor
+uvx gh-prlist monitor --own
+uvx gh-prlist monitor --team
+uvx gh-prlist monitor --own --team
+```
+
+`setup` writes TOML configuration to `~/.prlist`. Command-line options
+override that file; run `prlist <command> --help` for all overrides.
+
+The default policies show your open non-draft PRs with failing CI and
+non-draft team-review requests with green CI and no explicit merge conflict.
+`monitor` checks every ten minutes and writes a clickable report to
+`~/.cache/prlist/prs.html`.
+
+Each source can independently filter CI (`green`, `failing`, `any`) and
+mergeability (`not_conflicting`, `conflicting`, `any`). Notifications can
+include own PRs, team PRs, or both. Change-only notification state persists
+across monitor restarts.
+
+For clickable notification actions on macOS, install `terminal-notifier`.
+Without it, notifications fall back to `osascript`.

gh_prlist-0.2.0/gh_prlist.egg-info/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: gh-prlist
+Version: 0.2.0
+Summary: Configurable GitHub PR monitor with macOS notifications
+Author: Foad Kesheh
+Keywords: github,pull-request,cli,notification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# gh-prlist
+
+Configurable GitHub pull-request monitoring with clickable macOS
+notifications. The PyPI package is **`gh-prlist`** (`prlist` and `pr-list`
+are taken or blocked as too similar). The installed commands are `gh-prlist`,
+`pr-list`, and `prlist`. It requires the GitHub CLI (`gh`) to be installed and
+authenticated.
+
+```console
+uvx gh-prlist setup
+uvx gh-prlist list
+uvx gh-prlist monitor
+uvx gh-prlist monitor --own
+uvx gh-prlist monitor --team
+uvx gh-prlist monitor --own --team
+```
+
+`setup` writes TOML configuration to `~/.prlist`. Command-line options
+override that file; run `prlist <command> --help` for all overrides.
+
+The default policies show your open non-draft PRs with failing CI and
+non-draft team-review requests with green CI and no explicit merge conflict.
+`monitor` checks every ten minutes and writes a clickable report to
+`~/.cache/prlist/prs.html`.
+
+Each source can independently filter CI (`green`, `failing`, `any`) and
+mergeability (`not_conflicting`, `conflicting`, `any`). Notifications can
+include own PRs, team PRs, or both. Change-only notification state persists
+across monitor restarts.
+
+For clickable notification actions on macOS, install `terminal-notifier`.
+Without it, notifications fall back to `osascript`.

gh_prlist-0.2.0/gh_prlist.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+README.md
+pyproject.toml
+gh_prlist.egg-info/PKG-INFO
+gh_prlist.egg-info/SOURCES.txt
+gh_prlist.egg-info/dependency_links.txt
+gh_prlist.egg-info/entry_points.txt
+gh_prlist.egg-info/top_level.txt
+pr_list/__init__.py
+pr_list/__main__.py
+pr_list/ci.py
+pr_list/cli.py
+pr_list/config.py
+pr_list/formatters.py
+pr_list/github.py
+pr_list/models.py
+pr_list/notify.py
+pr_list/report.py
+pr_list/watch.py
+tests/test_ci.py
+tests/test_config.py
+tests/test_formatters.py
+tests/test_watch.py

gh_prlist-0.2.0/gh_prlist.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gh_prlist-0.2.0/gh_prlist.egg-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+gh-prlist = pr_list.cli:main
+pr-list = pr_list.cli:main
+prlist = pr_list.cli:main

gh_prlist-0.2.0/gh_prlist.egg-info/top_level.txt

@@ -0,0 +1 @@
+pr_list

gh_prlist-0.2.0/pr_list/__init__.py

@@ -0,0 +1,3 @@
+"""Configurable GitHub pull-request monitor."""
+
+__version__ = "0.2.0"

gh_prlist-0.2.0/pr_list/__main__.py

@@ -0,0 +1,4 @@
+from pr_list.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

gh_prlist-0.2.0/pr_list/ci.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from collections import Counter
+
+from pr_list.models import Check
+
+# Check names whose failure should not block "green".
+# Add substrings here if a workflow is noisy (e.g. deploy callbacks).
+NON_BLOCKING_FAILURE_SUBSTRINGS: tuple[str, ...] = ()
+
+PASS_STATES = frozenset({"pass", "passing", "success", "skip", "skipping", "neutral"})
+PENDING_STATES = frozenset({"pending", "queued", "in_progress", "in progress"})
+FAIL_STATES = frozenset({"fail", "failure", "cancelled", "canceled", "timed_out", "action_required"})
+
+
+def parse_checks_output(text: str) -> list[Check]:
+    """Parse `gh pr checks` TSV (name, state, ...)."""
+    checks: list[Check] = []
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("no checks"):
+            continue
+        parts = line.split("\t")
+        if len(parts) < 2:
+            continue
+        name, state = parts[0].strip(), parts[1].strip().lower()
+        if not name or not state:
+            continue
+        checks.append(Check(name=name, state=state))
+    return checks
+
+
+def _is_non_blocking_failure(name: str) -> bool:
+    lowered = name.lower()
+    return any(token.lower() in lowered for token in NON_BLOCKING_FAILURE_SUBSTRINGS)
+
+
+def summarize(checks: list[Check]) -> str:
+    counts = Counter(check.state for check in checks)
+    parts = [f"{state}={n}" for state, n in sorted(counts.items())]
+    return ", ".join(parts) if parts else "no checks"
+
+
+def is_failing(checks: list[Check]) -> bool:
+    """True when at least one non-ignored check failed. Pending-only is not failing."""
+    return any(
+        check.state in FAIL_STATES and not _is_non_blocking_failure(check.name)
+        for check in checks
+    )
+
+
+def failing_names(checks: list[Check], *, limit: int = 5) -> list[str]:
+    names: list[str] = []
+    seen: set[str] = set()
+    for check in checks:
+        if check.state not in FAIL_STATES or _is_non_blocking_failure(check.name):
+            continue
+        if check.name in seen:
+            continue
+        seen.add(check.name)
+        names.append(check.name)
+        if len(names) >= limit:
+            break
+    return names
+
+
+def is_green(checks: list[Check]) -> bool:
+    """True when nothing is pending and every remaining check passed or skipped.
+
+    No checks at all is not green — we cannot prove CI ran.
+    """
+    if not checks:
+        return False
+
+    for check in checks:
+        if check.state in PASS_STATES:
+            continue
+        if check.state in PENDING_STATES:
+            return False
+        if check.state in FAIL_STATES:
+            if _is_non_blocking_failure(check.name):
+                continue
+            return False
+        return False
+    return True

gh_prlist-0.2.0/pr_list/cli.py

@@ -0,0 +1,413 @@
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from pr_list import __version__
+from pr_list.config import (
+    CI_POLICIES,
+    CONFIG_PATH,
+    MERGE_POLICIES,
+    Config,
+    ConfigError,
+    interactive_setup,
+    load_config,
+    parse_interval,
+    write_config,
+)
+from pr_list.formatters import as_snapshot_json, as_snapshot_table
+from pr_list.github import (
+    GhError,
+    attach_ci,
+    ensure_gh,
+    merge_unique,
+    search_authored_prs,
+    search_team_review_prs,
+)
+from pr_list.models import PullRequest, Snapshot
+from pr_list.report import write_report
+from pr_list.watch import run_watch
+
+
+@dataclass
+class Runtime:
+    config: Config
+    sources: set[str]
+    json: bool
+    show_rejected: bool
+    notifications: bool
+    notify_on_change: bool
+    notification_sources: set[str]
+    interval_seconds: int
+    html: bool
+    html_path: Path
+    state_path: Path
+
+
+def _add_source_flags(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--own",
+        action="store_true",
+        help="Run only/also the configured own-PR source",
+    )
+    parser.add_argument(
+        "--team",
+        action="store_true",
+        help="Run only/also the configured team-review source",
+    )
+
+
+def _add_common_flags(parser: argparse.ArgumentParser, *, monitor: bool) -> None:
+    _add_source_flags(parser)
+    parser.add_argument("--owner", help="Override github.owner")
+    parser.add_argument("--author", help="Override github.author")
+    parser.add_argument("--reviewer", help="Override github.reviewer")
+    parser.add_argument("--limit", type=int, help="Override github.limit")
+    parser.add_argument("--workers", type=int, help="Override github.workers")
+    parser.add_argument("--own-ci", choices=sorted(CI_POLICIES))
+    parser.add_argument("--team-ci", choices=sorted(CI_POLICIES))
+    parser.add_argument("--own-mergeable", choices=sorted(MERGE_POLICIES))
+    parser.add_argument("--team-mergeable", choices=sorted(MERGE_POLICIES))
+    parser.add_argument(
+        "--own-drafts",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Include/exclude draft own PRs",
+    )
+    parser.add_argument(
+        "--team-drafts",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Include/exclude draft team PRs",
+    )
+    parser.add_argument(
+        "--json",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Print JSON",
+    )
+    parser.add_argument(
+        "--show-rejected",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Show team PRs filtered out by CI policy",
+    )
+    parser.add_argument(
+        "--html",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Write the HTML report",
+    )
+    parser.add_argument("--html-path", type=Path, help="Override report path")
+    parser.add_argument(
+        "--open",
+        action="store_true",
+        dest="open_report",
+        help="Open the HTML report after a one-shot list",
+    )
+    if monitor:
+        parser.add_argument("--interval", help="Override monitor interval")
+        parser.add_argument(
+            "--notifications",
+            action=argparse.BooleanOptionalAction,
+            default=None,
+            help="Enable/disable notifications",
+        )
+        parser.add_argument(
+            "--notify-on-change",
+            action=argparse.BooleanOptionalAction,
+            default=None,
+            help="Notify only when results changed since the last notification",
+        )
+        parser.add_argument(
+            "--notify-own",
+            action=argparse.BooleanOptionalAction,
+            default=None,
+            help="Include/exclude own PRs from notifications",
+        )
+        parser.add_argument(
+            "--notify-team",
+            action=argparse.BooleanOptionalAction,
+            default=None,
+            help="Include/exclude team PRs from notifications",
+        )
+        parser.add_argument("--state-path", type=Path, help="Notification state path")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="gh-prlist",
+        description="Configurable own-PR and team-review monitor.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument(
+        "--config",
+        type=Path,
+        default=CONFIG_PATH,
+        help=f"Config file (default: {CONFIG_PATH})",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    setup = sub.add_parser("setup", help="Interactively create or update configuration")
+    setup.add_argument(
+        "--config",
+        type=Path,
+        dest="command_config",
+        help="Config file (default: ~/.prlist)",
+    )
+
+    listing = sub.add_parser("list", help="List configured PR sources once")
+    _add_common_flags(listing, monitor=False)
+
+    monitor = sub.add_parser("monitor", help="Monitor and notify continuously")
+    _add_common_flags(monitor, monitor=True)
+    return parser
+
+
+def _normalize_legacy(argv: list[str]) -> list[str]:
+    commands = {"setup", "list", "monitor"}
+    if not argv or argv[0] in {"-h", "--help", "--version"} or commands.intersection(argv):
+        return argv
+    translated: list[str] = []
+    index = 0
+    while index < len(argv):
+        item = argv[index]
+        if item == "--include-drafts":
+            translated.append("--team-drafts")
+        elif item == "--no-green-ci":
+            translated.extend(["--team-ci", "any"])
+        elif item == "--no-mine-failing":
+            translated.append("--team")
+        else:
+            translated.append(item)
+        index += 1
+
+    root: list[str] = []
+    if len(translated) >= 2 and translated[0] == "--config":
+        root, translated = translated[:2], translated[2:]
+    if "--watch" in translated:
+        return [
+            *root,
+            "monitor",
+            *[item for item in translated if item != "--watch"],
+        ]
+    # Old invocations had no `list` subcommand.
+    return [*root, "list", *translated]
+
+
+def _override(value, fallback):
+    return fallback if value is None else value
+
+
+def resolve_runtime(args: argparse.Namespace, config: Config) -> Runtime:
+    config.github.owner = _override(args.owner, config.github.owner)
+    config.github.author = _override(args.author, config.github.author)
+    config.github.reviewer = _override(args.reviewer, config.github.reviewer)
+    config.github.limit = _override(args.limit, config.github.limit)
+    config.github.workers = _override(args.workers, config.github.workers)
+    config.own.ci = _override(args.own_ci, config.own.ci)
+    config.team.ci = _override(args.team_ci, config.team.ci)
+    config.own.mergeable = _override(
+        args.own_mergeable, config.own.mergeable
+    )
+    config.team.mergeable = _override(
+        args.team_mergeable, config.team.mergeable
+    )
+    config.own.include_drafts = _override(
+        args.own_drafts, config.own.include_drafts
+    )
+    config.team.include_drafts = _override(
+        args.team_drafts, config.team.include_drafts
+    )
+
+    explicit_sources = {
+        name for name in ("own", "team") if getattr(args, name, False)
+    }
+    sources = explicit_sources or {
+        name
+        for name in ("own", "team")
+        if getattr(config, name).enabled
+    }
+
+    monitor_command = args.command == "monitor"
+    interval = (
+        _override(getattr(args, "interval", None), config.monitor.interval)
+        if monitor_command
+        else config.monitor.interval
+    )
+    notification_sources = set(config.monitor.notification_sources)
+    for name in ("own", "team"):
+        override = getattr(args, f"notify_{name}", None)
+        if override is True:
+            notification_sources.add(name)
+        elif override is False:
+            notification_sources.discard(name)
+    notification_sources &= sources
+
+    html = _override(args.html, config.monitor.html if monitor_command else False)
+    return Runtime(
+        config=config,
+        sources=sources,
+        json=_override(args.json, config.output.json),
+        show_rejected=_override(
+            args.show_rejected, config.output.show_rejected
+        ),
+        notifications=_override(
+            getattr(args, "notifications", None), config.monitor.notifications
+        ),
+        notify_on_change=_override(
+            getattr(args, "notify_on_change", None),
+            config.monitor.notify_on_change,
+        ),
+        notification_sources=notification_sources,
+        interval_seconds=parse_interval(interval),
+        html=html,
+        html_path=Path(
+            _override(args.html_path, config.monitor.html_path)
+        ).expanduser(),
+        state_path=Path(
+            _override(getattr(args, "state_path", None), config.monitor.state_path)
+        ).expanduser(),
+    )
+
+
+def _matches(pr: PullRequest, ci_policy: str, merge_policy: str) -> bool:
+    ci_matches = (
+        bool(pr.ci_green)
+        if ci_policy == "green"
+        else pr.ci_failing
+        if ci_policy == "failing"
+        else True
+    )
+    merge_matches = (
+        pr.mergeable == "CONFLICTING"
+        if merge_policy == "conflicting"
+        else pr.mergeable != "CONFLICTING"
+        if merge_policy == "not_conflicting"
+        else True
+    )
+    return ci_matches and merge_matches
+
+
+def collect_snapshot(runtime: Runtime) -> Snapshot:
+    config = runtime.config
+    own: list[PullRequest] = []
+    team: list[PullRequest] = []
+    if "own" in runtime.sources:
+        own = search_authored_prs(
+            owner=config.github.owner,
+            author=config.github.author,
+            include_drafts=config.own.include_drafts,
+            limit=config.github.limit,
+        )
+    if "team" in runtime.sources:
+        team = search_team_review_prs(
+            owner=config.github.owner,
+            reviewer=config.github.reviewer,
+            include_drafts=config.team.include_drafts,
+            limit=config.github.limit,
+        )
+
+    checked = attach_ci(
+        merge_unique([own, team]), workers=config.github.workers
+    )
+    by_url = {pr.url: pr for pr in checked}
+    evaluated_team = [by_url[pr.url] for pr in team]
+    return Snapshot(
+        own=[
+            by_url[pr.url]
+            for pr in own
+            if _matches(
+                by_url[pr.url], config.own.ci, config.own.mergeable
+            )
+        ],
+        team=[
+            pr
+            for pr in evaluated_team
+            if _matches(pr, config.team.ci, config.team.mergeable)
+        ],
+        evaluated_team=evaluated_team,
+        show_ci=True,
+    )
+
+
+def _setup(args: argparse.Namespace) -> int:
+    path = (args.command_config or args.config).expanduser()
+    current = load_config(path)
+    config = interactive_setup(current, input_fn=input, output=sys.stdout)
+    written = write_config(config, path)
+    print(f"Config written: {written}")
+    notifier = shutil.which("terminal-notifier")
+    if config.monitor.notifications:
+        if notifier:
+            print(f"Clickable notifications enabled via {notifier}.")
+        else:
+            print(
+                "Notifications will use osascript; install terminal-notifier "
+                "for a clickable Show action."
+            )
+    print("Run: gh-prlist monitor")
+    return 0
+
+
+def _print_snapshot(snapshot: Snapshot, runtime: Runtime) -> None:
+    print(
+        as_snapshot_json(snapshot)
+        if runtime.json
+        else as_snapshot_table(snapshot)
+    )
+    if runtime.show_rejected:
+        for pr in snapshot.rejected:
+            print(
+                f"filtered team {pr.repo}#{pr.number}: {pr.ci_summary}",
+                file=sys.stderr,
+            )
+
+
+def _run_once(args: argparse.Namespace, runtime: Runtime) -> int:
+    snapshot = collect_snapshot(runtime)
+    _print_snapshot(snapshot, runtime)
+    if runtime.html or args.open_report:
+        written = write_report(snapshot, runtime.html_path)
+        print(f"report: {written}", file=sys.stderr)
+        if args.open_report:
+            subprocess.run(["open", str(written)], check=False)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    raw = sys.argv[1:] if argv is None else argv
+    args = build_parser().parse_args(_normalize_legacy(list(raw)))
+    if args.command is None:
+        build_parser().print_help()
+        return 0
+    try:
+        if args.command == "setup":
+            return _setup(args)
+        config = load_config(args.config)
+        runtime = resolve_runtime(args, config)
+        ensure_gh()
+        if args.command == "list":
+            return _run_once(args, runtime)
+        try:
+            return run_watch(
+                collect=lambda: collect_snapshot(runtime),
+                interval_seconds=runtime.interval_seconds,
+                as_json_output=runtime.json,
+                notifications=runtime.notifications,
+                notify_on_change=runtime.notify_on_change,
+                notification_sources=runtime.notification_sources,
+                stdout=sys.stdout,
+                html_path=runtime.html_path if runtime.html else None,
+                state_path=runtime.state_path,
+            )
+        except KeyboardInterrupt:
+            print("\nstopped", file=sys.stderr)
+            return 0
+    except (ConfigError, GhError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1