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

sourcecode/architecture_summary.py

@@ -31,6 +31,18 @@ _CORE_DETECTION_MODULES = {"scanner", "detectors", "classifier", "workspace"}
 # headline to a qualified, consistent phrasing instead of overclaiming.
 _MIN_REST_ENDPOINTS_FOR_LABEL = 5
 
+# BUG (neo4j field test): endpoint COUNT alone cannot separate "an API server"
+# from "a large engine/platform that also exposes a few HTTP endpoints". A graph
+# database with ~14 JAX-RS endpoints across 5,600+ source files is not a "REST
+# API" — yet it clears the count threshold above and gets mis-headlined, the exact
+# thing a reader sees in the first line. Add a proportionality guard: on a large
+# JVM codebase, only keep the "REST API" headline when the HTTP surface is
+# architecturally significant relative to code size (at least one endpoint per
+# _API_DOMINANCE_FILES_PER_ENDPOINT source files). Below that density the web
+# layer is a minor component, not the architecture.
+_LARGE_JVM_SOURCE_FILES = 400
+_API_DOMINANCE_FILES_PER_ENDPOINT = 100
+
 _OPTIONAL_LABEL_MAP: dict[str, str] = {
     "DependencyAnalyzer": "dependencias",
     "GraphAnalyzer": "grafo de módulos",
@@ -207,6 +219,21 @@ class ArchitectureSummarizer:
                         f"(HTTP framework present; only {total} endpoint{plural} "
                         f"detected — see `endpoints`)."
                     )
+                # Proportionality guard: a large JVM codebase whose HTTP surface is
+                # a rounding error is an engine/platform exposing an API, not an
+                # "API" project. Endpoint count already cleared the threshold above,
+                # so lead with what the system IS instead of overclaiming "REST API".
+                n_src = self._jvm_source_file_count(sm)
+                if (
+                    n_src >= _LARGE_JVM_SOURCE_FILES
+                    and total * _API_DOMINANCE_FILES_PER_ENDPOINT < n_src
+                ):
+                    plural = "s" if total != 1 else ""
+                    return (
+                        f"{stack_label} multi-module codebase{fw_str} — large "
+                        f"system ({n_src} source files) with a minor HTTP surface "
+                        f"({total} endpoint{plural}); not API-first. See `endpoints`."
+                    )
             return f"{stack_label} {runtime.lower()}{fw_str}."
         return f"{stack_label} project{fw_str}."
 
@@ -228,6 +255,20 @@ class ArchitectureSummarizer:
         self._endpoint_support_cache = (total, high)
         return self._endpoint_support_cache
 
+    def _jvm_source_file_count(self, sm: SourceMap) -> int:
+        """Count JVM source files in the scanned tree (excludes tooling paths).
+        Used by the proportionality guard to tell a large engine/platform apart
+        from an API-first project. A truncated tree only undercounts, which makes
+        the guard more conservative (less likely to degrade a real API)."""
+        exts = (".java", ".kt", ".kts", ".scala")
+        try:
+            return sum(
+                1 for p in flatten_file_tree(sm.file_tree)
+                if p.endswith(exts) and not self._is_tooling_path(p)
+            )
+        except Exception:
+            return 0
+
     def _qualify_web_pattern(self, arch: Any, arch_line: str, sm: SourceMap) -> str:
         """BUG #1 (Jenkins field test): the "mvc" pattern is a directory-name
         heuristic (dirs matching controller/model/view keywords). On a Java/Kotlin

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/classifier.py

@@ -34,6 +34,30 @@ _API_FRAMEWORKS = {
 _WEB_FRAMEWORKS = {"Next.js", "React", "Vue", "Svelte", "Vite", "Flutter", "Phoenix", "Angular"}
 _CLI_FRAMEWORKS = {"Typer", "Cobra", "Clap"}
 _API_STACKS = {"python", "go", "java", "php", "ruby", "dotnet", "kotlin", "scala"}
+
+# Center-of-gravity gate for the "api" decision (neo4j field test).
+# The historical rule was pure PRESENCE: any API framework on the classpath →
+# project_type="api". That mislabels a large engine/platform that merely exposes a
+# small HTTP surface. Two evidence paths defeat the existing adapter-localization
+# guard because they are repo-wide (no locatable minority module):
+#   * a jakarta.ws.rs / javax.ws.rs-api coordinate pinned in a BOM/parent pom's
+#     <dependencyManagement> (a version pin, not usage), and
+#   * a source-annotation "Jakarta EE" marker synthesized from @Path resources
+#     (detected_via carries no file path).
+# So on a repo large enough to HAVE a distinct center of gravity, require the API
+# surface to occupy a real share of the code (or the dominant module) before we
+# headline the whole system as an API. Small/single-module repos keep presence-based
+# behavior (a real API framework there defines the project — e.g. the Eureka field
+# test). JVM-only: this is where the false positive lives; other stacks are untouched.
+_JVM_STACKS = {"java", "kotlin", "scala", "groovy"}
+_JVM_CODE_EXTS = (".java", ".kt", ".kts", ".scala", ".groovy")
+_API_DOMINANCE_MIN_FILES = 300
+_API_PRIMARY_SHARE = 0.15
+_API_SURFACE_ENTRY_KINDS = frozenset({
+    "jax_rs_controller", "jax_rs_provider",
+    "rest_controller", "mvc_controller", "controller", "web", "server",
+})
+
 ConfidenceLevel = Literal["high", "medium", "low"]
 
 
@@ -143,7 +167,18 @@ class TypeClassifier:
             return "web_mvc"
 
         if framework_names & _API_FRAMEWORKS:
-            return "api"
+            if not (stack_names & _JVM_STACKS) or self._api_is_center_of_gravity(
+                file_tree, stacks, entry_points
+            ):
+                return "api"
+            # A JVM API framework is present but is NOT the repo's center of gravity.
+            # It survived adapter-localization only because its evidence is repo-wide
+            # (a BOM/parent-pom version pin, or a source-annotation marker with no
+            # locatable minority module). Do not headline the whole system as an API —
+            # the framework stays in stacks[].frameworks as a secondary capability and
+            # the primary type falls back to the structural center of gravity.
+            if self._is_multi_module(file_tree):
+                return "library"
 
         # All app-defining frameworks were localized to optional adapter submodules
         # (multi-module library with per-framework integrations) — report library,
@@ -263,6 +298,64 @@ class TypeClassifier:
                 localized.add(fw_name)
         return localized
 
+    def _api_is_center_of_gravity(
+        self,
+        file_tree: dict[str, Any],
+        stacks: Sequence[StackDetection],
+        entry_points: Sequence[EntryPoint],
+    ) -> bool:
+        """True when an API/web framework reflects the repo's center of gravity, not
+        merely its presence. Small or single-module JVM repos: a present API framework
+        defines the project (keeps the historical behavior). Large multi-module repos:
+        the HTTP surface must live in the dominant module or occupy at least
+        ``_API_PRIMARY_SHARE`` of the JVM source — otherwise it is a minor capability
+        of an engine/platform/library, not the primary type."""
+        counts: dict[str, int] = {}
+        for p in flatten_file_tree(file_tree):
+            if p.endswith(_JVM_CODE_EXTS):
+                mod = self._module_of(p)
+                counts[mod] = counts.get(mod, 0) + 1
+        counts.pop("", None)
+        total = sum(counts.values())
+        # Too small, or a single module, to reason about a center of gravity.
+        if total < _API_DOMINANCE_MIN_FILES or len(counts) < 2:
+            return True
+        dominant = max(counts, key=lambda m: counts[m])
+        api_modules = self._api_surface_modules(stacks, entry_points)
+        if not api_modules:
+            # API framework known only repo-wide (BOM version pin / annotation marker)
+            # with no source-located HTTP surface in a large multi-module system.
+            return False
+        if dominant in api_modules:
+            return True
+        api_files = sum(counts.get(m, 0) for m in api_modules)
+        return (api_files / total) >= _API_PRIMARY_SHARE
+
+    def _api_surface_modules(
+        self,
+        stacks: Sequence[StackDetection],
+        entry_points: Sequence[EntryPoint],
+    ) -> set[str]:
+        """Modules that actually host an HTTP/REST surface: derived from API entry
+        points (controllers / JAX-RS resources) and from API-framework file evidence.
+        Repo-wide manifest evidence (no path) contributes no module, by design."""
+        modules: set[str] = set()
+        for ep in entry_points:
+            if getattr(ep, "kind", None) in _API_SURFACE_ENTRY_KINDS and ep.path:
+                modules.add(self._module_of(ep.path))
+        for stack in stacks:
+            for fw in stack.frameworks:
+                if fw.name not in _API_FRAMEWORKS:
+                    continue
+                for ev in fw.detected_via:
+                    if ev.startswith("manifest:"):
+                        continue
+                    m = self._EVIDENCE_PATH_RE.search(ev)
+                    if m:
+                        modules.add(self._module_of(m.group(1).strip()))
+        modules.discard("")
+        return modules
+
     def _is_fullstack(self, stacks: Sequence[StackDetection]) -> bool:
         has_web = False
         has_api = False

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
 
 
@@ -245,6 +246,8 @@ _SUBCOMMANDS: frozenset[str] = frozenset(
         "rename-class",
         # Large file semantic chunking (BLOCKER-B)
         "chunk-file",
+        # Experimental evidence-based archetype (parallel to legacy)
+        "archetype",
     }
 )
 
@@ -700,7 +703,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 +751,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 +3916,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 +4368,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 +4397,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 +4427,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 +4510,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 +4544,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 +4768,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 +4822,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 +4941,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 +5105,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 +5114,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 +5130,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 +5259,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 +5383,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 +5703,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 +5959,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 +6041,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 +6065,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 +6081,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."
             ),
         }
 
@@ -6333,6 +6424,77 @@ def config_cmd() -> None:
 
 # ── cold-start (RIS bootstrap for external MCP and agents) ───────────────────
 
+@app.command("archetype")
+def archetype_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o", help="Write output to a file instead of stdout."
+    ),
+) -> None:
+    """[EXPERIMENTAL] Evidence-based architectural archetype (parallel to legacy).
+
+    Emits a 4-dimension archetype analysis — software_archetype, architectural_style,
+    deployment_shape, primary_interface — each with scored candidates, the evidence
+    (weighted by code mass), a confidence level, and a human explanation.
+
+    This runs ALONGSIDE the legacy architecture pattern and does NOT change any
+    report wording. It exists to validate the new model against the old one across
+    many repositories before any cutover.
+    """
+    import json as _json
+    from sourcecode.adaptive_scanner import AdaptiveScanner
+    from sourcecode.repo_classifier import RepoClassifier
+    from sourcecode.detectors import ProjectDetector, build_default_detectors
+    from sourcecode.schema import SourceMap
+    from sourcecode.tree_utils import flatten_file_tree
+    from sourcecode.archetype import ArchetypeClassifier
+
+    target = Path(path).resolve()
+    topology = RepoClassifier().classify(target)
+    scanner = AdaptiveScanner(target, topology=topology, base_depth=12)
+    file_tree = scanner.scan_tree()
+    manifests = scanner.find_manifests()
+
+    detector = ProjectDetector(build_default_detectors())
+    stacks, entry_points, _ = detector.detect(target, file_tree, manifests)
+    stacks, project_type = detector.classify_results(file_tree, stacks, entry_points)
+
+    sm = SourceMap(
+        file_tree=file_tree, stacks=stacks,
+        project_type=project_type, entry_points=entry_points,
+    )
+    sm.file_paths = [p.replace("\\", "/") for p in flatten_file_tree(file_tree)]
+    _java = next((s for s in stacks if s.stack == "java"), None)
+    if _java is not None:
+        sm.packaging = getattr(_java, "packaging", None)
+
+    # Module graph as a first-class Evidence Provider (ADR-0003 step 2). Built
+    # here so archetype can consume topological evidence. Bounded + best-effort:
+    # on very large trees or any failure it degrades to None (name-mass-only),
+    # which is exactly the pre-provider behaviour — no regression.
+    module_graph = None
+    try:
+        from sourcecode.graph_analyzer import GraphAnalyzer
+        module_graph = GraphAnalyzer(max_nodes=1200, max_edges=4000).analyze(
+            target, file_tree, detail="full", entry_points=entry_points,
+        )
+        if module_graph is not None:
+            sm.module_graph = module_graph
+            sm.module_graph_summary = module_graph.summary
+    except Exception:
+        module_graph = None
+
+    analysis = ArchetypeClassifier().analyze(sm, root=target, module_graph=module_graph)
+    result = analysis.to_dict()
+    result["legacy_project_type"] = project_type  # side-by-side with legacy for validation
+    out = _json.dumps(result, indent=2, ensure_ascii=False)
+    if output_path:
+        _safe_write_file(output_path, out)
+        typer.echo(f"Archetype analysis written to {output_path}")
+    else:
+        typer.echo(out)
+
+
 @app.command("cold-start")
 def cold_start_cmd(
     path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),

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