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

client/probes/tests.py

@@ -0,0 +1,532 @@
+"""The tests probes: the product's tests, listed, run, measured and fingerprinted.
+
+`test_tools` in the repo's .claude/method.json names, per test type, the commands that run its
+tests: `run` (with `{tests}` and `{junit}`, writing a JUnit XML report), `collect` (printing one
+test id per line) and `coverage` (with `{tests}` and `{lcov}`, writing an lcov report). The
+plain-string form is read as `run` alone. Commands run through the shell in the folder they are
+given, with `{tests}` the shell-quoted test ids. The service names only the type; the commands
+are the repo's own.
+
+A test's file is the longest start of its id that is a file in the repo (`tests/test_a.py` in
+`tests/test_a.py::test_x`); the rest of the id names the test function. A test's fingerprint is
+the hash of the reader's span of that function, or of the whole file when the reader cannot
+name it.
+
+What a command prints is read here and never returned: a run says each test's state, and which
+of the names it was asked to look for its report names.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import os
+import re
+import shlex
+import shutil
+import subprocess
+import tempfile
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from typing import NamedTuple
+from urllib.parse import urlsplit
+
+from . import code, errors
+
+KEYS = ("run", "collect", "coverage")
+CONFIG = ".claude/method.json"
+BASE = "main"
+ID_PARTS_RE = re.compile(r"::| > |#")
+PARAMS_RE = re.compile(r"\[.*\]$")
+SOURCE_END_RE = re.compile(r"[A-Za-z0-9_.-]")
+# The variable a test run against the environment gets: the scheme, host and port of its health.
+ENV_URL = "METHOD_ENV_URL"
+
+
+class Failed(Exception):
+    """A probe could not run; `error` is which of errors.ERRORS stopped it."""
+
+    def __init__(self, error: str):
+        """Keep the error."""
+        super().__init__(error)
+        self.error = error
+
+
+class Outcome(NamedTuple):
+    """One test's result, read from its JUnit report.
+
+    Attributes:
+        state: pass, failure, error or skipped.
+        text: What the report says about a failure, an error or a skip; never returned.
+
+    Company: assumes none.
+    """
+
+    state: str
+    text: str
+
+
+def _config(root) -> dict:
+    """The repo's .claude/method.json; Failed with unreadable when it cannot be read."""
+    path = Path(root) / CONFIG
+    if not path.is_file():
+        return {}
+    try:
+        found = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        raise Failed(errors.UNREADABLE) from None
+    return found if isinstance(found, dict) else {}
+
+
+def tools(root) -> dict:
+    """Read the test tools of each type from the repo's .claude/method.json.
+
+    A plain string is `run` alone; a type whose entry is neither is left out.
+
+    Args:
+        root: The repo.
+
+    Returns:
+        Type -> {run, collect, coverage}, in the file's order.
+
+    Raises:
+        Failed: With unreadable, if the file or its "test_tools" cannot be read.
+
+    Company: assumes none.
+    """
+    found = _config(root).get("test_tools", {})
+    if not isinstance(found, dict):
+        raise Failed(errors.UNREADABLE)
+    read = {}
+    for kind, entry in found.items():
+        if isinstance(entry, str):
+            read[kind] = {"run": entry}
+        elif isinstance(entry, dict) and all(isinstance(entry.get(k, ""), str) for k in KEYS):
+            read[kind] = {k: entry[k] for k in KEYS if k in entry}
+    return read
+
+
+def command(root, kind: str, key: str) -> str:
+    """The `key` command of type `kind`.
+
+    Args:
+        root: The repo.
+        kind: The test type.
+        key: run, collect or coverage.
+
+    Returns:
+        The command.
+
+    Raises:
+        Failed: With no_command, if the type has no entry or no such command; with unreadable,
+            if the tools cannot be read.
+
+    Company: assumes none.
+    """
+    value = tools(root).get(kind, {}).get(key, "")
+    if not value.split():
+        raise Failed(errors.NO_COMMAND)
+    return value
+
+
+def _program(cmd: str) -> str:
+    """The command's first word."""
+    try:
+        return (shlex.split(cmd) or [""])[0]
+    except ValueError:
+        return cmd.split()[0]
+
+
+def _shell(cmd: str, cwd: Path, env=None):
+    """Run the command through the shell in `cwd`, capturing its output as text."""
+    return subprocess.run(cmd, shell=True, cwd=cwd, capture_output=True, text=True, env=env)
+
+
+def _fill(cmd: str, **values) -> str:
+    """The command with each `{key}` replaced by its value."""
+    for key, value in values.items():
+        cmd = cmd.replace("{" + key + "}", value)
+    return cmd
+
+
+def collect(cmd: str, cwd: Path) -> tuple:
+    """Run the collect command and read the test ids it prints, one per line.
+
+    Args:
+        cmd: The collect command.
+        cwd: The folder it runs in.
+
+    Returns:
+        (the test ids, whether the command exited with 0).
+
+    Company: assumes none.
+    """
+    out = _shell(cmd, cwd)
+    return [line.strip() for line in out.stdout.splitlines() if line.strip()], out.returncode == 0
+
+
+def _outcome(report: Path) -> Outcome:
+    """The Outcome the JUnit report says; an error when it holds no test case."""
+    try:
+        cases = list(ET.parse(report).getroot().iter("testcase"))
+    except (OSError, ET.ParseError):
+        cases = []
+    if not cases:
+        return Outcome("error", "")
+    for state in ("error", "failure", "skipped"):
+        found = [e for case in cases for e in case.findall(state)]
+        if found:
+            return Outcome(
+                state, "\n".join(f"{e.get('message') or ''}\n{e.text or ''}" for e in found)
+            )
+    return Outcome("pass", "")
+
+
+def run_one(cmd: str, cwd: Path, test_id: str, env=None) -> Outcome:
+    """Run one test alone and read its outcome from its JUnit report.
+
+    The report is written to a temporary folder, removed afterwards.
+
+    Args:
+        cmd: The run command, with `{tests}` and `{junit}`.
+        cwd: The folder it runs in.
+        test_id: The test's id.
+        env: The run's environment; the current one when not given.
+
+    Returns:
+        The test's Outcome.
+
+    Company: assumes none.
+    """
+    with tempfile.TemporaryDirectory(prefix="method-junit-") as tmp:
+        report = Path(tmp) / "junit.xml"
+        _shell(_fill(cmd, tests=shlex.quote(test_id), junit=shlex.quote(str(report))), cwd, env)
+        return _outcome(report)
+
+
+def coverage(cmd: str, cwd: Path, ids: list) -> tuple:
+    """Run the coverage command for these tests and read its lcov report.
+
+    Args:
+        cmd: The coverage command, with `{tests}` and `{lcov}`.
+        cwd: The folder it runs in.
+        ids: The test ids.
+
+    Returns:
+        (file relative to cwd -> {line: hits}, whether the report was written, whether the
+        command exited with 0).
+
+    Company: assumes none.
+    """
+    with tempfile.TemporaryDirectory(prefix="method-lcov-") as tmp:
+        report = Path(tmp) / "coverage.lcov"
+        tests = " ".join(shlex.quote(i) for i in ids)
+        out = _shell(_fill(cmd, tests=tests, lcov=shlex.quote(str(report))), cwd)
+        if not report.is_file():
+            return {}, False, out.returncode == 0
+        text = report.read_text(encoding="utf-8", errors="replace")
+        return read_lcov(text, cwd), True, out.returncode == 0
+
+
+def read_lcov(text: str, root: Path) -> dict:
+    """Read an lcov report's line hits.
+
+    An absolute source path under `root` is made relative to it. Hits for the same line are
+    added up.
+
+    Args:
+        text: The lcov report.
+        root: The folder source paths are made relative to.
+
+    Returns:
+        File -> {line number: hits}.
+
+    Raises:
+        ValueError: If a `DA:` line does not hold numbers.
+
+    Company: assumes none.
+    """
+    found, current = {}, None
+    root = Path(root).resolve()
+    for line in text.splitlines():
+        if line.startswith("SF:"):
+            source = Path(line[3:].strip())
+            if source.is_absolute():
+                with contextlib.suppress(ValueError):
+                    source = source.resolve().relative_to(root)
+            current = found.setdefault(source.as_posix(), {})
+        elif line.startswith("DA:") and current is not None:
+            number, hits = line[3:].split(",")[:2]
+            current[int(number)] = current.get(int(number), 0) + int(float(hits))
+        elif line.startswith("end_of_record"):
+            current = None
+    return found
+
+
+def file_of(root: Path, test_id: str) -> str:
+    """Find the test's file: the longest start of the id that is a file in the repo.
+
+    A start only counts where the next character cannot continue a path.
+
+    Args:
+        root: The repo.
+        test_id: The test's id.
+
+    Returns:
+        The file's repo-relative path, or "".
+
+    Company: assumes none.
+    """
+    for end in range(len(test_id), 0, -1):
+        if end < len(test_id) and SOURCE_END_RE.match(test_id[end]):
+            continue
+        candidate = test_id[:end]
+        if (Path(root) / candidate).is_file():
+            return candidate
+    return ""
+
+
+def _function(test_id: str, name: str) -> str:
+    """The test function's dotted name: the rest of the id after its file, without parameters."""
+    parts = [PARAMS_RE.sub("", p).strip() for p in ID_PARTS_RE.split(test_id[len(name) :])]
+    return ".".join(p for p in parts if p)
+
+
+def fingerprint(root: Path, test_id: str) -> str:
+    """Fingerprint a test: the sha256 of the reader's span of its function, or of its file.
+
+    The function is found by its full dotted name, else by its last part when only one symbol
+    has it. The whole file is hashed when the reader cannot name it.
+
+    Args:
+        root: The repo.
+        test_id: The test's id.
+
+    Returns:
+        `sha256:<hex>`, or "" when the id names no file in the repo.
+
+    Company: assumes none.
+    """
+    name = file_of(root, test_id)
+    if not name:
+        return ""
+    target = Path(root) / name
+    lines = target.read_text(encoding="utf-8", errors="replace").splitlines(keepends=True)
+    span = lines
+    wanted = _function(test_id, name)
+    try:
+        found = code.symbols(target, name) if wanted and code.reader(target) else []
+    except errors.Refused:
+        found = []
+    match = next((s for s in found if s.name == wanted), None)
+    if match is None:
+        last = wanted.split(".")[-1]
+        named = [s for s in found if s.name.split(".")[-1] == last]
+        match = named[0] if len(named) == 1 else None
+    if match is not None:
+        span = lines[match.first - 1 : match.last]
+    return "sha256:" + hashlib.sha256("".join(span).encode("utf-8")).hexdigest()
+
+
+@contextlib.contextmanager
+def main_tree(root: Path):
+    """Give a temporary worktree of main, removed afterwards.
+
+    Args:
+        root: The repo.
+
+    Yields:
+        The worktree's folder, detached at main.
+
+    Raises:
+        Failed: If git cannot add the worktree.
+
+    Company: assumes none.
+    """
+    folder = Path(tempfile.mkdtemp(prefix="method-main-"))
+    tree = folder / "main"
+    try:
+        out = subprocess.run(
+            ["git", "worktree", "add", "-q", "--detach", str(tree), BASE],
+            cwd=root,
+            capture_output=True,
+            text=True,
+        )
+        if out.returncode != 0:
+            raise Failed(errors.failed(out.stderr))
+        yield tree
+    finally:
+        if tree.exists():
+            subprocess.run(
+                ["git", "worktree", "remove", "--force", str(tree)], cwd=root, capture_output=True
+            )
+        subprocess.run(["git", "worktree", "prune"], cwd=root, capture_output=True)
+        shutil.rmtree(folder, ignore_errors=True)
+
+
+@contextlib.contextmanager
+def _at(root: Path, at: str):
+    """The folder to work in: the repo itself at HEAD, a temporary worktree of main at main."""
+    if at == BASE:
+        with main_tree(root) as tree:
+            yield tree
+    else:
+        yield Path(root)
+
+
+def _env_url(root) -> str:
+    """The scheme, host and port of the environment's health; Failed with no_command if none."""
+    env = _config(root).get("environment")
+    health = env.get("health") if isinstance(env, dict) else None
+    if not isinstance(health, str) or not health.strip():
+        raise Failed(errors.NO_COMMAND)
+    parts = urlsplit(health)
+    return f"{parts.scheme}://{parts.netloc}"
+
+
+def _named(text: str, names: list) -> list:
+    """The names, of those given, that appear as words in the text."""
+    return [n for n in names if n and re.search(rf"\b{re.escape(n)}\b", text)]
+
+
+# --- the probes --------------------------------------------------------------------------------
+
+
+def collect_probe(params: dict, root) -> dict:
+    """tests.collect: the tests of every type the repo names, as its `collect` lists them.
+
+    At main, the commands of the head run in a temporary worktree of main.
+
+    Args:
+        params: {"at"}: HEAD or main.
+        root: The repo.
+
+    Returns:
+        The CollectFacts fields.
+
+    Company: assumes none.
+    """
+    root = Path(root)
+    try:
+        read = tools(root)
+    except Failed:
+        return {"types": []}
+    found = []
+    try:
+        with _at(root, params.get("at") or "HEAD") as cwd:
+            for kind, entry in read.items():
+                cmd = entry.get("collect", "")
+                if not cmd.split():
+                    found.append({"type": kind, "error": errors.NO_COMMAND})
+                    continue
+                ids, ok = collect(cmd, cwd)
+                tests = [{"id": i, "file": file_of(cwd, i) or None} for i in ids]
+                found.append(
+                    dict(
+                        {"type": kind, "tests": tests},
+                        **({} if ok else {"error": errors.COMMAND_FAILED}),
+                    )
+                )
+    except Failed as e:
+        return {"types": [{"type": kind, "error": e.error} for kind in read]}
+    return {"types": found}
+
+
+def run_probe(params: dict, root) -> dict:
+    """tests.run: run tests of one type, each alone, with the type's `run`.
+
+    At main, they run in a temporary worktree of main, with the tests' own files copied in from
+    the head. With environment, each run gets METHOD_ENV_URL, the scheme, host and port of the
+    environment's health. A type whose `run` names a program not found here is tool_missing,
+    asked with no ids too, which runs nothing.
+
+    Args:
+        params: {"type", "ids", "at", "look_for", "environment"}.
+        root: The repo.
+
+    Returns:
+        The RunFacts fields: each test's state, and which of look_for its report names.
+
+    Company: assumes none.
+    """
+    root = Path(root)
+    ids, look_for = list(params.get("ids") or []), list(params.get("look_for") or [])
+    try:
+        cmd = command(root, params["type"], "run")
+        if shutil.which(_program(cmd)) is None:
+            raise Failed(errors.TOOL_MISSING)
+        env = dict(os.environ, **{ENV_URL: _env_url(root)}) if params.get("environment") else None
+        if not ids:
+            return {"results": []}
+        results = []
+        at = params.get("at") or "HEAD"
+        with _at(root, at) as cwd:
+            if at == BASE:
+                for name in dict.fromkeys(file_of(root, i) for i in ids):
+                    if name:
+                        (cwd / name).parent.mkdir(parents=True, exist_ok=True)
+                        shutil.copyfile(root / name, cwd / name)
+            for test_id in ids:
+                outcome = run_one(cmd, cwd, test_id, env)
+                results.append(
+                    {"id": test_id, "state": outcome.state, "found": _named(outcome.text, look_for)}
+                )
+    except Failed as e:
+        return {"error": e.error}
+    return {"results": results}
+
+
+def coverage_probe(params: dict, root) -> dict:
+    """tests.coverage: run tests of one type with its `coverage`, and read the lines it measured.
+
+    Only files of the repo are kept. A command that exits non-zero, a test having failed, still
+    gives the lines it measured, with command_failed; one that writes no report gives none.
+
+    Args:
+        params: {"type", "ids"}.
+        root: The repo.
+
+    Returns:
+        The CoverageFacts fields.
+
+    Company: assumes none.
+    """
+    root = Path(root)
+    try:
+        cmd = command(root, params["type"], "coverage")
+    except Failed as e:
+        return {"error": e.error}
+    hits, written, ok = coverage(cmd, root, list(params.get("ids") or []))
+    files = [
+        {
+            "path": name,
+            "hit": sorted(n for n, c in lines.items() if c > 0),
+            "missed": sorted(n for n, c in lines.items() if c == 0),
+        }
+        for name, lines in sorted(hits.items())
+        if not Path(name).is_absolute() and not name.startswith("../")
+    ]
+    found = {"files": files}
+    return found if written and ok else dict(found, error=errors.COMMAND_FAILED)
+
+
+def fingerprints_probe(params: dict, root) -> dict:
+    """tests.fingerprints: the hash of each test's own lines, at the head or on main.
+
+    Args:
+        params: {"ids", "at"}.
+        root: The repo.
+
+    Returns:
+        The FingerprintFacts fields; a test whose file is not found has none.
+
+    Company: assumes none.
+    """
+    ids = list(params.get("ids") or [])
+    try:
+        with _at(Path(root), params.get("at") or "HEAD") as cwd:
+            found = [{"id": i, "fingerprint": fingerprint(cwd, i) or None} for i in ids]
+    except Failed:
+        found = [{"id": i, "fingerprint": None} for i in ids]
+    return {"tests": found}

client/repos.py

@@ -0,0 +1,68 @@
+"""Which managed repo a clone is: its remotes matched against every identifier the list gives.
+
+A managed repo comes with GitHub's fixed id, its current and earlier names, and its https and
+ssh clone addresses. A clone knows its remotes, written either way, perhaps with an old name;
+and the machine remembers the GitHub id of the repo each remote was found to be, so a rename
+on GitHub still finds it.
+"""
+
+from __future__ import annotations
+
+import re
+from urllib.parse import urlsplit
+
+# An scp-like ssh address: git@host:owner/name.git.
+SCP = re.compile(r"^(?:[^@/\s]+@)?([^:/\s]+):(?!//)(.+)$")
+
+
+def location(url: str) -> tuple[str, str] | None:
+    """A clone address as (host, owner/name), in lower case, without .git; None if it is none.
+
+    Args:
+        url: An https, ssh or scp-like address.
+
+    Returns:
+        The host and the path, or None.
+
+    Company: assumes none.
+    """
+    url = url.strip()
+    found = SCP.match(url) if "://" not in url else None
+    if found:
+        host, path = found[1], found[2]
+    else:
+        parts = urlsplit(url)
+        host, path = parts.hostname or "", parts.path
+    path = path.strip("/").removesuffix(".git").lower()
+    return (host.lower(), path) if host and path.count("/") == 1 else None
+
+
+def match(remotes: list[str], managed: list[dict], known_ids: dict[str, int] | None = None):
+    """The managed repo one of a clone's remotes is, or None.
+
+    Args:
+        remotes: The clone's remote addresses, origin first.
+        managed: The company's list: [{github_id, name, previous_names, https_url, ssh_url}].
+        known_ids: The GitHub id the machine found before for a remote, by its address.
+
+    Returns:
+        (the remote, the managed repo), or None.
+
+    Company: the one whose list is given.
+    """
+    known_ids = known_ids or {}
+    for remote in remotes:
+        here = location(remote)
+        for repo in managed:
+            if repo.get("github_id") and known_ids.get(remote) == repo["github_id"]:
+                return remote, repo
+            if here is None:
+                continue
+            addresses = {location(repo.get(k) or "") for k in ("https_url", "ssh_url")}
+            if here in addresses:
+                return remote, repo
+            hosts = {a[0] for a in addresses if a}
+            names = {n.lower() for n in [repo["name"], *repo.get("previous_names", [])]}
+            if here[0] in hosts and here[1] in names:
+                return remote, repo
+    return None