sourcecode 1.31.11__tar.gz → 1.31.13__tar.gz

{sourcecode-1.31.11 → sourcecode-1.31.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.31.11
+Version: 1.31.13
 Summary: Deterministic codebase context for AI coding agents
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -225,7 +225,7 @@ Description-Content-Type: text/markdown
 
 **Deterministic, behavior-aware codebase context for AI agents and PR review.**
 
-![Version](https://img.shields.io/badge/version-1.31.11-blue)
+![Version](https://img.shields.io/badge/version-1.31.13-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -261,7 +261,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.31.11
+# sourcecode 1.31.13
 ```
 
 ---

{sourcecode-1.31.11 → sourcecode-1.31.13}/README.md

@@ -2,7 +2,7 @@
 
 **Deterministic, behavior-aware codebase context for AI agents and PR review.**
 
-![Version](https://img.shields.io/badge/version-1.31.11-blue)
+![Version](https://img.shields.io/badge/version-1.31.13-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -38,7 +38,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.31.11
+# sourcecode 1.31.13
 ```
 
 ---

{sourcecode-1.31.11 → sourcecode-1.31.13}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "1.31.11"
+version = "1.31.13"
 description = "Deterministic codebase context for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-1.31.11 → sourcecode-1.31.13}/src/sourcecode/__init__.py

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

{sourcecode-1.31.11 → sourcecode-1.31.13}/src/sourcecode/cli.py

@@ -166,7 +166,7 @@ Compressed AI-ready context for Java/Spring enterprise codebases.
 # Known subcommand names — tokens matching these are routed as subcommands,
 # not consumed as a repository path.
 _SUBCOMMANDS: frozenset[str] = frozenset(
-    {"telemetry", "prepare-context", "version", "config", "analyze", "repo-ir", "mcp", "endpoints"}
+    {"telemetry", "prepare-context", "version", "config", "analyze", "repo-ir", "mcp", "endpoints", "impact"}
 )
 
 # Mutable container holding the path extracted by _preprocess_argv().
@@ -671,14 +671,14 @@ def main(
             f"Error: invalid value '{mode}' for --mode. Valid options: {', '.join(_MODE_CHOICES)}",
             err=True,
         )
-        raise typer.Exit(code=1)
+        raise typer.Exit(code=2)  # FIX-P2-7: arg validation → exit 2
     _RANK_CHOICES = ("relevance", "centrality", "git-churn")
     if rank_by not in _RANK_CHOICES:
         typer.echo(
             f"Error: invalid value '{rank_by}' for --rank-by. Valid options: {', '.join(_RANK_CHOICES)}",
             err=True,
         )
-        raise typer.Exit(code=1)
+        raise typer.Exit(code=2)  # FIX-P2-7: arg validation → exit 2
 
     if symbol is not None and not symbol.strip():
         typer.echo("symbol query cannot be empty", err=True)
@@ -690,14 +690,14 @@ def main(
             "Symbol search uses the contract pipeline which does not run in raw mode.",
             err=True,
         )
-        raise typer.Exit(code=1)
+        raise typer.Exit(code=2)  # FIX-P2-7: arg validation → exit 2
 
     if entrypoints_only and mode not in ("contract", "standard"):
         typer.echo(
             f"Error: --entrypoints-only requires --mode contract or standard (got '{mode}').",
             err=True,
         )
-        raise typer.Exit(code=1)
+        raise typer.Exit(code=2)  # FIX-P2-7: arg validation → exit 2
 
     if dependency_depth > 0:
         typer.echo(
@@ -715,33 +715,65 @@ def main(
             err=True,
         )
 
+    # P0-2 FIX: --compact and --full are mutually exclusive.
+    # compact is designed to be a bounded summary; --full removes truncation limits,
+    # which contradicts compact's purpose. Use --agent --full for expanded output.
+    if compact and full:
+        typer.echo(
+            "Error: --compact and --full are mutually exclusive. "
+            "--compact produces a bounded summary; --full removes truncation limits and "
+            "is meant for --agent mode. Use --agent --full for expanded output.",
+            err=True,
+        )
+        raise typer.Exit(code=2)
+
+    # P0-2 FIX: --full without --compact or --agent has no effect in contract/raw mode.
+    # Warn so the user knows the flag is not doing anything.
+    if full and not compact and not agent:
+        typer.echo(
+            "[warning] --full has no effect in contract/raw mode. "
+            "It only expands mybatis.dto_mappers and transactional_boundaries in "
+            "--compact or --agent mode. Add --agent to get expanded output.",
+            err=True,
+        )
+
+    # P0-2 FIX: --changed-only silently implies --compact; inform the user.
+    if changed_only and not compact and not agent:
+        typer.echo(
+            "[info] --changed-only implies --compact (bounding output to changed files).",
+            err=True,
+        )
+
     # Validate format choices
     if format not in FORMAT_CHOICES:
         typer.echo(
             f"Error: invalid value '{format}' for --format. Valid options: {', '.join(FORMAT_CHOICES)}",
             err=True,
         )
-        raise typer.Exit(code=1)
+        raise typer.Exit(code=2)  # FIX-P2-7: arg validation → exit 2
     if graph_detail not in GRAPH_DETAIL_CHOICES:
         typer.echo(
             f"Error: invalid value '{graph_detail}' for --graph-detail. Valid options: {', '.join(GRAPH_DETAIL_CHOICES)}",
             err=True,
         )
-        raise typer.Exit(code=1)
+        raise typer.Exit(code=2)  # FIX-P2-7: arg validation → exit 2
     if docs_depth not in DOCS_DEPTH_CHOICES:
         typer.echo(
             f"Error: invalid value '{docs_depth}' for --docs-depth. Valid options: {', '.join(DOCS_DEPTH_CHOICES)}",
             err=True,
         )
-        raise typer.Exit(code=1)
+        raise typer.Exit(code=2)  # FIX-P2-7: arg validation → exit 2
 
     # Path was extracted from argv by _preprocess_argv() before Click ran.
-    target = Path(_detected_path[0]).resolve()
+    # FIX-P2-8: preserve original user input in error messages (Windows Git Bash
+    # rewrites "/nonexistent" → "C:\Program Files\Git\nonexistent" via Path.resolve()).
+    _raw_path_input = _detected_path[0]
+    target = Path(_raw_path_input).resolve()
     if not target.exists():
-        typer.echo(f"Error: directory '{target}' does not exist.", err=True)
+        typer.echo(f"Error: directory '{_raw_path_input}' does not exist.", err=True)
         raise typer.Exit(code=1)
     if not target.is_dir():
-        typer.echo(f"Error: '{target}' is not a directory.", err=True)
+        typer.echo(f"Error: '{_raw_path_input}' is not a directory.", err=True)
         raise typer.Exit(code=1)
 
     # Normalize mode aliases
@@ -860,13 +892,27 @@ def main(
                 # 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
+                # FIX-P0-1: cache key must include ALL analysis-affecting flags.
+                # Previously missing: exclude, depth, rank_by, symbol, entrypoints_only,
+                # no_redact, graph_detail, docs_depth, max_nodes, graph_edges,
+                # max_importers, emit_graph.
+                # Use effective_depth (not raw depth) so Java auto-adjustment is captured.
+                _excl_key = (
+                    ",".join(sorted(e.strip() for e in exclude.split(",") if e.strip()))
+                    if exclude else ""
+                )
                 _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},"
                     f"arch={architecture},gc={git_context},em={env_map},"
-                    f"cn={code_notes},tree={tree},mode={mode}"
+                    f"cn={code_notes},tree={tree},mode={mode},"
+                    f"ex={_excl_key},depth={effective_depth},"
+                    f"rb={rank_by},sym={symbol},ep={entrypoints_only},"
+                    f"nr={no_redact},gd={graph_detail},dd={docs_depth},"
+                    f"mn={max_nodes},ge={graph_edges},mi={max_importers},"
+                    f"eg={emit_graph}"
                 )
                 _flags_h = _hashlib.md5(_flags_str.encode()).hexdigest()[:8]
                 _cache_key = f"{_git_sha}-{_flags_h}"
@@ -1612,7 +1658,26 @@ def main(
         data = agent_view(sm, full=full)
         if not no_redact:
             data = redact_dict(data)
-        content = json.dumps(data, indent=2, ensure_ascii=False)
+        # P0-1: Apply output budget — safety net for large repos.
+        from sourcecode.output_budget import trim_to_budget as _trim, BUDGET_AGENT
+        data = _trim(data, BUDGET_AGENT, label="agent")
+        # FIX-P0-2: agent mode must honour --format yaml (previously always emitted JSON).
+        if format == "yaml":
+            from io import StringIO
+            from ruamel.yaml import YAML as _YAML
+            _yaml_ag = _YAML()
+            _yaml_ag.default_flow_style = False
+            _yaml_ag.representer.add_representer(
+                type(None),
+                lambda dumper, data_val: dumper.represent_scalar(
+                    "tag:yaml.org,2002:null", "null"
+                ),
+            )
+            _stream_ag = StringIO()
+            _yaml_ag.dump(data, _stream_ag)
+            content = _stream_ag.getvalue()
+        else:
+            content = json.dumps(data, indent=2, ensure_ascii=False)
     elif compact:
         if changed_only and _allowed_changed_files:
             # GAP-5: preserve full entry_points for architecture context even in
@@ -1624,6 +1689,9 @@ def main(
         data = compact_view(sm, no_tree=no_tree, full=full)
         if not no_redact:
             data = redact_dict(data)
+        # P0-1: Apply output budget — safety net for large repos.
+        from sourcecode.output_budget import trim_to_budget as _trim_c, BUDGET_COMPACT
+        data = _trim_c(data, BUDGET_COMPACT, label="compact")
         if format == "yaml":
             from io import StringIO
             from ruamel.yaml import YAML as _YAML
@@ -2158,7 +2226,10 @@ def prepare_context_cmd(
                 _sys.stdout.buffer.write(_err_json.encode("utf-8"))
                 _sys.stdout.buffer.write(b"\n")
                 _sys.stdout.buffer.flush()
-            raise typer.Exit(code=1)
+            # FIX: no_diff (no PR changes) is not an error — exit 0, consistent
+            # with delta's no_changes handling. Only true errors exit non-zero.
+            _review_pr_exit = 0 if output.error_code == "no_diff" else 1
+            raise typer.Exit(code=_review_pr_exit)
         out["review_type"] = "pull_request"
         if output.ci_decision:
             out["ci_decision"] = output.ci_decision
@@ -2240,6 +2311,24 @@ def prepare_context_cmd(
     if llm_prompt:
         out["llm_prompt"] = builder.render_prompt(output)
 
+    # P0-1: Apply output budget per task — safety net for large repos.
+    from sourcecode.output_budget import (
+        trim_to_budget as _pc_trim,
+        BUDGET_FIX_BUG, BUDGET_REVIEW_PR, BUDGET_ONBOARD,
+        BUDGET_EXPLAIN, BUDGET_REFACTOR, BUDGET_DELTA,
+    )
+    _pc_budgets: dict[str, int] = {
+        "fix-bug":         BUDGET_FIX_BUG,
+        "review-pr":       BUDGET_REVIEW_PR,
+        "onboard":         BUDGET_ONBOARD,
+        "explain":         BUDGET_EXPLAIN,
+        "refactor":        BUDGET_REFACTOR,
+        "delta":           BUDGET_DELTA,
+        "generate-tests":  BUDGET_EXPLAIN,
+    }
+    _pc_budget = _pc_budgets.get(task, BUDGET_EXPLAIN)
+    out = _pc_trim(out, _pc_budget, label=task)
+
     if format == "github-comment" and task == "review-pr":
         from sourcecode.pr_comment_renderer import render_github_comment
         _pc_content = render_github_comment(out)
@@ -2457,6 +2546,115 @@ def repo_ir_cmd(
             _sys.stdout.write("\n")
 
 
+# ── impact (blast-radius / change-impact analysis) ────────────────────────────
+
+@app.command("impact")
+def impact_cmd(
+    target: str = typer.Argument(
+        ...,
+        help=(
+            "Class name (simple or FQN) or file path to analyze impact for. "
+            "Examples: UserService, org.example.UserService, UserService.java"
+        ),
+    ),
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository root to analyze (default: current directory)",
+    ),
+    depth: int = typer.Option(
+        4,
+        "--depth",
+        help="BFS depth for indirect caller traversal (default: 4).",
+        min=1,
+        max=8,
+    ),
+    output_path: Optional[Path] = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Write output to a file instead of stdout.",
+    ),
+    include_tests: bool = typer.Option(
+        False,
+        "--include-tests",
+        help="Include test files in analysis (excluded by default).",
+    ),
+) -> None:
+    """Blast-radius analysis: who calls this class and what breaks if it changes?
+
+    \b
+    Builds the repository IR and propagates impact from the target symbol
+    through the reverse dependency graph. Returns:
+      - direct_callers     — classes that directly call or depend on the target
+      - indirect_callers   — transitive callers (BFS, bounded by --depth)
+      - endpoints_affected — HTTP endpoints that transitively depend on the target
+      - transactional_boundaries_touched — @Transactional classes in the call chain
+      - risk_score / risk_level — quantified change risk
+
+    \b
+    Examples:
+      sourcecode impact UserService
+      sourcecode impact org.keycloak.services.DefaultKeycloakSession /path/to/keycloak
+      sourcecode impact UserService --depth 6 --output impact.json
+    """
+    import json as _json
+    import sys as _sys
+
+    from sourcecode.repository_ir import (
+        build_repo_ir, find_java_files, compute_blast_radius,
+    )
+    from sourcecode.output_budget import trim_to_budget as _trim, BUDGET_IMPACT
+
+    root = path.resolve()
+    if not root.is_dir():
+        typer.echo(f"Error: {root} is not a directory", err=True)
+        raise typer.Exit(1)
+
+    file_list = find_java_files(root)
+    if not include_tests:
+        file_list = [f for f in file_list if "/test/" not in f and "/tests/" not in f]
+
+    if not file_list:
+        typer.echo(
+            _json.dumps(
+                {
+                    "target": target,
+                    "resolution": "not_found",
+                    "message": "No Java files found in repository.",
+                    "risk_level": "unknown",
+                },
+                indent=2,
+            )
+        )
+        return
+
+    _prog = Progress()
+    _prog.start(f"building IR ({len(file_list)} files) for impact analysis")
+    try:
+        ir = build_repo_ir(file_list, root)
+    finally:
+        _prog.finish()
+
+    result = compute_blast_radius(ir, target, max_depth=depth)
+    result = _trim(result, BUDGET_IMPACT, label="impact")
+
+    output = _json.dumps(result, indent=2, ensure_ascii=False)
+    if output_path:
+        output_path.write_text(output, encoding="utf-8")
+        typer.echo(f"Impact analysis written to {output_path}", err=True)
+    else:
+        try:
+            _sys.stdout.buffer.write(output.encode("utf-8"))
+            _sys.stdout.buffer.write(b"\n")
+            _sys.stdout.buffer.flush()
+        except AttributeError:
+            _sys.stdout.write(output + "\n")
+
+    # Non-zero exit when target not found
+    if result.get("resolution") == "not_found":
+        raise typer.Exit(code=1)
+
+
 # ── endpoints ─────────────────────────────────────────────────────────────────
 
 # _extract_java_endpoints is imported from sourcecode.repository_ir as the
@@ -2723,6 +2921,9 @@ def mcp_init(
 @mcp_app.command("status")
 def mcp_status() -> None:
     """Show MCP integration status: dependencies, config files, and connectivity."""
+    import subprocess as _sp
+    import sys as _sys
+    from sourcecode import __version__ as _cli_version
     from sourcecode.mcp.onboarding.detector import detect_clients, is_client_running
     from sourcecode.mcp.onboarding import applier
 
@@ -2731,6 +2932,10 @@ def mcp_status() -> None:
     typer.echo("MCP Status")
     typer.echo(sep)
 
+    # FIX-P0-5/P0-6: Show CLI version explicitly so drift is immediately visible.
+    typer.echo(f"CLI version   {_cli_version}   ({_sys.executable})")
+    typer.echo("")
+
     # Stage 1: Dependencies
     try:
         import mcp as _mcp_pkg  # noqa: F401
@@ -2747,27 +2952,88 @@ def mcp_status() -> None:
         typer.echo("  Setup:   sourcecode mcp init")
         raise typer.Exit(code=0)
 
-    # Stage 2: Config files
-    typer.echo("Config files")
+    # Stage 2: Config files — is sourcecode registered in the client's config?
+    # FIX-P0-6: "configured" and "running" are distinct, independent checks.
+    # Also detect external server installs (different Python/executable than CLI).
+    typer.echo("Config (sourcecode registered in client config?)")
     for client in clients:
         if not client.app_installed:
-            typer.echo(f"  {client.name:<20} ✗ not found")
+            typer.echo(f"  {client.name:<20} ✗ app not found at expected path")
             typer.echo(f"    Expected: {client.config_path}")
             typer.echo(f"    Fix:      sourcecode mcp init --target {client.slug}")
             continue
         config = applier.read_config(client.config_path)
         if applier.is_installed(config):
             typer.echo(f"  {client.name:<20} ✓ configured   {client.config_path}")
+            # FIX-P0-5: inspect registered command for external-server drift.
+            _registered = config.get("mcpServers", {}).get("sourcecode", {})
+            _reg_cmd = _registered.get("command", "")
+            _reg_args = _registered.get("args", [])
+            # Built-in form: command=sourcecode args=[mcp, serve] (or just the binary)
+            _is_builtin = (
+                _reg_cmd == "sourcecode"
+                or (not _reg_args and _reg_cmd.endswith("/sourcecode"))
+                or (_reg_args and _reg_args[:2] == ["mcp", "serve"])
+            )
+            if _is_builtin:
+                typer.echo(f"    Server:  built-in (sourcecode mcp serve)  version={_cli_version}")
+            else:
+                # External server — different Python or custom server.py
+                typer.echo(f"    Server:  ⚠ EXTERNAL — {_reg_cmd} {' '.join(_reg_args)}")
+                # Try to get the external server's sourcecode version by finding the
+                # sourcecode binary relative to the registered Python executable,
+                # or falling back to probing the Python for the installed package.
+                _ext_ver: str = "unknown"
+                try:
+                    import os as _os
+                    # Strategy 1: look for sourcecode binary next to registered Python
+                    _reg_bin_dir = _os.path.dirname(_reg_cmd)
+                    _sc_sibling = _os.path.join(_reg_bin_dir, "sourcecode")
+                    if _os.path.isfile(_sc_sibling):
+                        _ver_r = _sp.run(
+                            [_sc_sibling, "--version"],
+                            capture_output=True, text=True, timeout=5,
+                        )
+                        if _ver_r.returncode == 0 and _ver_r.stdout.strip():
+                            # "sourcecode X.Y.Z" → extract version
+                            _ext_ver = _ver_r.stdout.strip().split()[-1]
+                    # Strategy 2: import via registered Python
+                    if _ext_ver == "unknown":
+                        _ver_r2 = _sp.run(
+                            [_reg_cmd, "-c",
+                             "import sourcecode; print(sourcecode.__version__)"],
+                            capture_output=True, text=True, timeout=5,
+                        )
+                        if _ver_r2.returncode == 0 and _ver_r2.stdout.strip():
+                            _ext_ver = _ver_r2.stdout.strip()
+                except Exception:
+                    pass
+                if _ext_ver != "unknown" and _ext_ver != _cli_version:
+                    typer.echo(
+                        f"    ⚠ VERSION DRIFT: external server version={_ext_ver}, "
+                        f"CLI version={_cli_version}"
+                    )
+                    typer.echo(
+                        "    To fix: sourcecode mcp init  (re-register using CLI built-in server)"
+                    )
+                elif _ext_ver != "unknown":
+                    typer.echo(f"    External server version={_ext_ver}  (matches CLI ✓)")
+                else:
+                    typer.echo(
+                        f"    ⚠ Cannot verify external server version (CLI={_cli_version}). "
+                        "Re-run: sourcecode mcp init to switch to built-in server."
+                    )
         else:
-            typer.echo(f"  {client.name:<20} ✗ not configured")
+            typer.echo(f"  {client.name:<20} ✗ not configured  (app found, but sourcecode entry missing)")
             typer.echo(f"    Fix: sourcecode mcp init --target {client.slug}")
     typer.echo("")
 
-    # Stage 3: Connectivity
-    typer.echo("Connectivity")
+    # Stage 3: Process liveness — is the client app currently running?
+    # This is independent from config: a running app may still need restart to pick up config.
+    typer.echo("Runtime (client app process running?)")
     any_installed = any(c.app_installed for c in clients)
     if not any_installed:
-        typer.echo("  (no clients to check)")
+        typer.echo("  (no client apps found — nothing to check)")
     else:
         for client in clients:
             if not client.app_installed:
@@ -2779,6 +3045,8 @@ def mcp_status() -> None:
                 typer.echo(f"    Fix: open {client.name}, then run sourcecode mcp status")
 
     typer.echo(sep)
+    typer.echo("  Note:    'configured' and 'running' are checked independently.")
+    typer.echo("           A running app still needs restart after first-time config.")
     typer.echo("  Setup:   sourcecode mcp init")
     typer.echo("  Remove:  sourcecode mcp remove")
 

{sourcecode-1.31.11 → sourcecode-1.31.13}/src/sourcecode/mcp/server.py

@@ -15,9 +15,15 @@ from typing import Any
 
 from mcp.server.fastmcp import FastMCP
 
+from sourcecode import __version__ as _sourcecode_version
 from sourcecode.mcp.runner import run_command
 
+# FIX-P0-5: MCP server version must match CLI version exactly.
+# FastMCP does not accept version= in __init__; inject it on the underlying
+# low-level Server so the MCP initialize handshake reports the correct version.
 mcp = FastMCP("sourcecode")
+if hasattr(mcp, "_mcp_server"):
+    mcp._mcp_server.version = _sourcecode_version  # type: ignore[attr-defined]
 
 
 def _ok(data: Any) -> dict:
@@ -37,10 +43,14 @@ def _execute(args: list[str]) -> dict:
 
 @mcp.tool()
 def get_compact_context(repo_path: str = ".", git_context: bool = False) -> dict:
-    """High-signal summary of a repository (~1000-3000 tokens).
+    """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]
-    Returns: stacks, entry points, dependency summary, confidence, gaps.
     repo_path: absolute path to the repository (default: current working directory).
     git_context: include git log and branch context in the analysis.
     """
@@ -56,10 +66,14 @@ def get_compact_context(repo_path: str = ".", git_context: bool = False) -> dict
 
 @mcp.tool()
 def get_agent_context(repo_path: str = ".", git_context: bool = False) -> dict:
-    """Agent-optimised analysis: identity, entry points, dependencies, gaps.
+    """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]
-    Returns: structured noise-free JSON for AI agents.
     repo_path: absolute path to the repository (default: current working directory).
     git_context: include git log and branch context in the analysis.
     """
@@ -79,8 +93,14 @@ def get_endpoints(repo_path: str = ".") -> dict:
 
     Maps to: sourcecode endpoints <repo_path>
     Returns: endpoints list with method, path, controller, handler fields;
-             total (int) and undocumented (int) counts.
+             security dict when authorization annotations are present
+             (policy: roles_allowed|permit_all|deny_all|authenticated|...);
+             total (int) and no_security_signal (int) counts.
+             no_security_signal counts endpoints with no recognized auth annotation —
+             repos using framework-level auth (e.g. Keycloak) may show high counts.
     Supports Spring MVC (@GetMapping etc.) and JAX-RS (@GET/@POST etc.).
+    Security annotations detected: @RolesAllowed, @PermitAll, @DenyAll,
+    @Authenticated, @PreAuthorize, @Secured, @SecurityRequirement, @M3FiltroSeguridad.
     repo_path: absolute path to the repository (default: current working directory).
     """
     if not isinstance(repo_path, str):
@@ -121,11 +141,17 @@ def get_delta(repo_path: str = ".", since: str = "HEAD~1") -> dict:
 
 @mcp.tool()
 def get_ir_summary(repo_path: str = ".") -> dict:
-    """Deterministic symbol-level IR summary for Java repositories.
+    """Deterministic symbol-level IR summary for Java repositories. Java only.
 
     Maps to: sourcecode repo-ir <repo_path> --summary-only
-    Returns: analysis summary, impact, and change_set — omits full graph nodes/edges.
-    repo_path: absolute path to the repository (default: current working directory).
+    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).
     """
     if not isinstance(repo_path, str):
         return _err("repo_path must be a string", "INVALID_ARGUMENT")
@@ -223,6 +249,34 @@ def generate_tests_context(repo_path: str = ".", include_all: bool = False) -> d
     return _execute(args)
 
 
+@mcp.tool()
+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>]
+    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).
+    """
+    if not isinstance(repo_path, str):
+        return _err("repo_path must be a string", "INVALID_ARGUMENT")
+    if not isinstance(target, str) or not target.strip():
+        return _err("target must be a non-empty class name or FQN", "INVALID_ARGUMENT")
+    if not isinstance(depth, int) or depth < 1 or depth > 8:
+        return _err("depth must be an integer between 1 and 8", "INVALID_ARGUMENT")
+    args = ["impact", target.strip(), repo_path, "--depth", str(depth)]
+    return _execute(args)
+
+
 _TELEMETRY_ACTIONS = frozenset({"status", "enable", "disable"})
 
 
@@ -248,12 +302,14 @@ def config() -> dict:
 def telemetry(action: str) -> dict:
     """Manage telemetry settings.
 
-    Maps to: sourcecode telemetry <status|enable|disable>
-    action must be one of: status, enable, disable
+    Maps to: sourcecode telemetry <action>
+    action: one of "status" (show current state), "enable" (opt in), "disable" (opt out).
+    Valid values: "status" | "enable" | "disable"
     """
+    # FIX-P2-10: enumerate valid actions in docstring so agents don't guess.
     if action not in _TELEMETRY_ACTIONS:
         return _err(
-            f"action must be one of {sorted(_TELEMETRY_ACTIONS)}",
+            f"Invalid action '{action}'. Must be one of: {', '.join(sorted(_TELEMETRY_ACTIONS))}",
             "INVALID_ARGUMENT",
         )
     return _execute(["telemetry", action])