cseq 0.0.1__py3-none-any.whl

cseq/parser.py

@@ -0,0 +1,797 @@
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any
+
+from .model import (
+    CallSiteRecord,
+    Diagnostic,
+    FileParseArtifact,
+    FlowEdge,
+    FlowEdgeKind,
+    FunctionRecord,
+    GuardedSourceRegion,
+    ParseStatus,
+    SourceRange,
+    TranslationUnit,
+    ValueSlot,
+    ValueSlotKind,
+)
+
+
+class ParserBackend(ABC):
+    name: str
+
+    @abstractmethod
+    def parse(self, translation_unit: TranslationUnit) -> FileParseArtifact:
+        raise NotImplementedError
+
+
+class ClangJsonParser(ParserBackend):
+    """PoC parser backend using clang's JSON AST dump.
+
+    The backend boundary is intentional: a Tree-sitter fast parser can be added
+    later without changing ProjectIndex / Program IR consumers.
+    """
+
+    name = "clang-json"
+
+    def __init__(self, clang_executable: str | None = None) -> None:
+        exe = clang_executable or shutil.which("clang")
+        if not exe:
+            raise RuntimeError("clang executable was not found")
+        self.clang_executable = exe
+
+    def parse(self, translation_unit: TranslationUnit) -> FileParseArtifact:
+        source = translation_unit.source.path
+        cmd = [
+            self.clang_executable,
+            "-Xclang", "-ast-dump=json",
+            "-fsyntax-only", "-Wno-everything",
+            *translation_unit.arguments,
+            str(source),
+        ]
+        proc = subprocess.run(
+            cmd,
+            cwd=translation_unit.working_directory,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+        )
+        diagnostics = _parse_clang_diagnostics(proc.stderr)
+        opaque_regions = _opaque_regions_from_clang_diagnostics(proc.stderr)
+        guarded_regions = _preprocessor_guard_regions(source.read_bytes(), translation_unit.source.project_relative_path)
+        root = _load_ast_prefix(proc.stdout)
+        functions: list[FunctionRecord] = []
+        callsites: list[CallSiteRecord] = []
+        value_slots: list[ValueSlot] = []
+        flow_edges: list[FlowEdge] = []
+        if root is not None:
+            _collect_functions(root, translation_unit, functions)
+            callsites, value_slots, flow_edges = collect_program_facts(root, translation_unit, functions)
+
+        if proc.returncode == 0 and root is not None:
+            status = ParseStatus.OK
+        elif root is not None and functions:
+            status = ParseStatus.ERROR_RECOVERED
+        elif root is not None:
+            status = ParseStatus.PARTIAL
+        else:
+            status = ParseStatus.OPAQUE_REGION
+
+        return FileParseArtifact(
+            translation_unit=translation_unit,
+            status=status,
+            functions=functions,
+            callsites=callsites,
+            value_slots=value_slots,
+            flow_edges=flow_edges,
+            diagnostics=diagnostics,
+            opaque_regions=opaque_regions,
+            guarded_regions=guarded_regions,
+            parser_backend=self.name,
+        )
+
+
+def _load_ast_prefix(stdout: str) -> dict[str, Any] | None:
+    if not stdout.strip():
+        return None
+    try:
+        value = json.loads(stdout)
+    except json.JSONDecodeError:
+        return None
+    return value if isinstance(value, dict) else None
+
+
+
+def _opaque_regions_from_clang_diagnostics(stderr: str) -> list[SourceRange]:
+    """Convert hard compiler diagnostics into explicit uncertain source ranges.
+
+    Clang often still emits a useful partial AST after an error.  The range is
+    intentionally narrow (diagnostic line/column) so callers can keep all other
+    recovered facts while still showing that this location is not trustworthy.
+    """
+    rx = re.compile(r"^(.*?):(\d+):(\d+):\s*(fatal error|error):", re.MULTILINE)
+    seen: set[tuple[int, int]] = set()
+    out: list[SourceRange] = []
+    for m in rx.finditer(stderr):
+        line, col = int(m.group(2)), int(m.group(3))
+        key = (line, col)
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(SourceRange(line, col, line, col))
+    return out
+
+def _parse_clang_diagnostics(stderr: str) -> list[Diagnostic]:
+    result: list[Diagnostic] = []
+    rx = re.compile(r"\b(fatal error|error|warning|note):\s*(.*)$")
+    for raw in stderr.splitlines():
+        m = rx.search(raw)
+        if not m:
+            continue
+        sev = m.group(1).replace("fatal error", "fatal")
+        result.append(Diagnostic(severity=sev, message=m.group(2).strip(), raw=raw))
+    return result
+
+
+def _location_entry(location: dict[str, Any] | None) -> dict[str, Any]:
+    """Return the effective source location from Clang JSON location variants."""
+    if not isinstance(location, dict):
+        return {}
+    expansion = location.get("expansionLoc")
+    if isinstance(expansion, dict):
+        return expansion
+    spelling = location.get("spellingLoc")
+    if isinstance(spelling, dict):
+        return spelling
+    return location
+
+
+def _same_path(a: str, b: Path, working_directory: Path) -> bool:
+    try:
+        pa = Path(a)
+        if not pa.is_absolute():
+            pa = working_directory / pa
+        return pa.resolve() == b.resolve()
+    except (OSError, RuntimeError, ValueError):
+        return Path(a).name.lower() == b.name.lower()
+
+
+def _node_belongs_to_translation_unit(node: dict[str, Any], tu: TranslationUnit) -> bool:
+    """Exclude definitions physically coming from included headers.
+
+    Clang may omit ``file`` for consecutive locations in the primary source, so
+    absence of ``file`` is accepted only when there is no ``includedFrom`` chain.
+    Macro locations prefer expansionLoc, which represents the user's call site.
+    """
+    loc = _location_entry(node.get("loc"))
+    rng = node.get("range") or {}
+    begin = _location_entry(rng.get("begin"))
+    candidates = [x for x in (loc, begin) if isinstance(x, dict) and x]
+    saw_primary_without_file = False
+    for entry in candidates:
+        file_name = entry.get("file")
+        if file_name:
+            if _same_path(str(file_name), tu.source.path, tu.working_directory):
+                return True
+            return False
+        if entry.get("includedFrom"):
+            return False
+        saw_primary_without_file = True
+    return saw_primary_without_file
+
+
+def _collect_functions(node: dict[str, Any], tu: TranslationUnit, out: list[FunctionRecord]) -> None:
+    if node.get("kind") == "FunctionDecl" and _has_body(node) and _node_belongs_to_translation_unit(node, tu):
+        loc = node.get("loc") or {}
+        rng = node.get("range") or {}
+        begin = rng.get("begin") or loc
+        end = rng.get("end") or loc
+        start_line = _int_or_none(begin.get("line")) or _int_or_none(loc.get("line"))
+        start_col = _int_or_none(begin.get("col")) or _int_or_none(loc.get("col"))
+        name = str(node.get("name") or "<anonymous>")
+        storage = node.get("storageClass")
+        type_info = node.get("type") or {}
+        params = tuple(
+            str(c.get("name"))
+            for c in node.get("inner") or ()
+            if isinstance(c, dict) and c.get("kind") == "ParmVarDecl" and c.get("name")
+        )
+        out.append(FunctionRecord(
+            name=name,
+            qualified_id=_function_id(tu, name, start_line, start_col, storage, type_info.get("qualType")),
+            source_path=tu.source.project_relative_path,
+            source_range=SourceRange(start_line, start_col, _int_or_none(end.get("line")), _int_or_none(end.get("col"))),
+            storage_class=str(storage) if storage else None,
+            type_qualifier=str(type_info.get("qualType")) if type_info.get("qualType") else None,
+            parameters=params,
+        ))
+    for child in node.get("inner") or ():
+        if isinstance(child, dict):
+            _collect_functions(child, tu, out)
+
+
+def collect_program_facts(root: dict[str, Any], tu: TranslationUnit, functions: list[FunctionRecord]) -> tuple[list[CallSiteRecord], list[ValueSlot], list[FlowEdge]]:
+    source_bytes = tu.source.path.read_bytes()
+    guard_by_line = _preprocessor_guard_map(source_bytes)
+    calls: list[CallSiteRecord] = []
+    slots: dict[str, ValueSlot] = {}
+    edges: list[FlowEdge] = []
+    funcs_by_name = {f.name: f for f in functions}
+
+    def add_slot(slot: ValueSlot | None) -> str | None:
+        if slot is None:
+            return None
+        slots.setdefault(slot.key, slot)
+        return slot.key
+
+    def add_function_source(name: str) -> str:
+        key = f"function::{name}"
+        slots.setdefault(key, ValueSlot(key, ValueSlotKind.FUNCTION, name))
+        return key
+
+    def add_sources_to_target(expr: dict[str, Any] | None, target: ValueSlot | None, kind: FlowEdgeKind, current: FunctionRecord | None) -> None:
+        target_key = add_slot(target)
+        if not target_key or not expr:
+            return
+        fn_names = _expr_function_names(expr)
+        for fn in sorted(fn_names):
+            edges.append(FlowEdge(add_function_source(fn), target_key, kind, tu.source.project_relative_path, _range(expr)))
+        src_slot = _expr_slot(expr, current, tu)
+        src_key = add_slot(src_slot)
+        if src_key and src_key != target_key:
+            edges.append(FlowEdge(src_key, target_key, kind, tu.source.project_relative_path, _range(expr)))
+
+    # Global array initializers first.
+    for node in _walk_nodes(root):
+        if node.get("kind") != "VarDecl" or not _is_global_var(node, root):
+            continue
+        name = node.get("name")
+        if not name:
+            continue
+        init = next((c for c in node.get("inner") or () if isinstance(c, dict) and c.get("kind") == "InitListExpr"), None)
+        if not init:
+            continue
+        for idx, elem in enumerate(init.get("inner") or ()):
+            if not isinstance(elem, dict):
+                continue
+            exact = ValueSlot(f"global::{name}[{idx}]", ValueSlotKind.GLOBAL_ARRAY_ELEMENT, str(name), index=idx)
+            summary = ValueSlot(f"global::{name}[*]", ValueSlotKind.GLOBAL_ARRAY_SUMMARY, str(name))
+            add_sources_to_target(elem, exact, FlowEdgeKind.INIT, None)
+            add_sources_to_target(elem, summary, FlowEdgeKind.INIT, None)
+
+    def walk(node: dict[str, Any], current: FunctionRecord | None, control_context: tuple[str, ...] = ()) -> None:
+        next_current = current
+        next_context = control_context
+        kind = node.get("kind")
+        control = None if kind == "IfStmt" else _control_context_label(node, source_bytes)
+        if control is not None:
+            next_context = (*control_context, control)
+        if node.get("kind") == "FunctionDecl" and _has_body(node):
+            if not _node_belongs_to_translation_unit(node, tu):
+                return
+            name = str(node.get("name") or "<anonymous>")
+            loc = _location_entry(node.get("loc"))
+            line = _int_or_none(loc.get("line"))
+            next_current = next((f for f in functions if f.name == name and (line is None or f.source_range.start_line == line)), current)
+            if next_current:
+                for param in node.get("inner") or ():
+                    if isinstance(param, dict) and param.get("kind") == "ParmVarDecl" and param.get("name"):
+                        add_slot(_decl_slot(param, next_current, tu))
+
+        if next_current is not None:
+            if node.get("kind") == "VarDecl" and node.get("name"):
+                target = _decl_slot(node, next_current, tu)
+                add_slot(target)
+                init = next((c for c in node.get("inner") or () if isinstance(c, dict)), None)
+                if init:
+                    add_sources_to_target(init, target, FlowEdgeKind.INIT, next_current)
+
+            if node.get("kind") == "BinaryOperator" and node.get("opcode") == "=":
+                inner = [c for c in node.get("inner") or () if isinstance(c, dict)]
+                if len(inner) >= 2:
+                    target = _expr_slot(inner[0], next_current, tu)
+                    add_sources_to_target(inner[1], target, FlowEdgeKind.ASSIGN, next_current)
+
+            if node.get("kind") == "CallExpr":
+                inner = [c for c in node.get("inner") or () if isinstance(c, dict)]
+                callee_expr = inner[0] if inner else None
+                direct = _direct_callee_name(node)
+                callee_slot = None if direct else _expr_slot(callee_expr, next_current, tu)
+                callee_slot_key = add_slot(callee_slot)
+                arg_slots: list[str | None] = []
+                for arg in inner[1:]:
+                    arg_slots.append(add_slot(_argument_object_slot(arg, next_current, tu)))
+                calls.append(CallSiteRecord(
+                    caller_id=next_current.qualified_id,
+                    caller_name=next_current.name,
+                    callee_name=direct,
+                    raw_text=_raw_text(node, source_bytes),
+                    source_path=tu.source.project_relative_path,
+                    source_range=_range(node, source_bytes),
+                    callee_slot_key=callee_slot_key,
+                    argument_slot_keys=tuple(arg_slots),
+                    control_context=next_context,
+                    macro_expanded=_is_macro_expanded(node),
+                    spelling_range=_range_with_loc_kind(node, "spellingLoc"),
+                    expansion_range=_range_with_loc_kind(node, "expansionLoc"),
+                    guard_expression=guard_by_line.get((_range(node, source_bytes).start_line or 0)),
+                ))
+
+        children = [c for c in node.get("inner") or () if isinstance(c, dict)]
+        if kind == "IfStmt":
+            raw_if = _raw_text(node, source_bytes).replace("\n", " ").strip()
+            if len(raw_if) > 80:
+                raw_if = raw_if[:77] + "..."
+            base = "if:" + raw_if
+            for i, child in enumerate(children):
+                if i == 1:
+                    child_ctx = (*control_context, base + "/then")
+                elif i >= 2:
+                    child_ctx = (*control_context, base + "/else")
+                else:
+                    child_ctx = control_context
+                walk(child, next_current, child_ctx)
+            return
+        if kind == "CaseStmt":
+            labels, body = _case_chain(node, source_bytes)
+            label = "|".join(labels) if labels else "?"
+            if body is not None:
+                walk(body, next_current, (*next_context, f"CASE:{label}"))
+            return
+        if kind == "DefaultStmt":
+            for child in children:
+                walk(child, next_current, (*next_context, "DEFAULT"))
+            return
+        for child in children:
+            walk(child, next_current, next_context)
+
+    walk(root, None, ())
+    return calls, list(slots.values()), edges
+
+
+
+
+def _case_chain(node: dict[str, Any], source_bytes: bytes) -> tuple[list[str], dict[str, Any] | None]:
+    """Return consecutive case labels and the first non-CaseStmt body.
+
+    Clang represents fall-through labels such as ``case 2: case 3: body`` as
+    nested CaseStmt nodes.  Treating the nesting as conjunction would be wrong:
+    the body is reachable from either label.  We therefore collapse the label
+    chain into one alternative region (``CASE:2|3``).
+    """
+    labels: list[str] = []
+    current: dict[str, Any] | None = node
+    while isinstance(current, dict) and current.get("kind") == "CaseStmt":
+        children = [c for c in current.get("inner") or () if isinstance(c, dict)]
+        if not children:
+            return labels, None
+        label_node = children[0]
+        label = _raw_text(label_node, source_bytes).strip() or "?"
+        labels.append(label)
+        body = children[1] if len(children) >= 2 else None
+        if isinstance(body, dict) and body.get("kind") == "CaseStmt":
+            current = body
+            continue
+        return labels, body
+    return labels, current
+
+def _control_context_label(node: dict[str, Any], source_bytes: bytes) -> str | None:
+    kind = node.get("kind")
+    if kind not in {"IfStmt", "SwitchStmt", "ForStmt", "WhileStmt", "DoStmt"}:
+        return None
+    raw = _raw_text(node, source_bytes).replace("\n", " ").strip()
+    if kind == "IfStmt":
+        return f"IF:{_header_expression(raw, 'if')}"
+    if kind == "SwitchStmt":
+        return f"SWITCH:{_header_expression(raw, 'switch')}"
+    if kind == "ForStmt":
+        header = _header_expression(raw, "for")
+        compact = "".join(header.split())
+        return "LOOP:" + (("[infinite] " if compact == "for(;;)" else "") + header)
+    if kind == "WhileStmt":
+        header = _header_expression(raw, "while")
+        compact = "".join(header.split())
+        return "LOOP:" + (("[infinite] " if compact in {"while(1)", "while(true)"} else "") + header)
+    if kind == "DoStmt":
+        compact = "".join(raw.split())
+        infinite = compact.endswith("while(1)") or compact.endswith("while(1);") or compact.endswith("while(true)") or compact.endswith("while(true);")
+        return "LOOP:" + (("[infinite] " if infinite else "") + ("do/while(1)" if infinite else "do/while"))
+    return None
+
+
+def _header_expression(raw: str, keyword: str) -> str:
+    pos = raw.find("(")
+    if pos < 0:
+        return keyword
+    depth = 0
+    for i in range(pos, len(raw)):
+        ch = raw[i]
+        if ch == "(": depth += 1
+        elif ch == ")":
+            depth -= 1
+            if depth == 0: return raw[: i + 1].strip()
+    return raw[:120].strip()
+
+
+def _walk_nodes(node: dict[str, Any]):
+    yield node
+    for child in node.get("inner") or ():
+        if isinstance(child, dict):
+            yield from _walk_nodes(child)
+
+
+def _is_global_var(node: dict[str, Any], root: dict[str, Any]) -> bool:
+    # Clang top-level VarDecls appear directly below TranslationUnitDecl.
+    return any(child is node for child in root.get("inner") or ())
+
+
+def _expr_function_names(node: dict[str, Any] | None) -> set[str]:
+    out: set[str] = set()
+    if not isinstance(node, dict):
+        return out
+    if node.get("kind") == "DeclRefExpr":
+        ref = node.get("referencedDecl") or {}
+        if ref.get("kind") == "FunctionDecl" and ref.get("name"):
+            out.add(str(ref["name"]))
+    for child in node.get("inner") or ():
+        if isinstance(child, dict):
+            out |= _expr_function_names(child)
+    return out
+
+
+def _expr_slot(node: dict[str, Any] | None, current: FunctionRecord | None, tu: TranslationUnit) -> ValueSlot | None:
+    if not isinstance(node, dict):
+        return None
+    kind = node.get("kind")
+    if kind in {"ImplicitCastExpr", "ParenExpr", "CStyleCastExpr", "UnaryOperator"}:
+        inner = [c for c in node.get("inner") or () if isinstance(c, dict)]
+        if inner:
+            return _expr_slot(inner[0], current, tu)
+    if kind == "DeclRefExpr":
+        ref = node.get("referencedDecl") or {}
+        if ref.get("kind") in {"VarDecl", "ParmVarDecl"} and ref.get("name"):
+            return _decl_ref_slot(ref, current, tu)
+    if kind == "MemberExpr" and node.get("name"):
+        inner = [c for c in node.get("inner") or () if isinstance(c, dict)]
+        base_node = inner[0] if inner else None
+        base = _expr_slot(base_node, current, tu) if base_node else None
+        if base:
+            field = str(node["name"])
+            if _is_union_typed(base_node):
+                return ValueSlot(
+                    f"{base.key}.<union>", ValueSlotKind.UNION_SUMMARY,
+                    f"{base.name}.<union>", base.function_id, field_name="<union>",
+                )
+            return ValueSlot(f"{base.key}.{field}", ValueSlotKind.STRUCT_FIELD, f"{base.name}.{field}", base.function_id, field_name=field)
+    if kind == "CallExpr" and current is not None:
+        allocator = _direct_callee_name(node)
+        if allocator in {"malloc", "calloc", "realloc", "aligned_alloc"}:
+            rng = _range(node)
+            where = f"{tu.source.project_relative_path}:{rng.start_line or '?'}:{rng.start_column or '?'}"
+            key = f"heap::{current.qualified_id}::{where}:{allocator}"
+            return ValueSlot(key, ValueSlotKind.HEAP_ALLOCATION, f"{allocator}@{where}", current.qualified_id)
+    if kind == "ArraySubscriptExpr":
+        inner = [c for c in node.get("inner") or () if isinstance(c, dict)]
+        if len(inner) >= 2:
+            base_name = _declref_name(inner[0])
+            if base_name:
+                idx = _integer_value(inner[1])
+                if idx is not None:
+                    return ValueSlot(f"global::{base_name}[{idx}]", ValueSlotKind.GLOBAL_ARRAY_ELEMENT, base_name, index=idx)
+                return ValueSlot(f"global::{base_name}[*]", ValueSlotKind.GLOBAL_ARRAY_SUMMARY, base_name)
+    return None
+
+
+def _is_union_typed(node: dict[str, Any] | None) -> bool:
+    if not isinstance(node, dict):
+        return False
+    type_info = node.get("type") or {}
+    qual = str(type_info.get("qualType") or type_info.get("desugaredQualType") or "")
+    if "union " in qual:
+        return True
+    # Cast/paren nodes may carry a pointer type while the inner DeclRef has the
+    # actual union spelling, so inspect their first child conservatively.
+    for child in node.get("inner") or ():
+        if isinstance(child, dict) and _is_union_typed(child):
+            return True
+    return False
+
+
+def _argument_object_slot(node: dict[str, Any], current: FunctionRecord, tu: TranslationUnit) -> ValueSlot | None:
+    # &h and h are both treated as the same abstract object for the PoC alias binding.
+    if node.get("kind") == "UnaryOperator" and node.get("opcode") == "&":
+        inner = [c for c in node.get("inner") or () if isinstance(c, dict)]
+        return _expr_slot(inner[0], current, tu) if inner else None
+    return _expr_slot(node, current, tu)
+
+
+def _decl_slot(node: dict[str, Any], current: FunctionRecord, tu: TranslationUnit) -> ValueSlot | None:
+    name = node.get("name")
+    if not name:
+        return None
+    if node.get("kind") == "ParmVarDecl":
+        key = f"{current.qualified_id}::param::{name}"
+        return ValueSlot(key, ValueSlotKind.PARAMETER, str(name), current.qualified_id)
+    key = f"{current.qualified_id}::local::{name}"
+    return ValueSlot(key, ValueSlotKind.LOCAL, str(name), current.qualified_id)
+
+
+def _decl_ref_slot(ref: dict[str, Any], current: FunctionRecord | None, tu: TranslationUnit) -> ValueSlot | None:
+    if current is None or not ref.get("name"):
+        return None
+    name = str(ref["name"])
+    if ref.get("kind") == "ParmVarDecl":
+        return ValueSlot(f"{current.qualified_id}::param::{name}", ValueSlotKind.PARAMETER, name, current.qualified_id)
+    return ValueSlot(f"{current.qualified_id}::local::{name}", ValueSlotKind.LOCAL, name, current.qualified_id)
+
+
+def _declref_name(node: dict[str, Any] | None) -> str | None:
+    if not isinstance(node, dict):
+        return None
+    if node.get("kind") == "DeclRefExpr":
+        ref = node.get("referencedDecl") or {}
+        if ref.get("name"):
+            return str(ref["name"])
+    for child in node.get("inner") or ():
+        if isinstance(child, dict):
+            found = _declref_name(child)
+            if found:
+                return found
+    return None
+
+
+def _integer_value(node: dict[str, Any] | None) -> int | None:
+    if not isinstance(node, dict):
+        return None
+    if node.get("kind") == "IntegerLiteral":
+        value = node.get("value")
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            return None
+    for child in node.get("inner") or ():
+        if isinstance(child, dict):
+            v = _integer_value(child)
+            if v is not None:
+                return v
+    return None
+
+
+
+def _is_macro_expanded(node: dict[str, Any]) -> bool:
+    rng = node.get("range") or {}
+    for part in (rng.get("begin") or {}, rng.get("end") or {}):
+        if isinstance(part, dict) and ("spellingLoc" in part or "expansionLoc" in part):
+            return True
+    return False
+
+
+def _range_with_loc_kind(node: dict[str, Any], key: str) -> SourceRange | None:
+    rng = node.get("range") or {}
+    begin_raw = rng.get("begin") or {}
+    end_raw = rng.get("end") or {}
+    begin = begin_raw.get(key) if isinstance(begin_raw, dict) else None
+    end = end_raw.get(key) if isinstance(end_raw, dict) else None
+    if not isinstance(begin, dict) and not isinstance(end, dict):
+        return None
+    begin = begin if isinstance(begin, dict) else {}
+    end = end if isinstance(end, dict) else begin
+    start_line = _int_or_none(begin.get("line")) or _int_or_none(end.get("line"))
+    end_line = _int_or_none(end.get("line")) or start_line
+    return SourceRange(start_line, _int_or_none(begin.get("col")), end_line, _int_or_none(end.get("col")))
+
+def _direct_callee_name(call_node: dict[str, Any]) -> str | None:
+    def find(node: Any) -> str | None:
+        if not isinstance(node, dict):
+            return None
+        if node.get("kind") == "DeclRefExpr":
+            ref = node.get("referencedDecl") or {}
+            if ref.get("kind") == "FunctionDecl" and ref.get("name"):
+                return str(ref["name"])
+        for child in node.get("inner") or ():
+            found = find(child)
+            if found:
+                return found
+        return None
+    inner = call_node.get("inner") or []
+    return find(inner[0]) if inner else None
+
+
+def _raw_text(node: dict[str, Any], source_bytes: bytes) -> str:
+    rng = node.get("range") or {}
+    begin = rng.get("begin") or {}
+    end = rng.get("end") or {}
+    start = begin.get("offset") if isinstance(begin, dict) else None
+    stop = end.get("offset") if isinstance(end, dict) else None
+    tok_len = end.get("tokLen") if isinstance(end, dict) else None
+    tok_len = tok_len or 1
+    if isinstance(start, int) and isinstance(stop, int):
+        return source_bytes[start:stop + int(tok_len)].decode("utf-8", errors="replace")
+
+    # Macro-expanded AST ranges often store expansionLoc/spellingLoc instead of
+    # direct offsets. Prefer the expansion location and reconstruct only the
+    # invocation token sequence from the original source.
+    expansion = begin.get("expansionLoc") if isinstance(begin, dict) else None
+    if not isinstance(expansion, dict):
+        expansion = end.get("expansionLoc") if isinstance(end, dict) else None
+    if isinstance(expansion, dict) and isinstance(expansion.get("offset"), int):
+        return _macro_invocation_text(source_bytes, int(expansion["offset"]))
+    return "<call>"
+
+
+def _macro_invocation_text(source_bytes: bytes, start: int) -> str:
+    text = source_bytes.decode("utf-8", errors="replace")
+    start = max(0, min(start, len(text)))
+    i = start
+    while i < len(text) and (text[i].isalnum() or text[i] == "_"):
+        i += 1
+    while i < len(text) and text[i].isspace() and text[i] not in "\r\n":
+        i += 1
+    if i >= len(text) or text[i] != "(":
+        return text[start:i].strip() or "<call>"
+    depth = 0
+    quote: str | None = None
+    escaped = False
+    j = i
+    while j < len(text):
+        ch = text[j]
+        if quote is not None:
+            if escaped:
+                escaped = False
+            elif ch == "\\":
+                escaped = True
+            elif ch == quote:
+                quote = None
+        else:
+            if ch in {"\"", "'"}:
+                quote = ch
+            elif ch == "(":
+                depth += 1
+            elif ch == ")":
+                depth -= 1
+                if depth == 0:
+                    return text[start:j + 1].strip()
+            elif ch in "\r\n;" and depth <= 0:
+                break
+        j += 1
+    return text[start:j].strip() or "<call>"
+
+
+def _range(node: dict[str, Any], source_bytes: bytes | None = None) -> SourceRange:
+    rng = node.get("range") or {}
+    begin = rng.get("begin") or node.get("loc") or {}
+    end = rng.get("end") or node.get("loc") or {}
+    if isinstance(begin, dict) and isinstance(begin.get("expansionLoc"), dict):
+        begin = begin["expansionLoc"]
+    elif isinstance(begin, dict) and isinstance(begin.get("spellingLoc"), dict):
+        begin = begin["spellingLoc"]
+    if isinstance(end, dict) and isinstance(end.get("expansionLoc"), dict):
+        end = end["expansionLoc"]
+    elif isinstance(end, dict) and isinstance(end.get("spellingLoc"), dict):
+        end = end["spellingLoc"]
+    start_line = _int_or_none(begin.get("line")) or _int_or_none(end.get("line"))
+    start_col = _int_or_none(begin.get("col"))
+    end_line = _int_or_none(end.get("line")) or start_line
+    end_col = _int_or_none(end.get("col"))
+    if source_bytes is not None and start_line is None and isinstance(begin.get("offset"), int):
+        start_line, start_col = _line_col_from_offset(source_bytes, int(begin["offset"]))
+    if source_bytes is not None and end_line is None and isinstance(end.get("offset"), int):
+        end_line, end_col = _line_col_from_offset(source_bytes, int(end["offset"]))
+    return SourceRange(start_line, start_col, end_line, end_col)
+
+
+def _line_col_from_offset(source_bytes: bytes, offset: int) -> tuple[int, int]:
+    offset = max(0, min(offset, len(source_bytes)))
+    prefix = source_bytes[:offset]
+    line = prefix.count(b"\n") + 1
+    last_nl = prefix.rfind(b"\n")
+    col = offset + 1 if last_nl < 0 else offset - last_nl
+    return line, col
+
+
+def _preprocessor_guard_map(source_bytes: bytes) -> dict[int, str]:
+    """Map active source lines to symbolic preprocessor guards.
+
+    This scanner does not try to evaluate C preprocessor expressions. It keeps
+    them as symbolic evidence so the active AST retains the reason a callsite
+    exists in the selected build.
+    """
+    text = source_bytes.decode("utf-8", errors="replace")
+    stack: list[dict[str, object]] = []
+    result: dict[int, str] = {}
+
+    def current_guard() -> str | None:
+        parts = [str(frame["current"]) for frame in stack if frame.get("current")]
+        return " && ".join(f"({p})" for p in parts) if parts else None
+
+    for lineno, raw in enumerate(text.splitlines(), 1):
+        stripped = raw.strip()
+        if stripped.startswith("#ifdef "):
+            expr = f"defined({stripped[7:].strip()})"
+            stack.append({"branches": [expr], "current": expr})
+            continue
+        if stripped.startswith("#ifndef "):
+            expr = f"!defined({stripped[8:].strip()})"
+            stack.append({"branches": [expr], "current": expr})
+            continue
+        if stripped.startswith("#if "):
+            expr = stripped[4:].strip() or "<empty>"
+            stack.append({"branches": [expr], "current": expr})
+            continue
+        if stripped.startswith("#elif ") and stack:
+            expr = stripped[6:].strip() or "<empty>"
+            branches = list(stack[-1].get("branches") or [])
+            prior = " || ".join(f"({x})" for x in branches)
+            stack[-1]["current"] = f"!({prior}) && ({expr})"
+            branches.append(expr)
+            stack[-1]["branches"] = branches
+            continue
+        if stripped.startswith("#else") and stack:
+            branches = list(stack[-1].get("branches") or [])
+            prior = " || ".join(f"({x})" for x in branches) or "<none>"
+            stack[-1]["current"] = f"!({prior})"
+            continue
+        if stripped.startswith("#endif") and stack:
+            stack.pop()
+            continue
+        guard = current_guard()
+        if guard is not None:
+            result[lineno] = guard
+    return result
+
+
+def _preprocessor_guard_regions(source_bytes: bytes, source_path: str) -> list[GuardedSourceRegion]:
+    """Return contiguous guarded source regions for *all* preprocessor branches.
+
+    This is intentionally independent from Clang's active AST.  Even source lines
+    excluded by the selected build remain represented as symbolic evidence, so an
+    inactive branch is distinguishable from code that never existed.
+    """
+    by_line = _preprocessor_guard_map(source_bytes)
+    if not by_line:
+        return []
+    regions: list[GuardedSourceRegion] = []
+    start: int | None = None
+    prev: int | None = None
+    expr: str | None = None
+    for line in sorted(by_line):
+        current = by_line[line]
+        if start is None:
+            start = prev = line
+            expr = current
+            continue
+        if current == expr and line == (prev or line) + 1:
+            prev = line
+            continue
+        regions.append(GuardedSourceRegion(source_path, SourceRange(start, 1, prev, None), str(expr)))
+        start = prev = line
+        expr = current
+    if start is not None:
+        regions.append(GuardedSourceRegion(source_path, SourceRange(start, 1, prev, None), str(expr)))
+    return regions
+
+
+def _has_body(node: dict[str, Any]) -> bool:
+    return any(isinstance(c, dict) and c.get("kind") == "CompoundStmt" for c in node.get("inner") or ())
+
+
+def _function_id(tu: TranslationUnit, name: str, line: int | None, col: int | None, storage: Any, qual_type: Any) -> str:
+    line = line if line is not None else "?"
+    col = col if col is not None else "?"
+    storage_text = storage or "external"
+    type_text = qual_type or "?"
+    return f"{tu.source.project_relative_path}:{line}:{col}:{storage_text}:{name}:{type_text}"
+
+
+def _int_or_none(value: Any) -> int | None:
+    return value if isinstance(value, int) else None