sourcecode 1.24.0__tar.gz → 1.27.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.24.0
+Version: 1.27.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.27.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.27.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.27.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.27.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.27.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.27.0}/pyproject.toml

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

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

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

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

@@ -1773,6 +1773,28 @@ 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,
+                "ci_decision": output.ci_decision or "git_ref_error",
+                "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.ci_decision:
+            out["ci_decision"] = output.ci_decision
         if output.since:
             out["since"] = output.since
         if output.impact_summary:

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

@@ -333,6 +333,16 @@ 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)
+    # CI decision state machine — machine-decidable signal
+    ci_decision: Optional[str] = None  # "no_changes" | "analysis_success" | "git_ref_error"
+    # git baseline resolution metadata
+    resolved_since_ref: Optional[str] = None   # actual ref/hash used for the diff
+    resolution_path: Optional[str] = None      # "exact_local_ref"|"remote_tracking_ref"|"symbolic_ref"|"head_minus_1_fallback"|"uncommitted_changes"|"unresolvable"
+    diff_validation_status: Optional[str] = None  # "valid_non_empty"|"valid_empty"|"invalid_ref"
 
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -618,7 +628,35 @@ 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,
+                    ci_decision="git_ref_error",
+                )
+            elif _delta_raw:
                 _delta_files = set(_delta_raw)
 
         # ── 5c. review-pr suspected_areas (needs git uncommitted_files) ──────
@@ -906,6 +944,11 @@ class TaskContextBuilder:
             change_type=_delta_change_type,
             dependency_graph_summary=_delta_dep_graph_summary,
             impact_score_per_file=_delta_impact_score_per_file,
+            ci_decision=(
+                "no_changes" if task_name == "delta" and not changed_files
+                else "analysis_success" if task_name == "delta"
+                else None
+            ),
         )
 
     def render_prompt(self, output: TaskOutput) -> str:
@@ -2087,9 +2130,131 @@ class TaskContextBuilder:
             impact_score_per_file,
         )
 
-    def _get_git_changed_files(self, since: Optional[str] = None) -> list[str]:
+    def _resolve_git_baseline(self, since: Optional[str]) -> dict[str, Any]:
+        """Resolve git baseline for delta diff using a 4-stage fallback chain.
+
+        Resolution order when `since` is provided:
+          1. exact local ref (git rev-parse --verify <since>)
+          2. remote-tracking ref  (origin/<since>)
+          3. symbolic ref         (git symbolic-ref refs/remotes/origin/HEAD)
+          4. HEAD~1 fallback
+
+        When `since` is None:
+          1. uncommitted changes  (git diff --name-only --relative)
+          2. HEAD~1 fallback
+
+        Returns dict with keys:
+            files: list[str]           — changed paths (empty = confirmed no changes)
+            resolved_ref: str          — ref actually used for the diff
+            resolution_path: str       — which strategy resolved it
+            diff_validation_status: str — "valid_non_empty"|"valid_empty"|"invalid_ref"
+            error: bool                — True only when ALL strategies failed
+        """
+        import subprocess
+
+        def _run(*args: str, timeout: int = 5) -> tuple[bool, str]:
+            try:
+                r = subprocess.run(
+                    ["git", *args], cwd=str(self.root),
+                    capture_output=True, text=True,
+                    encoding="utf-8", errors="replace", timeout=timeout,
+                )
+                return r.returncode == 0, (r.stdout or "").strip()
+            except (subprocess.TimeoutExpired, FileNotFoundError):
+                return False, ""
+
+        def _verify(ref: str) -> bool:
+            ok, _ = _run("rev-parse", "--verify", ref)
+            return ok
+
+        def _diff(ref: str) -> Optional[list[str]]:
+            ok, out = _run("diff", "--name-only", "--relative", ref, "HEAD", timeout=10)
+            if not ok:
+                return None
+            return [line.strip() for line in out.splitlines() if line.strip()]
+
+        def _make(files: list[str], ref: str, path: str) -> dict[str, Any]:
+            return {
+                "files": files,
+                "resolved_ref": ref,
+                "resolution_path": path,
+                "diff_validation_status": "valid_non_empty" if files else "valid_empty",
+                "error": False,
+            }
+
+        if since:
+            # Stage 1: exact local ref
+            if _verify(since):
+                files = _diff(since)
+                if files is not None:
+                    return _make(files, since, "exact_local_ref")
+
+            # Stage 2: remote-tracking ref (origin/<since>)
+            remote_ref = f"origin/{since}"
+            if _verify(remote_ref):
+                files = _diff(remote_ref)
+                if files is not None:
+                    return _make(files, remote_ref, "remote_tracking_ref")
+
+            # Stage 3: symbolic ref (origin/HEAD → e.g. origin/main)
+            ok, symref = _run("symbolic-ref", "refs/remotes/origin/HEAD")
+            if ok and symref:
+                short = symref.removeprefix("refs/remotes/")
+                if _verify(short):
+                    files = _diff(short)
+                    if files is not None:
+                        return _make(files, short, "symbolic_ref")
+
+            # Stage 4: HEAD~1 fallback — original ref was invalid
+            if _verify("HEAD~1"):
+                files = _diff("HEAD~1")
+                if files is not None:
+                    return {
+                        "files": files,
+                        "resolved_ref": "HEAD~1",
+                        "resolution_path": "head_minus_1_fallback",
+                        "diff_validation_status": "invalid_ref",  # original ref unresolved
+                        "error": False,
+                    }
+
+            # All stages failed
+            return {
+                "files": [],
+                "resolved_ref": since,
+                "resolution_path": "unresolvable",
+                "diff_validation_status": "invalid_ref",
+                "error": True,
+            }
+
+        else:
+            # No since: uncommitted changes first
+            ok, out = _run("diff", "--name-only", "--relative", timeout=10)
+            if ok:
+                files = [line.strip() for line in out.splitlines() if line.strip()]
+                if files:
+                    return _make(files, "HEAD", "uncommitted_changes")
+
+            # HEAD~1 fallback
+            if _verify("HEAD~1"):
+                files = _diff("HEAD~1")
+                if files is not None:
+                    return _make(files or [], "HEAD~1", "head_minus_1_fallback")
+
+            return {
+                "files": [],
+                "resolved_ref": "HEAD",
+                "resolution_path": "unresolvable",
+                "diff_validation_status": "invalid_ref",
+                "error": True,
+            }
+
+    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 +2277,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 +2299,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