sourcecode 1.6.0__tar.gz → 1.7.0__tar.gz

{sourcecode-1.6.0 → sourcecode-1.7.0}/PKG-INFO

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

{sourcecode-1.6.0 → sourcecode-1.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "1.6.0"
+version = "1.7.0"
 description = "Deterministic codebase context for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-1.6.0 → sourcecode-1.7.0}/src/sourcecode/__init__.py

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

{sourcecode-1.6.0 → sourcecode-1.7.0}/src/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-1.6.0 → sourcecode-1.7.0}/src/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,6 +1391,31 @@ def main(
                         ))
         sm = _replace(sm, pipeline_trace=_trace.build_trace())
 
+    # 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")
     _pipeline_error = False
@@ -1432,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:
@@ -1706,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-1.6.0 → sourcecode-1.7.0}/src/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

{sourcecode-1.6.0 → sourcecode-1.7.0}/src/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-1.7.0/src/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