sourcecode 1.71.0__tar.gz → 1.73.0__tar.gz

{sourcecode-1.71.0 → sourcecode-1.73.0}/CHANGELOG.md

@@ -1,5 +1,119 @@
 # Changelog
 
+## [1.73.0] — 2026-07-01
+
+### Fixed — audit reliability on a large non-Boot Spring monolith (Alfresco Community Repo field test)
+
+A real architecture audit of **alfresco-community-repo** (`fe6dd26c3f`; 6,549
+classes, 24 Maven modules, Spring 7 **without Spring Boot**, iBatis persistence,
+Camel/ActiveMQ messaging, Acegi-derived security, WebScript REST surface)
+surfaced seven defects — each capable of leading an automated consultant to a
+false conclusion. All fixed at root cause with regression coverage and
+re-verified on the live repo.
+
+- **`--compact` did not resolve `language_version` from a Maven property (BUG #1).**
+  Alfresco declares `<maven.compiler.source>${java.version}</...>` chained to
+  `<java.version>21</java.version>`; the Java-stack detector picked the first key
+  and emitted the literal `${java.version}` while `migrate-check` resolved it. A
+  shared `substitute_maven_properties` resolver (in `detectors/parsers.py`) now
+  backs BOTH paths — `--compact` reports `21`.
+- **`explain --output` wrote Markdown to a `.json` file with no warning (BUG #2).**
+  Broke any consumer assuming JSON parity across subcommands. `explain` now infers
+  JSON from a `.json` output extension (an explicit `--format` always wins), and
+  `--help` documents that its default output is human-readable text/Markdown.
+- **`entry_points.bootstrap` false positives on `*Application.java` by name (BUG #3).**
+  Alfresco's XSD/JAXB-generated `Application.java` model classes (no `main()`, no
+  bootstrap annotation, in a WAR) were listed as application entry points. A file
+  now qualifies only with a real `main(String[])` or a bootstrap annotation
+  (`@SpringBootApplication` / WAR `SpringBootServletInitializer` / `@QuarkusMain`
+  / …); the serializer's name-based bootstrap fallback was removed.
+- **"MyBatis" framework declared against the tool's own zero evidence (BUG #4).**
+  A `org.mybatis:mybatis` pom coordinate alone produced a "MyBatis" framework label
+  while the `mybatis` block reported `mapper_interfaces: 0, xml_files: 0` (Alfresco's
+  SQL layer is iBatis-style `*-SqlMap.xml`, surfaced separately). MyBatis is now
+  emitted only with real usage evidence — an `@Mapper` interface or a `*Mapper.xml`.
+- **`export --integrations` missed ActiveMQ/Camel messaging (BUG #5).**
+  JMS detection recognized little beyond a direct `JmsTemplate`, reporting 1
+  integration on a repo with an ActiveMQ connection-factory config and Camel routes.
+  Added `ActiveMQSslConnectionFactory` / pooled / caching connection-factory tokens
+  and an Apache Camel route pass (literal `activemq:`/`jms:` endpoint URIs, plus
+  variable-URI `from()/to()` routes inside a `RouteBuilder` as honest low-confidence
+  `camel-route` messaging records). Alfresco JMS/messaging surface: 1 → 5.
+- **`readiness_score` Hibernate false-positive — regression test (BUG #6).**
+  v1.63.0 once scored this Hibernate-free repo 42/100 with a phantom
+  `hibernate_rewrite` headline (~46 days). Already fixed by v1.72.0; added an
+  explicit regression test (`no Hibernate/JPA imports → hibernate.detected False,
+  headline_blocker never hibernate_rewrite`) so a future detector refactor cannot
+  reintroduce it.
+- **`endpoints` / C4 `api_surface` returned 0 with no explanation (BUG #7).**
+  On an obvious API server (WebScripts: XML descriptor + handler class, not
+  `@RestController`), a bare `total: 0` reads as "no public API". `endpoints` now
+  emits a first-class `zero_result_reason` naming the routing patterns searched and
+  any non-Spring surface detected (Alfresco: 482 WebScript descriptors / 901 handler
+  classes), and the C4 export's `api_surface` carries the same explanation.
+
+## [1.72.0] — 2026-07-01
+
+### Fixed — correctness on a large real-world Spring Boot 3 monolith (Broadleaf Commerce CE field test)
+
+A downstream architecture audit of **BroadleafCommerce** (`97705634ac`, branch
+`develop-7.0.x`; ~3,000 Java classes, 13 Maven poms, Spring Boot 3.5 / Spring 6.2 /
+Hibernate 5.6) hand-verified against source surfaced seven reproducible
+correctness defects across `modernize`, `spring-audit`, `migrate-check`, and
+`export --integrations`. Each fix targets the root cause and adds regression
+coverage; all were re-verified against the live repo.
+
+- **`spring-audit` TX-005 — 100% false-positive rate (4/4) on expected-exception idioms.**
+  The "swallowed exception in `@Transactional`" rule flagged the standard JPA
+  control-flow idiom (`Query.getSingleResult()` → `catch (NoResultException)` →
+  insert; tolerant insert → `catch (EntityExistsException)`) and catches carrying an
+  explicit `// do nothing — acceptable condition` intent comment. TX-005 now skips
+  catches whose caught type is a well-known expected-control-flow exception
+  (`NoResultException`, `NonUniqueResultException`, `EntityExistsException`,
+  `EmptyResultDataAccessException`, …) and catches whose body documents a deliberate
+  no-op, while still flagging a genuine unexpected-exception swallow.
+- **`modernize` `statically_unreferenced` — ~95% false positives on annotation-constant nested classes.**
+  Two compounding defects: (a) the pre-scan fast path emitted nested types as
+  `pkg.Inner`, dropping the enclosing class, so distinct nested types with the same
+  simple name (Broadleaf has 25 `GroupName`s) collapsed onto one colliding FQN;
+  (b) static-constant reads inside annotation arguments
+  (`@AdminPresentation(group = GroupName.General)`, incl. the fully-qualified
+  `Outer.Nested.CONST` form and class-level annotations) were never counted as
+  references, so the constant holders read as zero-caller dead code. Now: nested
+  symbols are binary-qualified (`Outer.Inner`); a new `references` edge pass resolves
+  annotation-value reads (bare, inherited-nested via supertypes, and qualified
+  chains) in both parsed and pre-scan-skipped files. Presentation-holder false
+  positives on Broadleaf went 11→0 (the survivors are genuinely-unused declarations).
+- **`modernize` `cross_module_tangles` — re-emitted the subsystem list instead of coupling.**
+  The field echoed `{label, class_count, member_count}` per subsystem with no edge
+  data. It now measures real directed inter-subsystem coupling from structural graph
+  edges, with `edge_count`, `reverse_edge_count`, and `mutual` (bidirectional/cyclic
+  = the actual tangle) — e.g. Broadleaf `profile↔common` is now correctly flagged
+  mutual.
+- **`migrate-check` MIG-031 — test-scope config counted as a production blocker + wrong explanation.**
+  A test-only `bl-applicationContext-test-security.xml` (under `src/main/resources`,
+  loaded only by test `@ContextConfiguration`) inflated `blocking_count`; XML config
+  with a `test` filename marker is now classified `code_context: "test"`
+  (blocking_count 1→0). The explanation was a static OR-template asserting both
+  triggers; it now reports only the sub-pattern that actually matched (auto-config
+  vs versioned legacy schema).
+- **`export --integrations` — missed in-code Spring Security LDAP (false negative).**
+  Subclassing `LdapUserDetailsMapper` and using `DirContextOperations` — the
+  idiomatic Spring Security LDAP auth mapper — was undetected (Broadleaf reported 0
+  LDAP). Added `LdapUserDetailsMapper` / `DirContextOperations` / context-source
+  tokens; Broadleaf now reports 5 LDAP integration points.
+- **`explain` vs `modernize` in-degree — silently contradictory numbers.**
+  The same class showed different fan-in in the two commands with no explanation.
+  Both metrics are now self-describing: `modernize.high_coupling_nodes` documents
+  `in_degree` as the raw all-edge-type incoming count; `explain` labels its value
+  as "N distinct caller classes".
+- **`spring-audit` vs `endpoints` — unreconcilable endpoint counts.**
+  The canonical IR (feeding `spring-audit`, `impact`, `validation`) did not apply the
+  `endpoints` command's filter for framework dynamic-admin FQN-shaped paths, so its
+  count was silently inflated. The filter is now shared; `endpoints_analyzed` is
+  documented as the deduplicated canonical count (≤ `endpoints` total, difference =
+  multi-prefix collapse), reconciling 225 vs 220 on Broadleaf.
+
 ## [1.71.0] — 2026-07-01
 
 ### Fixed — framework-framing & migration reliability on a large non-Boot Spring repo (Jenkins core field test)

{sourcecode-1.71.0 → sourcecode-1.73.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.71.0
+Version: 1.73.0
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm

{sourcecode-1.71.0 → sourcecode-1.73.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "1.71.0"
+version = "1.73.0"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-1.71.0 → sourcecode-1.73.0}/src/sourcecode/__init__.py

@@ -1,3 +1,3 @@
 """sourcecode — Deterministic codebase context maps for AI coding agents."""
 
-__version__ = "1.71.0"
+__version__ = "1.73.0"

{sourcecode-1.71.0 → sourcecode-1.73.0}/src/sourcecode/canonical_ir.py

@@ -16,6 +16,7 @@ from __future__ import annotations
 
 import hashlib
 import json
+import re
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Optional
@@ -37,6 +38,11 @@ IR_SCHEMA_VERSION = "1.0.0"
 # Edge types excluded from reverse graph (mirrors repository_ir._REVERSE_EXCLUDE)
 _REVERSE_EXCLUDE: frozenset[str] = frozenset({"annotated_with", "mapped_to"})
 
+# A route path that looks like a Java FQN is framework dynamic-admin routing, not a
+# real REST endpoint (mirrors the filter in repository_ir.extract_java_endpoints so
+# the CIR endpoint count reconciles with the `endpoints` command). See BUG #7.
+_FQN_PATH_RE: re.Pattern = re.compile(r"/(org|com|net|io|edu)\.[a-z][a-z0-9]*\.[a-zA-Z]")
+
 
 # ---------------------------------------------------------------------------
 # CanonicalSecurity
@@ -324,9 +330,17 @@ def ir_dict_to_canonical(
     # Build canonical endpoints from route_surface — stable ordering
     route_surface = ir.get("route_surface") or []
     # Deduplicate by endpoint id (route_surface can have duplicates from multi-prefix)
+    # BUG #7 (Broadleaf field test): the `endpoints` command (extract_java_endpoints)
+    # drops routes whose path looks like a Java FQN — framework dynamic-admin routing
+    # (Broadleaf @AdminSection registers entity class FQNs as URL segments) is not a
+    # real REST surface. The CIR endpoint list feeds `spring-audit` (endpoints_analyzed),
+    # `impact` and `validation`; it must apply the SAME filter so its count reconciles
+    # with `endpoints` instead of being silently inflated by those pseudo-routes.
     _seen_ids: set[str] = set()
     raw_endpoints: list[CanonicalEndpoint] = []
     for r in route_surface:
+        if _FQN_PATH_RE.search(r.get("path", "") or ""):
+            continue
         ep = _route_to_canonical_endpoint(r)
         if ep.id not in _seen_ids:
             _seen_ids.add(ep.id)

{sourcecode-1.71.0 → sourcecode-1.73.0}/src/sourcecode/cli.py

@@ -4221,6 +4221,7 @@ def _build_c4_export(
     edges: "list[dict]",
     endpoints: "list[dict]",
     integrations: "dict",
+    endpoint_meta: "Optional[dict]" = None,
 ) -> "dict":
     """Assemble a unified, tool-agnostic C4 architecture export + incremental manifest.
 
@@ -4236,6 +4237,15 @@ def _build_c4_export(
     # consumer counts/classifies modules instead of inferring them from leaf dirs.
     module_graph["module_roots"] = _detect_module_roots(by_directory)
     api_surface = _group_endpoints_by_controller(endpoints)
+    # BUG #7 (Alfresco field test): carry the endpoint extractor's structured
+    # zero-result explanation and non-Spring REST surface into api_surface, so a
+    # C4 consumer seeing 0 controllers understands WHY (unrecognized routing, e.g.
+    # WebScripts) instead of concluding the system has no public API.
+    if endpoint_meta:
+        if endpoint_meta.get("zero_result_reason"):
+            api_surface["zero_result_reason"] = endpoint_meta["zero_result_reason"]
+        if endpoint_meta.get("non_spring_rest_surface"):
+            api_surface["non_spring_rest_surface"] = endpoint_meta["non_spring_rest_surface"]
     containers = _detect_containers(root)
 
     limitations: "list[str]" = []
@@ -4364,7 +4374,8 @@ def export_cmd(
         from sourcecode.repository_ir import extract_java_endpoints
         ir = build_repo_ir(file_list, root)
         graph = ir.get("graph", {})
-        endpoints = extract_java_endpoints(root).get("endpoints", [])
+        _ep_data = extract_java_endpoints(root)
+        endpoints = _ep_data.get("endpoints", [])
         data = _build_c4_export(
             root,
             file_list,
@@ -4372,6 +4383,7 @@ def export_cmd(
             graph.get("edges", []),
             endpoints,
             detect_integrations(file_list, root),
+            endpoint_meta=_ep_data,
         )
         output = _serialize_dict(data, format)
         _emit_command_output(output, output_path, copy,
@@ -5215,14 +5227,16 @@ def explain_cmd(
         Path("."),
         help="Repository root (default: current directory)",
     ),
-    format: str = typer.Option(
-        "text", "--format", "-f",
-        help="Output format: text (default) or json.",
-        show_default=True,
+    format: Optional[str] = typer.Option(
+        None, "--format", "-f",
+        help="Output format: text (default) or json. If unset and --output ends "
+             "in .json, JSON is written automatically.",
     ),
     output_path: Optional[Path] = typer.Option(
         None, "--output", "-o",
-        help="Write output to a file instead of stdout.",
+        help="Write output to a file instead of stdout. NOTE: the default format is "
+             "human-readable text/Markdown, NOT JSON — pass --format json (or use a "
+             ".json output path) for machine-readable output.",
     ),
     copy: bool = typer.Option(
         False, "--copy", "-c",
@@ -5231,6 +5245,11 @@ def explain_cmd(
 ) -> None:
     """Human-readable architectural summary for a class.
 
+    \b
+    OUTPUT FORMAT: defaults to text/Markdown (human-oriented). Unlike most
+    subcommands this is NOT JSON by default — pass --format json, or give an
+    --output path ending in .json, for a machine-readable envelope.
+
     \b
     Generates a structured explanation derived entirely from static analysis:
       - Purpose and Spring stereotype
@@ -5278,6 +5297,15 @@ def explain_cmd(
         )
         raise typer.Exit(code=1)
 
+    # BUG #2 (Alfresco field test): `explain -o out.json` previously wrote Markdown
+    # to a .json file, breaking any programmatic consumer that assumed JSON parity
+    # with the other subcommands. Infer JSON from a .json output extension when
+    # --format is unset; an explicit --format always wins.
+    if format is None:
+        if output_path and str(output_path).lower().endswith(".json"):
+            format = "json"
+        else:
+            format = "text"
     _enforce_format("explain", format)
 
     file_list = find_java_files(target)
@@ -5764,11 +5792,63 @@ def modernize_cmd(
         key=lambda h: (-h["hotspot_score"], h["fqn"]),
     )[:15]
 
-    # Cross-module tangles: subsystems with high member count
-    tangle_modules = sorted(
-        [s for s in subsystems if len(s.get("members") or []) >= 5],
-        key=lambda s: -len(s.get("members") or []),
-    )[:10]
+    # Cross-module tangles: actual inter-subsystem coupling measured from the
+    # dependency graph, NOT a re-labelled subsystem list. For every structural
+    # edge whose endpoints live in two different subsystems we tally a directed
+    # (from_subsystem → to_subsystem) coupling count; pairs coupled in BOTH
+    # directions are the real tangles (bidirectional/cyclic module coupling).
+    _graph_edges: list = (ir.get("graph") or {}).get("edges") or []
+    # Structural coupling edge types. annotated_with / mapped_to / event edges are
+    # excluded (metadata + separate topology, not module-decomposition coupling).
+    _TANGLE_EDGE_TYPES = frozenset({
+        "imports", "injects", "extends", "implements",
+        "references", "calls", "instantiates", "returns",
+    })
+    _fqn_to_pkg: dict[str, str] = {}
+    _pkg_to_label: dict[str, str] = {}
+    for _s in subsystems:
+        _pp = _s.get("package_prefix") or _s.get("pkg") or ""
+        if not _pp:
+            continue
+        _pkg_to_label[_pp] = _s.get("label") or _s.get("name") or _pp
+        for _m in (_s.get("members") or []):
+            _fqn_to_pkg[_m] = _pp
+
+    from collections import Counter as _Counter
+    _pair_counts: "_Counter[tuple[str, str]]" = _Counter()
+    _pair_example: dict[tuple[str, str], str] = {}
+    for _e in _graph_edges:
+        if _e.get("type") not in _TANGLE_EDGE_TYPES:
+            continue
+        _a = _fqn_to_pkg.get(_e.get("from"))
+        _b = _fqn_to_pkg.get(_e.get("to"))
+        if not _a or not _b or _a == _b:
+            continue
+        _pair_counts[(_a, _b)] += 1
+        _pair_example.setdefault((_a, _b), f"{_e.get('from')} → {_e.get('to')}")
+
+    _cross_module_tangles = []
+    for (_a, _b), _cnt in sorted(
+        _pair_counts.items(), key=lambda kv: (-kv[1], kv[0])
+    ):
+        _reverse = _pair_counts.get((_b, _a), 0)
+        _cross_module_tangles.append({
+            "from_subsystem": _pkg_to_label.get(_a, _a),
+            "to_subsystem": _pkg_to_label.get(_b, _b),
+            "from_package": _a,
+            "to_package": _b,
+            "edge_count": _cnt,
+            "reverse_edge_count": _reverse,
+            # A mutual (cyclic) dependency is the actual "tangle" — both modules
+            # reference each other, so neither can be extracted independently.
+            "mutual": _reverse > 0,
+            "example": _pair_example.get((_a, _b), ""),
+        })
+    # Surface mutual tangles first (highest decomposition risk), then by strength.
+    _cross_module_tangles.sort(
+        key=lambda t: (not t["mutual"], -t["edge_count"], t["from_package"])
+    )
+    _cross_module_tangles = _cross_module_tangles[:15]
 
     _summary = {
         "total_classes": len([n for n in graph_nodes if n.get("type") in ("class", "interface")]),
@@ -5837,6 +5917,17 @@ def modernize_cmd(
                 {"fqn": n["fqn"], "in_degree": n.get("in_degree", 0), "role": n.get("role", "other")}
                 for n in coupling_nodes
             ],
+            # BUG #6 (Broadleaf field test): make the in_degree metric self-describing
+            # so it is not confused with `explain`'s caller count. They differ by design.
+            "high_coupling_nodes_note": (
+                "in_degree = raw count of incoming graph edges across ALL edge types "
+                "(imports, injects, extends/implements, references, annotations), "
+                "counted at symbol level. This is deliberately larger than and NOT "
+                "equal to `sourcecode explain`'s caller count, which reports DISTINCT "
+                "dependent classes (DI dependents + reverse-call-graph callers, "
+                "deduplicated to class level). Use in_degree for blast-radius ranking, "
+                "explain's caller list for the concrete dependents to inspect."
+            ),
             "statically_unreferenced": [
                 {"fqn": n["fqn"], "type": n.get("type", ""), "role": n.get("role", "other")}
                 for n in dead_zones
@@ -5853,14 +5944,15 @@ def modernize_cmd(
             ],
             "subsystem_summary": _subsystem_summary,
             "subsystem_summary_note": _subsystem_summary_note,
-            "cross_module_tangles": [
-                {
-                    "label": s.get("label") or s.get("name") or "",
-                    "class_count": _class_count(s.get("members") or []),
-                    "member_count": len(s.get("members") or []),
-                }
-                for s in tangle_modules
-            ],
+            "cross_module_tangles": _cross_module_tangles,
+            "cross_module_tangles_note": (
+                "Directed inter-subsystem coupling measured from structural graph "
+                "edges (imports/injects/extends/implements/references/calls). "
+                "edge_count = edges from_package→to_package; mutual=true marks a "
+                "bidirectional (cyclic) dependency — the actual tangle that blocks "
+                "independent module extraction. Empty means no cross-subsystem "
+                "structural coupling was detected."
+            ),
             # BUG-05 fix: don't recommend "Start with hotspot_candidates" when the list is empty.
             "recommendation": (
                 (

{sourcecode-1.71.0 → sourcecode-1.73.0}/src/sourcecode/detectors/java.py

@@ -10,7 +10,11 @@ from sourcecode.detectors.base import (
     EntryPoint,
     StackDetection,
 )
-from sourcecode.detectors.parsers import read_text_lines, unique_strings
+from sourcecode.detectors.parsers import (
+    read_text_lines,
+    substitute_maven_properties as _resolve_maven_property,
+    unique_strings,
+)
 from sourcecode.schema import FrameworkDetection
 from sourcecode.tree_utils import flatten_file_tree
 
@@ -55,6 +59,14 @@ _JAX_RS_PROVIDER_RE = re.compile(r'@Provider\b')
 
 # --- CDI / Jakarta EE scopes ---
 _CDI_SCOPED_RE = re.compile(r'@(?:ApplicationScoped|RequestScoped|SessionScoped|Singleton|Dependent)\b')
+# BUG #3: a genuine bootstrap entry declares a real main() or a bootstrap annotation
+# / WAR initializer supertype — never merely a `*Application.java` filename.
+_MAIN_METHOD_RE = re.compile(r'\bstatic\b[^;{}()]*\bmain\s*\(\s*(?:final\s+)?String')
+_BOOTSTRAP_ANNOTATION_RE = re.compile(
+    r'@(?:SpringBootApplication|QuarkusMain|MicronautApplication|'
+    r'EnableAutoConfiguration|SpringBootConfiguration)\b'
+    r'|\bextends\s+SpringBootServletInitializer\b'
+)
 
 # --- Keycloak / Quarkus SPI ---
 # Matches "implements EventListenerProvider" or "implements Foo, EventListenerProvider, Bar"
@@ -151,6 +163,18 @@ class JavaDetector(AbstractDetector):
         # Spring profiles — check src/main/options/, src/main/resources/
         spring_profiles = self._detect_spring_profiles(context.root, all_paths)
 
+        # BUG #4 (Alfresco field test): a `org.mybatis` coordinate in the pom is not
+        # proof the app USES MyBatis mappers. Alfresco declares org.mybatis:mybatis
+        # yet has zero @Mapper interfaces and zero *Mapper.xml — its SQL layer is
+        # iBatis-style *-SqlMap.xml (surfaced separately). Emitting "MyBatis" as an
+        # architecture framework then contradicted the tool's own evidence block
+        # (mapper_interfaces:0, xml_files:0) and mislabeled bean DTO mappers. Keep
+        # the label only with real usage evidence: a *Mapper.xml or an @Mapper interface.
+        if any(f.name == "MyBatis" for f in frameworks) and not self._has_mybatis_usage(
+            context.root, all_paths
+        ):
+            frameworks = [f for f in frameworks if f.name != "MyBatis"]
+
         entry_points = self._collect_entry_points(context)
         transactional_classes = self._collect_transactional_classes(context, all_paths)
         stack = StackDetection(
@@ -211,6 +235,17 @@ class JavaDetector(AbstractDetector):
                                 break
                     break
 
+        # BUG #1 (Alfresco field test): a picked value can be a Maven property
+        # reference — Alfresco's <maven.compiler.source>${java.version}</...> chains
+        # to <java.version>21</java.version> in the SAME <properties> block. Resolve
+        # ${...} references against the pom's own properties so --compact reports the
+        # concrete version ("21") instead of the literal "${java.version}", matching
+        # what migrate-check already surfaces. Bounded iteration guards ref cycles.
+        if "language_version" in result:
+            result["language_version"] = _resolve_maven_property(
+                result["language_version"], props
+            )
+
         return result
 
     def _detect_spring_profiles(self, root: Path, all_paths: list[str]) -> list[str]:
@@ -425,15 +460,25 @@ class JavaDetector(AbstractDetector):
         # Exclude test trees: test helpers like AdminApplication.java in
         # integration/src/test/java/ must not be treated as production entrypoints.
         from sourcecode.path_filters import is_test_path as _is_test_path
+        # BUG #3 (Alfresco field test): a `*Application.java` / `*Main.java` NAME does
+        # not make a file a bootstrap entry point. Alfresco has XSD-generated JAXB
+        # `Application.java` model classes (no main(), no bootstrap annotation) in a
+        # WAR with no own entry point — flagging them as `application` polluted the
+        # executive summary. Emit `kind="application"` ONLY when the file actually
+        # declares a `main(String[])` method or a bootstrap annotation.
         app_candidates = [
-            p for p in all_java
-            if p.endswith(("Application.java", "Main.java"))
-            and not _is_test_path(p)
-        ]
-        entry_points: list[EntryPoint] = [
-            EntryPoint(path=p, stack="java", kind="application", source="manifest")
-            for p in unique_strings(app_candidates)
+            p for p in unique_strings([
+                q for q in all_java
+                if q.endswith(("Application.java", "Main.java")) and not _is_test_path(q)
+            ])
         ]
+        entry_points: list[EntryPoint] = []
+        for p in app_candidates:
+            verified = self._verify_bootstrap_entry(context.root / p)
+            if verified:
+                entry_points.append(EntryPoint(
+                    path=p, stack="java", kind="application", source=verified,
+                ))
 
         # 2. Annotation-based scan: @RestController, @WebFilter, FilterRegistrationBean
         # Prioritize Controller-named files so all REST controllers are detected
@@ -481,6 +526,52 @@ class JavaDetector(AbstractDetector):
                 unique_eps.append(ep)
         return unique_eps
 
+    def _has_mybatis_usage(self, root: Path, all_paths: list[str]) -> bool:
+        """True when the repo shows real MyBatis usage, not just a pom coordinate.
+
+        Evidence = a *Mapper.xml file OR a *Mapper.java carrying the MyBatis
+        @Mapper annotation. iBatis-style *-SqlMap.xml is deliberately NOT counted
+        here — it is a distinct legacy pattern surfaced elsewhere (BUG #4).
+        """
+        if any(p.endswith("Mapper.xml") for p in all_paths):
+            return True
+        from sourcecode.path_filters import is_test_path as _is_test_path
+        mapper_java = [
+            p for p in all_paths
+            if p.endswith("Mapper.java") and not _is_test_path(p)
+        ]
+        for rel in mapper_java[:_MAX_JAVA_ENTRY_SCAN]:
+            try:
+                abs_path = root / rel
+                if abs_path.stat().st_size > _MAX_FILE_SIZE:
+                    continue
+                content = abs_path.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                continue
+            if "org.apache.ibatis.annotations.Mapper" in content or "@Mapper" in content:
+                return True
+        return False
+
+    def _verify_bootstrap_entry(self, abs_path: Path) -> "str | None":
+        """Return the evidence source when *abs_path* is a real bootstrap entry.
+
+        A file is a genuine application entry point only if it declares a
+        `main(String[])` method OR carries a recognized bootstrap annotation /
+        WAR initializer supertype. Returns "main_method" / "bootstrap_annotation"
+        accordingly, else None (name alone is never sufficient — see BUG #3).
+        """
+        try:
+            if abs_path.stat().st_size > _MAX_FILE_SIZE:
+                return None
+            content = abs_path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            return None
+        if _BOOTSTRAP_ANNOTATION_RE.search(content):
+            return "bootstrap_annotation"
+        if _MAIN_METHOD_RE.search(content):
+            return "main_method"
+        return None
+
     def _augment_deep_java_controllers(self, context: DetectionContext, all_java: list[str]) -> None:
         """Scan standard Java source roots for *Controller*.java files not in all_java.
 

{sourcecode-1.71.0 → sourcecode-1.73.0}/src/sourcecode/detectors/parsers.py

@@ -1,10 +1,33 @@
 from __future__ import annotations
 
 import json
+import re
 from collections.abc import Iterable
 from pathlib import Path
 from typing import Any, Optional
 
+_MAVEN_PROP_REF_RE = re.compile(r'\$\{([\w.\-]+)\}')
+
+
+def substitute_maven_properties(text: str, props: "dict[str, str]") -> str:
+    """Resolve Maven ${prop} references in *text* against *props*.
+
+    Shared single source of truth for Maven property resolution across
+    subcommands (BUG #1, Alfresco field test): both the --compact Java-stack
+    detector and migrate-check must resolve `${java.version}` → `21` identically.
+    Multi-level references (${a} where a=${b}) resolve in up to 3 passes; a
+    reference with no matching property is left verbatim (honest, not blanked).
+    """
+    if not props or "${" not in text:
+        return text
+    resolved = text
+    for _ in range(3):
+        new = _MAVEN_PROP_REF_RE.sub(lambda m: props.get(m.group(1), m.group(0)), resolved)
+        if new == resolved:
+            break
+        resolved = new
+    return resolved
+
 
 def load_json_file(path: Path) -> Optional[dict[str, Any]]:
     """Carga un fichero JSON sin lanzar si el contenido es invalido."""

{sourcecode-1.71.0 → sourcecode-1.73.0}/src/sourcecode/explain.py

@@ -298,10 +298,15 @@ def _structural_purpose(
     head = f"Likely {role} (no DI annotations found)" if role else \
         "Likely a structurally significant class (no DI annotations found)"
     signals: list[str] = []
+    # BUG #6 (Broadleaf field test): this counts DISTINCT dependent classes (DI
+    # dependents + reverse-call-graph callers, deduped to class level), which is a
+    # different metric from modernize's node.in_degree (raw incoming-edge count
+    # across ALL edge types, symbol-level). Name it explicitly so the two numbers
+    # are not read as a contradiction when cross-referenced.
     if in_degree >= 3:
-        signals.append(f"high in-degree ({in_degree})")
+        signals.append(f"high fan-in ({in_degree} distinct caller classes)")
     elif in_degree:
-        signals.append(f"in-degree {in_degree}")
+        signals.append(f"{in_degree} distinct caller class{'es' if in_degree != 1 else ''}")
     if lifecycle:
         signals.append(f"lifecycle methods detected ({'/'.join(lifecycle)})")
     suffix = f" — {', '.join(signals)}" if signals else ""