sourcecode 2.1.0__py3-none-any.whl → 2.3.0__py3-none-any.whl

sourcecode/endpoint_metrics.py

@@ -0,0 +1,42 @@
+"""Single source of truth for the endpoint / route-surface reconciliation note.
+
+Three commands report an endpoint count, each from a different point in the
+pipeline. Read side by side they look contradictory (e.g. 245 vs 225 vs 220 for
+one repo) — they are not. Expected ordering for a single repo:
+
+    repo-ir.route_surface  >=  endpoints.total  >=  spring-audit.endpoints_analyzed
+
+- ``repo-ir.route_surface`` is the RAW structural surface (every @RequestMapping /
+  @Path handler after inheritance projection and JAX-RS sub-resource-locator
+  composition). It still contains framework dynamic-admin routes whose path is a
+  Java FQN (e.g. ``/org.broadleafcommerce.core.search.domain.FieldImpl``), which
+  the ``endpoints`` command filters out — so it is NOT the canonical API surface.
+- ``endpoints.total`` is the canonical REST/API surface (FQN-shaped framework
+  routes removed). This is the number to cite for "how many endpoints".
+- ``spring-audit.endpoints_analyzed`` is that canonical surface further deduplicated
+  by (method, path, controller, handler) for security analysis.
+
+The exact arithmetic between the three is intentionally NOT asserted (the pipelines
+differ in dedup/expansion, so route_surface minus FQN-paths does not equal
+endpoints.total). Only the robust ordering and the population of each are stated.
+
+``spring-audit`` already documents its own count inline; this note gives repo-ir's
+raw ``route_surface`` the same self-description so no reader mistakes it for the
+canonical endpoint total.
+"""
+
+ENDPOINT_SURFACE_RECONCILIATION: str = (
+    "route_surface is the RAW structural route surface: every @RequestMapping/@Path "
+    "handler after inheritance projection and JAX-RS sub-resource-locator composition. "
+    "It is NOT the canonical API surface — it still contains framework dynamic-admin "
+    "routes whose path is a Java FQN (e.g. /org.broadleafcommerce...), which the "
+    "`endpoints` command excludes. Endpoint counts differ across commands BY DESIGN "
+    "and are not contradictory; expected ordering for one repo is "
+    "repo-ir.route_surface (raw, includes FQN-shaped framework routes) >= "
+    "endpoints.total (canonical REST/API surface, FQN-shaped routes filtered out) >= "
+    "spring-audit.metadata.endpoints_analyzed (canonical surface further deduplicated "
+    "by (method, path, controller, handler) for security analysis). Cite "
+    "endpoints.total for the real API surface; the pipelines differ in dedup and "
+    "prefix expansion, so the three counts are related by this ordering, not by exact "
+    "arithmetic."
+)

sourcecode/explain.py

@@ -17,6 +17,7 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Optional
 
+from sourcecode.caller_metrics import CALLER_METRIC_RECONCILIATION
 from sourcecode.fqn_utils import normalize_owner_fqn
 
 if TYPE_CHECKING:
@@ -121,6 +122,7 @@ class ClassExplanation:
             "purpose": self.purpose,
             "public_methods": self.public_methods,
             "incoming_callers": self.incoming_callers,
+            "incoming_callers_note": CALLER_METRIC_RECONCILIATION,
             "outgoing_deps": self.outgoing_deps,
             "events_published": self.events_published,
             "events_consumed": self.events_consumed,

sourcecode/graph_evidence.py

@@ -0,0 +1,352 @@
+"""Graph Evidence Provider — turns the structural module graph into reusable
+topological evidence (ADR-0003, migration step 2).
+
+Responsibility boundary (deliberately narrow):
+
+    ModuleGraph  ->  [ this module ]  ->  topological metrics  ->  GraphEvidence
+
+This component knows GRAPHS, not ARCHETYPES. It does not classify, does not
+emit prose verdicts, and never imports the archetype scorer. It computes a
+small, robust set of topological metrics and packages each as a language- and
+domain-agnostic ``GraphEvidence`` object. The archetype scorer consumes those
+evidence objects; it never traverses the graph itself.
+
+The metrics are chosen so that architectural style can emerge from STRUCTURE
+rather than from directory names:
+
+  * scc_mass                  — fraction of nodes that sit inside a NON-TRIVIAL
+                                strongly-connected component (an import cycle).
+                                Range [0,1]. 0 for a clean DAG (layered/
+                                hexagonal); high for a woven engine core.
+                                Cost O(V+E) (iterative Tarjan).
+  * cyclic_density            — fraction of edges that live INSIDE a non-trivial
+                                SCC (true back-edges). Range [0,1]. Low for
+                                layered; high for engine. Cost O(V+E).
+  * hub_concentration         — share of all edges pointing at the single
+                                highest fan-in node. Range [0,1]. High for
+                                engine/microkernel cores. Cost O(V+E).
+  * module_centralization     — Freeman centralization of the in-degree
+                                distribution. Range [0,1]. ~1 for a star
+                                (microkernel), ~0 for a uniform mesh. Cost O(V).
+  * downward_edge_ratio       — fraction of edges flowing from a LESS stable to
+                                a MORE stable node (Martin instability
+                                I = out/(in+out)). Range [0,1]. High for
+                                layered/hexagonal directed flow. Cost O(V+E).
+  * dependency_inversion_ratio— fraction of edges whose TARGET sits in the most
+                                stable quartile (a stable, depended-upon core).
+                                Range [0,1]. High for hexagonal/clean. O(V+E).
+  * fan_in_gini               — Gini inequality of the in-degree distribution.
+                                Range [0,1]. High when a few modules absorb most
+                                dependencies (engine). Cost O(V log V).
+
+All metrics are name-free: they are functions of the directed topology only.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Iterable, Optional
+
+# Structural edge kinds that represent a real dependency between modules.
+_STRUCTURAL_EDGE_KINDS = frozenset({"imports", "calls"})
+
+# Graph-size thresholds for how much a metric can be trusted / how much mass it
+# is allowed to contribute. A three-node toy graph must not speak with the same
+# authority as a sixty-module one.
+_MIN_NODES_FOR_METRICS = 4
+_MIN_EDGES_FOR_METRICS = 3
+_HIGH_CONF_NODES = 12
+_MASS_SATURATION_NODES = 10.0
+
+
+@dataclass(frozen=True)
+class GraphEvidence:
+    """One topological fact, ready to be consumed by any scorer.
+
+    Archetype-agnostic: it says *what the graph looks like*, never *what the
+    system is*. ``value`` is the raw metric in [0,1]; the scorer decides which
+    archetype (if any) that value supports and with what weight."""
+
+    provider: str          # always "module_graph"
+    kind: str              # metric name, e.g. "scc_mass"
+    value: float           # raw metric, 0..1
+    mass: float            # 0..1 — topological coverage (graph size proxy)
+    confidence: str        # low | medium | high — from graph size
+    detail: str            # human-readable one-liner
+
+    def to_dict(self) -> dict:
+        return {
+            "provider": self.provider,
+            "kind": self.kind,
+            "value": round(self.value, 4),
+            "mass": round(self.mass, 4),
+            "confidence": self.confidence,
+            "detail": self.detail,
+        }
+
+
+@dataclass
+class GraphEvidenceResult:
+    """Metrics + evidence produced from a single module graph."""
+
+    node_count: int
+    edge_count: int
+    metrics: dict[str, float] = field(default_factory=dict)
+    evidence: list[GraphEvidence] = field(default_factory=list)
+    available: bool = False       # False when the graph is too small to trust
+    confidence: str = "low"       # overall provider confidence
+
+    def metric(self, kind: str, default: float = 0.0) -> float:
+        return self.metrics.get(kind, default)
+
+    def to_dict(self) -> dict:
+        return {
+            "node_count": self.node_count,
+            "edge_count": self.edge_count,
+            "available": self.available,
+            "confidence": self.confidence,
+            "metrics": {k: round(v, 4) for k, v in self.metrics.items()},
+            "evidence": [e.to_dict() for e in self.evidence],
+        }
+
+
+class GraphEvidenceProvider:
+    """Transforms a module graph (nodes + directed edges) into GraphEvidence.
+
+    Stateless. Accepts anything exposing ``nodes`` and ``edges`` (a
+    ``schema.ModuleGraph`` does), so tests can hand it synthetic graphs without
+    building a repository."""
+
+    def analyze(
+        self,
+        graph: object,
+        *,
+        edge_kinds: Optional[Iterable[str]] = None,
+    ) -> GraphEvidenceResult:
+        nodes, adjacency = self._project(graph, edge_kinds)
+        n = len(nodes)
+        edges = [(u, v) for u, outs in adjacency.items() for v in outs]
+        e = len(edges)
+
+        result = GraphEvidenceResult(node_count=n, edge_count=e)
+        if n < _MIN_NODES_FOR_METRICS or e < _MIN_EDGES_FOR_METRICS:
+            # Too small to say anything structural. Report nothing rather than
+            # asserting metrics on noise.
+            return result
+
+        result.available = True
+        result.confidence = "high" if n >= _HIGH_CONF_NODES else "medium"
+        topo_mass = min(1.0, n / _MASS_SATURATION_NODES)
+
+        in_deg, out_deg = self._degrees(nodes, edges)
+        scc_of, scc_sizes = self._tarjan_scc(nodes, adjacency)
+        instability = self._instability(nodes, in_deg, out_deg)
+
+        m: dict[str, float] = {}
+        # Only NON-TRIVIAL SCCs (size > 1) count: a pure DAG has none, a woven
+        # engine core has many. A single-node "component" is not a cycle.
+        cyclic_nodes = sum(sz for sz in scc_sizes.values() if sz > 1)
+        m["scc_mass"] = (cyclic_nodes / n) if n else 0.0
+        m["cyclic_density"] = self._cyclic_density(edges, scc_of, scc_sizes, e)
+        m["hub_concentration"] = (max(in_deg.values(), default=0) / e) if e else 0.0
+        m["module_centralization"] = self._centralization(in_deg, n)
+        m["downward_edge_ratio"] = self._downward_ratio(edges, instability)
+        m["dependency_inversion_ratio"] = self._inversion_ratio(edges, instability)
+        m["fan_in_gini"] = self._gini([in_deg[x] for x in nodes])
+        result.metrics = m
+
+        # One evidence object per metric.
+        details = {
+            "scc_mass": f"{m['scc_mass']:.0%} of modules sit inside an import cycle",
+            "cyclic_density": f"{m['cyclic_density']:.0%} of edges are back-edges inside a cycle",
+            "hub_concentration": f"top module absorbs {m['hub_concentration']:.0%} of all dependencies",
+            "module_centralization": f"in-degree centralization {m['module_centralization']:.2f} (1=star, 0=mesh)",
+            "downward_edge_ratio": f"{m['downward_edge_ratio']:.0%} of edges flow toward more-stable modules",
+            "dependency_inversion_ratio": f"{m['dependency_inversion_ratio']:.0%} of edges point into the stable core",
+            "fan_in_gini": f"in-degree inequality (Gini) {m['fan_in_gini']:.2f}",
+        }
+        result.evidence = [
+            GraphEvidence(
+                provider="module_graph", kind=k, value=m[k], mass=topo_mass,
+                confidence=result.confidence, detail=details[k],
+            )
+            for k in details
+        ]
+        return result
+
+    # ── graph projection ───────────────────────────────────────────────────────
+    @staticmethod
+    def _project(
+        graph: object, edge_kinds: Optional[Iterable[str]]
+    ) -> "tuple[list[str], dict[str, set[str]]]":
+        """Reduce the graph to a deduped directed adjacency over the relevant
+        vertices. Prefers module-granularity nodes; falls back to all nodes."""
+        raw_nodes = list(getattr(graph, "nodes", []) or [])
+        raw_edges = list(getattr(graph, "edges", []) or [])
+        kinds = frozenset(edge_kinds) if edge_kinds is not None else _STRUCTURAL_EDGE_KINDS
+
+        module_ids = {getattr(nd, "id") for nd in raw_nodes if getattr(nd, "kind", None) == "module"}
+        # If the graph carries module nodes, restrict to them; otherwise use every
+        # node (synthetic test graphs, symbol-only graphs).
+        if module_ids:
+            allowed = module_ids
+        else:
+            allowed = {getattr(nd, "id") for nd in raw_nodes}
+
+        adjacency: dict[str, set[str]] = {nid: set() for nid in allowed}
+        for ed in raw_edges:
+            if getattr(ed, "kind", None) not in kinds:
+                continue
+            u = getattr(ed, "source", None)
+            v = getattr(ed, "target", None)
+            if u is None or v is None or u == v:
+                continue
+            if u not in allowed or v not in allowed:
+                continue
+            adjacency.setdefault(u, set()).add(v)
+            adjacency.setdefault(v, set())
+        nodes = sorted(adjacency.keys())
+        return nodes, adjacency
+
+    # ── metric primitives ──────────────────────────────────────────────────────
+    @staticmethod
+    def _degrees(
+        nodes: list[str], edges: list[tuple[str, str]]
+    ) -> "tuple[dict[str, int], dict[str, int]]":
+        in_deg = {x: 0 for x in nodes}
+        out_deg = {x: 0 for x in nodes}
+        for u, v in edges:
+            out_deg[u] += 1
+            in_deg[v] += 1
+        return in_deg, out_deg
+
+    @staticmethod
+    def _tarjan_scc(
+        nodes: list[str], adjacency: dict[str, set[str]]
+    ) -> "tuple[dict[str, int], dict[int, int]]":
+        """Iterative Tarjan. Returns (node -> scc_id, scc_id -> size)."""
+        index_of: dict[str, int] = {}
+        low: dict[str, int] = {}
+        on_stack: set[str] = set()
+        stack: list[str] = []
+        scc_of: dict[str, int] = {}
+        sizes: dict[int, int] = {}
+        counter = 0
+        scc_id = 0
+
+        for root in nodes:
+            if root in index_of:
+                continue
+            # work stack of (node, iterator-position)
+            work: list[tuple[str, int]] = [(root, 0)]
+            while work:
+                v, pi = work[-1]
+                if pi == 0:
+                    index_of[v] = low[v] = counter
+                    counter += 1
+                    stack.append(v)
+                    on_stack.add(v)
+                succ = sorted(adjacency.get(v, ()))
+                if pi < len(succ):
+                    work[-1] = (v, pi + 1)
+                    w = succ[pi]
+                    if w not in index_of:
+                        work.append((w, 0))
+                    elif w in on_stack:
+                        low[v] = min(low[v], index_of[w])
+                    continue
+                # done with v
+                if low[v] == index_of[v]:
+                    size = 0
+                    while True:
+                        w = stack.pop()
+                        on_stack.discard(w)
+                        scc_of[w] = scc_id
+                        size += 1
+                        if w == v:
+                            break
+                    sizes[scc_id] = size
+                    scc_id += 1
+                work.pop()
+                if work:
+                    parent = work[-1][0]
+                    low[parent] = min(low[parent], low[v])
+        return scc_of, sizes
+
+    @staticmethod
+    def _cyclic_density(
+        edges: list[tuple[str, str]], scc_of: dict[str, int],
+        scc_sizes: dict[int, int], e: int,
+    ) -> float:
+        if not e:
+            return 0.0
+        intra = 0
+        for u, v in edges:
+            su = scc_of.get(u)
+            if su is not None and su == scc_of.get(v) and scc_sizes.get(su, 1) > 1:
+                intra += 1
+        return intra / e
+
+    @staticmethod
+    def _centralization(in_deg: dict[str, int], n: int) -> float:
+        """Freeman in-degree centralization, normalized to [0,1]."""
+        if n < 2:
+            return 0.0
+        mx = max(in_deg.values(), default=0)
+        total_diff = sum(mx - d for d in in_deg.values())
+        denom = (n - 1) * (n - 1)  # theoretical max for a directed star
+        return min(1.0, total_diff / denom) if denom else 0.0
+
+    @staticmethod
+    def _instability(
+        nodes: list[str], in_deg: dict[str, int], out_deg: dict[str, int]
+    ) -> dict[str, float]:
+        """Martin instability I = out / (in + out). Isolated nodes -> None-like
+        (excluded via absence)."""
+        inst: dict[str, float] = {}
+        for x in nodes:
+            total = in_deg[x] + out_deg[x]
+            if total > 0:
+                inst[x] = out_deg[x] / total
+        return inst
+
+    @staticmethod
+    def _downward_ratio(
+        edges: list[tuple[str, str]], instability: dict[str, float]
+    ) -> float:
+        considered = 0
+        downward = 0
+        for u, v in edges:
+            if u in instability and v in instability:
+                considered += 1
+                # edge from less-stable (higher I) to more-stable (lower I)
+                if instability[u] >= instability[v]:
+                    downward += 1
+        return (downward / considered) if considered else 0.0
+
+    @staticmethod
+    def _inversion_ratio(
+        edges: list[tuple[str, str]], instability: dict[str, float]
+    ) -> float:
+        """Fraction of edges whose target sits in the most-stable quartile."""
+        vals = sorted(instability.values())
+        if not vals or not edges:
+            return 0.0
+        q1 = vals[max(0, len(vals) // 4 - 1)]
+        into_core = sum(
+            1 for _u, v in edges
+            if v in instability and instability[v] <= q1
+        )
+        return into_core / len(edges)
+
+    @staticmethod
+    def _gini(values: list[int]) -> float:
+        vals = sorted(float(v) for v in values)
+        n = len(vals)
+        s = sum(vals)
+        if n == 0 or s == 0:
+            return 0.0
+        cum = 0.0
+        for i, v in enumerate(vals, start=1):
+            cum += i * v
+        # Gini = (2*sum(i*x_i) / (n*sum)) - (n+1)/n
+        return max(0.0, min(1.0, (2 * cum) / (n * s) - (n + 1) / n))

sourcecode/path_filters.py

@@ -16,7 +16,8 @@ _TEST_SEGMENTS = frozenset({
 # code lives under src/main (e.g. a Maven module that ships a test framework).
 # A finding under one of these modules is test infrastructure, not the product.
 _TEST_MODULE_SEGMENTS = frozenset({
-    "testsuite", "test-framework", "testframework",
+    "testsuite", "test-suite", "test-suites",
+    "test-framework", "testframework",
     "integration-arquillian", "arquillian",
     "test-utils", "test-util", "testutils",
     "test-support", "testsupport",

sourcecode/repository_ir.py

@@ -22,6 +22,8 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Iterable, Optional
 
+from sourcecode.caller_metrics import CALLER_METRIC_RECONCILIATION
+from sourcecode.endpoint_metrics import ENDPOINT_SURFACE_RECONCILIATION
 from sourcecode.fqn_utils import normalize_owner_fqn as _normalize_owner_fqn
 from sourcecode.path_filters import is_test_path as _is_test_path
 from sourcecode.security_config import (
@@ -3965,6 +3967,11 @@ def _assemble(
     return {
         **_base,
         "route_surface": _route_surface,
+        # SC-9 (Broadleaf field test): route_surface is the RAW surface (includes
+        # framework dynamic-admin FQN-shaped routes the `endpoints` command filters).
+        # Self-describe it so its count is never read as contradicting endpoints /
+        # spring-audit totals when cross-referenced.
+        "route_surface_note": ENDPOINT_SURFACE_RECONCILIATION,
         "spring_events": _spring_events,
         "analysis_gaps": _analysis_gaps,
         "security_model": _security_model_asm,
@@ -4236,6 +4243,10 @@ def _build_route_surface(
                     "return_type": (sym.return_type.strip() if sym.return_type else "void"),
                     "stable_id": sym.stable_id,
                     "inheritance_depth": 0,
+                    # Provenance: which annotation family this modeled route came from.
+                    # Used downstream so a MODELED framework (JAX-RS) is never also reported
+                    # as an un-modeled "non_spring_rest_surface" (A2 field-validation fix).
+                    "framework": "jax_rs" if ann_name in _JAXRS_HTTP_ANNOTATIONS else "spring_mvc",
                 }
                 _route_entry["security_annotations"] = _sec
                 routes.append(_route_entry)
@@ -4721,11 +4732,16 @@ def apply_ir_size_limits(
         if isinstance(raw_rs, list):
             _rs_total = len(raw_rs)
             out["route_surface"] = raw_rs[:50]
+            # SC-9: always carry the raw-surface reconciliation note; prepend the
+            # truncation notice when the list was capped.
             if _rs_total > 50:
                 out["route_surface_note"] = (
-                    f"Showing 50/{_rs_total} endpoints. "
-                    "Remove --summary-only for full route surface."
+                    f"Showing 50/{_rs_total} route-surface entries. "
+                    "Remove --summary-only for the full route surface. "
+                    + ENDPOINT_SURFACE_RECONCILIATION
                 )
+            else:
+                out["route_surface_note"] = ENDPOINT_SURFACE_RECONCILIATION
         elif isinstance(raw_rs, dict):
             # Legacy dict format with "endpoints" sub-key
             raw_eps: list = raw_rs.get("endpoints") or []
@@ -5116,16 +5132,19 @@ def extract_java_endpoints(root: Path) -> "dict[str, Any]":
     # total false negative that also disables the `validation` command downstream.
     # Detection is by SYNTACTIC SHAPE (no framework knowledge): an HTTP-verb method
     # name, a first argument that is a string literal looking like a path (starts
-    # with "/", may contain :param / {param}), AND a second argument (the trailing
-    # comma) — the comma is what distinguishes a route registration from a 1-arg
-    # getter such as Map.get("/k"). Matches both bare `get(...)` (static-import /
-    # Spark style) and `app.get(...)` (Javalin style); the lookbehind only rejects
-    # an identifier char so `forget(` is not mistaken for `get(`. Reported at
-    # confidence "medium" — an occasional flagged false positive beats a total
-    # silent false negative.
+    # with "/", may contain :param / {param}), AND a second argument that is a
+    # HANDLER, not a literal. Matches both bare `get(...)` (static-import / Spark
+    # style) and `app.get(...)` (Javalin style); the lookbehind only rejects an
+    # identifier char so `forget(` is not mistaken for `get(`.
+    # B1 fix (field validation, openmrs FormUtil): a route handler is always a
+    # method-ref / lambda / call / identifier — never a bare literal. The negative
+    # lookahead after the comma rejects a literal second argument, so a plain map
+    # write like `swapChars.put("/", "slash")` is no longer mistaken for a `PUT /`
+    # route. Reported at confidence "medium" — an occasional flagged false positive
+    # beats a total silent false negative.
     _DSL_ROUTE_RE = _re.compile(
         r'(?<![A-Za-z0-9_])(get|post|put|delete|patch|head|options)\s*\(\s*'
-        r'"(/[^"\s]*)"\s*,'
+        r'"(/[^"\s]*)"\s*,(?!\s*(?:["0-9]|true\b|false\b|null\b))'
     )
     _dsl_routes: list[dict] = []
 
@@ -5441,6 +5460,15 @@ def extract_java_endpoints(root: Path) -> "dict[str, Any]":
     if _webscript_descriptors:
         _nonspring["webscripts"] += _webscript_descriptors
 
+    # A2 fix (eureka/keycloak field validation): JAX-RS is MODELED by _build_route_surface
+    # (routes carry framework="jax_rs"). When we actually modeled JAX-RS endpoints, it is
+    # NOT an un-modeled "non_spring_rest_surface" — reporting it as such contradicted the
+    # endpoints just emitted (e.g. keycloak's 689 JAX-RS routes labelled "not modeled").
+    # Only genuinely un-modeled surfaces (WebScripts, Servlets, or JAX-RS that produced no
+    # modeled route — client proxies / extraction gaps) remain here.
+    if any(r.get("framework") == "jax_rs" for r in routes):
+        _nonspring.pop("jax_rs", None)
+
     _nonspring_total = sum(_nonspring.values())
     if _nonspring_total:
         _frameworks = [k for k, v in _nonspring.items() if v]
@@ -5471,9 +5499,9 @@ def extract_java_endpoints(root: Path) -> "dict[str, Any]":
             )
         else:
             _msg = (
-                f"Additional REST surface present outside Spring MVC: detected {_fw_label}. "
-                f"These endpoints are NOT modeled here; the count covers Spring-MVC-annotated "
-                f"endpoints only."
+                f"Additional REST surface detected but NOT modeled here: {_fw_label}. "
+                f"The endpoints above cover the annotation-modeled surface (Spring MVC and "
+                f"JAX-RS); the {_fw_label} surface is additional and not included in the count."
             )
         result.setdefault("warnings", []).append(_msg)
 
@@ -6153,10 +6181,18 @@ def compute_blast_radius(
                 "no indirect callers reachable from sampled seeds (terminal sink or sparse graph). "
                 "Use a lower-fan-in entry point for full transitive traversal."
             )
+    # SC-6 (Broadleaf field test): the direct_callers array is a truncated display
+    # sample. Disclose the cap and point to stats.direct_caller_count as the true
+    # total (== explain.incoming_callers), then append the cross-command
+    # reconciliation so len(direct_callers) is never misread as a contradiction.
     if len(direct_callers) > 30:
         out["direct_callers_note"] = (
-            f"Showing 30/{n_direct} direct callers. Use --output to inspect full IR."
+            f"Showing 30/{n_direct} distinct direct callers; "
+            f"stats.direct_caller_count = {n_direct} is the true total "
+            f"(use --output for the full list). " + CALLER_METRIC_RECONCILIATION
         )
+    else:
+        out["direct_callers_note"] = CALLER_METRIC_RECONCILIATION
     if len(indirect_callers) > 50:
         out["indirect_callers_note"] = (
             f"Showing 50/{n_indirect} indirect callers. Use --output to inspect full IR."

sourcecode/semantic_integration_engine.py

@@ -179,7 +179,9 @@ class SemanticIntegrationEngine:
 
     def detect(self) -> list[Integration]:
         """All outbound integrations recoverable from typed facts, deterministically
-        ordered. One record per (type, kind, client). Targets are attributed by
+        ordered. One record per semantic point (kind + evidence location): a type that
+        touches several client libraries of the same kind counts once. Targets are
+        attributed by
         annotation args (declarative) or by literal scheme (imperative), never by a
         receiver variable name."""
         per_type: dict[str, list[Integration]] = {}
@@ -231,7 +233,21 @@ class SemanticIntegrationEngine:
             per_type[t.fqn] = list(recs.values())
 
         out = [r for recs in per_type.values() for r in recs]
-        return sorted(out, key=lambda i: (i.kind, i.client, i.evidence))
+        out.sort(key=lambda i: (i.kind, i.client, i.evidence))
+        # REG-1 (Broadleaf field test): one integration per semantic point =
+        # (kind, evidence location). A single type touching several client-library
+        # types of the SAME kind — e.g. spring-ldap + spring-security-ldap on one
+        # LdapUserDetailsMapper, or javamail + spring-mail on one MessageCreator —
+        # previously emitted one record per client label, double-counting the same
+        # integration. Collapse to a single record per (kind, evidence), preferring
+        # one that carries a resolved target; ties broken by the deterministic
+        # (kind, client, evidence) order established above.
+        deduped: dict[tuple, Integration] = {}
+        for r in out:
+            k = (r.kind, r.evidence)
+            if k not in deduped or (r.target and deduped[k].target is None):
+                deduped[k] = r
+        return list(deduped.values())
 
     def _coverage(self, n_records: int, n_files: int) -> "tuple[str, str]":
         """Honest coverage signal (mirrors integration_detector): a low count on a

sourcecode/serializer.py

@@ -462,11 +462,31 @@ def _mybatis_pairing(sm: "SourceMap", *, full: bool = False) -> "Optional[dict[s
 
 
 def _spring_boot_version(sm: "SourceMap") -> "Optional[str]":
-    """Extract Spring Boot version from detected frameworks."""
+    """Extract Spring Boot version from detected frameworks.
+
+    A3 fix (field validation, Broadleaf): when Spring Boot IS detected but the
+    stack detector could not attach a version (e.g. the version lives in a
+    `<spring.boot.version>` pom property rather than spring-boot-starter-parent),
+    fall back to migrate-check's property-resolving detector so `--compact`
+    reports the SAME version migrate-check already knows — the engine must not
+    surface a fact in one command and hide it in another. Gated on Boot already
+    being detected, so no phantom version is ever introduced.
+    """
+    _boot_detected = False
     for s in sm.stacks:
         for fw in s.frameworks:
-            if fw.name == "Spring Boot" and fw.version:
-                return fw.version
+            if fw.name == "Spring Boot":
+                if fw.version:
+                    return fw.version
+                _boot_detected = True
+    if _boot_detected:
+        _root = getattr(sm.metadata, "analyzed_path", None) if sm.metadata else None
+        if _root:
+            try:
+                from sourcecode.migrate_check import _detect_spring_boot
+                return _detect_spring_boot(Path(_root), 0)[1]
+            except Exception:
+                return None
     return None