sourcecode 2.2.0__py3-none-any.whl → 2.4.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/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

@@ -246,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",
     }
 )
 
@@ -5339,6 +5341,7 @@ def explain_cmd(
     from sourcecode.context_graph import ContextGraph
     from sourcecode.spring_model import SpringSemanticModel
     from sourcecode.explain import explain_class
+    from sourcecode import context_cache as _ctxcache
 
     if not class_name.strip():
         _emit_error_json(
@@ -5381,14 +5384,27 @@ def explain_cmd(
         )
         raise typer.Exit(code=1)
 
+    # AI Context Cache — operates at the *knowledge* level: it caches the
+    # reusable Canonical IR (the expensive Java parse), keyed only by knowledge
+    # state, not by command. explain then derives its answer cheaply from that
+    # shared CIR. The same cached CIR is reused for free by any other command.
+    # Provider-agnostic and best-effort: any fault degrades to a fresh build.
     _prog = Progress()
     _prog.start(f"explaining {class_name} ({len(file_list)} files)")
+    _cc_look = None
     try:
-        cir = ContextGraph.build(file_list, target).cir
+        try:
+            cir, _cc_look = _ctxcache.get_or_build_cir(
+                _resolve_repo_root(target), target, file_list
+            )
+        except Exception:
+            cir = ContextGraph.build(file_list, target).cir  # fallback: never break explain
         model = SpringSemanticModel.build(cir)
         explanation = explain_class(class_name, cir, model)
     finally:
         _prog.finish()
+    if _cc_look is not None:
+        typer.echo(_cc_look.render(), err=True)
 
     if format == "json":
         output = _json.dumps(explanation.to_dict(), indent=2, ensure_ascii=False)
@@ -6422,6 +6438,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)"),
@@ -7126,6 +7213,53 @@ def cache_freshness_cmd(
         typer.echo(f"RIS updated:  {result.get('ris_last_updated_at') or 'never'}")
 
 
+@cache_app.command("context-stats")
+def cache_context_stats_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    json_output: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Show AI Context Cache statistics (structured-knowledge reuse metrics).
+
+    This is the provider-agnostic context cache — distinct from the snapshot
+    cache reported by `ask cache status`. It measures reuse of ASK's structured
+    context (entities/evidence/observations/summaries), never prompts or LLM output.
+    """
+    from sourcecode import context_cache as _ctxcache
+    target = _resolve_repo_root(Path(path))
+    stats = _ctxcache.stats_for_repo(target)
+    if json_output:
+        import json as _j
+        typer.echo(_j.dumps(stats, indent=2, ensure_ascii=False))
+    else:
+        typer.echo(f"Cache dir:     {stats['cache_dir']}")
+        typer.echo(f"Enabled:       {stats['enabled']}")
+        typer.echo(f"Contexts:      {stats['contexts']}")
+        typer.echo(f"Hits:          {stats['hits']}")
+        typer.echo(f"Misses:        {stats['misses']}")
+        typer.echo(f"Invalidations: {stats['invalidations']}")
+        typer.echo(f"Stores:        {stats['stores']}")
+        typer.echo(f"Hit ratio:     {stats['hit_ratio']}")
+        typer.echo(f"Avg lookup:    {stats['avg_lookup_ms']} ms")
+        typer.echo(f"Avg build:     {stats['avg_build_ms']} ms")
+        typer.echo(f"Bytes stored:  {stats['bytes_stored']}")
+        typer.echo(f"KL version:    {stats['kl_schema_version']}  producer={stats['producer_version']}")
+
+
+@cache_app.command("context-clear")
+def cache_context_clear_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+) -> None:
+    """Delete the AI Context Cache for a repository (structured context + stats)."""
+    from sourcecode import context_cache as _ctxcache
+    target = _resolve_repo_root(Path(path))
+    if not yes and sys.stdin.isatty():
+        import click as _click
+        _click.confirm(f"Delete AI context cache for {target}?", abort=True, err=True)
+    removed = _ctxcache.clear_for_repo(target)
+    typer.echo(f"Removed {removed} context file(s).", err=True)
+
+
 # ── Entry point ───────────────────────────────────────────────────────────────
 
 def _stderr_is_interactive() -> bool: