sourcecode 2.1.0__tar.gz → 2.2.0__tar.gz

{sourcecode-2.1.0 → sourcecode-2.2.0}/CHANGELOG.md

@@ -1,5 +1,80 @@
 # Changelog
 
+## [2.2.0] — 2026-07-12
+
+**Field-validation hardening — narrative/reporting-layer correctness across the
+audit corpus.** A refute-first pass over ten real repositories fixed a batch of
+mislabeling and miscount bugs where the headline framing contradicted the
+structured output the engine had already produced. No Semantic IR change — every
+fix is in the reporting/narrative layer and reuses facts already extracted.
+
+### Fixed
+
+- **`endpoints` — modeled JAX-RS no longer double-reported as un-modeled surface
+  (A2).** `_build_route_surface` fully models JAX-RS, but `extract_java_endpoints`
+  also counted every `@Path` file into `non_spring_rest_surface{modeled:false}` and
+  warned "count covers Spring-MVC-annotated endpoints only" — contradicting the
+  JAX-RS routes just emitted (18 on eureka, 689 on keycloak). Modeled routes now
+  carry framework provenance (`jax_rs`/`spring_mvc`); when JAX-RS routes were
+  modeled, `jax_rs` is dropped from the un-modeled surface. Genuinely un-modeled
+  surfaces (WebScripts/Servlets, or JAX-RS that produced no route) still surface and
+  still warn.
+- **`spring-audit` — overloaded `@Transactional` methods counted separately (A1).**
+  `TransactionBoundaryIndex.by_symbol` is keyed by signature-less FQN, so overloaded
+  methods (`findAll()` / `findAll(Pageable)`) collapsed to one entry and `stats()`
+  undercounted. A new `all_declared` list (one entry per site) drives the count
+  (petclinic 1→2, matching source); FQN-keyed lookups are unchanged.
+- **`spring-audit` — per-site TX overloads no longer hidden by `by_symbol` collapse
+  (A1-RESIDUAL).** TX-001 (proxy-bypass) and TX-005 (exception-swallow) are per-site
+  checks but iterated the collapsed FQN map; a non-risky overload could overwrite a
+  risky one sharing an FQN, silently dropping the finding. Both now iterate
+  `all_declared` with a dedupe guard. Corpus TX counts unchanged (the residual was
+  latent).
+- **`compact` — Spring Boot version surfaced from pom property (A3).** `--compact`
+  deployment omitted the Boot version when it lived in a `<spring.boot.version>`
+  property rather than the starter-parent, while `migrate-check` resolved it. The
+  serializer now falls back to the property-resolving detector (single source of
+  truth), gated on Boot presence so non-Boot repos gain no phantom version
+  (Broadleaf 3.5.14, consistent).
+- **`endpoints` — `Map.put("/", literal)` no longer treated as a router-DSL route
+  (B1).** The router-DSL detector matched an HTTP-verb name + `"/"` first arg; a
+  plain map write (`swapChars.put("/", "slash")`) was reported as a `PUT /`
+  endpoint. A negative lookahead now rejects a literal second argument — a handler
+  is never a bare literal (openmrs 3→2, jobrunr 12/12 kept).
+- **`endpoints` — test-suite module controllers excluded from entry points (B2).**
+  A scaffolding `@Controller` in openmrs' `test-suite` module (sources under
+  `src/main`) surfaced as a production entry point. Entry-point collection now uses
+  the broader `is_test_or_fixture_path`, and `test-suite`/`test-suites` are
+  recognized test-module segments (openmrs 19→18; petclinic/eureka/keycloak
+  unchanged).
+- **`stack` — JAX-RS API surfaced in the headline stack from source annotations
+  (C1).** Eureka reported `project_type=library` with an empty stack despite 18
+  JAX-RS routes, because the manifest scan has no Jersey/Guice/jsr311 vocabulary and
+  (for gradle) reads only the root build file. When the `.java` scan found JAX-RS
+  entry points and no Jakarta EE framework was inferred, the stack now surfaces
+  `Jakarta EE` from the `@Path`/`@GET` evidence (eureka → `Java rest api using
+  Jakarta EE`). Manifest-only jsr311 still infers nothing (honesty preserved).
+
+### Changed
+
+- **`modernize` — cyclic tangles distinguished from one-way deps in
+  `cross_module_tangles` (TANGLE-1).** A directional dependency is normal layering,
+  not a tangle. Each entry now carries `coupling_type` (`cyclic` when mutual, else
+  `directional`); the note and recommendation state only cyclic entries are real
+  tangles. The key is retained (mcp/USER_GUIDE/tests reference it); cyclic entries
+  still sort first.
+- **CLI — consistent progress spinner across all long-running commands (UX-1).** The
+  TTY-gated progress spinner ran on only 5 code paths; the slowest commands
+  (`spring-audit`, `validation`, `migrate-check`, `endpoints`, `export`,
+  `impact-chain`, `pr-impact`, `explain`) ran silent. All 9 now show the same
+  stderr-only, TTY/CI-gated indicator (never pollutes stdout JSON, zero cost in CI).
+
+### Notes
+
+- No breaking changes. All fixes are reporting/narrative-layer; the Semantic IR and
+  default JSON schemas are unchanged (`cross_module_tangles` gains an additive
+  `coupling_type` field). 3193 tests passing.
+
 ## [2.1.0] — 2026-07-10
 
 **Robustness & Security Inference — vendor-agnostic security & validation posture.**

{sourcecode-2.1.0 → sourcecode-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 2.1.0
+Version: 2.2.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
@@ -38,11 +38,11 @@ Description-Content-Type: text/markdown
 
 # ASK Engine
 
-> **Persistent structural intelligence for AI coding agents.**
+> **ASK — Actionable Software Knowledge.** Persistent structural intelligence for AI coding agents.
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-2.1.0-blue)
+![Version](https://img.shields.io/badge/version-2.2.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -84,7 +84,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 2.1.0
+ask version                    # ask 2.2.0
 ```
 
 > **Package vs. command.** The install package is named `sourcecode` this release

{sourcecode-2.1.0 → sourcecode-2.2.0}/README.md

@@ -1,10 +1,10 @@
 # ASK Engine
 
-> **Persistent structural intelligence for AI coding agents.**
+> **ASK — Actionable Software Knowledge.** Persistent structural intelligence for AI coding agents.
 
 **Context · Impact · Migration · Architecture · Review — everything from one structural model.**
 
-![Version](https://img.shields.io/badge/version-2.1.0-blue)
+![Version](https://img.shields.io/badge/version-2.2.0-blue)
 ![Python](https://img.shields.io/badge/python-3.9%2B-green)
 
 > **ASK Engine** is the product. The CLI command is **`ask`**. The legacy **`sourcecode`**
@@ -46,7 +46,7 @@ brew tap haroundominique/sourcecode && brew install sourcecode
 # pip / pipx
 pipx install sourcecode        # or: pip install sourcecode
 
-ask version                    # ask 2.1.0
+ask version                    # ask 2.2.0
 ```
 
 > **Package vs. command.** The install package is named `sourcecode` this release

{sourcecode-2.1.0 → sourcecode-2.2.0}/pyproject.toml

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

{sourcecode-2.1.0 → sourcecode-2.2.0}/src/sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "2.1.0"
+__version__ = "2.2.0"

sourcecode-2.2.0/src/sourcecode/caller_metrics.py

@@ -0,0 +1,42 @@
+"""Single source of truth for the caller / fan-in metric reconciliation note.
+
+Three commands report a "how many things reference this class" number, each
+derived from a different graph projection. Read side by side they can look
+contradictory (e.g. 215 vs 103 for the same class) — they are not. They count
+different populations:
+
+    modernize.in_degree  >=  explain.incoming_callers  ~=  impact.stats.direct_caller_count
+
+- ``modernize.in_degree`` counts graph *edges* (all edge types, symbol level, not
+  deduplicated per class) — a blast-radius ranking weight, always the largest, and
+  not a count of classes.
+- ``explain.incoming_callers`` and ``impact.stats.direct_caller_count`` both count
+  *distinct dependent classes*. They normally match and are always the same order
+  of magnitude, but can differ by a small margin because each includes a slightly
+  different edge set (import-only references, DI-interface resolution). The
+  truncated ``impact.direct_callers`` array is a display sample, not the count.
+
+Empirically verified across repositories (Broadleaf ExtensionManager: 215 / 103 /
+103; petclinic entities & repositories: equal; occasional margin-of-one divergence
+on classes with import-only references). The strict-equality claim was deliberately
+NOT made — the note asserts only the robust ordering and the "same distinct-class
+metric" relationship.
+
+Every command that emits one of these numbers references this same string so the
+explanation can never drift or contradict itself between commands.
+"""
+
+CALLER_METRIC_RECONCILIATION: str = (
+    "Fan-in / caller counts differ across commands BY DESIGN and are not "
+    "contradictory. For the same class the expected relationship is: "
+    "modernize.in_degree >= explain.incoming_callers ~= impact.stats.direct_caller_count. "
+    "modernize.in_degree = raw count of ALL incoming graph edges (imports, injects, "
+    "extends/implements, references, annotations), counted at symbol level and NOT "
+    "deduplicated per class — a blast-radius ranking weight, not a count of classes; "
+    "it is always the largest of the three. explain.incoming_callers and "
+    "impact.stats.direct_caller_count both count DISTINCT dependent classes "
+    "(deduplicated to class level); they normally match but can differ by a small "
+    "margin because each includes a slightly different edge set (e.g. import-only "
+    "references or DI-interface resolution). The top-level impact.direct_callers array "
+    "may be truncated for output size — use stats.direct_caller_count for the true total."
+)

{sourcecode-2.1.0 → sourcecode-2.2.0}/src/sourcecode/cli.py

@@ -15,6 +15,7 @@ from sourcecode import __version__
 from sourcecode.error_schema import INVALID_INPUT_CODE, build_error_envelope
 from sourcecode.entrypoint_classifier import is_production_entry_point, normalize_entry_point
 from sourcecode.progress import Progress
+from sourcecode.caller_metrics import CALLER_METRIC_RECONCILIATION
 from sourcecode.repository_ir import extract_java_endpoints as _extract_java_endpoints
 
 
@@ -700,7 +701,8 @@ _WELCOME_CMDS = (
 
 def _print_welcome_plain(tier: str) -> None:
     """Plain-text welcome — fallback when rich is unavailable."""
-    lines = ["", f"  ASK Engine {__version__}   ·   {tier}   ·   CLI: ask", "",
+    lines = ["", f"  ASK Engine {__version__}   ·   {tier}   ·   CLI: ask",
+             "  Actionable Software Knowledge Engine", "",
              "  AI coding-agent context, instant.", "", "  Get started:"]
     for cmd, desc in _WELCOME_CMDS:
         lines.append(f"    {cmd.ljust(34)}{desc}")
@@ -747,8 +749,9 @@ def _print_welcome() -> None:
             t.append("   ")
             t.append(tier, style=tier_style)
         t.append("\n")
-    # "ENGINE" label beneath the wordmark.
-    t.append(_WELCOME_ENGINE + "\n", style="bold dim cyan")
+    # "ENGINE" label beneath the wordmark, with the acronym expansion.
+    t.append(_WELCOME_ENGINE, style="bold dim cyan")
+    t.append("   Actionable Software Knowledge\n", style="dim")
 
     t.append("\nAI coding-agent context, instant.\n\n", style="white")
 
@@ -3911,7 +3914,12 @@ def endpoints_cmd(
         )
         raise typer.Exit(code=1)
 
-    data = _extract_java_endpoints(target)
+    _prog = Progress()
+    _prog.start("scanning endpoints")
+    try:
+        data = _extract_java_endpoints(target)
+    finally:
+        _prog.finish()
 
     # Update RIS api_surface section (non-fatal side-effect).
     try:
@@ -4358,6 +4366,9 @@ def export_cmd(
         )
         raise typer.Exit(1)
 
+    _prog = Progress()
+    _prog.start("scanning repository")
+
     file_list = [
         f for f in find_java_files(root)
         if "/test/" not in f and "/tests/" not in f
@@ -4384,6 +4395,7 @@ def export_cmd(
             _integrations,
             endpoint_meta=_ep_data,
         )
+        _prog.finish()
         output = _serialize_dict(data, format)
         _emit_command_output(output, output_path, copy,
                              success_msg=f"C4 architecture export written to {output_path}")
@@ -4413,6 +4425,7 @@ def export_cmd(
             ContextGraph.build(file_list, root)
         ).as_report(len(file_list))
 
+    _prog.finish()
     output = _serialize_dict(data, format)
     _emit_command_output(output, output_path, copy,
                          success_msg=f"Export written to {output_path}")
@@ -4495,6 +4508,8 @@ def validation_cmd(
 
     from sourcecode.context_graph import ContextGraph
     from sourcecode.validation_surface import build_validation_surface
+    _prog = Progress()
+    _prog.start("mapping validation surface")
     # Structural facts come from the ContextGraph — the single access layer.
     _graph = ContextGraph.build_from_root(target)
     data = build_validation_surface(target, graph=_graph)
@@ -4527,6 +4542,7 @@ def validation_cmd(
         if _note:
             data["note"] = _note
 
+    _prog.finish()
     output = _serialize_dict(data, format)
     _summary = data.get("summary", {})
     # Human-facing heads-up when the result is empty purely because no OpenAPI
@@ -4750,6 +4766,8 @@ def spring_audit_cmd(
                              success_msg=f"Spring audit written to {output_path}")
         return
 
+    _prog = Progress()
+    _prog.start(f"auditing {len(file_list)} Java files")
     cir = ContextGraph.build(file_list, target).cir
     _model = SpringSemanticModel.build(cir)
 
@@ -4802,6 +4820,7 @@ def spring_audit_cmd(
     except Exception:
         pass
 
+    _prog.finish()
     if format == "github-comment":
         output = _render_spring_audit_github_comment(combined, min_severity)
     else:
@@ -4920,7 +4939,12 @@ def migrate_check_cmd(
 
     _file_limitations: list[str] = []
     file_list = find_java_files(target, limitations=_file_limitations)
-    report = run_migrate_check(file_list, target, min_severity=min_severity)
+    _prog = Progress()
+    _prog.start(f"checking migration ({len(file_list)} files)")
+    try:
+        report = run_migrate_check(file_list, target, min_severity=min_severity)
+    finally:
+        _prog.finish()
     if _file_limitations:
         report.limitations.extend(_file_limitations)
 
@@ -5079,6 +5103,8 @@ def impact_chain_cmd(
                              success_msg=f"Impact chain written to {output_path}")
         return
 
+    _prog = Progress()
+    _prog.start(f"analyzing impact ({len(file_list)} files)")
     cir = ContextGraph.build(file_list, target).cir
     _model = SpringSemanticModel.build(cir)
 
@@ -5086,6 +5112,7 @@ def impact_chain_cmd(
         from sourcecode.spring_event_topology import run_event_topology
         evt_result = run_event_topology(cir, symbol, model=_model)
         data = evt_result.to_dict()
+        _prog.finish()
         output = _serialize_dict(data, format)
         _emit_command_output(
             output, output_path, copy,
@@ -5101,6 +5128,7 @@ def impact_chain_cmd(
     result = run_impact_chain(cir, symbol, depth=depth, root=target, model=_model)
 
     data = result.to_dict()
+    _prog.finish()
     output = _serialize_dict(data, format)
     _emit_command_output(
         output, output_path, copy,
@@ -5229,9 +5257,14 @@ def pr_impact_cmd(
                              success_msg=f"PR impact report written to {output_path}")
         return
 
-    cir = ContextGraph.build(file_list, target).cir
-    model = SpringSemanticModel.build(cir)
-    report = run_pr_impact(cir, changed_files, root=target, model=model)
+    _prog = Progress()
+    _prog.start(f"analyzing PR impact ({len(file_list)} files)")
+    try:
+        cir = ContextGraph.build(file_list, target).cir
+        model = SpringSemanticModel.build(cir)
+        report = run_pr_impact(cir, changed_files, root=target, model=model)
+    finally:
+        _prog.finish()
 
     output = _serialize_dict(report.to_dict(), "json") if format == "json" else report.render_text()
     _emit_command_output(
@@ -5348,9 +5381,14 @@ def explain_cmd(
         )
         raise typer.Exit(code=1)
 
-    cir = ContextGraph.build(file_list, target).cir
-    model = SpringSemanticModel.build(cir)
-    explanation = explain_class(class_name, cir, model)
+    _prog = Progress()
+    _prog.start(f"explaining {class_name} ({len(file_list)} files)")
+    try:
+        cir = ContextGraph.build(file_list, target).cir
+        model = SpringSemanticModel.build(cir)
+        explanation = explain_class(class_name, cir, model)
+    finally:
+        _prog.finish()
 
     if format == "json":
         output = _json.dumps(explanation.to_dict(), indent=2, ensure_ascii=False)
@@ -5663,7 +5701,56 @@ def _partition_static_unreferenced(nodes: list[dict], root: Path) -> tuple[list[
             if files_scanned >= _CONFIG_SCAN_MAX_FILES or not unresolved_simple:
                 break
 
-    unreferenced = [n for n in nodes if n["fqn"] not in dispatched_fqns]
+    # 3. Nested-type qualified-reference scan (SC-2 residual). The static call-graph
+    #    does not emit an edge for a nested-type member access in ordinary method-body
+    #    code — e.g. `PropertyType.AdminGroupPresentation.NAME` credits the enclosing
+    #    type, not the nested holder — so a referenced nested class can look
+    #    zero-degree. When a candidate is a nested type (its second-to-last FQN segment
+    #    is an UpperCamel enclosing type) and its qualified `Outer.Nested` form appears
+    #    in some OTHER Java source, it is statically referenced: neither dead nor
+    #    framework-dispatched. Structural, name-agnostic (pattern derived from the
+    #    candidate's own FQN).
+    import re as _re_nested
+    statically_referenced: set[str] = set()
+    nested_patterns: dict[str, "tuple"] = {}
+    for n in nodes:
+        if n["fqn"] in dispatched_fqns:
+            continue
+        parts = (n.get("fqn") or "").split(".")
+        if len(parts) >= 2 and parts[-2][:1].isupper():
+            outer, nested = parts[-2], parts[-1]
+            nested_patterns[n["fqn"]] = (
+                _re_nested.compile(r"\b" + _re_nested.escape(outer) + r"\." + _re_nested.escape(nested) + r"\b"),
+                n.get("source_file") or "",
+            )
+    if nested_patterns:
+        files_scanned = 0
+        for dirpath, dirnames, filenames in os.walk(root):
+            dirnames[:] = [d for d in dirnames
+                           if d not in {".git", "build", "out", "target", "node_modules", ".gradle"}]
+            for fname in filenames:
+                if not fname.endswith(".java"):
+                    continue
+                if files_scanned >= _CONFIG_SCAN_MAX_FILES or len(statically_referenced) == len(nested_patterns):
+                    break
+                fpath = os.path.join(dirpath, fname)
+                rel = os.path.relpath(fpath, root)
+                try:
+                    with open(fpath, "r", encoding="utf-8", errors="replace") as fh:
+                        text = fh.read(_CONFIG_SCAN_MAX_BYTES)
+                except OSError:
+                    continue
+                files_scanned += 1
+                for fqn, (pat, own) in nested_patterns.items():
+                    if fqn in statically_referenced or rel == own:
+                        continue
+                    if pat.search(text):
+                        statically_referenced.add(fqn)
+            if files_scanned >= _CONFIG_SCAN_MAX_FILES or len(statically_referenced) == len(nested_patterns):
+                break
+
+    unreferenced = [n for n in nodes
+                    if n["fqn"] not in dispatched_fqns and n["fqn"] not in statically_referenced]
     dispatched = [n for n in nodes if n["fqn"] in dispatched_fqns]
     return unreferenced, dispatched
 
@@ -5870,8 +5957,13 @@ def modernize_cmd(
             "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.
+            # reference each other, so neither can be extracted independently. A
+            # one-way (directional) dependency is normal layering, NOT a tangle:
+            # TANGLE-1 (petclinic field test) surfaced owner→model / vet→model
+            # (reverse_edge_count:0) being labelled "tangles" when they are plain
+            # base-model usage. coupling_type states which it is, honestly.
             "mutual": _reverse > 0,
+            "coupling_type": "cyclic" if _reverse > 0 else "directional",
             "example": _pair_example.get((_a, _b), ""),
         })
     # Surface mutual tangles first (highest decomposition risk), then by strength.
@@ -5947,17 +6039,10 @@ 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 `ask 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."
-            ),
+            # SC-6 (Broadleaf field test): make the in_degree metric self-describing
+            # so it is not confused with `explain`'s / `impact`'s caller counts. All
+            # three share one reconciliation note so they can never contradict.
+            "high_coupling_nodes_note": CALLER_METRIC_RECONCILIATION,
             "statically_unreferenced": [
                 {"fqn": n["fqn"], "type": n.get("type", ""), "role": n.get("role", "other")}
                 for n in dead_zones
@@ -5978,10 +6063,12 @@ def modernize_cmd(
             "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."
+                "edge_count = edges from_package→to_package. coupling_type=cyclic "
+                "(mutual=true) is a bidirectional dependency — the actual tangle "
+                "that blocks independent module extraction; coupling_type="
+                "directional (reverse_edge_count=0) is a normal one-way layered "
+                "dependency, listed for coupling strength, NOT a tangle. 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": (
@@ -5992,7 +6079,9 @@ def modernize_cmd(
                 )
                 + "statically_unreferenced lists classes with no Java callers — review "
                 + "for framework dispatch (XML/reflection/SPI) before removing. "
-                + "Cross-module tangles indicate coupling worth decomposing."
+                + "In cross_module_tangles, coupling_type=cyclic entries are the "
+                + "real tangles to decompose first; directional entries are normal "
+                + "layering ranked by coupling strength."
             ),
         }
 

{sourcecode-2.1.0 → sourcecode-2.2.0}/src/sourcecode/detectors/java.py

@@ -176,6 +176,28 @@ class JavaDetector(AbstractDetector):
             frameworks = [f for f in frameworks if f.name != "MyBatis"]
 
         entry_points = self._collect_entry_points(context)
+
+        # C1 (Eureka field test): a repo whose REST surface is JAX-RS / Jakarta
+        # REST — declared on the source via @Path/@GET, not through a web framework
+        # coordinate in the build manifest — must still surface that in the headline
+        # stack. Eureka wires JAX-RS through Jersey 1.x (com.sun.jersey) + jsr311-api
+        # + Guice, none of which the manifest-coordinate scan models, and its child
+        # build.gradle files are not scanned at all — yet it ships 18 @Path resource
+        # classes. Without this the headline read "Java library / package" while the
+        # endpoints command listed a full JAX-RS API. When the annotation scan found
+        # JAX-RS entry points and no Jakarta-EE framework was inferred from the
+        # manifest, surface it so the stack (and project_type) reflect the REST API
+        # the endpoints already prove. Structural (VAI): reasons from the JAX-RS
+        # entry points found in source, not from a vendor dependency-name allowlist.
+        # detected_via carries no path form, so it is treated as repo-wide evidence
+        # (never localized to an adapter submodule).
+        if not any(f.name == "Jakarta EE" for f in frameworks) and any(
+            ep.kind in ("jax_rs_controller", "jax_rs_provider") for ep in entry_points
+        ):
+            frameworks.append(FrameworkDetection(
+                name="Jakarta EE", source="annotation", detected_via=["jax_rs_endpoints"],
+            ))
+
         transactional_classes = self._collect_transactional_classes(context, all_paths)
         stack = StackDetection(
             stack="java",
@@ -459,7 +481,13 @@ class JavaDetector(AbstractDetector):
         # 1. @SpringBootApplication entry: Application.java / Main.java by name
         # 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
+        # B2 (openmrs field test): exclude not just src/test/ trees but whole
+        # test-harness MODULES whose sources sit under src/main — e.g. openmrs'
+        # `test-suite/module/omod/src/main/java/.../TestModuleController.java`, a
+        # scaffolding @Controller (`GET /module/testmodule/hello`) that a narrow
+        # src/test/ check misses, so it surfaced as a production entry point. The
+        # broader is_test_or_fixture_path catches test-suite / *-test / *-it modules.
+        from sourcecode.path_filters import is_test_or_fixture_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

sourcecode-2.2.0/src/sourcecode/endpoint_metrics.py

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

{sourcecode-2.1.0 → sourcecode-2.2.0}/src/sourcecode/explain.py

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

{sourcecode-2.1.0 → sourcecode-2.2.0}/src/sourcecode/path_filters.py

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