ground-control-cli 0.2.0__py3-none-any.whl

client/machine.py

@@ -0,0 +1,254 @@
+"""What the machine remembers, and which company's key a repo uses.
+
+The machine keeps, outside every repo, the companies it is connected to (their addresses) and
+which company each remote was found to belong to, with the repo's GitHub id; each company's key
+lives in the operating system's keychain (client.system), never in a file. Nothing is written
+into a repo.
+
+A repo's company is found by matching its remotes against each connected company's managed
+list (client.repos), read from the service when a session starts; a repo found before is
+found again from what the machine remembers. A repo that is not managed, or whose company is
+not connected, has no company: the client says nothing there unless a person asked.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from client import repos
+from client.service import Service, ServiceError
+from client.system import System
+
+# Where the machine keeps what it remembers; the tests point it elsewhere.
+HOME_VARIABLE = "GROUNDCONTROL_HOME"
+# How long one call to the service may take, in seconds.
+TIMEOUT = 30
+
+
+def home() -> Path:
+    """The folder the machine keeps the client's state in: ~/.groundcontrol.
+
+    Company: assumes none.
+    """
+    return Path(os.environ.get(HOME_VARIABLE) or Path.home() / ".groundcontrol")
+
+
+def _state_path() -> Path:
+    """The file of addresses and remotes; no key is ever in it."""
+    return home() / "machine.json"
+
+
+def load() -> dict:
+    """What the machine remembers: {companies: [address], remotes: {remote: {...}}, door}.
+
+    Company: assumes none.
+    """
+    try:
+        found = json.loads(_state_path().read_text())
+    except (OSError, json.JSONDecodeError):
+        found = {}
+    return {
+        "companies": list(found.get("companies", [])),
+        "remotes": dict(found.get("remotes", {})),
+        "door": found.get("door", ""),
+    }
+
+
+def save(state: dict) -> None:
+    """Keep what the machine remembers.
+
+    Company: assumes none.
+    """
+    path = _state_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(state, indent=2, sort_keys=True) + "\n")
+
+
+def address_of(given: str) -> str:
+    """A company's address as the machine keeps it: an origin, https unless this machine.
+
+    Args:
+        given: The address as typed or carried by the install line, with or without a scheme.
+
+    Returns:
+        Such as https://acme.ground-control.io.
+
+    Raises:
+        ValueError: If it is no address.
+
+    Company: the one it names.
+    """
+    given = given.strip()
+    if "://" not in given:
+        given = f"https://{given}"
+    parts = urlsplit(given)
+    if not parts.hostname or parts.path.strip("/") or parts.query:
+        raise ValueError(f"{given}: give the company's address, such as https://acme.example.com")
+    return f"{parts.scheme}://{parts.netloc}".lower()
+
+
+def door_of(address: str) -> str:
+    """The door beside a company's address, as the service has it: login.<its domain>.
+
+    Args:
+        address: The company's origin, such as https://acme.ground-control.io.
+
+    Returns:
+        Such as https://login.ground-control.io.
+
+    Company: assumes none.
+    """
+    parts = urlsplit(address)
+    domain = (parts.hostname or "").split(".", 1)[-1]
+    port = f":{parts.port}" if parts.port else ""
+    return f"{parts.scheme}://login.{domain}{port}"
+
+
+def remember_company(address: str, door: str) -> None:
+    """Add a connected company, and the door the machine connects at, to what it remembers.
+
+    Company: the one at the address.
+    """
+    state = load()
+    if address not in state["companies"]:
+        state["companies"].append(address)
+    state["door"] = door
+    save(state)
+
+
+def forget_company(address: str) -> None:
+    """Forget a company, and every remote found to be one of its repos.
+
+    Company: the one at the address.
+    """
+    state = load()
+    state["companies"] = [a for a in state["companies"] if a != address]
+    state["remotes"] = {r: f for r, f in state["remotes"].items() if f.get("address") != address}
+    save(state)
+
+
+def remotes(root: Path) -> list[str]:
+    """A clone's remote addresses, origin first.
+
+    Company: assumes none.
+    """
+    try:
+        listed = subprocess.run(
+            ["git", "-C", str(root), "remote", "-v"], capture_output=True, text=True, timeout=10
+        ).stdout
+    except (OSError, subprocess.TimeoutExpired):
+        return []
+    found: dict[str, str] = {}
+    for line in listed.splitlines():
+        parts = line.split()
+        if len(parts) >= 2:
+            found.setdefault(parts[1], parts[0])
+    return sorted(found, key=lambda url: (found[url] != "origin", found[url]))
+
+
+def service(address: str, system: System) -> Service | None:
+    """The service at a company's address, with this machine's key for it; None without one.
+
+    Company: the one at the address.
+    """
+    key = system.get_key(address)
+    return Service(address, key, TIMEOUT) if key else None
+
+
+@dataclass(frozen=True)
+class Found:
+    """A repo's company: where to call, with which key, and the repo as the service names it.
+
+    Attributes:
+        service: The company's service, with its key.
+        repo: The repo's full name, as owner/name.
+        github_id: GitHub's id for it, when the service knows it.
+    """
+
+    service: Service
+    repo: str
+    github_id: int | None
+
+
+@dataclass(frozen=True)
+class Missing:
+    """Why a repo has no company here: one line, for a person who asked.
+
+    Attributes:
+        why: The line.
+    """
+
+    why: str
+
+
+NOT_CONNECTED = "this machine is connected to no company: run `groundcontrol init <its address>`"
+NO_REMOTE = "this repo has no remote to find its company by"
+
+
+def find(root: Path, system: System, refresh: bool = False) -> Found | Missing:
+    """The company of the repo at root, with its key, from the managed lists.
+
+    A remote the machine found before is found again without asking, unless `refresh`; then
+    every connected company's managed list is read (with nothing left running) and what the
+    machine remembers is set from them.
+
+    Args:
+        root: The repo.
+        system: The operating system's side, which holds the keys.
+        refresh: Whether to read the lists again even for a remote found before.
+
+    Returns:
+        Found, or Missing with the line that says what is missing.
+
+    Company: each connected one, until the repo's is found.
+    """
+    state = load()
+    if not state["companies"]:
+        return Missing(NOT_CONNECTED)
+    here = remotes(root)
+    if not here:
+        return Missing(NO_REMOTE)
+    if not refresh:
+        for remote in here:
+            known = state["remotes"].get(remote)
+            if known and known.get("address") in state["companies"]:
+                found = service(known["address"], system)
+                if found:
+                    return Found(found, known["name"], known.get("github_id"))
+    said = []
+    known_ids = {r: f["github_id"] for r, f in state["remotes"].items() if f.get("github_id")}
+    for address in state["companies"]:
+        called = service(address, system)
+        if called is None:
+            said.append(
+                f"the key for {address} is not in the keychain: run `groundcontrol init {address}`"
+            )
+            continue
+        try:
+            listed = called.managed()
+        except ServiceError as e:
+            said.append(f"{address}: {e.detail}")
+            continue
+        matched = repos.match(here, listed, known_ids)
+        if matched:
+            remote, repo = matched
+            state["remotes"] = {r: f for r, f in state["remotes"].items() if r not in here}
+            state["remotes"][remote] = {
+                "address": address,
+                "name": repo["name"],
+                "github_id": repo.get("github_id"),
+            }
+            save(state)
+            return Found(called, repo["name"], repo.get("github_id"))
+    if any(r in state["remotes"] for r in here):
+        state["remotes"] = {r: f for r, f in state["remotes"].items() if r not in here}
+        save(state)
+    if said:
+        return Missing("; ".join(said))
+    companies = ", ".join(state["companies"])
+    return Missing(f"this repo is not managed by {companies}: ask a manager there to manage it")

client/probes/__init__.py

@@ -0,0 +1,57 @@
+"""The probes the client runs on the developer's machine: generic, deciding nothing.
+
+A rule on the service names the probes it needs (app/method/facts.py, PROBES); the client runs
+each in the repo and returns what it found, a fact, as plain values with the fields of the
+probe's facts. A fact is a path, a hash, a count, a line number, a commit or a status code,
+never a file's contents or a command's output; a probe that cannot run says which of
+errors.ERRORS stopped it.
+
+The client is its own package: it imports nothing of the server.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from . import code, gh, git, health, tests
+
+# Every probe the client runs: its name -> the function of (params, root) that runs it.
+RUNS: dict[str, Callable[[dict, object], dict]] = {
+    "git.branch": git.branch,
+    "git.commit": git.commit,
+    "git.merge_base": git.merge_base,
+    "git.changed": git.changed,
+    "git.lines": git.lines,
+    "git.conflicts": git.conflicts,
+    "tests.collect": tests.collect_probe,
+    "tests.run": tests.run_probe,
+    "tests.coverage": tests.coverage_probe,
+    "tests.fingerprints": tests.fingerprints_probe,
+    "code.symbols": code.symbols_probe,
+    "code.callers": code.callers_probe,
+    "code.languages": code.languages_probe,
+    "gh.pr": gh.pr,
+    "gh.checks": gh.checks,
+    "health": health.health,
+}
+
+
+def run(name: str, params: dict, root) -> dict:
+    """Run one probe in the repo and return its fact as plain values.
+
+    Args:
+        name: The probe, one of RUNS.
+        params: Its parameters as plain values.
+        root: The repo it runs in.
+
+    Returns:
+        The fact: the fields of the probe's facts, as plain values.
+
+    Raises:
+        ValueError: If the client runs no probe of that name.
+
+    Company: assumes none.
+    """
+    if name not in RUNS:
+        raise ValueError(f"the client runs no probe `{name}`; it runs {', '.join(RUNS)}")
+    return RUNS[name](dict(params or {}), root)