stackvitals 0.1.0__py3-none-any.whl

mergescout/tool/queries.py

@@ -0,0 +1,293 @@
+import json
+import re
+import sqlite3
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from mergescout.labels import BEGINNER, norm_label
+from mergescout.signals.rules import TRIAGE_LABEL_PATTERN
+
+# Letters and digits only, like the index's tokenizer: "snake_case" quoted whole is a phrase, which detail=column rejects.
+WORD = re.compile(r"[^\W_]+")
+STOP = {"the", "and", "for", "with", "to", "of", "in", "on", "an", "is", "it", "be", "or", "not", "this", "that",
+        "from", "by", "at", "as"}
+NOTE = "Availability is from the snapshot; call check_issue before telling someone an issue is free."
+PARTS = {"availability": "p_avail", "outsider_merge": "p_merge", "reply": "p_reply", "fixed_before": "p_fixed",
+         "issue_quality": "p_quality", "multiplier": "mult"}
+# Real queries (2026-10-16): "database" missed issues titled "SQLite lock" or "Postgres timeout".
+_DB = ("db", "sql", "sqlite", "postgres", "postgresql", "mysql", "mongodb", "redis", "orm")
+_DOCS = ("doc", "docs", "documentation", "readme", "typo", "tutorial", "guide")
+SYNONYMS = {"database": _DB, "db": _DB, "sql": _DB, "doc": _DOCS, "docs": _DOCS, "documentation": _DOCS,
+            "test": ("tests", "testing", "pytest", "unittest", "coverage"), "testing": ("test", "tests", "pytest"),
+            "cli": ("command", "terminal", "flag", "subcommand"), "ui": ("frontend", "css", "component", "layout"),
+            "frontend": ("ui", "css", "component"), "api": ("endpoint", "rest", "http"),
+            "auth": ("login", "oauth", "authentication"), "login": ("auth", "oauth", "signin"),
+            # Not "cache" or "memory": real titles use them for features ("X-Cache header", "load into memory").
+            "performance": ("slow", "speed", "perf", "latency", "optimize", "benchmark"),
+            "perf": ("performance", "slow")}
+
+
+def fts_words(text: str | None) -> list[str]:
+    return list(dict.fromkeys(w.lower() for w in WORD.findall(text or "") if len(w) >= 2 and w.lower() not in STOP))
+
+
+def fts_query(text: str | None, synonyms: bool = False) -> str | None:
+    # Every word becomes a quoted term, so search syntax in user text is never interpreted.
+    words = fts_words(text)
+    if synonyms:
+        plural = lambda w: SYNONYMS.get(w[:-1], ()) if w.endswith("s") else ()
+        words = list(dict.fromkeys(words + [s for w in words for s in SYNONYMS.get(w, plural(w))]))
+    return " OR ".join(f'"{w}"' for w in words) or None
+
+
+def parts(r: dict) -> dict:
+    return {name: None if r[col] is None else round(r[col], 3) for name, col in PARTS.items()}
+
+
+def _pct(x) -> int:
+    return round((x or 0) * 100)
+
+
+def _days(d) -> str:
+    return "less than a day" if not d else "the last day" if d == 1 else f"the last {d} days"
+
+
+def _rate(merged, decided, rate, low, high, enough, r: dict, who: str) -> str:
+    if not enough:
+        return f"not enough evidence yet ({decided} decided {who})"
+    # Users read "last 4 days" as a slow repo; say plainly that a busy repo's newest PRs cover a short time.
+    span = (f" over {_days(r['window_days'])}" if r["window_complete"]
+            else f", from the newest 300 PRs, which cover only {_days(r['window_days'])}")
+    return f"{_pct(rate)}% of {who} merged ({merged} of {decided}, likely {_pct(low)}-{_pct(high)}%){span}"
+
+
+def rate_text(r: dict) -> str:
+    merged = r["merged"] or 0
+    return _rate(merged, merged + (r["closed"] or 0), r["merge_rate"], r["merge_low"], r["merge_high"],
+                 r["merge_enough"], r, "outsider PRs")
+
+
+def newcomer_text(r: dict) -> str:
+    return _rate(r["newcomer_merged"] or 0, r["newcomer_decided"] or 0, r["newcomer_rate"], r["newcomer_low"],
+                 r["newcomer_high"], r["newcomer_enough"], r, "first PRs by newcomers")
+
+
+def review_text(r: dict) -> str:
+    if not r["review_enough"]:
+        return f"review time: not enough evidence yet ({r['reviewed'] or 0} maintainer reviews)"
+    h = r["median_review_hours"]
+    return f"maintainers usually first review outsider PRs within ~{h:.1f} h (median of {r['reviewed']})"
+
+
+class Snapshot:
+    def __init__(self, path: Path):
+        self.db = sqlite3.connect(Path(path).resolve().as_uri() + "?mode=ro", uri=True, check_same_thread=False)
+        self.db.row_factory = sqlite3.Row
+        self.meta = dict(self.db.execute("SELECT key, value FROM meta").fetchall())
+        self.built_at = self.meta.get("built_at")
+        # Files from schema 1.0 have no beginner column; "help wanted" then still counts as beginner.
+        cols = {c[1] for c in self.db.execute("PRAGMA table_info(issues)")}
+        self.beginner_col = "beginner" if "beginner" in cols else "opportunity"
+
+    def _days_since(self, ts: str | None) -> int | None:
+        if not ts or not self.built_at:
+            return None
+        return (datetime.fromisoformat(self.built_at.replace("Z", "+00:00"))
+                - datetime.fromisoformat(ts.replace("Z", "+00:00"))).days
+
+    def _rows(self, sql: str, params=()) -> list[dict]:
+        return [dict(r) for r in self.db.execute(sql, params).fetchall()]
+
+    def stats(self) -> dict:
+        free = self.db.execute("SELECT count(*) FROM issues WHERE available = 1").fetchone()[0]
+        langs = self._rows("SELECT language, count(*) AS issues FROM issues WHERE available = 1 AND language IS NOT NULL"
+                           " GROUP BY language ORDER BY 2 DESC LIMIT 15")
+        return {**{k: (int(v) if v.isdigit() else v) for k, v in self.meta.items()}, "free_issues": free,
+                "top_languages": langs}
+
+    def repo(self, name: str) -> dict | None:
+        rows = self._rows("SELECT * FROM repos WHERE name = ? COLLATE NOCASE", (name,))
+        return rows[0] if rows else None
+
+    def _row(self, r: dict, detail: bool) -> dict:
+        walls = [w["wall"] for w in json.loads(r["walls_json"]) if w.get("blocking")]
+        labels = json.loads(r["labels"])
+        names = {norm_label(x) for x in labels}
+        # The shown score is the one the list is sorted by (base score with freshness), so lists read in order.
+        out = {"issue": f"{r['repo']}#{r['number']}", "url": f"https://github.com/{r['repo']}/issues/{r['number']}",
+               "title": r["title"], "labels": labels, "score": round(r["rank_score"], 2),
+               "level": "beginner label" if names & BEGINNER else "help wanted" if "help wanted" in names
+               else "no beginner label",
+               "free": bool(r["available"]), "outsider_merge": rate_text(r), "review": review_text(r),
+               "walls": walls, "updated": (r["updated_at"] or "")[:10]}
+        if r.get("matched"):
+            out["matched"] = r["matched"]
+        untriaged = [x for x in labels if re.search(TRIAGE_LABEL_PATTERN, norm_label(x))]
+        if untriaged and r["available"]:
+            out["warning"] = (f"also labelled '{untriaged[0]}': a maintainer may not have confirmed it yet;"
+                              " ask before starting")
+        if r.get("kind") == "discussion":
+            out["kind"] = "discussion or tracker, not a ready task"
+        if not r["available"]:
+            out["taken"] = r["blocked_by"]
+        days = self._days_since(r["last_claim_at"])
+        if r["claimers"] and days is not None:
+            out["earlier_claims"] = (f"{r['claimers']} person(s) offered to work on it, the last {days} days ago;"
+                                     " ask on the issue before starting")
+        if detail:
+            out.update({"base_score": round(r["score"], 2), "score_parts": parts(r), "notes": json.loads(r["repo_notes"]),
+                        "stars": r["stars"], "dead_ends": r["dead_ends"], "interest_30d": r["interest_30d"],
+                        "body": r["body"]})
+        return out
+
+    def _select(self, where: str, params: dict, order: str, limit: int, join_fts: bool = False) -> list[dict]:
+        fts = "JOIN issues_fts f ON f.rowid = i.rowid" if join_fts else ""
+        return self._rows(f"SELECT i.*, r.name AS repo, r.stars, r.merged, r.closed, r.merge_rate, r.merge_low,"
+                          f" r.merge_high, r.merge_enough, r.window_days, r.window_complete, r.median_review_hours,"
+                          f" r.review_enough, r.reviewed, r.walls_json, r.notes AS repo_notes FROM issues i {fts}"
+                          f" JOIN repos r USING (repo_id)"
+                          f" WHERE {where} ORDER BY {order}" + ("" if limit is None else " LIMIT :limit"),
+                          params if limit is None else {**params, "limit": limit})
+
+    def find_issues(self, language=None, topic=None, beginner_labels_only=False, min_score=0.0, allow_walls=True,
+                    limit=10, detail=False) -> dict:
+        # min_score applies to the score users see in the list (with freshness).
+        where = ["i.available = 1", "i.rank_score >= :min_score"]
+        params = {"min_score": min_score}
+        if language:
+            where.append("i.language = :language")
+            params["language"] = language
+        if beginner_labels_only:
+            where.append(f"i.{self.beginner_col} = 1")
+        if not allow_walls:
+            where.append("r.blocking_walls = 0")
+        q = fts_query(topic, synonyms=True)
+        if topic and not q:
+            return {"snapshot": self.built_at, "results": [],
+                    "note": "The topic had no searchable words (very common words are ignored); try other words."}
+        limit = max(1, min(limit, 50))
+        state = {"seen": {}, "picked": [], "keys": set()}
+        if q:
+            # Real queries (2026-10-16): only 19 of 40 topic results had the topic in the title; those come first.
+            for matched, match in (("title or label", f"{{title labels}} : ({q})"), ("text", q)):
+                self._fill(" AND ".join(where + ["issues_fts MATCH :q"]), {**params, "q": match}, limit, state,
+                           matched)
+        else:
+            self._fill(" AND ".join(where), params, limit, state, None)
+        return {"snapshot": self.built_at, "note": NOTE, "results": [self._row(r, detail) for r in state["picked"]]}
+
+    def _fill(self, where: str, params: dict, limit: int, state: dict, matched: str | None) -> None:
+        # Real data (2026-10-15): one welcoming repo filled the whole top list; show at most 2 per repo.
+        # Pages of the ranked index are read until the list is full, so a dominant repo cannot shorten it.
+        seen, picked, page, offset = state["seen"], state["picked"], limit * 5, 0
+        while len(picked) < limit and offset < 5000:
+            rows = self._select(where, params, f"i.rank_score DESC LIMIT {page} OFFSET {offset}", None,
+                                matched is not None)
+            for r in rows:
+                key = (r["repo_id"], r["number"])
+                if key in state["keys"] or seen.get(r["repo_id"], 0) >= 2 or len(picked) >= limit:
+                    continue
+                seen[r["repo_id"]] = seen.get(r["repo_id"], 0) + 1
+                state["keys"].add(key)
+                picked.append({**r, "matched": matched} if matched else r)
+            if len(rows) < page:
+                break
+            offset += page
+
+    def issue(self, name: str, number: int) -> dict | None:
+        rows = self._select("r.name = :name COLLATE NOCASE AND i.number = :number", {"name": name, "number": number},
+                            "i.number", 1)
+        return rows[0] if rows else None
+
+    def examples(self, repo_id: int) -> list[dict]:
+        return self._rows("SELECT number, merged_at, lines, files, days_to_merge FROM outsider_prs WHERE repo_id = ?"
+                          " ORDER BY merged_at DESC", (repo_id,))
+
+    def explain(self, name: str, number: int) -> dict | None:
+        r = self.issue(name, number)
+        repo = self.repo(name)
+        if r is None or repo is None:
+            return None
+        labels = {lb["label"]: lb for lb in json.loads(repo["labels_json"])}
+        return {"version": 1, "snapshot": self.built_at, "source": {"fetched_at": r["fetched_at"]},
+                "issue": {"ref": f"{repo['name']}#{number}", "title": r["title"], "labels": json.loads(r["labels"]),
+                          "assignees": r["assignees"], "linked_open_prs": r["linked_open_prs"],
+                          "dead_ends": r["dead_ends"], "interest_30d": r["interest_30d"]},
+                "availability": {"available": bool(r["available"]),
+                                 "blocked_by": [b for b in (r["blocked_by"] or "").split(", ") if b],
+                                 "last_claim_at": r["last_claim_at"], "claimers": r["claimers"]},
+                "repo": {"outsider_merge": {"merged": repo["merged"], "decided": (repo["merged"] or 0) + (repo["closed"] or 0),
+                                            "rate": repo["merge_rate"], "low": repo["merge_low"],
+                                            "high": repo["merge_high"], "enough": bool(repo["merge_enough"]),
+                                            "window_days": repo["window_days"],
+                                            "window_complete": bool(repo["window_complete"])},
+                         "newcomer_merge": {"merged": repo["newcomer_merged"], "decided": repo["newcomer_decided"],
+                                            "rate": repo["newcomer_rate"], "low": repo["newcomer_low"],
+                                            "high": repo["newcomer_high"], "enough": bool(repo["newcomer_enough"])},
+                         "review_hours": {"median": repo["median_review_hours"], "n": repo["reviewed"],
+                                          "enough": bool(repo["review_enough"])},
+                         "excluded": {"bot_prs": repo["bot_prs"], "ai_prs": repo["ai_prs"],
+                                      "insider_prs": repo["insider_prs"]}},
+                "labels": [labels[lb] for lb in dict.fromkeys(norm_label(x) for x in json.loads(r["labels"]))
+                           if lb in labels],
+                "walls": json.loads(repo["walls_json"]),
+                "score": {**parts(r), "total": round(r["score"], 3), "in_lists": round(r["rank_score"], 3)},
+                "notes": json.loads(repo["notes"])}
+
+    def repo_health(self, name: str, detail: bool = False) -> dict | None:
+        r = self.repo(name)
+        if r is None:
+            return None
+        counts = self.db.execute("SELECT count(*) FILTER (WHERE opportunity = 1),"
+                                 " count(*) FILTER (WHERE opportunity = 1 AND available = 1) FROM issues WHERE repo_id = ?",
+                                 (r["repo_id"],)).fetchone()
+        out = {"repo": r["name"], "url": f"https://github.com/{r['name']}", "stars": r["stars"], "language": r["language"],
+               "outsider_merge": rate_text(r), "newcomer_merge": newcomer_text(r),
+               "review": review_text(r), "insiders": r["insiders"],
+               "excluded_prs": {"bots": r["bot_prs"], "ai_agents": r["ai_prs"], "insiders": r["insider_prs"]},
+               "walls": json.loads(r["walls_json"]), "beginner_issues": {"open": counts[0], "free": counts[1]},
+               "how_to_reach": {"discussions": bool(r["has_discussions"]),
+                                "contributing": f"https://github.com/{r['name']}/blob/HEAD/CONTRIBUTING.md"
+                                if r["contributing"] else None,
+                                "issues": f"https://github.com/{r['name']}/issues"},
+               "snapshot": self.built_at}
+        if detail:
+            out["labels"] = json.loads(r["labels_json"])
+            out["accepted_outsider_prs"] = self.examples(r["repo_id"])
+        return out
+
+    def repos_needing_help(self, language=None, limit=10) -> dict:
+        # Welcoming to outsiders (enough evidence, merge rate at least 50% even at the low end) but few maintainers.
+        built = datetime.fromisoformat(self.built_at.replace("Z", "+00:00")) if self.built_at else datetime.now(timezone.utc)
+        recent = (built - timedelta(days=90)).strftime("%Y-%m-%dT%H:%M:%SZ")
+        rows = self._rows("SELECT * FROM repos WHERE merge_enough = 1 AND merge_low >= 0.5 AND insiders <= 3"
+                          " AND coalesce(archived, 0) = 0 AND pushed_at >= :recent"
+                          " AND (:language IS NULL OR language = :language) ORDER BY outsider_prs DESC LIMIT :limit",
+                          {"recent": recent, "language": language, "limit": max(1, min(limit, 50))})
+        return {"snapshot": self.built_at, "results": [
+            {"repo": r["name"], "url": f"https://github.com/{r['name']}", "language": r["language"],
+             "why": f"{r['insiders']} active maintainers handle {r['outsider_prs']} outsider PRs; {rate_text(r)};"
+                    f" {review_text(r)}"} for r in rows]}
+
+    def similar_issues(self, name: str, number: int, limit: int = 5) -> dict:
+        base = self.issue(name, number)
+        if base is None:
+            return {"snapshot": self.built_at, "results": []}
+        # The rarest title words that other issues share: common words ("add", "error") match thousands and are slow.
+        counts = {w: self.db.execute("SELECT count(*) FROM issues_fts WHERE issues_fts MATCH ?", (f'"{w}"',)).fetchone()[0]
+                  for w in fts_words(base["title"])}
+        rare = [w for w, n in sorted(counts.items(), key=lambda kv: kv[1]) if n >= 2][:3]
+        q = " OR ".join(f'"{w}"' for w in rare) or None
+        rows = self._select("issues_fts MATCH :q AND i.available = 1 AND NOT (i.repo_id = :rid AND i.number = :n)",
+                            {"q": q, "rid": base["repo_id"], "n": number}, "bm25(issues_fts), i.rank_score DESC",
+                            max(1, min(limit, 20)), True) if q else []
+        return {"snapshot": self.built_at, "results": [self._row(r, False) for r in rows]}
+
+    def with_repo_stats(self, items: list[dict]) -> list[dict]:
+        out = []
+        for it in items:
+            r = self.repo(it["repo"])
+            if r is not None:
+                out.append({**it, "outsider_merge": rate_text(r), "review": review_text(r),
+                            "walls": [w["wall"] for w in json.loads(r["walls_json"]) if w.get("blocking")]})
+        return out

mergescout/tool/refs.py

@@ -0,0 +1,31 @@
+import re
+from dataclasses import dataclass
+
+REF = re.compile(r"(?:https?://)?(?:www\.)?(?:github\.com/)?([A-Za-z0-9_.-]+)/([A-Za-z0-9_.-]+?)"
+                 r"(?:\.git)?(?:(?:/issues/|/pull/|#)(\d+))?/?$")
+
+
+@dataclass(frozen=True)
+class Ref:
+    owner: str
+    name: str
+    number: int | None
+
+    @property
+    def repo(self) -> str:
+        return f"{self.owner}/{self.name}"
+
+    @property
+    def key(self) -> str:
+        return f"{self.repo}#{self.number}" if self.number else self.repo
+
+
+def parse_ref(text: str) -> Ref:
+    s = re.sub(r"\?.*$", "", (text or "").strip())
+    # "#issuecomment-123" and other anchors are not part of the issue reference; "#7" is.
+    s = re.sub(r"#(?!\d+/?$).*$", "", s)
+    s = re.sub(r"\s+#", "#", s)
+    m = REF.match(s)
+    if not m:
+        raise ValueError(f"Could not read {text!r}; use owner/name#number or a GitHub issue URL.")
+    return Ref(m.group(1), m.group(2), int(m.group(3)) if m.group(3) else None)

mergescout/tool/store.py

@@ -0,0 +1,129 @@
+import json
+import os
+import sqlite3
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+
+import zstandard
+
+from mergescout.snapshot.publish import MANIFEST, PACKED, PREFIX, SNAPSHOT, sha256
+from mergescout.snapshot.schema import SCHEMA_MAJOR
+
+DEFAULT_REPO = "kaushik-yadav/merge-scout"
+
+
+def home() -> Path:
+    root = Path(os.environ.get("MERGESCOUT_HOME") or Path.home() / ".mergescout")
+    root.mkdir(parents=True, exist_ok=True)
+    return root
+
+
+def data_token() -> str | None:
+    # The same names the rest of the suite reads, so one exported token serves every command.
+    for name in ("MERGESCOUT_TOKEN", "STACKVITALS_TOKEN", "GITHUB_TOKEN", "GH_TOKEN"):
+        if os.environ.get(name, "").strip():
+            return os.environ[name].strip()
+    return None
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _major(version) -> int:
+    return int(str(version).split(".")[0])
+
+
+class SnapshotStore:
+    def __init__(self, root: Path, releases):
+        self.root, self.releases = root, releases
+        self.root.mkdir(parents=True, exist_ok=True)
+        self.path = root / SNAPSHOT
+
+    def local_manifest(self) -> dict | None:
+        p = self.root / MANIFEST
+        if not (p.exists() and self.path.exists()):
+            return None
+        try:
+            return json.loads(p.read_text(encoding="utf-8"))
+        except (ValueError, OSError):
+            # A cut-off manifest only costs a fresh check, never a locked-out user.
+            return None
+
+    def _tmp(self, name: str) -> Path:
+        # Per process and thread, so two AI tools starting together never share a half-written file.
+        return self.root / f"{name}.{os.getpid()}.{threading.get_ident()}"
+
+    def _remember(self, manifest: dict) -> None:
+        tmp = self._tmp(MANIFEST)
+        tmp.write_text(json.dumps({**manifest, "checked_at": _now()}), encoding="utf-8")
+        os.replace(tmp, self.root / MANIFEST)
+
+    def _latest(self) -> tuple[dict, dict] | None:
+        tags = sorted((r for r in self.releases.list_releases() if r["tag_name"].startswith(PREFIX)),
+                      key=lambda r: r["tag_name"], reverse=True)
+        for release in tags:
+            assets = {a["name"]: a for a in self.releases.assets(release)}
+            if MANIFEST in assets and PACKED in assets:
+                tmp = self._tmp("remote-manifest.json")
+                try:
+                    self.releases.download_asset(assets[MANIFEST], tmp)
+                    manifest = json.loads(tmp.read_text(encoding="utf-8"))
+                finally:
+                    tmp.unlink(missing_ok=True)
+                return {**manifest, "tag": release["tag_name"]}, assets[PACKED]
+        return None
+
+    def update(self, force: bool = False) -> str:
+        found = self._latest()
+        if found is None:
+            return "no snapshot is published yet"
+        manifest, asset = found
+        local = self.local_manifest()
+        if local and local.get("sha256") == manifest["sha256"] and not force:
+            self._remember(local)
+            return f"up to date ({local['built_at']})"
+
+        def refuse(reason: str) -> str:
+            # Remember the check, so a refused file is not downloaded again on every start.
+            if local:
+                self._remember(local)
+                return f"kept the current file: {reason}"
+            return f"no snapshot installed: {reason}"
+
+        if _major(manifest["schema_version"]) != SCHEMA_MAJOR:
+            return refuse(f"the new snapshot needs a newer mergescout (schema {manifest['schema_version']})")
+        packed, fresh = self._tmp(PACKED + ".part"), self._tmp(SNAPSHOT + ".new")
+        try:
+            self.releases.download_asset(asset, packed)
+            if sha256(packed) != manifest["sha256"]:
+                return refuse("the download did not match its checksum")
+            with packed.open("rb") as fi, fresh.open("wb") as fo:
+                zstandard.ZstdDecompressor().copy_stream(fi, fo)
+            db = sqlite3.connect(fresh)
+            ok = db.execute("PRAGMA quick_check").fetchone()[0] == "ok"
+            version = dict(db.execute("SELECT key, value FROM meta").fetchall()).get("schema_version", "0")
+            db.close()
+            if not ok or _major(version) != SCHEMA_MAJOR:
+                return refuse("the new snapshot failed its check")
+            try:
+                os.replace(fresh, self.path)
+            except PermissionError:
+                return refuse("it is in use; restart your AI tool to load the new one")
+            self._remember(manifest)
+            return f"updated to {manifest['built_at']}"
+        finally:
+            packed.unlink(missing_ok=True)
+            fresh.unlink(missing_ok=True)
+
+    def ensure(self, max_age_hours: float = 24, log=print) -> Path | None:
+        local = self.local_manifest()
+        stamp = (local or {}).get("checked_at")
+        checked = datetime.fromisoformat(stamp.replace("Z", "+00:00")) if stamp else None
+        if checked is None or (datetime.now(timezone.utc) - checked).total_seconds() / 3600 >= max_age_hours:
+            try:
+                log(self.update())
+            except Exception as exc:  # noqa: BLE001 - any failure keeps the last good file
+                log(f"could not check for a new snapshot: {exc}")
+        return self.path if self.path.exists() else None

mergescout/tool/tracking.py

@@ -0,0 +1,83 @@
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+import httpx
+
+from mergescout.tool.live import LiveError
+from mergescout.tool.refs import parse_ref
+
+OUTCOMES = ("started", "pr_opened", "merged", "closed_unmerged", "abandoned", "taken_by_someone_else")
+WATCH = ("state", "assignees", "linked_open_prs")
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+class Tracker:
+    # Tracked issues and outcomes stay on this machine; nothing is sent anywhere.
+    def __init__(self, root: Path):
+        self.root = root
+        self.file, self.outcomes = root / "tracked.json", root / "outcomes.jsonl"
+
+    def tracked(self) -> dict:
+        if not self.file.exists():
+            return {}
+        try:
+            return json.loads(self.file.read_text(encoding="utf-8"))
+        except ValueError:
+            # A damaged file is kept aside for the user and tracking starts fresh.
+            os.replace(self.file, self.file.with_name(self.file.name + ".bad"))
+            return {}
+
+    def _save(self, data: dict) -> None:
+        self.root.mkdir(parents=True, exist_ok=True)
+        tmp = self.file.with_name(f"{self.file.name}.{os.getpid()}.tmp")
+        tmp.write_text(json.dumps(data, indent=1), encoding="utf-8")
+        os.replace(tmp, self.file)
+
+    @staticmethod
+    def _view(status: dict) -> dict:
+        return {**{k: status.get(k) for k in WATCH}, "claims": len(status.get("claims") or []),
+                "waits": len(status.get("waits") or [])}
+
+    def track(self, key: str, status: dict) -> dict:
+        # GitHub names ignore letter case, so tracked keys do too.
+        key = key.lower()
+        data = self.tracked()
+        data[key] = {"tracked_at": data.get(key, {}).get("tracked_at", _now()), "last": self._view(status)}
+        self._save(data)
+        return data[key]
+
+    def untrack(self, key: str) -> None:
+        data = self.tracked()
+        data.pop(key.lower(), None)
+        self._save(data)
+
+    def updates(self, live) -> list[dict]:
+        data, changes = self.tracked(), []
+        for key, item in data.items():
+            ref = parse_ref(key)
+            try:
+                now = self._view(live.issue_status(ref.owner, ref.name, ref.number))
+            except (LiveError, httpx.HTTPError) as exc:
+                # One deleted issue or a rate limit must not hide the others.
+                changes.append({"issue": key, "error": str(exc)})
+                continue
+            diff = {k: [item["last"].get(k), v] for k, v in now.items() if item["last"].get(k) != v}
+            if diff:
+                changes.append({"issue": key, "changed": diff})
+            item["last"] = now
+        self._save(data)
+        return changes
+
+    def report_outcome(self, key: str, outcome: str, note: str = "") -> dict:
+        if outcome not in OUTCOMES:
+            raise ValueError(f"Outcome must be one of: {', '.join(OUTCOMES)}.")
+        entry = {"issue": key.lower(), "outcome": outcome, "note": note[:500], "at": _now()}
+        self.root.mkdir(parents=True, exist_ok=True)
+        with self.outcomes.open("a", encoding="utf-8") as f:
+            f.write(json.dumps(entry) + "\n")
+        return entry

stackvitals/__init__.py

@@ -0,0 +1,2 @@
+"""StackVitals: a free, open-source developer suite. MergeScout (package `mergescout`) is its Contribute module."""
+__version__ = "0.1.0"

stackvitals/__main__.py

@@ -0,0 +1,4 @@
+"""python -m stackvitals: the same as the stackvitals command (the Action runs it this way, from source)."""
+from stackvitals.cli import main
+
+raise SystemExit(main())

stackvitals/ci/__init__.py

@@ -0,0 +1 @@
+"""CI Health: flaky and slow jobs, steps and tests from a repo's GitHub Actions history."""