sourcecode 1.35.6__py3-none-any.whl → 1.35.8__py3-none-any.whl

sourcecode/__init__.py

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

sourcecode/mcp/registry.py

@@ -10,7 +10,7 @@ Internal helpers remain explicitly marked and are not exported to MCP.
 """
 from __future__ import annotations
 
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 import inspect
 from functools import lru_cache
 from typing import Any, Callable, Mapping
@@ -69,6 +69,7 @@ class ToolSpec:
     aliases: tuple[str, ...] = ()
     internal: bool = False
     not_exposed_to_cli: bool = False
+    mcp_hidden: bool = False
     docstring: str = ""
     runtime_command: str = ""
     _argv_builder: Callable[[Mapping[str, Any]], list[str]] | None = field(
@@ -82,6 +83,10 @@ class ToolSpec:
     def public(self) -> bool:
         return not self.internal and not self.not_exposed_to_cli
 
+    @property
+    def mcp_visible(self) -> bool:
+        return self.public and not self.mcp_hidden
+
     def build_argv(self, inputs: Mapping[str, Any]) -> list[str]:
         if self._argv_builder is None:
             raise RuntimeError(f"ToolSpec '{self.name}' has no argv builder")
@@ -488,8 +493,11 @@ def _alias_spec(
     aliases: tuple[str, ...] = (),
     internal: bool = False,
     not_exposed_to_cli: bool = False,
+    mcp_hidden: bool = False,
+    docstring_override: str | None = None,
     validator: Callable[[Mapping[str, Any]], str | None] | None = None,
 ) -> ToolSpec:
+    doc = docstring_override or _build_contract_doc(description, params, cli_path, supported_targets, unsupported_targets)
     return ToolSpec(
         name=name,
         description=description,
@@ -500,7 +508,8 @@ def _alias_spec(
         aliases=aliases,
         internal=internal,
         not_exposed_to_cli=not_exposed_to_cli,
-        docstring=_build_contract_doc(description, params, cli_path, supported_targets, unsupported_targets),
+        mcp_hidden=mcp_hidden,
+        docstring=doc,
         runtime_command=" ".join(cli_path) if cli_path else "sourcecode",
         _argv_builder=argv_builder,
         validator=validator,
@@ -535,41 +544,86 @@ def _root_aliases() -> list[ToolSpec]:
         module = str(inputs["module"]).strip("/")
         return [f"{repo_path}/{module}", "--compact"]
 
+    _GET_COMPACT_DOC = """\
+Compact human/LLM summary of a repository (~1000-3000 tokens). USE THIS FIRST.
+
+Best for: quick project orientation, first-time context, token-budget constrained tasks.
+Returns: stacks, entry points, dependency summary, architecture summary, confidence, gaps.
+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]
+repo_path: absolute path to the repository (default: current working directory).
+git_context: include git log and branch context in the analysis.
+"""
+
+    _GET_AGENT_DOC = """\
+Full structured agent context with extended machine-oriented signals (~5000-15000 tokens).
+
+Best for: deep analysis, bug investigation, code review, or when get_compact_context
+lacks sufficient detail. Includes all compact fields plus: env_map, code_notes,
+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]
+repo_path: absolute path to the repository (default: current working directory).
+git_context: include git log and branch context in the analysis.
+"""
+
+    _GET_MODULE_DOC = """\
+Compact analysis of a specific module or subdirectory within a repository.
+
+Maps to: sourcecode <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').
+Returns: same fields as get_compact_context but scoped to the module subtree.
+"""
+
+    _TELEMETRY_DOC = """\
+Manage telemetry settings.
+
+Maps to: sourcecode telemetry <action>
+action: one of "status" (show current state), "enable" (opt in), "disable" (opt out).
+Valid values: "status" | "enable" | "disable"
+"""
+
     return [
         _alias_spec(
             "get_compact_context",
-            "Compact repository summary derived from the root CLI command. "
-            "Use get_agent_context for richer detail.",
+            "Compact human/LLM summary of a repository (~1000-3000 tokens). USE THIS FIRST.",
             ("sourcecode",),
             params_compact,
             compact_argv,
             supported_targets=("repo_path",),
             unsupported_targets=("file_path",),
             validator=validate_repo_path,
+            docstring_override=_GET_COMPACT_DOC,
         ),
         _alias_spec(
             "get_agent_context",
-            "Extended repository context derived from the root CLI command.",
+            "Full structured agent context with extended machine-oriented signals (~5000-15000 tokens).",
             ("sourcecode",),
             params_compact,
             agent_argv,
             supported_targets=("repo_path",),
             unsupported_targets=("file_path",),
             validator=validate_repo_path,
+            docstring_override=_GET_AGENT_DOC,
         ),
         _alias_spec(
             "get_module_context",
-            "Compact context for a specific module path derived from the root CLI command.",
+            "Compact analysis of a specific module or subdirectory within a repository.",
             ("sourcecode",),
             params_module,
             module_argv,
             supported_targets=("repo_path", "module_path"),
             unsupported_targets=("file_path",),
             validator=validate_repo_path,
+            docstring_override=_GET_MODULE_DOC,
         ),
         _alias_spec(
             "telemetry",
-            "Telemetry action helper alias that dispatches to the telemetry CLI group.",
+            "Manage telemetry settings: status | enable | disable.",
             ("telemetry",),
             (
                 ToolParamSpec(
@@ -582,6 +636,7 @@ def _root_aliases() -> list[ToolSpec]:
             ),
             lambda inputs: ["telemetry", str(inputs["action"])],
             supported_targets=("action",),
+            docstring_override=_TELEMETRY_DOC,
         ),
     ]
 
@@ -589,10 +644,20 @@ def _root_aliases() -> list[ToolSpec]:
 def _prepare_context_aliases() -> list[ToolSpec]:
     validate_repo_path = _repo_path_validator()
 
-    def task_alias(name: str, task: str, description: str, *, supported_targets: tuple[str, ...]) -> ToolSpec:
+    # Only used for prepare-context tasks that genuinely accept --since (delta, review-pr).
+    def _since_task_alias(
+        name: str,
+        task: str,
+        description: str,
+        *,
+        supported_targets: tuple[str, ...],
+        docstring_override: str | None = None,
+    ) -> ToolSpec:
         params = (
             ToolParamSpec("repo_path", "argument", str, required=False, default=".", is_path=True),
-            ToolParamSpec("since", "argument", str, required=False, default=""),
+            ToolParamSpec("since", "option", str, required=False, default="",
+                          option_names=("--since",),
+                          help="Git ref to diff against (e.g. HEAD~3, origin/main)."),
         )
 
         def argv_builder(inputs: Mapping[str, Any]) -> list[str]:
@@ -602,7 +667,6 @@ def _prepare_context_aliases() -> list[ToolSpec]:
             if not value and name == "get_delta":
                 try:
                     from sourcecode.mcp.server import _auto_since as _resolve_since
-
                     value = _resolve_since(repo_path)
                 except Exception:
                     value = "HEAD~1"
@@ -619,31 +683,310 @@ def _prepare_context_aliases() -> list[ToolSpec]:
             supported_targets=supported_targets,
             unsupported_targets=("file_path",),
             validator=validate_repo_path,
+            docstring_override=docstring_override,
         )
 
+    _GET_DELTA_DOC = """\
+Incremental context: git-changed files since a reference commit.
+
+Maps to: sourcecode 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
+       origin/master). Falls back to HEAD~1 if no remote branch found.
+       Pass "HEAD~1" explicitly to force single-commit diff.
+"""
+
+    _REVIEW_PR_DOC = """\
+Execution paths and risk analysis for changed files in a pull request.
+
+Maps to: sourcecode 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).
+       If omitted, diffs against uncommitted changes or HEAD~1 fallback.
+"""
+
+    _FIX_BUG_DOC = """\
+Risk-ranked files for bug investigation, optionally focused by symptom.
+
+Maps to: sourcecode 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
+         (e.g. "NullPointerException in UserService.findById").
+         Without symptom, ranking is generic (by churn/complexity). With symptom,
+         the matching class and its callers are ranked first.
+"""
+
+    _ONBOARD_DOC = """\
+Onboarding context: structured overview for new contributors.
+
+Maps to: sourcecode prepare-context onboard <repo_path>
+Returns: project structure, key entry points, architectural patterns, getting-started guide.
+repo_path: absolute path to the repository (default: current working directory).
+"""
+
+    _EXPLAIN_DOC = """\
+Architecture and entry-point explanation for a repository.
+
+Maps to: sourcecode prepare-context explain <repo_path>
+Returns: project summary, architecture overview, entry points, key dependencies.
+repo_path: absolute path to the repository (default: current working directory).
+"""
+
+    _REFACTOR_DOC = """\
+Structural issues and refactor opportunities for a repository.
+
+Maps to: sourcecode prepare-context refactor <repo_path>
+Returns: structural issues, coupling hotspots, high-churn files, improvement opportunities.
+repo_path: absolute path to the repository (default: current working directory).
+"""
+
+    _GENERATE_TESTS_DOC = """\
+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.
+        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.
+repo_path: absolute path to the repository (default: current working directory).
+include_all: return full test_gaps list without truncating to top 20.
+"""
+
+    _IR_SUMMARY_DOC = """\
+Deterministic symbol-level IR summary for Java repositories. Java only.
+
+Maps to: sourcecode 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
+Use get_compact_context or get_agent_context for non-Java repos.
+
+repo_path: absolute path to the Java repository (default: current working directory).
+"""
+
+    _IMPACT_CONTEXT_DOC = """\
+Blast-radius analysis: who calls a class and what breaks if it changes? Java only.
+
+Maps to: sourcecode impact <target> <repo_path> [--depth <depth>]
+Returns: direct_callers, indirect_callers, endpoints_affected,
+         transactional_boundaries_touched, risk_score, risk_level, stats.
+
+Use this when:
+- Planning a refactor: understand the full call chain before changing a class
+- PR review: assess blast radius of a changed service or utility class
+- Incident triage: find all paths that reach a faulty component
+
+target: class name (simple or FQN) or Java file path. Examples:
+        "UserService", "org.example.UserService", "UserService.java"
+repo_path: absolute path to the Java repository (default: current working directory).
+depth: BFS depth for indirect caller traversal (1–8, default: 4).
+"""
+
+    _MODERNIZE_DOC = """\
+Analyzes codebase for modernization opportunities: dead zones, hotspot scores, upgrade candidates.
+
+Maps to: sourcecode modernize <repo_path>
+Returns: hotspot_candidates (high fan-in + git churn), dead_zone_candidates (isolated classes),
+         high_coupling_nodes, subsystem_summary, cross_module_tangles, recommendation.
+
+Best for: refactor planning, identifying where to start, finding safe removal candidates.
+Use get_compact_context or get_agent_context first for project orientation.
+
+repo_path: absolute path to the Java repository (default: current working directory).
+"""
+
+    _CHECK_FRESHNESS_DOC = """\
+Report RIS freshness relative to the current git HEAD.
+
+Answers instantly: is the cached snapshot current? How many commits behind?
+Use before deciding whether to call get_compact_context for a refresh.
+
+Returns:
+  fresh (bool)             — True when RIS HEAD == current HEAD and no uncommitted changes
+  current_git_head (str)   — Current repo HEAD (short SHA)
+  ris_git_head (str|null)  — HEAD stored in RIS at last build
+  delta_commits (int|null) — Commits between ris_git_head and HEAD (0 = in sync)
+  has_uncommitted_changes  — Working tree has staged or unstaged changes
+  ris_exists (bool)        — False when no RIS built yet
+  ris_last_updated_at (str)— ISO-8601 timestamp of last RIS write
+
+repo_path: absolute path to the repository (default: current working directory).
+"""
+
+    _COLD_START_DOC = """\
+Instant session bootstrap from persisted Repository Intelligence Snapshot (RIS).
+
+PREFER start_session over this tool — it provides orchestration guidance on top
+of the same RIS data. Use get_cold_start_context when you only need the raw
+RIS bootstrap object without tool sequencing recommendations.
+
+Returns cached structural context built from prior analysis runs — zero re-analysis cost.
+
+status values:
+  "cold_start_ready"  — RIS exists and matches the current git HEAD.
+  "cold_start_stale"  — RIS exists but HEAD has changed since last analysis.
+                        Data is still useful; run get_compact_context to refresh.
+  "no_ris"            — No RIS yet for this repo; run get_compact_context first.
+
+Returns: status, repo_id, git_head, stale (bool), last_updated_at,
+         summary (compact snapshot), entrypoints, endpoints, hotspots.
+
+repo_path: absolute path to the repository (default: current working directory).
+"""
+
+    _GET_ENDPOINTS_DOC = """\
+REST API endpoint surface extraction from Java source files. JAVA ONLY.
+
+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>
+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.
+         total (int), no_security_signal (int), and security_model (str) fields.
+         no_security_signal counts endpoints where security.policy == "none_detected".
+         security_model values: "filter_based" (centralized Spring Security config —
+         high no_security_signal is expected and does NOT mean endpoints are unprotected),
+         "annotation_based" (per-endpoint annotations only), "mixed" (both),
+         "unknown" (no security signals detected).
+Supports Spring MVC (@GetMapping etc.) and JAX-RS (@GET/@POST etc.).
+repo_path: absolute path to the Java repository (default: current working directory).
+"""
+
+    _CACHE_STATUS_DOC = """\
+Report cache metadata for a repository.
+
+Maps to: sourcecode cache status <repo_path> --json
+Returns: cache entries with git_head, timestamps, size info.
+Use check_freshness for RIS-specific freshness checking (faster, richer).
+repo_path: absolute path to the repository (default: current working directory).
+"""
+
+    _CACHE_WARM_DOC = """\
+Warm the cache for a repository (builds compact and agent analysis snapshots).
+
+Maps to: sourcecode cache warm <repo_path>
+Builds or refreshes the Repository Intelligence Snapshot (RIS).
+Use before analytical workflows to ensure fast subsequent tool calls (~8s first run,
+instant after).
+repo_path: absolute path to the repository (default: current working directory).
+"""
+
+    _CACHE_CLEAR_DOC = """\
+Clear cached analysis for a repository.
+
+Maps to: sourcecode cache clear <repo_path> [--include-ris]
+Removes cached context files. After clearing, run get_compact_context or cache_warm to rebuild.
+include_ris: also remove the RIS snapshot in addition to analysis cache (default: False).
+repo_path: absolute path to the repository (default: current working directory).
+"""
+
     return [
-        task_alias("get_delta", "delta", "Incremental delta context from prepare-context.", supported_targets=("repo_path", "git_ref")),
-        task_alias("fix_bug_context", "fix-bug", "Bug investigation context from prepare-context.", supported_targets=("repo_path", "symptom")),
-        task_alias("review_pr_context", "review-pr", "Pull-request review context from prepare-context.", supported_targets=("repo_path", "git_ref")),
-        task_alias("onboard_context", "onboard", "Onboarding context from prepare-context.", supported_targets=("repo_path",)),
-        task_alias("explain_context", "explain", "Architecture explanation from prepare-context.", supported_targets=("repo_path",)),
-        task_alias("refactor_context", "refactor", "Refactor context from prepare-context.", supported_targets=("repo_path",)),
+        # --- get_delta / review_pr_context: both genuinely use --since ---
+        _since_task_alias(
+            "get_delta", "delta",
+            "Incremental context: git-changed files since a reference commit.",
+            supported_targets=("repo_path", "git_ref"),
+            docstring_override=_GET_DELTA_DOC,
+        ),
+        _since_task_alias(
+            "review_pr_context", "review-pr",
+            "Execution paths and risk analysis for changed files in a pull request.",
+            supported_targets=("repo_path", "git_ref"),
+            docstring_override=_REVIEW_PR_DOC,
+        ),
+
+        # --- fix_bug_context: --symptom (not --since) ---
+        _alias_spec(
+            "fix_bug_context",
+            "Risk-ranked files for bug investigation, optionally focused by symptom.",
+            ("prepare-context",),
+            (
+                ToolParamSpec("repo_path", "argument", str, required=False, default=".", is_path=True),
+                ToolParamSpec("symptom", "option", str, required=False, default=None,
+                              option_names=("--symptom",),
+                              help="Error message or class name to focus file ranking."),
+            ),
+            lambda inputs: (
+                ["prepare-context", "fix-bug", str(inputs.get("repo_path", "."))]
+                + (["--symptom", str(inputs["symptom"])] if inputs.get("symptom") else [])
+            ),
+            supported_targets=("repo_path", "symptom"),
+            unsupported_targets=("file_path",),
+            validator=validate_repo_path,
+            docstring_override=_FIX_BUG_DOC,
+        ),
+
+        # --- onboard / explain / refactor: no --since ---
+        _alias_spec(
+            "onboard_context",
+            "Onboarding context: structured overview for new contributors.",
+            ("prepare-context",),
+            (
+                ToolParamSpec("repo_path", "argument", str, required=False, default=".", is_path=True),
+            ),
+            lambda inputs: ["prepare-context", "onboard", str(inputs.get("repo_path", "."))],
+            supported_targets=("repo_path",),
+            unsupported_targets=("file_path",),
+            validator=validate_repo_path,
+            docstring_override=_ONBOARD_DOC,
+        ),
+        _alias_spec(
+            "explain_context",
+            "Architecture and entry-point explanation for a repository.",
+            ("prepare-context",),
+            (
+                ToolParamSpec("repo_path", "argument", str, required=False, default=".", is_path=True),
+            ),
+            lambda inputs: ["prepare-context", "explain", str(inputs.get("repo_path", "."))],
+            supported_targets=("repo_path",),
+            unsupported_targets=("file_path",),
+            validator=validate_repo_path,
+            docstring_override=_EXPLAIN_DOC,
+        ),
+        _alias_spec(
+            "refactor_context",
+            "Structural issues and refactor opportunities for a repository.",
+            ("prepare-context",),
+            (
+                ToolParamSpec("repo_path", "argument", str, required=False, default=".", is_path=True),
+            ),
+            lambda inputs: ["prepare-context", "refactor", str(inputs.get("repo_path", "."))],
+            supported_targets=("repo_path",),
+            unsupported_targets=("file_path",),
+            validator=validate_repo_path,
+            docstring_override=_REFACTOR_DOC,
+        ),
+
+        # --- other prepare-context aliases ---
         _alias_spec(
             "generate_tests_context",
-            "Test gap analysis from prepare-context.",
+            "Untested source files and test gap analysis for a repository.",
             ("prepare-context",),
             (
                 ToolParamSpec("repo_path", "argument", str, required=False, default=".", is_path=True),
-                ToolParamSpec("include_all", "argument", bool, required=False, default=False, option_names=("--all",), is_flag=True),
+                ToolParamSpec("include_all", "option", bool, required=False, default=False,
+                              option_names=("--all",), is_flag=True),
+            ),
+            lambda inputs: (
+                ["prepare-context", "generate-tests", str(inputs.get("repo_path", "."))]
+                + (["--all"] if bool(inputs.get("include_all")) else [])
             ),
-            lambda inputs: ["prepare-context", "generate-tests", str(inputs.get("repo_path", "."))] + (["--all"] if bool(inputs.get("include_all")) else []),
             supported_targets=("repo_path",),
             unsupported_targets=("file_path",),
             validator=validate_repo_path,
+            docstring_override=_GENERATE_TESTS_DOC,
         ),
+
+        # --- Java analysis aliases ---
         _alias_spec(
             "get_ir_summary",
-            "Summary-mode Java IR context from repo-ir.",
+            "Deterministic symbol-level IR summary for Java repositories. Java only.",
             ("repo-ir",),
             (
                 ToolParamSpec("repo_path", "argument", str, required=False, default=".", is_path=True),
@@ -652,10 +995,11 @@ def _prepare_context_aliases() -> list[ToolSpec]:
             supported_targets=("repo_path",),
             unsupported_targets=("file_path",),
             validator=validate_repo_path,
+            docstring_override=_IR_SUMMARY_DOC,
         ),
         _alias_spec(
             "get_impact_context",
-            "Blast-radius analysis from impact.",
+            "Blast-radius analysis: who calls a class and what breaks if it changes? Java only.",
             ("impact",),
             (
                 ToolParamSpec("repo_path", "argument", str, required=False, default=".", is_path=True),
@@ -672,10 +1016,11 @@ def _prepare_context_aliases() -> list[ToolSpec]:
             supported_targets=("repo_path", "class_name"),
             unsupported_targets=("file_path",),
             validator=validate_repo_path,
+            docstring_override=_IMPACT_CONTEXT_DOC,
         ),
         _alias_spec(
             "modernize_context",
-            "Modernization analysis from modernize.",
+            "Modernization analysis: dead zones, hotspot scores, upgrade candidates.",
             ("modernize",),
             (
                 ToolParamSpec("repo_path", "argument", str, required=False, default=".", is_path=True),
@@ -684,10 +1029,13 @@ def _prepare_context_aliases() -> list[ToolSpec]:
             supported_targets=("repo_path",),
             unsupported_targets=("file_path",),
             validator=validate_repo_path,
+            docstring_override=_MODERNIZE_DOC,
         ),
+
+        # --- cache / freshness aliases ---
         _alias_spec(
             "check_freshness",
-            "Cache freshness check derived from cache freshness.",
+            "Report RIS freshness relative to the current git HEAD.",
             ("cache", "freshness"),
             (
                 ToolParamSpec("repo_path", "argument", str, required=False, default=".", is_path=True),
@@ -696,10 +1044,11 @@ def _prepare_context_aliases() -> list[ToolSpec]:
             supported_targets=("repo_path",),
             unsupported_targets=("file_path",),
             validator=validate_repo_path,
+            docstring_override=_CHECK_FRESHNESS_DOC,
         ),
         _alias_spec(
             "get_cold_start_context",
-            "Cold-start snapshot from the cold-start CLI command.",
+            "Instant session bootstrap from persisted Repository Intelligence Snapshot (RIS).",
             ("cold-start",),
             (
                 ToolParamSpec("repo_path", "argument", str, required=False, default=".", is_path=True),
@@ -708,6 +1057,69 @@ def _prepare_context_aliases() -> list[ToolSpec]:
             supported_targets=("repo_path",),
             unsupported_targets=("file_path",),
             validator=validate_repo_path,
+            docstring_override=_COLD_START_DOC,
+        ),
+
+        # --- get_endpoints: clean alias replacing raw canonical with 7 CLI params ---
+        _alias_spec(
+            "get_endpoints",
+            "REST API endpoint surface extraction from Java source files. JAVA ONLY.",
+            ("endpoints",),
+            (
+                ToolParamSpec("repo_path", "argument", str, required=False, default=".", is_path=True),
+            ),
+            lambda inputs: ["endpoints", str(inputs.get("repo_path", "."))],
+            supported_targets=("repo_path",),
+            unsupported_targets=("file_path",),
+            validator=validate_repo_path,
+            docstring_override=_GET_ENDPOINTS_DOC,
+        ),
+
+        # --- cache management: curated aliases stripping CLI noise params ---
+        _alias_spec(
+            "cache_status",
+            "Report cache metadata for a repository.",
+            ("cache", "status"),
+            (
+                ToolParamSpec("repo_path", "argument", str, required=False, default=".", is_path=True),
+            ),
+            lambda inputs: ["cache", "status", str(inputs.get("repo_path", ".")), "--json"],
+            supported_targets=("repo_path",),
+            unsupported_targets=("file_path",),
+            validator=validate_repo_path,
+            docstring_override=_CACHE_STATUS_DOC,
+        ),
+        _alias_spec(
+            "cache_warm",
+            "Warm the cache for a repository (builds compact and agent analysis snapshots).",
+            ("cache", "warm"),
+            (
+                ToolParamSpec("repo_path", "argument", str, required=False, default=".", is_path=True),
+            ),
+            lambda inputs: ["cache", "warm", str(inputs.get("repo_path", "."))],
+            supported_targets=("repo_path",),
+            unsupported_targets=("file_path",),
+            validator=validate_repo_path,
+            docstring_override=_CACHE_WARM_DOC,
+        ),
+        _alias_spec(
+            "cache_clear",
+            "Clear cached analysis for a repository.",
+            ("cache", "clear"),
+            (
+                ToolParamSpec("repo_path", "argument", str, required=False, default=".", is_path=True),
+                ToolParamSpec("include_ris", "option", bool, required=False, default=False,
+                              option_names=("--include-ris",), is_flag=True,
+                              help="Also remove RIS snapshot (default: False)."),
+            ),
+            lambda inputs: (
+                ["cache", "clear", str(inputs.get("repo_path", ".")), "--yes"]
+                + (["--include-ris"] if bool(inputs.get("include_ris")) else [])
+            ),
+            supported_targets=("repo_path",),
+            unsupported_targets=("file_path",),
+            validator=validate_repo_path,
+            docstring_override=_CACHE_CLEAR_DOC,
         ),
     ]
 
@@ -788,17 +1200,174 @@ def _internal_specs() -> list[ToolSpec]:
     ]
 
 
+# Canonical CLI tools that are MCP-noise: raw passthroughs, meta-commands, and duplicates
+# superseded by cleaner alias variants. Still tracked by validate_registry(); just not served.
+_MCP_HIDDEN_CANONICAL_TOOLS: frozenset[str] = frozenset({
+    # Raw CLI passthroughs (clean alias exists)
+    "sourcecode_root",    # 40+ flags, no agent guidance; use get_compact_context / get_agent_context
+    "prepare_context",    # requires knowing subtask string; use task-specific aliases
+    "repo_ir",            # raw IR dump; use get_ir_summary
+    "fix_bug",            # raw Pro command; use fix_bug_context for MCP
+    "review_pr",          # raw Pro command; use review_pr_context for MCP
+    "onboard",            # raw with llm_prompt/copy flags; use onboard_context
+    # Duplicates (inferior params — cleaner alias exists)
+    "impact",             # path/target order reversed vs get_impact_context; use get_impact_context
+    "cold_start",         # duplicate of get_cold_start_context
+    "cache_freshness",    # duplicate of check_freshness
+    "modernize",          # duplicate of modernize_context
+    # Raw CLI tools with output-format/noise params — clean alias with only repo_path exists
+    "endpoints",          # 7 CLI params (output_path/format/copy/etc.); use get_endpoints
+    "cache_status",       # path + json_output flag; curated alias strips json_output, renames path→repo_path
+    "cache_warm",         # path + compact/agent output flags; curated alias keeps only repo_path
+    "cache_clear",        # path + yes/all_ destructive flags; curated alias keeps repo_path + include_ris only
+    # Curated overrides — canonical CLI spec replaced by cleaner alias with same name.
+    # Listed here so validate_registry() skips CLI param-drift checks on the alias.
+    "spring_audit",       # curated: repo_path + scope + min_severity only (strips output_path/format/copy)
+    "impact_chain",       # curated: repo_path + symbol + depth + query_type with choices
+    # MCP self-management (an agent is not the MCP client admin)
+    "mcp_init",
+    "mcp_serve",
+    "mcp_status",
+    "mcp_remove",
+    "mcp_list_tools",
+    # Telemetry sub-commands (consolidated into telemetry(action=))
+    "telemetry_status",
+    "telemetry_enable",
+    "telemetry_disable",
+})
+
+
+def _java_spring_aliases() -> list[ToolSpec]:
+    """Curated MCP overrides for Java/Spring tools.
+
+    These replace the auto-generated canonical specs with cleaner param surfaces:
+    - repo_path (not raw `path`) for consistency with all other MCP tools
+    - MCP-irrelevant CLI flags (output_path, format, copy) stripped
+    - query_type choices documented so agents discover event topology
+    - Rich docstrings instead of contract-format stubs
+    """
+    validate_repo_path = _repo_path_validator()
+
+    _SPRING_AUDIT_DOC = """\
+Spring semantic audit: TX anomalies + security surface. JAVA/SPRING ONLY.
+
+Do NOT call on non-Java repositories — returns spring_detected=false with no findings.
+
+Patterns detected:
+  TX-001: @Transactional missing rollbackFor for checked exceptions
+  TX-002: propagation=NEVER/NOT_SUPPORTED inside @Transactional scope
+  TX-003: readOnly=true method calling write operations
+  TX-004: REQUIRES_NEW nested inside REQUIRED (TX isolation breach risk)
+  TX-005: @Async method called within @Transactional context (TX context lost)
+  SEC-001: public endpoint with no security annotation (none_detected policy)
+  SEC-002: security annotation on non-endpoint method (misplaced)
+  SEC-003: missing auth on admin-pattern operations
+
+Returns: schema_version, spring_detected, scope, summary, findings[], limitations, metadata.
+findings fields: id, pattern_id, category, severity, confidence, title, symbol,
+  source_file, evidence, explanation, fix_hint.
+
+repo_path: absolute path to the Java repository (default: current working directory).
+scope: "all" (default) | "tx" (TX-001..005 only) | "security" (SEC-001..003 only)
+min_severity: "low" (default) | "medium" | "high" | "critical"
+"""
+
+    _IMPACT_CHAIN_DOC = """\
+Spring impact-chain: blast radius of a symbol with TX/SEC semantic enrichment. JAVA/SPRING ONLY.
+
+Do NOT call on non-Java repositories — returns resolution=not_found.
+
+Two query modes via query_type:
+  "impact" (default) — BFS call graph: direct_callers, indirect_callers, endpoints_affected,
+    transaction_boundary, security_surfaces, impact_findings (TX/SEC patterns in call chain).
+  "events" — event topology: publishers, consumers, propagation graph for an event class
+    or event publisher. Use when symbol is an event class (e.g. OrderPlacedEvent).
+
+Returns: schema_version, symbol, resolution, direct_callers, indirect_callers,
+  endpoints_affected, transaction_boundary, security_surfaces, impact_findings,
+  analysis_warnings, risk_level, confidence, metadata.
+
+symbol: FQN, class name, or Class#method.
+  Examples: "OrderService", "com.example.OrderService#placeOrder",
+            "OrderPlacedEvent" (with query_type="events" for event topology)
+repo_path: absolute path to the Java repository (default: current working directory).
+depth: BFS traversal depth 1–8 (default 4).
+query_type: "impact" (default) | "events"
+"""
+
+    spring_audit = _alias_spec(
+        "spring_audit",
+        "Spring semantic audit: TX anomalies + security surface. JAVA/SPRING ONLY.",
+        ("spring-audit",),
+        (
+            ToolParamSpec("repo_path", "argument", str, required=False, default=".", is_path=True,
+                          help="Absolute path to the Java repository."),
+            ToolParamSpec("scope", "option", str, required=False, default="all",
+                          option_names=("--scope",), choices=("all", "tx", "security"),
+                          help="all (default) | tx | security"),
+            ToolParamSpec("min_severity", "option", str, required=False, default="low",
+                          option_names=("--min-severity",), choices=("low", "medium", "high", "critical"),
+                          help="low (default) | medium | high | critical"),
+        ),
+        lambda inputs: [
+            "spring-audit",
+            str(inputs.get("repo_path", ".")),
+            "--scope", str(inputs.get("scope", "all")),
+            "--min-severity", str(inputs.get("min_severity", "low")),
+        ],
+        supported_targets=("repo_path",),
+        unsupported_targets=("file_path",),
+        validator=validate_repo_path,
+        docstring_override=_SPRING_AUDIT_DOC,
+    )
+
+    impact_chain = _alias_spec(
+        "impact_chain",
+        "Spring impact-chain: blast radius + TX/SEC enrichment. JAVA/SPRING ONLY.",
+        ("impact-chain",),
+        (
+            ToolParamSpec("symbol", "argument", str, required=True, default=None,
+                          help="FQN, class name, or Class#method."),
+            ToolParamSpec("repo_path", "argument", str, required=False, default=".", is_path=True,
+                          help="Absolute path to the Java repository."),
+            ToolParamSpec("depth", "option", int, required=False, default=4,
+                          option_names=("--depth",), help="BFS depth 1–8 (default 4)."),
+            ToolParamSpec("query_type", "option", str, required=False, default="impact",
+                          option_names=("--type",), choices=("impact", "events"),
+                          help="impact (default) = call-chain blast radius; events = event topology"),
+        ),
+        lambda inputs: [
+            "impact-chain",
+            str(inputs["symbol"]),
+            str(inputs.get("repo_path", ".")),
+            "--depth", str(inputs.get("depth", 4)),
+            "--type", str(inputs.get("query_type", "impact")),
+        ],
+        supported_targets=("repo_path", "class_name"),
+        unsupported_targets=("file_path",),
+        validator=validate_repo_path,
+        docstring_override=_IMPACT_CHAIN_DOC,
+    )
+
+    return [spring_audit, impact_chain]
+
+
 @lru_cache(maxsize=1)
 def build_tool_specs() -> tuple[ToolSpec, ...]:
     """Build the full MCP registry from the live CLI runtime."""
-    canonical = [
+    canonical_raw = [
         _canonical_spec_for_runtime_command(runtime)
         for runtime in discover_runtime_commands()
         if (runtime.callback is not None or runtime.path == ())
         and (not runtime.hidden or runtime.path == ("analyze",))
     ]
+    # Mark canonical tools that should not be served via MCP (validate_registry still checks them)
+    canonical = [
+        replace(spec, mcp_hidden=True) if spec.name in _MCP_HIDDEN_CANONICAL_TOOLS else spec
+        for spec in canonical_raw
+    ]
 
-    aliases = _root_aliases() + _prepare_context_aliases()
+    aliases = _root_aliases() + _prepare_context_aliases() + _java_spring_aliases()
     internals = _internal_specs()
 
     merged: dict[str, ToolSpec] = {}
@@ -842,6 +1411,11 @@ def validate_registry() -> list[str]:
         spec = registry_by_path.get(path)
         if spec is None:
             continue
+        # Skip docstring/param drift for mcp_hidden tools and intentional curated overrides.
+        # Curated aliases (e.g. spring_audit, impact_chain) replace canonical CLI specs with
+        # cleaner MCP surfaces — their params diverge from the raw CLI by design.
+        if spec.name in _MCP_HIDDEN_CANONICAL_TOOLS or spec.mcp_hidden:
+            continue
         expected_doc = _first_doc_line(runtime.docstring or runtime.help or "")
         if expected_doc and expected_doc not in spec.description:
             issues.append(f"docstring_mismatch:{spec.name}")
@@ -853,9 +1427,15 @@ def validate_registry() -> list[str]:
     return issues
 
 
+@lru_cache(maxsize=1)
+def build_mcp_tool_specs() -> tuple[ToolSpec, ...]:
+    """Tool specs actually served via MCP: public and not mcp_hidden."""
+    return tuple(spec for spec in build_tool_specs() if spec.mcp_visible)
+
+
 def mcp_tool_specs() -> tuple[ToolSpec, ...]:
-    """Public tool specs only."""
-    return build_public_tool_specs()
+    """Tool specs served via MCP (public, not mcp_hidden)."""
+    return build_mcp_tool_specs()
 
 
 def mcp_internal_tool_specs() -> tuple[ToolSpec, ...]:

sourcecode/mcp/server.py

@@ -1179,17 +1179,36 @@ def telemetry(action: str) -> dict:
     return _execute(["telemetry", action])
 
 
+_NATIVE_MCP_TOOLS: frozenset[str] = frozenset({
+    "start_session",
+    "analyze_task",
+    "run_pr_review_flow",
+    "run_bug_investigation_flow",
+    "run_feature_flow",
+})
+
+
 def _finalize_mcp_registry() -> None:
-    """Replace manual tool registration with the runtime-generated registry."""
-    from sourcecode.mcp.registry import build_public_tool_specs, make_tool_callable, validate_registry
+    """Sync the MCP server with the runtime-generated registry.
+
+    Removes every tool except the 5 native orchestration tools (start_session,
+    analyze_task, flow runners) which are registered via @mcp.tool() in this
+    module and have no backing CLI command. All other tools are rebuilt from the
+    runtime-derived registry (build_mcp_tool_specs).
+    """
+    from sourcecode.mcp.registry import build_mcp_tool_specs, make_tool_callable, validate_registry
+
+    mcp_specs = build_mcp_tool_specs()
 
+    # Remove everything except the native orchestration tools
     try:
         for tool in list(mcp._tool_manager.list_tools()):  # type: ignore[attr-defined]
-            mcp.remove_tool(tool.name)
+            if tool.name not in _NATIVE_MCP_TOOLS:
+                mcp.remove_tool(tool.name)
     except Exception:
         pass
 
-    for spec in build_public_tool_specs():
+    for spec in mcp_specs:
         tool_fn = make_tool_callable(spec)
         tool_fn.__doc__ = spec.docstring
         globals()[spec.name] = tool_fn

{sourcecode-1.35.6.dist-info → sourcecode-1.35.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.35.6
+Version: 1.35.8
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm

{sourcecode-1.35.6.dist-info → sourcecode-1.35.8.dist-info}/RECORD

@@ -1,4 +1,4 @@
-sourcecode/__init__.py,sha256=TcLh06FmiHFO9CNvHqSENDrpMzVidT6Co88A6deoVv8,103
+sourcecode/__init__.py,sha256=4pSX2tiJdyiu03u0G_n4-Ww2ajE_E7piY8T-20n_IDM,103
 sourcecode/adaptive_scanner.py,sha256=XffluXKzJUXrMtjEiAOnSNPZnztdIcts17T9ouHeID0,10521
 sourcecode/architecture_analyzer.py,sha256=qh749a7ykPtGmQI1MR9y6j8TtL_jBdVYFx9YRsLqOMw,44121
 sourcecode/architecture_summary.py,sha256=z34_6v7cSwy98cof2UVciGho7SCrZ93tiqMmq5WNzRQ,20405
@@ -76,9 +76,9 @@ sourcecode/detectors/terraform.py,sha256=cxORPR_zVLOJpHlh4e9JnFpkQsn_UnqMMom5yG6
 sourcecode/detectors/tooling.py,sha256=8CKbtxwQoABP-WyBRNmdAmHDOvAH57AR1cF4UKuWEdQ,2074
 sourcecode/mcp/__init__.py,sha256=XU4HfRGbdid8wdUA0x_4f7uKZD1z3mv_XUY_WU_T9Mw,179
 sourcecode/mcp/orchestrator.py,sha256=BMi1D6liJHI3DXiaC8yeBLLP0wXajpCP3-vnRGqrvnw,26850
-sourcecode/mcp/registry.py,sha256=9SdXkwfc89_dkYFNeSbIgO5KDSMoI5sFoIBRX2PLt14,33248
+sourcecode/mcp/registry.py,sha256=r6YBd9OZoQ4nwg2roQkt6dAAO__e8REtPn--WKLUYIY,60206
 sourcecode/mcp/runner.py,sha256=-Dp2qPGRkfNTVen6bKh7WtzQqpcEtsrXoiuajvshlKk,2866
-sourcecode/mcp/server.py,sha256=hNnXB7UcNyYDCqyu47cHsb3vsULaqgFSTQkBj6C-UcA,51611
+sourcecode/mcp/server.py,sha256=lBSQCw3yFe8rZHp2GGVcfua0EJUYZmsIUbvA4GIJv9s,52210
 sourcecode/mcp/onboarding/__init__.py,sha256=sj2PWqEBmMc4zBNkomg89WtL0M6S7A9yb7_wAuSWNP4,66
 sourcecode/mcp/onboarding/applier.py,sha256=B9CneieWTpaDSDIyW3S5nrlRlBpvfqUcgi93-mm_ApQ,2135
 sourcecode/mcp/onboarding/backup.py,sha256=ihqGOR8QTX8HASRSEDyfFyXr5bkXrygPHamv4p9KTmk,1452
@@ -90,8 +90,8 @@ sourcecode/telemetry/consent.py,sha256=wLMvGNJeSSyZoNkQXpoUioY6mMv4Qdvuw7S9jAEWn
 sourcecode/telemetry/events.py,sha256=oEvvulfsv5GIDWG2174gSS6tNB95w38AIYiYeifGKlE,2294
 sourcecode/telemetry/filters.py,sha256=Asa71oRl7q3Wt_FMwuufIZJFzSYdgRNKS8LHCIyFeYE,4805
 sourcecode/telemetry/transport.py,sha256=KJeIPCPWMdmbCP3ySGs2iUlia34U6vWne2dZsUezesw,1560
-sourcecode-1.35.6.dist-info/METADATA,sha256=yC_5VR0K7bAsP10Dli2yOR3RAPA8ylm3slY150Z9O6g,21263
-sourcecode-1.35.6.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-1.35.6.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
-sourcecode-1.35.6.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-1.35.6.dist-info/RECORD,,
+sourcecode-1.35.8.dist-info/METADATA,sha256=LJSPDerXZXrHOmZrrgWCeQJme4iEyM7ePFxC4t3gDh4,21263
+sourcecode-1.35.8.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-1.35.8.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
+sourcecode-1.35.8.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-1.35.8.dist-info/RECORD,,