diffcone 0.1.0__py3-none-any.whl

diffcone/evidence.py

@@ -0,0 +1,738 @@
+"""Execution evidence: what each test executed at one commit, as planning data.
+
+The recorder (``diffcone/collect.py``, a pytest plugin) writes raw per-process
+records of code objects and repository paths. :func:`fold` maps those code
+objects to symbols of diffcone's own index of the same commit and checks the
+collection is usable; :func:`write_store` and :func:`load_store` keep the
+result in ``.diffcone/evidence/<commit>-<environment>.sqlite``.
+
+Nothing here runs project code, and the planner treats an :class:`Evidence`
+the way it treats a manifest: data a runner integration produced. See
+internal/evidence_design.md.
+"""
+
+from __future__ import annotations
+
+import array
+import glob
+import json
+import os
+import sqlite3
+import struct
+import subprocess
+import tempfile
+import time
+import zlib
+from bisect import bisect_right
+from collections import defaultdict
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from diffcone.cache import make_own_dir
+from diffcone.cython import symbol_id
+from diffcone.model import MODULE, SourceIndex
+
+STORE_FORMAT = 1
+FLAG_SUBPROCESS = 1  # the test started a subprocess, whose execution is not seen
+FLAG_UNSTABLE = 2  # the test's record differed between two collections
+EVIDENCE_DIR = Path(".diffcone") / "evidence"
+# An import run by a module outside the source roots: nothing static can say
+# who observes what it built.
+UNINDEXED_MODULE = "path:"
+
+
+class EvidenceError(Exception):
+    """A collection that cannot be trusted, or a store that cannot be read."""
+
+
+@dataclass(frozen=True)
+class TestRecord:
+    __test__ = False  # not a pytest class
+
+    symbols: frozenset[int]
+    paths: frozenset[int]  # opened or stat'ed (indices into Evidence.paths)
+    dirs: frozenset[int] = frozenset()  # listed
+    flags: int = 0
+
+
+@dataclass
+class Evidence:
+    commit: str
+    source_roots: list[str]
+    environment: dict
+    environment_hash: str
+    command: str
+    created: float
+    symbols: list[str]
+    paths: list[str]
+    tests: dict[str, TestRecord]
+    # Symbols executed outside every test window (imports, collection, hooks).
+    import_phase: frozenset[str] = frozenset()
+    # Symbol -> the modules whose import ran it (``path:<file>`` for a module
+    # outside the index).
+    import_by: dict[str, frozenset[str]] = field(default_factory=dict)
+    # Symbols executed outside every test window while no import was running
+    # (session hooks, collection, pytest_generate_tests).
+    hook_phase: frozenset[str] = frozenset()
+    # Paths project code opened or stat'ed outside every test window
+    # -> the modules being imported then ("" for none: a hook or collection;
+    # ``path:<file>`` for a module outside the index).
+    import_paths: dict[str, frozenset[str]] = field(default_factory=dict)
+    import_dirs: dict[str, frozenset[str]] = field(default_factory=dict)  # listed, likewise
+    # Something outside every test window started a subprocess.
+    import_subprocess: bool = False
+    reverse_checked: bool = False
+    # The store this one was advanced from (``run --collect``), and the commit
+    # of the last full collection in its line (its own commit when it is one).
+    advanced_from: str | None = None
+    full_commit: str | None = None
+    # Every test pytest collected at the commit (parameters folded), before
+    # any deselection; None when not recorded (an older store, or advanced
+    # by a run that ran nothing).
+    collected: frozenset[str] | None = None
+    location: Path | None = None
+
+    def executed(self, record: TestRecord) -> set[str]:
+        return {self.symbols[i] for i in record.symbols}
+
+    def touched(self, record: TestRecord) -> set[str]:
+        """Paths the test opened or stat'ed."""
+        return {self.paths[i] for i in record.paths}
+
+    def listed(self, record: TestRecord) -> set[str]:
+        """Directories the test listed."""
+        return {self.paths[i] for i in record.dirs}
+
+
+# --------------------------------------------------------------------------- folding
+
+
+class _Owners:
+    """Code object (file, first line, qualname) -> the innermost symbol whose
+    definition contains that line; a module's own code maps to the module.
+    Nested functions, lambdas and comprehensions land in their enclosing
+    symbol, as coverage validation maps lines."""
+
+    def __init__(self, index: SourceIndex) -> None:
+        self.cython = index.cython
+        self.module_of_path: dict[str, str] = {}
+        spans: dict[str, list[tuple[int, int, str]]] = defaultdict(list)
+        for symbol in index.symbols.values():
+            if symbol.kind == MODULE:
+                self.module_of_path[symbol.path] = symbol.id
+            for start, end in symbol.line_ranges:
+                spans[symbol.path].append((start, end, symbol.id))
+        self.spans = {path: sorted(s) for path, s in spans.items()}
+        self.starts = {path: [s[0] for s in spans_] for path, spans_ in self.spans.items()}
+        self.memo: dict[tuple[str, int, str], str | None] = {}
+
+    def __call__(self, path: str, line: int, qualname: str) -> str | None:
+        key = (path, line, qualname)
+        if key in self.memo:
+            return self.memo[key]
+        cython = self.cython.get(path)
+        if cython is not None:
+            # A profiled Cython build: the function whose span holds the code
+            # object's first line (its first decorator); module-level code
+            # maps to no symbol and stays a path the test touched.
+            function = cython.function_at(line)
+            self.memo[key] = symbol_id(path, function.name) if function else None
+            return self.memo[key]
+        found = self.module_of_path.get(path)
+        if qualname != "<module>" and path in self.spans:
+            best: tuple[int, str] | None = None
+            spans = self.spans[path]
+            for i in range(bisect_right(self.starts[path], line) - 1, -1, -1):
+                start, end, sid = spans[i]
+                if end >= line and (best is None or end - start < best[0]):
+                    best = (end - start, sid)
+            if best is not None:
+                found = best[1]
+        self.memo[key] = found
+        return found
+
+
+@dataclass
+class _Raw:
+    tests: dict[str, tuple[set[str], set[str], set[str], int]]
+    import_phase: set[str]
+    hook_phase: set[str]
+    import_by: dict[str, set[str]]
+    import_paths: dict[str, set[str]]
+    import_dirs: dict[str, set[str]]
+    import_subprocess: bool
+    environment: dict
+    environment_hash: str
+    collected: set[str] | None = None
+    # A shared fixture (by key) -> what its setup ran in any process, and
+    # the shared fixtures each test used.
+    fixtures: dict[str, tuple[set[str], set[str], set[str], int]] = field(default_factory=dict)
+    test_fixtures: dict[str, set[str]] = field(default_factory=dict)
+
+
+def _read_raw(directory: Path, owners: _Owners, project_modules: set[str]) -> _Raw:
+    processes = sorted(glob.glob(str(directory / "process-*.json")))
+    if not processes:
+        raise EvidenceError(
+            "the suite wrote no evidence: was the plugin loaded (-p diffcone_collect), "
+            "and did pytest run at all?"
+        )
+    raw = _Raw(
+        {}, set(), set(), defaultdict(set), defaultdict(set), defaultdict(set), False, {}, ""
+    )
+    environments: list[dict] = []
+    seen_pids = set()
+    for process_file in processes:
+        with open(process_file, encoding="utf-8") as f:
+            data = json.load(f)
+        pid = str(data["pid"])
+        seen_pids.add(pid)
+        if data["errors"]:
+            raise EvidenceError(
+                "the recorder failed inside the suite, so the record may be incomplete: "
+                + "; ".join(data["errors"][:5])
+            )
+        shadowed = [
+            (name, file) for name, file in data["outside_modules"] if name in project_modules
+        ]
+        if shadowed:
+            name, file = shadowed[0]
+            raise EvidenceError(
+                f"the suite imported {name} from {file}, outside the checkout: it ran an "
+                f"installed copy of the project, not the code at this commit "
+                f"({len(shadowed)} module(s))"
+            )
+        environments.append(data["environment"])
+        raw.environment_hash = data["environment_hash"]
+        if data.get("collected") is not None:
+            raw.collected = (raw.collected or set()) | set(data["collected"])
+        symbol_of: list[str | None] = []
+        file_of: list[str | None] = []
+        for path, line, qualname in data["table"]:
+            symbol = owners(path, line, qualname)
+            symbol_of.append(symbol)
+            # Code from a repository file the index does not read (outside the
+            # source roots): recorded as a path the test touched.
+            file_of.append(None if symbol is not None else path)
+        for i in data["import_phase"]:
+            if symbol_of[i] is not None:
+                raw.import_phase.add(symbol_of[i])
+            elif file_of[i] is not None:
+                raw.import_paths[file_of[i]].add("")
+        for i in data["hook_phase"]:
+            if symbol_of[i] is not None:
+                raw.hook_phase.add(symbol_of[i])
+        for key, seen in (("import_paths", raw.import_paths), ("import_dirs", raw.import_dirs)):
+            for path, modules in data[key].items():
+                for module_path in modules:
+                    module = owners.module_of_path.get(module_path) if module_path else ""
+                    seen[path].add(module if module is not None else UNINDEXED_MODULE + module_path)
+        raw.import_subprocess |= bool(data["import_flags"] & FLAG_SUBPROCESS)
+        for key, modules in data["import_by"].items():
+            symbol = symbol_of[int(key)]
+            if symbol is None:
+                continue
+            for module_path in modules:
+                module = owners.module_of_path.get(module_path)
+                raw.import_by[symbol].add(module or UNINDEXED_MODULE + module_path)
+        for key, w in data.get("fixtures", {}).items():
+            symbols, paths, dirs, flags = raw.fixtures.setdefault(key, (set(), set(), set(), 0))
+            for c in w["codes"]:
+                if symbol_of[c] is not None:
+                    symbols.add(symbol_of[c])
+                elif file_of[c] is not None:
+                    paths.add(file_of[c])
+            paths.update(w["paths"])
+            dirs.update(w["dirs"])
+            raw.fixtures[key] = (symbols, paths, dirs, flags | w["flags"])
+        tests_file = directory / f"tests-{pid}.bin"
+        if data["wrote_tests"]:
+            if not tests_file.exists():
+                raise EvidenceError(f"process {pid} recorded no test file")
+            blob = tests_file.read_bytes()
+            i = 0
+            while i < len(blob):
+                try:
+                    n, m = struct.unpack_from("<II", blob, i)
+                    i += 8
+                    name = blob[i : i + n].decode()
+                    i += n
+                    record = json.loads(zlib.decompress(blob[i : i + m]))
+                except (struct.error, zlib.error, UnicodeDecodeError, ValueError) as exc:
+                    raise EvidenceError(
+                        f"process {pid} wrote a truncated or corrupt test file ({exc})"
+                    ) from exc
+                i += m
+                symbols, paths, dirs, flags = raw.tests.setdefault(name, (set(), set(), set(), 0))
+                for c in record["codes"]:
+                    if symbol_of[c] is not None:
+                        symbols.add(symbol_of[c])
+                    elif file_of[c] is not None:
+                        paths.add(file_of[c])
+                paths.update(record["paths"])
+                dirs.update(record["dirs"])
+                raw.tests[name] = (symbols, paths, dirs, flags | record["flags"])
+                raw.test_fixtures.setdefault(name, set()).update(record.get("fixtures", ()))
+    orphans = [
+        p
+        for p in glob.glob(str(directory / "tests-*.bin"))
+        if Path(p).stem.split("-", 1)[1] not in seen_pids
+    ]
+    if orphans:
+        raise EvidenceError(
+            f"{len(orphans)} test process(es) ended without finishing their record "
+            "(a crashed worker?); the evidence would be incomplete"
+        )
+    if any(env != environments[0] for env in environments):
+        raise EvidenceError("the test processes ran in different environments")
+    raw.environment = environments[0]
+    # A shared fixture set up in several processes (xdist workers) may have
+    # run its real work in one only (a file lock, a cache file the others
+    # read): every test using it is credited with what it ran anywhere.
+    for name, keys in raw.test_fixtures.items():
+        symbols, paths, dirs, flags = raw.tests[name]
+        for key in keys:
+            f_symbols, f_paths, f_dirs, f_flags = raw.fixtures.get(key, (set(), set(), set(), 0))
+            symbols |= f_symbols
+            paths |= f_paths
+            dirs |= f_dirs
+            flags |= f_flags
+        raw.tests[name] = (symbols, paths, dirs, flags)
+    return raw
+
+
+def fold(
+    directories: list[Path],
+    index: SourceIndex,
+    *,
+    commit: str,
+    source_roots: list[str],
+    command: str,
+    project_modules: set[str],
+) -> Evidence:
+    """Turn one or two raw collections (the second in reverse order) into
+    evidence. A test whose record differs between the two is unstable: its
+    path depends on what ran before it, so it is always selected.
+    ``project_modules`` are the importable names of the indexed modules: one
+    of them loaded from outside the checkout means an installed copy ran."""
+    owners = _Owners(index)
+    raws = [_read_raw(d, owners, project_modules) for d in directories]
+    if len(raws) > 1 and raws[1].environment != raws[0].environment:
+        raise EvidenceError("the two collections ran in different environments")
+    unstable: set[str] = set()
+    tests: dict[str, tuple[set[str], set[str], set[str], int]] = {}
+    # Stability is judged on symbols and tracked data files. pytest stats
+    # package directories and ``__init__`` files lazily, during whichever
+    # test runs first, and that is not the test's own behaviour.
+    data_files = set(index.other_files)
+    for raw in raws:
+        for name, (symbols, paths, dirs, flags) in raw.tests.items():
+            if name in tests:
+                before = tests[name]
+                if before[0] != symbols or (before[1] ^ paths) & data_files:
+                    unstable.add(name)
+                tests[name] = (
+                    before[0] | symbols,
+                    before[1] | paths,
+                    before[2] | dirs,
+                    before[3] | flags,
+                )
+            else:
+                if len(raws) > 1 and raw is not raws[0]:
+                    unstable.add(name)  # ran in one order only
+                tests[name] = (set(symbols), set(paths), set(dirs), flags)
+    if len(raws) > 1:
+        unstable |= set(raws[0].tests) - set(raws[1].tests)
+    symbol_table = sorted({s for symbols, _, _, _ in tests.values() for s in symbols})
+    path_table = sorted({p for _, paths, dirs, _ in tests.values() for p in paths | dirs})
+    sid = {s: i for i, s in enumerate(symbol_table)}
+    pid = {p: i for i, p in enumerate(path_table)}
+    shared: dict[frozenset[int], frozenset[int]] = {}
+
+    def intern(ids: frozenset[int]) -> frozenset[int]:
+        return shared.setdefault(ids, ids)
+
+    records = {
+        name: TestRecord(
+            intern(frozenset(sid[s] for s in symbols)),
+            intern(frozenset(pid[p] for p in paths)),
+            intern(frozenset(pid[p] for p in dirs)),
+            flags | (FLAG_UNSTABLE if name in unstable else 0),
+        )
+        for name, (symbols, paths, dirs, flags) in sorted(tests.items())
+    }
+    return Evidence(
+        commit=commit,
+        source_roots=list(source_roots),
+        environment=raws[0].environment,
+        environment_hash=raws[0].environment_hash,
+        command=command,
+        created=time.time(),
+        symbols=symbol_table,
+        paths=path_table,
+        tests=records,
+        import_phase=frozenset().union(*(r.import_phase for r in raws)),
+        hook_phase=frozenset().union(*(r.hook_phase for r in raws)),
+        import_by=_merged(r.import_by for r in raws),
+        import_paths=_merged(r.import_paths for r in raws),
+        import_dirs=_merged(r.import_dirs for r in raws),
+        import_subprocess=any(r.import_subprocess for r in raws),
+        reverse_checked=len(raws) > 1,
+        collected=(
+            frozenset().union(*(r.collected for r in raws if r.collected is not None))
+            if any(r.collected is not None for r in raws)
+            else None
+        ),
+    )
+
+
+def advance(
+    previous: Evidence,
+    fresh: Evidence | None,
+    rerun: set[str],
+    commit: str,
+    alive: set[str] | None = None,
+) -> Evidence:
+    """The evidence for ``commit`` after a run of the tests ``rerun`` there,
+    from ``previous`` (evidence at an ancestor C whose plan selected
+    ``rerun``) and ``fresh`` (what that run recorded; None when nothing ran).
+
+    A test the plan did not select runs identically at C and at ``commit``,
+    so its record carries over. A rerun test takes its fresh record, keeping
+    an ``unstable`` flag a partial run cannot re-check; one that recorded
+    nothing is dropped and has no evidence from here on. Process-wide data
+    is the union of both: the run imported only what its tests needed, and a
+    stale entry only escalates more (roadmap item 6).
+
+    With ``alive`` (the tests that are targets at ``commit``) a carried record
+    of any other test, one deleted since C, is dropped. Dropping is always
+    safe: a test without a record is selected."""
+    if fresh is not None:
+        if fresh.environment_hash != previous.environment_hash:
+            raise EvidenceError("the run's environment differs from the recording's")
+        if sorted(fresh.source_roots) != sorted(previous.source_roots):
+            raise EvidenceError("the run's source roots differ from the recording's")
+    sources = [previous] + ([fresh] if fresh is not None else [])
+    tests: dict[str, tuple[Evidence, TestRecord, int]] = {
+        name: (previous, record, 0)
+        for name, record in previous.tests.items()
+        if name not in rerun and (alive is None or name in alive)
+    }
+    if fresh is not None:
+        for name, record in fresh.tests.items():
+            old = previous.tests.get(name)
+            tests[name] = (fresh, record, old.flags & FLAG_UNSTABLE if old else 0)
+    symbol_table = sorted({ev.symbols[i] for ev, r, _ in tests.values() for i in r.symbols})
+    path_table = sorted({ev.paths[i] for ev, r, _ in tests.values() for i in r.paths | r.dirs})
+    sid = {s: i for i, s in enumerate(symbol_table)}
+    pid = {p: i for i, p in enumerate(path_table)}
+    # Keyed by the table as well as the set: fold interns equal sets across
+    # symbols and paths, and records share sets, which the store keeps once.
+    shared: dict[tuple[int, int], frozenset[int]] = {}
+
+    def remap(ids: frozenset[int], table: list[str], new: dict[str, int]) -> frozenset[int]:
+        key = (id(table), id(ids))
+        if key not in shared:
+            shared[key] = frozenset(new[table[i]] for i in ids)
+        return shared[key]
+
+    records = {
+        name: TestRecord(
+            remap(r.symbols, ev.symbols, sid),
+            remap(r.paths, ev.paths, pid),
+            remap(r.dirs, ev.paths, pid),
+            r.flags | carried,
+        )
+        for name, (ev, r, carried) in sorted(tests.items())
+    }
+    return Evidence(
+        commit=commit,
+        source_roots=list(previous.source_roots),
+        environment=previous.environment,
+        environment_hash=previous.environment_hash,
+        command=previous.command,
+        created=time.time(),
+        symbols=symbol_table,
+        paths=path_table,
+        tests=records,
+        import_phase=frozenset().union(*(e.import_phase for e in sources)),
+        hook_phase=frozenset().union(*(e.hook_phase for e in sources)),
+        import_by=_merged(e.import_by for e in sources),
+        import_paths=_merged(e.import_paths for e in sources),
+        import_dirs=_merged(e.import_dirs for e in sources),
+        import_subprocess=any(e.import_subprocess for e in sources),
+        reverse_checked=previous.reverse_checked,
+        advanced_from=previous.commit,
+        full_commit=previous.full_commit or previous.commit,
+        # The run collected the whole suite at head before selecting from
+        # it; with nothing run, head's collection is unknown.
+        collected=fresh.collected if fresh is not None else None,
+    )
+
+
+def _merged(maps: Iterable[dict[str, set[str]]]) -> dict[str, frozenset[str]]:
+    out: dict[str, set[str]] = defaultdict(set)
+    for mapping in maps:
+        for key, values in mapping.items():
+            out[key] |= values
+    return {k: frozenset(v) for k, v in sorted(out.items())}
+
+
+# --------------------------------------------------------------------------- store
+
+
+def _pack(ids) -> bytes:
+    return zlib.compress(array.array("I", sorted(ids)).tobytes(), 6)
+
+
+def _unpack(blob: bytes) -> frozenset[int]:
+    values = array.array("I")
+    values.frombytes(zlib.decompress(blob))
+    return frozenset(values)
+
+
+def store_name(evidence: Evidence) -> str:
+    return f"{evidence.commit}-{evidence.environment_hash}.sqlite"
+
+
+def write_store(evidence: Evidence, directory: Path) -> Path:
+    """Write atomically: a reader never sees half a store."""
+    make_own_dir(directory)
+    target = directory / store_name(evidence)
+    fd, tmp = tempfile.mkstemp(dir=directory, suffix=".tmp")
+    os.close(fd)
+    try:
+        db = sqlite3.connect(tmp)
+        with db:
+            db.executescript(
+                """
+                CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+                CREATE TABLE symbols (id INTEGER PRIMARY KEY, name TEXT NOT NULL);
+                CREATE TABLE paths (id INTEGER PRIMARY KEY, path TEXT NOT NULL);
+                CREATE TABLE sets (id INTEGER PRIMARY KEY, data BLOB NOT NULL);
+                CREATE TABLE tests (
+                    target TEXT PRIMARY KEY, symbols INTEGER NOT NULL,
+                    paths INTEGER NOT NULL, dirs INTEGER NOT NULL, flags INTEGER NOT NULL);
+                CREATE TABLE import_by (symbol TEXT NOT NULL, module TEXT NOT NULL);
+                """
+            )
+            meta = {
+                "format": STORE_FORMAT,
+                "commit": evidence.commit,
+                "source_roots": evidence.source_roots,
+                "environment": evidence.environment,
+                "environment_hash": evidence.environment_hash,
+                "command": evidence.command,
+                "created": evidence.created,
+                "import_phase": sorted(evidence.import_phase),
+                "hook_phase": sorted(evidence.hook_phase),
+                "import_paths": {p: sorted(m) for p, m in evidence.import_paths.items()},
+                "import_dirs": {p: sorted(m) for p, m in evidence.import_dirs.items()},
+                "import_subprocess": evidence.import_subprocess,
+                "reverse_checked": evidence.reverse_checked,
+                "advanced_from": evidence.advanced_from,
+                "full_commit": evidence.full_commit or evidence.commit,
+                "collected": sorted(evidence.collected) if evidence.collected is not None else None,
+            }
+            db.executemany(
+                "INSERT INTO meta VALUES (?, ?)", [(k, json.dumps(v)) for k, v in meta.items()]
+            )
+            db.executemany("INSERT INTO symbols VALUES (?, ?)", enumerate(evidence.symbols))
+            db.executemany("INSERT INTO paths VALUES (?, ?)", enumerate(evidence.paths))
+            set_ids: dict[int, int] = {}
+            rows = []
+            for name, record in evidence.tests.items():
+                ids = []
+                for s in (record.symbols, record.paths, record.dirs):
+                    if id(s) not in set_ids:
+                        set_ids[id(s)] = len(set_ids)
+                        db.execute("INSERT INTO sets VALUES (?, ?)", (set_ids[id(s)], _pack(s)))
+                    ids.append(set_ids[id(s)])
+                rows.append((name, *ids, record.flags))
+            db.executemany("INSERT INTO tests VALUES (?, ?, ?, ?, ?)", rows)
+            db.executemany(
+                "INSERT INTO import_by VALUES (?, ?)",
+                [(s, m) for s, modules in evidence.import_by.items() for m in sorted(modules)],
+            )
+        db.close()
+        os.replace(tmp, target)
+    finally:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+    evidence.location = target
+    return target
+
+
+def _meta(db: sqlite3.Connection) -> dict:
+    return {k: json.loads(v) for k, v in db.execute("SELECT key, value FROM meta")}
+
+
+def load_store(path: Path) -> Evidence:
+    try:
+        db = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
+    except sqlite3.Error as exc:
+        raise EvidenceError(f"cannot open evidence recording {path}: {exc}") from exc
+    try:
+        meta = _meta(db)
+        if meta.get("format") != STORE_FORMAT:
+            raise EvidenceError(
+                f"evidence recording {path} has format {meta.get('format')}, this diffcone "
+                f"reads {STORE_FORMAT}; collect it again"
+            )
+        symbols = [n for _, n in db.execute("SELECT id, name FROM symbols ORDER BY id")]
+        paths = [p for _, p in db.execute("SELECT id, path FROM paths ORDER BY id")]
+        sets = {i: _unpack(blob) for i, blob in db.execute("SELECT id, data FROM sets")}
+        tests = {
+            name: TestRecord(sets[s], sets[p], sets[d], flags)
+            for name, s, p, d, flags in db.execute(
+                "SELECT target, symbols, paths, dirs, flags FROM tests"
+            )
+        }
+        import_by: dict[str, set[str]] = defaultdict(set)
+        for symbol, module in db.execute("SELECT symbol, module FROM import_by"):
+            import_by[symbol].add(module)
+        evidence = Evidence(
+            commit=meta["commit"],
+            source_roots=meta["source_roots"],
+            environment=meta["environment"],
+            environment_hash=meta["environment_hash"],
+            command=meta["command"],
+            created=meta["created"],
+            symbols=symbols,
+            paths=paths,
+            tests=tests,
+            import_phase=frozenset(meta["import_phase"]),
+            hook_phase=frozenset(meta["hook_phase"]),
+            import_by={s: frozenset(m) for s, m in import_by.items()},
+            import_paths={p: frozenset(m) for p, m in meta["import_paths"].items()},
+            import_dirs={p: frozenset(m) for p, m in meta["import_dirs"].items()},
+            import_subprocess=meta["import_subprocess"],
+            reverse_checked=meta["reverse_checked"],
+            advanced_from=meta.get("advanced_from"),
+            full_commit=meta.get("full_commit") or meta["commit"],
+            collected=frozenset(meta["collected"]) if meta.get("collected") is not None else None,
+            location=path,
+        )
+    except (sqlite3.Error, KeyError, TypeError, ValueError, AttributeError, zlib.error) as exc:
+        raise EvidenceError(f"cannot read evidence recording {path}: {exc}") from exc
+    finally:
+        db.close()
+    return evidence
+
+
+@dataclass(frozen=True)
+class StoreInfo:
+    path: Path
+    commit: str
+    environment_hash: str
+    source_roots: tuple[str, ...]
+    created: float
+    tests: int
+    python: str
+    advanced_from: str | None = None
+    full_commit: str | None = None
+
+
+def find_store(repo: Path, spec: str, source_roots: list[str], reference: str) -> Path:
+    """The store ``spec`` names: a path, or ``auto`` for the store (with these
+    source roots) whose commit is the nearest ancestor of ``reference``, the
+    commit being planned towards; the newest one on a tie. Evidence from any
+    ancestor is sound (changes are planned from its commit), and a nearer one
+    has fewer changes to plan."""
+    if spec != "auto":
+        path = Path(spec)
+        if not path.exists():
+            raise EvidenceError(f"no evidence recording at {spec}")
+        return path
+    best: tuple[int, float, Path] | None = None
+    missing: list[str] = []
+    for store in list_stores(repo):
+        if sorted(store.source_roots) != sorted(source_roots):
+            continue
+        if not has_commit(repo, store.commit):
+            missing.append(store.commit)
+            continue
+        if subprocess.run(
+            ["git", "merge-base", "--is-ancestor", store.commit, reference],
+            cwd=repo,
+            capture_output=True,
+        ).returncode:
+            continue
+        count = subprocess.run(
+            ["git", "rev-list", "--count", f"{store.commit}..{reference}"],
+            cwd=repo,
+            capture_output=True,
+            text=True,
+        )
+        distance = int(count.stdout.strip() or 0)
+        key = (distance, -store.created, store.path)
+        if best is None or key < best:
+            best = key
+    if best is None:
+        hints = []
+        if missing:
+            hints.append(
+                f"the recording(s) at {', '.join(c[:12] for c in missing)} are for commits this "
+                f"checkout does not have; fetch them (git fetch --depth=1 origin {missing[0]})"
+            )
+        shallow = subprocess.run(
+            ["git", "rev-parse", "--is-shallow-repository"],
+            cwd=repo,
+            capture_output=True,
+            text=True,
+        )
+        if shallow.stdout.strip() == "true":
+            hints.append(
+                "this clone is shallow, so whether a recording's commit is an ancestor cannot "
+                "be told: fetch the history, or pass the recording's path to --evidence"
+            )
+        raise EvidenceError(
+            f"no evidence recording with source roots {source_roots} at an ancestor of "
+            f"{reference[:12]}; record one with `diffcone collect`"
+            + "".join(f"; {h}" for h in hints)
+        )
+    return best[2]
+
+
+def has_commit(repo: Path, commit: str) -> bool:
+    """Whether the repository holds ``commit``'s object."""
+    return (
+        subprocess.run(
+            ["git", "cat-file", "-e", f"{commit}^{{commit}}"], cwd=repo, capture_output=True
+        ).returncode
+        == 0
+    )
+
+
+def list_stores(repo: Path) -> list[StoreInfo]:
+    """Every readable store of the repository, newest first."""
+    found = []
+    for path in sorted((repo / EVIDENCE_DIR).glob("*.sqlite")):
+        try:
+            db = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
+            try:
+                meta = _meta(db)
+                (count,) = db.execute("SELECT COUNT(*) FROM tests").fetchone()
+            finally:
+                db.close()
+        except (sqlite3.Error, ValueError):
+            continue
+        if meta.get("format") != STORE_FORMAT:
+            continue
+        try:
+            info = StoreInfo(
+                path,
+                meta["commit"],
+                meta["environment_hash"],
+                tuple(meta["source_roots"]),
+                meta["created"],
+                count,
+                meta["environment"]["python"].split()[0],
+                meta.get("advanced_from"),
+                meta.get("full_commit") or meta["commit"],
+            )
+        except (KeyError, TypeError, AttributeError):
+            continue  # a malformed store is skipped, not fatal to every plan
+        found.append(info)
+    return sorted(found, key=lambda s: -s.created)