sourcecode 1.33.1__tar.gz → 1.33.3__tar.gz

{sourcecode-1.33.1 → sourcecode-1.33.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.33.1
+Version: 1.33.3
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm
@@ -39,7 +39,7 @@ Description-Content-Type: text/markdown
 
 **Persistent structural context and ultra-fast repeated analysis for AI coding agents.**
 
-![Version](https://img.shields.io/badge/version-1.33.1-blue)
+![Version](https://img.shields.io/badge/version-1.33.3-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -113,7 +113,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.33.1
+# sourcecode 1.33.3
 ```
 
 ---

{sourcecode-1.33.1 → sourcecode-1.33.3}/README.md

@@ -2,7 +2,7 @@
 
 **Persistent structural context and ultra-fast repeated analysis for AI coding agents.**
 
-![Version](https://img.shields.io/badge/version-1.33.1-blue)
+![Version](https://img.shields.io/badge/version-1.33.3-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -76,7 +76,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.33.1
+# sourcecode 1.33.3
 ```
 
 ---

{sourcecode-1.33.1 → sourcecode-1.33.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "1.33.1"
+version = "1.33.3"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-1.33.1 → sourcecode-1.33.3}/src/sourcecode/__init__.py

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

{sourcecode-1.33.1 → sourcecode-1.33.3}/src/sourcecode/cache.py

@@ -57,6 +57,7 @@ import hashlib
 import json
 import os
 import re
+import subprocess
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Optional
@@ -110,6 +111,24 @@ _CORE_RE = re.compile(r"^core-([0-9a-f]+)-[0-9a-f]+\.json\.gz$")
 _VIEW_RE = re.compile(r"^view-([0-9a-f]{16})-[0-9a-f]+\.json\.gz$")
 
 
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _get_git_head(repo_root: Path) -> str:
+    """Return short git HEAD SHA, or '' on any error."""
+    try:
+        r = subprocess.run(
+            ["git", "-C", str(repo_root), "rev-parse", "--short", "HEAD"],
+            capture_output=True, text=True, timeout=2,
+        )
+        if r.returncode == 0:
+            return r.stdout.strip()
+    except Exception:
+        pass
+    return ""
+
+
 # ---------------------------------------------------------------------------
 # Public API — location helpers
 # ---------------------------------------------------------------------------
@@ -138,15 +157,51 @@ def cache_dir(repo_root: Path) -> Path:
 def status(repo_root: Path) -> dict[str, Any]:
     """Return a stats dict describing the current cache state for *repo_root*.
 
-    Keys: ``cache_dir``, ``cores``, ``snapshots``, ``views``, ``cas_blobs``,
-    ``total_size_bytes``, ``total_size_mb``.
+    Keys: ``cache_dir``, ``cores``, ``views``, ``cas_blobs``,
+    ``total_size_bytes``, ``total_size_mb``, ``ris_exists``, ``ris_git_head``,
+    ``ris_last_updated_at``, ``ris_is_stale``, ``current_git_head``.
+
+    Note: ``snapshots`` is a legacy v1 field — always 0 in v2 (kept for
+    backward compatibility; v2 writes ``core-*`` and ``view-*`` files only).
     """
     cache_d = cache_dir(repo_root)
+    current_head = _get_git_head(repo_root)
+
+    # RIS metadata (lazy import to avoid circular dependency)
+    ris_fields: dict[str, Any]
+    try:
+        from sourcecode.ris import load_ris as _load_ris  # noqa: PLC0415
+        _ris = _load_ris(repo_root)
+        if _ris is not None:
+            _ris_stale = bool(current_head and _ris.git_head and current_head != _ris.git_head)
+            ris_fields = {
+                "ris_exists": True,
+                "ris_git_head": _ris.git_head,
+                "ris_last_updated_at": _ris.last_updated_at,
+                "ris_is_stale": _ris_stale,
+            }
+        else:
+            ris_fields = {
+                "ris_exists": False,
+                "ris_git_head": None,
+                "ris_last_updated_at": None,
+                "ris_is_stale": False,
+            }
+    except Exception:
+        ris_fields = {
+            "ris_exists": False,
+            "ris_git_head": None,
+            "ris_last_updated_at": None,
+            "ris_is_stale": False,
+        }
+
     if not cache_d.exists():
         return {
             "cache_dir": str(cache_d),
             "cores": 0, "snapshots": 0, "views": 0, "cas_blobs": 0,
             "total_size_bytes": 0, "total_size_mb": 0.0,
+            "current_git_head": current_head,
+            **ris_fields,
         }
     cores = list(cache_d.glob("core-*.json.gz"))
     snapshots = list(cache_d.glob("snapshot-*.json.gz"))
@@ -162,11 +217,18 @@ def status(repo_root: Path) -> dict[str, Any]:
         "cas_blobs": len(cas_blobs),
         "total_size_bytes": total_bytes,
         "total_size_mb": round(total_bytes / (1024 * 1024), 2),
+        "current_git_head": current_head,
+        **ris_fields,
     }
 
 
-def clear(repo_root: Path) -> int:
-    """Delete all cache files for *repo_root*.  Returns the number of files removed."""
+def clear(repo_root: Path, *, clear_ris: bool = False) -> int:
+    """Delete cache files for *repo_root*.  Returns the number of files removed.
+
+    By default, RIS (``ris.json.gz``) is preserved across clears — it is the
+    persistent structural index used by cold-start bootstrapping.  Pass
+    ``clear_ris=True`` (CLI: ``--include-ris``) to also delete the RIS.
+    """
     cache_d = cache_dir(repo_root)
     if not cache_d.exists():
         return 0
@@ -180,6 +242,11 @@ def clear(repo_root: Path) -> int:
         for f in cas_d.glob("*.gz"):
             _safe_unlink(f)
             removed += 1
+    if clear_ris:
+        ris_file = cache_d / "ris.json.gz"
+        if ris_file.exists():
+            _safe_unlink(ris_file)
+            removed += 1
     return removed
 
 

{sourcecode-1.33.1 → sourcecode-1.33.3}/src/sourcecode/cli.py

@@ -1058,6 +1058,22 @@ def main(
         code_notes = True
         architecture = True
 
+    def _inject_cache_meta(raw: str, meta: dict) -> str:
+        """Inject ``_cache`` provenance block into a JSON dict string.
+
+        Parses *raw* as JSON, adds ``_cache`` key, re-serialises.  Returns *raw*
+        unchanged on any parse failure or non-dict JSON (YAML pass-through, etc.).
+        """
+        try:
+            import json as _jm
+            obj = _jm.loads(raw)
+            if isinstance(obj, dict):
+                obj["_cache"] = meta
+                return _jm.dumps(obj, indent=2, ensure_ascii=False)
+        except Exception:
+            pass
+        return raw
+
     # ── Two-layer cache ────────────────────────────────────────────────────────
     # L1 (core): (repo, commit, analysis_flags) → pre-computed view data dict
     #            key  = core-<git_sha>-<analysis_hash>.json.gz
@@ -1202,6 +1218,23 @@ def main(
 
     if _cache_hit_content is not None:
         from sourcecode.serializer import write_output
+        if format == "json":
+            try:
+                from sourcecode.ris import _has_uncommitted_changes as _huc
+                _uncommitted = _huc(target)
+            except Exception:
+                _uncommitted = False
+            _hit_source = "L2_view" if (_view_key and _core_hash) else "L1_core"
+            _data_scope = "COMPACT" if compact else ("AGENT" if agent else "FULL")
+            _cache_hit_content = _inject_cache_meta(_cache_hit_content, {
+                "cache_source": _hit_source,
+                "git_head_at_generation": _git_sha,
+                "current_git_head": _git_sha,
+                "is_stale": False,
+                "has_uncommitted_changes": _uncommitted,
+                "generated_at": None,
+                "data_scope": _data_scope,
+            })
         write_output(_cache_hit_content, output=output)
         if copy and not output:
             _copy_to_clipboard(_cache_hit_content)
@@ -2082,6 +2115,23 @@ def main(
 
     # 6. Write output (CLI-04)
     _progress.finish()
+    if format == "json":
+        try:
+            from sourcecode.ris import _has_uncommitted_changes as _huc_fresh
+            _uncommitted_fresh = _huc_fresh(target)
+        except Exception:
+            _uncommitted_fresh = False
+        import datetime as _dt
+        _data_scope_fresh = "COMPACT" if compact else ("AGENT" if agent else "FULL")
+        content = _inject_cache_meta(content, {
+            "cache_source": "fresh",
+            "git_head_at_generation": _git_sha,
+            "current_git_head": _git_sha,
+            "is_stale": False,
+            "has_uncommitted_changes": _uncommitted_fresh,
+            "generated_at": _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "data_scope": _data_scope_fresh,
+        })
     write_output(content, output=output)
 
     # Persist to two-layer cache (git SHA unchanged → re-use on next run).
@@ -4231,23 +4281,36 @@ def cache_status_cmd(
     else:
         typer.echo(f"Cache dir:   {stats['cache_dir']}")
         typer.echo(f"Cores:       {stats['cores']}")
-        typer.echo(f"Snapshots:   {stats['snapshots']}")
         typer.echo(f"Views:       {stats['views']}")
         typer.echo(f"CAS blobs:   {stats['cas_blobs']}")
         typer.echo(f"Total size:  {stats['total_size_mb']} MB")
+        # RIS section
+        if stats.get("ris_exists"):
+            _stale_tag = " [STALE]" if stats.get("ris_is_stale") else ""
+            typer.echo(f"RIS:         exists  HEAD={stats.get('ris_git_head', '?')}{_stale_tag}  updated={stats.get('ris_last_updated_at', '?')}")
+        else:
+            typer.echo("RIS:         none  (run analysis to build)")
+        if stats.get("current_git_head"):
+            typer.echo(f"Current HEAD:{stats['current_git_head']}")
 
 
 @cache_app.command("clear")
 def cache_clear_cmd(
     path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
     yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+    include_ris: bool = typer.Option(False, "--include-ris", help="Also delete the RIS snapshot (ris.json.gz). By default, RIS is preserved across clears."),
 ) -> None:
-    """Delete all cached snapshots for a repository."""
+    """Delete cached snapshots for a repository.
+
+    By default, RIS (ris.json.gz) is preserved — it is the persistent structural
+    index used for cold-start bootstrapping.  Use --include-ris to also clear it.
+    """
     from sourcecode import cache as _cm
     target = Path(path).resolve()
     if not yes:
-        typer.confirm(f"Delete all cache files for {target}?", abort=True)
-    removed = _cm.clear(target)
+        _ris_note = " (including RIS)" if include_ris else " (RIS preserved — use --include-ris to also clear it)"
+        typer.confirm(f"Delete all cache files for {target}{_ris_note}?", abort=True)
+    removed = _cm.clear(target, clear_ris=include_ris)
     typer.echo(f"Removed {removed} file(s).")
 
 
@@ -4257,7 +4320,11 @@ def cache_warm_cmd(
     compact: bool = typer.Option(True, "--compact/--no-compact", help="Warm compact view (default: on)."),
     agent: bool = typer.Option(False, "--agent", help="Also warm agent view."),
 ) -> None:
-    """Pre-populate the cache by running a fresh analysis."""
+    """Pre-populate the cache by running a fresh analysis.
+
+    Runs a full analysis to populate L1/L2 caches and rebuild the RIS
+    (Repository Intelligence Snapshot). Useful after a merge/pull in CI.
+    """
     import shutil as _shutil
     import subprocess as _sub
     import sys as _sys
@@ -4271,7 +4338,7 @@ def cache_warm_cmd(
         cmd.append("--agent")
     result = _sub.run(cmd, capture_output=True, text=True)
     if result.returncode == 0:
-        typer.echo("Cache warmed.", err=True)
+        typer.echo("Cache warmed (L1/L2 + RIS rebuilt).", err=True)
     else:
         typer.echo(f"Warm failed (exit {result.returncode}).", err=True)
         if result.stderr:
@@ -4279,6 +4346,88 @@ def cache_warm_cmd(
         raise typer.Exit(code=result.returncode)
 
 
+@cache_app.command("freshness")
+def cache_freshness_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    json_output: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Report RIS freshness relative to the current git HEAD.
+
+    Answers: is the cached snapshot current? How many commits behind is it?
+
+    \b
+    Output fields:
+      fresh              — True when RIS HEAD matches current HEAD and no uncommitted changes
+      current_git_head   — Current repo HEAD (short SHA)
+      ris_git_head       — HEAD stored in RIS when it was last built
+      delta_commits      — Number of commits between ris_git_head and HEAD (0 = in sync)
+      has_uncommitted_changes — Working tree has staged/unstaged changes
+      ris_exists         — False when no RIS has been built yet
+      ris_last_updated_at — ISO-8601 timestamp of last RIS write
+    """
+    import json as _json
+    import subprocess as _sub
+    from sourcecode import cache as _cm
+    from sourcecode.ris import _has_uncommitted_changes as _huc
+    from sourcecode.ris import load_ris as _lris
+
+    target = Path(path).resolve()
+    current_head = _cm._get_git_head(target)
+    ris = _lris(target)
+
+    if ris is None:
+        result: dict = {
+            "fresh": False,
+            "ris_exists": False,
+            "current_git_head": current_head,
+            "ris_git_head": None,
+            "delta_commits": None,
+            "has_uncommitted_changes": _huc(target),
+            "ris_last_updated_at": None,
+        }
+    else:
+        ris_head = ris.git_head
+        head_matches = bool(current_head and ris_head and current_head == ris_head)
+        uncommitted = _huc(target)
+
+        # Count commits between ris_head and current HEAD
+        delta = None
+        if ris_head and current_head and ris_head != current_head:
+            try:
+                _r = _sub.run(
+                    ["git", "-C", str(target), "rev-list", "--count", f"{ris_head}..HEAD"],
+                    capture_output=True, text=True, timeout=5,
+                )
+                if _r.returncode == 0:
+                    delta = int(_r.stdout.strip())
+            except Exception:
+                pass
+        elif head_matches:
+            delta = 0
+
+        result = {
+            "fresh": head_matches and not uncommitted,
+            "ris_exists": True,
+            "current_git_head": current_head,
+            "ris_git_head": ris_head,
+            "delta_commits": delta,
+            "has_uncommitted_changes": uncommitted,
+            "ris_last_updated_at": ris.last_updated_at,
+        }
+
+    if json_output:
+        typer.echo(_json.dumps(result, indent=2, ensure_ascii=False))
+    else:
+        _fresh_tag = "FRESH" if result["fresh"] else "STALE"
+        typer.echo(f"Status:       {_fresh_tag}")
+        typer.echo(f"Current HEAD: {result['current_git_head'] or '(unknown)'}")
+        typer.echo(f"RIS HEAD:     {result.get('ris_git_head') or '(none)'}")
+        if result.get("delta_commits") is not None:
+            typer.echo(f"Delta:        {result['delta_commits']} commit(s) behind")
+        typer.echo(f"Uncommitted:  {result['has_uncommitted_changes']}")
+        typer.echo(f"RIS updated:  {result.get('ris_last_updated_at') or 'never'}")
+
+
 # ── Entry point ───────────────────────────────────────────────────────────────
 
 def main_entry() -> None:

{sourcecode-1.33.1 → sourcecode-1.33.3}/src/sourcecode/mcp/server.py

@@ -215,7 +215,10 @@ def get_agent_context(repo_path: str = ".", git_context: bool = False) -> dict:
 
 @mcp.tool()
 def get_endpoints(repo_path: str = ".") -> dict:
-    """REST API endpoint surface extraction from Java source files.
+    """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;
@@ -230,7 +233,7 @@ def get_endpoints(repo_path: str = ".") -> dict:
     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).
+    repo_path: absolute path to the Java repository (default: current working directory).
     """
     _raw = repo_path
     try:
@@ -275,25 +278,43 @@ def get_module_context(repo_path: str = ".", module: str = "") -> dict:
         )
 
 
+def _auto_since(repo_path: str) -> str:
+    """Detect best merge-base for delta: origin/main > origin/master > HEAD~1."""
+    import subprocess as _sp
+    for base in ("origin/main", "origin/master"):
+        try:
+            r = _sp.run(
+                ["git", "-C", repo_path, "merge-base", "HEAD", base],
+                capture_output=True, text=True, timeout=5,
+            )
+            if r.returncode == 0 and r.stdout.strip():
+                return r.stdout.strip()
+        except Exception:
+            pass
+    return "HEAD~1"
+
+
 @mcp.tool()
-def get_delta(repo_path: str = ".", since: str = "HEAD~1") -> dict:
+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>
     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.
     """
     _raw = repo_path
     try:
         if not isinstance(repo_path, str):
             return _err("repo_path must be a string", "INVALID_ARGUMENT")
-        if not isinstance(since, str) or not since.strip():
-            return _err("since must be a non-empty git ref", "INVALID_ARGUMENT")
         repo_path = _normalize_repo_path(repo_path)
         _path_err = _check_repo_path(repo_path)
         if _path_err is not None:
             return _path_err
-        return _execute(["prepare-context", "delta", repo_path, "--since", since])
+        _since = since.strip() if isinstance(since, str) and since.strip() else _auto_since(repo_path)
+        return _execute(["prepare-context", "delta", repo_path, "--since", _since])
     except Exception as exc:
         return _err(
             f"Internal error: {type(exc).__name__}: {exc} — repo_path recibido: {_raw}",
@@ -301,6 +322,40 @@ def get_delta(repo_path: str = ".", since: str = "HEAD~1") -> dict:
         )
 
 
+@mcp.tool()
+def check_freshness(repo_path: str = ".") -> dict:
+    """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).
+    """
+    _raw = repo_path
+    try:
+        if not isinstance(repo_path, str):
+            return _err("repo_path must be a string", "INVALID_ARGUMENT")
+        repo_path = _normalize_repo_path(repo_path)
+        _path_err = _check_repo_path(repo_path)
+        if _path_err is not None:
+            return _path_err
+        return _execute(["cache", "freshness", repo_path, "--json"])
+    except Exception as exc:
+        return _err(
+            f"Internal error: {type(exc).__name__}: {exc} — repo_path: {_raw}",
+            "INTERNAL_ERROR",
+        )
+
+
 @mcp.tool()
 def get_ir_summary(repo_path: str = ".") -> dict:
     """Deterministic symbol-level IR summary for Java repositories. Java only.

{sourcecode-1.33.1 → sourcecode-1.33.3}/src/sourcecode/ris.py

@@ -349,6 +349,26 @@ def _current_git_head(repo_root: Path) -> str:
     return ""
 
 
+def _has_uncommitted_changes(repo_root: Path) -> bool:
+    """Return True if working tree has staged or unstaged changes.
+
+    Uses ``git status --porcelain`` — any non-empty output means the working
+    tree diverges from HEAD.  Returns False on any error (non-git dirs, etc.).
+    """
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(repo_root), "status", "--porcelain"],
+            capture_output=True,
+            text=True,
+            timeout=2,
+        )
+        if result.returncode == 0:
+            return bool(result.stdout.strip())
+    except Exception:
+        pass
+    return False
+
+
 def get_cold_start_context(repo_root: Path) -> dict:
     """Return a lightweight bootstrap object from the persisted RIS.
 
@@ -361,28 +381,39 @@ def get_cold_start_context(repo_root: Path) -> dict:
 
         current_head = _current_git_head(repo_root)
         stale = bool(current_head and ris.git_head and current_head != ris.git_head)
+        uncommitted = _has_uncommitted_changes(repo_root)
 
         endpoints = ris.api_surface.get("endpoints", [])
+        _is_java = (
+            (repo_root / "pom.xml").exists()
+            or (repo_root / "build.gradle").exists()
+            or (repo_root / "build.gradle.kts").exists()
+        )
+        # api_surface_complete: False when this is a Java repo but endpoints are absent.
+        # An empty list does NOT mean "no endpoints exist" — it means the endpoint
+        # index has not been built yet.  Agents must call get_endpoints to populate.
+        _api_complete = not _is_java or bool(endpoints)
         result: dict = {
             "status": "cold_start_stale" if stale else "cold_start_ready",
             "repo_id": ris.repo_id,
             "git_head": ris.git_head,
+            "current_git_head": current_head,
             "stale": stale,
+            "has_uncommitted_changes": uncommitted,
             "last_updated_at": ris.last_updated_at,
+            "cache_source": "RIS",
+            "data_scope": "RIS_BOOTSTRAP",
+            "api_surface_complete": _api_complete,
             "summary": ris.compact_summary,
             "entrypoints": ris.structural_map.get("entrypoints", []),
             "endpoints": endpoints,
             "hotspots": ris.git_context_snapshot.get("hotspots", []),
         }
-        if not endpoints:
-            _is_java = (repo_root / "pom.xml").exists() or \
-                       (repo_root / "build.gradle").exists() or \
-                       (repo_root / "build.gradle.kts").exists()
-            if _is_java:
-                result["endpoints_hint"] = (
-                    "Java repo detected but no endpoint index found. "
-                    "Call get_endpoints (or: sourcecode endpoints <path>) to populate."
-                )
+        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."
+            )
         return result
     except Exception:
         return {"status": "no_ris"}

{sourcecode-1.33.1 → sourcecode-1.33.3}/src/sourcecode/serializer.py

@@ -631,9 +631,12 @@ def _bootstrap_structured(eps: list) -> "Optional[dict[str, Any]]":
     if security:
         result["security"] = security
     if controllers:
-        # Count unique files (classes) vs total entries (methods/endpoints)
+        # Each controller file generates one EntryPoint regardless of how many
+        # handler methods it contains.  controller_classes == len(controllers)
+        # always (deduplicated by path in _scan_java_file_for_entry_points).
+        # "methods" is therefore removed from the note — use `sourcecode endpoints`
+        # for per-method HTTP surface.
         controller_classes = len({c["path"] for c in controllers})
-        controller_methods = len(controllers)
 
         # Extract all DDD module names from controller paths and group by domain area.
         # Path pattern: .../ddd/{module}/infrastructure/rest/*Controller.java
@@ -655,9 +658,8 @@ def _bootstrap_structured(eps: list) -> "Optional[dict[str, Any]]":
                 module_names.append(module)
 
         _ctrl_note = (
-            f"{controller_methods} detected entry-point methods across "
-            f"{controller_classes} controller classes"
-            f" (use 'sourcecode endpoints' for full surface)"
+            f"{controller_classes} controller classes detected"
+            f" (use 'sourcecode endpoints' for per-method HTTP surface)"
         )
         if len(module_names) > 30:
             # Group by first path segment under ddd/ (inferred domain area)
@@ -678,14 +680,12 @@ def _bootstrap_structured(eps: list) -> "Optional[dict[str, Any]]":
                         domain_groups[domain_prefix or "other"].append(module)
             result["controllers"] = {
                 "classes": controller_classes,
-                "methods": controller_methods,
                 "note": _ctrl_note,
                 "modules": {k: sorted(v) for k, v in sorted(domain_groups.items())},
             }
         else:
             result["controllers"] = {
                 "classes": controller_classes,
-                "methods": controller_methods,
                 "note": _ctrl_note,
                 "modules": sorted(module_names),
             }