sourcecode 1.33.1__py3-none-any.whl → 1.33.2__py3-none-any.whl

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/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/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/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,

{sourcecode-1.33.1.dist-info → sourcecode-1.33.2.dist-info}/METADATA

@@ -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.dist-info → sourcecode-1.33.2.dist-info}/RECORD

@@ -1,13 +1,13 @@
-sourcecode/__init__.py,sha256=etbaHEAFq4Y5ytZacDtpQYJt_hteBOpOxKlJl-EIGJY,103
+sourcecode/__init__.py,sha256=tN8Xe7UyyVpCOi0lC9IYgThLHlUY6kso5Yf2r_0OwA0,103
 sourcecode/adaptive_scanner.py,sha256=XffluXKzJUXrMtjEiAOnSNPZnztdIcts17T9ouHeID0,10521
 sourcecode/architecture_analyzer.py,sha256=qh749a7ykPtGmQI1MR9y6j8TtL_jBdVYFx9YRsLqOMw,44121
 sourcecode/architecture_summary.py,sha256=z34_6v7cSwy98cof2UVciGho7SCrZ93tiqMmq5WNzRQ,20405
 sourcecode/ast_extractor.py,sha256=_btmeOJIe3t-NicF94D5ZAesa2YIJ0_QNExGnbHxGFE,50578
-sourcecode/cache.py,sha256=h1BT-9PG_7HK---ZzH0j5u3PN0dz2s6IRAUOjQIPYH4,28055
+sourcecode/cache.py,sha256=wAyPrXN5DqiGivnMpeEuun2xHDKfBer2_oBsh6kj_vc,30447
 sourcecode/cache.tmp_new,sha256=-IvV7CojiZjqeKMln1m-lqI0QVA2uFGWmYir4XRFOUk,27970
 sourcecode/canonical_ir.py,sha256=_HM3AUmKSdna9u4dCoU6rpgSA6HdF8gzOKZykIUCNGY,23277
 sourcecode/classifier.py,sha256=2lYoSH3vOTkXZYPU7Go2WIet1-IuNzTWVhc-ULnXtgw,8024
-sourcecode/cli.py,sha256=aoy3H0QhffBj6CLMGHDMlhtW2TQOwrJfK8LFEsajJFM,173536
+sourcecode/cli.py,sha256=rtQ4Bx4L82G0vuSPz1Iabu1azPwF3vuNiAZVxQSvXrQ,176581
 sourcecode/code_notes_analyzer.py,sha256=EJemNCNc9Dn-1RZYu-aNbK0ELzmsyC4s6FdHi3XyNEI,9392
 sourcecode/confidence_analyzer.py,sha256=_jckZSxksV-OU38vbkxfVNBnWCtlCq8Vwfg23x1uspA,19054
 sourcecode/context_scorer.py,sha256=QpChSpsmaAYz91rXA4Ue5xzQmNz_ZboZN09YOHScq1U,14679
@@ -36,7 +36,7 @@ sourcecode/redactor.py,sha256=SB4hwIvg8h-hvcqKcDWaZvA-aSyn-at-BIRwa0tUv5E,3227
 sourcecode/relevance_scorer.py,sha256=MYF4FFkveAQps9SmTeTlh6ODiBz2F--_hWNeHMLtUHQ,8405
 sourcecode/repo_classifier.py,sha256=FG1vaWKdWXsWdl-S8hjVMiTqcwgaRXkDyvK4rPcOGtQ,22681
 sourcecode/repository_ir.py,sha256=-NjBQUT7zyya4ng8Hq0-ChoiHZkUif9lr-Q878gmj8M,153163
-sourcecode/ris.py,sha256=2pQcNN-5akweoBjjWAk_x3QpJ06wukQInmMlMj7WxwI,14737
+sourcecode/ris.py,sha256=dAzD8suyQyq_gixQbgzFiIzeFBfONJ6A54qd44vOwMc,15595
 sourcecode/runtime_classifier.py,sha256=uTAD6BDCiBLUZEDRfqk718kM4RTT_vAbfkcOI2_Xx58,18432
 sourcecode/scanner.py,sha256=WdOQ78mMzjR1NjmKTlbxdgwinnCTfAhxCVLBEFQiFHU,8899
 sourcecode/schema.py,sha256=aHNXDf8LGyUC8ZDE_VS9kiskC2-Oswhi_WnpdGy6HDw,24897
@@ -80,8 +80,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.33.1.dist-info/METADATA,sha256=NqcQIRQo2sldQvv32_3mF9QUqPAxJR5LO4kgdBaojY0,16440
-sourcecode-1.33.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-1.33.1.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
-sourcecode-1.33.1.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-1.33.1.dist-info/RECORD,,
+sourcecode-1.33.2.dist-info/METADATA,sha256=5ow3o68xzE1c77dH1MfolgnmPKRepCxBGOtZco3luV8,16440
+sourcecode-1.33.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-1.33.2.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
+sourcecode-1.33.2.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-1.33.2.dist-info/RECORD,,