sourcecode 1.31.9__py3-none-any.whl → 1.31.11__py3-none-any.whl

sourcecode/__init__.py

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

sourcecode/classifier.py

@@ -20,6 +20,7 @@ _API_FRAMEWORKS = {
     "Rocket",
     "Spring Boot",
     "Quarkus",
+    "Jakarta EE",   # JAX-RS / Jakarta REST — pure JAX-RS projects must not fall to "unknown"
     "Laravel",
     "Symfony",
     "Ktor",

sourcecode/cli.py

@@ -858,7 +858,10 @@ def main(
             # to avoid polluting sub-project directories used in tests.
             if _git_sha and (target / ".git").exists():
                 # Include every output-affecting flag so different flag combos never collide
+                # Include version so cache is invalidated on sourcecode upgrades
+                from sourcecode import __version__ as _sc_version
                 _flags_str = (
+                    f"v={_sc_version},"
                     f"c={compact},ag={agent},fmt={format},full={full},"
                     f"co={changed_only},dep={dependencies},gm={graph_modules},"
                     f"docs={docs},fm={full_metrics},sem={semantics},"
@@ -2475,9 +2478,9 @@ def endpoints_cmd(
     """Extract REST API endpoint surface from Java source files.
 
     \b
-    Scans all @GetMapping/@PostMapping/@PutMapping/@DeleteMapping/@PatchMapping
-    and @RequestMapping annotations. Extracts HTTP method, path, controller class,
-    handler method, and @M3FiltroSeguridad permission resource name.
+    Scans Spring MVC (@GetMapping/@PostMapping/@PutMapping/@DeleteMapping/@PatchMapping/@RequestMapping)
+    and JAX-RS (@GET/@POST/@PUT/@DELETE/@PATCH with @Path) annotations.
+    Extracts HTTP method, path, controller class, and handler method.
 
     \b
     Examples:

sourcecode/confidence_analyzer.py

@@ -222,11 +222,18 @@ class ConfidenceAnalyzer:
             ))
 
         # Spring profile documentation (comments in application-{profile}.yml)
+        # Only relevant for Spring Boot projects — Quarkus/Jakarta use similar file names
+        # but they're Quarkus profiles, not Spring profiles.
+        _is_spring_boot = any(
+            f.name in ("Spring Boot", "Spring")
+            for stack in sm.stacks
+            for f in getattr(stack, "frameworks", [])
+        )
         _profile_ymls = [
             p for p in sm.file_paths
             if "application-" in p.rsplit("/", 1)[-1] and p.endswith((".yml", ".yaml", ".properties"))
         ]
-        if _profile_ymls:
+        if _is_spring_boot and _profile_ymls:
             # Check for at least one comment line (# ...) across profile files
             _root = Path(sm.metadata.analyzed_path) if sm.metadata.analyzed_path else None
             _has_profile_docs = False

sourcecode/dependency_analyzer.py

@@ -128,8 +128,13 @@ def _infer_role(name: str, ecosystem: str, scope: str) -> str:
         return "runtime"
 
     if ecosystem == "java":
+        # Scope is authoritative: provided and dev scopes are not runtime, regardless of
+        # artifact name. Checking artifact patterns first would mis-classify spring-boot-test
+        # (scope=test) as "runtime", inflating false-positive fan-in signals.
         if scope == "provided":
             return "provided"
+        if is_dev:
+            return "devtool"
         artifact = n.split(":")[-1] if ":" in n else n
         if any(x in artifact for x in ("spring-boot", "spring-security")):
             return "runtime"
@@ -143,7 +148,7 @@ def _infer_role(name: str, ecosystem: str, scope: str) -> str:
             return "parsing"
         if any(x in artifact for x in ("jjwt", "nimbus-jose")):
             return "runtime"
-        return "devtool" if is_dev else "runtime"
+        return "runtime"
 
     return "devtool" if is_dev else "runtime"
 
@@ -1142,7 +1147,7 @@ class DependencyAnalyzer:
         records: list[DependencyRecord] = []
         deps_elem = root_elem.find(f"{ns}dependencies")
         if deps_elem is None:
-            return [], ["java: pom.xml sin bloque <dependencies>"]
+            return [], ["java: pom.xml has no <dependencies> block"]
 
         for dep in deps_elem.findall(f"{ns}dependency"):
             group_id = (dep.findtext(f"{ns}groupId") or "").strip()
@@ -1190,7 +1195,7 @@ class DependencyAnalyzer:
 
         limitations: list[str] = []
         if not records:
-            limitations.append("java: pom.xml sin dependencias parseables (puede usar BOM o propiedades)")
+            limitations.append("java: pom.xml has no parseable dependencies (may use BOM or properties)")
 
         # Warn when Spring Boot BOM manages transitive deps — they can't be resolved statically.
         parent_artifact_local = (

sourcecode/detectors/java.py

@@ -34,13 +34,16 @@ _HTTP_PATH_RE = re.compile(
 _REQUEST_METHOD_VERB_RE = re.compile(
     r'method\s*=\s*RequestMethod\.([A-Z]+)'
 )
-# @M3FiltroSeguridad custom security annotation
-_M3_FILTRO_RE = re.compile(r'@M3FiltroSeguridad\b')
-_M3_FILTRO_PARAMS_RE = re.compile(
-    r'@M3FiltroSeguridad\s*\(\s*'
-    r'(?:nombreRecurso\s*=\s*(?:"([^"]*)"|([\w.]+)))?'  # group 1: string literal, group 2: constant ref
-    r'(?:[^)]*nivelRequerido\s*=\s*(\d+))?'  # group 3: nivel
-)
+# Custom security annotation registry — extend here for project-specific annotations.
+# Each entry: annotation_simple_name → compiled params regex.
+# Groups: (1) resource string literal, (2) resource constant ref, (3) level integer.
+_CUSTOM_SECURITY_ANNOTATIONS: dict[str, re.Pattern] = {
+    "M3FiltroSeguridad": re.compile(
+        r'@M3FiltroSeguridad\s*\(\s*'
+        r'(?:nombreRecurso\s*=\s*(?:"([^"]*)"|([\w.]+)))?'
+        r'(?:[^)]*nivelRequerido\s*=\s*(\d+))?'
+    ),
+}
 
 # Security config detection
 _WEB_SECURITY_CONFIGURER_RE = re.compile(r'WebSecurityConfigurerAdapter\b')
@@ -436,7 +439,7 @@ class JavaDetector(AbstractDetector):
         ))
         if (not has_controller and not has_filter and not has_security
                 and "ControllerAdvice" not in content
-                and "M3FiltroSeguridad" not in content
+                and not any(ann in content for ann in _CUSTOM_SECURITY_ANNOTATIONS)
                 and not has_jax_rs and not has_cdi and not has_spi):
             return []
 
@@ -449,11 +452,13 @@ class JavaDetector(AbstractDetector):
             elif verb_match:
                 http_path = f"[{verb_match.group(1)}]"
             security_evidence = None
-            m3_match = _M3_FILTRO_PARAMS_RE.search(content)
-            if m3_match:
-                nombre = m3_match.group(1) or m3_match.group(2) or ""
-                nivel = m3_match.group(3) or ""
-                security_evidence = f"@M3FiltroSeguridad(nombreRecurso={nombre!r}, nivelRequerido={nivel})"
+            for _ann_name, _ann_re in _CUSTOM_SECURITY_ANNOTATIONS.items():
+                _m = _ann_re.search(content)
+                if _m:
+                    nombre = _m.group(1) or _m.group(2) or ""
+                    nivel = _m.group(3) or ""
+                    security_evidence = f"@{_ann_name}(nombreRecurso={nombre!r}, nivelRequerido={nivel})"
+                    break
             return [EntryPoint(
                 path=rel_path, stack="java", kind="rest_controller",
                 source="annotation", confidence="high",
@@ -474,11 +479,13 @@ class JavaDetector(AbstractDetector):
             elif verb_match:
                 http_path = f"[{verb_match.group(1)}]"
             security_evidence = None
-            m3_match = _M3_FILTRO_PARAMS_RE.search(content)
-            if m3_match:
-                nombre = m3_match.group(1) or m3_match.group(2) or ""
-                nivel = m3_match.group(3) or ""
-                security_evidence = f"@M3FiltroSeguridad(nombreRecurso={nombre!r}, nivelRequerido={nivel})"
+            for _ann_name, _ann_re in _CUSTOM_SECURITY_ANNOTATIONS.items():
+                _m = _ann_re.search(content)
+                if _m:
+                    nombre = _m.group(1) or _m.group(2) or ""
+                    nivel = _m.group(3) or ""
+                    security_evidence = f"@{_ann_name}(nombreRecurso={nombre!r}, nivelRequerido={nivel})"
+                    break
             return [EntryPoint(
                 path=rel_path, stack="java", kind="mvc_controller",
                 source="annotation", confidence="medium",
@@ -514,7 +521,10 @@ class JavaDetector(AbstractDetector):
             )]
 
         # --- JAX-RS resource class ---
-        if has_jax_rs and _JAX_RS_PATH_RE.search(content) and _JAX_RS_VERB_RE.search(content):
+        # Guard uses annotation PRESENCE ("@Path" in content), not _JAX_RS_PATH_RE, because
+        # the value-parsing regex fails for @Path(CONSTANT) and @Path(PREFIX + "/sub").
+        # _JAX_RS_PATH_RE is still used to extract the http_path display string when parseable.
+        if has_jax_rs and "@Path" in content and _JAX_RS_VERB_RE.search(content):
             path_m = _JAX_RS_PATH_RE.search(content)
             verb_m = _JAX_RS_VERB_RE.search(content)
             http_path: str | None = None

sourcecode/doc_analyzer.py

@@ -273,10 +273,11 @@ class DocAnalyzer:
                 name = class_m.group(1)
                 doc_text = self._clean_javadoc(jd_match.group(1))
                 records.append(DocRecord(
+                    symbol=name,
+                    kind="class",
+                    language="java",
                     path=path,
                     workspace=workspace,
-                    kind="class",
-                    name=name,
                     doc_text=doc_text,
                     importance=self._infer_importance(path, "class", entry_points),
                 ))
@@ -291,10 +292,11 @@ class DocAnalyzer:
                     continue
                 doc_text = self._clean_javadoc(jd_match.group(1))
                 records.append(DocRecord(
+                    symbol=name,
+                    kind="function",
+                    language="java",
                     path=path,
                     workspace=workspace,
-                    kind="function",
-                    name=name,
                     doc_text=doc_text,
                     importance=self._infer_importance(path, "function", entry_points),
                 ))

sourcecode/mcp/server.py

@@ -78,8 +78,9 @@ def get_endpoints(repo_path: str = ".") -> dict:
     """REST API endpoint surface extraction from Java source files.
 
     Maps to: sourcecode endpoints <repo_path>
-    Returns: endpoints list with method, path, controller, handler, required_permission;
-             total count and undocumented count.
+    Returns: endpoints list with method, path, controller, handler fields;
+             total (int) and undocumented (int) counts.
+    Supports Spring MVC (@GetMapping etc.) and JAX-RS (@GET/@POST etc.).
     repo_path: absolute path to the repository (default: current working directory).
     """
     if not isinstance(repo_path, str):
@@ -179,6 +180,49 @@ def onboard_context(repo_path: str = ".") -> dict:
     return _execute(["prepare-context", "onboard", repo_path])
 
 
+@mcp.tool()
+def explain_context(repo_path: str = ".") -> dict:
+    """Architecture and entry-point explanation for a repository.
+
+    Maps to: sourcecode prepare-context explain <repo_path>
+    Returns: project summary, architecture, entry points, key dependencies.
+    repo_path: absolute path to the repository (default: current working directory).
+    """
+    if not isinstance(repo_path, str):
+        return _err("repo_path must be a string", "INVALID_ARGUMENT")
+    return _execute(["prepare-context", "explain", repo_path])
+
+
+@mcp.tool()
+def refactor_context(repo_path: str = ".") -> dict:
+    """Structural issues and refactor opportunities for a repository.
+
+    Maps to: sourcecode prepare-context refactor <repo_path>
+    Returns: structural issues, coupling hotspots, improvement opportunities.
+    repo_path: absolute path to the repository (default: current working directory).
+    """
+    if not isinstance(repo_path, str):
+        return _err("repo_path must be a string", "INVALID_ARGUMENT")
+    return _execute(["prepare-context", "refactor", repo_path])
+
+
+@mcp.tool()
+def generate_tests_context(repo_path: str = ".", include_all: bool = False) -> dict:
+    """Untested source files and test gap analysis for a repository.
+
+    Maps to: sourcecode prepare-context generate-tests <repo_path> [--all]
+    Returns: test_gaps list of untested files ranked by risk.
+    repo_path: absolute path to the repository (default: current working directory).
+    include_all: return full test_gaps list without truncating to top 20.
+    """
+    if not isinstance(repo_path, str):
+        return _err("repo_path must be a string", "INVALID_ARGUMENT")
+    args = ["prepare-context", "generate-tests", repo_path]
+    if include_all:
+        args.append("--all")
+    return _execute(args)
+
+
 _TELEMETRY_ACTIONS = frozenset({"status", "enable", "disable"})
 
 

sourcecode/prepare_context.py

@@ -573,17 +573,17 @@ def _read_code_signal_evidence(root: Path, file_path: str, artifact_type: str) -
 
 _ARTIFACT_CHANGE_EFFECT: dict[str, str] = {
     "entrypoint":     "application entrypoint (framework bootstrap / CLI handler)",
-    "controller":     "HTTP routing layer (request-to-handler mapping)",
-    "service":        "business logic layer (@Service component)",
-    "repository":     "data access layer (persistence queries / ORM)",
+    "controller":     "HTTP handler layer (Spring @RestController / JAX-RS @Path resource)",
+    "service":        "business logic layer (Spring @Service / CDI @ApplicationScoped bean)",
+    "repository":     "data access layer (persistence queries / ORM / CDI store)",
     "mapper":         "SQL-object mapping layer (MyBatis mapper / query template)",
     "security":       "security component (authentication / access control configuration)",
-    "spring_config":  "Spring @Configuration class (bean definitions / datasource wiring)",
-    "spring_profile": "Spring profile override (environment-specific configuration)",
+    "spring_config":  "framework configuration class (Spring @Configuration / Quarkus @QuarkusApplication)",
+    "spring_profile": "environment-specific configuration override (Spring profile / Quarkus profile)",
     "config":         "configuration file (application properties / environment values)",
     "build_manifest": "build manifest (dependency and plugin configuration)",
     "db_migration":   "database schema migration (DDL change pending execution)",
-    "domain_model":   "domain entity (@Entity / value object)",
+    "domain_model":   "domain entity (@Entity / CDI model / value object)",
     "dto":            "data transfer object (serialization contract)",
     "test":           "test file (no production code modified)",
     "documentation":  "documentation file (no runtime impact)",
@@ -1810,32 +1810,44 @@ class TaskContextBuilder:
                         )[:16000]
                         _pub_count = _content.count("public ")
                         _ann_count = (
+                            # Spring MVC / Spring Boot
                             _content.count("@Transactional")
                             + _content.count("@RequestMapping")
                             + _content.count("@GetMapping")
                             + _content.count("@PostMapping")
                             + _content.count("@PutMapping")
                             + _content.count("@DeleteMapping")
+                            # JAX-RS
+                            + _content.count("@Path")
+                            + _content.count("@GET")
+                            + _content.count("@POST")
+                            + _content.count("@PUT")
+                            + _content.count("@DELETE")
+                            + _content.count("@PATCH")
+                            # CDI / Jakarta EE
+                            + _content.count("@ApplicationScoped")
+                            + _content.count("@RequestScoped")
+                            + _content.count("@Singleton")
                         )
                     except OSError:
                         pass
                     _java_candidates.append({
                         "path": _p,
                         "public_method_count": _pub_count,
-                        "has_spring_annotations": _ann_count > 0,
+                        "has_framework_annotations": _ann_count > 0,
                         "_rank": _pub_count + _ann_count * 2,
                     })
 
                 _java_candidates.sort(
-                    key=lambda x: -(x["public_method_count"] * (1.5 if x["has_spring_annotations"] else 1.0))
+                    key=lambda x: -(x["public_method_count"] * (1.5 if x["has_framework_annotations"] else 1.0))
                 )
                 _top = _java_candidates if all_gaps else _java_candidates[:20]
                 test_gaps = [
                     {
                         "path": c["path"],
                         "public_method_count": c["public_method_count"],
-                        "has_spring_annotations": c["has_spring_annotations"],
-                        "rank_score": round(c["public_method_count"] * (1.5 if c["has_spring_annotations"] else 1.0), 1),
+                        "has_framework_annotations": c["has_framework_annotations"],
+                        "rank_score": round(c["public_method_count"] * (1.5 if c["has_framework_annotations"] else 1.0), 1),
                     }
                     for c in _top
                 ]
@@ -1893,15 +1905,20 @@ class TaskContextBuilder:
 
         conf_summary, analysis_gaps = ConfidenceAnalyzer().analyze(sm_for_conf)
         confidence = conf_summary.overall
+        _has_mybatis = any(
+            f.name == "MyBatis"
+            for s in stacks
+            for f in getattr(s, "frameworks", [])
+        )
         if task_name in ("delta", "review-pr"):
             # Use delta-specific gaps; ConfidenceAnalyzer gaps are about full-repo
             # detection quality and are not meaningful for an incremental diff.
             gaps = _delta_analysis_gaps
-            if _mybatis_warning:
+            if _mybatis_warning and _has_mybatis:
                 gaps.append(_mybatis_warning["reason"])
         else:
             gaps = [g.reason for g in analysis_gaps]
-            if _mybatis_warning:
+            if _mybatis_warning and _has_mybatis:
                 gaps.append(_mybatis_warning["reason"])
 
         # ── 9. why_these_files ────────────────────────────────────────────────
@@ -2103,8 +2120,15 @@ class TaskContextBuilder:
         _uncommitted = uncommitted_files or set()
         _max_churn = max(_hotspots.values(), default=1)
 
+        # Per-file note counts — feeds code_note_count into RankingEngine for all tasks.
+        # RankingEngine is the sole ranking source; no ad-hoc annotation boost outside it.
+        _note_counts: dict[str, int] = {}
+        for _n in (code_notes or []):
+            _np = getattr(_n, "path", "")
+            if _np:
+                _note_counts[_np] = _note_counts.get(_np, 0) + 1
+
         # Pre-compute fix-bug signals (used only when task_name == "fix-bug")
-        _annotated_files: set[str] = set()
         _dominant_stack = ""
         _recently_changed_stacks: set[str] = set()
         # Query-aware signals extracted from symptom (class names, exception types, tokens)
@@ -2113,10 +2137,6 @@ class TaskContextBuilder:
         _symptom_tokens: set[str] = set()          # all lowercase tokens
 
         if task_name == "fix-bug":
-            _bug_kinds = {"FIXME", "BUG", "HACK", "XXX"}
-            for _n in (code_notes or []):
-                if getattr(_n, "kind", "").upper() in _bug_kinds:
-                    _annotated_files.add(getattr(_n, "path", ""))
 
             def _file_stack(p: str) -> str:
                 ext = Path(p).suffix.lower()
@@ -2167,13 +2187,15 @@ class TaskContextBuilder:
             if is_test and task_name != "generate-tests":
                 continue
 
-            # Structural + git signals from unified engine (task-weighted)
+            # Structural + git signals from unified engine (task-weighted).
+            # code_note_count routes annotation density through RankingEngine — single source.
             fs = engine.score(
                 path,
                 is_entrypoint=(path in runtime_entry_set),
                 git_churn=_hotspots.get(path, 0),
                 max_churn=_max_churn,
                 is_changed=(path in _uncommitted),
+                code_note_count=_note_counts.get(path, 0),
                 task=task_name,
             )
 
@@ -2257,6 +2279,9 @@ class TaskContextBuilder:
                     # Single-token match: no boost — avoids OR explosion
 
                 # ── Git / annotation signals ──
+                _note_ct = _note_counts.get(path, 0)
+                if _note_ct > 0:
+                    _why_parts.append(f"annotation density ({_note_ct} FIXME/BUG/HACK notes)")
                 if path in _uncommitted:
                     content_boost += 0.40
                     _why_parts.append("uncommitted change (+0.40)")
@@ -2264,9 +2289,6 @@ class TaskContextBuilder:
                 if _recency > 0:
                     content_boost += _recency
                     _why_parts.append(f"recent commits (+{_recency:.2f})")
-                if path in _annotated_files:
-                    content_boost += 0.20
-                    _why_parts.append("FIXME/BUG annotation (+0.20)")
                 _file_stk = _file_stack(path)
                 if _dominant_stack and _file_stk == _dominant_stack:
                     content_boost += 0.10
@@ -2357,12 +2379,22 @@ class TaskContextBuilder:
             if task_name == "onboard":
                 def _arch_layer(p: str) -> str:
                     n = Path(p).name.lower()
+                    is_java = n.endswith(".java")
+                    # HTTP handler layer: Spring MVC controllers AND JAX-RS resources/endpoints
+                    # Restrict "resource"/"endpoint" to .java files to avoid matching
+                    # Maven's src/main/resources/ directory or XML resource files.
                     if "controller" in n:
                         return "controllers"
-                    if "repository" in n or "mapper" in n or "dao" in n:
+                    if is_java and ("resource" in n or "endpoint" in n or "restadapter" in n):
+                        return "controllers"
+                    # Data access layer: Spring repos, DAOs, JDBC, JPA stores
+                    if "repository" in n or "mapper" in n or "dao" in n or "store" in n:
                         return "repositories"
+                    # Business logic: Spring @Service, CDI providers, factories
                     if "service" in n:
                         return "services"
+                    if is_java and ("provider" in n or "factory" in n or "manager" in n):
+                        return "services"
                     pn = p.replace("\\", "/")
                     if "entity" in n or "/entity/" in pn or "/domain/" in pn or "/model/" in pn:
                         return "domain"