symgrep-codesearch 0.5.0__py3-none-any.whl

symgrep/blocks.py

@@ -0,0 +1,326 @@
+"""Block-granular units: sub-function AST blocks + a scope signature, for search-by-MEANING.
+
+WHY THIS MODULE EXISTS. `functions()` (semantic.py) indexes whole functions, so search-by-meaning finds a
+duplicated FUNCTION but misses a duplicated BLOCK — the same coherent snippet living inside two otherwise-
+different functions (the sub-function Type-4 clone honestreview's canonical_concerns axis asks for). This
+module extracts those blocks and gives each a deterministic SCOPE SIGNATURE (the block as an "environment":
+what it reads, what it writes, what it does), so retrieval separates a domain accumulation from a generic
+loop by more than a prose sentence. See docs/BLOCK_CHUNKING_SPEC.md.
+
+WHAT IS AND IS NOT A JUDGEMENT (the same line semantic.py draws):
+  · Extracting a block and computing its signature is PARSING — the tree-sitter AST settles it exactly, no
+    meaning decision. Alpha-renaming invariance (two clones with different local names → same signature) is a
+    property of dropping plain-identifier leaf NAMES, not of any classifier.
+  · Turning a block into a one-sentence job description is a judgement → an LLM (cli.py's describer), grounded
+    by the signature. Matching a query to those is RETRIEVAL (semantic.py). This module decides nothing about
+    duplication; it yields candidate units, and the caller's model judges "same job".
+
+CHANGE-DETECTION IS CONTENT, NOT MTIME. A block's identity (its `key`) embeds the sha256 of its own body, and
+`body_hash` is carried explicitly, so the build's incremental logic keys re-describe on CONTENT: a block that
+merely moves keeps its key (no re-describe), a body that changes gets a new key. `stamp` (mtime:size) is
+carried ONLY as the per-file freshness DISPLAY signal search_by_meaning renders — it never gates re-describe
+(mirrors functions() / semantic.py's documented stamp-is-a-signal contract), so a `touch`/restore/sync that
+resets mtime does NOT cause a reindex.
+
+DEGRADES, NEVER DEPENDS. Block extraction is an OPTIONAL layer. If the tree-sitter pack is absent the layer is
+UNAVAILABLE and says so ONCE (never a silent per-file swallow), returning no blocks while functions() keeps
+indexing. A per-file cap engaging is COUNTED and REPORTED, never a silent drop. No broad `except` hides a
+real failure: a genuine parse crash propagates as the bug it is.
+
+Reuses structural.py's tree-sitter parse (byte spans + node.type, all TS_LANG_BY_EXT languages) and
+enclosing.file_symbols for the enclosing-symbol nesting. No new dependency.
+"""
+import pathlib
+import sys
+from typing import Dict, List, Optional
+
+from .semantic import _cfg_int, _hash8   # shared helpers (one definition — name-uniqueness)
+
+# A block = a coherent standalone AST sub-tree. Matched by tree-sitter TYPE SUFFIX so ONE rule spans grammars
+# (the C-family/python grammars share these type names; the suffix match tolerates the prefixes that differ).
+BLOCK_TYPE_SUFFIXES = ("for_statement", "for_in_statement", "foreach_statement", "while_statement",
+                       "if_statement", "switch_statement", "match_statement", "try_statement",
+                       "with_statement", "case_statement", "catch_clause")
+# Nodes whose leaf identifier IS semantically meaningful across clones (kept in the signature): a call target
+# and an accessed attribute/member/field/property name. A PLAIN variable identifier is dropped (alpha-
+# invariance) but counted, so the signature is shape + API surface, not variable names.
+_CALL_SUFFIXES = ("call", "call_expression", "method_invocation", "function_call")
+_ATTR_SUFFIXES = ("attribute", "member_expression", "field_expression", "selector_expression",
+                  "member_access_expression", "scoped_identifier")
+_ASSIGN_SUFFIXES = ("assignment", "assignment_expression", "augmented_assignment",
+                    "assignment_statement", "variable_declarator", "short_var_declaration")
+
+MIN_BLOCK_LINES_DEFAULT = 3
+MIN_BLOCK_CHARS_DEFAULT = 60
+BLOCK_MAX_PER_FILE_DEFAULT = 200
+
+
+class BlockLayerUnavailable(RuntimeError):
+    """The tree-sitter pack needed for block extraction is not installed. Raised so the OPTIONAL block layer
+    says 'unavailable' once, loudly, rather than silently returning no blocks — unavailable ≠ empty."""
+
+
+def _lang_of(path: pathlib.Path) -> Optional[str]:
+    from .enclosing import TS_LANG_BY_EXT
+    return TS_LANG_BY_EXT.get(path.suffix.lower())
+
+
+def _is_func_node(t: str) -> bool:
+    return (t.endswith("function_definition") or t.endswith("method_definition")
+            or t in ("function_declaration", "method_declaration", "function_item", "arrow_function"))
+
+
+def _func_nodes(root):
+    """All function/method nodes in the tree (stack walk, like structural.search_source)."""
+    out, stack = [], [root]
+    while stack:
+        n = stack.pop()
+        if _is_func_node(n.type):
+            out.append(n)
+        stack.extend(n.children)
+    return out
+
+
+def _block_nodes(fn_node):
+    """Qualifying block nodes inside a function — OUTERMOST WINS (do not descend into a collected block, so a
+    nested if inside a for is not indexed twice and blocks never overlap)."""
+    out, stack = [], list(fn_node.children)
+    while stack:
+        n = stack.pop()
+        if any(n.type.endswith(suf) for suf in BLOCK_TYPE_SUFFIXES):
+            out.append(n)
+            continue                       # outermost wins — do NOT descend into this block's children
+        stack.extend(n.children)
+    return out
+
+
+def _suffix_any(t: str, suffixes) -> bool:
+    return any(t.endswith(s) or t == s for s in suffixes)
+
+
+def _rightmost_identifier(node, data: bytes) -> Optional[str]:
+    """The last identifier leaf under `node` (obj.attr.method → 'method'); the meaningful API name."""
+    order = []
+    stack = [node]
+    while stack:
+        n = stack.pop()
+        if n.type.endswith("identifier") or n.type.endswith("property_identifier") \
+                or n.type.endswith("field_identifier"):
+            order.append((n.start_byte, n))
+        stack.extend(n.children)
+    if not order:
+        return None
+    order.sort()
+    last = order[-1][1]
+    txt = data[last.start_byte:last.end_byte].decode("utf-8", "ignore")
+    return txt or None
+
+
+def scope_signature(node, data: bytes) -> str:
+    """A canonical, alpha-renaming-invariant SHAPE+API signature of a block — the block as an environment.
+
+    Deterministic parsing, no judgement. Captures: the control-type skeleton (order-sensitive), the sorted
+    unique call targets + accessed member names (the API surface — these ARE meaningful across clones), the
+    operator multiset, literal KINDS (not values), and counts of assigned vs read plain identifiers (a size
+    signal for in/out, names dropped for alpha-invariance). Two Type-4 clones that differ only in local
+    variable names produce the SAME signature; two blocks that call different methods do not.
+
+    This is retrieval enrichment + a $0 exact-clone pre-filter, explicitly NOT a resolved dataflow: it does
+    not prove two blocks are the same, it makes the embedding and the describe prompt see the block's shape.
+    """
+    ctl = []                     # control skeleton, in walk order
+    calls, attrs, ops = set(), set(), []
+    lits = set()
+    assigned, read = 0, 0
+    assign_target_ids = set()
+
+    def _collect_targets(n):
+        kids = n.named_children if n.named_children else n.children
+        if kids:
+            st = [kids[0]]
+            while st:
+                m = st.pop()
+                if m.type.endswith("identifier"):
+                    assign_target_ids.add(m.id)
+                st.extend(m.children)
+
+    stack = [node]
+    while stack:
+        n = stack.pop()
+        t = n.type
+        if any(t.endswith(suf) for suf in BLOCK_TYPE_SUFFIXES):
+            ctl.append(next(s for s in BLOCK_TYPE_SUFFIXES if t.endswith(s)))
+        if _suffix_any(t, _ASSIGN_SUFFIXES):
+            _collect_targets(n)
+        if _suffix_any(t, _CALL_SUFFIXES):
+            fnc = n.child_by_field_name("function") if hasattr(n, "child_by_field_name") else None
+            target = fnc or (n.named_children[0] if n.named_children else None)
+            if target is not None:
+                name = _rightmost_identifier(target, data)
+                if name:
+                    calls.add(name)
+        if _suffix_any(t, _ATTR_SUFFIXES):
+            name = _rightmost_identifier(n, data)
+            if name:
+                attrs.add(name)
+        if t.endswith("identifier"):
+            if n.id in assign_target_ids:
+                assigned += 1
+            else:
+                read += 1
+        elif t.endswith("string") or t == "string_literal":
+            lits.add("str")
+        elif t.endswith("integer") or t.endswith("number") or t == "int_literal" or t.endswith("float"):
+            lits.add("num")
+        elif t in ("true", "false", "null", "nil"):
+            lits.add("bool")
+        elif not n.children and not n.is_named:
+            tok = data[n.start_byte:n.end_byte].decode("utf-8", "ignore")
+            if tok and all(c in "+-*/%<>=!&|^~" for c in tok) and tok != "=":
+                ops.append(tok)
+        stack.extend(n.children)
+    parts = [
+        "ctl:" + ">".join(ctl),
+        "call:" + ",".join(sorted(calls)),
+        "attr:" + ",".join(sorted(attrs)),
+        "op:" + ",".join(sorted(ops)),
+        "lit:" + ",".join(sorted(lits)),
+        f"io:{read}r/{assigned}w",
+    ]
+    return " ".join(parts)
+
+
+def _parsers_for(langs) -> Dict[str, object]:
+    """Acquire a tree-sitter parser per language ONCE. If the pack is absent, raise BlockLayerUnavailable —
+    the OPTIONAL layer is unavailable and says so once, never a per-file silent swallow. A concrete parser
+    that cannot be built for one known language is left out (that language simply yields no blocks); a missing
+    PACK (ImportError) fails the whole layer loudly because nothing can parse."""
+    from . import structural
+    from .enclosing import TreeSitterUnavailable
+    parsers = {}
+    for lang in sorted(set(langs)):
+        try:
+            parsers[lang] = structural._get_parser(lang)
+        except (ImportError, TreeSitterUnavailable) as e:
+            raise BlockLayerUnavailable(
+                "no usable tree-sitter grammar pack, so block extraction is UNAVAILABLE — this is NOT "
+                "'no blocks found'. Install tree-sitter-language-pack, or leave SYMGREP_INDEX_BLOCKS unset. "
+                f"[{e}]") from e
+    return parsers
+
+
+def blocks(roots: List[str]) -> List[dict]:
+    """Every qualifying sub-function block under `roots`, mirroring functions()' dict shape plus block fields.
+
+    Returned dict: {key, qual, path, lineno, body, body_hash, stamp, unit:"block", parent_key, block_start,
+    block_end, signature, sig_hash}. Key = "<abspath>::<parent_sym>#<block_kind>@<body_hash8>" — CONTENT-keyed
+    (a block that moves keeps its key; a changed body gets a new one). Identical blocks in one function
+    collide on key → deduped (they ARE the same content). Bounded by min-size + per-file cap; skips trivia.
+    Every drop (per-file cap) and skip (unparsed file) is counted and REPORTED, never silent.
+    """
+    from .enclosing import file_symbols
+    from .semantic import INDEXABLE_EXTS, _is_generated, _looks_minified, _module_name
+
+    min_lines = _cfg_int("SYMGREP_BLOCK_MIN_LINES", MIN_BLOCK_LINES_DEFAULT)
+    min_chars = _cfg_int("SYMGREP_BLOCK_MIN_CHARS", MIN_BLOCK_CHARS_DEFAULT)
+    max_per_file = _cfg_int("SYMGREP_BLOCK_MAX_PER_FILE", BLOCK_MAX_PER_FILE_DEFAULT)
+
+    # Enumerate candidate files first, so parsers are acquired once for exactly the languages present.
+    cand = []
+    for root in roots:
+        rp = pathlib.Path(root)
+        files = [rp] if rp.is_file() else sorted(
+            p for p in rp.rglob("*")
+            if p.is_file() and p.suffix.lower() in INDEXABLE_EXTS and not _is_generated(p, rp))
+        for f in files:
+            lang = _lang_of(f)
+            if lang:
+                cand.append((f, lang))
+    if not cand:
+        return []
+    parsers = _parsers_for(l for _f, l in cand)      # raises BlockLayerUnavailable if the pack is absent (loud)
+
+    out = []
+    capped_files = 0        # files where the per-file cap engaged (blocks beyond the cap intentionally omitted)
+    capped_blocks = 0       # count of qualifying blocks omitted by the cap — the honest denominator
+    parse_skipped = 0       # files whose bytes would not parse (counted, not swallowed)
+    for f, lang in cand:
+        parser = parsers.get(lang)
+        if parser is None:
+            continue
+        try:
+            st = f.stat()
+            if st.st_size > 0 and getattr(st, "st_blocks", 1) == 0:   # iCloud dataless guard (as functions())
+                continue
+            text = f.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        if _looks_minified(text):
+            continue
+        data = text.encode("utf-8")
+        tree = parser.parse(data)                    # valid bytes parse; a genuine crash propagates (a real bug)
+        if tree is None or tree.root_node is None:
+            parse_skipped += 1
+            continue
+        fs = file_symbols(str(f))
+        stamp = f"{st.st_mtime_ns}:{st.st_size}"     # DISPLAY freshness signal only — identity is body_hash
+        mod = _module_name(f)
+        n_file = 0
+        capped_here = False
+        seen_keys = set()
+        for fn in _func_nodes(tree.root_node):
+            fn_line = fn.start_point[0] + 1
+            parent_sym = _enclosing_name(fs, fn_line) or f"<anon@{fn_line}>"
+            for blk in _block_nodes(fn):
+                body = data[blk.start_byte:blk.end_byte].decode("utf-8", "ignore")
+                if body.count("\n") + 1 < min_lines or len(body) < min_chars:
+                    continue
+                if n_file >= max_per_file:           # cap engaged — COUNT the omission, do not silently drop
+                    capped_blocks += 1
+                    capped_here = True
+                    continue
+                bh = _hash8(body)
+                block_kind = next(s for s in BLOCK_TYPE_SUFFIXES if blk.type.endswith(s))
+                key = f"{f.resolve()}::{parent_sym}#{block_kind}@{bh}"
+                if key in seen_keys:                 # exact-dup within this function → dedup (same content)
+                    continue
+                seen_keys.add(key)
+                sig = scope_signature(blk, data)
+                start_line = blk.start_point[0] + 1
+                out.append({
+                    "key": key,
+                    "qual": f"{mod}.{parent_sym}#{block_kind}@{bh}",   # whitespace-free (MCP contract)
+                    "path": str(f), "lineno": start_line, "body": body, "body_hash": bh, "stamp": stamp,
+                    "unit": "block", "parent_key": f"{f.resolve()}::{parent_sym}",
+                    "block_start": start_line, "block_end": blk.end_point[0] + 1,
+                    "signature": sig, "sig_hash": _hash8(sig),
+                })
+                n_file += 1
+        if capped_here:
+            capped_files += 1
+    if capped_blocks or parse_skipped:
+        sys.stderr.write(
+            f"symgrep block-index: {len(out)} block(s); "
+            f"OMITTED {capped_blocks} block(s) past the per-file cap ({max_per_file}) in {capped_files} file(s) "
+            f"[raise SYMGREP_BLOCK_MAX_PER_FILE]; {parse_skipped} file(s) would not parse (counted, not "
+            f"described).\n")
+    return out
+
+
+def _enclosing_name(fs, line: int) -> Optional[str]:
+    """The innermost enclosing symbol name at `line`, via FileSymbols.enclosing when available, else a manual
+    innermost-span scan over fs.symbols."""
+    if fs is None:
+        return None
+    enc = getattr(fs, "enclosing", None)
+    if callable(enc):
+        sym = enc(line)
+        if sym is not None:
+            return sym.name
+    best = None
+    for s in (getattr(fs, "symbols", None) or []):
+        if s.start is None or s.end is None:
+            continue
+        if s.start <= line <= s.end and (best is None or s.start > best.start):
+            best = s
+    return best.name if best else None

symgrep/classfile.py

@@ -0,0 +1,221 @@
+"""Symbols from a compiled JVM `.class` file — the constant pool read directly, no JDK.
+
+WHY THIS IS DIFFERENT FROM EVERY OTHER SYMBOL PATH. Source (.java, .py, …) is TEXT: ripgrep matches it
+and tree-sitter/ast gives exact spans. A `.class` is BINARY bytecode — ripgrep, symgrep's whole Tier 1,
+cannot search it, and there is no source text to grep. But the JVM classfile format (JVMS §4) is fixed
+and self-describing: the constant pool holds the class name, every method name + type descriptor, and
+every field name. Extracting them is reading a documented binary layout — PARSING, exactly like
+tree-sitter reads a grammar, so it carries no model call and its `basis` is "classfile" (honest: this
+came from bytecode, not source).
+
+WHAT IT CAN AND CANNOT KNOW (stated, never blurred):
+  · CAN: class name, method names + descriptors (overloads disambiguated), field names — the public
+    shape a `file_symbols` consumer wants when the source is a dependency it does not have.
+  · Line spans: ONLY if the class was compiled with debug info (the optional Code→LineNumberTable
+    attribute). Present → real spans; absent → start=0, end=None, and the basis still says "classfile"
+    so a consumer never mistakes a missing span for line 0.
+  · CANNOT: local variable names, comments, or a trustworthy one-sentence "what it does" — bytecode is
+    a lossy witness of intent, which is why `.class` feeds the STRUCTURAL file_symbols path and is
+    deliberately kept OUT of the semantic (meaning) index. Describing a method from its bytecode would
+    be a confident-wrong-answer; if you have the source, index the source.
+
+This slots into enclosing.file_symbols so the existing `file_symbols(path)` MCP tool answers for a
+`.class` with no new surface — a dependency jar's symbols become queryable without unzipping to source.
+"""
+import struct
+from typing import Dict, List, Optional, Tuple
+
+# Constant-pool tag → how many bytes its body occupies after the 1-byte tag, and whether it eats an
+# extra pool slot (Long/Double do — JVMS §4.4.5). This is the format, not a heuristic.
+_CP_LAYOUT: Dict[int, Tuple[int, bool]] = {
+    1: (-1, False),   # Utf8: u2 length then <length> bytes (handled specially)
+    3: (4, False),    # Integer
+    4: (4, False),    # Float
+    5: (8, True),     # Long  — takes TWO pool slots
+    6: (8, True),     # Double — takes TWO pool slots
+    7: (2, False),    # Class → name_index
+    8: (2, False),    # String
+    9: (4, False),    # Fieldref
+    10: (4, False),   # Methodref
+    11: (4, False),   # InterfaceMethodref
+    12: (4, False),   # NameAndType
+    15: (3, False),   # MethodHandle
+    16: (2, False),   # MethodType
+    17: (4, False),   # Dynamic
+    18: (4, False),   # InvokeDynamic
+    19: (2, False),   # Module
+    20: (2, False),   # Package
+}
+
+MAGIC = 0xCAFEBABE
+
+
+class NotAClassFile(ValueError):
+    pass
+
+
+class _Reader:
+    def __init__(self, data: bytes):
+        self.d = data
+        self.i = 0
+
+    def u1(self) -> int:
+        v = self.d[self.i]
+        self.i += 1
+        return v
+
+    def u2(self) -> int:
+        v = struct.unpack_from(">H", self.d, self.i)[0]
+        self.i += 2
+        return v
+
+    def u4(self) -> int:
+        v = struct.unpack_from(">I", self.d, self.i)[0]
+        self.i += 4
+        return v
+
+    def take(self, n: int) -> bytes:
+        v = self.d[self.i:self.i + n]
+        self.i += n
+        return v
+
+
+def _mutf8(b: bytes) -> str:
+    """Decode JVM "modified UTF-8" (JVMS 4.4.7): U+0000 encoded as 0xC0 0x80, supplementary chars as
+    CESU-8 surrogate pairs. A plain utf-8 decode silently corrupts both. Fast path for the ASCII/BMP
+    names that dominate; the manual walk runs only when the modified encodings are actually present."""
+    if 0xC0 not in b and 0xED not in b:
+        try:
+            return b.decode("utf-8")
+        except UnicodeDecodeError:
+            pass
+    out = []
+    i, n = 0, len(b)
+    while i < n:
+        c = b[i]
+        if c == 0xC0 and i + 1 < n and b[i + 1] == 0x80:
+            out.append("\x00"); i += 2
+        elif c < 0x80:
+            out.append(chr(c)); i += 1
+        elif c == 0xED and i + 5 < n and (b[i + 1] & 0xF0) == 0xA0:   # 6-byte CESU-8 surrogate pair
+            hi = 0xD000 | ((b[i + 1] & 0x3F) << 6) | (b[i + 2] & 0x3F)
+            lo = 0xD000 | ((b[i + 4] & 0x3F) << 6) | (b[i + 5] & 0x3F)
+            out.append(chr(0x10000 + (((hi - 0xD800) << 10) | (lo - 0xDC00)))); i += 6
+        elif 0xC0 <= c < 0xE0 and i + 1 < n:
+            out.append(chr(((c & 0x1F) << 6) | (b[i + 1] & 0x3F))); i += 2
+        elif 0xE0 <= c < 0xF0 and i + 2 < n:
+            out.append(chr(((c & 0x0F) << 12) | ((b[i + 1] & 0x3F) << 6) | (b[i + 2] & 0x3F))); i += 3
+        else:
+            out.append("�"); i += 1
+    return "".join(out)
+
+
+def _parse_constant_pool(r: _Reader) -> Dict[int, object]:
+    count = r.u2()
+    pool: Dict[int, object] = {}
+    idx = 1
+    while idx < count:
+        tag = r.u1()
+        if tag == 1:                                  # Utf8
+            length = r.u2()
+            pool[idx] = ("Utf8", _mutf8(r.take(length)))
+        elif tag == 7:                                # Class → name_index
+            pool[idx] = ("Class", r.u2())
+        elif tag in _CP_LAYOUT:
+            size, wide = _CP_LAYOUT[tag]
+            body = r.take(size)
+            pool[idx] = (tag, body)
+            if wide:
+                idx += 1                              # Long/Double occupy this slot AND the next
+        else:
+            raise NotAClassFile(f"unknown constant-pool tag {tag} at index {idx}")
+        idx += 1
+    return pool
+
+
+def _utf8(pool: Dict[int, object], index: int) -> Optional[str]:
+    v = pool.get(index)
+    return v[1] if isinstance(v, tuple) and v[0] == "Utf8" else None
+
+
+def _class_name(pool: Dict[int, object], class_index: int) -> Optional[str]:
+    v = pool.get(class_index)
+    if isinstance(v, tuple) and v[0] == "Class":
+        raw = _utf8(pool, v[1])
+        return raw.replace("/", ".") if raw else None      # internal "a/b/C" → "a.b.C"
+    return None
+
+
+def _member_symbols(r: _Reader, pool: Dict[int, object], class_name: str, kind: str) -> List[dict]:
+    out: List[dict] = []
+    count = r.u2()
+    for _ in range(count):
+        r.u2()                                        # access_flags
+        name = _utf8(pool, r.u2())
+        desc = _utf8(pool, r.u2())
+        span: Optional[Tuple[int, int]] = None
+        attr_count = r.u2()
+        for _a in range(attr_count):
+            attr_name = _utf8(pool, r.u2())
+            attr_len = r.u4()
+            body_start = r.i
+            if kind == "method" and attr_name == "Code":
+                span = _code_line_span(r, pool)
+            r.i = body_start + attr_len               # always skip by declared length (robust)
+        out.append({"name": name, "desc": desc, "kind": kind, "span": span})
+    return out
+
+
+def _code_line_span(r: _Reader, pool: Dict[int, object]) -> Optional[Tuple[int, int]]:
+    """Read a Code attribute far enough to find its LineNumberTable (optional debug info)."""
+    r.u2(); r.u2()                                    # max_stack, max_locals
+    code_len = r.u4()
+    r.i += code_len                                   # skip bytecode
+    exc_len = r.u2()
+    r.i += exc_len * 8                                # exception table
+    lines: List[int] = []
+    sub_count = r.u2()
+    for _ in range(sub_count):
+        sub_name = _utf8(pool, r.u2())
+        sub_len = r.u4()
+        start = r.i
+        if sub_name == "LineNumberTable":
+            n = r.u2()
+            for _e in range(n):
+                r.u2()                                # start_pc
+                lines.append(r.u2())                  # line_number
+        r.i = start + sub_len
+    return (min(lines), max(lines)) if lines else None
+
+
+def classfile_symbols(data: bytes):
+    """-> (class_name, [Symbol]) via enclosing.Symbol. Raises NotAClassFile on a non-class buffer."""
+    from .enclosing import FileSymbols, Symbol
+    r = _Reader(data)
+    if r.u4() != MAGIC:
+        raise NotAClassFile("bad magic (not 0xCAFEBABE)")
+    r.u2(); r.u2()                                    # minor, major version
+    pool = _parse_constant_pool(r)
+    r.u2()                                            # access_flags
+    class_name = _class_name(pool, r.u2()) or "(unknown)"
+    r.u2()                                            # super_class
+    n_ifaces = r.u2()
+    r.i += n_ifaces * 2                               # interfaces[]
+    fields = _member_symbols(r, pool, class_name, "field")
+    methods = _member_symbols(r, pool, class_name, "method")
+
+    # Disambiguate overloaded methods by appending the descriptor — keeps names UNIQUE (symgrep's ethos)
+    # only where they would collide, so the common case stays clean `Class.method`.
+    seen: Dict[str, int] = {}
+    for m in methods:
+        seen[m["name"]] = seen.get(m["name"], 0) + 1
+    syms: List[Symbol] = []
+    for m in methods:
+        base = f"{class_name}.{m['name']}"
+        name = f"{base}{m['desc']}" if seen[m["name"]] > 1 else base
+        start, end = (m["span"] if m["span"] else (0, None))
+        syms.append(Symbol(name=name, kind="method", start=start, end=end, basis="classfile"))
+    for f in fields:
+        syms.append(Symbol(name=f"{class_name}.{f['name']}", kind="field",
+                           start=0, end=None, basis="classfile"))
+    return class_name, FileSymbols(symbols=syms, basis="classfile")