sourcecode 2.0.1__py3-none-any.whl → 2.2.0__py3-none-any.whl

sourcecode/mcp/server.py

@@ -108,14 +108,14 @@ def _coerce_cli_error(exc: Exception, default_message: str) -> CallToolResult:
             and "pro" in payload.get("error", "").lower()
         ):
             feature = payload.get("feature", "")
-            msg = payload.get("message", f"'{feature}' requires a Pro license. Run: sourcecode activate <key>")
+            msg = payload.get("message", f"'{feature}' requires a Pro license. Run: ask activate <key>")
             structured = {
                 "success": False,
                 "data": None,
                 "error": build_error_object(
                     "PRO_REQUIRED",
                     msg,
-                    hint="sourcecode activate <license_key>",
+                    hint="ask activate <license_key>",
                     expected="Active Pro license.",
                 ),
             }
@@ -627,7 +627,7 @@ def get_compact_context(repo_path: str = ".", git_context: bool = False) -> dict
     Includes security_surface, mybatis, and transactional_boundaries for Java/Spring projects.
     For richer machine-oriented detail (deeper signals, more sections), use get_agent_context.
 
-    Maps to: sourcecode <repo_path> --compact [--git-context]
+    Maps to: ask <repo_path> --compact [--git-context]
     repo_path: absolute path to the repository (default: current working directory).
     git_context: include git log and branch context in the analysis.
     """
@@ -661,7 +661,7 @@ def get_agent_context(repo_path: str = ".", git_context: bool = False) -> dict:
     architecture layers, security surface, transactional boundaries, module graph summary.
     Prefer get_compact_context for quick orientation or token-constrained workflows.
 
-    Maps to: sourcecode <repo_path> --agent [--git-context]
+    Maps to: ask <repo_path> --agent [--git-context]
     repo_path: absolute path to the repository (default: current working directory).
     git_context: include git log and branch context in the analysis.
     """
@@ -696,7 +696,7 @@ def get_endpoints(repo_path: str = ".") -> dict:
     Do NOT call this on non-Java repositories — it will return empty results.
     Use get_compact_context or get_agent_context for non-Java repos.
 
-    Maps to: sourcecode endpoints <repo_path>
+    Maps to: ask endpoints <repo_path>
     Returns: endpoints list with method, path, controller, handler fields;
              security dict always present (policy: roles_allowed|permit_all|deny_all|
              authenticated|...|none_detected); none_detected = no auth annotation found.
@@ -733,7 +733,7 @@ def get_spring_audit(repo_path: str = ".", scope: str = "all") -> dict:
 
     Do NOT call this on non-Java repositories — it will return spring_detected=false.
 
-    Maps to: sourcecode spring-audit <repo_path> --scope <scope>
+    Maps to: ask spring-audit <repo_path> --scope <scope>
     Returns: SpringAuditResult with schema_version, spring_detected, scope, summary,
              findings list (id, pattern_id, category, severity, confidence, title,
              symbol, source_file, evidence, explanation, fix_hint), limitations, metadata.
@@ -790,7 +790,7 @@ def get_migration_readiness(repo_path: str = ".", min_severity: str = "low") ->
     the goal is migration planning — not ongoing audit.
     Do NOT call on non-Java repositories — returns readiness_score=null (N/A) with no findings.
 
-    Maps to: sourcecode migrate-check <repo_path> --min-severity <min_severity>
+    Maps to: ask migrate-check <repo_path> --min-severity <min_severity>
     Returns: MigrationReport with schema_version, readiness_score (0–100, or null=N/A when no migration target applies; 100=ready to migrate),
              jakarta_readiness / boot3_readiness / jdk_modernization / hibernate_readiness
              (per-dimension 0–100), headline_blocker (e.g. "hibernate_rewrite" or null),
@@ -847,7 +847,7 @@ def get_impact_chain(repo_path: str = ".", symbol: str = "", depth: int = 4) ->
 
     Do NOT call this on non-Java repositories — it will return resolution=not_found.
 
-    Maps to: sourcecode impact-chain <symbol> <repo_path> [--depth <depth>]
+    Maps to: ask impact-chain <symbol> <repo_path> [--depth <depth>]
     Returns: ImpactChainResult with schema_version, symbol, resolution,
              direct_callers, indirect_callers, endpoints_affected,
              transaction_boundary (propagation/isolation/read_only),
@@ -901,7 +901,7 @@ def get_impact_chain(repo_path: str = ".", symbol: str = "", depth: int = 4) ->
 def get_module_context(repo_path: str = ".", module: str = "") -> dict:
     """Compact analysis of a specific module or subdirectory within a repository.
 
-    Maps to: sourcecode <repo_path>/<module> --compact
+    Maps to: ask <repo_path>/<module> --compact
     repo_path: absolute path to the repository root.
     module: subdirectory name relative to repo_path (e.g. 'src/auth', 'api', 'core').
     """
@@ -944,7 +944,7 @@ def _auto_since(repo_path: str) -> str:
 def get_delta(repo_path: str = ".", since: str = "") -> dict:
     """Incremental context: git-changed files since a reference commit.
 
-    Maps to: sourcecode prepare-context delta <repo_path> --since <since>
+    Maps to: ask prepare-context delta <repo_path> --since <since>
     repo_path: absolute path to the repository (default: current working directory).
     since: git ref to diff against (e.g. HEAD~3, main, origin/main).
            If empty or omitted, auto-detects merge-base with origin/main (or
@@ -1055,12 +1055,12 @@ def check_freshness(repo_path: str = ".") -> dict:
 def get_ir_summary(repo_path: str = ".") -> dict:
     """Deterministic symbol-level IR summary for Java repositories. Java only.
 
-    Maps to: sourcecode repo-ir <repo_path> --summary-only
+    Maps to: ask repo-ir <repo_path> --summary-only
     Returns: reverse_graph (top 10 hubs), route_surface (top 50 endpoints),
              subsystems (top 15), impact, analysis. Full graph nodes/edges omitted.
 
     Output is bounded to ~100 KB for LLM safety. For full IR (can exceed 10 MB
-    on large repos), use the CLI: sourcecode repo-ir <path> --output ir.json
+    on large repos), use the CLI: ask repo-ir <path> --output ir.json
     Use get_compact_context or get_agent_context for non-Java repos.
 
     IR access paths (for full IR via CLI):
@@ -1097,7 +1097,7 @@ def get_ir_summary(repo_path: str = ".") -> dict:
 def fix_bug_context(repo_path: str = ".", symptom: str = "") -> dict:
     """Risk-ranked files for bug investigation, optionally focused by symptom.
 
-    Maps to: sourcecode prepare-context fix-bug <repo_path> [--symptom <symptom>]
+    Maps to: ask prepare-context fix-bug <repo_path> [--symptom <symptom>]
     Includes compact_base: security_surface, transactional_boundaries, spring_profiles.
     repo_path: absolute path to the repository (default: current working directory).
     symptom: optional error message or class name to focus the file ranking
@@ -1126,7 +1126,7 @@ def fix_bug_context(repo_path: str = ".", symptom: str = "") -> dict:
 def review_pr_context(repo_path: str = ".", since: str = "") -> dict:
     """Execution paths and risk analysis for changed files in a pull request.
 
-    Maps to: sourcecode prepare-context review-pr <repo_path> [--since <since>]
+    Maps to: ask prepare-context review-pr <repo_path> [--since <since>]
     Returns: compact_base + execution_paths (diff-scoped) + hotspots for changed files.
     repo_path: absolute path to the repository (default: current working directory).
     since: git ref to diff against (e.g. HEAD~3, main, origin/main).
@@ -1155,7 +1155,7 @@ def review_pr_context(repo_path: str = ".", since: str = "") -> dict:
 def onboard_context(repo_path: str = ".") -> dict:
     """Onboarding context: structured overview for new contributors.
 
-    Maps to: sourcecode prepare-context onboard <repo_path>
+    Maps to: ask prepare-context onboard <repo_path>
     repo_path: absolute path to the repository (default: current working directory).
     """
     _raw = repo_path
@@ -1178,7 +1178,7 @@ def onboard_context(repo_path: str = ".") -> dict:
 def explain_context(repo_path: str = ".") -> dict:
     """Architecture and entry-point explanation for a repository.
 
-    Maps to: sourcecode prepare-context explain <repo_path>
+    Maps to: ask prepare-context explain <repo_path>
     Returns: project summary, architecture, entry points, key dependencies.
     repo_path: absolute path to the repository (default: current working directory).
     """
@@ -1202,7 +1202,7 @@ def explain_context(repo_path: str = ".") -> dict:
 def refactor_context(repo_path: str = ".") -> dict:
     """Structural issues and refactor opportunities for a repository.
 
-    Maps to: sourcecode prepare-context refactor <repo_path>
+    Maps to: ask prepare-context refactor <repo_path>
     Returns: structural issues, coupling hotspots, improvement opportunities.
     repo_path: absolute path to the repository (default: current working directory).
     """
@@ -1226,7 +1226,7 @@ def refactor_context(repo_path: str = ".") -> dict:
 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]
+    Maps to: ask prepare-context generate-tests <repo_path> [--all]
     Returns: test_gaps list of untested files ranked by risk.
             On large repos (>2000 classes) analysis is bounded by SOURCECODE_TESTS_TIMEOUT_MS
             (default: 15000 ms). If timeout elapses, returns truncated=true with partial results.
@@ -1279,7 +1279,7 @@ def generate_tests_context(repo_path: str = ".", include_all: bool = False) -> d
 def get_impact_context(repo_path: str = ".", target: str = "", depth: int = 4) -> dict:
     """Blast-radius analysis: who calls a class and what breaks if it changes? Java only.
 
-    Maps to: sourcecode impact <target> <repo_path> [--depth <depth>]
+    Maps to: ask impact <target> <repo_path> [--depth <depth>]
     Returns: direct_callers, indirect_callers, endpoints_affected,
              transactional_boundaries_touched, risk_score, risk_level, stats.
 
@@ -1334,7 +1334,7 @@ def get_impact_context(repo_path: str = ".", target: str = "", depth: int = 4) -
 def modernize_context(repo_path: str = ".", format: str = "json") -> dict:
     """Analyzes codebase for modernization opportunities: dead zones, hotspot scores, upgrade candidates.
 
-    Maps to: sourcecode modernize <repo_path>
+    Maps to: ask modernize <repo_path>
     Returns: hotspot_candidates (high fan-in + git churn), statically_unreferenced (zero-caller classes — NOT confirmed dead; verify no framework dispatch) + framework_dispatched,
              high_coupling_nodes, subsystem_summary, cross_module_tangles, recommendation.
 
@@ -1368,9 +1368,9 @@ _TELEMETRY_ACTIONS = frozenset({"status", "enable", "disable"})
 
 @mcp.tool()
 def version() -> dict:
-    """Return sourcecode version and MCP compatibility metadata.
+    """Return ASK Engine version and MCP compatibility metadata.
 
-    Maps to: sourcecode version
+    Maps to: ask version
     Returns structured JSON: cli_version, mcp_schema_version, compatibility_schema_version.
     cli_version and mcp_schema_version are always identical (released together).
     """
@@ -1381,7 +1381,7 @@ def version() -> dict:
 def config() -> dict:
     """Show sourcecode CLI configuration.
 
-    Maps to: sourcecode config
+    Maps to: ask config
     """
     return _execute(["config"])
 
@@ -1390,7 +1390,7 @@ def config() -> dict:
 def telemetry(action: str) -> dict:
     """Manage telemetry settings.
 
-    Maps to: sourcecode telemetry <action>
+    Maps to: ask telemetry <action>
     action: one of "status" (show current state), "enable" (opt in), "disable" (opt out).
     Valid values: "status" | "enable" | "disable"
     """

sourcecode/mcp_nudge.py

@@ -26,7 +26,7 @@ _FLAG: Path = Path.home() / ".sourcecode" / "nudge_shown"
 
 _MSG = (
     "→ Claude Desktop detected. "
-    "Run `sourcecode mcp init` to enable agent integration.\n"
+    "Run `ask mcp init` to enable agent integration.\n"
 )
 
 # Module-level imports so names are patchable in tests.

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

sourcecode/repository_ir.py

@@ -22,6 +22,8 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Iterable, Optional
 
+from sourcecode.caller_metrics import CALLER_METRIC_RECONCILIATION
+from sourcecode.endpoint_metrics import ENDPOINT_SURFACE_RECONCILIATION
 from sourcecode.fqn_utils import normalize_owner_fqn as _normalize_owner_fqn
 from sourcecode.path_filters import is_test_path as _is_test_path
 from sourcecode.security_config import (
@@ -3965,6 +3967,11 @@ def _assemble(
     return {
         **_base,
         "route_surface": _route_surface,
+        # SC-9 (Broadleaf field test): route_surface is the RAW surface (includes
+        # framework dynamic-admin FQN-shaped routes the `endpoints` command filters).
+        # Self-describe it so its count is never read as contradicting endpoints /
+        # spring-audit totals when cross-referenced.
+        "route_surface_note": ENDPOINT_SURFACE_RECONCILIATION,
         "spring_events": _spring_events,
         "analysis_gaps": _analysis_gaps,
         "security_model": _security_model_asm,
@@ -4236,6 +4243,10 @@ def _build_route_surface(
                     "return_type": (sym.return_type.strip() if sym.return_type else "void"),
                     "stable_id": sym.stable_id,
                     "inheritance_depth": 0,
+                    # Provenance: which annotation family this modeled route came from.
+                    # Used downstream so a MODELED framework (JAX-RS) is never also reported
+                    # as an un-modeled "non_spring_rest_surface" (A2 field-validation fix).
+                    "framework": "jax_rs" if ann_name in _JAXRS_HTTP_ANNOTATIONS else "spring_mvc",
                 }
                 _route_entry["security_annotations"] = _sec
                 routes.append(_route_entry)
@@ -4721,11 +4732,16 @@ def apply_ir_size_limits(
         if isinstance(raw_rs, list):
             _rs_total = len(raw_rs)
             out["route_surface"] = raw_rs[:50]
+            # SC-9: always carry the raw-surface reconciliation note; prepend the
+            # truncation notice when the list was capped.
             if _rs_total > 50:
                 out["route_surface_note"] = (
-                    f"Showing 50/{_rs_total} endpoints. "
-                    "Remove --summary-only for full route surface."
+                    f"Showing 50/{_rs_total} route-surface entries. "
+                    "Remove --summary-only for the full route surface. "
+                    + ENDPOINT_SURFACE_RECONCILIATION
                 )
+            else:
+                out["route_surface_note"] = ENDPOINT_SURFACE_RECONCILIATION
         elif isinstance(raw_rs, dict):
             # Legacy dict format with "endpoints" sub-key
             raw_eps: list = raw_rs.get("endpoints") or []
@@ -5116,16 +5132,19 @@ def extract_java_endpoints(root: Path) -> "dict[str, Any]":
     # total false negative that also disables the `validation` command downstream.
     # Detection is by SYNTACTIC SHAPE (no framework knowledge): an HTTP-verb method
     # name, a first argument that is a string literal looking like a path (starts
-    # with "/", may contain :param / {param}), AND a second argument (the trailing
-    # comma) — the comma is what distinguishes a route registration from a 1-arg
-    # getter such as Map.get("/k"). Matches both bare `get(...)` (static-import /
-    # Spark style) and `app.get(...)` (Javalin style); the lookbehind only rejects
-    # an identifier char so `forget(` is not mistaken for `get(`. Reported at
-    # confidence "medium" — an occasional flagged false positive beats a total
-    # silent false negative.
+    # with "/", may contain :param / {param}), AND a second argument that is a
+    # HANDLER, not a literal. Matches both bare `get(...)` (static-import / Spark
+    # style) and `app.get(...)` (Javalin style); the lookbehind only rejects an
+    # identifier char so `forget(` is not mistaken for `get(`.
+    # B1 fix (field validation, openmrs FormUtil): a route handler is always a
+    # method-ref / lambda / call / identifier — never a bare literal. The negative
+    # lookahead after the comma rejects a literal second argument, so a plain map
+    # write like `swapChars.put("/", "slash")` is no longer mistaken for a `PUT /`
+    # route. Reported at confidence "medium" — an occasional flagged false positive
+    # beats a total silent false negative.
     _DSL_ROUTE_RE = _re.compile(
         r'(?<![A-Za-z0-9_])(get|post|put|delete|patch|head|options)\s*\(\s*'
-        r'"(/[^"\s]*)"\s*,'
+        r'"(/[^"\s]*)"\s*,(?!\s*(?:["0-9]|true\b|false\b|null\b))'
     )
     _dsl_routes: list[dict] = []
 
@@ -5441,6 +5460,15 @@ def extract_java_endpoints(root: Path) -> "dict[str, Any]":
     if _webscript_descriptors:
         _nonspring["webscripts"] += _webscript_descriptors
 
+    # A2 fix (eureka/keycloak field validation): JAX-RS is MODELED by _build_route_surface
+    # (routes carry framework="jax_rs"). When we actually modeled JAX-RS endpoints, it is
+    # NOT an un-modeled "non_spring_rest_surface" — reporting it as such contradicted the
+    # endpoints just emitted (e.g. keycloak's 689 JAX-RS routes labelled "not modeled").
+    # Only genuinely un-modeled surfaces (WebScripts, Servlets, or JAX-RS that produced no
+    # modeled route — client proxies / extraction gaps) remain here.
+    if any(r.get("framework") == "jax_rs" for r in routes):
+        _nonspring.pop("jax_rs", None)
+
     _nonspring_total = sum(_nonspring.values())
     if _nonspring_total:
         _frameworks = [k for k, v in _nonspring.items() if v]
@@ -5471,9 +5499,9 @@ def extract_java_endpoints(root: Path) -> "dict[str, Any]":
             )
         else:
             _msg = (
-                f"Additional REST surface present outside Spring MVC: detected {_fw_label}. "
-                f"These endpoints are NOT modeled here; the count covers Spring-MVC-annotated "
-                f"endpoints only."
+                f"Additional REST surface detected but NOT modeled here: {_fw_label}. "
+                f"The endpoints above cover the annotation-modeled surface (Spring MVC and "
+                f"JAX-RS); the {_fw_label} surface is additional and not included in the count."
             )
         result.setdefault("warnings", []).append(_msg)
 
@@ -5648,7 +5676,7 @@ def compute_blast_radius(
             "message": (
                 f"No symbol matching {target!r} found in IR. "
                 "Verify the class name or FQN. "
-                "Run `sourcecode repo-ir <repo> --output ir.json` to inspect available symbols."
+                "Run `ask repo-ir <repo> --output ir.json` to inspect available symbols."
             ),
             "direct_callers": [],
             "indirect_callers": [],
@@ -6153,10 +6181,18 @@ def compute_blast_radius(
                 "no indirect callers reachable from sampled seeds (terminal sink or sparse graph). "
                 "Use a lower-fan-in entry point for full transitive traversal."
             )
+    # SC-6 (Broadleaf field test): the direct_callers array is a truncated display
+    # sample. Disclose the cap and point to stats.direct_caller_count as the true
+    # total (== explain.incoming_callers), then append the cross-command
+    # reconciliation so len(direct_callers) is never misread as a contradiction.
     if len(direct_callers) > 30:
         out["direct_callers_note"] = (
-            f"Showing 30/{n_direct} direct callers. Use --output to inspect full IR."
+            f"Showing 30/{n_direct} distinct direct callers; "
+            f"stats.direct_caller_count = {n_direct} is the true total "
+            f"(use --output for the full list). " + CALLER_METRIC_RECONCILIATION
         )
+    else:
+        out["direct_callers_note"] = CALLER_METRIC_RECONCILIATION
     if len(indirect_callers) > 50:
         out["indirect_callers_note"] = (
             f"Showing 50/{n_indirect} indirect callers. Use --output to inspect full IR."

sourcecode/ris.py

@@ -506,7 +506,7 @@ def get_cold_start_context(repo_root: Path) -> dict:
         if not endpoints and _is_java:
             result["endpoints_hint"] = (
                 "Java repo detected but no endpoint index found. "
-                "Call get_endpoints (or: sourcecode endpoints <path>) to populate."
+                "Call get_endpoints (or: ask endpoints <path>) to populate."
             )
         return result
     except Exception: