sourcecode 1.31.16__py3-none-any.whl → 1.31.18__py3-none-any.whl

sourcecode/__init__.py

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

sourcecode/cache.py

@@ -0,0 +1,470 @@
+"""
+Snapshot cache manager for sourcecode — v2.
+
+Cache layout
+------------
+    ~/.sourcecode/cache/<repo_id>/
+        snapshot-<git_sha>-<flags_hash>.json.gz   ← versioned envelope
+        cas/
+            <blob_hash16>.gz                       ← content-addressed blobs
+
+Schema
+------
+Every snapshot file is a gzip-compressed JSON *envelope*:
+
+    {
+      "sv":     "2",                       // schema version — bump to invalidate all
+      "key":    "abc1234-aabbccdd",        // cache key (git_sha + flags_hash)
+      "ts":     "2026-05-24T22:00:00Z",   // write timestamp (ISO-8601 UTC)
+      "fmt":    "json",                    // output format: "json" | "yaml"
+      "layers": {"heuristic": "...", ...}, // analyzer fingerprints at write time
+      // ── content (one of two forms) ──────────────────────────────────────
+      "snap":   {...},                     // inline fields (small) — JSON mode
+      "cas":    {"file_paths": "<h16>",…}  // large fields deduped into CAS store
+      // — OR —
+      "raw":    "<content string>"         // YAML or unparseable JSON stored as-is
+    }
+
+Content-addressed store (CAS)
+-----------------------------
+Large top-level JSON fields (> _CAS_THRESHOLD bytes) are extracted into the
+``cas/`` directory as individual gzip-compressed blobs identified by a 16-char
+SHA-256 hash of their uncompressed bytes.  Two snapshots that share an
+identical ``file_paths`` array reference the *same* blob — zero duplication.
+
+Eviction / GC
+-------------
+After each write, ``_gc()`` keeps snapshots from the last
+``SOURCECODE_CACHE_KEEP_COMMITS`` distinct git commits (default 5, override via
+env var).  A CAS sweep runs concurrently: blobs unreferenced by any surviving
+snapshot are deleted.
+
+Backward compatibility
+----------------------
+v1 files (raw gzip'd content, no envelope) are detected by the absence of an
+``sv`` key in the decompressed JSON, and served transparently.  Legacy files
+in ``<repo>/.sourcecode-cache/`` are also checked as a final fallback.
+
+Env vars
+--------
+  SOURCECODE_CACHE_DIR          Override global cache base (default: ~/.sourcecode/cache)
+  SOURCECODE_CACHE_KEEP_COMMITS How many git commits to retain (default: 5; 0 = unlimited)
+"""
+from __future__ import annotations
+
+import gzip
+import hashlib
+import json
+import os
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+
+# ---------------------------------------------------------------------------
+# Version / constants
+# ---------------------------------------------------------------------------
+
+#: Bump this string to invalidate *all* existing cached snapshots.
+SCHEMA_VERSION: str = "2"
+
+#: Fields eligible for CAS deduplication (applied to top-level JSON dict keys).
+_CAS_FIELDS: frozenset[str] = frozenset([
+    "file_paths",
+    "entry_points",
+    "docs",
+    "dependencies",
+    "graph",
+    "semantic_calls",
+    "semantic_symbols",
+    "architecture",
+    "metrics",
+    "git_history",
+    "env_map",
+    "code_notes",
+])
+
+#: Serialised size threshold (bytes) above which a field is moved to CAS.
+_CAS_THRESHOLD: int = 4096
+
+_DEFAULT_KEEP_COMMITS: int = 5
+
+# Matches "snapshot-<hex_commit>-<hex_flags>.json.gz"
+_SNAPSHOT_RE = re.compile(r"^snapshot-([0-9a-f]+)-[0-9a-f]+\.json\.gz$")
+
+
+# ---------------------------------------------------------------------------
+# Public API — location helpers
+# ---------------------------------------------------------------------------
+
+def repo_id(repo_root: Path) -> str:
+    """Stable 16-char hex identifier derived from the canonical repo path."""
+    return hashlib.sha256(str(repo_root.resolve()).encode()).hexdigest()[:16]
+
+
+def cache_dir(repo_root: Path) -> Path:
+    """
+    Return the per-repo cache directory (``~/.sourcecode/cache/<repo_id>/``).
+
+    Override the base via ``SOURCECODE_CACHE_DIR``.
+    """
+    env_base = os.environ.get("SOURCECODE_CACHE_DIR", "")
+    base: Path = Path(env_base) if env_base else Path.home() / ".sourcecode" / "cache"
+    return base / repo_id(repo_root)
+
+
+# ---------------------------------------------------------------------------
+# Public API — read / write
+# ---------------------------------------------------------------------------
+
+def read(repo_root: Path, cache_key: str) -> Optional[str]:
+    """
+    Return the cached snapshot string for *cache_key*, or ``None`` on miss.
+
+    Lookup order:
+    1. ``<cache_dir>/snapshot-<cache_key>.json.gz``  — v2 envelope (new)
+    2. ``<repo_root>/.sourcecode-cache/snapshot-<cache_key>.json``  — legacy
+    """
+    cache_d = cache_dir(repo_root)
+
+    # ── 1. Global location (.json.gz, v2 envelope or v1 raw) ───────────────
+    gz_path = cache_d / f"snapshot-{cache_key}.json.gz"
+    if gz_path.exists():
+        try:
+            result = _parse_envelope(gz_path.read_bytes(), cache_d)
+            if result is not None:
+                return result
+        except Exception:
+            pass
+        _safe_unlink(gz_path)  # corrupted or version mismatch — evict
+        return None
+
+    # ── 2. Legacy location (<repo>/.sourcecode-cache/*.json) ───────────────
+    legacy = repo_root / ".sourcecode-cache" / f"snapshot-{cache_key}.json"
+    if legacy.exists():
+        try:
+            return legacy.read_text(encoding="utf-8")
+        except Exception:
+            return None
+
+    return None
+
+
+def write(
+    repo_root: Path,
+    cache_key: str,
+    content: str,
+    *,
+    fmt: str = "json",
+    layers: Optional[dict[str, str]] = None,
+) -> None:
+    """
+    Persist *content* as a versioned, optionally CAS-deduped snapshot.
+
+    Parameters
+    ----------
+    repo_root : Path
+        Root directory of the analysed repository.
+    cache_key : str
+        ``"{git_sha}-{flags_hash}"`` identifying this analysis.
+    content : str
+        Final rendered output (JSON or YAML string).
+    fmt : str
+        ``"json"`` or ``"yaml"`` — determines whether CAS extraction applies.
+    layers : dict[str, str], optional
+        Analyzer fingerprints (from ``_compute_analyzer_fingerprints()``).
+        Stored in the envelope for future layer-aware reuse.
+
+    Writes are always best-effort: any failure is silently swallowed.
+    """
+    cache_d = cache_dir(repo_root)
+    dest = cache_d / f"snapshot-{cache_key}.json.gz"
+    try:
+        cache_d.mkdir(parents=True, exist_ok=True)
+        payload = _build_envelope(cache_key, content, fmt, layers or {}, cache_d)
+        dest.write_bytes(payload)
+    except Exception:
+        return  # non-fatal
+
+    _gc(cache_d)
+
+
+# ---------------------------------------------------------------------------
+# Envelope (de)serialisation
+# ---------------------------------------------------------------------------
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _build_envelope(
+    cache_key: str,
+    content: str,
+    fmt: str,
+    layers: dict[str, str],
+    cache_d: Path,
+) -> bytes:
+    """Build a versioned envelope and return gzip-compressed bytes."""
+    envelope: dict[str, Any] = {
+        "sv": SCHEMA_VERSION,
+        "key": cache_key,
+        "ts": _now_iso(),
+        "fmt": fmt,
+        "layers": layers,
+    }
+
+    if fmt == "json":
+        # Try to parse and extract large fields into CAS
+        try:
+            snap_dict = json.loads(content)
+            if isinstance(snap_dict, dict):
+                inline, cas_refs = _cas_extract(snap_dict, cache_d)
+                envelope["snap"] = inline
+                if cas_refs:
+                    envelope["cas"] = cas_refs
+            else:
+                # JSON array or primitive — store as-is
+                envelope["raw"] = content
+        except Exception:
+            envelope["raw"] = content
+    else:
+        # YAML or unknown format — store raw string
+        envelope["raw"] = content
+
+    return gzip.compress(
+        json.dumps(envelope, ensure_ascii=False).encode("utf-8"),
+        compresslevel=6,
+    )
+
+
+def _parse_envelope(data: bytes, cache_d: Path) -> Optional[str]:
+    """
+    Decompress *data*, parse envelope, resolve CAS refs, return content string.
+
+    Returns ``None`` on schema version mismatch, CAS miss, or parse failure.
+    v1 files (no envelope wrapper) are detected and served transparently.
+    """
+    try:
+        raw_bytes = gzip.decompress(data)
+    except Exception:
+        return None
+
+    # ── v1 detection ────────────────────────────────────────────────────────
+    # v1 stored the content string directly (gzip'd UTF-8), not an envelope.
+    # Heuristic: if decompressed bytes are not a JSON object with an "sv" key,
+    # treat as v1 and return the raw bytes as the content string.
+    try:
+        envelope = json.loads(raw_bytes.decode("utf-8"))
+    except Exception:
+        # Not JSON at all (e.g. YAML v1) — return as-is
+        try:
+            return raw_bytes.decode("utf-8")
+        except Exception:
+            return None
+
+    if not isinstance(envelope, dict) or envelope.get("sv") != SCHEMA_VERSION:
+        # dict without "sv" → v1 JSON snapshot; non-matching sv → old envelope
+        # Serve v1 transparently; reject mismatched schema versions as a miss.
+        if isinstance(envelope, dict) and "sv" in envelope:
+            return None  # schema version mismatch
+        # No "sv" at all → v1 format, raw content
+        return raw_bytes.decode("utf-8")
+
+    # ── v2 envelope ─────────────────────────────────────────────────────────
+    if "raw" in envelope:
+        return envelope["raw"]
+
+    if "snap" in envelope:
+        inline: dict[str, Any] = envelope["snap"]
+        cas_refs: dict[str, str] = envelope.get("cas", {})
+        if cas_refs:
+            restored = _cas_restore(inline, cas_refs, cache_d)
+            if restored is None:
+                return None  # CAS miss (blob evicted or corrupted)
+        else:
+            restored = dict(inline)
+        # Re-serialise with the same parameters used by the pipeline.
+        # json.loads → json.dumps round-trips correctly: Python 3.7+ preserves
+        # dict insertion order and the pipeline uses indent=2, ensure_ascii=False.
+        return json.dumps(restored, indent=2, ensure_ascii=False)
+
+    return None  # malformed envelope
+
+
+# ---------------------------------------------------------------------------
+# CAS store
+# ---------------------------------------------------------------------------
+
+def _cas_dir(cache_d: Path) -> Path:
+    return cache_d / "cas"
+
+
+def _cas_path(cache_d: Path, blob_hash: str) -> Path:
+    return _cas_dir(cache_d) / f"{blob_hash}.gz"
+
+
+def _cas_store_blob(cache_d: Path, serialised: str) -> str:
+    """
+    Store *serialised* (a JSON string) in the CAS.  Idempotent.
+
+    Returns the 16-char SHA-256 hex hash that identifies the blob.
+    """
+    raw = serialised.encode("utf-8")
+    blob_hash = hashlib.sha256(raw).hexdigest()[:16]
+    path = _cas_path(cache_d, blob_hash)
+    if not path.exists():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(gzip.compress(raw, compresslevel=6))
+    return blob_hash
+
+
+def _cas_load_blob(cache_d: Path, blob_hash: str) -> Optional[str]:
+    """Return the stored JSON string for *blob_hash*, or ``None`` if absent."""
+    path = _cas_path(cache_d, blob_hash)
+    if not path.exists():
+        return None
+    try:
+        return gzip.decompress(path.read_bytes()).decode("utf-8")
+    except Exception:
+        return None
+
+
+def _cas_extract(
+    snap_dict: dict[str, Any],
+    cache_d: Path,
+) -> tuple[dict[str, Any], dict[str, str]]:
+    """
+    Walk *snap_dict* top-level fields.  Fields that:
+      - are in ``_CAS_FIELDS``
+      - serialise to more than ``_CAS_THRESHOLD`` bytes
+
+    … are stored as CAS blobs and replaced with their hash in the returned
+    ``cas_refs`` mapping.  Other fields remain inline.
+    """
+    inline: dict[str, Any] = {}
+    cas_refs: dict[str, str] = {}
+
+    for key, value in snap_dict.items():
+        if key in _CAS_FIELDS and value is not None:
+            serialised = json.dumps(value, ensure_ascii=False)
+            if len(serialised.encode("utf-8")) > _CAS_THRESHOLD:
+                blob_hash = _cas_store_blob(cache_d, serialised)
+                cas_refs[key] = blob_hash
+                continue
+        inline[key] = value
+
+    return inline, cas_refs
+
+
+def _cas_restore(
+    inline: dict[str, Any],
+    cas_refs: dict[str, str],
+    cache_d: Path,
+) -> Optional[dict[str, Any]]:
+    """
+    Reconstruct a full snapshot dict by loading CAS blobs for *cas_refs*.
+
+    Returns ``None`` if any blob is missing (treat as cache miss).
+    """
+    result: dict[str, Any] = dict(inline)
+    for field, blob_hash in cas_refs.items():
+        blob_str = _cas_load_blob(cache_d, blob_hash)
+        if blob_str is None:
+            return None  # blob evicted or corrupted → full miss
+        try:
+            result[field] = json.loads(blob_str)
+        except Exception:
+            return None
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Eviction / GC
+# ---------------------------------------------------------------------------
+
+def _gc(cache_d: Path) -> None:
+    """
+    Evict old snapshots and sweep orphaned CAS blobs.
+
+    Keeps snapshots from the last ``SOURCECODE_CACHE_KEEP_COMMITS`` distinct
+    git commits (determined by mtime of files in each commit group).
+    """
+    keep = int(os.environ.get("SOURCECODE_CACHE_KEEP_COMMITS", _DEFAULT_KEEP_COMMITS))
+
+    try:
+        all_snapshots = list(cache_d.glob("snapshot-*.json.gz"))
+        if not all_snapshots:
+            return
+
+        # Group snapshot files by commit SHA
+        groups: dict[str, list[Path]] = {}
+        for f in all_snapshots:
+            m = _SNAPSHOT_RE.match(f.name)
+            if m:
+                groups.setdefault(m.group(1), []).append(f)
+
+        surviving: list[Path]
+
+        if keep <= 0 or len(groups) <= keep:
+            # No eviction needed — but still sweep CAS
+            surviving = all_snapshots
+        else:
+            def _newest_mtime(commit: str) -> float:
+                return max(p.stat().st_mtime for p in groups[commit])
+
+            sorted_commits = sorted(groups, key=_newest_mtime, reverse=True)
+            surviving = []
+            for i, commit in enumerate(sorted_commits):
+                if i < keep:
+                    surviving.extend(groups[commit])
+                else:
+                    for f in groups[commit]:
+                        _safe_unlink(f)
+
+        _gc_cas(cache_d, surviving)
+
+    except Exception:
+        pass  # GC failure is non-fatal
+
+
+def _gc_cas(cache_d: Path, surviving_snapshots: list[Path]) -> None:
+    """
+    Delete CAS blobs not referenced by any snapshot in *surviving_snapshots*.
+
+    Walks each snapshot's ``cas`` dict to collect live hashes; deletes the rest.
+    """
+    cas_d = _cas_dir(cache_d)
+    if not cas_d.exists():
+        return
+
+    try:
+        # Collect all hashes referenced by surviving snapshots
+        referenced: set[str] = set()
+        for snap_path in surviving_snapshots:
+            try:
+                raw = gzip.decompress(snap_path.read_bytes())
+                env = json.loads(raw.decode("utf-8"))
+                if isinstance(env, dict) and "cas" in env:
+                    referenced.update(env["cas"].values())
+            except Exception:
+                pass  # unreadable snapshot — conservatively keep its blobs unknown
+
+        # Delete blobs not referenced by any surviving snapshot
+        for blob in cas_d.glob("*.gz"):
+            if blob.stem not in referenced:
+                _safe_unlink(blob)
+
+    except Exception:
+        pass  # CAS sweep failure is non-fatal
+
+
+# ---------------------------------------------------------------------------
+# Utilities
+# ---------------------------------------------------------------------------
+
+def _safe_unlink(path: Path) -> None:
+    try:
+        path.unlink(missing_ok=True)
+    except Exception:
+        pass

sourcecode/cli.py

@@ -876,14 +876,16 @@ def main(
         architecture = True  # agents need full architectural signal (M4)
         graph_modules = True  # IC-003: import graph needed for architecture confidence
 
-    # ── GAP-9: Cache check — serve from .sourcecode-cache when git SHA unchanged ──
+    # ── GAP-9: Cache check — serve from global cache when git SHA unchanged ──
+    # Cache is stored in ~/.sourcecode/cache/<repo_id>/ (outside the repo).
+    # Snapshots are gzip-compressed (.json.gz) — ~85 % smaller than plain JSON.
+    # Eviction keeps the last SOURCECODE_CACHE_KEEP_COMMITS commits (default 5).
     import hashlib as _hashlib
     import subprocess as _sub
-    _cache_dir = target / ".sourcecode-cache"
+    from sourcecode import cache as _cache_mod
     _cache_hit_content: Optional[str] = None
     _git_sha = ""
     _cache_key = ""
-    _cache_file: Optional[Path] = None
     if not no_cache:
         try:
             _sha_r = _sub.run(
@@ -921,13 +923,10 @@ def main(
                 )
                 _flags_h = _hashlib.md5(_flags_str.encode()).hexdigest()[:8]
                 _cache_key = f"{_git_sha}-{_flags_h}"
-                _cache_file = _cache_dir / f"snapshot-{_cache_key}.json"
-                if _cache_file.exists():
-                    _cache_hit_content = _cache_file.read_text(encoding="utf-8")
+                _cache_hit_content = _cache_mod.read(target, _cache_key)
         except Exception:
             _git_sha = ""
             _cache_key = ""
-            _cache_file = None
 
     if _cache_hit_content is not None:
         from sourcecode.serializer import write_output
@@ -1762,12 +1761,17 @@ def main(
     write_output(content, output=output)
 
     # GAP-9: Persist to cache for future identical runs (git SHA unchanged)
-    if not no_cache and _cache_key and _cache_file is not None and not _pipeline_error:
-        try:
-            _cache_dir.mkdir(parents=True, exist_ok=True)
-            _cache_file.write_text(content, encoding="utf-8")
-        except Exception:
-            pass
+    # Writes versioned envelope to ~/.sourcecode/cache/<repo_id>/<key>.json.gz.
+    # Large JSON fields are extracted into shared CAS blobs (deduplication).
+    # GC runs inline after each write (keep last N commits + CAS sweep).
+    if not no_cache and _cache_key and not _pipeline_error:
+        _cache_mod.write(
+            target,
+            _cache_key,
+            content,
+            fmt=format,
+            layers=_compute_analyzer_fingerprints(),
+        )
 
     if _pipeline_error:
         raise typer.Exit(code=2)

sourcecode/repository_ir.py

@@ -2691,6 +2691,60 @@ def apply_ir_size_limits(
         "global_score": (ir.get("impact") or {}).get("global_score", 0),
         "ranked_nodes": ranked,
     }
+
+    # ── Trim reverse_graph to match node/edge limits ──────────────────────────
+    # BUG-P0-02: reverse_graph was never bounded by --max-nodes/--max-edges.
+    # A 26K-node repo (Broadleaf) emits ~3MB of reverse_graph even when
+    # --max-nodes 200 --max-edges 500 is requested.
+    full_rg: dict = ir.get("reverse_graph") or {}
+    if full_rg:
+        # Inner caller-list cap: prevents individual entries from dominating budget.
+        # Formula: max(20, max_nodes // 4) when max_nodes given; 50 otherwise.
+        def _cap_rg_lists(entry: dict, cap: int) -> dict:
+            return {k: (v[:cap] if isinstance(v, list) and len(v) > cap else v)
+                    for k, v in entry.items()}
+
+        if kept_fqns is not None:
+            # max_nodes was applied — restrict reverse_graph to kept nodes only.
+            # Cap inner caller lists proportionally: large max_nodes → more callers shown.
+            _inner_cap = max(20, max_nodes // 4) if max_nodes else 50
+            trimmed_rg: dict = {
+                k: _cap_rg_lists(v, _inner_cap)
+                for k, v in full_rg.items()
+                if k in kept_fqns
+            }
+            out["reverse_graph"] = trimmed_rg
+            _rg_trimmed_count = len(full_rg) - len(trimmed_rg)
+            if _rg_trimmed_count:
+                out["reverse_graph_note"] = (
+                    f"reverse_graph trimmed: {len(trimmed_rg)}/{len(full_rg)} entries "
+                    f"kept (matching --max-nodes {max_nodes} kept nodes), "
+                    f"caller lists capped at {_inner_cap}. "
+                    "Use --output for full reverse_graph."
+                )
+        elif max_edges is not None:
+            # Only max_edges given (no max_nodes): cap reverse_graph keys
+            # proportionally.  Target: at most max_edges keys, sorted by in-degree
+            # (most-connected hubs first) so the most useful entries survive.
+            _rg_limit = max(1, min(max_edges, len(full_rg)))
+            _rg_sorted_keys = sorted(
+                full_rg.keys(),
+                key=lambda k: sum(len(v) for v in full_rg[k].values() if isinstance(v, list)),
+                reverse=True,
+            )
+            _inner_cap = 50
+            out["reverse_graph"] = {
+                k: _cap_rg_lists(full_rg[k], _inner_cap)
+                for k in _rg_sorted_keys[:_rg_limit]
+            }
+            if len(full_rg) > _rg_limit:
+                out["reverse_graph_note"] = (
+                    f"reverse_graph trimmed: {_rg_limit}/{len(full_rg)} entries "
+                    f"kept (top by in-degree, bounded by --max-edges {max_edges}), "
+                    f"caller lists capped at {_inner_cap}. "
+                    "Use --output for full reverse_graph."
+                )
+
     return out
 
 
@@ -2849,7 +2903,9 @@ def compute_blast_radius(
     """
     reverse_graph: dict[str, dict[str, list[str]]] = ir.get("reverse_graph") or {}
     route_surface: list[dict] = ir.get("route_surface") or []
-    graph_nodes: list[dict] = (ir.get("graph") or {}).get("nodes") or []
+    _graph: dict = ir.get("graph") or {}
+    graph_nodes: list[dict] = _graph.get("nodes") or []
+    graph_edges: list[dict] = _graph.get("edges") or []
     subsystems: list[dict] = ir.get("subsystems") or []
 
     # ── 1. Resolve target → one or more FQNs ─────────────────────────────────
@@ -2914,6 +2970,76 @@ def compute_blast_radius(
                 if _effective_depth > 1:
                     queue.append((c, 1))
 
+    # ── 2a. Interface bridging: Spring DI / CDI / IoC pattern ────────────────
+    # In DI frameworks (Spring, CDI, Guice), callers inject the INTERFACE, not
+    # the Impl.  e.g. `impact OrderServiceImpl` → 0 direct callers, because every
+    # caller wires against OrderService.
+    #
+    # Root cause: implements edges in graph.edges often carry unresolved short-name
+    # `to` values (e.g. "OrderService" not FQN), so _build_reverse_adjacency drops
+    # them (to_symbol ∉ all_fqns).  The reverse_graph["...OrderService"] therefore
+    # has no "implements" key — we cannot scan it from the reverse side.
+    #
+    # Fix: scan FORWARD graph edges for type=implements FROM our matched classes.
+    # Resolve the `to` value (short or FQN) against reverse_graph keys via suffix
+    # matching.  Gather non-structural callers of those interface keys and merge
+    # them into direct_callers.
+    _iface_bridging: list[dict] = []  # [{interface, caller_count}] for output metadata
+
+    _target_is_interface = any(
+        n.get("symbol_kind") == "interface" or n.get("type") == "interface"
+        for n in graph_nodes
+        if n.get("fqn") in matched_fqns
+    )
+
+    if not _target_is_interface and graph_edges:
+        # Build suffix→FQN lookup for reverse_graph keys (one-time, O(n))
+        _rg_suffix_map: dict[str, list[str]] = {}
+        for _rg_key in reverse_graph:
+            _sfx = _simple_name(_rg_key)
+            _rg_suffix_map.setdefault(_sfx, []).append(_rg_key)
+
+        _BRIDGE_SKIP = frozenset({
+            "implements", "extends", "contained_in", "annotated_with"
+        })
+
+        for _edge in graph_edges:
+            if _edge.get("type") != "implements":
+                continue
+            _from = _edge.get("from") or ""
+            if _from not in matched_fqns:
+                continue
+            # Resolve `to` (may be short name like "OrderService" or full FQN)
+            _to_raw = _edge.get("to") or ""
+            _to_simple = _simple_name(_to_raw)
+            _candidate_iface_keys: list[str] = []
+            if _to_raw in reverse_graph:
+                _candidate_iface_keys = [_to_raw]
+            else:
+                _candidate_iface_keys = _rg_suffix_map.get(_to_simple, [])
+
+            for _iface_fqn in _candidate_iface_keys:
+                _rg_entry = reverse_graph[_iface_fqn]
+                _iface_callers = [
+                    c
+                    for _etype, _clist in _rg_entry.items()
+                    if _etype not in _BRIDGE_SKIP
+                    for c in _clist
+                    if c not in matched_fqns
+                ]
+                if not _iface_callers:
+                    continue
+                _iface_bridging.append({
+                    "interface": _iface_fqn,
+                    "caller_count": len(_iface_callers),
+                })
+                for c in _iface_callers:
+                    if c not in all_affected:
+                        all_affected[c] = 1
+                        direct_callers.append(c)
+                        if _effective_depth > 1:
+                            queue.append((c, 1))
+
     # BFS for indirect callers
     indirect_callers: list[str] = []
     visited: set[str] = set(matched_fqns) | set(direct_callers)
@@ -3142,6 +3268,13 @@ def compute_blast_radius(
     if n_modules > 1:
         _parts.append(f"impact crosses {n_modules} modules")
 
+    if _iface_bridging:
+        _iface_names = [b["interface"].split(".")[-1] for b in _iface_bridging]
+        _parts.append(
+            f"callers resolved via interface{'s' if len(_iface_names) > 1 else ''} "
+            f"({', '.join(_iface_names)}) — Spring/CDI DI pattern"
+        )
+
     if not _parts:
         explanation = f"No callers or dependents found for {target!r}. Low-risk isolated change."
     else:
@@ -3181,6 +3314,13 @@ def compute_blast_radius(
     }
     if _candidates_out:
         out["candidates"] = _candidates_out
+    if _iface_bridging:
+        out["via_interface_resolution"] = _iface_bridging
+        out["via_interface_note"] = (
+            "Target is a concrete class injected via interface(s) in DI frameworks "
+            "(Spring/CDI/Guice). direct_callers includes callers of the implemented "
+            "interface(s) — these are the real production dependents."
+        )
     if len(direct_callers) > 30:
         out["direct_callers_note"] = (
             f"Showing 30/{n_direct} direct callers. Use --output to inspect full IR."

{sourcecode-1.31.16.dist-info → sourcecode-1.31.18.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.31.16
+Version: 1.31.18
 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
 
 **AI-ready change intelligence for Java/Spring enterprise monoliths.**
 
-![Version](https://img.shields.io/badge/version-1.31.16-blue)
+![Version](https://img.shields.io/badge/version-1.31.18-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -263,7 +263,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.31.16
+# sourcecode 1.31.18
 ```
 
 ---
@@ -302,15 +302,24 @@ sourcecode fix-bug /path/to/repo --symptom "NullPointerException in checkout"
 
 Measured against open-source enterprise Java repos:
 
-| Repo | Classes | Cold scan (`--compact`) | Cache hit | Endpoints found |
-|------|---------|------------------------|-----------|----------------|
-| BroadleafCommerce | ~2970 | 2.6s | 0.26s | 130 |
-| Keycloak | ~6363 | 8.4s | 0.27s | 693 |
+| Repo | Java files | Cold scan (`--compact`) | Cache hit | Cache speedup | Endpoints found |
+|------|-----------|------------------------|-----------|---------------|----------------|
+| BroadleafCommerce | 2,985 | 2.9s | 0.20s | ~13x | 130 |
+| Keycloak | 7,885 | 9.0s | 0.27s | ~33x | 693 |
 
-Cache speedup: **30x**. The cache is keyed on file content hashes — invalidated only when source changes.
+The cache is keyed on file content hashes — invalidated only when source changes. Speedup varies by repo size and OS I/O.
 
-**`impact` on a high-fan-in class:**  
-For hub interfaces (2000+ direct dependents), use `--depth 1` — it gives you the direct endpoints in 12s. Default depth=4 can take 90+ seconds on very large repos.
+**Token sizes (measured):**
+
+| Mode | BroadleafCommerce | Keycloak |
+|------|------------------|---------|
+| `--compact` | ~2,900 | ~4,000 |
+| `--agent` | ~4,800 | ~5,500 |
+| `onboard` | ~2,600 | n/a |
+| `fix-bug` (trimmed) | ~27,000 | ~4,600 |
+
+**`impact` on high-fan-in classes:**  
+For hub interfaces (1000+ direct dependents), use `--depth 1` — direct endpoints are already the most actionable signal. Depth=4 on very large repos may take 90+ seconds.
 
 ---
 
@@ -318,7 +327,7 @@ For hub interfaces (2000+ direct dependents), use `--depth 1` — it gives you t
 
 | Flag | Alias | Default | Description |
 |------|-------|---------|-------------|
-| `--compact` | | off | High-signal summary (typically 2000–4000 tokens): stacks, entry points, dependencies, confidence, gaps. Includes `mybatis` and `transactional_boundaries` for Java projects. |
+| `--compact` | | off | High-signal summary (typically 2,500–4,000 tokens for mid-to-large Java repos): stacks, entry points, dependencies, confidence, gaps. Includes `transactional_boundaries` for Spring projects. |
 | `--agent` | | off | Structured JSON for AI agents: project identity, entry points, architecture, dependencies, confidence. More detail than `--compact`. ~4500–5500 tokens. |
 | `--full` | | off | Remove truncation limits on `transactional_boundaries`, `mybatis.dto_mappers`, and other capped lists. |
 | `--git-context` | `-g` | off | Include git activity: recent commits, change hotspots, and uncommitted file count. |
@@ -360,9 +369,10 @@ sourcecode impact OrderService . --depth 2                 # limit BFS depth
 | `candidates` | On partial match: up to 10 FQNs ranked by relevance |
 
 **Best practices:**
-- Target **interfaces**, not implementations: `impact OrderService` > `impact OrderServiceImpl`. Callers depend on the interface contract, not the Impl.
+- Target **interfaces**, not implementations: `impact OrderService` > `impact OrderServiceImpl`. In Spring projects, callers inject the interface via `@Autowired` — the impl has zero direct callers in the graph even though it runs all the code. Querying the impl returns `direct_callers: []` with no error; querying the interface returns the real blast radius.
 - Use `--depth 1` when the target has 200+ callers — direct endpoints are already the most actionable signal.
 - The cache applies to the underlying IR scan — second `impact` run on the same repo is significantly faster.
+- When you get `direct_callers: 0` for a `@Service` or `@Repository` class, that is almost certainly the interface-injection pattern. Re-run with the interface name.
 
 **Supported targets:**
 - Simple class name: `OrderService`
@@ -389,14 +399,16 @@ Extracts all Spring MVC (`@GetMapping`, `@PostMapping`, `@RequestMapping`, etc.)
 ## `repo-ir` — Symbol-level IR
 
 ```bash
-sourcecode repo-ir /path/to/repo
-sourcecode repo-ir /path/to/repo --summary-only          # compact: analysis + impact, no full graph
+sourcecode repo-ir /path/to/repo --summary-only          # recommended: analysis + impact, no full graph (~20K tokens)
 sourcecode repo-ir /path/to/repo --since HEAD~1           # symbol-level diff
-sourcecode repo-ir /path/to/repo --max-nodes 200 --max-edges 500
+sourcecode repo-ir /path/to/repo --files src/.../OrderService.java   # single-file IR
+sourcecode repo-ir /path/to/repo --max-nodes 200 --max-edges 500     # limits forward graph only — see note below
 ```
 
 Builds a deterministic symbol graph: classes, methods, import/injection edges, Spring roles, subsystems. Output is JSON with `graph`, `reverse_graph`, `impact`, `subsystems`, and `route_surface`.
 
+**Size warning:** Without `--summary-only`, output can exceed 1MB for mid-size repos. `--max-nodes`/`--max-edges` limit the forward `graph` section only — the `reverse_graph` section is not bounded by these flags and is the largest component. Always use `--summary-only` unless you need the full graph for downstream tooling.
+
 ---
 
 ## `onboard` — [OSS Core] Codebase orientation
@@ -475,47 +487,103 @@ Note: `sourcecode onboard`, `sourcecode fix-bug`, `sourcecode review-pr`, and `s
 
 ## How to use sourcecode effectively
 
-### With AI agents (Claude, GPT-4, etc.)
+### Onboarding — new repo, new agent session
 
 ```bash
-# Inject bounded context at session start:
-sourcecode /repo --agent | paste-to-agent
+# Bounded context at session start (~2,500–5,500 tokens)
+sourcecode /repo --compact              # fast overview
+sourcecode /repo --agent               # more detail: file relevance, architecture, event flows
+sourcecode onboard /repo               # task-structured: entry points, key files, gaps
+```
 
-# For a change task:
-sourcecode impact PaymentService /repo --depth 1 | ask-agent "What are the risks?"
+Use `--compact` or `--agent` as first-prompt injection for AI coding agents. Both are bounded and deterministic.
 
-# For PR review:
-sourcecode review-pr /repo --since main | ask-agent "Summarize architectural risks"
+### Impact analysis — before touching a class
+
+```bash
+# Always target the INTERFACE in Spring projects:
+sourcecode impact OrderService /repo           # ✓ correct: 30 callers, 11 endpoints
+sourcecode impact OrderServiceImpl /repo       # ✗ wrong: 0 callers (Spring DI blindness)
+
+# Large hub interfaces — depth=1 is faster and still actionable:
+sourcecode impact KeycloakSession /repo --depth 1
+
+# If you get direct_callers:[] for a @Service class, re-query the interface.
 ```
 
-### In CI/CD pipelines
+### Bug triage — symptom-driven
 
 ```bash
-# Always-fresh bounded JSON — deterministic, cacheable by content hash
-sourcecode /repo --compact --no-cache --format json --output context.json
+# Specific symptoms produce the best signal:
+sourcecode fix-bug /repo --symptom "OIDC token refresh fails after realm update"
+sourcecode fix-bug /repo --symptom "NullPointerException in OrderService during checkout"
 
-# PR gate — parse ci_decision field
-sourcecode review-pr /repo --since $BASE_REF --output review.json
-jq '.ci_decision' review.json    # "analysis_success" | "git_ref_error" | etc.
+# Generic symptoms produce noisy output (100s of files) — be specific.
+# Use --output to capture full output without budget truncation.
+sourcecode fix-bug /repo --symptom "payment timeout" --output triage.json
 ```
 
-### For debugging production issues
+### PR review
 
 ```bash
-# Correlate symptom to files
-sourcecode fix-bug /repo --symptom "NullPointerException in PaymentProcessor when cart is empty"
-# → ranked list of files, suspected areas, git commits touching relevant code
+# JSON for programmatic use:
+sourcecode review-pr /repo --since main --output review.json
+jq '.ci_decision' review.json    # "analysis_success" | "git_ref_error"
+
+# Markdown for GitHub comment:
+sourcecode review-pr /repo --since main --format github-comment
+
+# CI/CD gate — parse risk and test coverage fields:
+jq '{ci_decision, test_coverage_risk, impact_summary}' review.json
 ```
 
-### For understanding blast radius
+### Modernization planning
 
 ```bash
-# Interface targets give the most complete signal
-sourcecode impact OrderService /repo --depth 2
-# → shows all endpoints, transaction boundaries, and modules affected
+sourcecode modernize /repo
+# high_coupling_nodes: classes most risky to change (by fan-in degree)
+# dead_zone_candidates: classes with zero callers — safe to remove or refactor
+# Note: hotspot_candidates may be empty in annotation-heavy codebases —
+#       check high_coupling_nodes directly for coupling signal.
+```
 
-# On very large repos or hub classes, depth=1 is faster and still actionable
-sourcecode impact KeycloakSession /repo --depth 1
+### Symbol IR for downstream tooling
+
+```bash
+# Always use --summary-only unless you need the full graph:
+sourcecode repo-ir /repo --summary-only --output ir.json   # ~20K tokens
+sourcecode repo-ir /repo --since HEAD~3 --summary-only     # changed symbols only
+
+# Full graph warning: output can exceed 1MB for mid-size repos.
+# --max-nodes/--max-edges only limit the forward graph, not reverse_graph.
+```
+
+### With AI agents (Claude, GPT-4, etc.)
+
+```bash
+# Start agent session with bounded context:
+sourcecode /repo --agent --output context.json && cat context.json | agent-cli
+
+# For a specific change task, combine context + impact:
+sourcecode /repo --compact > context.json
+sourcecode impact PaymentService /repo --depth 1 >> impact.json
+# Feed both to agent: "Given this context and impact, what are the risks of changing PaymentService?"
+
+# For PR review:
+sourcecode review-pr /repo --since main --format github-comment
+# Paste directly into GitHub PR description or feed to agent
+```
+
+### In CI/CD pipelines
+
+```bash
+# Deterministic, content-hash cached — safe to run on every commit
+sourcecode /repo --compact --no-cache --output context.json
+
+# PR gate
+sourcecode review-pr /repo --since $BASE_REF --output review.json
+DECISION=$(jq -r '.ci_decision' review.json)
+if [ "$DECISION" != "analysis_success" ]; then echo "Review failed: $DECISION"; fi
 ```
 
 ---
@@ -525,8 +593,11 @@ sourcecode impact KeycloakSession /repo --depth 1
 - No runtime analysis — all signals are static (annotation, import graph, file structure)
 - No semantic code understanding — it reads structure, not logic
 - Architecture pattern detection works best for Spring MVC layered apps; SPI/plugin architectures (e.g. Quarkus extension model) are classified as "layered" which may be inaccurate
-- Endpoint recall for JAX-RS subresource locator pattern is ~65% — endpoints mounted dynamically via factory methods are not individually counted
-- `impact` on implementation classes (e.g. `OrderServiceImpl`) reflects callers of the implementation specifically, which is often zero if callers use the interface — prefer targeting the interface
+- Endpoint recall for JAX-RS subresource locator pattern is ~65% — endpoints mounted dynamically via factory methods are not individually counted. JAX-RS sub-resource paths (method-level `@Path` inside a `@Path`-annotated class) are extracted as relative paths, not the fully composed URL.
+- `impact` on implementation classes (e.g. `OrderServiceImpl`) reflects callers of the implementation specifically — **in Spring Boot projects this is almost always zero**, because callers inject the interface via `@Autowired`. Always target the interface (`OrderService`) to get the real blast radius. The tool does not auto-resolve impl → interface. When `direct_callers: []` is returned with `confidence_level: high` for a `@Service` class, treat it as a prompt to re-query the interface.
+- `no_security_signal` on endpoints means no method-level security annotations (`@PreAuthorize`, `@Secured`) were found — it does **not** mean the endpoint is unsecured. Projects using Spring Security filter chains, XML security config, or custom filters will show 100% `no_security_signal` even when fully secured.
+- `hotspot_candidates` in `modernize` output reflects graph coupling, not git churn — in annotation-heavy codebases it is often empty even though real hotspots exist. Check `high_coupling_nodes` directly for the coupling picture.
+- `project_summary` is extracted from the repository README — it may reflect marketing language rather than architectural description
 
 ---
 

{sourcecode-1.31.16.dist-info → sourcecode-1.31.18.dist-info}/RECORD

@@ -1,11 +1,12 @@
-sourcecode/__init__.py,sha256=WRDjwdcctiM18O9La_WTmoTUfMIZt9RXjtQC1kObj58,104
+sourcecode/__init__.py,sha256=RKBkTCXd0nPibD6uZj_CLNSWfxJYQOS-gsplP4C8K_g,104
 sourcecode/adaptive_scanner.py,sha256=XffluXKzJUXrMtjEiAOnSNPZnztdIcts17T9ouHeID0,10521
 sourcecode/architecture_analyzer.py,sha256=4R13Yb02OrPeB4IH3z6V_g7HWhmGcRHbI8CobCVnRrc,39111
 sourcecode/architecture_summary.py,sha256=z34_6v7cSwy98cof2UVciGho7SCrZ93tiqMmq5WNzRQ,20405
 sourcecode/ast_extractor.py,sha256=XgrZg2DcWcUm9r87cRG3KGO7IK2TIL_N-CvhSbUmmh4,49901
+sourcecode/cache.py,sha256=HDkUZqXOovBc1PjTg-JpOQlyKhUMmEhiG789R7L4Wms,16348
 sourcecode/canonical_ir.py,sha256=NZu0XICv__hkQGKzW2LNQLRqb1L28K2p_WQCQKS5Zlk,23141
 sourcecode/classifier.py,sha256=yWeq6agTjkFa3zuNa-gdVIHtjoBoPoVlJnX-b7tdVJs,7851
-sourcecode/cli.py,sha256=2AMxV0HWV8y89JVKWHLCdgLHZVzQ4yjZaK9dm-KGJck,139374
+sourcecode/cli.py,sha256=zBJZqoOntf3m4UWqvixrNdSDdytevuYJF4rDvxXTM8k,139621
 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
@@ -31,7 +32,7 @@ sourcecode/ranking_engine.py,sha256=ZAucq_YX2KkWUuAZf4P0lhtQ_38vEFnUhuGtSZd1S0E,
 sourcecode/redactor.py,sha256=xuGcadGEHaPw4qZXlMDvzMCsr4VOkdp3oBQptHyJk8c,2884
 sourcecode/relevance_scorer.py,sha256=MYF4FFkveAQps9SmTeTlh6ODiBz2F--_hWNeHMLtUHQ,8405
 sourcecode/repo_classifier.py,sha256=FG1vaWKdWXsWdl-S8hjVMiTqcwgaRXkDyvK4rPcOGtQ,22681
-sourcecode/repository_ir.py,sha256=qUuuYAyXvFW_fqfD8AU1X2Z1Odq2lodu8Urj51AOpPk,133501
+sourcecode/repository_ir.py,sha256=NooCrMJYqycKSYTEroVWTYR8X83hHaAYKTsgYxvlz-I,140221
 sourcecode/runtime_classifier.py,sha256=uTAD6BDCiBLUZEDRfqk718kM4RTT_vAbfkcOI2_Xx58,18432
 sourcecode/scanner.py,sha256=WdOQ78mMzjR1NjmKTlbxdgwinnCTfAhxCVLBEFQiFHU,8899
 sourcecode/schema.py,sha256=aHNXDf8LGyUC8ZDE_VS9kiskC2-Oswhi_WnpdGy6HDw,24897
@@ -75,8 +76,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.31.16.dist-info/METADATA,sha256=gumbkAKXOwaszw6emN9Vzqer20NAkWkXVdJOCsSzCWc,26562
-sourcecode-1.31.16.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-1.31.16.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
-sourcecode-1.31.16.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-1.31.16.dist-info/RECORD,,
+sourcecode-1.31.18.dist-info/METADATA,sha256=paObgQ32RFOKlwHD7oyNK6tRtbEBRStsmeXXSg4RaPw,31103
+sourcecode-1.31.18.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-1.31.18.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
+sourcecode-1.31.18.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-1.31.18.dist-info/RECORD,,