sourcecode 1.24.0__tar.gz → 1.26.0__tar.gz

{sourcecode-1.24.0 → sourcecode-1.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.24.0
+Version: 1.26.0
 Summary: Deterministic codebase context for AI coding agents
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -221,7 +221,7 @@ Description-Content-Type: text/markdown
 
 **Compressed AI-ready context for Java/Spring enterprise codebases.**
 
-![Version](https://img.shields.io/badge/version-1.24.0-blue)
+![Version](https://img.shields.io/badge/version-1.26.0-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -255,7 +255,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.24.0
+# sourcecode 1.26.0
 ```
 
 ---
@@ -263,7 +263,7 @@ sourcecode version
 ## Quickstart
 
 ```bash
-# High-signal summary (~600-800 tokens) — recommended starting point
+# High-signal summary (1000–3000 tokens depending on repo size) — recommended starting point
 sourcecode --compact
 
 # Add git hotspots and uncommitted file count
@@ -311,8 +311,9 @@ Example output for a Spring Boot project (`--compact`):
 
 | Flag | Alias | Default | Description |
 |------|-------|---------|-------------|
-| `--compact` | | off | **Recommended.** ~600-800 token summary: stack, entry points, dependencies, risk flags, confidence, gaps. Optimized for agent context windows. |
+| `--compact` | | off | High-signal summary (1000–3000 tokens): stacks, entry points, dependencies, risk flags, confidence, gaps. Includes `security_surface`, `mybatis`, and `transactional_boundaries` for Java projects. |
 | `--agent` | | off | Structured noise-free JSON for AI agents: identity, entry points, dependencies, confidence, gaps. Auto-enables dependency, env-var, and code-notes analysis. |
+| `--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 changes. |
 | `--changed-only` | | off | Limit output to git-modified files (staged, unstaged, untracked). Forces compact output. |
 | `--depth` | | `4` | File tree traversal depth (1–20). Java/Maven projects auto-adjust to 12. |
@@ -342,16 +343,18 @@ sourcecode prepare-context TASK [PATH] [OPTIONS]
 | `refactor` | Structural problems, improvement opportunities, high-annotation files | Code quality review |
 | `generate-tests` | Source files without test pairs, coverage gap analysis | Writing missing tests |
 | `review-pr` | Uncommitted/changed files + architectural impact | Pre-merge review |
-| `delta` | Only files changed in a git range (`--since`), affected entry points | Incremental CI context |
+| `delta` | Changed files with multi-hop impact analysis, structural import graph, system-level impact summary | Incremental CI/review context |
 
 ### Options
 
 | Option | Description |
 |--------|-------------|
 | `--since REF` | Git ref for `delta` task (e.g. `HEAD~3`, `main`, `v1.2.0`). Required for `delta`; ignored for other tasks. |
+| `--symptom TEXT` | *(fix-bug only)* Keyword hint for the bug — boosts matching files and surfaces related code notes. |
 | `--llm-prompt` | Append a ready-to-use LLM prompt to the output. |
 | `--dry-run` | Show what would be analyzed without running it. |
 | `--copy` / `-c` | Copy output to clipboard after a successful run. |
+| `--output` / `-o` | Write output to a file. |
 | `--task-help` | List all tasks with descriptions and exit. |
 
 ### Examples
@@ -360,11 +363,8 @@ sourcecode prepare-context TASK [PATH] [OPTIONS]
 # Explain the current repo
 sourcecode prepare-context explain
 
-# Analyze a specific repo path
-sourcecode prepare-context explain /path/to/repo
-
-# Focus on bug-prone files
-sourcecode prepare-context fix-bug
+# Focus on bug-prone files, with a symptom hint
+sourcecode prepare-context fix-bug --symptom "NullPointerException in OrderService"
 
 # Incremental context: files changed since branch diverged from main
 sourcecode prepare-context delta . --since main
@@ -378,6 +378,51 @@ sourcecode prepare-context --task-help
 
 ---
 
+## `delta` — incremental impact analysis
+
+The `delta` task is the recommended mode for CI pipelines and PR reviews. It goes beyond listing changed files: it builds a structural import graph and propagates impact transitively up to 3 hops.
+
+```bash
+sourcecode prepare-context delta [PATH] --since REF
+```
+
+**Output fields:**
+
+| Field | Description |
+|-------|-------------|
+| `changed_files` | Files modified in the git range |
+| `relevant_files` | Changed files + files pulled in by the import graph (scored by artifact type and hop distance) |
+| `impact_summary` | Human-readable summary: artifact types changed and active risk areas |
+| `affected_modules` | DDD domain modules touched by the change |
+| `risk_areas` | Per-area severity breakdown (`security`, `api`, `persistence`, etc.) |
+| `change_type` | Closed taxonomy: `behavioral_change`, `structural_change`, `configuration_change`, `dependency_change`, `security_change` |
+| `system_impact` | Subsystems affected, behavioral changes, runtime impact notes |
+| `dependency_graph_summary` | Verified structural import edges (hop 1–3) and `propagation_depth`. **Only real imports — no heuristics, no test files.** |
+| `impact_score_per_file` | Per-file numeric impact score (0–1) |
+| `since` | The git ref used |
+| `gaps` | What the analysis could not determine |
+
+**How the import graph works:**
+
+1. Each changed file is classified by artifact type (`controller`, `service`, `repository`, `security`, `spring_config`, etc.).
+2. A BFS traversal walks the import graph **repo-wide** (not restricted to the same module), up to 3 hops deep.
+3. `dependency_graph_summary.edges` only contains verified `import` / `@Autowired` / constructor-injection relationships. Test files and heuristic proximity matches are excluded from edges (they appear in `relevant_files` only if they have real imports of changed files).
+4. Score decays 30% per hop: a directly-changed `SecurityConfig.java` scores 0.90; its direct importer scores 0.63; a transitive importer scores 0.44.
+
+```bash
+# Changed service → controller → facade (3 hops)
+sourcecode prepare-context delta . --since main
+
+# Output includes:
+# dependency_graph_summary.edges:
+#   hop-1: OrderService.java → OrderRepository.java
+#   hop-2: OrderRepository.java → OrderController.java
+#   hop-3: OrderController.java → OrderFacade.java
+# propagation_depth: 3
+```
+
+---
+
 ## Output schema
 
 All outputs include a `confidence_summary` block with `overall`, `stack`, and `entry_points` confidence levels (`high` / `medium` / `low`), plus an `analysis_gaps` list describing what could not be analyzed and why.

{sourcecode-1.24.0 → sourcecode-1.26.0}/README.md

@@ -2,7 +2,7 @@
 
 **Compressed AI-ready context for Java/Spring enterprise codebases.**
 
-![Version](https://img.shields.io/badge/version-1.24.0-blue)
+![Version](https://img.shields.io/badge/version-1.26.0-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -36,7 +36,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.24.0
+# sourcecode 1.26.0
 ```
 
 ---
@@ -44,7 +44,7 @@ sourcecode version
 ## Quickstart
 
 ```bash
-# High-signal summary (~600-800 tokens) — recommended starting point
+# High-signal summary (1000–3000 tokens depending on repo size) — recommended starting point
 sourcecode --compact
 
 # Add git hotspots and uncommitted file count
@@ -92,8 +92,9 @@ Example output for a Spring Boot project (`--compact`):
 
 | Flag | Alias | Default | Description |
 |------|-------|---------|-------------|
-| `--compact` | | off | **Recommended.** ~600-800 token summary: stack, entry points, dependencies, risk flags, confidence, gaps. Optimized for agent context windows. |
+| `--compact` | | off | High-signal summary (1000–3000 tokens): stacks, entry points, dependencies, risk flags, confidence, gaps. Includes `security_surface`, `mybatis`, and `transactional_boundaries` for Java projects. |
 | `--agent` | | off | Structured noise-free JSON for AI agents: identity, entry points, dependencies, confidence, gaps. Auto-enables dependency, env-var, and code-notes analysis. |
+| `--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 changes. |
 | `--changed-only` | | off | Limit output to git-modified files (staged, unstaged, untracked). Forces compact output. |
 | `--depth` | | `4` | File tree traversal depth (1–20). Java/Maven projects auto-adjust to 12. |
@@ -123,16 +124,18 @@ sourcecode prepare-context TASK [PATH] [OPTIONS]
 | `refactor` | Structural problems, improvement opportunities, high-annotation files | Code quality review |
 | `generate-tests` | Source files without test pairs, coverage gap analysis | Writing missing tests |
 | `review-pr` | Uncommitted/changed files + architectural impact | Pre-merge review |
-| `delta` | Only files changed in a git range (`--since`), affected entry points | Incremental CI context |
+| `delta` | Changed files with multi-hop impact analysis, structural import graph, system-level impact summary | Incremental CI/review context |
 
 ### Options
 
 | Option | Description |
 |--------|-------------|
 | `--since REF` | Git ref for `delta` task (e.g. `HEAD~3`, `main`, `v1.2.0`). Required for `delta`; ignored for other tasks. |
+| `--symptom TEXT` | *(fix-bug only)* Keyword hint for the bug — boosts matching files and surfaces related code notes. |
 | `--llm-prompt` | Append a ready-to-use LLM prompt to the output. |
 | `--dry-run` | Show what would be analyzed without running it. |
 | `--copy` / `-c` | Copy output to clipboard after a successful run. |
+| `--output` / `-o` | Write output to a file. |
 | `--task-help` | List all tasks with descriptions and exit. |
 
 ### Examples
@@ -141,11 +144,8 @@ sourcecode prepare-context TASK [PATH] [OPTIONS]
 # Explain the current repo
 sourcecode prepare-context explain
 
-# Analyze a specific repo path
-sourcecode prepare-context explain /path/to/repo
-
-# Focus on bug-prone files
-sourcecode prepare-context fix-bug
+# Focus on bug-prone files, with a symptom hint
+sourcecode prepare-context fix-bug --symptom "NullPointerException in OrderService"
 
 # Incremental context: files changed since branch diverged from main
 sourcecode prepare-context delta . --since main
@@ -159,6 +159,51 @@ sourcecode prepare-context --task-help
 
 ---
 
+## `delta` — incremental impact analysis
+
+The `delta` task is the recommended mode for CI pipelines and PR reviews. It goes beyond listing changed files: it builds a structural import graph and propagates impact transitively up to 3 hops.
+
+```bash
+sourcecode prepare-context delta [PATH] --since REF
+```
+
+**Output fields:**
+
+| Field | Description |
+|-------|-------------|
+| `changed_files` | Files modified in the git range |
+| `relevant_files` | Changed files + files pulled in by the import graph (scored by artifact type and hop distance) |
+| `impact_summary` | Human-readable summary: artifact types changed and active risk areas |
+| `affected_modules` | DDD domain modules touched by the change |
+| `risk_areas` | Per-area severity breakdown (`security`, `api`, `persistence`, etc.) |
+| `change_type` | Closed taxonomy: `behavioral_change`, `structural_change`, `configuration_change`, `dependency_change`, `security_change` |
+| `system_impact` | Subsystems affected, behavioral changes, runtime impact notes |
+| `dependency_graph_summary` | Verified structural import edges (hop 1–3) and `propagation_depth`. **Only real imports — no heuristics, no test files.** |
+| `impact_score_per_file` | Per-file numeric impact score (0–1) |
+| `since` | The git ref used |
+| `gaps` | What the analysis could not determine |
+
+**How the import graph works:**
+
+1. Each changed file is classified by artifact type (`controller`, `service`, `repository`, `security`, `spring_config`, etc.).
+2. A BFS traversal walks the import graph **repo-wide** (not restricted to the same module), up to 3 hops deep.
+3. `dependency_graph_summary.edges` only contains verified `import` / `@Autowired` / constructor-injection relationships. Test files and heuristic proximity matches are excluded from edges (they appear in `relevant_files` only if they have real imports of changed files).
+4. Score decays 30% per hop: a directly-changed `SecurityConfig.java` scores 0.90; its direct importer scores 0.63; a transitive importer scores 0.44.
+
+```bash
+# Changed service → controller → facade (3 hops)
+sourcecode prepare-context delta . --since main
+
+# Output includes:
+# dependency_graph_summary.edges:
+#   hop-1: OrderService.java → OrderRepository.java
+#   hop-2: OrderRepository.java → OrderController.java
+#   hop-3: OrderController.java → OrderFacade.java
+# propagation_depth: 3
+```
+
+---
+
 ## Output schema
 
 All outputs include a `confidence_summary` block with `overall`, `stack`, and `entry_points` confidence levels (`high` / `medium` / `low`), plus an `analysis_gaps` list describing what could not be analyzed and why.

{sourcecode-1.24.0 → sourcecode-1.26.0}/pyproject.toml

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

{sourcecode-1.24.0 → sourcecode-1.26.0}/src/sourcecode/__init__.py

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

{sourcecode-1.24.0 → sourcecode-1.26.0}/src/sourcecode/cli.py

@@ -1773,6 +1773,25 @@ def prepare_context_cmd(
         out["affected_entry_points"] = output.affected_entry_points
     # Delta-specific impact fields
     if task == "delta":
+        if output.error_code:
+            # Hard error — emit structured error JSON and exit, skip normal delta fields
+            _err_out: dict[str, Any] = {
+                "task": output.task,
+                "error": output.error_code,
+                "since": output.since,
+                "message": output.error_message,
+            }
+            if output.error_hints:
+                _err_out["hint"] = output.error_hints
+            _err_json = json.dumps(_err_out, indent=2, ensure_ascii=False)
+            if output_path is not None:
+                output_path.write_text(_err_json, encoding="utf-8")
+            else:
+                import sys as _sys
+                _sys.stdout.buffer.write(_err_json.encode("utf-8"))
+                _sys.stdout.buffer.write(b"\n")
+                _sys.stdout.buffer.flush()
+            raise typer.Exit(code=1)
         if output.since:
             out["since"] = output.since
         if output.impact_summary:

{sourcecode-1.24.0 → sourcecode-1.26.0}/src/sourcecode/prepare_context.py

@@ -333,6 +333,10 @@ class TaskOutput:
     change_type: list[str] = field(default_factory=list)
     dependency_graph_summary: dict = field(default_factory=dict)
     impact_score_per_file: dict = field(default_factory=dict)
+    # error state (git ref not found, etc.)
+    error_code: Optional[str] = None
+    error_message: Optional[str] = None
+    error_hints: list[str] = field(default_factory=list)
 
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -618,7 +622,34 @@ class TaskContextBuilder:
         _delta_files: Optional[set[str]] = None
         if task_name == "delta":
             _delta_raw = self._get_git_changed_files(since=since)
-            if _delta_raw:
+            if _delta_raw is None:
+                # Explicit --since ref couldn't be resolved — hard error, no fallback
+                _avail_branches, _suggested = self._get_available_refs(since or "")
+                _hints: list[str] = []
+                if _suggested:
+                    _hints.append(f"Did you mean '{_suggested}'?")
+                if _avail_branches:
+                    _hints.append(f"Available refs: {', '.join(_avail_branches[:8])}")
+                return TaskOutput(
+                    task="delta",
+                    goal="Produce incremental context for changed files — avoids re-reading the full repo.",
+                    project_summary=None,
+                    architecture_summary=None,
+                    relevant_files=[],
+                    suspected_areas=[],
+                    improvement_opportunities=[],
+                    test_gaps=[],
+                    key_dependencies=[],
+                    code_notes_summary=None,
+                    limitations=[],
+                    confidence="low",
+                    since=since,
+                    error_code="git_ref_not_found",
+                    error_message=f"Git reference '{since}' does not exist in this repository.",
+                    error_hints=_hints,
+                    gaps=[f"Cannot compute delta: git ref '{since}' not found."] + _hints,
+                )
+            elif _delta_raw:
                 _delta_files = set(_delta_raw)
 
         # ── 5c. review-pr suspected_areas (needs git uncommitted_files) ──────
@@ -2087,9 +2118,13 @@ class TaskContextBuilder:
             impact_score_per_file,
         )
 
-    def _get_git_changed_files(self, since: Optional[str] = None) -> list[str]:
+    def _get_git_changed_files(self, since: Optional[str] = None) -> Optional[list[str]]:
         """Get files changed since a git ref (default: HEAD~1) relative to self.root.
 
+        Returns None when `since` is explicitly provided but cannot be resolved —
+        this is an error state, not "no changes". Callers must distinguish None
+        (ref invalid) from [] (ref valid, no changes).
+
         Uses --relative so paths are relative to cwd (self.root), not the git repo
         root. This is critical for monorepos where self.root is a subpath of the
         git root and git diff would otherwise return prefixed paths that don't match
@@ -2112,9 +2147,13 @@ class TaskContextBuilder:
                     line.strip() for line in (result.stdout or "").splitlines()
                     if line.strip()
                 ]
+            # Non-zero exit with explicit ref = ref doesn't exist — no silent fallback
+            if since:
+                return None
         except (subprocess.TimeoutExpired, FileNotFoundError):
-            pass
-        # Fallback: uncommitted changes
+            if since:
+                return None
+        # No explicit since: fall back to uncommitted changes
         try:
             result = subprocess.run(
                 ["git", "diff", "--name-only", "--relative"],
@@ -2130,3 +2169,26 @@ class TaskContextBuilder:
         except (subprocess.TimeoutExpired, FileNotFoundError):
             pass
         return []
+
+    def _get_available_refs(self, invalid_ref: str) -> tuple[list[str], Optional[str]]:
+        """Return (available_branch_names, suggested_alternative) for error hints."""
+        import subprocess
+        branches: list[str] = []
+        suggested: Optional[str] = None
+        try:
+            r = subprocess.run(
+                ["git", "branch", "-a", "--format=%(refname:short)"],
+                cwd=str(self.root),
+                capture_output=True, text=True, timeout=5,
+            )
+            if r.returncode == 0:
+                all_refs = [b.strip() for b in r.stdout.splitlines() if b.strip()]
+                branches = [b for b in all_refs if "HEAD" not in b][:10]
+                ref_lower = invalid_ref.lower()
+                if ref_lower == "master" and any(b.rstrip("/").endswith("main") for b in all_refs):
+                    suggested = "main"
+                elif ref_lower == "main" and any(b.rstrip("/").endswith("master") for b in all_refs):
+                    suggested = "master"
+        except (subprocess.TimeoutExpired, FileNotFoundError):
+            pass
+        return branches, suggested