diffgenome 0.1.0__py3-none-any.whl

diffgenome/change.py

@@ -0,0 +1,86 @@
+"""Change-centred analysis: from a diff (or an explicit symbol) to changed symbols.
+
+Diff parsing is language-neutral (paths and line ranges on the new side). Mapping lines
+to symbols goes through a `SymbolIndex`, which a language adapter implements.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+from diffgenome.model import SymbolId
+
+
+class Located(Protocol):
+    @property
+    def symbol(self) -> SymbolId: ...
+
+
+class SymbolIndex(Protocol):
+    def symbols_at(self, rel_path: str, lines: set[int]) -> Sequence[Located]: ...
+
+
+@dataclass(frozen=True)
+class ChangedRange:
+    path: str
+    lines: frozenset[int]  # new-side line numbers; empty for pure deletions
+
+
+@dataclass
+class ChangeSet:
+    description: str
+    ranges: list[ChangedRange]
+    symbols: list[SymbolId]
+    unmapped_paths: list[str]  # changed files no symbol could be mapped for (non-code, deleted)
+
+
+_HUNK = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@")
+
+
+def parse_unified_diff(text: str) -> list[ChangedRange]:
+    ranges: dict[str, set[int]] = {}
+    path: str | None = None
+    for line in text.splitlines():
+        if line.startswith("+++ "):
+            target = line[4:].strip()
+            path = None if target == "/dev/null" else target.removeprefix("b/")
+            if path is not None:
+                ranges.setdefault(path, set())
+        elif line.startswith("@@") and path is not None:
+            m = _HUNK.match(line)
+            if m:
+                start, count = int(m.group(1)), int(m.group(2) or "1")
+                ranges[path].update(range(start, start + max(count, 1)))
+    return [ChangedRange(p, frozenset(ls)) for p, ls in sorted(ranges.items())]
+
+
+def git_diff(repo: Path, revspec: str) -> str:
+    """`revspec` like ``base..head`` or a single commit (diffed against its parent)."""
+    spec = revspec if ".." in revspec else f"{revspec}^..{revspec}"
+    return subprocess.run(
+        ["git", "diff", "--unified=0", "--no-color", spec],
+        cwd=repo, capture_output=True, text=True, check=True,
+    ).stdout  # fmt: skip
+
+
+def changes_from_diff(text: str, index: SymbolIndex, description: str) -> ChangeSet:
+    ranges = parse_unified_diff(text)
+    symbols: list[SymbolId] = []
+    unmapped: list[str] = []
+    for r in ranges:
+        defs = index.symbols_at(r.path, set(r.lines)) if r.lines else []
+        found = [d.symbol for d in defs]
+        if found:
+            symbols.extend(s for s in found if s not in symbols)
+        else:
+            unmapped.append(r.path)
+    return ChangeSet(description, ranges, symbols, unmapped)
+
+
+def changes_from_symbols(symbols: list[SymbolId]) -> ChangeSet:
+    return ChangeSet("symbol-centred: " + ", ".join(symbols), [], list(symbols), [])

diffgenome/change_artifact.py

@@ -0,0 +1,310 @@
+"""The integration artifact: ``diffgenome-change/1``.
+
+A bounded, deterministic, change-centred projection of the behavioral graph for consumers
+such as Sydes. It is derived from the same graph as ``map.md`` and ``slice.json`` but
+exposes no internal objects: symbols become nodes with stable ids and locations, evidence
+becomes one edge per (caller, callee) with its evidence class, join grade, STATE status,
+exit verdict and provenance, stand-in leaves become boundaries, and every join the composer
+rejected on a seam in the neighborhood is listed with its reason. It is consumable without
+the trace corpus. Nothing in it is a confidence score: the grades are the evidence.
+"""
+
+from __future__ import annotations
+
+import json
+from collections import Counter, defaultdict
+from datetime import UTC, datetime
+from typing import Any
+
+from diffgenome import __version__
+from diffgenome.graph import BehavioralGraph, GraphEdge
+from diffgenome.model import (
+    CallNode,
+    EvidenceKind,
+    Execution,
+    JoinStrength,
+    Origin,
+    Stimulus,
+    SymbolId,
+)
+from diffgenome.projection import case_metrics, project, render_behavior_map
+
+FORMAT = "diffgenome-change/1"
+
+# Evidence classes a consumer merges on. Observed and composed are runtime evidence of
+# different standing; the rest are places where DiffGenome's knowledge stops.
+EVIDENCE_OBSERVED = "observed"
+EVIDENCE_COMPOSED = "composed"
+EVIDENCE_EXTERNAL = "external"
+EVIDENCE_UNRESOLVED = "unresolved"
+EVIDENCE_GAP = "gap"
+EVIDENCE_DECLARATION = "declaration"
+EVIDENCE_OS = "os"
+
+
+def _name(symbol: SymbolId) -> str:
+    return symbol.split(":", 1)[1] if ":" in symbol else symbol
+
+
+def _execution_label(execution_id: str) -> str:
+    return execution_id.split("@")[0]
+
+
+def _test_file(ex: Execution) -> str | None:
+    """The test source file of an execution: the location of the first test-origin call
+    the collector attributed a location to (the stimulus root itself may carry none, as a
+    Go subtest's does)."""
+    symbols = {sym.id: sym for sym in ex.symbols}
+    for node in ex.nodes:
+        if isinstance(node, CallNode):
+            sym = symbols.get(node.symbol)
+            if sym is not None and sym.origin is Origin.TEST and sym.location is not None:
+                return sym.location.path
+    return None
+
+
+def _state_status(graph: BehavioralGraph, edge: GraphEdge) -> str:
+    """STATE evidence status of a composed edge, from the join attempts behind it:
+    ``matched`` (STATE grade reached), ``conflict-filtered`` (candidates were rejected on
+    state; the accepted ones matched), ``unavailable`` (VALUE held but no state facts on a
+    side), ``not_consulted`` (below VALUE, where STATE is never evaluated)."""
+    if edge.kind is not EvidenceKind.COMPOSED:
+        return "n/a"
+    best = edge.best_join
+    if best is JoinStrength.STATE:
+        return "matched"
+    sites = {ev.site for ev in edge.evidence}
+    notes = [a.note for a in graph.attempts if a.site in sites and a.target == edge.callee]
+    if best is JoinStrength.VALUE:
+        if any("state unavailable" in n or "no common state" in n for n in notes):
+            return "unavailable"
+        return "unavailable"
+    return "not_consulted"
+
+
+def _exit_status(edge: GraphEdge) -> str | None:
+    if edge.kind is not EvidenceKind.COMPOSED:
+        return None
+    verdicts = {ev.exit for ev in edge.evidence if ev.exit}
+    if not verdicts:
+        return None
+    for v in ("same", "kind", "unknown"):
+        if verdicts == {v}:
+            return v
+    return "mixed:" + "/".join(sorted(verdicts))
+
+
+def build_change_artifact(
+    graph: BehavioralGraph,
+    seeds: list[SymbolId],
+    *,
+    up: int,
+    down: int,
+    change_spec: str,
+    runtime: str,
+    repo: str,
+    revision: str | None,
+    budget: dict[str, Any],
+    probes: list[dict[str, Any]],
+    notes: list[str],
+    graph_before: BehavioralGraph | None = None,
+) -> dict[str, Any]:
+    """Build the artifact from a graph and the changed symbols. Deterministic for a
+    given graph: every list is sorted, every set rendered as a sorted list."""
+    nb = graph.neighborhood(seeds, up=up, down=down)
+    projected = project(graph)
+    keys = {(e.caller, e.callee) for _, e in nb.edges.values()}
+    distance: dict[tuple[SymbolId, SymbolId], int] = {}
+    for d, e in nb.edges.values():
+        key = (e.caller, e.callee)
+        distance[key] = min(d, distance.get(key, d))
+    edges_by_key: dict[tuple[SymbolId, SymbolId], list[GraphEdge]] = defaultdict(list)
+    for _, e in nb.edges.values():
+        edges_by_key[(e.caller, e.callee)].append(e)
+
+    # ---- nodes: every production symbol touched by the neighborhood, plus the seeds
+    node_ids: set[SymbolId] = set(seeds)
+    for (c, k), be in projected.items():
+        if (c, k) in keys and graph.origin(c) is not Origin.TEST:
+            node_ids.add(c)
+            if be.boundary is None:
+                node_ids.add(k)
+    nodes = []
+    for sid in sorted(node_ids):
+        sym = graph.symbols.get(sid)
+        nodes.append(
+            {
+                "id": sid,
+                "name": _name(sid),
+                "file": sym.location.path if sym and sym.location else None,
+                "line": sym.location.line if sym and sym.location else None,
+                "kind": sym.kind if sym else "callable",
+                "origin": (sym.origin.value if sym else Origin.UNKNOWN.value),
+                "changed": sid in seeds,
+                "executed_by": len(graph.tests_by_symbol.get(sid, ())),
+            }
+        )
+
+    # ---- edges and boundaries
+    edges: list[dict[str, Any]] = []
+    boundaries: list[dict[str, Any]] = []
+    for (c, k), be in sorted(projected.items()):
+        if (c, k) not in keys or graph.origin(c) is Origin.TEST:
+            continue
+        raw = edges_by_key[(c, k)]
+        if be.boundary is not None:
+            rules = sorted({r for e in raw for r in e.rules})
+            boundaries.append(
+                {
+                    "caller": c,
+                    "target": k,
+                    "target_name": _name(k),
+                    "kind": be.boundary,
+                    "rules": rules,
+                    "distance": distance[(c, k)],
+                    "executions": sorted(_execution_label(x) for x in be.tests | be.probes),
+                }
+            )
+            continue
+        composed = [e for e in raw if e.kind is EvidenceKind.COMPOSED]
+        observed = be.observed_executions
+        evidence = EVIDENCE_OBSERVED if observed else EVIDENCE_COMPOSED
+        best = be.best_grade
+        state = "n/a"
+        exit_ = None
+        if composed:
+            state = _state_status(graph, composed[0])
+            exit_ = _exit_status(composed[0])
+        edges.append(
+            {
+                "caller": c,
+                "callee": k,
+                "evidence": evidence,
+                "distance": distance[(c, k)],
+                "join": best if evidence == EVIDENCE_COMPOSED else None,
+                "also_composed_at": best if evidence == EVIDENCE_OBSERVED and best else None,
+                "state": state if evidence == EVIDENCE_COMPOSED else "n/a",
+                "exit": exit_,
+                "probe_derived": bool(be.probes) and not be.tests,
+                "executions": sorted(_execution_label(x) for x in be.tests),
+                "probes": sorted(_execution_label(x) for x in be.probes),
+                "composed_shapes_by_grade": dict(sorted(be.composed.items())),
+                "same_shape_alternates": be.alternates,
+                "ambiguous": be.ambiguous,
+                "rules": sorted(be.rules),
+            }
+        )
+
+    # ---- executions contributing
+    exec_ids = {
+        x
+        for be in projected.values()
+        for x in (be.tests | be.probes)
+        if (be.caller, be.callee) in keys
+    }
+    executions = []
+    for x in sorted(exec_ids):
+        stim = "generated_probe"
+        test_file: str | None = None
+        outcome: str | None = None
+        if graph.corpus is not None and x in graph.corpus.executions:
+            ex = graph.corpus.executions[x]
+            stim = ex.stimulus.value
+            test_file = _test_file(ex)
+            outcome = ex.outcome
+        elif "diffgenome_probe" not in x:
+            stim = Stimulus.EXISTING_TEST.value
+        executions.append(
+            {"id": _execution_label(x), "stimulus": stim, "file": test_file, "outcome": outcome}
+        )
+
+    # ---- ambiguous seams and rejected candidates on neighborhood seams
+    sites = {ev.site for _, e in nb.edges.values() for ev in e.evidence}
+    site_caller: dict[Any, SymbolId] = {}
+    for _, e in nb.edges.values():
+        for ev in e.evidence:
+            site_caller.setdefault(ev.site, e.caller)
+    rejected: list[dict[str, Any]] = []
+    by_seam: dict[tuple[SymbolId, SymbolId], Counter[str]] = defaultdict(Counter)
+    accepted_by_seam: dict[tuple[SymbolId, SymbolId], set[str]] = defaultdict(set)
+    for a in graph.attempts:
+        if a.site not in sites:
+            continue
+        seam = (site_caller.get(a.site, "?"), a.target)
+        if a.accepted:
+            accepted_by_seam[seam].add(a.fragment.execution)
+            continue
+        reason = a.note.split(";")[0].strip()
+        by_seam[seam][reason] += 1
+        rejected.append(
+            {
+                "caller": seam[0],
+                "target": a.target,
+                "candidate": _execution_label(a.fragment.execution),
+                "reason": reason,
+            }
+        )
+    rejected.sort(key=lambda r: (r["caller"], r["target"], r["candidate"], r["reason"]))
+    ambiguous_seams = [
+        {
+            "caller": c,
+            "target": k,
+            "accepted_candidates": len(accepted_by_seam.get((c, k), ())),
+            "rejected_candidates": sum(by_seam.get((c, k), Counter()).values()),
+            "rejection_reasons": dict(sorted(by_seam.get((c, k), Counter()).items())),
+        }
+        for (c, k) in sorted(set(by_seam) | {s for s, v in accepted_by_seam.items() if len(v) > 1})
+    ]
+
+    metrics = case_metrics(graph, seeds, up, down, [], graph_before)
+    facts = {
+        k: v
+        for k, v in metrics.items()
+        if k
+        in (
+            "observed_edges", "composed_edges", "joins", "rejected_joins", "ambiguous_joins",
+            "internal_gaps", "declarations_no_in_repo_body", "unresolved_boundaries",
+            "external_boundaries", "existing_tests_contributing", "probe_derived_edges",
+            "structural_coverage_ratio_NOT_correctness",
+        )
+    }  # fmt: skip
+    return {
+        "format": FORMAT,
+        "generated_by": f"diffgenome {__version__}",
+        "generated_at": datetime.now(tz=UTC).isoformat(timespec="seconds"),
+        "repository": {"root": repo, "runtime": runtime, "revision": revision or "checkout"},
+        "change": {
+            "spec": change_spec,
+            "symbols": sorted(seeds),
+            "symbols_never_executed": sorted(s for s in seeds if s not in graph.tests_by_symbol),
+        },
+        "neighborhood": {"up": up, "down": down, "symbols": len(node_ids)},
+        "budget": budget,
+        "nodes": nodes,
+        "edges": edges,
+        "boundaries": boundaries,
+        "executions": executions,
+        "ambiguous_seams": ambiguous_seams,
+        "rejected_candidates": rejected[:200],
+        "probes": probes,
+        "facts": facts,
+        "invariants": [
+            "observed edges were seen in one execution; composed edges are reconstructed "
+            "across a stand-in seam and are never presented as observed",
+            "join grades are evidence classes, not a probability: "
+            "SYMBOL < ARG_SHAPE < VALUE < STATE",
+            "structural_coverage_ratio_NOT_correctness counts symbol pairs with evidence; "
+            "it says nothing about whether the behavior is right",
+            "boundaries are where DiffGenome's knowledge stops: external stays substituted, "
+            "unresolved was not attributed, gap has no executing fragment",
+        ],
+        "notes": list(notes),
+    }
+
+
+def render_behavioral_map(graph: BehavioralGraph, seeds: list[SymbolId], up: int, down: int) -> str:
+    return render_behavior_map(graph, seeds, up=up, down=down)
+
+
+def dumps(artifact: dict[str, Any]) -> str:
+    return json.dumps(artifact, indent=1, sort_keys=False) + "\n"

diffgenome/collect/__init__.py

@@ -0,0 +1,2 @@
+"""Capture adapters. Each is specific to a platform or runtime and emits the protocol in
+`diffgenome.model`. Nothing outside this package may depend on how capture works."""

diffgenome/collect/go_test.py

@@ -0,0 +1,271 @@
+"""Go runtime adapter: source instrumentation + `go test`.
+
+Everything Go-specific lives here and in diffgenome/_collectors/go. The workspace copy gets the
+`dg` runtime package copied to `<module>/internal/diffgenome/dg`, its sources rewritten in
+place by the instrumenter (built once with the host Go), and `go test` runs inside the
+sandbox with the module cache read-only and GOPROXY=off (no network). Generated mock
+packages are test origin; their methods claim the sole in-repo definer of the mocked
+interface method (a static fact from the MockGen header and the package's method sets).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from diffgenome.model import Execution, Stimulus, SymbolId
+from diffgenome.probe import copy_probe_traces
+from diffgenome.runtime import SymbolIndex
+from diffgenome.sandbox import Workspace
+from diffgenome.serialize import execution_from_json
+
+TOOLS = Path(__file__).resolve().parent.parent / "_collectors" / "go"
+
+
+@dataclass(frozen=True)
+class Definition:
+    symbol: SymbolId
+    path: str
+    start: int
+    end: int
+    kind: str
+
+
+class GoSymbolIndex:
+    def __init__(
+        self,
+        repo_root: Path,
+        source_roots: list[Path],
+        test_roots: list[Path],
+        index_file: Path,
+        mock_roots: list[Path] | None = None,
+    ) -> None:
+        self.repo_root = repo_root.resolve()
+        self.source_roots = [p.resolve() for p in source_roots]
+        self.test_roots = [p.resolve() for p in test_roots]
+        self.mock_roots = [p.resolve() for p in (mock_roots or [])]
+        doc = json.loads(index_file.read_text())
+        self._defs = [
+            Definition(d["symbol"], d["path"], d["start"], d["end"], d["kind"])
+            for d in doc["definitions"]
+        ]
+        self._by_symbol = {d.symbol: d for d in self._defs}
+        self._by_path: dict[str, list[Definition]] = {}
+        for d in self._defs:
+            self._by_path.setdefault(d.path, []).append(d)
+
+    def definitions(self, rel_path: str) -> list[Definition]:
+        return self._by_path.get(rel_path, [])
+
+    def symbols_at(self, rel_path: str, lines: set[int]) -> list[Definition]:
+        hits: dict[SymbolId, Definition] = {}
+        for line in lines:
+            covering = [d for d in self.definitions(rel_path) if d.start <= line <= d.end]
+            funcs = [d for d in covering if d.kind == "function"]
+            pick = (
+                max(funcs, key=lambda d: d.start)
+                if funcs
+                else (max(covering, key=lambda d: d.start) if covering else None)
+            )
+            if pick:
+                hits[pick.symbol] = pick
+        return sorted(hits.values(), key=lambda d: (d.path, d.start))
+
+    def find(self, symbol: SymbolId) -> Definition | None:
+        return self._by_symbol.get(symbol)
+
+    def source(self, symbol: SymbolId, context: int = 0) -> str | None:
+        d = self.find(symbol)
+        if d is None:
+            return None
+        lines = (self.repo_root / d.path).read_text(encoding="utf-8").splitlines()
+        lo, hi = max(0, d.start - 1 - context), min(len(lines), d.end + context)
+        return "\n".join(f"{i + 1:5d}  {lines[i]}" for i in range(lo, hi))
+
+    def enclosing_class(self, symbol: SymbolId) -> Definition | None:
+        # go:pkg.Type.Method -> go:pkg.Type
+        name = symbol.split(":", 1)[1]
+        parts = name.split(".")
+        if len(parts) < 3:
+            return None
+        return self.find("go:" + ".".join(parts[:-1]))
+
+    def is_test(self, symbol: SymbolId) -> bool:
+        # Go tests live beside the code: test-ness is the _test.go suffix or a mock package.
+        d = self.find(symbol)
+        if d is None:
+            return False
+        if d.path.endswith("_test.go"):
+            return True
+        path = self.repo_root / d.path
+        return any(path.is_relative_to(r) for r in self.mock_roots)
+
+    def return_type_of(self, symbol: SymbolId) -> SymbolId | None:
+        return None  # not extracted for this runtime yet
+
+    def module_of(self, symbol: SymbolId) -> str | None:
+        d = self.find(symbol)
+        return d.path.rsplit("/", 1)[0] if d and "/" in d.path else ("." if d else None)
+
+    def tests_importing(self, module: str, limit: int = 3) -> list[str]:
+        # Go tests live in the package directory itself.
+        pkg = self.repo_root / module
+        hits = (
+            sorted(str(f.relative_to(self.repo_root)) for f in pkg.glob("*_test.go"))
+            if pkg.is_dir()
+            else []
+        )
+        return hits[:limit]
+
+
+class GoTestRuntime:
+    name = "go/test"
+
+    def __init__(
+        self,
+        repo: Path,
+        source_root: str,
+        test_root: str,
+        tests: str,
+        mock_dirs: list[str] | None = None,
+    ) -> None:
+        self.repo = repo.resolve()
+        self.source_root = source_root
+        self.test_root = test_root  # package dir whose tests are the stimuli, e.g. "api"
+        self.tests = tests  # go test pattern, e.g. "./api/"
+        self.mock_dirs = mock_dirs or []
+        which = shutil.which("go")
+        if not which:
+            raise RuntimeError("go not found on PATH")
+        self.go = Path(which).resolve()
+        self.module = self._module_path()
+        self.gopath = Path(
+            subprocess.run(
+                [str(self.go), "env", "GOPATH"], capture_output=True, text=True
+            ).stdout.strip()
+        )
+        self.gocache = Path(
+            subprocess.run(
+                [str(self.go), "env", "GOCACHE"], capture_output=True, text=True
+            ).stdout.strip()
+        )
+
+    def _module_path(self) -> str:
+        for line in (self.repo / "go.mod").read_text().splitlines():
+            if line.startswith("module "):
+                return line.split()[1]
+        raise RuntimeError("go.mod has no module line")
+
+    def prepare(self, ws: Workspace) -> SymbolIndex:
+        # runtime package inside the module so no network/module edits are needed
+        dst = ws.repo / "internal" / "diffgenome" / "dg"
+        dst.mkdir(parents=True, exist_ok=True)
+        shutil.copy(TOOLS / "dg" / "dg.go", dst / "dg.go")
+        tool = ws.root / "dg-instrument"
+        # build from a copy inside the workspace: the installed package may be read-only
+        build_dir = ws.root / "go-collector"
+        if not build_dir.exists():
+            shutil.copytree(TOOLS, build_dir)
+        subprocess.run(
+            [str(self.go), "build", "-o", str(tool), "./instrument"],
+            cwd=build_dir, check=True, capture_output=True, text=True,
+            env={**os.environ, "GOFLAGS": "-mod=mod", "GOPROXY": "off"},
+        )  # fmt: skip
+        index_file = ws.root / "symbol-index.json"
+        result = subprocess.run(
+            [
+                str(tool), "-root", str(ws.repo), "-module", self.module, "-src", self.source_root,
+                "-tests", ",".join(self.mock_dirs), "-index", str(index_file),
+                "-facts", str(ws.root / "mechanics-ir.json"),
+            ],
+            capture_output=True, text=True, check=True,
+        )  # fmt: skip
+        (ws.root / "instrument.log").write_text(result.stdout + result.stderr)
+        mock_roots = [self.repo / d for d in self.mock_dirs]
+        return GoSymbolIndex(
+            self.repo,
+            [self.repo / self.source_root],
+            [self.repo / self.test_root, *mock_roots],
+            index_file,
+            mock_roots,
+        )
+
+    def trace(
+        self, ws: Workspace, out_dir: Path, stimulus: Stimulus, only: list[str] | None
+    ) -> tuple[list[Execution], str, str]:
+        tag = "existing" if stimulus is Stimulus.EXISTING_TEST else "probe"
+        traces_ws = ws.root / f"traces-{tag}-{len(list(ws.root.glob('traces-*')))}"
+        traces_ws.mkdir(parents=True, exist_ok=True)
+        env = {
+            "DIFFGENOME_OUT": str(traces_ws),
+            "DIFFGENOME_STIMULUS": stimulus.value,
+            "GOPATH": str(self.gopath),
+            "GOCACHE": str(ws.root / "gocache"),
+            "GOMODCACHE": str(self.gopath / "pkg" / "mod"),
+            "GOFLAGS": "-mod=mod",
+            "GOPROXY": "off",
+            "GOTOOLCHAIN": "local",
+            "CGO_ENABLED": "0",
+            "PATH": f"{self.go.parent}:/usr/bin:/bin",
+        }
+        argv = [str(self.go), "test", "-count=1", "-p", "1"]
+        if only:
+            # A probe file added after preparation must be instrumented too (Begin/End
+            # come from instrumentation); already-instrumented files are skipped.
+            tool = ws.root / "dg-instrument"
+            subprocess.run(
+                [
+                    str(tool), "-root", str(ws.repo), "-module", self.module,
+                    "-src", os.path.dirname(only[0]) or ".", "-tests", ",".join(self.mock_dirs),
+                ],
+                capture_output=True, text=True, check=True,
+            )  # fmt: skip
+            # a probe file lives in the package dir; run that package, only the probe tests
+            pkg = "./" + os.path.dirname(only[0]) + "/"
+            argv += ["-run", "DiffgenomeProbe", pkg]
+        else:
+            argv += [self.tests]
+        result = ws.run(argv, env=env, timeout=1800, allow_loopback=True)
+        out_dir.mkdir(parents=True, exist_ok=True)
+        copy_probe_traces(traces_ws, out_dir)
+        executions = [execution_from_json(f.read_text()) for f in sorted(out_dir.glob("*.json"))]
+        return executions, result.stdout, result.stderr
+
+    def probe_relpath(self, tag: str) -> str:
+        return f"{self.test_root}/diffgenome_probe_{tag}_test.go"
+
+    def conventions(self, index: SymbolIndex) -> str:
+        return (
+            f"Runtime: Go ({self._go_version()}), the standard `go test` runner with testify "
+            "(`require`) and gomock available. The probe is a file named "
+            f"diffgenome_probe_*_test.go placed in the package directory `{self.test_root}/` "
+            f"(package `{self._package_name()}`), so it can use unexported identifiers of that "
+            "package directly; test functions MUST be named TestDiffgenomeProbe... so the "
+            f"harness can select them. Module path: {self.module}. No network and no database "
+            "are available; substitute the Store with the generated gomock "
+            "(`mockdb.NewMockStore(ctrl)`) as the existing tests do. Only modules already in "
+            "go.mod can be imported (GOPROXY=off): the standard library, this module, testify, "
+            "gomock, pgx/v5 and gin; do not add new dependencies. Sqlc `Queries` take a `DBTX` "
+            "interface (pgx), so a hand-written fake DBTX returning a fake `pgx.Row` can drive "
+            "real query code without a database."
+        )
+
+    def _package_name(self) -> str:
+        pkg = self.repo / self.test_root
+        for f in sorted(pkg.glob("*.go")):
+            for line in f.read_text(encoding="utf-8").splitlines():
+                if line.startswith("package "):
+                    return line.split()[1]
+        return os.path.basename(self.test_root)
+
+    def _go_version(self) -> str:
+        try:
+            return subprocess.run(
+                [str(self.go), "version"], capture_output=True, text=True, timeout=10
+            ).stdout.strip()
+        except (OSError, subprocess.TimeoutExpired):
+            return "?"