adl-toolkit 0.0.0-stage → 0.1.3

package/adl_drift/lang/java/extractor.py

@@ -0,0 +1,582 @@
+"""Symbol table extractor — walks the Java CST and produces Symbol records
+(P4.2, PROBLEMS.md).
+
+Java mapping (see PROBLEMS.md P4.2 for the full writeup):
+- `method_declaration` / constructor declarations -> `Symbol(kind="function")`,
+  param types read from `formal_parameters` (Java types are mandatory, so
+  `param_types`/`return_type` are always populated, unlike Python's optional
+  annotations), plus a `signature_key` overload discriminator (P4.5).
+- `class_declaration` / `interface_declaration` / `enum_declaration` /
+  `record_declaration` -> `Symbol(kind="class")`; `superclasses` from
+  `extends`, `implements` from `implements` (P4.9).
+- `field_declaration` / `constant_declaration` -> `Symbol(kind="attribute",
+  parent=<class>)` — a direct extraction (Java has explicit field
+  declarations; no Python-style `self.X` heuristic needed). An interface
+  body spells its implicitly `public static final` fields (JLS 9.3) as
+  `constant_declaration` nodes with the same `type` + `variable_declarator`
+  shape; without them `Config DEFAULT = ...` on an interface was invisible
+  to every field-typed receiver chain (batch 25).
+- `annotation` / `marker_annotation` nodes -> decorator-equivalent strings on
+  the symbol's existing `decorators` field.
+- `import_declaration` -> `ImportRecord`, covering plain, `static`, and
+  wildcard (`*`) imports.
+
+Deliberately not implemented (no Java equivalent, per P4.2's own scope):
+`async`, and `exec`/`eval` literal-template expansion (P2.16, Python-only).
+Also deliberately not implemented here: `Symbol.is_test` — unlike Python's
+own `_looks_like_test`, JUnit/TestNG detection is P4.3's job (`lang/java/
+detectors/tests.py::JavaTestDetector`), which already owns the shared,
+provenance-checked annotation-import matching (`lang/java/type_provenance.py`).
+`Symbol.is_test` is backfilled from that detector's `java_test` pattern by
+`graph/builder.py::add_file_result`, the same way `ROUTES` patterns backfill
+`is_entry_point` — see PROBLEMS.md P4.2's "Fix applied" note. A second,
+extractor-local reimplementation previously existed here and was removed:
+it duplicated (and could silently drift from) the detector's logic.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from tree_sitter import Node
+
+from adl_drift.lang.base import ParseResult
+from adl_drift.lang.base import SymbolExtractor as _BaseSymbolExtractor
+from adl_drift.lang.java.ids import DEFAULT_PACKAGE, erased_type, signature_key
+from adl_drift.utils.types import AnalysisResult, ImportRecord, Symbol
+
+_CLASS_TYPES = (
+    "class_declaration",
+    "interface_declaration",
+    "enum_declaration",
+    "record_declaration",
+    "annotation_type_declaration",
+)
+_SCOPE_CLASS_TYPES = _CLASS_TYPES
+_CONSTRUCTOR_TYPES = ("constructor_declaration", "compact_constructor_declaration")
+_METHOD_TYPES = ("method_declaration", *_CONSTRUCTOR_TYPES)
+_ANNOTATION_TYPES = ("annotation", "marker_annotation")
+_CLASS_KEYWORD = {
+    "class_declaration": "class",
+    "interface_declaration": "interface",
+    "enum_declaration": "enum",
+    "record_declaration": "record",
+    "annotation_type_declaration": "annotation",
+}
+
+
+class JavaSymbolExtractor(_BaseSymbolExtractor):
+    """Extracts method/class/field symbols + import records from a parsed Java file."""
+
+    def _build(self, parse: ParseResult, file_path: Path) -> AnalysisResult:
+        symbols: List[Symbol] = []
+        imports: List[str] = []
+        import_records: List[ImportRecord] = []
+        seen_field_keys: set = set()  # (scope_chain, parent or "", name) — dedupe fields only;
+        # overloaded methods legitimately share this key and must NOT be deduped here (P4.5's
+        # signature_key is what disambiguates them downstream, not this pass).
+
+        anon_index = self._index_anonymous_classes(parse.tree.root_node)
+
+        for node in self._walk(parse.tree.root_node):
+            if node.type in _METHOD_TYPES:
+                sym = self._extract_method(node, parse.source_bytes, file_path, anon_index)
+                if sym:
+                    symbols.append(sym)
+            elif node.type in _CLASS_TYPES:
+                sym = self._extract_class(node, parse.source_bytes, file_path, anon_index)
+                if sym:
+                    symbols.append(sym)
+            elif self._is_anonymous_class_body(node):
+                symbols.append(self._extract_anonymous_class(
+                    node, parse.source_bytes, file_path, anon_index,
+                ))
+            elif node.type in ("field_declaration", "constant_declaration"):
+                for sym in self._extract_fields(node, parse.source_bytes, file_path, anon_index):
+                    key = self._dedupe_key(sym)
+                    if key in seen_field_keys:
+                        continue
+                    seen_field_keys.add(key)
+                    symbols.append(sym)
+            elif node.type == "import_declaration":
+                imports.append(self.parser.node_text(node, parse.source_bytes).strip())
+                import_records.extend(
+                    self._extract_import_records(node, parse.source_bytes)
+                )
+
+        return self._finalize(
+            parse,
+            file_path,
+            symbols,
+            imports,
+            import_records,
+            language="java",
+            module_name=self.module_name_from_parse(parse),
+        )
+
+    def module_name_for_file(self, file_path: Path) -> str:
+        return self.module_name_from_parse(self.parser.parse_file(file_path))
+
+    def module_name_from_parse(self, parse: ParseResult) -> str:
+        """Return the declared Java package, or a stable default-package id."""
+        for node in parse.tree.root_node.named_children:
+            if node.type != "package_declaration":
+                continue
+            for child in reversed(node.named_children):
+                if child.type in ("identifier", "scoped_identifier"):
+                    return self.parser.node_text(child, parse.source_bytes).strip()
+        return DEFAULT_PACKAGE
+
+    # -- imports ----------------------------------------------------------
+
+    def _extract_import_records(self, node: Node, source: bytes) -> List[ImportRecord]:
+        """Handles `import a.b.C;`, `import static a.b.C.m;`, and
+        `import a.b.*;` (plain or static wildcard)."""
+        is_static = any(c.type == "static" for c in node.children)
+        has_wildcard = any(c.type == "asterisk" for c in node.children)
+
+        scoped: Optional[Node] = None
+        for child in node.children:
+            if child.type in ("scoped_identifier", "identifier"):
+                scoped = child
+                break
+        if scoped is None:
+            return []
+
+        if has_wildcard:
+            return [ImportRecord(
+                module=self.parser.node_text(scoped, source),
+                name="*",
+                is_wildcard=True,
+                is_static=is_static,
+            )]
+
+        name_node = scoped.child_by_field_name("name")
+        if name_node is None:
+            # bare `import Foo;` (default-package type — legal, rare)
+            return [ImportRecord(
+                module="", name=self.parser.node_text(scoped, source), is_static=is_static,
+            )]
+        scope_node = scoped.child_by_field_name("scope")
+        module = self.parser.node_text(scope_node, source) if scope_node is not None else ""
+        return [ImportRecord(
+            module=module,
+            name=self.parser.node_text(name_node, source),
+            is_static=is_static,
+        )]
+
+    # -- methods / constructors --------------------------------------------
+
+    def _extract_method(
+        self, node: Node, source: bytes, file_path: Path, anon_index: Dict[int, int],
+    ) -> Optional[Symbol]:
+        name_node = node.child_by_field_name("name")
+        if name_node is None:
+            return None
+        name = self.parser.node_text(name_node, source)
+        params_node = self._method_parameters(node)
+        param_types = self._extract_param_types(params_node, source) if params_node else {}
+        params_text = self.parser.node_text(params_node, source) if params_node else "()"
+
+        return_type_node = node.child_by_field_name("type")  # absent for constructors
+        return_type = (
+            self.parser.node_text(return_type_node, source).strip() if return_type_node else None
+        )
+        return_dims = node.child_by_field_name("dimensions")
+        if return_dims is not None and return_type is not None:
+            return_type += self.parser.node_text(return_dims, source).strip()
+        signature = f"{return_type} {name}{params_text}" if return_type else f"{name}{params_text}"
+
+        decorators = self._extract_annotations(node, source)
+        parent = self._find_parent_class(node, source, anon_index)
+        scope_chain = self._scope_chain(node, source, anon_index)
+        modifiers = self._extract_modifiers(node, source)
+
+        # Persist static-ness into metadata (not just `modifiers`): the graph
+        # builder copies `symbol.metadata` onto the GraphNode but drops
+        # `symbol.modifiers`, so the resolver — which sees only GraphNodes —
+        # can read `java_is_static` but never `modifiers`. Needed so the
+        # static-import call path can reject an equally-named *instance*
+        # method that `import static a.b.C.name;` cannot legally bind (F-02).
+        metadata: Dict[str, object] = (
+            {"constructor": True} if node.type in _CONSTRUCTOR_TYPES else {}
+        )
+        metadata["java_is_static"] = "static" in modifiers
+        # P4.12 abstract-dispatch fan-out needs to tell an *abstract* method
+        # (interface method with no body, or `abstract`-modified method on an
+        # abstract class — the receiver whose runtime target is unknown) from a
+        # concrete one. `native` methods also have no Java body, but still have
+        # a valid runtime target, so they must keep their direct edge.
+        # `java_return_type` is persisted for the same issue's `@Bean`
+        # factory-method bean index (a `@Bean T make()` registers `T` as an
+        # injectable candidate — see the resolver).
+        metadata["java_is_abstract"] = self._is_java_abstract_method(node, modifiers)
+        if return_type is not None:
+            metadata["java_return_type"] = return_type
+
+        return Symbol(
+            name=name,
+            kind="function",
+            file_path=file_path,
+            position=self.parser.node_position(node),
+            decorators=decorators,
+            signature=signature,
+            parent=parent,
+            param_types=param_types,
+            return_type=return_type,
+            throws=self._extract_throws(node, source),
+            modifiers=modifiers,
+            scope_chain=scope_chain,
+            signature_key=signature_key(param_types.values()),
+            metadata=metadata,
+        )
+
+    @staticmethod
+    def _is_java_abstract_method(node: Node, modifiers: List[str]) -> bool:
+        if node.type != "method_declaration":
+            return False
+        if node.child_by_field_name("body") is not None:
+            return False
+        if "native" in modifiers:
+            return False
+        if "abstract" in modifiers:
+            return True
+
+        parent = node.parent
+        while parent is not None:
+            if parent.type in (
+                "class_declaration",
+                "interface_declaration",
+                "enum_declaration",
+                "record_declaration",
+                "annotation_type_declaration",
+            ):
+                return parent.type in ("interface_declaration", "annotation_type_declaration")
+            parent = parent.parent
+        return False
+
+    @staticmethod
+    def _method_parameters(node: Node) -> Optional[Node]:
+        params = node.child_by_field_name("parameters")
+        if params is not None or node.type != "compact_constructor_declaration":
+            return params
+        record = node.parent.parent if node.parent is not None else None
+        if record is not None and record.type == "record_declaration":
+            return record.child_by_field_name("parameters")
+        return None
+
+    def _extract_param_types(self, params_node: Node, source: bytes) -> Dict[str, str]:
+        """Walk `formal_parameters` children, return {param_name: type_text}.
+
+        Handles plain `formal_parameter` and varargs `spread_parameter`
+        (`String... args` -> type text `String...`, which `ids.erased_type`
+        normalizes to `String[]`).
+        """
+        out: Dict[str, str] = {}
+        for child in params_node.children:
+            if child.type == "formal_parameter":
+                type_node = child.child_by_field_name("type")
+                name_node = child.child_by_field_name("name")
+                if type_node is not None and name_node is not None:
+                    type_text = self.parser.node_text(type_node, source).strip()
+                    dimensions = child.child_by_field_name("dimensions")
+                    if dimensions is not None:
+                        type_text += self.parser.node_text(dimensions, source).strip()
+                    out[self.parser.node_text(name_node, source)] = type_text
+            elif child.type == "spread_parameter":
+                type_parts: List[str] = []
+                var_decl: Optional[Node] = None
+                for sub in child.children:
+                    if sub.type == "variable_declarator":
+                        var_decl = sub
+                    elif sub.type == "modifiers":
+                        continue
+                    else:
+                        type_parts.append(self.parser.node_text(sub, source))
+                if var_decl is not None:
+                    name_node = var_decl.child_by_field_name("name")
+                    if name_node is not None:
+                        out[self.parser.node_text(name_node, source)] = "".join(type_parts).strip()
+        return out
+
+    # -- classes / interfaces / enums / records ----------------------------
+
+    def _extract_class(
+        self, node: Node, source: bytes, file_path: Path, anon_index: Dict[int, int]
+    ) -> Optional[Symbol]:
+        name_node = node.child_by_field_name("name")
+        if name_node is None:
+            return None
+        name = self.parser.node_text(name_node, source)
+        decorators = self._extract_annotations(node, source)
+        parent = self._find_parent_class(node, source, anon_index)
+        scope_chain = self._scope_chain(node, source, anon_index)
+        superclasses_raw = self._extract_superclasses(node, source)
+        implements_raw = self._extract_implements(node, source)
+        modifiers = self._extract_modifiers(node, source)
+
+        metadata: Dict[str, Any] = {"java_type_kind": _CLASS_KEYWORD[node.type]}
+        if node.type == "enum_declaration":
+            body = node.child_by_field_name("body")
+            metadata["enum_constants"] = [
+                self.parser.node_text(name_node, source)
+                for child in (body.children if body is not None else [])
+                if child.type == "enum_constant"
+                for name_node in [child.child_by_field_name("name")]
+                if name_node is not None
+            ]
+        # `Symbol.superclasses`/`implements` feed the shared, language-agnostic
+        # `graph/builder.py::resolve_relationships` INHERITS/IMPLEMENTS lookup,
+        # which expects a plain declared name the same way the Python
+        # extractor's own `_extract_superclasses` already reduces `Generic[T]`
+        # to `Generic` — an un-erased `Box<Stripe>` never matches the by-name
+        # index there, so the edge (and everything built on it: ancestor
+        # method lookup, OVERRIDES, P4.12's fan-out/DI narrowing) was silently
+        # never created for any class with a parameterized supertype. The raw,
+        # generic-preserving text is kept separately in metadata for
+        # `lang/java/resolver.py`'s generic-return-through-inheritance
+        # substitution (F-01), which is the one place that argument text is
+        # still needed.
+        try:
+            superclasses = [erased_type(s) for s in superclasses_raw]
+            implements = [erased_type(s) for s in implements_raw]
+        except ValueError:
+            superclasses, implements = superclasses_raw, implements_raw
+        metadata["java_superclass_args"] = superclasses_raw
+        metadata["java_implements_args"] = implements_raw
+        # P4.12: a receiver typed as an interface *or* an `abstract class` has
+        # an unknown runtime implementation and drives the fan-out; a plain
+        # concrete class does not. `interface` is already covered by
+        # `java_type_kind`; `abstract` on a class needs its own flag.
+        metadata["java_is_abstract"] = "abstract" in modifiers
+        if node.type == "record_declaration":
+            # Records have an implicit canonical constructor whose arity
+            # equals the component count — resolver._resolve_constructor
+            # (P4.4 P1 fix) needs this to reject calls with the wrong
+            # argument count instead of accepting any `new Point(...)`.
+            params_node = node.child_by_field_name("parameters")
+            if params_node is not None:
+                components = self._extract_param_types(params_node, source)
+                metadata["record_component_types"] = list(components.values())
+                metadata["record_components"] = dict(components)
+            else:
+                metadata["record_component_types"] = []
+                metadata["record_components"] = {}
+
+        return Symbol(
+            name=name,
+            kind="class",
+            file_path=file_path,
+            position=self.parser.node_position(node),
+            decorators=decorators,
+            signature=f"{_CLASS_KEYWORD[node.type]} {name}",
+            parent=parent,
+            superclasses=superclasses,
+            implements=implements,
+            modifiers=modifiers,
+            scope_chain=scope_chain,
+            metadata=metadata,
+        )
+
+    def _extract_anonymous_class(
+        self, node: Node, source: bytes, file_path: Path, anon_index: Dict[int, int],
+    ) -> Symbol:
+        """Materialize the synthetic owner already used by anonymous members.
+
+        Methods and fields inside an anonymous class carry a `$N` scope segment.
+        Without a matching CLASS node their CONTAINS edge is structurally
+        dangling even though call resolution remains possible.
+        """
+        name = f"${anon_index[node.start_byte]}"
+        return Symbol(
+            name=name,
+            kind="class",
+            file_path=file_path,
+            position=self.parser.node_position(node),
+            signature=f"anonymous class {name}",
+            parent=self._find_parent_class(node, source, anon_index),
+            scope_chain=self._scope_chain(node, source, anon_index),
+            metadata={"java_type_kind": "anonymous", "synthetic": "anonymous_class"},
+        )
+
+    def _extract_type_list(self, node: Node, source: bytes) -> List[str]:
+        """Collect raw type text from a `type_list` (or a single bare type
+        child, e.g. a class's single `extends Base`)."""
+        out: List[str] = []
+        for child in node.children:
+            if child.type == "type_list":
+                out.extend(self._extract_type_list(child, source))
+            elif child.type in ("type_identifier", "scoped_type_identifier", "generic_type"):
+                out.append(self.parser.node_text(child, source).strip())
+        return out
+
+    def _extract_superclasses(self, node: Node, source: bytes) -> List[str]:
+        """`extends Base` on a class (field `superclass`) or `extends A, B`
+        on an interface (positional `extends_interfaces` — interfaces permit
+        multiple, so it isn't a named single-value field like `superclass`)."""
+        superclass_node = node.child_by_field_name("superclass")
+        if superclass_node is not None:
+            return self._extract_type_list(superclass_node, source)
+        for child in node.children:
+            if child.type == "extends_interfaces":
+                return self._extract_type_list(child, source)
+        return []
+
+    def _extract_implements(self, node: Node, source: bytes) -> List[str]:
+        interfaces_node = node.child_by_field_name("interfaces")
+        if interfaces_node is None:
+            return []
+        return self._extract_type_list(interfaces_node, source)
+
+    # -- fields --------------------------------------------------------------
+
+    def _extract_fields(
+        self, node: Node, source: bytes, file_path: Path, anon_index: Dict[int, int]
+    ) -> List[Symbol]:
+        type_node = node.child_by_field_name("type")
+        base_type_text = self.parser.node_text(type_node, source).strip() if type_node else None
+        decorators = self._extract_annotations(node, source)
+        modifiers = self._extract_modifiers(node, source)
+        parent = self._find_parent_class(node, source, anon_index)
+        scope_chain = self._scope_chain(node, source, anon_index)
+
+        out: List[Symbol] = []
+        for child in node.children:
+            if child.type != "variable_declarator":
+                continue
+            name_node = child.child_by_field_name("name")
+            if name_node is None:
+                continue
+            type_text = base_type_text
+            dimensions = child.child_by_field_name("dimensions")
+            if dimensions is not None and type_text is not None:
+                type_text += self.parser.node_text(dimensions, source).strip()
+            out.append(Symbol(
+                name=self.parser.node_text(name_node, source),
+                kind="attribute",
+                file_path=file_path,
+                position=self.parser.node_position(child),
+                decorators=decorators,
+                signature=type_text,
+                parent=parent,
+                modifiers=modifiers,
+                scope_chain=scope_chain,
+            ))
+        return out
+
+    # -- annotations (decorator-equivalent) -----------------------------------
+
+    def _extract_annotations(self, node: Node, source: bytes) -> List[str]:
+        modifiers_node: Optional[Node] = None
+        for child in node.children:
+            if child.type == "modifiers":
+                modifiers_node = child
+                break
+        if modifiers_node is None:
+            return []
+        return [
+            self.parser.node_text(child, source).strip()
+            for child in modifiers_node.children
+            if child.type in _ANNOTATION_TYPES
+        ]
+
+    def _extract_modifiers(self, node: Node, source: bytes) -> List[str]:
+        for child in node.children:
+            if child.type == "modifiers":
+                return [
+                    self.parser.node_text(part, source).strip()
+                    for part in child.children
+                    if part.type not in _ANNOTATION_TYPES and not part.is_extra
+                ]
+        return []
+
+    def _extract_throws(self, node: Node, source: bytes) -> List[str]:
+        for child in node.children:
+            if child.type == "throws":
+                return [
+                    self.parser.node_text(exception, source).strip()
+                    for exception in child.named_children
+                    if not exception.is_extra
+                ]
+        return []
+
+    # -- scope chain: nested/inner/local/anonymous classes --------------------
+
+    def _index_anonymous_classes(self, root: Node) -> Dict[int, int]:
+        """Assign anonymous class bodies an ordinal within their callable.
+
+        Enum constants share their enclosing enum as the scope. This keeps
+        IDs stable when an unrelated earlier callable gains an anonymous
+        class while still distinguishing enum-constant subclasses.
+        """
+        index: Dict[int, int] = {}
+        counts: Dict[int, int] = {}
+        for node in self._walk(root):
+            if not self._is_anonymous_class_body(node):
+                continue
+            owner = node.parent
+            while owner is not None:
+                if owner.type in _METHOD_TYPES or owner.type in _CLASS_TYPES:
+                    break
+                owner = owner.parent
+            owner_start = owner.start_byte if owner is not None else root.start_byte
+            counts[owner_start] = counts.get(owner_start, 0) + 1
+            index[node.start_byte] = counts[owner_start]
+        return index
+
+    @staticmethod
+    def _is_anonymous_class_body(node: Node) -> bool:
+        return node.type == "class_body" and node.parent is not None \
+            and node.parent.type in ("object_creation_expression", "enum_constant")
+
+    def _scope_chain(
+        self, node: Node, source: bytes, anon_index: Dict[int, int]
+    ) -> List[str]:
+        """Java's own scope chain (P2.17/P1.10's `<locals>` semantics don't
+        apply): nested/inner/static-nested classes contribute their name;
+        a local class's enclosing method also contributes its name (methods
+        can't nest in Java, so a method only ever shows up here when it
+        encloses a local or anonymous class); an anonymous class contributes
+        a synthetic `$N` segment. `symbol.parent` (nearest enclosing
+        class-like ancestor) stays the separate, coarser field used for
+        display/self-reference; this is the uniqueness key."""
+        chain: List[str] = []
+        p = node.parent
+        while p is not None:
+            if p.type in _SCOPE_CLASS_TYPES:
+                nn = p.child_by_field_name("name")
+                if nn is not None:
+                    chain.append(self.parser.node_text(nn, source))
+            elif p.type in _METHOD_TYPES:
+                nn = p.child_by_field_name("name")
+                if nn is not None:
+                    params = self._method_parameters(p)
+                    param_types = self._extract_param_types(params, source) if params else {}
+                    discriminator = signature_key(param_types.values())
+                    if p.type in _CONSTRUCTOR_TYPES:
+                        chain.append(discriminator)
+                    else:
+                        chain.append(self.parser.node_text(nn, source) + discriminator)
+            elif self._is_anonymous_class_body(p):
+                chain.append(f"${anon_index[p.start_byte]}")
+            p = p.parent
+        chain.reverse()
+        return chain
+
+    def _find_parent_class(
+        self, node: Node, source: bytes, anon_index: Dict[int, int]
+    ) -> Optional[str]:
+        """Nearest enclosing class-like ancestor's name (real or synthetic
+        anonymous-class segment), skipping over intervening methods —
+        mirrors `lang.python.extractor`'s `_find_parent_class`."""
+        p = node.parent
+        while p is not None:
+            if p.type in _SCOPE_CLASS_TYPES:
+                nn = p.child_by_field_name("name")
+                if nn is not None:
+                    return self.parser.node_text(nn, source)
+            elif self._is_anonymous_class_body(p):
+                return f"${anon_index[p.start_byte]}"
+            p = p.parent
+        return None

package/adl_drift/lang/java/ids.py

@@ -0,0 +1,99 @@
+"""Java overload identity helpers (P4.5).
+
+Kept parser-free so P4.1 and P4.2 can use it independently.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from functools import lru_cache
+
+
+DEFAULT_PACKAGE = "<default>"
+
+
+_TYPE_ANNOTATION = re.compile(r"@[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*")
+
+
+def _strip_type_annotations(text: str) -> str:
+    """Remove Java type-use annotations, including nested/quoted arguments."""
+    out: list[str] = []
+    i = 0
+    while i < len(text):
+        match = _TYPE_ANNOTATION.match(text, i)
+        if match is None:
+            out.append(text[i])
+            i += 1
+            continue
+
+        i = match.end()
+        while i < len(text) and text[i].isspace():
+            i += 1
+        if i < len(text) and text[i] == "(":
+            depth = 0
+            quote: str | None = None
+            escaped = False
+            while i < len(text):
+                char = text[i]
+                i += 1
+                if quote:
+                    if escaped:
+                        escaped = False
+                    elif char == "\\":
+                        escaped = True
+                    elif char == quote:
+                        quote = None
+                elif char in ('"', "'"):
+                    quote = char
+                elif char == "(":
+                    depth += 1
+                elif char == ")":
+                    depth -= 1
+                    if depth == 0:
+                        break
+            if depth:
+                raise ValueError(f"unbalanced type annotation: {text!r}")
+            while i < len(text) and text[i].isspace():
+                i += 1
+    return "".join(out)
+
+
+@lru_cache(maxsize=None)
+def erased_type(type_text: str) -> str:
+    """Return stable source-level Java type erasure for node identity.
+
+    Pure function of `type_text` alone (no graph/analysis state), so caching
+    is unconditionally safe and unbounded cache growth is bounded in
+    practice by the number of distinct type-strings in a corpus (thousands,
+    not millions). Memoized because the same handful of type strings
+    ("String", "int", "List<String>", ...) recur millions of times across a
+    large corpus's overload/param-type matching (§8 bước 7 profiling: 3.25M
+    calls on JUnit5, ~9% of resolve_calls time between this and its helper
+    `_strip_type_annotations`, which this is the only caller of).
+    """
+    text = _strip_type_annotations(type_text.strip())
+    out: list[str] = []
+    depth = 0
+    for char in text:
+        if char == "<":
+            depth += 1
+        elif char == ">":
+            depth -= 1
+            if depth < 0:
+                raise ValueError(f"unbalanced generic type: {type_text!r}")
+        elif depth == 0:
+            out.append(char)
+    if depth:
+        raise ValueError(f"unbalanced generic type: {type_text!r}")
+
+    erased = "".join(out).replace("...", "[]")
+    erased = "".join(erased.split())
+    if not erased:
+        raise ValueError("Java type cannot be empty")
+    return erased
+
+
+def signature_key(parameter_types: Iterable[str]) -> str:
+    """Return erased overload suffix, e.g. ``(String,int[])``."""
+    return f"({','.join(erased_type(t) for t in parameter_types)})"