sourcecode 1.71.0__py3-none-any.whl → 1.73.0__py3-none-any.whl

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/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/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/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/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/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 ""

sourcecode/integration_detector.py

@@ -83,6 +83,17 @@ _TOKEN_CLIENTS: "tuple[tuple[str, str, str], ...]" = (
     ("InitialLdapContext", "ldap", "jndi-ldap"),
     ("InitialDirContext", "ldap", "jndi-ldap"),
     ("LdapContext", "ldap", "jndi-ldap"),
+    # Spring Security LDAP authentication (BUG #5, Broadleaf field test): the
+    # idiomatic auth integration is a UserDetails mapper that extends
+    # LdapUserDetailsMapper and consumes DirContextOperations — neither uses
+    # LdapTemplate/ContextSource directly, so the connection-type tokens above
+    # miss it entirely. These types come from spring-security-ldap / spring-ldap
+    # and are unambiguous LDAP integration points.
+    ("LdapUserDetailsMapper", "ldap", "spring-security-ldap"),
+    ("DirContextOperations", "ldap", "spring-ldap"),
+    ("LdapContextSource", "ldap", "spring-ldap"),
+    ("DefaultSpringSecurityContextSource", "ldap", "spring-security-ldap"),
+    ("BindAuthenticator", "ldap", "spring-security-ldap"),
     # Mail / SMTP (JavaMail / Jakarta Mail)
     ("JavaMailSender", "smtp", "spring-mail"),
     ("MimeMessage", "smtp", "javamail"),
@@ -90,12 +101,33 @@ _TOKEN_CLIENTS: "tuple[tuple[str, str, str], ...]" = (
     # JMS / messaging
     ("JmsTemplate", "jms", "jmstemplate"),
     ("ActiveMQConnectionFactory", "jms", "activemq"),
+    # BUG #5 (Alfresco field test): the connection-factory family beyond the plain
+    # ActiveMQConnectionFactory — Alfresco wires ActiveMQSslConnectionFactory and
+    # pooled/caching factories as Spring @Beans, none of which were recognized.
+    ("ActiveMQSslConnectionFactory", "jms", "activemq"),
+    ("PooledConnectionFactory", "jms", "activemq-pooled"),
+    ("CachingConnectionFactory", "jms", "spring-jms"),
 )
 _TOKEN_RES = tuple(
     (re.compile(r"\b" + re.escape(tok) + r"\b"), kind, client)
     for tok, kind, client in _TOKEN_CLIENTS
 )
 
+# BUG #5: Apache Camel route detection. Only applied inside a confirmed Camel file.
+_CAMEL_CONTEXT_RE = re.compile(r"org\.apache\.camel\b|\bextends\s+RouteBuilder\b")
+# A from()/to() endpoint with a literal scheme URI, e.g. from("activemq:queue:foo").
+_CAMEL_URI_RE = re.compile(r'\b(from|to)\s*\(\s*"([a-z][a-z0-9+.\-]*):([^"]*)"')
+# A route anchored by from(<non-string>) — endpoint URI comes from a variable/property.
+_CAMEL_VAR_ROUTE_RE = re.compile(r'\bfrom\s*\(\s*[A-Za-z_]')
+# Camel URI scheme → integration kind (jms-family messaging schemes collapse to "jms").
+_CAMEL_SCHEME_KIND: "dict[str, str]" = {
+    "activemq": "jms", "amq": "jms", "jms": "jms", "sjms": "jms", "sjms2": "jms",
+    "amqp": "jms", "stomp": "jms",
+    "kafka": "kafka", "mqtt": "mqtt", "paho": "mqtt",
+    "http": "http", "https": "http", "http4": "http", "rest": "http",
+    "smtp": "smtp", "smtps": "smtp",
+}
+
 
 def _line_of(text: str, idx: int) -> int:
     """1-based line number of character offset ``idx`` in ``text``."""
@@ -312,6 +344,28 @@ def detect_integrations(file_paths: "list[str]", root: Path) -> dict:
                         _add(kind, client, url.group(1), rel, lineno)
                         break
 
+        # BUG #5 (Alfresco field test): Apache Camel routes are messaging/integration
+        # endpoints declared as a fluent DSL (from(...)/to(...)) inside a RouteBuilder,
+        # NOT as JmsTemplate/connection-factory constructs — so they were invisible.
+        # Only trust from()/to() inside a confirmed Camel file (import org.apache.camel
+        # or `extends RouteBuilder`) to avoid matching unrelated fluent `.to(...)`.
+        if _CAMEL_CONTEXT_RE.search(text):
+            for m in _CAMEL_URI_RE.finditer(text):
+                scheme = m.group(2).lower()
+                uri = f"{scheme}:{m.group(3)}"
+                kind = _CAMEL_SCHEME_KIND.get(scheme, "messaging")
+                _add(kind, f"camel-{scheme}", uri, rel, _line_of(text, m.start()))
+            # Routes whose endpoint URI is a variable/property (Alfresco's
+            # from(sourceQueue).to(targetTopic)) cannot yield a literal target, but the
+            # route IS a real messaging integration point — record it honestly with a
+            # null target and low confidence rather than dropping it.
+            if not any(r["client"].startswith("camel-") and r["evidence"].startswith(f"{rel}:")
+                       for r in records):
+                vm = _CAMEL_VAR_ROUTE_RE.search(text)
+                if vm:
+                    _add("messaging", "camel-route", None, rel,
+                         _line_of(text, vm.start()), confidence="low")
+
     records.sort(key=lambda r: (r["kind"], r["client"], r["evidence"]))
 
     by_kind: "dict[str, int]" = {}

sourcecode/migrate_check.py

@@ -645,6 +645,18 @@ def _classify_code_context(finding: "MigrationFinding") -> str:
     if is_test_or_fixture_path(path):
         return "test"
     norm = path.replace("\\", "/").lower()
+    # BUG #4 (Broadleaf field test): a Spring XML config file can live under
+    # src/main/resources yet be test-only scaffolding loaded exclusively by
+    # test @ContextConfiguration (e.g. bl-applicationContext-test-security.xml).
+    # is_test_or_fixture_path deliberately ignores the filename, so a `test`
+    # marker in the config file's own name is not seen. For XML config, a `test`
+    # token in the base filename is a strong, low-FP test-scope signal —
+    # production context files are not named `-test-`. Keep it out of
+    # blocking_count so test scaffolding never inflates the headline blocker.
+    if norm.endswith(".xml"):
+        base = norm.rsplit("/", 1)[-1]
+        if re.search(r"(?:^|[-_.])test(?:[-_.]|$)", base):
+            return "test"
     if any(frag in norm for frag in _GENERATED_PATH_FRAGMENTS):
         return "generated"
     # javax.annotation.Generated is the marker emitted into autogenerated code.
@@ -936,6 +948,42 @@ def _find_non_java_files(
     return xml_files, build_files
 
 
+def _xml_explanation_for(rule: "_XmlRule", matches: list) -> str:
+    """Return an explanation reflecting the sub-pattern that actually matched.
+
+    BUG #4 (Broadleaf field test): MIG-031's pattern is an OR of two independent
+    triggers — old-style `<http auto-config="true">` and a versioned legacy schema
+    (spring-security-[2-5].x.xsd). The static template asserted BOTH, so a file
+    that only used auto-config (its schema line already being the unversioned
+    spring-security.xsd) got a factually wrong explanation claiming a versioned
+    schema. Emit only the condition(s) present in this file.
+    """
+    if rule.id != "MIG-031":
+        return rule.explanation
+    matched_text = " ".join(m.group(0).lower() for m in matches)
+    has_autoconfig = "auto-config" in matched_text
+    has_versioned_schema = bool(re.search(r"spring-security-[2345]\.", matched_text))
+    triggers: list[str] = []
+    if has_autoconfig:
+        triggers.append(
+            "uses the old-style <http auto-config='true'> shortcut, which was "
+            "removed in Spring Security 6"
+        )
+    if has_versioned_schema:
+        triggers.append(
+            "references a versioned legacy schema (spring-security-[2-5].x.xsd) "
+            "whose namespace attributes changed in Spring Security 6"
+        )
+    if not triggers:  # defensive — pattern matched but neither branch classified
+        return rule.explanation
+    return (
+        "XML-based Spring Security configuration in this file "
+        + " and ".join(triggers)
+        + ". Spring Security 6 (Spring Boot 3) requires migrating this to "
+        "Java-based @Configuration with a SecurityFilterChain @Bean."
+    )
+
+
 def _scan_xml_file(text: str, rel_path: str) -> list["MigrationFinding"]:
     """Apply XML rules to raw XML text. Returns one finding per matched rule."""
     findings: list[MigrationFinding] = []
@@ -947,6 +995,7 @@ def _scan_xml_file(text: str, rel_path: str) -> list["MigrationFinding"]:
             continue
         first_line = text[: matches[0].start()].count("\n") + 1
         snippets = [m.group(0)[:120].strip() for m in matches[:5]]
+        explanation = _xml_explanation_for(rule, matches)
         findings.append(
             MigrationFinding(
                 id=MigrationFinding.make_id(rule.id, rel_path),
@@ -956,7 +1005,7 @@ def _scan_xml_file(text: str, rel_path: str) -> list["MigrationFinding"]:
                 source_file=rel_path,
                 first_line=first_line,
                 imports_found=snippets,
-                explanation=rule.explanation,
+                explanation=explanation,
                 fix_hint=rule.fix_hint,
                 migration_target=rule.migration_target,
                 openrewrite_recipe=rule.openrewrite_recipe,
@@ -1119,18 +1168,10 @@ def _resolve_maven_properties(text: str) -> str:
     props: dict[str, str] = {}
     for m in re.finditer(r'<([A-Za-z][\w.\-]*)>\s*([^<${}]+?)\s*</\1>', text):
         props[m.group(1)] = m.group(2).strip()
-    if not props:
-        return text
-
-    resolved = text
-    for _ in range(3):
-        def _sub(m: re.Match) -> str:  # noqa: E306
-            return props.get(m.group(1), m.group(0))
-        resolved_new = re.sub(r'\$\{([\w.\-]+)\}', _sub, resolved)
-        if resolved_new == resolved:
-            break
-        resolved = resolved_new
-    return resolved
+    # Shared ${...} substitution core (BUG #1): identical resolution semantics as
+    # the --compact Java-stack detector.
+    from sourcecode.detectors.parsers import substitute_maven_properties
+    return substitute_maven_properties(text, props)
 
 
 def _scan_dep_file(text: str, rel_path: str) -> list["MigrationFinding"]:

sourcecode/repository_ir.py

@@ -387,6 +387,59 @@ def _strip_java_comments(source: str) -> str:
     return source
 
 
+# Declaration keyword OR a brace — matched in source order to track nesting when
+# building minimal symbols for pre-scan-skipped files (see _minimal_class_symbols).
+_MIN_DECL_OR_BRACE_RE = re.compile(r'\b(?:class|interface|enum)\s+([A-Z]\w*)|([{}])')
+
+
+def _minimal_class_symbols(
+    source: str, package: str, rel_path: str
+) -> "list[SymbolRecord]":
+    """Nesting-aware class/interface/enum symbols for pre-scan-skipped files.
+
+    Tracks brace depth so a NESTED type gets a fully-qualified `pkg.Outer.Inner`
+    FQN (matching _extract_symbols), never a package-only `pkg.Inner`.
+
+    BUG #2 (Broadleaf field test): the previous fast path emitted every declared
+    type as `f"{pkg}.{name}"`, dropping the enclosing class. Two distinct nested
+    types with the same simple name under different outer classes in one package
+    (Broadleaf has 25 `GroupName` nested classes) therefore collapsed onto ONE
+    colliding FQN, and — since pre-scan-skipped files build no relations — those
+    zero-degree phantom nodes were reported as false `statically_unreferenced`
+    dead code. Qualifying by the enclosing class keeps them distinct and correct.
+    """
+    decl_source = _STRING_LITERAL_RE.sub('', _strip_java_comments(source))
+    syms: "list[SymbolRecord]" = []
+    stack: "list[tuple[str, int]]" = []   # (fqn, brace-depth at which body opened)
+    depth = 0
+    pending_fqn: "Optional[str]" = None
+    for m in _MIN_DECL_OR_BRACE_RE.finditer(decl_source):
+        name = m.group(1)
+        if name is not None:
+            enclosing = stack[-1][0] if stack else None
+            if enclosing:
+                pending_fqn = f"{enclosing}.{name}"
+            else:
+                pending_fqn = f"{package}.{name}" if package else name
+            continue
+        brace = m.group(2)
+        if brace == '{':
+            depth += 1
+            if pending_fqn is not None:
+                stack.append((pending_fqn, depth))
+                syms.append(SymbolRecord(
+                    symbol=pending_fqn, type="class", confidence="medium",
+                    declaring_file=rel_path,
+                ))
+                pending_fqn = None
+        else:  # '}'
+            while stack and stack[-1][1] == depth:
+                stack.pop()
+            if depth > 0:
+                depth -= 1
+    return syms
+
+
 def _parse_annotation_line(line: str) -> tuple[str, str]:
     """Parse annotation name and args from a line starting with '@'.
 
@@ -1127,6 +1180,234 @@ def _build_same_package_map(symbols: list[SymbolRecord]) -> dict[str, dict[str,
     return result
 
 
+# A type-qualified member reference inside an annotation argument, e.g. the
+# `GroupName.General` / `FieldOrder.NAME` in
+# `@AdminPresentation(group = GroupName.General, order = FieldOrder.NAME)`, or the
+# fully-qualified nested form `SystemPropertyAdminPresentation.GroupOrder.General`.
+# group(0) is the whole dotted chain (UpperCamel head + `.member`… tail); the
+# resolver walks the chain through known nested types so a reference to
+# `Outer.Nested.CONST` credits the NESTED holder, not just the outer type.
+_ANN_REF_TOKEN_RE = re.compile(r'\b[A-Z]\w*(?:\.\w+)+')
+# Combined token scanner: an annotation-with-args head, a type declaration, or a
+# brace — matched in source order so annotation references can be attributed to
+# the class whose body encloses them.
+_ANN_OR_DECL_OR_BRACE_RE = re.compile(
+    r'@([A-Z]\w*)\s*\('
+    r'|\b(?:class|interface|enum)\s+([A-Z]\w*)'
+    r'|([{}])'
+)
+
+
+def _extract_annotation_type_refs(
+    source: str, package: str
+) -> "list[tuple[str, str]]":
+    """Return (enclosing_class_fqn, referenced_type_simple_name) pairs.
+
+    Walks the comment/string-stripped source tracking the nesting stack so each
+    type reference found inside an annotation argument list is attributed to the
+    class whose body encloses the annotated member. Member-level annotations sit
+    inside the class body (stack has the class); this is the common case for
+    `@AdminPresentation(group = GroupName.General)` on entity fields.
+    """
+    text = _STRING_LITERAL_RE.sub('""', _strip_java_comments(source))
+    refs: "list[tuple[str, str]]" = []
+    stack: "list[tuple[str, int]]" = []
+    depth = 0
+    pending: "Optional[str]" = None
+    # Type refs found in a CLASS-LEVEL annotation (which precedes the class body,
+    # so the stack does not yet contain the owning class) are held here and
+    # attributed to the class when its body opens — e.g. an interface annotated
+    # `@AdminTabPresentation(name = TabName.General)` that references its OWN
+    # nested constant holders.
+    pending_class_refs: "list[str]" = []
+    n = len(text)
+    idx = 0
+    while idx < n:
+        m = _ANN_OR_DECL_OR_BRACE_RE.search(text, idx)
+        if not m:
+            break
+        ann, cname, brace = m.group(1), m.group(2), m.group(3)
+        if ann is not None:
+            # Balance the annotation's parens and scan its argument text.
+            popen = m.end() - 1
+            d = 0
+            j = popen
+            while j < n:
+                c = text[j]
+                if c == '(':
+                    d += 1
+                elif c == ')':
+                    d -= 1
+                    if d == 0:
+                        break
+                j += 1
+            arg_text = text[popen + 1:j]
+            cur_class = stack[-1][0] if stack else ""
+            for tm in _ANN_REF_TOKEN_RE.finditer(arg_text):
+                if cur_class:
+                    refs.append((cur_class, tm.group(0)))
+                else:
+                    pending_class_refs.append(tm.group(0))
+            idx = j + 1
+            continue
+        if cname is not None:
+            enc = stack[-1][0] if stack else None
+            pending = f"{enc}.{cname}" if enc else (
+                f"{package}.{cname}" if package else cname
+            )
+            idx = m.end()
+            continue
+        if brace == '{':
+            depth += 1
+            if pending is not None:
+                stack.append((pending, depth))
+                # A class-level annotation on this class referenced these types.
+                for head in pending_class_refs:
+                    refs.append((pending, head))
+                pending_class_refs = []
+                pending = None
+        else:  # '}'
+            while stack and stack[-1][1] == depth:
+                stack.pop()
+            if depth > 0:
+                depth -= 1
+        idx = m.end()
+    return refs
+
+
+def _annotation_reference_edges(
+    ref_sources: "list[tuple[str, list[str], list[tuple[str, str]]]]",
+    all_symbols: "list[SymbolRecord]",
+    relations: "list[RelationEdge]",
+    same_pkg_map: "dict[str, dict[str, str]]",
+) -> "list[RelationEdge]":
+    """Emit `references` edges for static constants read inside annotation args.
+
+    BUG #2 (Broadleaf field test): `@AdminPresentation(group = GroupName.General)`
+    is a real reference to the constant-holder nested class `GroupName`, but the
+    static call-graph never counted annotation-argument reads as edges. The
+    referenced nested classes therefore had zero in-degree and were reported as
+    false `statically_unreferenced` dead code (~95% of that list on Broadleaf).
+
+    Resolution for a bare head type T referenced from class C:
+      import / same-package / wildcard  →  direct FQN, else
+      nested-type lookup: a unique repo nested type named T, or — when the simple
+      name is ambiguous (Broadleaf has 25 `GroupName`s) — the one declared by C or
+      one of C's (transitive) supertypes. Unresolvable / ambiguous refs are
+      dropped (honest: no guessed edge).
+    """
+    class_fqns: set[str] = {
+        s.symbol for s in all_symbols
+        if s.type in ("class", "interface") and "#" not in s.symbol
+    }
+    # enclosing_of[nested_fqn] = outer_fqn; nested_by_simple[simple] = {fqns}.
+    enclosing_of: dict[str, str] = {}
+    nested_by_simple: dict[str, set[str]] = {}
+    for fqn in class_fqns:
+        prefix = fqn
+        while True:
+            cut = prefix.rfind(".")
+            if cut < 0:
+                break
+            prefix = prefix[:cut]
+            if prefix in class_fqns:
+                enclosing_of[fqn] = prefix
+                nested_by_simple.setdefault(fqn[len(prefix) + 1:], set()).add(fqn)
+                break
+
+    direct_super: dict[str, set[str]] = {}
+    for e in relations:
+        if e.type in ("extends", "implements"):
+            direct_super.setdefault(e.from_symbol, set()).add(e.to_symbol)
+
+    def _super_closure(fqn: str) -> set[str]:
+        seen: set[str] = set()
+        stack = [fqn]
+        while stack:
+            cur = stack.pop()
+            for sup in direct_super.get(cur, ()):
+                if sup not in seen:
+                    seen.add(sup)
+                    stack.append(sup)
+        return seen
+
+    edges: list[RelationEdge] = []
+    seen_edges: set[tuple[str, str]] = set()
+    for package, raw_imports, ref_pairs in ref_sources:
+        if not ref_pairs:
+            continue
+        import_map: dict[str, str] = {}
+        wildcard_pkgs: list[str] = []
+        for fq in raw_imports:
+            parts = fq.split(".")
+            if parts[-1] == "*":
+                wildcard_pkgs.append(fq[:-2])
+            else:
+                import_map[parts[-1]] = fq
+        pkg_types = same_pkg_map.get(package, {})
+
+        def _resolve_head(head: str, cur_class: str) -> "Optional[str]":
+            fq = import_map.get(head) or pkg_types.get(head)
+            if fq:
+                return fq
+            for wp in wildcard_pkgs:
+                cand = same_pkg_map.get(wp, {}).get(head)
+                if cand:
+                    return cand
+            # cur_class itself may BE the head (self-qualified nested ref).
+            if cur_class.rsplit(".", 1)[-1] == head:
+                return cur_class
+            cands = nested_by_simple.get(head)
+            if not cands:
+                return None
+            if len(cands) == 1:
+                return next(iter(cands))
+            allowed = {cur_class} | _super_closure(cur_class)
+            matched = [c for c in cands if enclosing_of.get(c) in allowed]
+            if len(matched) == 1:
+                return matched[0]
+            self_nested = f"{cur_class}.{head}"
+            if self_nested in cands:
+                return self_nested
+            return None
+
+        def _resolve_chain(chain: str, cur_class: str) -> "Optional[str]":
+            parts = chain.split(".")
+            fqn = _resolve_head(parts[0], cur_class)
+            if not fqn:
+                return None
+            # Walk the remaining segments through KNOWN nested types so a
+            # `Outer.Nested.CONST` reference credits the nested holder actually read,
+            # not merely the outer type. Stop at the first non-type segment (the
+            # constant/field), which is the deepest resolvable class.
+            for seg in parts[1:]:
+                nxt = f"{fqn}.{seg}"
+                if nxt in class_fqns:
+                    fqn = nxt
+                else:
+                    break
+            return fqn
+
+        for cur_class, chain in ref_pairs:
+            if cur_class not in class_fqns:
+                continue
+            target = _resolve_chain(chain, cur_class)
+            if not target or target == cur_class or target not in class_fqns:
+                continue
+            key = (cur_class, target)
+            if key in seen_edges:
+                continue
+            seen_edges.add(key)
+            edges.append(RelationEdge(
+                from_symbol=cur_class,
+                to_symbol=target,
+                type="references",
+                confidence="high",
+                evidence={"type": "annotation_value", "value": chain},
+            ))
+    return edges
+
+
 # Reserved words that read like calls (`if (`, `for (`, …). Can never be sibling
 # method names (Java reserves them), but guard the intra-class scan anyway.
 _CALL_KEYWORDS: frozenset[str] = frozenset({
@@ -3374,6 +3655,9 @@ def build_repo_ir(
     )
 
     _per_file: list[tuple[str, str, str, list[str], list[SymbolRecord]]] = []
+    # (package, imports, annotation-ref-pairs) for the reference-graph post-pass,
+    # collected from BOTH fully-parsed and pre-scan-skipped files (BUG #2).
+    _ann_ref_sources: list[tuple[str, list[str], list[tuple[str, str]]]] = []
     for rel_path in sorted(file_paths):
         abs_path = root / rel_path
         try:
@@ -3400,23 +3684,31 @@ def build_repo_ir(
             # literals before scanning so only real declarations are captured. The name
             # must also start uppercase ([A-Z]) — Java type convention, matching the
             # precision of the full _CLASS_DECL_RE used on annotated files.
-            _decl_source = _STRING_LITERAL_RE.sub('', _strip_java_comments(source))
-            _min_syms: list[SymbolRecord] = []
-            for _cm in re.finditer(r'\b(?:class|interface|enum)\s+([A-Z]\w*)', _decl_source):
-                _cls_name = _cm.group(1)
-                _fqn = f"{_pkg}.{_cls_name}" if _pkg else _cls_name
-                _min_syms.append(SymbolRecord(
-                    symbol=_fqn, type="class", confidence="medium",
-                    declaring_file=rel_path,
-                ))
+            _min_syms = _minimal_class_symbols(source, _pkg, rel_path)
             all_symbols.extend(_min_syms)
-            # No relations needed for non-annotated files
+            # No relations needed for non-annotated files. BUG #2: but a pre-scan-
+            # skipped file can still hold annotation-argument constant references —
+            # e.g. a presentation interface whose class-level @AdminTabPresentation
+            # references its own nested TabName/TabOrder holders. Capture those refs
+            # (cheaply, no full parse) so the reference-graph post-pass can resolve
+            # them and the holders are not flagged as false dead code.
+            if "@" in source:
+                _skipped_refs = _extract_annotation_type_refs(source, _pkg)
+                if _skipped_refs:
+                    _imports = re.findall(
+                        r'^\s*import\s+(?:static\s+)?([\w.]+)\s*;', source, re.MULTILINE
+                    )
+                    _ann_ref_sources.append((_pkg, _imports, _skipped_refs))
             continue
         package, symbols, raw_imports = _extract_symbols(
             source, rel_path, extra_capture=_extra_capture
         )
         all_symbols.extend(symbols)
         _per_file.append((rel_path, source, package, raw_imports, symbols))
+        if "@" in source:
+            _parsed_refs = _extract_annotation_type_refs(source, package)
+            if _parsed_refs:
+                _ann_ref_sources.append((package, raw_imports, _parsed_refs))
 
     # Build {package: {simple_name: FQN}} from every class/interface found.
     _same_pkg_map: dict[str, dict[str, str]] = _build_same_package_map(all_symbols)
@@ -3454,6 +3746,15 @@ def build_repo_ir(
 
         all_relations.extend(relations)
 
+    # BUG #2 (Broadleaf): annotation-argument static-constant reads
+    # (@Anno(attr = SomeType.CONST)) are real references — emit them as edges so
+    # constant-holder types are not reported as zero-caller dead code. Runs as a
+    # global post-pass because bare inherited-nested references (e.g. `GroupName`
+    # from an implemented interface) need the repo-wide supertype/nested index.
+    all_relations.extend(
+        _annotation_reference_edges(_ann_ref_sources, all_symbols, all_relations, _same_pkg_map)
+    )
+
     spring_summary = _build_spring_summary(all_symbols)
 
     # Deduplicate relations
@@ -4434,6 +4735,41 @@ def extract_java_endpoints(root: Path) -> "dict[str, Any]":
                 f"endpoints only."
             )
         result.setdefault("warnings", []).append(_msg)
+
+    # BUG #7 (Alfresco field test): a bare "total: 0" must never be read by an
+    # automated consumer as "this service exposes no public API". Emit a first-class
+    # structured `zero_result_reason` (mirroring integrations.coverage_note /
+    # security_model_detail.reason) naming the routing patterns that WERE searched and
+    # any non-Spring surface detected, so a 0 is understood as "no RECOGNIZED pattern",
+    # not "no surface". Only when the Spring/annotation surface is genuinely empty.
+    if not endpoints:
+        _searched = (
+            "@RestController/@Controller + @RequestMapping/@GetMapping/@PostMapping/"
+            "@PutMapping/@DeleteMapping/@PatchMapping, JAX-RS @Path, functional "
+            "RouterFunction routing, and OpenAPI-spec-recovered routes"
+        )
+        if _nonspring_total:
+            _fw_names = {
+                "webscripts": "Alfresco WebScripts (XML descriptor + handler class)",
+                "jax_rs": "JAX-RS",
+                "servlets": "mapped Servlets",
+            }
+            _detected = ", ".join(
+                _fw_names.get(k, k) for k, v in _nonspring.items() if v
+            )
+            result["zero_result_reason"] = (
+                f"0 endpoints recognized. Searched: {_searched}. A NON-Spring REST "
+                f"surface WAS detected ({_detected}) but is not statically modeled — "
+                f"do NOT read this as 'no public API'. Inspect that framework's routing "
+                f"(e.g. *.desc.xml descriptors for WebScripts) to enumerate the surface."
+            )
+        else:
+            result["zero_result_reason"] = (
+                f"0 endpoints recognized. Searched: {_searched}. No recognized routing "
+                f"construct was found; a framework this analyzer does not model may "
+                f"still expose an HTTP surface — verify manually before concluding the "
+                f"service has no public API."
+            )
     return result
 
 

sourcecode/serializer.py

@@ -702,7 +702,12 @@ def _bootstrap_structured(eps: list) -> "Optional[dict[str, Any]]":
         kind = getattr(ep, "kind", "")
         stem = _Path(path).stem
 
-        if kind == "application" or any(k in stem for k in ("Application", "Main", "Initializer", "Bootstrap")):
+        # BUG #3 (Alfresco field test): bootstrap membership is driven by the
+        # VERIFIED entry kind ("application" is emitted only when the detector
+        # confirmed a main()/bootstrap annotation), never by a `*Application*`
+        # filename alone — XSD-generated Application.java model classes must not
+        # appear here.
+        if kind == "application":
             if path not in seen_b:
                 seen_b.add(path)
                 bootstrap.append(path)

sourcecode/spring_security_audit.py

@@ -491,6 +491,17 @@ def run_security_audit(
         limitations=_sec_limitations,
         metadata={
             "endpoints_analyzed": len(cir.endpoints),
+            "endpoints_analyzed_note": (
+                "Count of canonical endpoints analyzed for security: Spring-MVC/JAX-RS "
+                "annotated handlers plus OpenAPI-spec-recovered routes. Built from the "
+                "SAME route surface as the `endpoints` command and with the SAME "
+                "exclusion of framework dynamic-admin FQN-shaped paths, but "
+                "DEDUPLICATED by (method, path, controller, handler) — so this value is "
+                "<= the `endpoints` command total, the small difference being "
+                "multi-prefix routes that collapse to one canonical endpoint here. It "
+                "does not include the non-Spring REST surface (`endpoints` reports that "
+                "separately under non_spring_rest_surface)."
+            ),
             "security_model": cir.metadata.get("security_model", "unknown"),
             "analysis_time_ms": elapsed_ms,
         },

sourcecode/spring_tx_analyzer.py

@@ -56,13 +56,61 @@ _WRITE_METHOD_RE = re.compile(
 # _CATCH_SWALLOW_RE is retained for reference but replaced by brace-counting
 # extraction in _has_swallowed_exception to avoid false positives from nested
 # braces (nested if/try blocks inside catch terminating the match prematurely).
-_CATCH_HEADER_RE = re.compile(r'\bcatch\s*\([^)]+\)\s*\{')
+_CATCH_HEADER_RE = re.compile(r'\bcatch\s*\(([^)]+)\)\s*\{')
 _LOG_IN_CATCH_RE = re.compile(r'\b(?:log|logger|LOG|System\.out|e\.print)\b')
 _RETHROW_IN_CATCH_RE = re.compile(r'\bthrow\b')
 # Non-trivial return (method call) inside a catch block indicates recovery, not
 # silent swallowing — e.g. `return findNextId(idType)` after creating a missing row.
 _RECOVERY_RETURN_RE = re.compile(r'\breturn\s+\w[\w.<>]*\s*\(')
 
+# Exception types whose catch is a documented part of normal control flow, not a
+# masked failure. Catching these is the standard JPA/Spring-Data idiom (e.g.
+# Query.getSingleResult() throws NoResultException by contract when 0 rows match;
+# a tolerant insert catches EntityExistsException on a race). Catching one of
+# these must never trigger TX-005. (Broadleaf field test: 4/4 TX-005 findings
+# were this idiom — 100% FP rate.)
+_EXPECTED_CONTROL_FLOW_EXCEPTIONS = frozenset({
+    "NoResultException",
+    "NonUniqueResultException",
+    "EntityExistsException",
+    "EntityNotFoundException",
+    "EmptyResultDataAccessException",
+    "IncorrectResultSizeDataAccessException",
+})
+# A caught type is "expected" if any of its simple-name tokens is in the set above.
+_CATCH_TYPE_TOKEN_RE = re.compile(r'[A-Za-z_][A-Za-z0-9_.]*')
+# Lexical markers of a deliberate, developer-documented no-op inside a catch block.
+# When the catch body's leading comment says the swallow is intentional, TX-005 is
+# not reporting a bug — it is second-guessing an explicit decision.
+_INTENTIONAL_SWALLOW_COMMENT_RE = re.compile(
+    r'(?://|/\*|\*)[^\n]*?\b('
+    r'intentional|intentionally|acceptable|expected|'
+    r'do\s+nothing|no[\s\-]?op|noop|ignore[ds]?|ignoring|'
+    r'on\s+purpose|safe\s+to\s+ignore|by\s+design|not\s+an?\s+error'
+    r')\b',
+    re.IGNORECASE,
+)
+
+
+def _caught_types(catch_header_inner: str) -> list[str]:
+    """Extract caught exception simple-name tokens from a catch header inner text.
+
+    `catch_header_inner` is the text inside the parens, e.g.
+    "NoResultException nre" or "IllegalStateException | IOException e".
+    Returns simple names only (last dotted segment), lowercase-preserving.
+    """
+    # Drop the trailing variable name; split multi-catch on '|'.
+    types: list[str] = []
+    for alt in catch_header_inner.split('|'):
+        toks = _CATCH_TYPE_TOKEN_RE.findall(alt)
+        # First token(s) are the type; the last bare identifier is the var name.
+        # A type token contains '.' or starts uppercase; the var name is lowercase.
+        for tok in toks:
+            simple = tok.rsplit('.', 1)[-1]
+            if simple and simple[0].isupper():
+                types.append(simple)
+    return types
+
 
 def _extract_method_body(source: str, method_name: str) -> str:
     """Extract the first method body matching method_name using brace counting.
@@ -597,7 +645,7 @@ class _TX005ExceptionSwallowing:
                     depth -= 1
                 i += 1
             body = source[brace_pos:i]
-            for catch_block in self._extract_catch_blocks(body):
+            for caught_header, catch_block in self._extract_catch_blocks(body):
                 if not _LOG_IN_CATCH_RE.search(catch_block):
                     continue
                 if _RETHROW_IN_CATCH_RE.search(catch_block):
@@ -605,18 +653,31 @@ class _TX005ExceptionSwallowing:
                 # Non-trivial return (method call) indicates recovery, not swallowing.
                 if _RECOVERY_RETURN_RE.search(catch_block):
                     continue
+                # Catching an exception that is part of normal control flow (JPA
+                # getSingleResult / tolerant insert) is not error-masking — skip.
+                caught = _caught_types(caught_header)
+                if any(t in _EXPECTED_CONTROL_FLOW_EXCEPTIONS for t in caught):
+                    continue
+                # A developer-documented deliberate no-op is an explicit decision,
+                # not a bug the tool should flag.
+                if _INTENTIONAL_SWALLOW_COMMENT_RE.search(catch_block):
+                    continue
                 return True
         return False
 
     @staticmethod
-    def _extract_catch_blocks(body: str) -> list[str]:
-        """Extract full catch block bodies from a method body using brace counting.
-
-        Handles nested braces correctly — unlike a simple [^}]* regex which
-        terminates at the first nested '}' inside the catch block.
+    def _extract_catch_blocks(body: str) -> list[tuple[str, str]]:
+        """Extract (caught-type-header, catch-body) pairs from a method body.
+
+        Uses brace counting so nested braces inside the catch body do not
+        terminate the match prematurely (unlike a simple [^}]* regex). The
+        caught-type-header is the text inside the catch parens (e.g.
+        "NoResultException nre"), used to distinguish expected-control-flow
+        exceptions from genuinely swallowed failures.
         """
-        blocks: list[str] = []
+        blocks: list[tuple[str, str]] = []
         for m in _CATCH_HEADER_RE.finditer(body):
+            header_inner = m.group(1)
             brace_pos = m.end() - 1
             depth = 1
             i = brace_pos + 1
@@ -627,7 +688,7 @@ class _TX005ExceptionSwallowing:
                 elif c == '}':
                     depth -= 1
                 i += 1
-            blocks.append(body[brace_pos:i])
+            blocks.append((header_inner, body[brace_pos:i]))
         return blocks
 
 

{sourcecode-1.71.0.dist-info → sourcecode-1.73.0.dist-info}/METADATA

@@ -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.dist-info → sourcecode-1.73.0.dist-info}/RECORD

@@ -1,13 +1,13 @@
-sourcecode/__init__.py,sha256=y7H6BpC2bXN93kgVpSIJ6MrHneDY6yl0VNPo_qOu4Ts,103
+sourcecode/__init__.py,sha256=5AfqhGbJzMplmuXdrkAIi2e7-XhaUzzC_uaeeU_260s,103
 sourcecode/adaptive_scanner.py,sha256=XffluXKzJUXrMtjEiAOnSNPZnztdIcts17T9ouHeID0,10521
 sourcecode/architecture_analyzer.py,sha256=r_xf-SWXwUm3nVQMCSXHJ3M8zKsQP7Ze8Nqf6TVLRq8,45998
 sourcecode/architecture_summary.py,sha256=UaxmUU77oTlWxttMU3c6PxHrU-Q6q5N31TeU_NWWTdU,24297
 sourcecode/ast_extractor.py,sha256=sa6CmLpn-k5G3_Hzxn8hAlZ5-TS-EVzXDD0Gvxd2jzs,50613
 sourcecode/cache.py,sha256=1V3vsaODAa2UBJAC0xpvxpmRdriCezQx5Q8JCcfgziE,31892
-sourcecode/canonical_ir.py,sha256=DEwucOPJguLsVtg5cV8mWXNi112l5jmBhv73KGGebVk,24849
+sourcecode/canonical_ir.py,sha256=IftvTlokcSLbZYHjXQu55FnS_X1LU9bXGsGxm6ujPtw,25793
 sourcecode/cir_graphs.py,sha256=9G0HHj1kw2325IDyzo2OpX73BNswEckecf4MZUXB4JM,12078
 sourcecode/classifier.py,sha256=YTTCoRdcLEFRVcql9Ow1dE7eYQj0jq2rgx32bRDnb1k,13852
-sourcecode/cli.py,sha256=VqAiGRauTO-s8yBJh2JMldha3VKx0jTXC0tOvRpWQkI,283297
+sourcecode/cli.py,sha256=UTcQWF3BGvEZ9I-gPyU9LYDGa-8AmNa_jQYO96hTAqw,288485
 sourcecode/code_notes_analyzer.py,sha256=EJemNCNc9Dn-1RZYu-aNbK0ELzmsyC4s6FdHi3XyNEI,9392
 sourcecode/confidence_analyzer.py,sha256=_jckZSxksV-OU38vbkxfVNBnWCtlCq8Vwfg23x1uspA,19054
 sourcecode/context_scorer.py,sha256=QpChSpsmaAYz91rXA4Ue5xzQmNz_ZboZN09YOHScq1U,14679
@@ -20,7 +20,7 @@ sourcecode/doc_analyzer.py,sha256=05bjTUbDbmnbajD_cgRnACzS8T7xxBKVX4CjkJlhZg8,24
 sourcecode/entrypoint_classifier.py,sha256=jhTYlyqDJH2AtdEcLVaRU3lYRTJuF8DkxVzl4-W3zWE,5322
 sourcecode/env_analyzer.py,sha256=aNTyYgQk5noJDfJU6FmasmESOHfiomyJw5EvZqjy6qc,22213
 sourcecode/error_schema.py,sha256=uwosfNaSujtYm11_732Hu92z5ITV040fQDaIyefSvR4,1683
-sourcecode/explain.py,sha256=GbcruAyzlmseV3o2rjeyxGQxToCfSYHJjKG3N05NVbQ,19897
+sourcecode/explain.py,sha256=2Og-r74yUm38wAF6qD28Gt0jxi1Ygdx33hwp6-NH0xs,20348
 sourcecode/file_chunker.py,sha256=3vkM3mDQ5eE_yTPvUgjyjpGFBIjkW6_mrBmIbrylnA8,16444
 sourcecode/file_classifier.py,sha256=A0fEABqtfVu1MfoaxnPAvGpZgneGgVXlJDhT74NYXxE,15314
 sourcecode/flow_analyzer.py,sha256=dSiuY4w49k29jW_EPXUOND9B5uVbuCA7kjnuHi-pIWA,28781
@@ -29,12 +29,12 @@ sourcecode/fqn_utils.py,sha256=XLU7zDkNBXz_RZkIUNfpPmp1nekWtqP-fxV92tDV1vg,2158
 sourcecode/git_analyzer.py,sha256=JStxTQXNjBWi_wLdwhsZs9mT-v50cSJIz4Agzn6Kh9I,13362
 sourcecode/graph_analyzer.py,sha256=DHR8fY69oU_Pi4SYaWboX6EoEFrctQKB9dsjpqwGMzw,62403
 sourcecode/hibernate_strat.py,sha256=h0leIhlWvSjYq3F99LxvLIDLrJ-xPYxWAREG4LkqZ-4,61190
-sourcecode/integration_detector.py,sha256=HlVdiVki7i62t3pJ0lRjTQQ7WZqPDcPLTqBGAfjFjVQ,17883
+sourcecode/integration_detector.py,sha256=9_SeZQXcatdoCfxl9ciSbRJ84IQkSJooAcv0Efh9FgM,21376
 sourcecode/jdk_exports.py,sha256=fCrlwNAXUT9gge_joq6kMnY3zJxYB2pxqy-0w3o3MJI,874
 sourcecode/license.py,sha256=wckiLuiwaE35KMCStUf1gYzleJuFe6qsSyxUQJvit3s,23500
 sourcecode/mcp_nudge.py,sha256=5ELU_ixzh6uA83NXLOZT8h00OhL53okfQdji3jyKOjg,2917
 sourcecode/metrics_analyzer.py,sha256=m0ENgtqKeBL17kUIK3fmGkgo7UfXBNHxCMj0H_Y5K7c,22750
-sourcecode/migrate_check.py,sha256=VyA-2n5J1Cqf1XxhQ143pf5Y7IvGwolMM1F4OCLOOaU,102628
+sourcecode/migrate_check.py,sha256=Fz12IrMTQWjvbT7melwJGf1aNqQDtzbyRPd_bDA7hdw,105025
 sourcecode/openapi_surface.py,sha256=BTt0K-woZbkbWTN77IkqeBm_Okag9owR0848fmot8sk,16207
 sourcecode/output_budget.py,sha256=Js9yUlfQtPhqBl9R6wn_9UHVjjJc3GtLcqyfjf5t50Q,9869
 sourcecode/path_filters.py,sha256=VnaD9jxZVNzluackNSTCdIddwzAqIseuSCs_A-gpCDM,6898
@@ -47,21 +47,21 @@ sourcecode/redactor.py,sha256=SB4hwIvg8h-hvcqKcDWaZvA-aSyn-at-BIRwa0tUv5E,3227
 sourcecode/relevance_scorer.py,sha256=0AgEt4KrV73nioMqBgjhGjtY7L2C7L7cSyKtj3IKcrw,9408
 sourcecode/rename_refactor.py,sha256=h6dNFlB9aZ_3q6heeHBkgXQeXaT03nvPSsYH6P8qxFg,12965
 sourcecode/repo_classifier.py,sha256=FG1vaWKdWXsWdl-S8hjVMiTqcwgaRXkDyvK4rPcOGtQ,22681
-sourcecode/repository_ir.py,sha256=tj3e_uxkVGTRWfzkf2YoGO-oGakSO4DmWrUQow0dFGk,231201
+sourcecode/repository_ir.py,sha256=YUuyWIFeUve26RGaWPIk1Qbj04u6sTyR1-qPs-gYznM,245995
 sourcecode/ris.py,sha256=RcqLVwC-doFcKKViYDkCjZLBqf_wzLES7-F6vHEeWzE,20419
 sourcecode/runtime_classifier.py,sha256=uTAD6BDCiBLUZEDRfqk718kM4RTT_vAbfkcOI2_Xx58,18432
 sourcecode/scanner.py,sha256=WdOQ78mMzjR1NjmKTlbxdgwinnCTfAhxCVLBEFQiFHU,8899
 sourcecode/schema.py,sha256=aHNXDf8LGyUC8ZDE_VS9kiskC2-Oswhi_WnpdGy6HDw,24897
 sourcecode/security_config.py,sha256=_m8oQAy2gP7Ho2I-IIMTFFjFVWbJIGlLEOiAWK2TDjs,3503
 sourcecode/semantic_analyzer.py,sha256=4OdG6tTSnTvq3_dSWMbQu8Ad1ndSCKeG-b9qM4hIxkw,89176
-sourcecode/serializer.py,sha256=MSxYZ-_UYDPKMvg-hVk-MnKN-TfrmxXL202siCssa9U,129110
+sourcecode/serializer.py,sha256=hv5pQQQa20XxPwcKLlLAgvXwWubm-B-cgQept6x-H7U,129373
 sourcecode/spring_event_topology.py,sha256=5_ON_21Le5zbG-1GRc5GLIi5HJfy_QjcXLVPC5WeUGQ,18055
 sourcecode/spring_findings.py,sha256=G7Or2lKBUQbcTDqudLvSs9XvNg_YoAa-_lBOG_ULs8E,5457
 sourcecode/spring_impact.py,sha256=1Eu1vkdwTVsw92iBEJDe_i_FaSf4uGH9Rb0eSgIAAZc,57542
 sourcecode/spring_model.py,sha256=zOAgFmrRbG4a6KLm1TJl55aWMyPNsz3OS3FSczqPG6A,16594
-sourcecode/spring_security_audit.py,sha256=XtPJ1SXlZJ8k6VYmaWuAp7Bbir4UmreAL7doIGQ5I7o,20595
+sourcecode/spring_security_audit.py,sha256=xrdv3MaR_m2wblA6a8MRWM7attvZeoPXKsoRO_R2lY4,21401
 sourcecode/spring_semantic.py,sha256=O1nKSGVzlukuxLHQVuCPxc-XrcrMFxwlHA20_dmEGgM,13307
-sourcecode/spring_tx_analyzer.py,sha256=FdFcyqPp3aT9oJ-PKrnXcTA6s69wdvzG-NBm0GMGPTU,30717
+sourcecode/spring_tx_analyzer.py,sha256=iH9mK0Tgvhgy_Ee2r13KA_RMf8HKN-pjCKQGuyCCBjM,33812
 sourcecode/summarizer.py,sha256=hV-kPFXXh15GnIvmLZnmVWTEbmr35C-yKVtPiR25U2g,21802
 sourcecode/tree_utils.py,sha256=8GAkIfQAsvtEudIeW1l4ooH_oRtrWR8cpJQJsEa_Pfw,2093
 sourcecode/validation_surface.py,sha256=2Ojfzhw9R4XpemAFqb9RXf4FKyI3DYjGo4Dp0AHZMQo,22600
@@ -76,10 +76,10 @@ sourcecode/detectors/elixir.py,sha256=jCpvt5Yi6jvplc80ovRtWh17q-11ZGo9qX7o8b57TJ
 sourcecode/detectors/go.py,sha256=2r66uRQfeTWsqxr4HDhT6vExZErby0t46QXLHVBRv9w,2782
 sourcecode/detectors/heuristic.py,sha256=7cRxrip4yIaggYzZJB6ef8yHKh-gHgiH_pXMFcjlyFU,3723
 sourcecode/detectors/hybrid.py,sha256=IGFRUVsAZ1ooRlFdznCeJAV6vy1yVDx-VyghvLtddXc,9101
-sourcecode/detectors/java.py,sha256=hyAlTo8_y-tzNVun3zvHmWN8RdG--sdLquCI7fQBAVc,34263
+sourcecode/detectors/java.py,sha256=xlp4mqd26QWJf3MWqmTbD0IND_VEVzPHlGaLC4MNXNA,39028
 sourcecode/detectors/jvm_ext.py,sha256=EgHJ5W8EE-ZTN9V607mVzohyKgZE8Mc2jCi-DF8RAZU,2616
 sourcecode/detectors/nodejs.py,sha256=Hg3Gmr7yIMJFiLoDwOTk2wtu00wxIs6kZf-oQujTFUA,13187
-sourcecode/detectors/parsers.py,sha256=ugPg8yNUf0Ai1gA7Fnn6wAkYGFjTxRodSP3IeViYJJ4,2290
+sourcecode/detectors/parsers.py,sha256=ug9K31tyHqinmv0HkIVQVjdTZpBv67FYKAEf52YXOSM,3178
 sourcecode/detectors/php.py,sha256=W_AQD0WMVDdWHa9h_ilX6W8XSpz0X4ctpMK2WXfXf1I,1887
 sourcecode/detectors/project.py,sha256=ghWWOlqg2_uywzeZX573CCkFWQPlc8bBGvvX1BfIDYI,8315
 sourcecode/detectors/python.py,sha256=i2_Wtk_p0BJx5R8gBQ8NaQByzJ8zEfZkw9NNpKlvOYM,10486
@@ -104,8 +104,8 @@ sourcecode/telemetry/consent.py,sha256=H5z2Wu63pZqbaKucRPoJQJ0zCo4cke9ZlBrJC-MaW
 sourcecode/telemetry/events.py,sha256=LtzYfaX9Ilckj5PTvAcTpDa9mLqDsYPDUiDkRa58piY,2580
 sourcecode/telemetry/filters.py,sha256=NHa5T-6DaZduQPFuC34jOqHWQgSizM-Ygq8aZ4j19ng,5834
 sourcecode/telemetry/transport.py,sha256=4gGHsq0WeY9VywEZXA3vUxykfiYnw9uuqfjAAec7F8o,1681
-sourcecode-1.71.0.dist-info/METADATA,sha256=w75cRYv8E561ZW0S1KTAry6BealPGHv20TwuZgW-NGM,48339
-sourcecode-1.71.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-1.71.0.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
-sourcecode-1.71.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-1.71.0.dist-info/RECORD,,
+sourcecode-1.73.0.dist-info/METADATA,sha256=s089V_1fTpsg8m9aRjhv4mv0miXocG_qV5uAyzr2L60,48339
+sourcecode-1.73.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-1.73.0.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
+sourcecode-1.73.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-1.73.0.dist-info/RECORD,,