queue-watch 0.1.0__py3-none-any.whl

queue_watch/changes.py

@@ -0,0 +1,181 @@
+"""Changes: records from every source that describe the same branch or commit.
+
+Records correlate by ``ref`` and fall back to ``sha``; records with neither stay
+in their source's own tab. Kinds with a role in a change: ``run`` (CI),
+``queue_entry`` (live merge queue position) and ``attempt`` (a finished merge
+attempt). Other kinds are only shown per source.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import NamedTuple
+
+# Worst first: decides the one state that represents a whole change.
+PRIORITY = ("failure", "blocked", "running", "queued", "cancelled", "success", "neutral", "unknown")
+GROUPS = (
+    ("attention", "Needs attention", "blocked"),
+    ("running", "Running", "running"),
+    ("queued", "Queued", "queued"),
+    ("done", "Done", "success"),
+)
+TIME_KEYS = ("created_at", "updated_at", "started_at", "finished_at")
+ROLES = frozenset({"run", "queue_entry", "attempt"})
+
+
+class Hit(NamedTuple):
+    """One record and the id of the source that reported it."""
+
+    source: str
+    record: dict
+
+
+def worst(states: list[str]) -> str | None:
+    return min(states, key=PRIORITY.index, default=None)
+
+
+def stamp(record: dict, *keys: str) -> float:
+    """Latest of ``keys`` (all timestamps by default) as epoch seconds; 0 if none."""
+    times = [
+        datetime.fromisoformat(record[key]).timestamp()
+        for key in keys or TIME_KEYS
+        if record.get(key)
+    ]
+    return max(times, default=0.0)
+
+
+@dataclass
+class Change:
+    key: str
+    ref: str | None = None
+    sha: str | None = None
+    runs: list[Hit] = field(default_factory=list)  # newest first
+    entries: list[Hit] = field(default_factory=list)  # queue order
+    attempts: list[Hit] = field(default_factory=list)  # newest first
+
+    @property
+    def entry(self) -> Hit | None:
+        return self.entries[0] if self.entries else None
+
+    @property
+    def checks(self) -> list[Hit]:
+        """The newest run of each workflow: what CI currently says about this change."""
+        latest: dict[tuple[str, str], Hit] = {}
+        for hit in self.runs:
+            latest.setdefault((hit.source, hit.record["title"]), hit)
+        return list(latest.values())
+
+    @property
+    def ci_state(self) -> str | None:
+        return worst([hit.record["state"] for hit in self.checks])
+
+    @property
+    def live_states(self) -> list[str]:
+        states = [self.ci_state] if self.runs else []
+        return states + ([self.entry.record["state"]] if self.entry else [])
+
+    @property
+    def state(self) -> str:
+        if self.live_states:
+            return worst(self.live_states)
+        return self.attempts[0].record["state"] if self.attempts else "unknown"
+
+    @property
+    def group(self) -> str:
+        live = set(self.live_states)
+        if live & {"failure", "blocked"}:
+            return "attention"
+        if "running" in live:
+            return "running"
+        if "queued" in live:
+            return "queued"
+        return "done"
+
+    @property
+    def title(self) -> str:
+        for hit in (self.entry, *self.attempts):
+            if hit:
+                return re.sub(r"^#\d+\s+", "", hit.record["title"])
+        newest = self.runs[0].record if self.runs else {}
+        return newest.get("subtitle") or newest.get("title") or self.key
+
+    @property
+    def pr(self) -> int | None:
+        if self.entry and isinstance(
+            number := (self.entry.record.get("fields") or {}).get("pull_request"), int
+        ):
+            return number
+        for hit in (self.entry, *self.attempts):
+            if hit and (match := re.match(r"#(\d+)\b", hit.record["title"])):
+                return int(match.group(1))
+        return None
+
+    @property
+    def owner(self) -> str | None:
+        for hit in (self.entry, *self.attempts, *self.runs):
+            if hit and hit.record.get("owner"):
+                return hit.record["owner"]
+        return None
+
+    @property
+    def url(self) -> str | None:
+        for hit in (self.entry, *self.runs, *self.attempts):
+            if hit and hit.record.get("url"):
+                return hit.record["url"]
+        return None
+
+    @property
+    def activity(self) -> float:
+        hits = (*self.runs, *self.entries, *self.attempts)
+        return max((stamp(hit.record) for hit in hits), default=0.0)
+
+
+def correlate(snapshots: dict[str, dict]) -> list[Change]:
+    """One Change per ref (falling back to sha), in merge order, then most recent."""
+    by_ref: dict[str, Change] = {}
+    by_sha: dict[str, Change] = {}
+    changes: list[Change] = []
+    for source, snapshot in snapshots.items():
+        for record in snapshot.get("records", []):
+            ref, sha = record.get("ref"), record.get("sha")
+            if record["kind"] not in ROLES or not (ref or sha):
+                continue
+            change = (ref and by_ref.get(ref)) or (sha and by_sha.get(sha))
+            if not change:
+                change = Change(key=ref or sha)
+                changes.append(change)
+            if ref:
+                by_ref.setdefault(ref, change)
+                change.ref = change.ref or ref
+            if sha:
+                by_sha.setdefault(sha, change)
+                change.sha = change.sha or sha
+            hit = Hit(source, record)
+            match record["kind"]:
+                case "run":
+                    change.runs.append(hit)
+                case "queue_entry":
+                    change.entries.append(hit)
+                case "attempt":
+                    change.attempts.append(hit)
+    for change in changes:
+        change.runs.sort(key=lambda hit: stamp(hit.record, "created_at"), reverse=True)
+        change.entries.sort(key=lambda hit: position(hit.record))
+        change.attempts.sort(key=lambda hit: stamp(hit.record), reverse=True)
+    changes.sort(key=lambda c: (position(c.entry.record) if c.entry else 1e9, -c.activity))
+    return changes
+
+
+def position(record: dict) -> float:
+    value = record.get("position")
+    return value if isinstance(value, int) else 1e9
+
+
+def grouped(changes: list[Change]) -> list[tuple[str, str, str, list[Change]]]:
+    """(key, label, representative state, changes) per group, in display order."""
+    return [
+        (key, label, state, [change for change in changes if change.group == key])
+        for key, label, state in GROUPS
+    ]

queue_watch/cli.py

@@ -0,0 +1,129 @@
+"""queue-watch: read-only terminal dashboard for CI runs and merge queues.
+
+Click tabs, rows, filters and toolbar buttons; scroll tables and the inspector
+with the wheel. Keyboard: tab/arrows, / search, r refresh, p pause, o open the
+selected record, q quit. Times are shown in America/Los_Angeles.
+
+With no source flags, queue-watch uses the repository's .queue-watch.toml once
+you have trusted it, and otherwise the current checkout's GitHub repository:
+Actions, plus the merge queue when the default branch has one. Nothing is ever
+changed: no reruns, cancellations, merges, lock acquisition or remote installs.
+Last good data stays visible on failure and is labelled stale. --once prints one
+JSON snapshot per source and exits nonzero when any source fails.
+
+Examples:
+  queue-watch                               # inside a GitHub checkout
+  queue-watch --repo owner/repo
+  queue-watch --profile work                # ~/.config/queue-watch/work.toml
+  queue-watch --config sources.toml --once
+  queue-watch trust                         # after reviewing .queue-watch.toml
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+
+from . import __version__
+from .config import ConfigError, Source, load
+from .discovery import CONFIG_NAME, detect, github_sources, profile_path, repo_config, trust
+
+
+async def once(sources: list[Source]) -> int:
+    results = await asyncio.gather(
+        *(source.snapshot() for source in sources), return_exceptions=True
+    )
+    output = {"observed_at": datetime.now(UTC).isoformat(), "sources": {}}
+    failed = False
+    for source, result in zip(sources, results, strict=True):
+        entry = {"adapter": source.adapter.name, "label": source.label}
+        if isinstance(result, BaseException):
+            entry["error"] = str(result) or type(result).__name__
+            failed = True
+        else:
+            entry["snapshot"] = result
+        output["sources"][source.id] = entry
+    print(json.dumps(output, indent=2))
+    return int(failed)
+
+
+def trust_command(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        prog="queue-watch trust",
+        description=f"Trust a repository's {CONFIG_NAME} after reviewing it. Trust "
+        "covers the file's exact bytes; edits need trusting again.",
+    )
+    parser.add_argument("path", nargs="?", type=Path, help=f"default: the checkout's {CONFIG_NAME}")
+    args = parser.parse_args(argv)
+    path = args.path or repo_config(Path.cwd())
+    if path is None:
+        parser.error(f"no {CONFIG_NAME} at the root of this Git checkout")
+    try:
+        sources = trust(path)
+    except (OSError, UnicodeDecodeError, ConfigError) as error:
+        parser.error(str(error))
+    print(f"Trusted {path.resolve()}")
+    for source in sources:
+        print(f"  {source.id}: {source.adapter.name} ({source.label})")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    if argv[:1] == ["trust"]:
+        return trust_command(argv[1:])
+    parser = argparse.ArgumentParser(
+        prog="queue-watch",
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"queue-watch {__version__}")
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument("--repo", help="GitHub owner/repo: Actions plus any merge queue")
+    group.add_argument("--config", type=Path, help="TOML file with [[source]] tables")
+    group.add_argument("--profile", help="NAME for ~/.config/queue-watch/NAME.toml")
+    parser.add_argument("--once", action="store_true", help="print JSON once; no TUI")
+    parser.add_argument(
+        "--theme", default="tokyo-night", help="Textual theme (default tokyo-night)"
+    )
+    parser.add_argument("--ascii", action="store_true", help="ASCII glyphs and borders only")
+    parser.add_argument(
+        "--density",
+        choices=("compact", "comfortable"),
+        default="compact",
+        help="change rows: compact one-line, or comfortable with title, owner and PR "
+        "on a second line (press d to switch)",
+    )
+    args = parser.parse_args(argv)
+    try:
+        if args.config:
+            sources = load(args.config.expanduser())
+        elif args.profile:
+            sources = load(profile_path(args.profile))
+        elif args.repo:
+            sources = asyncio.run(github_sources(args.repo))
+        else:
+            sources = asyncio.run(detect(Path.cwd()))
+    except (ConfigError, OSError, UnicodeDecodeError) as error:
+        parser.error(str(error))
+    if args.once:
+        return asyncio.run(once(sources))
+    if not sys.stdin.isatty() or not sys.stdout.isatty():
+        parser.error("interactive mode needs a terminal; use --once for JSON")
+    from .app import QueueWatch
+
+    app = QueueWatch(sources, theme=args.theme, ascii=args.ascii, density=args.density)
+    if args.theme not in app.available_themes:
+        parser.error(
+            f"unknown theme {args.theme!r}; choose from {', '.join(sorted(app.available_themes))}"
+        )
+    app.run(mouse=True)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

queue_watch/config.py

@@ -0,0 +1,105 @@
+"""Sources: configured adapter instances, loaded from TOML or command-line flags.
+
+[[source]]
+id = "ci"                     # unique; required
+adapter = "github-actions"    # required; see queue_watch.adapters.registry()
+label = "CI"                  # optional; defaults to the adapter's label
+interval = 15                 # optional refresh seconds
+repo = "owner/repo"           # every other key is an adapter option
+"""
+
+from __future__ import annotations
+
+import inspect
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+from .adapters import Adapter, registry
+from .model import validate_snapshot
+
+
+class ConfigError(ValueError):
+    """The source configuration cannot be used."""
+
+
+@dataclass
+class Source:
+    id: str
+    label: str
+    interval: float
+    adapter: Adapter
+
+    async def snapshot(self) -> dict:
+        return validate_snapshot(await self.adapter.snapshot())
+
+
+INJECTED = frozenset({"config_dir"})
+
+
+def build(entry: dict, where: str, config_dir: Path | None = None) -> Source:
+    options = dict(entry)
+    source_id = options.pop("id", None)
+    name = options.pop("adapter", None)
+    if not isinstance(source_id, str) or not source_id:
+        raise ConfigError(f"{where}: id must be a non-empty string")
+    adapters = registry()
+    if name not in adapters:
+        raise ConfigError(
+            f"{where}: adapter must be one of {', '.join(sorted(adapters))}, got {name!r}"
+        )
+    kind = adapters[name]
+    label = options.pop("label", kind.label)
+    interval = options.pop("interval", kind.interval)
+    if not isinstance(interval, (int, float)) or isinstance(interval, bool) or interval < 1:
+        raise ConfigError(f"{where}: interval must be a number of seconds >= 1")
+    parameters = inspect.signature(kind.__init__).parameters
+    accepted = {key: p for key, p in parameters.items() if key not in {"self", *INJECTED}}
+    unknown = sorted(set(options) - set(accepted))
+    if unknown:
+        raise ConfigError(
+            f"{where}: {name} does not accept {', '.join(unknown)}; "
+            f"options are {', '.join(accepted)}"
+        )
+    missing = [
+        key
+        for key, parameter in accepted.items()
+        if parameter.default is inspect.Parameter.empty and key not in options
+    ]
+    if missing:
+        raise ConfigError(f"{where}: {name} needs {', '.join(missing)}")
+    if "config_dir" in parameters:
+        options["config_dir"] = config_dir
+    try:
+        adapter = kind(**options)
+    except (TypeError, ValueError) as error:
+        raise ConfigError(f"{where}: {error}") from error
+    return Source(source_id, str(label), float(interval), adapter)
+
+
+def load(path: Path) -> list[Source]:
+    try:
+        text = path.read_text()
+    except OSError as error:
+        raise ConfigError(f"{path}: {error}") from error
+    return parse(text, path)
+
+
+def parse(text: str, path: Path) -> list[Source]:
+    """Sources from TOML ``text`` that was read from ``path``."""
+    try:
+        data = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as error:
+        raise ConfigError(f"{path}: {error}") from error
+    entries = data.get("source")
+    if not isinstance(entries, list) or not entries:
+        raise ConfigError(f"{path}: define at least one [[source]] table")
+    sources = [
+        build(entry, f"{path} source {index + 1}", path.parent.resolve())
+        for index, entry in enumerate(entries)
+    ]
+    ids = [source.id for source in sources]
+    duplicates = sorted({source_id for source_id in ids if ids.count(source_id) > 1})
+    if duplicates:
+        raise ConfigError(f"{path}: duplicate source id {', '.join(duplicates)}")
+    return sources

queue_watch/discovery.py

@@ -0,0 +1,149 @@
+"""Where sources come from when no --repo or --config is given.
+
+Order: a repository's own ``.queue-watch.toml`` (only once trusted), then the
+GitHub repository of the current checkout (Actions, plus its merge queue when the
+default branch has one).
+
+A repository config can run commands and open SSH connections, so a fresh clone
+must not be able to do either on its own. ``queue-watch trust`` records the
+SHA-256 of the file's exact bytes; any later edit needs trusting again, like
+``direnv allow``. Files passed with --config or --profile are the user's own and
+are trusted implicitly.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+
+from .config import ConfigError, Source, build, parse
+
+CONFIG_NAME = ".queue-watch.toml"
+
+
+def state_dir() -> Path:
+    base = os.environ.get("XDG_STATE_HOME") or Path.home() / ".local" / "state"
+    return Path(base) / "queue-watch"
+
+
+def profile_path(name: str) -> Path:
+    if not name or "/" in name or name.startswith("."):
+        raise ConfigError(f"profile must be a plain name, got {name!r}")
+    base = os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config"
+    return Path(base) / "queue-watch" / f"{name}.toml"
+
+
+def git_root(cwd: Path) -> Path | None:
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(cwd), "rev-parse", "--show-toplevel"],
+            capture_output=True,
+            check=False,
+            text=True,
+            timeout=10,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    return Path(result.stdout.strip()) if result.returncode == 0 else None
+
+
+def repo_config(cwd: Path) -> Path | None:
+    root = git_root(cwd)
+    if root is None:
+        return None
+    path = root / CONFIG_NAME
+    return path if path.is_file() else None
+
+
+def _store() -> Path:
+    return state_dir() / "trusted.json"
+
+
+def _trusted() -> dict[str, str]:
+    try:
+        data = json.loads(_store().read_text())
+    except (OSError, ValueError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def digest(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def trust(path: Path) -> list[Source]:
+    """Validate ``path`` and record its current bytes as trusted."""
+    path = path.resolve()
+    data = path.read_bytes()
+    sources = parse(data.decode(), path)  # Never trust a file that cannot load.
+    trusted = _trusted()
+    trusted[str(path)] = digest(data)
+    store = _store()
+    store.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile("w", dir=store.parent, delete=False) as handle:
+        json.dump(trusted, handle, indent=2, sort_keys=True)
+    os.replace(handle.name, store)
+    return sources
+
+
+def load_trusted(path: Path) -> list[Source]:
+    """Load a repository config only if these exact bytes were trusted."""
+    path = path.resolve()
+    data = path.read_bytes()  # Check and parse the same bytes.
+    recorded = _trusted().get(str(path))
+    if recorded != digest(data):
+        state = "changed since it was trusted" if recorded else "is not trusted yet"
+        raise ConfigError(
+            f"{path} {state}. It can run commands and open SSH connections. "
+            "Review it, then run: queue-watch trust"
+        )
+    return parse(data.decode(), path)
+
+
+def github_repo(cwd: Path) -> str | None:
+    try:
+        result = subprocess.run(
+            ["gh", "repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"],
+            capture_output=True,
+            check=False,
+            text=True,
+            timeout=20,
+            cwd=cwd,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    name = result.stdout.strip()
+    return name if result.returncode == 0 and name else None
+
+
+async def detect(cwd: Path) -> list[Source]:
+    path = repo_config(cwd)
+    if path is not None:
+        return load_trusted(path)
+    repo = github_repo(cwd)
+    if repo is None:
+        raise ConfigError(
+            "no sources found: not inside a GitHub checkout with an authenticated gh, "
+            f"and no {CONFIG_NAME}. Pass --repo, --config or --profile."
+        )
+    return await github_sources(repo)
+
+
+async def github_sources(repo: str) -> list[Source]:
+    """Actions for ``repo``, plus its merge queue when the default branch has one."""
+    from .adapters.github_merge_queue import has_queue
+
+    sources = [build({"id": "ci", "adapter": "github-actions", "repo": repo}, repo)]
+    try:
+        queued = await has_queue(repo)
+    except (OSError, RuntimeError, ValueError, KeyError) as error:
+        raise ConfigError(f"cannot check {repo} for a merge queue: {error}") from error
+    if queued:
+        sources.append(
+            build({"id": "merge-queue", "adapter": "github-merge-queue", "repo": repo}, repo)
+        )
+    return sources