sourcecode 1.33.1__tar.gz → 1.33.2__tar.gz

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

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

{sourcecode-1.33.1 → sourcecode-1.33.2}/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.2-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.2
 ```
 
 ---

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

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

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

{sourcecode-1.33.1 → sourcecode-1.33.2}/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.2}/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).")
 
 

{sourcecode-1.33.1 → sourcecode-1.33.2}/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,14 +381,19 @@ 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", [])
         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",
             "summary": ris.compact_summary,
             "entrypoints": ris.structural_map.get("entrypoints", []),
             "endpoints": endpoints,