cg-code-graph 0.10.1__py3-none-any.whl

codegraph/plugins/swift/exact.py

@@ -0,0 +1,415 @@
+"""Swift exact layer: compiler-resolved call edges from the Swift index store.
+
+The index store is what `swift build --enable-index-store` (SwiftPM) or Xcode (DerivedData `Index.noindex/DataStore`)
+writes; it is read through the toolchain's libIndexStore (indexstore.py). Index-store definitions are matched to the
+syntax layer's declarations by file, line and name, so node ids stay those of the heuristic layer; the heuristic
+CALLS / INSTANTIATES edges of the covered files are replaced by the compiler's call occurrences (the caller comes from
+the `calledBy` / `containedBy` relation).
+
+Where the store comes from, in order:
+  CODEGRAPH_SWIFT_INDEX_STORE=/path/to/store    an existing store (CI, Xcode DerivedData, a previous build)
+  CODEGRAPH_SWIFT_INDEX=1                       run `swift build --enable-index-store` for a SwiftPM package (the build
+                                                runs the package manifest and plugins, hence opt-in), with the build
+                                                directory under the codegraph cache and a source fingerprint so an
+                                                unchanged package is not rebuilt
+Without one of those (or without a toolchain / libIndexStore) the heuristic layer stays and coverage says why.
+"""
+from __future__ import annotations
+
+import glob
+import json
+import os
+import re
+import shutil
+import subprocess
+import time
+from collections import defaultdict
+from pathlib import Path
+
+from ...core.model import EXACT, HEURISTIC
+from ...core import cache, fsutil
+from ..native import runner
+from . import indexstore as ix
+
+# index-store names of accessor definitions (`getter:label`, `didSet:items`): owned by their property
+ACCESSORS = ("getter:", "setter:", "_modify:", "modify:", "read:", "_read:", "willSet:", "didSet:")
+ACCESSOR_ATTR = {"getter": "get", "setter": "set", "willSet": "willSet", "didSet": "didSet", "modify": "modify",
+                 "_modify": "modify"}
+
+CALL_KINDS = ("CALLS", "INSTANTIATES")
+
+
+def find_swift() -> str | None:
+    env = os.environ.get("CODEGRAPH_SWIFT")
+    if env:
+        return env if (Path(env).exists() or shutil.which(env)) else None
+    w = shutil.which("swift")
+    if w:
+        return w
+    for pat in (str(Path.home() / "tools" / "swift-*" / "usr" / "bin" / "swift"), "/usr/share/swift/usr/bin/swift",
+                "/opt/swift/usr/bin/swift"):
+        hits = sorted(glob.glob(pat))
+        if hits:
+            return hits[-1]
+    return None
+
+
+def _store_dirs(build: Path) -> list[Path]:
+    return [Path(p) for p in sorted(glob.glob(str(build / "*" / "debug" / "index" / "store")))
+            + sorted(glob.glob(str(build / "debug" / "index" / "store")))]
+
+
+def find_store(project, files: list[str]) -> tuple[Path | None, dict]:
+    """(index store directory or None, info); info["status"] explains a missing store."""
+    pre = os.environ.get("CODEGRAPH_SWIFT_INDEX_STORE")
+    swift = find_swift()
+    lib = ix.find_lib(swift)
+    if pre:
+        if not Path(pre).is_dir():
+            return None, {"status": f"CODEGRAPH_SWIFT_INDEX_STORE={pre} is not a directory"}
+        if not lib:
+            return None, {"status": "libIndexStore not found (a Swift toolchain or CODEGRAPH_LIBINDEXSTORE is needed "
+                                    "to read the index store)"}
+        return Path(pre), {"source": "CODEGRAPH_SWIFT_INDEX_STORE", "path": pre, "lib": lib}
+    root = Path(project.root)
+    if not (root / "Package.swift").is_file():
+        return None, {"status": "no Package.swift at the project root (Xcode projects: set CODEGRAPH_SWIFT_INDEX_STORE "
+                                "to DerivedData/<app>/Index.noindex/DataStore)"}
+    if not swift:
+        return None, {"status": "no Swift toolchain (swift not on PATH; CODEGRAPH_SWIFT)"}
+    if not lib:
+        return None, {"status": f"libIndexStore not found next to {swift} (CODEGRAPH_LIBINDEXSTORE)"}
+    if os.environ.get("CODEGRAPH_SWIFT_INDEX") != "1":
+        return None, {"status": "Swift toolchain found but the package was not built: `swift build` runs the package "
+                                "manifest and plugins; set CODEGRAPH_SWIFT_INDEX=1, or CODEGRAPH_SWIFT_INDEX_STORE to an "
+                                "existing store (Xcode DerivedData)",
+                      "toolchain": swift}
+    return _build(root, files, swift, lib)
+
+
+def _build(root: Path, files: list[str], swift: str, lib: str) -> tuple[Path | None, dict]:
+    """`swift build --enable-index-store` into a per-project build directory under the cache; skipped when the sources
+    and manifests are unchanged since the last successful build."""
+    srcs = list(files) + [f for f in ("Package.swift", "Package.resolved") if (root / f).exists()]
+    srcs += [p.name for p in root.glob("Package@swift-*.swift")]
+    key = runner.fingerprint(root, srcs, f"swift-index|{runner.tool_version(swift, ('--version',))}")
+    build = cache.subdir("swift-build") / cache.swift_build_key(root)
+    stamp = build / "codegraph-stamp.json"
+    info = {"source": "swift build", "toolchain": swift, "lib": lib, "build_path": str(build)}
+    timeout = int(os.environ.get("CODEGRAPH_INDEXER_TIMEOUT", "3600"))
+    use_cache = os.environ.get("CODEGRAPH_NO_CACHE") != "1"
+    with runner.key_lock("swift", build.name, timeout) as waited:     # one build per build directory at a time
+        if waited:
+            info["lock_wait_seconds"] = waited
+        try:
+            done = json.loads(stamp.read_text()) if stamp.exists() else {}
+        except (OSError, ValueError):
+            done = {}
+        stores = _store_dirs(build)
+        if use_cache and done.get("key") == key and stores:
+            info["cache"] = "hit"
+            return stores[0], info
+        info["cache"] = "miss"
+        build.mkdir(parents=True, exist_ok=True)
+        cache.note_project(root)
+        cmd = [swift, "build", "--enable-index-store", "--build-path", str(build)]
+        info["command"] = " ".join(cmd[1:])
+        t0 = time.time()
+        try:
+            r = subprocess.run(cmd, cwd=root, capture_output=True, text=True, timeout=timeout)
+        except subprocess.TimeoutExpired:
+            info["error"] = f"timeout after {timeout}s"
+            info["status"] = f"swift build failed ({info['error']})"
+            return None, info
+        except OSError as e:
+            info["error"] = str(e)
+            info["status"] = f"swift build failed ({e})"
+            return None, info
+        info["seconds"] = round(time.time() - t0, 2)
+        out = (r.stdout or "") + "\n" + (r.stderr or "")
+        info["stderr_tail"] = [x for x in out.strip().splitlines()[-8:]]
+        stores = _store_dirs(build)
+        if r.returncode != 0:
+            errs = [x.strip() for x in out.splitlines() if re.search(r"\berror:", x)]
+            info["error"] = f"exit {r.returncode}"
+            info["notes"] = list(dict.fromkeys(errs))[:6]
+            first = re.sub(r"^/\S*/", "", errs[0].replace(str(root) + os.sep, ""))[:160] if errs else ""
+            if not stores:
+                info["status"] = "swift build failed (" + info["error"] + (f": {first}" if first else "") + ")"
+                return None, info
+            # a partial build still indexed the modules that compiled
+            info["partial"] = True
+            info["build_error"] = first
+        else:
+            stamp.write_text(json.dumps({"key": key, "cache_version": fsutil.CACHE_VERSION}))
+        return (stores[0] if stores else None), info
+
+
+class ExactLayer:
+    def __init__(self, plugin):
+        self.p = plugin
+        self.b = plugin.b
+
+    def _all_decls(self):
+        return list(self.p.decls.values())
+
+    def apply(self, store: Path, lib: str, root: Path, files: list[str], st: dict) -> bool:
+        occ_by_path = ix.load(store, None, lib)
+        rels = self._map_paths(occ_by_path, root, files)
+        st["index_files"] = len(rels)
+        if not rels:
+            st["index_units_outside_project"] = len(occ_by_path)
+            return False
+        by_line = defaultdict(list)
+        for d in self._all_decls():
+            by_line[(d.file, d.line)].append(d)
+        usr_node: dict[str, str] = {}
+        ctor_type: dict[str, str] = {}
+        matched = unmatched = 0
+        accessor_of: dict[str, str] = {}
+        accessor_kind: dict[str, str] = {}   # accessor usr -> "getter" | "setter" | "didSet" | ...
+        prop_def: dict[str, str] = {}
+        prop_how: dict[str, str] = {}        # property usr -> "computed" | "observed" | "lazy" (property nodes)
+        parent_of: dict[str, str] = {}       # definition usr -> enclosing type / extension usr (childOf)
+        ext_of: dict[str, str] = {}          # extension usr -> extended type usr
+        for rel, occs in rels.items():
+            for o in occs:
+                if not o.roles & ix.DEFINITION:
+                    for rr, ru, _rn, _rk in o.rels:
+                        if rr & ix.REL_EXTENDEDBY and o.kind in ix.TYPES:      # `extension DispatchQueue { }`
+                            ext_of[ru] = o.usr
+                            if o.usr not in usr_node:
+                                nid = self._decl(rel, o.line, o.name, ("class",), by_line) or \
+                                    (f"class:{o.name}" if f"class:{o.name}" in self.b.nodes else None)
+                                if nid:
+                                    usr_node[o.usr] = nid
+                    continue
+                for rr, ru, _rn, _rk in o.rels:
+                    if rr & ix.REL_CHILDOF:
+                        parent_of.setdefault(o.usr, ru)
+                if o.kind in ("instancemethod", "function", "staticmethod", "classmethod") and \
+                        o.name.startswith(ACCESSORS):
+                    for rr, ru, _rn, _rk in o.rels:
+                        if rr & ix.REL_ACCESSOROF:
+                            accessor_of[o.usr] = ru
+                            accessor_kind[o.usr] = o.name.split(":", 1)[0]
+                    continue
+                if o.kind in ("instanceproperty", "staticproperty", "classproperty", "variable"):
+                    if o.name == "body":
+                        prop_def[o.usr] = self._decl(rel, o.line, "body", ("method",), by_line) or ""
+                    else:
+                        d = self._prop_decl(rel, o.line, o.name, by_line)
+                        if d is not None:             # a computed / observed / lazy property node (#72)
+                            prop_def[o.usr] = d.id
+                            prop_how[o.usr] = next(m for m in ("computed", "observed", "lazy") if m in d.modifiers)
+                    continue
+                if o.kind not in ix.CALLABLE and o.kind not in ix.TYPES:
+                    continue
+                base = "init" if o.kind == "constructor" else o.name.split("(")[0]
+                kinds = ("class",) if o.kind in ix.TYPES else ("function", "method")
+                nid = self._decl(rel, o.line, base, kinds, by_line)
+                if nid is None and o.kind != "constructor":
+                    nid = self._decl_by_name(rel, base, kinds, o)
+                if o.kind == "constructor":
+                    parent = next((ru for rr, ru, _rn, rk in o.rels if rr & ix.REL_CHILDOF), None)
+                    if parent:
+                        ctor_type[o.usr] = parent
+                if nid is None:
+                    if o.kind != "constructor":
+                        unmatched += 1
+                    continue
+                usr_node[o.usr] = nid
+                matched += 1
+        for acc, prop in accessor_of.items():         # SwiftUI `body` getter -> method:<View>.body
+            if prop_def.get(prop):
+                usr_node[acc] = prop_def[prop]
+        st["index_defs_matched"] = matched
+        st["index_defs_unmatched"] = unmatched
+        def owner(usr: str, depth: int = 0) -> str | None:
+            """Node of a caller symbol: itself, the `body` property of an accessor, else its enclosing type
+            (accessors -> property -> type; extension -> extended type)."""
+            if not usr or depth > 6:
+                return None
+            if usr in usr_node:
+                return usr_node[usr]
+            prop = accessor_of.get(usr)
+            if prop:
+                if prop_def.get(prop):
+                    return prop_def[prop]
+                return owner(prop, depth + 1)
+            if usr in ext_of:
+                return owner(ext_of[usr], depth + 1)
+            return owner(parent_of.get(usr, ""), depth + 1)
+
+        covered = set(rels)
+        lambdas = defaultdict(list)     # Vapor route handlers / BGTask closures own the calls inside them
+        for nid, n in self.b.nodes.items():
+            if n.lang == "swift" and n.kind == "function" and n.attrs.get("lambda") and n.file in covered and n.line:
+                lambdas[n.file].append((n.line, n.end_line or n.line, nid))
+        seen_lines = {(rel, o.line) for rel, occs in rels.items() for o in occs}
+        heur, kept = self._remove_heuristic(covered, seen_lines)
+        st["heuristic_kept_not_compiled"] = kept
+        exact = set()
+        refs = ext = 0
+        for rel, occs in rels.items():
+            fid = f"file:swift:{rel}"
+            for o in occs:
+                if o.roles & ix.DEFINITION or not (o.roles & ix.CALL or o.kind == "constructor"):
+                    continue
+                if o.kind not in ix.CALLABLE:
+                    continue
+                prop = accessor_of.get(o.usr) if o.name.startswith(ACCESSORS) else None
+                if o.name.startswith(ACCESSORS) and not (prop in prop_how and self._runs(accessor_kind.get(o.usr, ""),
+                                                                                         prop_how[prop])):
+                    continue
+                if prop is not None:
+                    # a read (getter) or write (setter / modify) of a property node: a call of it (#72)
+                    targets = [(prop_def[prop], "CALLS")]
+                elif o.kind == "constructor":
+                    tt = ctor_type.get(o.usr, "")
+                    # an initializer declared in an extension: its parent is the extension, whose node is the type's
+                    tnode = usr_node.get(tt) or usr_node.get(ext_of.get(tt, ""))
+                    if tnode is None:
+                        ext += 1
+                        continue
+                    targets = [(tnode, "INSTANTIATES")]
+                    if o.usr in usr_node:
+                        targets.append((usr_node[o.usr], "CALLS"))
+                else:
+                    t = usr_node.get(o.usr)
+                    if t is None:
+                        ext += 1
+                        continue
+                    targets = [(t, "CALLS")]
+                src = None
+                acc = {}
+                for rr, ru, _rn, _rk in o.rels:
+                    if rr & (ix.REL_CALLEDBY | ix.REL_CONTAINEDBY):
+                        src = owner(ru)
+                        if src is not None:
+                            acc = self._accessor_attr(src, accessor_kind.get(ru))
+                            break
+                if src is None:
+                    src = self._owner_type(rel, o.line) or fid
+                if src.startswith("class:"):
+                    # the initializer of a `lazy var` belongs to the type in the store; here to the property node
+                    pd = next((d for d in self.p.props_in.get(rel, ()) if d.line <= o.line <= d.end
+                               and f"class:{d.cls}" == src), None)
+                    src = pd.id if pd is not None else src
+                lam = min((x for x in lambdas.get(rel, ()) if x[0] <= o.line <= x[1]),
+                          key=lambda x: x[1] - x[0], default=None)
+                if lam is not None:
+                    src = lam[2]
+                for dst, kind in targets:
+                    if (src == dst and kind == "CALLS") or src not in self.b.nodes or dst not in self.b.nodes:
+                        continue
+                    if prop is not None:
+                        acc = {**acc, "property": "read" if accessor_kind.get(o.usr) == "getter" else "write"}
+                    br = self.p.branch_at.get((rel, o.line, self.b.nodes[dst].name), {}) \
+                        if kind == "INSTANTIATES" else {}
+                    self.b.add_edge(src, dst, kind, rel, o.line, EXACT, source="indexstore",
+                                    **({"dynamic": True} if o.roles & ix.DYNAMIC else {}), **acc, **br)
+                    exact.add((src, dst, kind))
+                    refs += 1
+        st["index_references"] = refs
+        st["index_refs_external"] = ext
+        agree = len(heur & exact)
+        st["exact_vs_heuristic"] = {
+            "heuristic_edges": len(heur), "exact_edges": len(exact), "agree": agree,
+            "precision": round(agree / len(heur), 3) if heur else None,
+            "recall": round(agree / len(exact), 3) if exact else None,
+            # candidate edges (receiver type unknown, one per same-name method, #83) are compared on their own
+            "candidate_edges": len(self.candidates), "candidate_agree": len(self.candidates & exact)}
+        return True
+
+    def _map_paths(self, occ_by_path: dict, root: Path, files: list[str]) -> dict:
+        """Index-store source paths -> project-relative paths: under the project root, else by the longest
+        project path suffix (a store built in another checkout or on another machine)."""
+        rootr = str(Path(root).resolve()) + os.sep
+        fset = set(files)
+        by_name = defaultdict(list)
+        for f in files:
+            by_name[f.rsplit("/", 1)[-1]].append(f)
+        out = {}
+        for p, occs in occ_by_path.items():
+            rel = None
+            if p.startswith(rootr) and p[len(rootr):] in fset:
+                rel = p[len(rootr):]
+            else:
+                cands = [f for f in by_name.get(p.rsplit("/", 1)[-1], []) if p.endswith("/" + f)]
+                rel = max(cands, key=len) if cands else None
+            if rel is not None:
+                out[rel] = occs
+        return out
+
+    @staticmethod
+    def _runs(accessor: str, how: str) -> bool:
+        """Does a use of this accessor run code of a property node? A read of a computed or lazy property, a write of
+        a computed or observed one (the getter of a stored property with observers is the plain storage)."""
+        if accessor in ("getter", "read", "_read"):
+            return how in ("computed", "lazy")
+        if accessor in ("setter", "modify", "_modify"):
+            return how in ("computed", "observed")
+        return False
+
+    def _accessor_attr(self, src: str, accessor: str | None) -> dict:
+        """{"accessor": "didSet"} for a call inside an explicit accessor of a property node (as the heuristic pass)."""
+        name = ACCESSOR_ATTR.get(accessor or "")
+        n = self.b.nodes.get(src)
+        return {"accessor": name} if name and n is not None and name in (n.attrs.get("accessors") or ()) else {}
+
+    def _prop_decl(self, rel, line, name, by_line):
+        """The property node of a property definition: by its line, else (attributes on the lines above the name)
+        the one of that name whose range holds the line."""
+        for d in by_line.get((rel, line), ()):
+            if d.name == name and "property" in d.modifiers:
+                return d
+        for d in self.p.props_in.get(rel, ()):
+            if d.name == name and d.line <= line <= d.end:
+                return d
+        return None
+
+    def _decl(self, rel, line, name, kinds, by_line):
+        for d in by_line.get((rel, line), ()):
+            if d.name == name and d.kind in kinds:
+                return d.id
+        return None
+
+    def _decl_by_name(self, rel, name, kinds, o):
+        """An overload (one node per name) or a declaration whose name line differs from the node's line."""
+        parent = next((rn for rr, _ru, rn, _rk in o.rels if rr & ix.REL_CHILDOF), None)
+        for d in self._all_decls():
+            if d.file == rel and d.name == name and d.kind in kinds and "property" not in d.modifiers and \
+                    (parent is None or (d.cls or "").split(".")[-1] == parent or d.kind == "class"):
+                if d.line <= o.line <= d.end or d.kind != "class":
+                    return d.id
+        return None
+
+    def _owner_type(self, rel, line):
+        best = None
+        for d in self._all_decls():
+            if d.file == rel and d.kind == "class" and d.line <= line <= d.end:
+                if best is None or d.end - d.line < best.end - best.line:
+                    best = d
+        return best.id if best else None
+
+    def _remove_heuristic(self, covered: set, seen_lines: set) -> tuple[set, int]:
+        """Drop the heuristic call edges of the covered files; returns their (src, dst, kind) set. An edge on a line
+        without any index occurrence is code the compiler did not see (an inactive `#if` branch on this platform):
+        it is kept, marked `via: not-compiled`, and left out of the comparison. Candidate edges (#83) go to
+        self.candidates, compared on their own."""
+        out, cand, kept = set(), set(), 0
+        for key, e in list(self.b.edges.items()):
+            if e.confidence != HEURISTIC or e.file not in covered or e.kind not in CALL_KINDS:
+                continue
+            n = self.b.nodes.get(e.src)
+            if n is None or n.lang != "swift":
+                continue
+            if (e.file, e.line) not in seen_lines:
+                e.attrs["via"] = "not-compiled"
+                kept += 1
+                continue
+            (cand if e.attrs.get("binding") == "candidate" else out).add((e.src, e.dst, e.kind))
+            del self.b.edges[key]
+        self.candidates = cand
+        return out, kept

codegraph/plugins/swift/indexstore.py

@@ -0,0 +1,209 @@
+"""Read a Swift compiler index store (`swift build --enable-index-store`, Xcode DerivedData `Index.noindex/DataStore`)
+through the toolchain's libIndexStore C API (ctypes, the function-pointer `_apply_f` variants).
+
+load(store, roots) -> {source path: [Occurrence]} for the units whose main file lies under one of `roots`.
+"""
+from __future__ import annotations
+
+import ctypes
+import os
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+
+DECLARATION, DEFINITION, REFERENCE, READ, WRITE, CALL, DYNAMIC, ADDRESSOF, IMPLICIT = (1 << i for i in range(9))
+REL_CHILDOF, REL_BASEOF, REL_OVERRIDEOF, REL_RECEIVEDBY, REL_CALLEDBY, REL_EXTENDEDBY, REL_ACCESSOROF, \
+    REL_CONTAINEDBY = (1 << i for i in range(9, 17))
+
+KIND = {1: "module", 5: "enum", 6: "struct", 7: "class", 8: "protocol", 9: "extension", 11: "typealias",
+        12: "function", 13: "variable", 14: "field", 15: "enumconstant", 16: "instancemethod", 17: "classmethod",
+        18: "staticmethod", 19: "instanceproperty", 20: "classproperty", 21: "staticproperty", 22: "constructor",
+        23: "destructor", 25: "parameter"}
+CALLABLE = {"function", "instancemethod", "classmethod", "staticmethod", "constructor"}
+TYPES = {"enum", "struct", "class", "protocol"}
+
+
+class StrRef(ctypes.Structure):
+    _fields_ = [("data", ctypes.c_char_p), ("length", ctypes.c_size_t)]
+
+
+def _s(r: StrRef) -> str:
+    if not r.data or not r.length:
+        return ""
+    return ctypes.string_at(r.data, r.length).decode("utf-8", "replace")
+
+
+@dataclass
+class Occurrence:
+    line: int
+    col: int
+    roles: int
+    usr: str
+    name: str
+    kind: str
+    subkind: int
+    rels: list = field(default_factory=list)     # (roles, usr, name, kind)
+
+
+def find_lib(swift: str | None = None) -> str | None:
+    """libIndexStore.so: CODEGRAPH_LIBINDEXSTORE, else next to the `swift` toolchain (usr/lib)."""
+    env = os.environ.get("CODEGRAPH_LIBINDEXSTORE")
+    if env:
+        return env if Path(env).exists() else None
+    sw = swift or shutil.which("swift")
+    if sw:
+        base = Path(sw).resolve().parent.parent
+        for name in ("libIndexStore.so", "libIndexStore.dylib"):
+            for d in (base / "lib", base / "lib" / "swift" / "linux"):
+                if (d / name).exists():
+                    return str(d / name)
+    # macOS: /usr/bin/swift is a shim; the library lives in the selected Xcode's default toolchain
+    for dev in (os.environ.get("DEVELOPER_DIR"), "/Applications/Xcode.app/Contents/Developer"):
+        if dev:
+            p = Path(dev) / "Toolchains" / "XcodeDefault.xctoolchain" / "usr" / "lib" / "libIndexStore.dylib"
+            if p.exists():
+                return str(p)
+    return None
+
+
+_LIB = {}
+
+
+def _lib(path: str):
+    if path in _LIB:
+        return _LIB[path]
+    L = ctypes.CDLL(path)
+    vp, u64, cb = ctypes.c_void_p, ctypes.c_uint64, ctypes.CFUNCTYPE
+    L.indexstore_store_create.restype = vp
+    L.indexstore_store_create.argtypes = [ctypes.c_char_p, ctypes.POINTER(vp)]
+    L.indexstore_error_get_description.restype = ctypes.c_char_p
+    L.indexstore_error_get_description.argtypes = [vp]
+    L.indexstore_store_dispose.argtypes = [vp]
+    L.UNIT_CB = cb(ctypes.c_bool, vp, StrRef)
+    L.indexstore_store_units_apply_f.argtypes = [vp, ctypes.c_uint, vp, L.UNIT_CB]
+    L.indexstore_unit_reader_create.restype = vp
+    L.indexstore_unit_reader_create.argtypes = [vp, ctypes.c_char_p, ctypes.POINTER(vp)]
+    L.indexstore_unit_reader_dispose.argtypes = [vp]
+    for f in ("main_file", "module_name", "working_dir"):
+        fn = getattr(L, f"indexstore_unit_reader_get_{f}")
+        fn.restype, fn.argtypes = StrRef, [vp]
+    L.indexstore_unit_reader_is_system_unit.restype = ctypes.c_bool
+    L.indexstore_unit_reader_is_system_unit.argtypes = [vp]
+    L.DEP_CB = cb(ctypes.c_bool, vp, vp)
+    L.indexstore_unit_reader_dependencies_apply_f.argtypes = [vp, vp, L.DEP_CB]
+    L.indexstore_unit_dependency_get_kind.restype = ctypes.c_int
+    L.indexstore_unit_dependency_get_kind.argtypes = [vp]
+    for f in ("filepath", "name"):
+        fn = getattr(L, f"indexstore_unit_dependency_get_{f}")
+        fn.restype, fn.argtypes = StrRef, [vp]
+    L.indexstore_record_reader_create.restype = vp
+    L.indexstore_record_reader_create.argtypes = [vp, ctypes.c_char_p, ctypes.POINTER(vp)]
+    L.indexstore_record_reader_dispose.argtypes = [vp]
+    L.OCC_CB = cb(ctypes.c_bool, vp, vp)
+    L.indexstore_record_reader_occurrences_apply_f.argtypes = [vp, vp, L.OCC_CB]
+    L.indexstore_occurrence_get_symbol.restype = vp
+    L.indexstore_occurrence_get_symbol.argtypes = [vp]
+    L.indexstore_occurrence_get_roles.restype = u64
+    L.indexstore_occurrence_get_roles.argtypes = [vp]
+    L.indexstore_occurrence_get_line_col.argtypes = [vp, ctypes.POINTER(ctypes.c_uint), ctypes.POINTER(ctypes.c_uint)]
+    L.REL_CB = cb(ctypes.c_bool, vp, vp)
+    L.indexstore_occurrence_relations_apply_f.argtypes = [vp, vp, L.REL_CB]
+    L.indexstore_symbol_relation_get_roles.restype = u64
+    L.indexstore_symbol_relation_get_roles.argtypes = [vp]
+    L.indexstore_symbol_relation_get_symbol.restype = vp
+    L.indexstore_symbol_relation_get_symbol.argtypes = [vp]
+    for f in ("name", "usr"):
+        fn = getattr(L, f"indexstore_symbol_get_{f}")
+        fn.restype, fn.argtypes = StrRef, [vp]
+    for f in ("kind", "subkind", "language"):
+        fn = getattr(L, f"indexstore_symbol_get_{f}")
+        fn.restype, fn.argtypes = ctypes.c_int, [vp]
+    _LIB[path] = L
+    return L
+
+
+class IndexStoreError(RuntimeError):
+    pass
+
+
+def load(store: str | Path, roots: list[str | Path] | None, lib_path: str) -> dict[str, list[Occurrence]]:
+    """Occurrences per absolute source path, for non-system units whose main file is under `roots`."""
+    L = _lib(lib_path)
+    err = ctypes.c_void_p()
+    st = L.indexstore_store_create(str(store).encode(), ctypes.byref(err))
+    if not st:
+        msg = L.indexstore_error_get_description(err) if err else b"?"
+        raise IndexStoreError(f"cannot open index store {store}: {msg.decode(errors='replace')}")
+    roots_s = [str(Path(r).resolve()) + os.sep for r in roots] if roots else None
+    units: list[str] = []
+
+    @L.UNIT_CB
+    def on_unit(_ctx, name):
+        units.append(_s(name))
+        return True
+
+    L.indexstore_store_units_apply_f(st, 0, None, on_unit)
+    records: dict[str, str] = {}      # source path -> record name (the newest unit wins)
+    for u in units:
+        ur = L.indexstore_unit_reader_create(st, u.encode(), ctypes.byref(err))
+        if not ur:
+            continue
+        try:
+            if L.indexstore_unit_reader_is_system_unit(ur):
+                continue
+            main = _s(L.indexstore_unit_reader_get_main_file(ur))
+            if not main or (roots_s is not None and not any(main.startswith(r) for r in roots_s)):
+                continue
+
+            @L.DEP_CB
+            def on_dep(_ctx, dep):
+                if L.indexstore_unit_dependency_get_kind(dep) == 2:          # record
+                    fp = _s(L.indexstore_unit_dependency_get_filepath(dep))
+                    if fp == main:
+                        records[fp] = _s(L.indexstore_unit_dependency_get_name(dep))
+                return True
+
+            L.indexstore_unit_reader_dependencies_apply_f(ur, None, on_dep)
+        finally:
+            L.indexstore_unit_reader_dispose(ur)
+    out: dict[str, list[Occurrence]] = {}
+    sym_cache: dict[int, tuple] = {}
+
+    def sym(p):
+        r = sym_cache.get(p)
+        if r is None:
+            r = (_s(L.indexstore_symbol_get_usr(p)), _s(L.indexstore_symbol_get_name(p)),
+                 KIND.get(L.indexstore_symbol_get_kind(p), "other"), L.indexstore_symbol_get_subkind(p))
+            sym_cache[p] = r
+        return r
+
+    for path, rec in records.items():
+        rr = L.indexstore_record_reader_create(st, rec.encode(), ctypes.byref(err))
+        if not rr:
+            continue
+        occs: list[Occurrence] = []
+        sym_cache.clear()
+        try:
+            @L.OCC_CB
+            def on_occ(_ctx, o):
+                line, col = ctypes.c_uint(), ctypes.c_uint()
+                L.indexstore_occurrence_get_line_col(o, ctypes.byref(line), ctypes.byref(col))
+                usr, name, kind, sub = sym(L.indexstore_occurrence_get_symbol(o))
+                oc = Occurrence(line.value, col.value, L.indexstore_occurrence_get_roles(o), usr, name, kind, sub)
+
+                @L.REL_CB
+                def on_rel(_c, rel):
+                    rs = sym(L.indexstore_symbol_relation_get_symbol(rel))
+                    oc.rels.append((L.indexstore_symbol_relation_get_roles(rel), rs[0], rs[1], rs[2]))
+                    return True
+
+                L.indexstore_occurrence_relations_apply_f(o, None, on_rel)
+                occs.append(oc)
+                return True
+
+            L.indexstore_record_reader_occurrences_apply_f(rr, None, on_occ)
+        finally:
+            L.indexstore_record_reader_dispose(rr)
+        out[path] = occs
+    L.indexstore_store_dispose(st)
+    return out