sourcecode 1.5.0__py3-none-any.whl → 1.7.0__py3-none-any.whl

sourcecode/__init__.py

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

sourcecode/adaptive_scanner.py

@@ -135,7 +135,8 @@ class AdaptiveScanner:
             if current_depth >= n:
                 # At or inside the source root
                 if rel_parts[:n] == src_parts:
-                    return src_max  # definite source territory — early exit
+                    # base_depth acts as a floor — explicit --depth always wins
+                    return max(src_max, self.base_depth)
             else:
                 # Ancestor check: src_parts starts with rel_parts?
                 if src_parts[:current_depth] == rel_parts:

sourcecode/cli.py

@@ -10,6 +10,7 @@ import typer
 
 from sourcecode import __version__
 from sourcecode.entrypoint_classifier import is_production_entry_point, normalize_entry_point
+from sourcecode.progress import Progress
 
 
 # ---------------------------------------------------------------------------
@@ -138,18 +139,19 @@ def _check_pipeline_coherence(sm: "SourceMap") -> list[str]:  # type: ignore[nam
     return issues
 
 _HELP = """\
-Deterministic codebase context for AI coding agents.
+Compressed AI-ready context for Java/Spring enterprise codebases.
 
-[bold]Usage:[/bold]
-  sourcecode                   [dim]# analyze current directory[/dim]
-  sourcecode /path/to/repo     [dim]# analyze specific path[/dim]
-  sourcecode --agent           [dim]# structured output for AI agents[/dim]
+[bold]Examples:[/bold]
+  sourcecode saint-server --compact
+  sourcecode . --changed-only --git-context
+  sourcecode saint-server --symbol SeguridadRestController
+  sourcecode prepare-context onboard saint-server
+  sourcecode prepare-context delta . --since main
 
 [bold]Subcommands:[/bold]
-  prepare-context TASK [PATH]  [dim]# task-specific context[/dim]
+  prepare-context TASK [PATH]  [dim]# task-specific context (onboard, delta, fix-bug, ...)[/dim]
   telemetry status|enable|disable
   version
-  config
 """
 
 # Known subcommand names — tokens matching these are routed as subcommands,
@@ -382,28 +384,28 @@ def main(
     graph_modules: bool = typer.Option(
         False,
         "--graph-modules",
-        help=(
-            "Include a structural module graph: nodes (files/symbols) and edges (imports, calls, contains). "
-            "Useful for understanding coupling and call flows. Adds module_graph to output. "
-            "Combine with --graph-detail and --graph-edges to control scope."
-        ),
+        hidden=True,
+        help="Include a structural module graph in output.",
     ),
     graph_detail: str = typer.Option(
         "high",
         "--graph-detail",
-        help="Detail level for --graph-modules: high (top modules by importance), medium (filtered by relevance), full (all nodes and edges). Default: high.",
+        hidden=True,
+        help="Detail level for --graph-modules: high, medium, full.",
         show_default=True,
     ),
     max_nodes: Optional[int] = typer.Option(
         None,
         "--max-nodes",
-        help="Maximum number of nodes in --graph-modules output when using high or medium detail. Prevents oversized graphs in large codebases.",
+        hidden=True,
+        help="Maximum nodes in --graph-modules output.",
         min=1,
     ),
     graph_edges: Optional[str] = typer.Option(
         None,
         "--graph-edges",
-        help="Edge types for --graph-modules, comma-separated: imports,calls,contains,extends. Default: all available. Example: --graph-edges imports,calls",
+        hidden=True,
+        help="Edge types for --graph-modules, comma-separated: imports,calls,contains,extends.",
     ),
     no_tree: bool = typer.Option(
         False,
@@ -414,10 +416,8 @@ def main(
     tree: bool = typer.Option(
         False,
         "--tree",
-        help=(
-            "Include the full file_tree and flat file_paths list in output (deep-dive layer). "
-            "Adds significant size — use when the agent needs to browse the full file structure."
-        ),
+        hidden=True,
+        help="Include the full file_tree and flat file_paths list in output.",
     ),
     no_redact: bool = typer.Option(
         False,
@@ -448,41 +448,33 @@ def main(
     docs: bool = typer.Option(
         False,
         "--docs",
-        help="Extract documentation: docstrings, function signatures, and module-level comments. Adds doc_summary and docs to output. Combine with --docs-depth to control coverage.",
+        hidden=True,
+        help="Extract documentation: docstrings, function signatures, and module-level comments.",
     ),
     docs_depth: str = typer.Option(
         "symbols",
         "--docs-depth",
-        help="Documentation extraction depth: module (module-level only), symbols (functions and classes), full (all symbols including private). Default: symbols.",
+        hidden=True,
+        help="Documentation extraction depth: module, symbols, full.",
         show_default=True,
     ),
     full_metrics: bool = typer.Option(
         False,
         "--full-metrics",
-        help=(
-            "Technical audit: lines of code, symbol counts, cyclomatic complexity, and test coverage per file. "
-            "Produces file_metrics and metrics_summary. "
-            "Not included in --agent output — designed for CI pipelines and code review tools, not as primary agent context."
-        ),
+        hidden=True,
+        help="Technical audit: LOC, complexity, test coverage per file.",
     ),
     semantics: bool = typer.Option(
         False,
         "--semantics",
-        help=(
-            "Semantic analysis: cross-file symbol resolution, call graph with confidence levels, and import linking. "
-            "Adds semantic_calls, semantic_symbols, semantic_links, semantic_summary, and hotspots (files ranked by fan-in/fan-out). "
-            "Slower than default analysis — skip for quick scans. "
-            "Confidence degrades on dynamic dispatch, decorators, and generated code."
-        ),
+        hidden=True,
+        help="Cross-file symbol resolution and call graph analysis.",
     ),
     architecture: bool = typer.Option(
         False,
         "--architecture",
-        help=(
-            "Architectural inference: detect functional layers (MVC/layered/hexagonal), bounded contexts, "
-            "and dominant structural patterns. Adds architecture to output. "
-            "Confidence is low when based on directory names alone — combine with --semantics for higher accuracy."
-        ),
+        hidden=True,
+        help="Architectural layer inference (MVC/hexagonal/layered).",
     ),
     git_context: bool = typer.Option(
         False,
@@ -788,7 +780,7 @@ def main(
     # Require at least 8: src(1)+main(2)+java(3)+com(4)+co(5)+app(6)+module(7)+file.
     _java_manifest_names = {"pom.xml", "build.gradle", "build.gradle.kts"}
     _is_java = any(Path(m).name in _java_manifest_names for m in manifests)
-    _java_min_depth = 10
+    _java_min_depth = 12
     effective_depth = max(depth, _java_min_depth) if _is_java and depth < _java_min_depth else depth
 
     # --agent: enable signal analyzers; output via agent_view (not compact)
@@ -1399,11 +1391,30 @@ def main(
                         ))
         sm = _replace(sm, pipeline_trace=_trace.build_trace())
 
-    # P3-B: Auto-switch to centrality ranking when DDD layout detected
-    if (rank_by == "relevance"
-            and sm.architecture is not None
-            and sm.architecture.pattern == "ddd"):
-        rank_by = "centrality"
+    # Pre-compute uncommitted files for --changed-only.
+    # The contract pipeline filter and git_context are two separate subsystems;
+    # wire them here so the pipeline uses git_context data, not an independent git call.
+    _allowed_changed_files: Optional[set[str]] = None
+    if changed_only:
+        from sourcecode.git_analyzer import GitAnalyzer as _GitAnalyzerEarly
+        try:
+            _gc_early = _GitAnalyzerEarly().analyze(target, depth=1, days=1)
+            _bad_gc = {"no_git_repo", "git_not_found", "git_timeout"}
+            if _gc_early and not (_bad_gc & set(_gc_early.limitations)):
+                _uc = _gc_early.uncommitted_changes
+                if _uc:
+                    _allowed_changed_files = (
+                        set(_uc.staged) | set(_uc.unstaged) | set(_uc.untracked)
+                    )
+            if not _allowed_changed_files:
+                typer.echo(
+                    "[changed-only] git unavailable or no uncommitted changes — falling back to full scan.",
+                    err=True,
+                )
+                changed_only = False
+        except Exception:
+            typer.echo("[changed-only] git error — falling back to full scan.", err=True)
+            changed_only = False
 
     # Contract pipeline — runs for mode=contract|standard|deep|hybrid (skip for raw)
     _is_contract_mode = mode in ("contract", "standard")
@@ -1438,6 +1449,7 @@ def main(
                 max_importers=max_importers,
                 semantic_calls=sm.semantic_calls or None,
                 code_notes=sm.code_notes or None,
+                allowed_changed_files=_allowed_changed_files,
                 **_java_pipeline_kwargs,
             )
         except Exception as _exc:
@@ -1712,8 +1724,13 @@ def prepare_context_cmd(
     if llm_prompt:
         out["llm_prompt"] = builder.render_prompt(output)
 
+    import sys as _sys
     _pc_content = json.dumps(out, indent=2, ensure_ascii=False)
-    typer.echo(_pc_content)
+    _pc_bytes = _pc_content.encode("utf-8")
+    _sys.stdout.buffer.write(_pc_bytes)
+    if not _pc_content.endswith("\n"):
+        _sys.stdout.buffer.write(b"\n")
+    _sys.stdout.buffer.flush()
 
     if copy:
         _trimmed = _pc_content.strip()

sourcecode/contract_pipeline.py

@@ -183,6 +183,7 @@ class ContractPipeline:
         code_notes: Optional[list] = None,
         max_contracts: Optional[int] = _MAX_CONTRACTS,
         min_score: Optional[float] = None,
+        allowed_changed_files: Optional[set[str]] = None,
     ) -> tuple[list[FileContract], ContractSummary]:
         """Run the full extraction pipeline.
 
@@ -200,9 +201,14 @@ class ContractPipeline:
         engine = RankingEngine(monorepo_packages)
 
         # 1. Changed files (for --changed-only and ranking)
+        # When allowed_changed_files is provided (from pre-computed git uncommitted_changes),
+        # use it directly. Otherwise fall back to independent git commands.
         changed_files: set[str] = set()
         if changed_only or rank_by == "git-churn":
-            changed_files = _get_changed_files(root)
+            if allowed_changed_files is not None:
+                changed_files = allowed_changed_files
+            else:
+                changed_files = _get_changed_files(root)
 
         # 2. Select files to extract
         # Exclude test files by default — they dominate by count but add noise
@@ -240,10 +246,18 @@ class ContractPipeline:
 
         # Apply max_files cap — bypass when symbol search to ensure defining files are found.
         # A symbol query over a large repo needs all files; result set is small after filtering.
+        # MyBatis Mapper.xml contracts rank below Java files on path score alone (.xml has no
+        # suffix boost). Give them the same priority slot as entry_points so they survive the cap.
+        def _is_priority(p: str) -> bool:
+            if p in entry_paths:
+                return True
+            name = p.rsplit("/", 1)[-1]
+            return name.lower().endswith("mapper.xml")
+
         if symbol is None and len(src_paths) > self.max_files:
             src_paths = sorted(
                 src_paths,
-                key=lambda p: (p in entry_paths, scorer.score(p)),
+                key=lambda p: (_is_priority(p), scorer.score(p)),
                 reverse=True,
             )[:self.max_files]
 
@@ -362,7 +376,9 @@ class ContractPipeline:
 
     def _rank(self, contracts: list[FileContract], rank_by: RankStrategy) -> list[FileContract]:
         if rank_by == "centrality":
-            return sorted(contracts, key=lambda c: (-(c.fan_in + c.fan_out), c.path))
+            # Entrypoints (REST controllers, main classes) surface first even in centrality mode:
+            # they have low fan_in (not imported) but are the primary API surface.
+            return sorted(contracts, key=lambda c: (-c.is_entrypoint, -(c.fan_in + c.fan_out), c.path))
         if rank_by == "git-churn":
             return sorted(contracts, key=lambda c: (-c.is_changed, -c.relevance_score, c.path))
         # Default: relevance — path breaks ties deterministically

sourcecode/detectors/java.py

@@ -225,6 +225,12 @@ class JavaDetector(AbstractDetector):
         all_paths = flatten_file_tree(context.file_tree)
         all_java = [p for p in all_paths if p.endswith(".java")]
 
+        # Augment with a direct scan of standard Java source roots for Controller-named
+        # files that the depth-limited file_tree scanner may have missed.
+        # DDD layouts place REST controllers at depth 10+ (e.g.
+        # src/main/java/com/org/app/ddd/domain/infraestructure/rest/XxxRestController.java).
+        self._augment_deep_java_controllers(context, all_java)
+
         # 1. @SpringBootApplication entry: Application.java / Main.java by name
         app_candidates = [
             p for p in all_java
@@ -270,6 +276,40 @@ class JavaDetector(AbstractDetector):
                 unique_eps.append(ep)
         return unique_eps
 
+    def _augment_deep_java_controllers(self, context: DetectionContext, all_java: list[str]) -> None:
+        """Scan standard Java source roots for *Controller*.java files not in all_java.
+
+        The depth-limited file_tree scanner misses files at depth >= max_depth.
+        DDD layouts place REST controllers deep (e.g. depth 10+), so we supplement
+        with a direct filesystem walk scoped to the standard Maven/Gradle source root.
+        """
+        import os as _os
+        existing = set(all_java)
+        # Standard Java source root candidates (Maven first, then Gradle/other)
+        _SRC_ROOTS = ("src/main/java", "src/main/kotlin", "src/java", "src")
+        for src_root_name in _SRC_ROOTS:
+            src_root = context.root / src_root_name
+            if not src_root.is_dir():
+                continue
+            try:
+                for dirpath, _dirs, filenames in _os.walk(str(src_root)):
+                    for fname in filenames:
+                        if "Controller" not in fname or not fname.endswith(".java"):
+                            continue
+                        full = Path(dirpath) / fname
+                        if full.is_symlink():
+                            continue
+                        try:
+                            rel = str(full.relative_to(context.root)).replace("\\", "/")
+                            if rel not in existing:
+                                all_java.append(rel)
+                                existing.add(rel)
+                        except ValueError:
+                            pass
+            except OSError:
+                pass
+            return  # use only first matching source root
+
     def _scan_java_file_for_entry_points(self, abs_path: Path, rel_path: str) -> list[EntryPoint]:
         try:
             if abs_path.stat().st_size > _MAX_FILE_SIZE:

sourcecode/prepare_context.py

@@ -398,11 +398,27 @@ class TaskContextBuilder:
         from sourcecode.tree_utils import flatten_file_tree
 
         _topology = RepoClassifier().classify(self.root)
-        scanner = AdaptiveScanner(self.root, topology=_topology, base_depth=6)
+        # Shallow pre-scan to detect Java manifests before choosing depth.
+        from sourcecode.scanner import FileScanner as _FileScanner
+        _pre = _FileScanner(self.root, max_depth=1)
+        _pre_manifests = _pre.find_manifests()
+        _java_names = {"pom.xml", "build.gradle", "build.gradle.kts"}
+        _is_java = any(Path(m).name in _java_names for m in _pre_manifests)
+        _base_depth = 12 if _is_java else 6
+        scanner = AdaptiveScanner(self.root, topology=_topology, base_depth=_base_depth)
         file_tree = scanner.scan_tree()
         manifests = scanner.find_manifests()
         all_paths = [p.replace("\\", "/") for p in flatten_file_tree(file_tree)]
 
+        # Warn when Java project has no Mapper.xml — suggests files below scan depth.
+        _mybatis_warning: dict | None = None
+        if _is_java and not any(p.endswith("Mapper.xml") for p in all_paths):
+            _mybatis_warning = {
+                "area": "mybatis",
+                "reason": "Mapper XML files may exist below scan depth. Re-run with --depth 12.",
+                "impact": "high",
+            }
+
         # ── 2. Detect stacks + entry points ───────────────────────────────
         from dataclasses import replace as _replace
         from sourcecode.detectors import ProjectDetector, build_default_detectors
@@ -500,6 +516,7 @@ class TaskContextBuilder:
         code_notes_summary: Optional[dict[str, Any]] = None
         suspected_areas: list[str] = []
         improvement_opportunities: list[str] = []
+        cn_notes_for_ranking: list = []
 
         if spec.enable_code_notes:
             from dataclasses import asdict
@@ -507,6 +524,7 @@ class TaskContextBuilder:
 
             cn_notes, _cn_adrs, cn_summary = CodeNotesAnalyzer().analyze(self.root)
             code_notes_summary = asdict(cn_summary)
+            cn_notes_for_ranking = cn_notes
 
             if task_name == "fix-bug":
                 bug_kinds = {"FIXME", "BUG", "HACK", "XXX"}
@@ -555,6 +573,7 @@ class TaskContextBuilder:
             monorepo_packages=sm.monorepo_packages if sm.monorepo_packages else None,
             git_hotspots=git_hotspots,
             uncommitted_files=uncommitted_files,
+            code_notes=cn_notes_for_ranking if cn_notes_for_ranking else None,
         )
 
         # ── 7. Test gaps (generate-tests only) ────────────────────────────
@@ -594,6 +613,8 @@ class TaskContextBuilder:
         conf_summary, analysis_gaps = ConfidenceAnalyzer().analyze(sm_for_conf)
         confidence = conf_summary.overall
         gaps = [g.reason for g in analysis_gaps]
+        if _mybatis_warning:
+            gaps.append(_mybatis_warning["reason"])
 
         # ── 9. why_these_files ────────────────────────────────────────────────
         why_these_files: dict[str, str] = {
@@ -705,6 +726,7 @@ class TaskContextBuilder:
         monorepo_packages: Optional[list] = None,
         git_hotspots: Optional[dict[str, int]] = None,
         uncommitted_files: Optional[set[str]] = None,
+        code_notes: Optional[list] = None,
     ) -> list[RelevantFile]:
         from sourcecode.ranking_engine import RankingEngine
         from sourcecode.file_classifier import FileClassifier
@@ -719,6 +741,35 @@ class TaskContextBuilder:
         _uncommitted = uncommitted_files or set()
         _max_churn = max(_hotspots.values(), default=1)
 
+        # Pre-compute fix-bug signals (used only when task_name == "fix-bug")
+        _annotated_files: set[str] = set()
+        _dominant_stack = ""
+        _recently_changed_stacks: set[str] = set()
+        if task_name == "fix-bug":
+            _bug_kinds = {"FIXME", "BUG"}
+            for _n in (code_notes or []):
+                if getattr(_n, "kind", "").upper() in _bug_kinds:
+                    _annotated_files.add(getattr(_n, "path", ""))
+
+            def _file_stack(p: str) -> str:
+                ext = Path(p).suffix.lower()
+                if ext == ".java": return "java"
+                if ext in (".ts", ".tsx", ".js", ".jsx", ".mjs"): return "typescript"
+                if ext == ".py": return "python"
+                if ext == ".go": return "go"
+                if ext in (".kt", ".kts"): return "kotlin"
+                if ext == ".rs": return "rust"
+                if ext == ".rb": return "ruby"
+                return "unknown"
+
+            from collections import Counter as _Counter
+            _stk_counts: _Counter[str] = _Counter(
+                _file_stack(f) for f in _uncommitted if _file_stack(f) != "unknown"
+            )
+            if _stk_counts:
+                _dominant_stack = _stk_counts.most_common(1)[0][0]
+                _recently_changed_stacks = set(_stk_counts.keys())
+
         scored: list[tuple[float, str, RelevantFile]] = []
 
         for path in all_paths:
@@ -762,10 +813,28 @@ class TaskContextBuilder:
 
             # Task-specific boosts for differentiated file weighting
             path_lower = path.lower()
+            _fix_bug_why = ""
             if task_name == "fix-bug":
-                if any(x in path_lower for x in ("exception", "error", "handler", "advice")):
-                    content_boost += 1.5
-                    content_reasons.append("exception handler — high risk area")
+                _why_parts: list[str] = []
+                if path in _uncommitted:
+                    content_boost += 0.40
+                    _why_parts.append("uncommitted change (+0.40)")
+                _recency = min(0.30, _hotspots.get(path, 0) * 0.05)
+                if _recency > 0:
+                    content_boost += _recency
+                    _why_parts.append(f"recent commits (+{_recency:.2f})")
+                if path in _annotated_files:
+                    content_boost += 0.20
+                    _why_parts.append("FIXME/BUG annotation (+0.20)")
+                _file_stk = _file_stack(path)
+                if _dominant_stack and _file_stk == _dominant_stack:
+                    content_boost += 0.10
+                    _why_parts.append("dominant changed stack (+0.10)")
+                if _recently_changed_stacks and _file_stk not in _recently_changed_stacks and _file_stk != "unknown":
+                    content_boost -= 0.30
+                    _why_parts.append("different stack from recent changes (-0.30)")
+                if _why_parts:
+                    _fix_bug_why = ", ".join(_why_parts)
             elif task_name == "generate-tests":
                 stem = Path(path).stem.lower()
                 has_test = any(
@@ -797,7 +866,7 @@ class TaskContextBuilder:
             )
             all_reasons = [r for r in fs.reasons if r != "source file"] + content_reasons
             reason_str = ", ".join(all_reasons) if all_reasons else "source file"
-            why_str = _java_why(path, file_class)
+            why_str = _fix_bug_why if _fix_bug_why else _java_why(path, file_class)
 
             scored.append((total, path, RelevantFile(
                 path=path,

sourcecode/progress.py

@@ -0,0 +1,110 @@
+"""Lightweight terminal progress indicator for long-running commands.
+
+Writes only to stderr. Zero-cost when stderr is not a TTY or CI is detected.
+Thread-safe; stop() is idempotent.
+"""
+from __future__ import annotations
+
+import os
+import sys
+import threading
+import time
+from typing import Optional
+
+_FRAMES = ("⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏")
+
+
+def _terminal_capable() -> bool:
+    if not sys.stderr.isatty():
+        return False
+    if os.environ.get("TERM") in ("dumb", ""):
+        return False
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("CI"):
+        return False
+    return True
+
+
+class Progress:
+    """In-place spinner on stderr.
+
+    Usage::
+
+        p = Progress()
+        p.start("scanning files")
+        ...
+        p.update("extracting contracts")
+        ...
+        p.finish()          # clears line, prints "✓ done (3.2s)"
+
+    Always call stop() or finish() — both are idempotent.
+    """
+
+    def __init__(self) -> None:
+        self._enabled = _terminal_capable()
+        self._phase = ""
+        self._t0 = time.monotonic()
+        self._lock = threading.Lock()
+        self._stop_event = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+        self._stopped = False
+
+    @property
+    def elapsed(self) -> float:
+        return time.monotonic() - self._t0
+
+    def start(self, phase: str = "initializing") -> "Progress":
+        self._t0 = time.monotonic()
+        with self._lock:
+            self._phase = phase
+        self._stopped = False
+        if not self._enabled:
+            return self
+        self._stop_event.clear()
+        self._thread = threading.Thread(target=self._loop, daemon=True)
+        self._thread.start()
+        return self
+
+    def update(self, phase: str) -> None:
+        with self._lock:
+            self._phase = phase
+
+    def stop(self) -> float:
+        """Stop and clear spinner. Returns elapsed seconds. Idempotent."""
+        elapsed = self.elapsed
+        if self._stopped:
+            return elapsed
+        self._stopped = True
+        if not self._enabled:
+            return elapsed
+        self._stop_event.set()
+        if self._thread:
+            self._thread.join(timeout=1.0)
+        sys.stderr.write("\r\033[K")
+        sys.stderr.flush()
+        return elapsed
+
+    def finish(self) -> None:
+        """Stop spinner and print a completion line to stderr."""
+        elapsed = self.stop()
+        if not self._enabled:
+            return
+        t = f"{elapsed:.1f}s" if elapsed < 60 else f"{elapsed / 60:.1f}m"
+        sys.stderr.write(f"✓ done ({t})\n")
+        sys.stderr.flush()
+
+    def _loop(self) -> None:
+        idx = 0
+        while not self._stop_event.wait(timeout=0.08):
+            frame = _FRAMES[idx % len(_FRAMES)]
+            elapsed = time.monotonic() - self._t0
+            with self._lock:
+                phase = self._phase
+            line = f"\r{frame} {phase} ({elapsed:.1f}s)"
+            try:
+                sys.stderr.write(line)
+                sys.stderr.flush()
+            except Exception:
+                break
+            idx += 1

sourcecode/serializer.py

@@ -1110,6 +1110,10 @@ def standard_view(sm: SourceMap, *, include_tree: bool = False) -> dict[str, Any
 
     if sm.semantic_summary is not None and sm.semantic_summary.requested:
         result["semantic_summary"] = asdict(sm.semantic_summary)
+        # Backward compat: also emit hotspots at top level (moved to semantic_summary in v1.5.0).
+        # Consumers reading d["hotspots"] directly still work.
+        if sm.semantic_summary.hotspots:
+            result["hotspots"] = sm.semantic_summary.hotspots[:10]
         # Defensive filter: never emit objects with null required fields.
         # A null entry in these arrays is worse than a shorter array — it causes
         # agents to misinterpret the analysis as valid when it is not.

{sourcecode-1.5.0.dist-info → sourcecode-1.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.5.0
+Version: 1.7.0
 Summary: Deterministic codebase context for AI coding agents
 License:                                  Apache License
                                    Version 2.0, January 2004

{sourcecode-1.5.0.dist-info → sourcecode-1.7.0.dist-info}/RECORD

@@ -1,16 +1,16 @@
-sourcecode/__init__.py,sha256=81eXvIk2uxc6dFJg9ND6pJ-xePSGbA0ZUJgr1h_bZ48,102
-sourcecode/adaptive_scanner.py,sha256=6dh34C2qZXyRbw-8xBhbEwDdXanM6CRFRWayVoYITnA,10190
+sourcecode/__init__.py,sha256=MNhBIzrBdGRgftj8IVZxLq9o3V4ixPrsZuHUqg_wZZw,102
+sourcecode/adaptive_scanner.py,sha256=RTNExwWPXzjgLaRueT7UuxkPj5ZEToWjGbx1j0LSZ9E,10250
 sourcecode/architecture_analyzer.py,sha256=oPmGPf9_p6y8Z7SIGHEu57nVYwxycIovDzBvlHl-l5k,32557
 sourcecode/architecture_summary.py,sha256=J9yoLgh8wXwIRrT6q6JooB6PekivbOEYpJz4BUXdalk,20545
 sourcecode/ast_extractor.py,sha256=XgrZg2DcWcUm9r87cRG3KGO7IK2TIL_N-CvhSbUmmh4,49901
 sourcecode/classifier.py,sha256=GKTMN8qKZX7ponSwDJfN08RrasI4CVpq1_gFBgEopps,7093
-sourcecode/cli.py,sha256=_oYoP4_AAFGw0gg-FBGn_DKh7y49xmwuL6D_Bafl2w4,74497
+sourcecode/cli.py,sha256=LaztdHrrzn4tIrGDmWldYpsPkO1xSU5Wj0ATZBhTyJ8,74423
 sourcecode/code_notes_analyzer.py,sha256=rRd8bFYV0krjlxxQV0wenwE9K7pVpUQSR7KvSvUQKw4,9226
 sourcecode/confidence_analyzer.py,sha256=HcaewB2pZaZ_hfKrZWtr_yPMY2-CxS1zzTUD7c4argc,13188
 sourcecode/context_scorer.py,sha256=QpChSpsmaAYz91rXA4Ue5xzQmNz_ZboZN09YOHScq1U,14679
 sourcecode/context_summarizer.py,sha256=CiQrfBEzun949bWvmLabWoj2HhPn6Lw62ofqnsy0FlQ,6503
 sourcecode/contract_model.py,sha256=nRxJKPMs1VHwFTa8AVXhGmaLjti3Lr2sjHDpWgv1bfE,3917
-sourcecode/contract_pipeline.py,sha256=_mZn0GD7UjjJ7E79DmmYjF0sVkuOLBZEgZHqgXVyTrs,26648
+sourcecode/contract_pipeline.py,sha256=VEOvmj-emKuUT-GUosde9FRYyeH8szNW1WSnisNSs2o,27592
 sourcecode/coverage_parser.py,sha256=q0LeZJaX1bnntLu-ImksdBsMlpsVmk_iUfSaB4eaJGo,19702
 sourcecode/dependency_analyzer.py,sha256=p4ljXhkcGBbFlhaZuPrsjOVjDXaKLTg0Gor2p4qFPP0,56208
 sourcecode/doc_analyzer.py,sha256=a1CIClCNmfYM3ku4bdgwHQpmb6Js4wdJZ1V5EYLo04I,24345
@@ -20,7 +20,8 @@ sourcecode/file_classifier.py,sha256=48ly5Z6exkzBy8lNy1AkdP4-oJqIA1zT3LZfffuTyDo
 sourcecode/git_analyzer.py,sha256=PD3eNWydznQ6KLNpxGzBqizIHoPIKevfwz9Xyf_pDt4,11600
 sourcecode/graph_analyzer.py,sha256=iUK-7pSV-cvGqqD2hENdYmhnm0wcXFEyK-xnu5ul8OU,62515
 sourcecode/metrics_analyzer.py,sha256=m0ENgtqKeBL17kUIK3fmGkgo7UfXBNHxCMj0H_Y5K7c,22750
-sourcecode/prepare_context.py,sha256=LsFDp7HnHdvtwVa46YUD60uMBfwXaVs4suMfBvc8tyI,37357
+sourcecode/prepare_context.py,sha256=8Pk5OMXo6jYfhAFVbpfFsrdqoP0yKQzO9Lk7rj-lmjI,40818
+sourcecode/progress.py,sha256=qn30sWaHOkjTgXsSBmiPkz7Rsbwc5oSlIe6JNEMYp_k,3149
 sourcecode/ranking_engine.py,sha256=virVglafZufioHpZpwktjMvUiL0TZELWQCQnQNV8dFo,9360
 sourcecode/redactor.py,sha256=xuGcadGEHaPw4qZXlMDvzMCsr4VOkdp3oBQptHyJk8c,2884
 sourcecode/relevance_scorer.py,sha256=MYF4FFkveAQps9SmTeTlh6ODiBz2F--_hWNeHMLtUHQ,8405
@@ -29,7 +30,7 @@ sourcecode/runtime_classifier.py,sha256=zWX3r3HCKHc-qtIobErOa8aKMmaoPYREtJKvPcBG
 sourcecode/scanner.py,sha256=aM3h9-DCQ3xKpeHpHYdo2vX6T5P95HA_YwZbkAVNwmo,8288
 sourcecode/schema.py,sha256=rNxpDUgOfvJDzz6DKitL-5_0UAh0YomNwTsSSe8PafY,24066
 sourcecode/semantic_analyzer.py,sha256=12TwXYkYbDcBdu0heX_EmfPM2EkO8a_r5osf0SaeQbs,88956
-sourcecode/serializer.py,sha256=2ztWD4FCebPD0D5tY-kNgLlsATaQsPrSQY6rLQeemRI,69467
+sourcecode/serializer.py,sha256=6dHvWc-iqqCjpu9-FcAXqtpKEO4mO3AZVzWT7Tphajo,69736
 sourcecode/summarizer.py,sha256=ZuzIdm3t8A-d5MuQL0TSNLrd-L0IQIuguIxeNXMNJf8,16070
 sourcecode/tree_utils.py,sha256=Fj9OIuUksBvgibNd3feog0sMDjVypJzPexp5lvMoYWI,1424
 sourcecode/workspace.py,sha256=X_6NmNnitvT3_38V-JDChydo_sR68s249hLFlrQskU0,8271
@@ -42,7 +43,7 @@ sourcecode/detectors/elixir.py,sha256=jCpvt5Yi6jvplc80ovRtWh17q-11ZGo9qX7o8b57TJ
 sourcecode/detectors/go.py,sha256=2r66uRQfeTWsqxr4HDhT6vExZErby0t46QXLHVBRv9w,2782
 sourcecode/detectors/heuristic.py,sha256=bCqqgbHavl4Sse3dqT8mwmo1wAdgeJr7VyXOmfClLKo,3387
 sourcecode/detectors/hybrid.py,sha256=IGFRUVsAZ1ooRlFdznCeJAV6vy1yVDx-VyghvLtddXc,9101
-sourcecode/detectors/java.py,sha256=0NKsy1uls5wvQSK7DJP_fM-v5_uuMEr_an47caelLHE,16612
+sourcecode/detectors/java.py,sha256=XAnVOmq7yXgO_4UGlIFIVgNRtyWZQEVsDDu3sa5mTsk,18669
 sourcecode/detectors/jvm_ext.py,sha256=EgHJ5W8EE-ZTN9V607mVzohyKgZE8Mc2jCi-DF8RAZU,2616
 sourcecode/detectors/nodejs.py,sha256=7fsyAmrGkkguX6U80HUQpIe9MRaYyi_A7zbaRtmFmGc,13097
 sourcecode/detectors/parsers.py,sha256=ugPg8yNUf0Ai1gA7Fnn6wAkYGFjTxRodSP3IeViYJJ4,2290
@@ -60,8 +61,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.5.0.dist-info/METADATA,sha256=kdZtCFuIhrWj6KDM4nZ-tMqWzuwiY2hXt4C8hP6PETc,20411
-sourcecode-1.5.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-1.5.0.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
-sourcecode-1.5.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-1.5.0.dist-info/RECORD,,
+sourcecode-1.7.0.dist-info/METADATA,sha256=Vl1rL1-LLgo7afbfxCc0-l2GLTsAfFZzSrvl53DuzQQ,20411
+sourcecode-1.7.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-1.7.0.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
+sourcecode-1.7.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-1.7.0.dist-info/RECORD,,