sourcecode 1.27.0__tar.gz → 1.29.0__tar.gz

sourcecode-1.29.0/.continue-here.md

@@ -0,0 +1,108 @@
+# Continue Here — atlas-cli --agent token reduction
+
+**Paused:** 2026-05-16 (sesión 4)
+**Repo:** `/Users/user/Downloads/atlas-cli`
+**Branch:** master
+**Commit:** `f1cb001 corrigiendo bug --agent que duplicaba tokens sin justificación` (committed)
+
+---
+
+## Estado actual
+
+Sesión 4: refactorización de `agent_view()` en `serializer.py` completada. **Todo committed.** Working tree limpio.
+
+---
+
+## Qué se hizo esta sesión
+
+### Problema resuelto
+
+`--agent` producía ~11.337 tokens en SAS vs ~5.885 de `--compact`, con contenido casi idéntico. Objetivo: reducir tokens significativamente manteniendo solo lo que diferencia `--agent`.
+
+### Cambios en `agent_view()` (`src/sourcecode/serializer.py`)
+
+| Cambio | Impacto |
+|--------|---------|
+| Elimina `production_dependencies` / `dev_tools` / `test_utilities` / `build_tooling` (dep_groups asdict completo) | Mayor fuente de bloat: -3.000-5.000 tokens en repos grandes |
+| `key_dependencies`: de asdict+50 items → `name+version+role+risk_flags` solo, cap 20 | -500-1.500 tokens |
+| Elimina `confidence_summary.hard_signals` / `soft_signals` / `ignored_signals` | -500-1.000 tokens |
+| Elimina bloque `agent_mode` (contenido estático sin señal) | -80 tokens siempre |
+| Elimina `signals.env_vars.keys[]` (duplica compact `env_map`) | -300-500 tokens |
+| `signals.code_notes.top` cap 10→5, strip a `kind+path+line+text` | -200 tokens |
+| Entry points (no-bootstrap): strip a `path+kind+confidence` (como compact) | reducción moderada |
+| Elimina `development_entry_points` (noise para agentes de producción) | pequeña |
+| `architecture.layers` capado a 5 | pequeña |
+
+**Reducción estimada para SAS:** −40–60% tokens vs `--agent` anterior.
+
+### Campos que permanecen únicos de `--agent`
+
+| Campo | Por qué justifica tokens extra vs `--compact` |
+|-------|----------------------------------------------|
+| `file_relevance` (top-20 scored) | Compact no tiene equivalente. Agente sabe qué leer sin explorar. |
+| `architecture.layers` | Compact solo tiene `architecture_summary` string. |
+| `suspicious_dependencies` | Deps declarados sin import observado. Compact no lo tiene. |
+| `confidence_reasons` | Explicación accionable de secciones low-confidence. Compact no lo tiene. |
+
+### Tests actualizados
+
+- `tests/test_block5_quality.py` — 5 tests de `agent_mode` reemplazados por tests de las nuevas garantías (no `agent_mode`, no `hard_signals`, no `env_vars.keys`, no dep_groups)
+- `tests/test_pipeline_integrity.py` — `test_agent_splits_development_and_auxiliary_eps` → verifica que dev/aux EPs NO aparecen
+
+---
+
+## Tests al pausar
+
+Suite completa (sin fallos pre-existentes): **todo verde**
+
+Fallos pre-existentes (no relacionados, ya presentes antes):
+- `test_block2_coverage.py::test_java_marked_unsupported` — DocRecord bug en doc_analyzer.py
+- `test_dependency_analyzer_node_python.py::test_python_requirements_without_lockfile` — versión typer mismatch
+
+---
+
+## Pendiente / próximos pasos opcionales
+
+1. **Smoke test en saint-server** para medir tokens reales antes/después:
+   ```bash
+   sourcecode saint-server --agent --output /tmp/agent_new.json
+   python3 -c "import json,sys; d=json.load(open('/tmp/agent_new.json')); print('agent tokens (est):', len(json.dumps(d))//4)"
+   ```
+
+2. **Verificar que `suspicious_dependencies` es útil en repos reales** — en repos Python/JS (no JVM, donde el index de imports no funciona). En JVM siempre vacío por diseño.
+
+3. **Ajustar caps según medición real**: si `file_relevance` (20 files) sigue siendo el mayor contribuyente de tokens, considerar reducir a 15. Medir con `--full` vs default.
+
+4. **Smoke tests delta pendientes** de sesión anterior — ver sección "Smoke tests sesión 3" en historial de commits.
+
+---
+
+## Para retomar
+
+```bash
+cd /Users/user/Downloads/atlas-cli
+git log --oneline -3
+# debe mostrar: f1cb001 corrigiendo bug --agent que duplicaba tokens sin justificación
+
+python3 -m pytest tests/ \
+  --ignore=tests/test_block2_coverage.py \
+  --deselect=tests/test_dependency_analyzer_node_python.py::test_python_requirements_without_lockfile_keeps_declared_versions \
+  -q
+# Expected: todo verde
+
+# Verificación rápida agent_view
+python3 -c "
+from sourcecode.serializer import agent_view
+from sourcecode.schema import SourceMap, StackInfo, SourceMapMetadata
+sm = SourceMap(stacks=[StackInfo(stack='python', primary=True)], project_type='python', project_summary='test')
+r = agent_view(sm)
+assert 'agent_mode' not in r
+assert 'production_dependencies' not in r
+assert 'hard_signals' not in r.get('confidence_summary', {})
+print('OK — agent_mode/dep_groups/hard_signals all absent')
+"
+```
+
+---
+
+*Pausado 2026-05-16 sesión 4 — gsd:pause-work*

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.27.0
+Version: 1.29.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.27.0-blue)
+![Version](https://img.shields.io/badge/version-1.29.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.27.0
+# sourcecode 1.29.0
 ```
 
 ---

{sourcecode-1.27.0 → sourcecode-1.29.0}/README.md

@@ -2,7 +2,7 @@
 
 **Compressed AI-ready context for Java/Spring enterprise codebases.**
 
-![Version](https://img.shields.io/badge/version-1.27.0-blue)
+![Version](https://img.shields.io/badge/version-1.29.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.27.0
+# sourcecode 1.29.0
 ```
 
 ---

{sourcecode-1.27.0 → sourcecode-1.29.0}/pyproject.toml

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

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

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

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

@@ -1633,7 +1633,7 @@ def prepare_context_cmd(
       refactor       Structural issues, improvement opportunities
       generate-tests Untested source files, test gap analysis
       onboard        Full project context for new agents/developers
-      review-pr      Changed files + architectural impact
+      review-pr      PR diff: changed files, security/transactional impact, test gaps (requires git diff or --since)
       delta          Incremental context: git-changed files only
 
     \b
@@ -1642,6 +1642,8 @@ def prepare_context_cmd(
       sourcecode prepare-context explain /path/to/repo
       sourcecode prepare-context fix-bug
       sourcecode prepare-context delta --since main
+      sourcecode prepare-context review-pr --since origin/main
+      sourcecode prepare-context review-pr . --since main --output review.json
       sourcecode prepare-context onboard --llm-prompt
       sourcecode prepare-context --task-help
     """
@@ -1734,6 +1736,14 @@ def prepare_context_cmd(
             "test_gaps": False, "code_notes_summary": False,
             "changed_files": True, "affected_entry_points": True,
         },
+        "review-pr": {
+            "project_summary": False, "architecture_summary": False,
+            "relevant_files": True, "key_dependencies": False,
+            "gaps": True, "confidence": False,
+            "suspected_areas": False, "improvement_opportunities": False,
+            "test_gaps": False, "code_notes_summary": False,
+            "changed_files": True, "affected_entry_points": True,
+        },
     }
     _content_filter = _TASK_CONTENT_MAP.get(task, {})
 
@@ -1813,6 +1823,53 @@ def prepare_context_cmd(
             out["dependency_graph_summary"] = output.dependency_graph_summary
         if output.impact_score_per_file:
             out["impact_score_per_file"] = output.impact_score_per_file
+    # review-pr specific fields
+    if task == "review-pr":
+        if output.error_code:
+            _err_out: dict[str, Any] = {
+                "task": output.task,
+                "ci_decision": output.ci_decision or "error",
+                "error": output.error_code,
+                "message": output.error_message,
+            }
+            if output.since:
+                _err_out["since"] = output.since
+            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)
+        out["review_type"] = "pull_request"
+        if output.ci_decision:
+            out["ci_decision"] = output.ci_decision
+        if output.base_ref:
+            out["base_ref"] = output.base_ref
+        if output.since:
+            out["since"] = output.since
+        if output.affected_modules:
+            out["affected_modules"] = output.affected_modules
+        if output.security_impact:
+            out["security_impact"] = output.security_impact
+        if output.transactional_impact:
+            out["transactional_impact"] = output.transactional_impact
+        if output.configuration_impact:
+            out["configuration_impact"] = output.configuration_impact
+        if output.test_coverage_risk:
+            out["test_coverage_risk"] = output.test_coverage_risk
+        if output.review_hotspots:
+            out["review_hotspots"] = output.review_hotspots
+        if output.suggested_review_order:
+            out["suggested_review_order"] = output.suggested_review_order
+        if output.impact_summary:
+            out["impact_summary"] = output.impact_summary
+        if output.why_these_files:
+            out["reasoning"] = output.why_these_files
     if output.limitations:
         out["limitations"] = output.limitations
     if output.symptom:

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

@@ -338,11 +338,19 @@ class TaskOutput:
     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"
+    ci_decision: Optional[str] = None  # "no_changes" | "analysis_success" | "git_ref_error" | "no_git_repo"
     # 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"
+    # review-pr specific impact sections
+    base_ref: Optional[str] = None
+    security_impact: dict = field(default_factory=dict)
+    transactional_impact: dict = field(default_factory=dict)
+    configuration_impact: dict = field(default_factory=dict)
+    test_coverage_risk: dict = field(default_factory=dict)
+    review_hotspots: list[str] = field(default_factory=list)
+    suggested_review_order: list[str] = field(default_factory=list)
 
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -659,6 +667,58 @@ class TaskContextBuilder:
             elif _delta_raw:
                 _delta_files = set(_delta_raw)
 
+        # ── 5d. review-pr: git-first gate ──────────────────────────────────────
+        if task_name == "review-pr":
+            if not self._is_git_repo():
+                return TaskOutput(
+                    task="review-pr", goal=spec.goal,
+                    project_summary=None, architecture_summary=None,
+                    relevant_files=[], suspected_areas=[],
+                    improvement_opportunities=[], test_gaps=[],
+                    key_dependencies=[], code_notes_summary=None,
+                    limitations=[], confidence="low",
+                    error_code="no_git_repo",
+                    error_message="review-pr requires a git repository.",
+                    ci_decision="no_git_repo",
+                )
+            _pr_raw = self._get_git_changed_files(since=since)
+            if _pr_raw is None:
+                _avail_pr, _sug_pr = self._get_available_refs(since or "")
+                _pr_hints: list[str] = []
+                if _sug_pr:
+                    _pr_hints.append(f"Did you mean '{_sug_pr}'?")
+                if _avail_pr:
+                    _pr_hints.append(f"Available refs: {', '.join(_avail_pr[:8])}")
+                return TaskOutput(
+                    task="review-pr", goal=spec.goal,
+                    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"Base ref '{since}' not found in this repository.",
+                    error_hints=_pr_hints,
+                    gaps=[f"Cannot compute PR diff: git ref '{since}' not found."] + _pr_hints,
+                    ci_decision="git_ref_error",
+                )
+            if not _pr_raw:
+                _no_diff_hint = "review-pr requires changed files or --since <ref>."
+                return TaskOutput(
+                    task="review-pr", goal=spec.goal,
+                    project_summary=None, architecture_summary=None,
+                    relevant_files=[], suspected_areas=[],
+                    improvement_opportunities=[], test_gaps=[],
+                    key_dependencies=[], code_notes_summary=None,
+                    limitations=[], confidence="low",
+                    error_code="no_diff",
+                    error_message=f"No PR diff detected. {_no_diff_hint}",
+                    gaps=[f"No PR diff detected. {_no_diff_hint}"],
+                    ci_decision="no_changes",
+                )
+            _delta_files = set(_pr_raw)
+
         # ── 5c. review-pr suspected_areas (needs git uncommitted_files) ──────
         if task_name == "review-pr" and spec.enable_code_notes:
             pr_areas: dict[str, int] = {}
@@ -698,7 +758,7 @@ class TaskContextBuilder:
         _delta_dep_graph_summary: dict = {}
         _delta_impact_score_per_file: dict = {}
 
-        if task_name == "delta":
+        if task_name in ("delta", "review-pr"):
             _delta_changed_list: list[str] = sorted(_delta_files) if _delta_files else []
             (
                 relevant_files,
@@ -727,7 +787,88 @@ class TaskContextBuilder:
                 delta_files=None,
             )
 
-        # ── 6b. Symptom keyword boost + related notes (fix-bug + --symptom) ──
+        # ── 6b. review-pr: derive PR-specific impact sections from delta analysis ──
+        _pr_security_impact: dict = {}
+        _pr_transactional_impact: dict = {}
+        _pr_configuration_impact: dict = {}
+        _pr_test_coverage_risk: dict = {}
+        _pr_review_hotspots: list[str] = []
+        _pr_suggested_review_order: list[str] = []
+        _pr_base_ref: Optional[str] = None
+
+        if task_name == "review-pr":
+            _pr_base_ref = since or "HEAD"
+            _sys_risk_areas = _delta_system_impact.get("risk_areas", [])
+
+            _security_files = [
+                f for ra in _sys_risk_areas if ra["area"] == "security"
+                for f in ra["affected_files"]
+            ]
+            _transaction_files = [
+                f for ra in _sys_risk_areas if ra["area"] in ("transactions", "business_logic")
+                for f in ra["affected_files"]
+            ]
+            _config_files = [
+                f for ra in _sys_risk_areas if ra["area"] in ("api", "config")
+                for f in ra["affected_files"]
+                if any(kw in f.lower() for kw in ("config", "properties", "yml", "yaml", "xml", "spring"))
+            ]
+
+            if _security_files:
+                _pr_security_impact = {
+                    "affected_resources": _security_files,
+                    "risk_level": "high",
+                }
+            if _transaction_files:
+                _pr_transactional_impact = {
+                    "affected_transactions": _transaction_files,
+                    "risk": "possible transaction boundary change",
+                }
+            if _config_files:
+                _pr_configuration_impact = {"changed_configs": _config_files}
+
+            # Test coverage risk scoped to changed source files only
+            _changed_src = [
+                f for f in sorted(_delta_files or set())
+                if not self._is_test(f) and self._is_source(f)
+            ]
+            _test_stems = {Path(p).stem for p in test_set}
+            _untested_changed = [f for f in _changed_src if Path(f).stem not in _test_stems]
+            _test_risk_level = (
+                "high" if len(_untested_changed) > 3
+                else "medium" if _untested_changed
+                else "low"
+            )
+            _pr_test_coverage_risk = {
+                "changed_files_without_tests": _untested_changed[:10],
+                "risk_level": _test_risk_level,
+            }
+
+            # Review hotspots: top changed files ranked by impact score
+            _pr_review_hotspots = sorted(
+                _delta_files or set(),
+                key=lambda f: _delta_impact_score_per_file.get(f, 0.0),
+                reverse=True,
+            )[:8]
+
+            # Suggested review order: security first, then api → service → persistence → config
+            _ORDER_TYPES = ["security", "controller", "service", "repository", "mapper",
+                            "spring_config", "config", "domain_model", "dto"]
+            _seen_order: set[str] = set()
+            for _otype in _ORDER_TYPES:
+                for _ra in _delta_risk_areas:
+                    for _f in _ra.get("affected_files", []):
+                        if _f not in _seen_order:
+                            _cls = self._classify_changed_file(_f)
+                            if _cls["artifact_type"] == _otype:
+                                _pr_suggested_review_order.append(_f)
+                                _seen_order.add(_f)
+            for _f in _pr_review_hotspots:
+                if _f not in _seen_order:
+                    _pr_suggested_review_order.append(_f)
+                    _seen_order.add(_f)
+
+        # ── 6c. Symptom keyword boost + related notes (fix-bug + --symptom) ──
         symptom_keywords: list[str] = []
         related_notes: list[dict] = []
         symptom_note: Optional[str] = None
@@ -883,7 +1024,7 @@ class TaskContextBuilder:
 
         conf_summary, analysis_gaps = ConfidenceAnalyzer().analyze(sm_for_conf)
         confidence = conf_summary.overall
-        if task_name == "delta":
+        if task_name in ("delta", "review-pr"):
             # Use delta-specific gaps; ConfidenceAnalyzer gaps are about full-repo
             # detection quality and are not meaningful for an incremental diff.
             gaps = _delta_analysis_gaps
@@ -895,16 +1036,16 @@ class TaskContextBuilder:
                 gaps.append(_mybatis_warning["reason"])
 
         # ── 9. why_these_files ────────────────────────────────────────────────
-        if task_name == "delta":
+        if task_name in ("delta", "review-pr"):
             why_these_files = _delta_why
         else:
             why_these_files = {rf.path: rf.reason for rf in relevant_files}
 
-        # ── 10. Delta: git changed files + entry points ───────────────────────
+        # ── 10. Delta / review-pr: git changed files + entry points ──────────
         changed_files: list[str] = []
         affected_entry_points: list[str] = []
-        if task_name == "delta":
-            changed_files = sorted(_delta_files) if _delta_files else self._get_git_changed_files(since=since)
+        if task_name in ("delta", "review-pr"):
+            changed_files = sorted(_delta_files) if _delta_files else (self._get_git_changed_files(since=since) or [])
             _ep_set = {ep.path for ep in entry_points}
             # include framework-detected entry points AND files classified as
             # entrypoint/controller/security by artifact taxonomy
@@ -939,16 +1080,24 @@ class TaskContextBuilder:
             impact_summary=_delta_impact_summary,
             affected_modules=_delta_affected_modules,
             risk_areas=_delta_risk_areas,
-            since=since if task_name == "delta" else None,
+            since=since if task_name in ("delta", "review-pr") else None,
             system_impact=_delta_system_impact,
             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 "analysis_success" if task_name in ("delta", "review-pr")
                 else None
             ),
+            # review-pr specific
+            base_ref=_pr_base_ref,
+            security_impact=_pr_security_impact,
+            transactional_impact=_pr_transactional_impact,
+            configuration_impact=_pr_configuration_impact,
+            test_coverage_risk=_pr_test_coverage_risk,
+            review_hotspots=_pr_review_hotspots,
+            suggested_review_order=_pr_suggested_review_order,
         )
 
     def render_prompt(self, output: TaskOutput) -> str:
@@ -1240,6 +1389,19 @@ class TaskContextBuilder:
     def _is_source(self, path: str) -> bool:
         return Path(path).suffix.lower() in _SOURCE_EXTENSIONS
 
+    def _is_git_repo(self) -> bool:
+        import subprocess
+        try:
+            r = subprocess.run(
+                ["git", "rev-parse", "--git-dir"],
+                cwd=str(self.root),
+                capture_output=True, text=True,
+                encoding="utf-8", errors="replace", timeout=5,
+            )
+            return r.returncode == 0
+        except (subprocess.TimeoutExpired, FileNotFoundError):
+            return False
+
     # ── Delta impact analysis ─────────────────────────────────────────────────
 
     @staticmethod
@@ -2309,10 +2471,11 @@ class TaskContextBuilder:
             r = subprocess.run(
                 ["git", "branch", "-a", "--format=%(refname:short)"],
                 cwd=str(self.root),
-                capture_output=True, text=True, timeout=5,
+                capture_output=True, text=True,
+                encoding="utf-8", errors="replace", timeout=5,
             )
             if r.returncode == 0:
-                all_refs = [b.strip() for b in r.stdout.splitlines() if b.strip()]
+                all_refs = [b.strip() for b in (r.stdout or "").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):

sourcecode-1.29.0/tests/test_encoding_regression.py

@@ -0,0 +1,138 @@
+"""Regression tests for C3 — UTF-8 double-encoding of accented characters.
+
+Fixture files:
+  - tests/fixtures/latin1_sample_iso.java  — Latin-1 encoded (bytes 0xe1, 0xf3, etc.)
+  - tests/fixtures/latin1_sample.java      — UTF-8 encoded (multibyte sequences)
+
+Both should decode cleanly to the correct Unicode characters.
+The old code read Latin-1 files with errors='replace', producing double-encoded garbage.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from sourcecode.tree_utils import safe_read_text
+
+FIXTURES = Path(__file__).parent / "fixtures"
+LATIN1_FILE = FIXTURES / "latin1_sample_iso.java"
+UTF8_FILE = FIXTURES / "latin1_sample.java"
+
+
+class TestSafeReadText:
+    """safe_read_text must decode both UTF-8 and Latin-1 files correctly."""
+
+    def test_utf8_file_reads_correctly(self):
+        content = safe_read_text(UTF8_FILE)
+        # These characters must appear verbatim — not as double-encoded sequences
+        assert "días" in content, f"Expected 'días', got: {content[:200]!r}"
+        assert "ñ" in content or "función" in content or "ñoño" in content
+        assert "Ã" not in content, "Double-encoded: U+00C3 found (Ã). Encoding was mangled."
+
+    def test_latin1_file_reads_correctly(self):
+        content = safe_read_text(LATIN1_FILE)
+        # Latin-1 0xe1 = 'á' — must decode to the correct character
+        assert "á" in content, f"Expected 'á', got: {content!r}"
+        assert "ó" in content, f"Expected 'ó', got: {content!r}"
+        # No replacement chars
+        assert "�" not in content, "Replacement character found — file was not decoded correctly."
+        # No double-encoding: 'á' in double-encoded UTF-8-as-Latin-1 would appear as 'á'
+        assert "Ã" not in content, "Double-encoded: U+00C3 found (Ã). Latin-1 file was not decoded correctly."
+
+    def test_nonexistent_file_raises_oserror(self):
+        with pytest.raises(OSError):
+            safe_read_text(FIXTURES / "does_not_exist.java")
+
+
+class TestCodeNotesEncoding:
+    """CodeNotesAnalyzer must extract notes from Latin-1 files without encoding corruption."""
+
+    def test_latin1_todo_extracted_cleanly(self):
+        from sourcecode.code_notes_analyzer import CodeNotesAnalyzer
+
+        # analyze() scans FIXTURES dir — Latin-1 file is there
+        analyzer = CodeNotesAnalyzer()
+        notes, _, _ = analyzer.analyze(FIXTURES)
+        # Should have extracted TODO without replacement chars
+        todo_texts = [n.text for n in notes if "latin1_sample_iso" in n.path]
+        for text in todo_texts:
+            assert "â" not in text, f"Double-encoded byte found in TODO text: {text!r}"
+            assert "Ã" not in text, f"Double-encoded char in TODO text: {text!r}"
+            assert "�" not in text, f"Replacement char in TODO text: {text!r}"
+
+
+class TestGetAvailableRefsWindowsEncoding:
+    """Regression: _get_available_refs crashed on Windows due to cp1252 encoding and None stdout.
+
+    Bug: subprocess.run(text=True) without encoding= uses the OS default (cp1252 on Windows).
+    Git output containing byte 0x8d raises UnicodeDecodeError (not caught). If stdout is None,
+    r.stdout.splitlines() raises AttributeError. Both cause unhandled tracebacks.
+    Fix: encoding="utf-8", errors="replace", and (r.stdout or "").splitlines().
+    """
+
+    def _make_builder(self) -> "TaskContextBuilder":
+        from sourcecode.prepare_context import TaskContextBuilder
+        return TaskContextBuilder(FIXTURES)
+
+    def test_case_a_stdout_none_does_not_crash(self, monkeypatch):
+        """stdout=None must not raise AttributeError on splitlines()."""
+        import subprocess
+        import types
+
+        fake = types.SimpleNamespace(returncode=0, stdout=None, stderr="")
+        monkeypatch.setattr(subprocess, "run", lambda *a, **kw: fake)
+
+        builder = self._make_builder()
+        refs, suggested = builder._get_available_refs("main")
+        assert refs == []
+        assert suggested is None
+
+    def test_case_b_non_utf8_bytes_no_unicode_error(self, monkeypatch):
+        """Bytes invalid in cp1252 (e.g. 0x8d) must not raise UnicodeDecodeError.
+
+        With encoding='utf-8' + errors='replace', replacement chars appear instead.
+        """
+        import subprocess
+        import types
+
+        # Simulate git returning a branch name that survived errors="replace" decoding
+        # (the replacement char � stands in for the bad byte)
+        replaced = "develop\nfeature/caf�\n"
+        fake = types.SimpleNamespace(returncode=0, stdout=replaced, stderr="")
+        monkeypatch.setattr(subprocess, "run", lambda *a, **kw: fake)
+
+        builder = self._make_builder()
+        refs, _ = builder._get_available_refs("main")
+        assert "develop" in refs
+
+    def test_case_c_nonexistent_ref_returns_available_refs(self, monkeypatch):
+        """Non-existent --since ref must yield a list of available branches, not a crash."""
+        import subprocess
+        import types
+
+        fake = types.SimpleNamespace(
+            returncode=0,
+            stdout="develop\norigin/develop\nrelease/1.2\n",
+            stderr="",
+        )
+        monkeypatch.setattr(subprocess, "run", lambda *a, **kw: fake)
+
+        builder = self._make_builder()
+        refs, suggested = builder._get_available_refs("main")
+        assert "develop" in refs
+        # invalid_ref="main", all_refs contains no "master" → no suggestion
+        assert suggested is None
+
+    def test_case_d_nonzero_returncode_returns_empty(self, monkeypatch):
+        """returncode != 0 must not parse stdout — returns empty list silently."""
+        import subprocess
+        import types
+
+        fake = types.SimpleNamespace(returncode=128, stdout="fatal: not a git repo\n", stderr="")
+        monkeypatch.setattr(subprocess, "run", lambda *a, **kw: fake)
+
+        builder = self._make_builder()
+        refs, suggested = builder._get_available_refs("main")
+        assert refs == []
+        assert suggested is None