sourcecode 1.33.2__tar.gz → 1.33.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.33.2
+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.2-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.2
+# sourcecode 1.33.3
 ```
 
 ---

{sourcecode-1.33.2 → 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.2-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.2
+# sourcecode 1.33.3
 ```
 
 ---

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "1.33.2"
+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.2 → sourcecode-1.33.3}/src/sourcecode/__init__.py

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

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

@@ -4320,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
@@ -4334,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:
@@ -4342,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.2 → 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.2 → sourcecode-1.33.3}/src/sourcecode/ris.py

@@ -384,6 +384,15 @@ def get_cold_start_context(repo_root: Path) -> dict:
         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,
@@ -394,20 +403,17 @@ def get_cold_start_context(repo_root: Path) -> dict:
             "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.2 → 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),
             }