adl-toolkit 0.0.0-stage → 0.1.1

package/adl_drift/lang/java/resolution/dispatch.py

@@ -0,0 +1,540 @@
+"""Abstract dispatch fan-out and Spring dependency-injection narrowing."""
+
+from __future__ import annotations
+
+import re
+from typing import Dict, List, Optional, Set, Tuple, Union
+
+from adl_drift.graph.node import NodeType
+from adl_drift.lang.java.ids import DEFAULT_PACKAGE
+from adl_drift.lang.java.resolution.constants import (
+    JAVA_COMPONENT_ANNOTATIONS,
+    JAVA_DI_ANNOTATION_FQNS,
+    JAVA_INJECTION_ANNOTATIONS,
+    _ANNOTATION_STRING_ARG,
+    _CONCRETE_TYPE_KINDS,
+    _CONF_DI_SINGLE_COMPONENT,
+    _CONF_MULTI_IMPLEMENTOR,
+    _CONF_SINGLE_IMPLEMENTOR,
+    _CONF_SPRING_PRIMARY,
+    _CONF_SPRING_QUALIFIER,
+    _MOCK_ALLOCATION_TYPE,
+)
+from adl_drift.lang.java.resolution.model import (
+    BeanCandidate as _BeanCandidate,
+    DINarrowResult as _DINarrowResult,
+)
+
+class DispatchMixin:
+    def _is_concrete_class(self, class_id: str) -> bool:
+        """True iff `class_id` is a concrete type able to carry a runtime
+        method body — a `class`/`record`/`enum` that is not `abstract`. An
+        interface or `abstract class` is the *source* of dispatch ambiguity,
+        never a fan-out target."""
+        node = self.builder._nodes.get(class_id)
+        if node is None or node.node_type != NodeType.CLASS:
+            return False
+        kind = node.metadata.get("java_type_kind")
+        if kind not in _CONCRETE_TYPE_KINDS:
+            return False
+        return not bool(node.metadata.get("java_is_abstract", False))
+
+    def _is_abstract_method(self, func_id: str) -> bool:
+        node = self.builder._nodes.get(func_id)
+        return bool(node is not None and node.metadata.get("java_is_abstract", False))
+
+    def _is_abstract_target(self, target: Union[str, List[str]]) -> bool:
+        """True iff the P4.4-resolved target is (entirely) an abstract method —
+        the signal that a concrete runtime implementation is elsewhere. A list
+        target (an unresolved interface-level overload tie) counts only when
+        *every* candidate is abstract, so a mixed tie with a concrete default
+        keeps its direct edges."""
+        ids = target if isinstance(target, list) else [target]
+        return bool(ids) and all(self._is_abstract_method(t) for t in ids)
+
+    def _abstract_fan_out(
+        self, recv_class_id: str, resolved_target: Union[str, List[str]],
+        method_name: str, arg_count: int, arg_types: Optional[List[str]],
+        caller_ctx: "_ImportContext", obj_node, source: bytes,
+        enclosing_class_id: Optional[str], own_param_types: Dict[str, str],
+        local_types: "_LocalScopes",
+    ) -> Optional[Tuple[Union[str, List[str]], float, Dict[str, object]]]:
+        """The abstract-receiver branch (deep-dive §6.3). Returns a
+        `(target(s), confidence, metadata)` triple that *replaces* the P4.4
+        interface-method edge, or None to keep it (strict mode, a concrete
+        target, or zero concrete implementors — precision-first: never flood).
+
+        Order of evidence, strongest first: Spring DI narrowing off the
+        receiver field's injection annotations, then the raw implementor
+        fan-out (single implementor -> high; many -> low). The precision↔recall
+        dial (`self._fanout_mode`) governs the raw fan-out: `strict` keeps only
+        the interface edge, `balanced` caps emission above `self._fanout_cap`,
+        `recall` emits every implementor."""
+        if not self._is_abstract_target(resolved_target):
+            return None
+        if self._fanout_mode == "strict":
+            return None
+
+        # 1. Exact local allocation. Keep the declared receiver type for
+        # static resolution; use Interface x = new Impl() only to narrow the
+        # runtime expansion. Evidence expires at the first reassignment.
+        if obj_node.type == "identifier":
+            local_name = self._text(obj_node, source)
+            allocation_type = local_types.allocation_type_at(
+                local_name, obj_node.start_byte,
+            )
+            if allocation_type == _MOCK_ALLOCATION_TYPE:
+                # A Mockito mock/spy has no real declared implementation to
+                # dispatch to — keep the honest abstract-declaration edge
+                # rather than guessing an unrelated project class that
+                # happens to implement the same interface (P5 finding #2).
+                return None
+            if allocation_type is not None:
+                allocation_class_id = self._resolve_declared_type(
+                    allocation_type, caller_ctx.module, caller_ctx.import_map,
+                    caller_ctx.wildcard_packages, enclosing_class_id,
+                )
+                if (
+                    allocation_class_id is not None
+                    and self._is_concrete_class(allocation_class_id)
+                    and (
+                        allocation_class_id == recv_class_id
+                        or recv_class_id in self._class_ancestors(allocation_class_id)
+                    )
+                ):
+                    allocation_target, _ = self._resolve_own_or_ancestor(
+                        allocation_class_id, method_name, arg_count, arg_types,
+                        _CONF_SINGLE_IMPLEMENTOR, _CONF_SINGLE_IMPLEMENTOR,
+                        caller_ctx,
+                    )
+                    if (
+                        isinstance(allocation_target, str)
+                        and not self._is_abstract_method(allocation_target)
+                    ):
+                        recv_node = self.builder._nodes.get(recv_class_id)
+                        declared = (
+                            recv_node.name if recv_node is not None else recv_class_id
+                        )
+                        return allocation_target, _CONF_SINGLE_IMPLEMENTOR, {
+                            "declared_receiver_type": declared,
+                            "strategy": "single_implementor",
+                            "allocation_narrowed": True,
+                        }
+
+        # 2. Unanimous own-class field allocation. This never consults
+        # sibling subclasses, so an inherited polymorphic test fixture keeps
+        # its full runtime expansion.
+        field_name: Optional[str] = None
+        if enclosing_class_id is not None:
+            if obj_node.type == "identifier":
+                candidate = self._text(obj_node, source)
+                if (
+                    local_types.type_at(candidate, obj_node.start_byte) is None
+                    and candidate not in own_param_types
+                    and candidate in self._all_field_types(enclosing_class_id)
+                ):
+                    field_name = candidate
+            elif obj_node.type == "field_access":
+                inner = obj_node.child_by_field_name("object")
+                field = obj_node.child_by_field_name("field")
+                if inner is not None and inner.type == "this" and field is not None:
+                    field_name = self._text(field, source)
+        field_allocation_id = (
+            self._field_allocation_types.get(enclosing_class_id, {}).get(field_name)
+            if enclosing_class_id is not None and field_name is not None else None
+        )
+        if field_allocation_id == _MOCK_ALLOCATION_TYPE:
+            # Same fact as step 1, for a field-declared mock/spy receiver
+            # (`ConfigurationParameters configParams = mock();`).
+            return None
+        if (
+            field_allocation_id is not None
+            and self._is_concrete_class(field_allocation_id)
+            and (
+                field_allocation_id == recv_class_id
+                or recv_class_id in self._class_ancestors(field_allocation_id)
+            )
+        ):
+            field_target, _ = self._resolve_own_or_ancestor(
+                field_allocation_id, method_name, arg_count, arg_types,
+                _CONF_SINGLE_IMPLEMENTOR, _CONF_SINGLE_IMPLEMENTOR, caller_ctx,
+            )
+            if isinstance(field_target, str) and not self._is_abstract_method(field_target):
+                recv_node = self.builder._nodes.get(recv_class_id)
+                declared = recv_node.name if recv_node is not None else recv_class_id
+                return field_target, _CONF_SINGLE_IMPLEMENTOR, {
+                    "declared_receiver_type": declared,
+                    "strategy": "single_implementor",
+                    "field_allocation_narrowed": True,
+                }
+
+        # 3. Spring DI narrowing (only meaningful for an injected field).
+        field_node_id = self._receiver_field_node_id(
+            obj_node, source, enclosing_class_id, local_types, own_param_types,
+        )
+        if field_node_id is not None and self._is_injected_field(field_node_id):
+            di = self._di_narrow(
+                recv_class_id, field_node_id, method_name, arg_count, arg_types, caller_ctx,
+            )
+            if di is not None:
+                if di.target is None:
+                    return None
+                recv_node = self.builder._nodes.get(recv_class_id)
+                declared = recv_node.name if recv_node is not None else recv_class_id
+                return di.target, di.confidence, {
+                    "declared_receiver_type": declared, "strategy": di.strategy,
+                }
+
+        # 4. Raw implementor fan-out.
+        return self._raw_implementor_fan_out(
+            recv_class_id, method_name, arg_count, arg_types, caller_ctx,
+        )
+
+    def _raw_implementor_fan_out(
+        self, recv_class_id: str, method_name: str, arg_count: int,
+        arg_types: Optional[List[str]], caller_ctx: "_ImportContext",
+    ) -> Optional[Tuple[Union[str, List[str]], float, Dict[str, object]]]:
+        """The mode-gated raw implementor fan-out, shared by the typed-receiver
+        branch (via `_abstract_fan_out`, after DI narrowing) and the `this`/bare
+        + `super` branches (which have no injectable field, so they call this
+        directly). Resolves `method_name` on every concrete subtype of
+        `recv_class_id` and returns `(target(s), confidence, metadata)`, or None
+        to keep the honest abstract-declaration edge: `strict` mode, zero
+        concrete implementors, or — in `balanced` mode — more implementors than
+        `self._fanout_cap` (precision-first: never flood blast radius). Metadata
+        carries `declared_receiver_type` + `strategy` so impact/MCP can explain
+        the fanned-out edges (deep-dive §8.4). Callers must have already
+        established the resolved target is abstract (`_is_abstract_target`)."""
+        if self._fanout_mode == "strict":
+            return None
+        recv_node = self.builder._nodes.get(recv_class_id)
+        declared = recv_node.name if recv_node is not None else recv_class_id
+        base_meta: Dict[str, object] = {"declared_receiver_type": declared}
+        targets = self._fan_out_implementors(
+            recv_class_id, method_name, arg_count, arg_types, caller_ctx,
+        )
+        if not targets:
+            return None  # interface-only: keep the honest declaration edge.
+        telemetry = getattr(self, "fanout_telemetry", None)
+        if isinstance(telemetry, dict):
+            telemetry.setdefault("candidate_counts", []).append(len(targets))
+        if len(targets) == 1:
+            if isinstance(telemetry, dict):
+                telemetry.setdefault("emitted_counts", []).append(1)
+            return targets[0], _CONF_SINGLE_IMPLEMENTOR, {
+                **base_meta, "strategy": "single_implementor",
+            }
+        if self._fanout_mode == "balanced" and len(targets) > self._fanout_cap:
+            # Precision-first: too many implementors to name honestly — keep
+            # the single interface edge rather than flooding blast radius.
+            if isinstance(telemetry, dict):
+                telemetry["cap_skipped"] = int(telemetry.get("cap_skipped", 0)) + 1
+                telemetry.setdefault("emitted_counts", []).append(0)
+            return None
+        if isinstance(telemetry, dict):
+            telemetry.setdefault("emitted_counts", []).append(len(targets))
+        return targets, _CONF_MULTI_IMPLEMENTOR, {
+            **base_meta, "strategy": "interface_fanout",
+        }
+
+    def _fan_out_implementors(
+        self, root_class_id: str, method_name: str, arg_count: int,
+        arg_types: Optional[List[str]], caller_ctx: "_ImportContext",
+    ) -> List[str]:
+        """Ordered, de-duplicated concrete method targets for the fan-out: for
+        every concrete transitive subtype of `root_class_id` (interface or
+        abstract class), resolve `method_name` on that subtype the normal P4.4
+        way and collect the concrete override it lands on. A subtype that does
+        not resolve the method (or resolves it only to another abstract
+        declaration) contributes nothing — never a guess."""
+        targets: List[str] = []
+        seen: Set[str] = set()
+        for impl in sorted(self._subtypes.get(root_class_id, ())):
+            if not self._is_concrete_class(impl):
+                continue
+            mt, _ = self._resolve_own_or_ancestor(
+                impl, method_name, arg_count, arg_types,
+                _CONF_SINGLE_IMPLEMENTOR, _CONF_SINGLE_IMPLEMENTOR, caller_ctx,
+            )
+            for tid in (mt if isinstance(mt, list) else [mt] if mt else []):
+                if tid in seen or self._is_abstract_method(tid):
+                    continue
+                seen.add(tid)
+                targets.append(tid)
+        return targets
+
+    # -- DI narrowing (Spring) ------------------------------------------------
+
+    def _receiver_field_node_id(
+        self, obj_node, source: bytes, enclosing_class_id: Optional[str],
+        local_types: "_LocalScopes", param_types: Dict[str, str],
+    ) -> Optional[str]:
+        """The VARIABLE node id of the field a receiver reads, when the receiver
+        is genuinely a field of the enclosing class — a bare `field` identifier
+        that is neither a local nor a parameter, or an explicit `this.field`.
+        Anything else (a local, a parameter, a static-class receiver, a chained
+        expression) is not an injectable field and returns None."""
+        if enclosing_class_id is None:
+            return None
+        field_name: Optional[str] = None
+        if obj_node.type == "identifier":
+            name = self._text(obj_node, source)
+            if local_types.type_at(name, obj_node.start_byte) is not None:
+                return None  # a local, not a field
+            if name in param_types:
+                return None  # a parameter, not a field
+            field_name = name
+        elif obj_node.type == "field_access":
+            inner = obj_node.child_by_field_name("object")
+            field_node = obj_node.child_by_field_name("field")
+            if inner is not None and inner.type == "this" and field_node is not None:
+                field_name = self._text(field_node, source)
+        if field_name is None:
+            return None
+        return self._all_field_node_ids(enclosing_class_id).get(field_name)
+
+    def _all_field_node_ids(self, class_id: str) -> Dict[str, str]:
+        """`{field_name: field VARIABLE node id}` for `class_id` merged with
+        every ancestor's fields, nearer declarations winning — the node-id
+        analogue of `_all_field_types` (an injected field may be declared on a
+        base class)."""
+        merged: Dict[str, str] = {}
+        for anc in reversed(self._class_ancestors(class_id)):
+            merged.update(self._field_nodes.get(anc, {}))
+        merged.update(self._field_nodes.get(class_id, {}))
+        return merged
+
+    def _is_injected_field(self, field_node_id: str) -> bool:
+        node = self.builder._nodes.get(field_node_id)
+        if node is None:
+            return False
+        return field_node_id in self._di_injected_fields or any(
+            self._di_annotation_simple_name(d, node.file_path) in JAVA_INJECTION_ANNOTATIONS
+            for d in node.decorators
+        )
+
+    def _field_qualifier(self, field_node_id: str) -> Optional[str]:
+        """The `@Qualifier("name")` (or `@Resource(name="…")`-style single
+        string arg) requested on an injected field, or None."""
+        node = self.builder._nodes.get(field_node_id)
+        if node is None:
+            return None
+        for deco in node.decorators:
+            simple = self._di_annotation_simple_name(deco, node.file_path)
+            if simple == "Resource":
+                named = self._annotation_named_string_arg(deco, "name")
+                if named:
+                    return named
+                return node.name
+        direct = self._qualifier_from_decorators(node.decorators, node.file_path)
+        if direct:
+            return direct
+        injected = self._di_injected_fields.get(field_node_id)
+        if injected is not None:
+            return injected.qualifier
+        return None
+
+    def _qualifier_from_decorators(
+        self, decorators: List[str], file_path: str,
+    ) -> Optional[str]:
+        for deco in decorators:
+            simple = self._di_annotation_simple_name(deco, file_path)
+            if simple == "Qualifier":
+                arg = self._annotation_string_arg(deco)
+                if arg:
+                    return arg
+            elif simple == "Resource":
+                arg = self._annotation_named_string_arg(deco, "name")
+                if arg:
+                    return arg
+        return None
+
+    def _di_narrow(
+        self, interface_id: str, field_node_id: str, method_name: str,
+        arg_count: int, arg_types: Optional[List[str]], caller_ctx: "_ImportContext",
+    ) -> Optional[_DINarrowResult]:
+        """Narrow an injected interface field to one concrete Spring bean
+        (deep-dive §7.3). Returns a target when the evidence names exactly one
+        bean — a matching `@Qualifier` (0.95), a sole `@Component`-family
+        implementor (0.85), or a `@Primary` among several (0.90). An explicit
+        but unresolved/ambiguous qualifier returns a blocked result so callers
+        do not fall back to unrelated DI rules."""
+        candidates = self._bean_candidates(interface_id)
+        if not candidates:
+            return None
+        qualifier = self._field_qualifier(field_node_id)
+        if qualifier is not None:
+            matches = [
+                c for c in candidates
+                if qualifier in c.qualifiers or c.bean_name == qualifier
+            ]
+            if len(matches) == 1:
+                tgt = self._resolve_bean_method(
+                    matches[0], method_name, arg_count, arg_types, caller_ctx,
+                )
+                if tgt is not None:
+                    return _DINarrowResult(
+                        tgt, _CONF_SPRING_QUALIFIER, "spring_qualifier",
+                    )
+            if len(matches) == 0:
+                return _DINarrowResult(None, 0.0, "spring_qualifier_unresolved")
+            return _DINarrowResult(None, 0.0, "spring_qualifier_ambiguous")
+        if len(candidates) == 1:
+            tgt = self._resolve_bean_method(
+                candidates[0], method_name, arg_count, arg_types, caller_ctx,
+            )
+            if tgt is not None:
+                return _DINarrowResult(
+                    tgt, _CONF_DI_SINGLE_COMPONENT, "di_single_component",
+                )
+        primaries = [c for c in candidates if c.primary]
+        if len(primaries) == 1:
+            tgt = self._resolve_bean_method(
+                primaries[0], method_name, arg_count, arg_types, caller_ctx,
+            )
+            if tgt is not None:
+                return _DINarrowResult(tgt, _CONF_SPRING_PRIMARY, "spring_primary")
+        return None
+
+    def _resolve_bean_method(
+        self, bean: "_BeanCandidate", method_name: str, arg_count: int,
+        arg_types: Optional[List[str]], caller_ctx: "_ImportContext",
+    ) -> Optional[str]:
+        """Resolve `method_name` on a bean's concrete type to a single method
+        node id (None if it does not resolve to exactly one concrete method)."""
+        mt, _ = self._resolve_own_or_ancestor(
+            bean.type_id, method_name, arg_count, arg_types,
+            _CONF_SINGLE_IMPLEMENTOR, _CONF_SINGLE_IMPLEMENTOR, caller_ctx,
+        )
+        if isinstance(mt, str) and not self._is_abstract_method(mt):
+            return mt
+        return None
+
+    def _bean_candidates(self, interface_id: str) -> List["_BeanCandidate"]:
+        """Every concrete Spring bean that can satisfy `interface_id`: its
+        `@Component`-family concrete implementors, plus any `@Bean` factory
+        method producing one of its implementors."""
+        subtypes = self._subtypes.get(interface_id, set())
+        out: List[_BeanCandidate] = []
+        for impl in sorted(subtypes):
+            if not self._is_concrete_class(impl):
+                continue
+            info = self._component_info(impl)
+            if info is not None:
+                out.append(info)
+        for bm in self._bean_method_candidates:
+            if bm.type_id in subtypes:
+                out.append(bm)
+        return out
+
+    def _component_info(self, class_id: str) -> Optional["_BeanCandidate"]:
+        """A `_BeanCandidate` for a class iff it carries a `@Component`-family
+        annotation, else None. Bean name comes from the annotation's string arg
+        (`@Service("fast")`) or the decapitalized simple class name; qualifiers
+        gather any `@Qualifier` plus the bean name; `@Primary` sets the flag."""
+        node = self.builder._nodes.get(class_id)
+        if node is None or not node.decorators:
+            return None
+        names = {self._di_annotation_simple_name(d, node.file_path): d for d in node.decorators}
+        if not (JAVA_COMPONENT_ANNOTATIONS & set(names)):
+            return None
+        bean_name, qualifiers, primary = self._bean_metadata_from_decorators(
+            node.decorators, node.name, node.file_path,
+        )
+        return _BeanCandidate(class_id, bean_name, qualifiers, primary, source="component")
+
+    def _bean_metadata_from_decorators(
+        self, decorators: List[str], type_or_method_name: str, file_path: str,
+    ) -> Tuple[Optional[str], FrozenSet[str], bool]:
+        """`(bean_name, qualifiers, primary)` distilled from a class's/`@Bean`
+        method's annotation list. The explicit bean name is the string arg of a
+        component/`@Bean` annotation if given, else the decapitalized name;
+        qualifiers include any `@Qualifier` value *and* the bean name itself (a
+        field `@Qualifier("stripeGateway")` matches a bean named after its
+        class); `@Primary` presence sets the flag."""
+        primary = False
+        qualifiers: Set[str] = set()
+        explicit_name: Optional[str] = None
+        for deco in decorators:
+            simple = self._di_annotation_simple_name(deco, file_path)
+            if simple == "Primary":
+                primary = True
+            elif simple == "Qualifier":
+                arg = self._annotation_string_arg(deco)
+                if arg:
+                    qualifiers.add(arg)
+            elif simple in JAVA_COMPONENT_ANNOTATIONS or simple == "Bean":
+                arg = self._annotation_string_arg(deco)
+                if arg:
+                    explicit_name = arg
+        bean_name = explicit_name or self._decapitalize(type_or_method_name)
+        if bean_name:
+            qualifiers.add(bean_name)
+        return bean_name, frozenset(qualifiers), primary
+
+    @staticmethod
+    def _decapitalize(name: str) -> str:
+        """Spring's default bean name from a class name: the simple name with
+        its first letter lowercased (`StripeGateway` -> `stripeGateway`)."""
+        return name[:1].lower() + name[1:] if name else name
+
+    def _di_annotation_simple_name(self, deco: str, file_path: str) -> str:
+        """Simple annotation name from decorator text (`@lombok.Getter` ->
+        `Getter`, `@Qualifier("x")` -> `Qualifier`, reusing the builder's own
+        dotted-name + argument-stripping parser) iff it is eligible as
+        Spring/Jakarta DI evidence — "" when it instead resolves to a
+        project-local `@interface` declaration shadowing that well-known name
+        (F-02 fix, `_is_local_annotation`), the DI-evidence analogue of the
+        Lombok-stub guard `_decorator_is_local_annotation` already applies. A
+        project's own `@interface Service {}` (or `Autowired`/`Qualifier`/
+        `Primary`/`Bean`/`Component`/...) must never be read as Spring's —
+        every call site that treats a decorator as DI/component evidence
+        (constructor- and setter-injection indexing, field/param injection
+        checks, `@Qualifier`/`@Primary` narrowing, `@Component`-family
+        detection, `@Bean` factory candidates) goes through this rather than
+        a bare simple-name comparison for that reason."""
+        dname = self.builder._decorator_name(deco)
+        if not dname:
+            return ""
+        simple = dname.split(".")[-1]
+        if self._is_local_annotation(dname, simple, file_path):
+            return ""
+        fqn = self._resolved_di_annotation_fqn(dname, simple, file_path)
+        if fqn not in JAVA_DI_ANNOTATION_FQNS:
+            return ""
+        return simple
+
+    def _resolved_di_annotation_fqn(
+        self, dname: str, simple: str, file_path: str,
+    ) -> Optional[str]:
+        if "." in dname:
+            return dname
+        ctx = self._file_ctx.get(file_path)
+        if ctx is None:
+            return None
+        imported = ctx.import_map.get(simple)
+        if imported is not None:
+            return imported
+        own_fqn = simple if ctx.module == DEFAULT_PACKAGE else f"{ctx.module}.{simple}"
+        if own_fqn in JAVA_DI_ANNOTATION_FQNS:
+            return own_fqn
+        for pkg in ctx.wildcard_packages:
+            fqn = f"{pkg}.{simple}"
+            if fqn in JAVA_DI_ANNOTATION_FQNS:
+                return fqn
+        return None
+
+    @staticmethod
+    def _annotation_string_arg(deco: str) -> Optional[str]:
+        """The first string-literal argument of an annotation, or None
+        (`@Qualifier("stripe")` -> `stripe`)."""
+        m = _ANNOTATION_STRING_ARG.search(deco)
+        return m.group(1) if m is not None else None
+
+    @staticmethod
+    def _annotation_named_string_arg(deco: str, arg_name: str) -> Optional[str]:
+        """A named string-literal annotation argument, or None
+        (`@Resource(name = "stripe")` -> `stripe`)."""
+        pattern = re.compile(rf"\b{re.escape(arg_name)}\s*=\s*\"((?:[^\"\\]|\\.)*)\"")
+        m = pattern.search(deco)
+        return m.group(1) if m is not None else None