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

codegraph/plugins/native/gates.py

@@ -0,0 +1,286 @@
+"""Compile-time gates for systems code: Rust `#[cfg(...)]` predicates and C/C++ preprocessor conditions.
+
+Two uses:
+  1. Always: every item / statement under a condition gets GATED_BY edges to `feature:<pkg>/<name>`, `cfg:<pred>`
+     (Rust) or `define:<MACRO>` (C/C++) nodes, with the attribute / directive line as evidence.
+  2. With a gate scenario (`index --gates FILE`, first scenario), conditions are evaluated three-valued
+     (true / false / unknown) and references made inside a region whose condition is *false* get edge.gate set,
+     exactly like the PHP feature-flag gating, so `reaches` lists them under GATED.
+
+Scenario keys understood here (others are ignored, so one gates file can serve several languages):
+  features_on / features_off   Cargo features ("fs" for any package, or "kv-core/fs")
+  cargo_features               "default" | "none" | [list]: exactly these features (per package, plus what they
+                               enable) are on; every other feature is off
+  cfg_true / cfg_false         other cfg atoms: "unix", "windows", 'target_os="linux"', "test", "debug_assertions"
+  defines_on / defines_off     C/C++ macros ("NAME" or "NAME=VALUE"); defines_on = defined, defines_off = undefined
+"""
+from __future__ import annotations
+
+import re
+
+TRUE, FALSE, UNKNOWN = True, False, None
+
+
+# ---------------------------------------------------------------- Rust cfg predicates
+def parse_cfg(s: str):
+    """'all(unix, not(feature = "x"))' -> ('all', [('atom','unix',None), ('not', ('atom','feature','x'))])."""
+    toks = re.findall(r'"(?:[^"\\]|\\.)*"|[A-Za-z_][\w:]*|[(),=]', s)
+    pos = [0]
+
+    def peek():
+        return toks[pos[0]] if pos[0] < len(toks) else None
+
+    def take():
+        t = peek()
+        pos[0] += 1
+        return t
+
+    def expr():
+        t = take()
+        if t is None:
+            return ("atom", "?", None)
+        if t in ("all", "any", "not") and peek() == "(":
+            take()
+            args = []
+            while peek() not in (")", None):
+                args.append(expr())
+                if peek() == ",":
+                    take()
+            take()
+            if t == "not":
+                return ("not", args[0] if args else ("atom", "?", None))
+            return (t, args)
+        if peek() == "=":
+            take()
+            v = take() or '""'
+            return ("atom", t, v.strip('"'))
+        return ("atom", t, None)
+
+    try:
+        return expr()
+    except Exception:
+        return ("atom", s.strip(), None)
+
+
+def cfg_atoms(p) -> list[tuple[str, str | None]]:
+    if p[0] == "atom":
+        return [(p[1], p[2])]
+    if p[0] == "not":
+        return cfg_atoms(p[1])
+    return [a for x in p[1] for a in cfg_atoms(x)]
+
+
+def atom_text(key: str, val: str | None) -> str:
+    return key if val is None else f'{key}="{val}"'
+
+
+class Scenario:
+    """First gate scenario of the gates file, seen from native code."""
+
+    def __init__(self, sc: dict | None, packages: dict[str, dict] | None = None):
+        sc = sc or {}
+        self.name = sc.get("name")
+        self.raw = sc
+        self.features_on = set(sc.get("features_on") or [])
+        self.features_off = set(sc.get("features_off") or [])
+        self.cfg_true = set(sc.get("cfg_true") or [])
+        self.cfg_false = set(sc.get("cfg_false") or [])
+        self.defines = {}
+        for d in sc.get("defines_on") or []:
+            k, _, v = str(d).partition("=")
+            self.defines[k.strip()] = v.strip() or "1"
+        self.undefined = set(sc.get("defines_off") or [])
+        # cargo_features: compute the exact enabled set per package
+        self.exact: dict[str, set] | None = None
+        cf = sc.get("cargo_features")
+        if cf is not None and packages:
+            self.exact = {}
+            for pkg, feats in packages.items():
+                want = set(["default"] if cf == "default" else [] if cf == "none" else
+                           [f.split("/", 1)[1] if "/" in f and f.split("/", 1)[0] == pkg else f for f in cf if "/" not in f or f.startswith(pkg + "/")])
+                on, todo = set(), list(want)
+                while todo:
+                    f = todo.pop()
+                    if f in on:
+                        continue
+                    on.add(f)
+                    for g in feats.get(f, []):
+                        if "/" not in g and not g.startswith("dep:"):
+                            todo.append(g)
+                self.exact[pkg] = on
+
+    @property
+    def active(self) -> bool:
+        return bool(self.name)
+
+    # Rust
+    def feature(self, pkg: str, f: str):
+        if f"{pkg}/{f}" in self.features_on or f in self.features_on:
+            return TRUE
+        if f"{pkg}/{f}" in self.features_off or f in self.features_off:
+            return FALSE
+        if self.exact is not None and pkg in self.exact:
+            return f in self.exact[pkg]
+        return UNKNOWN
+
+    def eval_cfg(self, p, pkg: str):
+        k = p[0]
+        if k == "atom":
+            key, val = p[1], p[2]
+            if key == "feature" and val is not None:
+                return self.feature(pkg, val)
+            t = atom_text(key, val)
+            if t in self.cfg_true:
+                return TRUE
+            if t in self.cfg_false:
+                return FALSE
+            return UNKNOWN
+        if k == "not":
+            v = self.eval_cfg(p[1], pkg)
+            return None if v is None else (not v)
+        vals = [self.eval_cfg(x, pkg) for x in p[1]]
+        if k == "all":
+            if any(v is False for v in vals):
+                return FALSE
+            return TRUE if all(v is True for v in vals) else UNKNOWN
+        if any(v is True for v in vals):
+            return TRUE
+        return FALSE if vals and all(v is False for v in vals) else UNKNOWN
+
+    # C / C++
+    def eval_pp(self, expr: str):
+        return eval_pp(expr, self.defines, self.undefined)
+
+
+# ---------------------------------------------------------------- C preprocessor conditions
+_PP_TOK = re.compile(r"\s*(defined|\|\||&&|==|!=|<=|>=|<<|>>|[!()<>+\-*/%]|0[xX][0-9a-fA-F]+[uUlL]*|\d+[uUlL]*|[A-Za-z_]\w*|.)")
+
+
+def pp_macros(expr: str) -> list[str]:
+    """Macro names a condition depends on (identifiers, `defined X`), in order, without duplicates."""
+    out = []
+    for m in re.finditer(r"[A-Za-z_]\w*", expr):
+        n = m.group(0)
+        if n != "defined" and n not in out and not n.startswith("__has_"):
+            out.append(n)
+    return out
+
+
+def eval_pp(expr: str, defines: dict[str, str], undefined: set[str]):
+    """Three-valued evaluation of a #if expression. Unknown macros make the result unknown (None)
+    unless the other operand decides it (0 && x, 1 || x)."""
+    toks = [t for t in _PP_TOK.findall(expr) if t.strip()]
+    pos = [0]
+
+    def peek():
+        return toks[pos[0]] if pos[0] < len(toks) else None
+
+    def take():
+        t = peek()
+        pos[0] += 1
+        return t
+
+    def num(t):
+        try:
+            return int(t.rstrip("uUlL"), 0)
+        except ValueError:
+            return None
+
+    def primary():
+        t = take()
+        if t is None:
+            return None
+        if t == "(":
+            v = lor()
+            if peek() == ")":
+                take()
+            return v
+        if t == "!":
+            v = primary()
+            return None if v is None else int(not v)
+        if t == "-":
+            v = primary()
+            return None if v is None else -v
+        if t == "defined":
+            paren = peek() == "("
+            if paren:
+                take()
+            name = take()
+            if paren and peek() == ")":
+                take()
+            if name in defines:
+                return 1
+            if name in undefined:
+                return 0
+            return None
+        n = num(t)
+        if n is not None:
+            return n
+        if re.match(r"[A-Za-z_]", t):
+            if peek() == "(":  # function-like macro / __has_include(...): unknown
+                depth = 0
+                while peek() is not None:
+                    x = take()
+                    depth += {"(": 1, ")": -1}.get(x, 0)
+                    if depth == 0:
+                        break
+                return None
+            if t in defines:
+                return num(defines[t]) if num(defines[t]) is not None else None
+            if t in undefined:
+                return 0
+            return None
+        return None
+
+    def binop(sub, ops):
+        def f():
+            v = sub()
+            while peek() in ops:
+                op = take()
+                w = sub()
+                if v is None or w is None:
+                    v = None
+                    continue
+                v = {"==": int(v == w), "!=": int(v != w), "<": int(v < w), ">": int(v > w), "<=": int(v <= w),
+                     ">=": int(v >= w), "+": v + w, "-": v - w, "*": v * w, "/": (v // w if w else None),
+                     "%": (v % w if w else None), "<<": v << w if 0 <= w < 64 else None, ">>": v >> w if 0 <= w < 64 else None}[op]
+            return v
+        return f
+
+    mul = binop(primary, ("*", "/", "%"))
+    add = binop(mul, ("+", "-"))
+    shift = binop(add, ("<<", ">>"))
+    rel = binop(shift, ("<", ">", "<=", ">="))
+    eq = binop(rel, ("==", "!="))
+
+    def land():
+        v = eq()
+        while peek() == "&&":
+            take()
+            w = eq()
+            v = 0 if (v == 0 or w == 0) else (None if v is None or w is None else 1)
+        return v
+
+    def lor():
+        v = land()
+        while peek() == "||":
+            take()
+            w = land()
+            v = 1 if (v not in (None, 0) or w not in (None, 0)) else (None if v is None or w is None else 0)
+        return v
+
+    try:
+        v = lor()
+    except Exception:
+        return UNKNOWN
+    return UNKNOWN if v is None else bool(v)
+
+
+def range_lookup(ranges: list[tuple[int, int, object]]):
+    """ranges: (start_line, end_line, payload), 1-based inclusive. Returns f(line) -> list of payloads covering it
+    (outermost first)."""
+    ranges = sorted(ranges, key=lambda r: (r[0], -r[1]))
+
+    def f(line: int):
+        return [p for (a, b, p) in ranges if a <= line <= b]
+    return f

codegraph/plugins/native/runner.py

@@ -0,0 +1,183 @@
+"""Running external SCIP indexers (rust-analyzer, scip-clang) with an on-disk cache.
+
+The cache key covers the cache version, the indexer version, its arguments and (path, size, content hash) of every
+relevant source file, so re-indexing an unchanged project reuses the previous SCIP file and any content change (even
+one that keeps the size and mtime) re-runs the indexer. CODEGRAPH_NO_CACHE=1 disables the cache.
+Output never goes into the indexed project: files live under <cache root>/scip/ (core/cache.py: $CODEGRAPH_CACHE,
+else $XDG_CACHE_HOME/codegraph or ~/.cache/codegraph), named <name>-v<cache version>-<project key>-<key>.scip.
+Concurrent processes indexing the same project share one indexer run (a per-key lock) and never see each other's
+partial output (private temporary files, atomic os.replace).
+"""
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import os
+import re
+import secrets
+import shutil
+import subprocess
+import time
+from pathlib import Path
+
+try:
+    import fcntl
+except ImportError:      # Windows: no flock; runs stay safe through private temporary files, without the wait
+    fcntl = None
+
+from ...core import cache, fsutil
+
+
+def cache_dir() -> Path:
+    return cache.subdir("scip", create=True)
+
+
+def find_tool(env: str, names: list[str], extra_dirs: list[Path] = ()) -> str | None:
+    v = os.environ.get(env)
+    if v:
+        return v if (Path(v).exists() or shutil.which(v)) else None
+    for n in names:
+        p = shutil.which(n)
+        if p:
+            return p
+        for d in extra_dirs:
+            if (Path(d) / n).exists():
+                return str(Path(d) / n)
+    return None
+
+
+def tool_version(tool: str, args=("--version",)) -> str:
+    try:
+        r = subprocess.run([tool, *args], capture_output=True, text=True, timeout=60)
+        return (r.stdout or r.stderr).strip().splitlines()[0] if (r.stdout or r.stderr) else "?"
+    except Exception:
+        return "?"
+
+
+def fingerprint(root: Path, files: list[str], extra: str) -> str:
+    """Cache key: cache version + `extra` (indexer version, config) + root + (path, size, content hash) per file."""
+    h = hashlib.sha256(f"cg-cache-v{fsutil.CACHE_VERSION}\0{extra}".encode())
+    h.update(str(root).encode())
+    for f in sorted(files):
+        h.update(f"{f}\0{fsutil.content_key(root / f)}\n".encode())
+    return h.hexdigest()[:20]
+
+
+def _prune_legacy(name: str) -> None:
+    """Drop SCIP files written under an older cache version (`<name>-<20 hex>.scip`): their keys can never match again."""
+    for old in cache_dir().glob(f"{name}-*.scip"):
+        if re.fullmatch(rf"{re.escape(name)}-[0-9a-f]{{20}}\.scip", old.name):
+            old.unlink(missing_ok=True)
+
+
+@contextlib.contextmanager
+def key_lock(name: str, key: str, timeout: float):
+    """An exclusive per-key lock (`<name>-<key>.lock` in the cache dir), so concurrent processes indexing the same
+    project run the indexer once: the others wait, then find the cached result. Yields the seconds spent waiting, or
+    None when the lock could not be taken in `timeout` (or file locks are unavailable): the caller runs unlocked then."""
+    if fcntl is None:
+        yield None
+        return
+    path = cache_dir() / f"{name}-v{fsutil.CACHE_VERSION}-{key}.lock"
+    fd = os.open(path, os.O_RDWR | os.O_CREAT, 0o644)
+    t0, got = time.time(), False
+    try:
+        while True:
+            try:
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                got = True
+                break
+            except OSError:
+                if time.time() - t0 >= timeout:
+                    break
+                time.sleep(0.2)
+        yield round(time.time() - t0, 2) if got else None
+    finally:
+        if got:
+            fcntl.flock(fd, fcntl.LOCK_UN)
+        os.close(fd)
+
+
+def write_atomic(path: Path, text: str) -> None:
+    """Write a file other processes may read at the same time: a private temporary file, then os.replace."""
+    if path.exists() and path.read_text() == text:
+        return
+    tmp = path.with_name(f"{path.name}.{os.getpid()}.{secrets.token_hex(4)}.tmp")
+    tmp.write_text(text)
+    os.replace(tmp, path)
+
+
+def _prune_tmp(name: str, max_age: float = 86400) -> None:
+    """Drop temporary outputs a killed run left behind (older than a day)."""
+    now = time.time()
+    for t in cache_dir().glob(f"{name}-*.tmp.scip"):
+        try:
+            if now - t.stat().st_mtime > max_age:
+                t.unlink(missing_ok=True)
+        except OSError:
+            pass
+
+
+def run_cached(name: str, key: str, cmd: list[str], cwd: Path, out_path_arg: str | None, timeout: int,
+               out_flag_style: str = "space", env: dict | None = None,
+               notes: str | None = None, root: Path | None = None) -> tuple[Path | None, dict]:
+    """Run `cmd` (which writes a SCIP file) unless a cached result exists. The output path is appended to `cmd`
+    as `<out_path_arg> <path>` (style 'space') or `<out_path_arg>=<path>` (style 'eq'). `env` replaces the child's
+    environment; output lines matching the `notes` regex are kept in info["notes"] (a build error far above the tail).
+    Safe for concurrent processes: one run per key at a time (key_lock; the others wait and get a cache hit), each
+    run writes its own temporary file and moves it into the cache atomically."""
+    _prune_legacy(name)
+    proj = root or cwd
+    key = f"{cache.root_key(proj)}-{key}"        # the project's entries carry its key: `cg clean <root>` finds them
+    cache.note_project(proj)
+    out = cache_dir() / f"{name}-v{fsutil.CACHE_VERSION}-{key}.scip"
+    use_cache = os.environ.get("CODEGRAPH_NO_CACHE") != "1"
+    info = {"cache": "hit" if out.exists() and use_cache else "miss", "command": " ".join(cmd)}
+    if info["cache"] == "hit":
+        return out, info
+    with key_lock(name, key, timeout) as waited:
+        if waited:
+            info["lock_wait_seconds"] = waited
+        if use_cache and out.exists():         # another process indexed the same project while this one waited
+            info["cache"] = "hit"
+            return out, info
+        _prune_tmp(name)
+        return _run(cmd, cwd, out, out_path_arg, out_flag_style, timeout, info, env, notes)
+
+
+def _run(cmd, cwd, out: Path, out_path_arg, out_flag_style, timeout, info, env=None,
+         notes=None) -> tuple[Path | None, dict]:
+    tmp = out.with_name(f"{out.stem}.{os.getpid()}.{secrets.token_hex(4)}.tmp.scip")
+    full = list(cmd)
+    if out_path_arg:
+        full += [f"{out_path_arg}={tmp}"] if out_flag_style == "eq" else [out_path_arg, str(tmp)]
+    t0 = time.time()
+    try:
+        try:
+            r = subprocess.run(full, cwd=cwd, capture_output=True, text=True, timeout=timeout, env=env)
+        except subprocess.TimeoutExpired:
+            info["error"] = f"timeout after {timeout}s"
+            return None, info
+        except OSError as e:
+            info["error"] = str(e)
+            return None, info
+        info["seconds"] = round(time.time() - t0, 2)
+        tail = (r.stderr or "").strip().splitlines()[-8:]
+        info["stderr_tail"] = tail
+        if notes:
+            rx = re.compile(notes)
+            hits = [x.strip()[:300] for x in ((r.stdout or "") + "\n" + (r.stderr or "")).splitlines() if rx.search(x)]
+            if hits:
+                info["notes"] = list(dict.fromkeys(hits))[:6]
+        if r.returncode != 0 or not tmp.exists():
+            info["error"] = f"exit {r.returncode}" + ("" if tmp.exists() else ", no SCIP output written")
+            if r.returncode == 0 and out.exists():    # the cache file appeared meanwhile (unlocked fallback)
+                info.pop("error")
+                info["cache"] = "hit"
+                return out, info
+            return None, info
+        os.replace(tmp, out)
+        return out, info
+    finally:
+        if tmp.exists():
+            tmp.unlink(missing_ok=True)

codegraph/plugins/native/scipread.py

@@ -0,0 +1,194 @@
+"""SCIP reading helpers shared by the native-language plugins (Rust, C/C++).
+
+Unlike the generic importer (plugins/scip/importer.py), the native plugins own their node ids: definitions are
+matched to syntactic items by (file, line, name) so the SCIP layer and the tree-sitter layer agree. This module only
+loads an index, merges duplicate documents (scip-clang emits one per translation unit that touches a header) and
+parses symbol descriptors.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "scip"))
+import scip_pb2  # noqa: E402
+
+DEFINITION = scip_pb2.SymbolRole.Definition
+FORWARD_DEFINITION = getattr(scip_pb2.SymbolRole, "ForwardDefinition", 64)
+WRITE_ACCESS = scip_pb2.SymbolRole.WriteAccess
+
+
+@dataclass
+class Occ:
+    line: int          # 0-based
+    col: int
+    end_col: int
+    symbol: str
+    roles: int
+    enclosing: tuple   # (start_line, end_line) 0-based, or ()
+
+
+@dataclass
+class Doc:
+    path: str
+    occs: list[Occ] = field(default_factory=list)
+    symbols: dict = field(default_factory=dict)   # symbol -> SymbolInformation
+
+
+@dataclass
+class Index:
+    tool: str
+    version: str
+    docs: dict[str, Doc]
+    # symbol -> list of (path, Occ) definitions (scip-clang: also forward definitions/declarations)
+    defs: dict[str, list] = field(default_factory=dict)
+    occurrences: int = 0     # non-local occurrences read
+    positioned: int = 0      # ... of which carried a range cg can read
+
+
+def has_position(o) -> bool:
+    """The occurrence carries a range in a form cg reads (packed `range` of 3 / 4 ints, or a typed range)."""
+    return len(o.range) in (3, 4) or o.HasField("single_line_range") or o.HasField("multi_line_range")
+
+
+def health_warning(name: str, occurrences: int, positioned: int, definitions: int | None = None,
+                   matched: int | None = None, what: str = "the syntax layer's declarations") -> str | None:
+    """A warning for an index cg could not use although it is not empty, else None. Reported in `cg coverage`
+    (`warnings`) and by `cg doctor --scip`, instead of an exact layer that silently adds nothing."""
+    if occurrences and not positioned:
+        return (f"SCIP index {name}: {occurrences} occurrences but none with a usable position (range missing or in a "
+                "form cg does not read): no edges could be placed; regenerate it, or report the indexer version")
+    if occurrences and definitions == 0:
+        return (f"SCIP index {name}: {occurrences} occurrences but 0 definitions (symbols cg maps to nodes): nothing "
+                "imported; check the indexer and that the index belongs to this project")
+    if definitions and matched == 0:
+        return (f"SCIP index {name}: 0 of {definitions} definitions matched {what}: the exact layer added no edges; "
+                "check that the index was built from these sources (same paths, same revision)")
+    return None
+
+
+def _rng(r) -> tuple[int, int, int, int]:
+    r = list(r)
+    if len(r) == 3:
+        return r[0], r[1], r[0], r[2]
+    if len(r) == 4:
+        return r[0], r[1], r[2], r[3]
+    return (0, 0, 0, 0)
+
+
+def _typed(o, legacy: str, single: str, multi: str) -> tuple[int, int, int, int] | None:
+    """An occurrence range: the legacy packed `range` / `enclosing_range`, else the typed one newer indexers write
+    (SCIP 0.9 `single_line_range` / `multi_line_range`, e.g. scip-java 0.13); None when absent."""
+    r = getattr(o, legacy)
+    if len(r):
+        return _rng(r)
+    if o.HasField(single):
+        t = getattr(o, single)
+        return t.line, t.start_character, t.line, t.end_character
+    if o.HasField(multi):
+        t = getattr(o, multi)
+        return t.start_line, t.start_character, t.end_line, t.end_character
+    return None
+
+
+def occ_range(o) -> tuple[int, int, int, int]:
+    return _typed(o, "range", "single_line_range", "multi_line_range") or (0, 0, 0, 0)
+
+
+def occ_enclosing(o) -> tuple[int, int, int, int] | None:
+    return _typed(o, "enclosing_range", "single_line_enclosing_range", "multi_line_enclosing_range")
+
+
+def load(path: str | Path) -> Index:
+    idx = scip_pb2.Index()
+    idx.ParseFromString(Path(path).read_bytes())
+    docs: dict[str, Doc] = {}
+    seen: dict[str, set] = {}
+    out_occ = [0, 0]
+    for d in idx.documents:
+        doc = docs.get(d.relative_path)
+        if doc is None:
+            doc = docs[d.relative_path] = Doc(d.relative_path)
+            seen[d.relative_path] = set()
+        s = seen[d.relative_path]
+        for o in d.occurrences:
+            if o.symbol.startswith("local ") or not o.symbol:
+                continue
+            out_occ[0] += 1
+            if has_position(o):
+                out_occ[1] += 1
+            sl, sc, el, ec = occ_range(o)
+            key = (sl, sc, ec, o.symbol, o.symbol_roles)
+            if key in s:
+                continue
+            s.add(key)
+            enc = ()
+            er = occ_enclosing(o)
+            if er:
+                enc = (er[0], er[2])
+            doc.occs.append(Occ(sl, sc, ec, o.symbol, o.symbol_roles, enc))
+        for si in d.symbols:
+            if not si.symbol.startswith("local "):
+                doc.symbols.setdefault(si.symbol, si)
+    out = Index(idx.metadata.tool_info.name, idx.metadata.tool_info.version, docs, occurrences=out_occ[0],
+                positioned=out_occ[1])
+    for doc in docs.values():
+        doc.occs.sort(key=lambda o: (o.line, o.col))
+        for o in doc.occs:
+            if o.roles & DEFINITION:
+                out.defs.setdefault(o.symbol, []).append((doc.path, o))
+    return out
+
+
+_DESC = re.compile(r"(`(?:[^`]|``)*`|[^\s/#.()\[\]:!`]+)?(/|#|\.|:|!|\(([^)]*)\)\.|\[)")
+
+
+def descriptors(symbol: str) -> tuple[str, list[tuple[str, str]]] | None:
+    """'<scheme> <manager> <package> <version> <descriptors>' -> (package, [(name, suffix)]).
+    suffix: '/' namespace, '#' type, '.' term, '(' method, '!' macro, '[' type parameter / impl disambiguator."""
+    if symbol.startswith("local "):
+        return None
+    parts = symbol.split(" ", 4)
+    if len(parts) < 5:
+        return None
+    pkg, desc = parts[2], parts[4]
+    out = []
+    i = 0
+    while i < len(desc):
+        if desc[i] == "[":  # [name] type parameter (rust-analyzer uses it for impl#[Type][Trait])
+            j = i + 1
+            depth = 1
+            while j < len(desc) and depth:
+                if desc[j] == "`":
+                    k = desc.find("`", j + 1)
+                    j = (k if k > 0 else len(desc) - 1) + 1
+                    continue
+                depth += {"[": 1, "]": -1}.get(desc[j], 0)
+                j += 1
+            out.append((desc[i + 1:j - 1].strip("`"), "["))
+            i = j
+            continue
+        m = _DESC.match(desc, i)
+        if not m or m.end() == i:
+            break
+        name = (m.group(1) or "").strip("`").replace("``", "`")
+        suf = m.group(2)
+        if suf.startswith("("):
+            suf = "("
+        out.append((name, suf))
+        i = m.end()
+    return pkg, out
+
+
+def is_project_symbol(idx: Index, symbol: str) -> bool:
+    return symbol in idx.defs
+
+
+def native_warning(path, idx: Index, stats: dict) -> str | None:
+    """health_warning for a native plugin's import (rust-analyzer, scip-clang): matched = definitions placed on a
+    syntax-layer item, the rest became synthetic nodes."""
+    m = stats.get("scip_defs_matched", 0)
+    return health_warning(Path(path).name, idx.occurrences, idx.positioned,
+                          (m + stats.get("scip_defs_synthetic", 0)) or None, m, "the syntax layer's items")