sourcecode 2.6.0__tar.gz → 2.6.2__tar.gz

{sourcecode-2.6.0 → sourcecode-2.6.2}/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## [2.6.2] — 2026-07-23
+
+**Field-eval Fase 3 — cache reuse (C) + cold-scan honesty (E). No
+functional-contract change; both are safe, measured additions.** Suite:
+**3679 passed, 5 skipped, 1 deselected** (the deselected chunker test is a
+pre-existing external-fixture flake).
+
+### Changed
+
+- **C — `review-pr` reuses the shared repo-wide CIR when it is already warm.**
+  The `review-pr` behavioral-impact path builds a *deliberately bounded* scope
+  (changed files + sibling directories, git-first, no full-repo traversal — the
+  bound is what keeps it fast). It now consults the shared Canonical IR through
+  a new get-only `context_cache.peek_cir`: on a warm cache the impact engine
+  runs over the full repo-wide graph for free (strictly more callers — closes
+  the DI-mediated blind spot) at O(1); on a miss it keeps its own scoped build.
+  `peek_cir` **never builds and never writes**, so a scoped caller can never
+  poison the repo-wide knowledge key that `explain`/`impact` read from — the
+  reason the building `get_or_build_cir` was the wrong tool for this path.
+
+### Added
+
+- **E — cold-scan advisory on large repositories.** A cache hit short-circuits
+  before the file scan, so a full *cold* scan is where the wait lives. On a
+  large repo (≥ `_LARGE_REPO_ADVISORY_FILES` files) the CLI now prints a one-line
+  advisory that cold analysis scales with repo size and is cached afterwards.
+  Honest by construction: it states the *shape* of the cost, never an absolute
+  latency, and is **TTY-gated** so it never reaches stdout (JSON) or an agent.
+
+## [2.6.1] — 2026-07-22
+
+**Stability patch — extraction/label fidelity on the 2.6.x line. No new
+capability, no functional-contract change.** Two isolated corrections where the
+system produced a correct result but described it imperfectly (P1-H) or gave a
+provably-correct answer a misleading label (SIM-4). `2.6.0` remains the stable
+baseline; this is a fidelity patch on top of it. Full suite: **3637 passed, 5
+skipped, 1 deselected** (the deselected chunker test is a pre-existing external
+fixture flake).
+
+### Fixed
+
+- **P1-H — lowercase-initial type declarations were silently dropped.**
+  `_CLASS_DECL_RE` assumed the PascalCase convention (`[A-Z]\w*`) for the
+  type-name start, so valid lowercase-initial Java types never entered the
+  symbol graph (e.g. `iFieldMetadata`, `i18nUpdateCartServiceExtensionHandler`;
+  JNA C-struct mirrors `passwd`/`group`/`pam_*`). The same assumption was
+  duplicated in the multi-line-join gate, so a lowercase declaration whose brace
+  sat on a continuation line stayed lost even after widening the primary regex.
+  Both name-start charsets widened to `[A-Za-z]\w*`, and a length-preserving
+  string-literal blanking guard was added at the declaration-scan sites so a
+  `class`/`interface` keyword appearing inside a string literal (e.g. a log
+  message `"... advice class for {} ..."`) can no longer mint a phantom type.
+  Fleet A/B over six real repositories: +9 real types recovered, zero phantoms,
+  zero symbols lost, control repositories byte-stable.
+- **SIM-4 — a method-precise resolution was labelled `class_expanded`.** When a
+  `Class#method` query matched one class by short/suffix name and its method
+  resolved to exactly one method node, `impact-chain` returned the correct
+  method-scoped result but tagged it `class_expanded` — signalling "I broadened
+  your query to the whole class" over a narrow, correct answer. A distinct
+  resolution value `method_resolved` now describes that case (confidence stays
+  high; nothing was widened); the genuine no-method class-expansion case keeps
+  `class_expanded`. No behavioural change — the resolved symbol set, confidence,
+  and callers are identical; only the exposed label changed to match reality.
+
 ## [2.6.0] — 2026-07-22
 
 **Engineering Decision Support — Part B (capability milestone) lands, plus the

{sourcecode-2.6.0 → sourcecode-2.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 2.6.0
+Version: 2.6.2
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm

{sourcecode-2.6.0 → sourcecode-2.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "2.6.0"
+version = "2.6.2"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-2.6.0 → sourcecode-2.6.2}/src/sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "2.6.0"
+__version__ = "2.6.2"

{sourcecode-2.6.0 → sourcecode-2.6.2}/src/sourcecode/archetype.py

@@ -599,7 +599,18 @@ class ArchetypeClassifier:
             # winner barely above the evidence floor is "undetermined-ish" and must
             # not read as high/medium however lonely it is.
             confident_enough = top.score >= _MIN_CONFIDENT_SCORE
-            if confident_enough and rel_margin >= 0.4 and mass_backed and graph_backed:
+            # Signal diversity: "high" requires the label to be backed by MORE THAN ONE
+            # distinct signal. A lone dominant signal — however strong (e.g. a fan-in
+            # Gini alone labeling a REST API an "engine") — is a single point of view and
+            # must not read as high confidence (field-eval Fase 0).
+            distinct_signals = len({e.signal for e in top.evidence if e.contribution > 0})
+            if (
+                confident_enough
+                and rel_margin >= 0.4
+                and mass_backed
+                and graph_backed
+                and distinct_signals >= 2
+            ):
                 confidence = "high"
             elif confident_enough and rel_margin >= 0.25 and mass_backed:
                 confidence = "medium"

{sourcecode-2.6.0 → sourcecode-2.6.2}/src/sourcecode/cli.py

@@ -160,10 +160,11 @@ def _build_help_text() -> str:
     text = f"""\
 [bold]ASK Engine[/bold]  [dim]· CLI: ask[/dim]   {plan_badge}
 
-Persistent structural context and ultra-fast repeated analysis for AI coding agents.
+Deterministic Java/Spring semantics and reusable structural context for AI coding agents.
 
-Cache warms on first scan; every subsequent call returns pre-built context in milliseconds.
-Cold scan: 2–10s depending on repo size. Warm cache: 0.3–0.6s.
+Cache warms on first scan; later calls reuse pre-built context instead of rescanning.
+Scan and warm time scale with repo size — small repos in seconds, large repos (thousands
+of files) in minutes. Semantic analysis itself is sub-second; repo indexing dominates.
 
 [bold]Primary usage:[/bold]
   ask --compact                  high-signal summary (~2,500–4,000 tokens)
@@ -725,6 +726,31 @@ DOCS_DEPTH_CHOICES = ["module", "symbols", "full"]
 # ── Module-level constants ─────────────────────────────────────────────────────
 _FREE_TIER_NODE_CAP: int = 50  # graph/semantic node cap — applies only to large repos on free tier
 _JAVA_MIN_SCAN_DEPTH: int = 12  # Maven src/main/java/<pkg>/<module>/File depth floor
+_LARGE_REPO_ADVISORY_FILES: int = 3000  # cold-scan advisory threshold (files); honest expectation-setting, not a speed claim
+
+
+def _cold_scan_advisory_message(
+    file_tree: dict,
+    *,
+    file_count: Optional[int] = None,
+) -> Optional[str]:
+    """Return the large-repo cold-scan advisory line, or ``None`` when the repo is
+    below :data:`_LARGE_REPO_ADVISORY_FILES`.
+
+    Honest expectation-setting (field-eval Fase 3, item E): it states the *shape* of
+    the cost — cold analysis scales with repo size, cached afterwards — and never
+    asserts a duration the tool cannot keep. Pure and TTY-agnostic: the caller owns
+    the ``sys.stderr.isatty()`` gate so this never reaches stdout (JSON) or an agent.
+    """
+    if file_count is None:
+        from sourcecode.tree_utils import flatten_file_tree as _flatten_ft
+        file_count = sum(1 for _p in _flatten_ft(file_tree) if Path(_p).suffix)
+    if file_count < _LARGE_REPO_ADVISORY_FILES:
+        return None
+    return (
+        f"[scan] large repository (~{file_count:,} files) — cold analysis scales with "
+        "repo size and may take a while; the result is cached, so later runs are fast."
+    )
 _JVM_STACKS: frozenset[str] = frozenset({"java", "kotlin", "scala", "groovy"})
 _IMPACT_PRIORITY_THRESHOLDS: list[tuple[float, str]] = [
     (0.60, "high"),
@@ -762,7 +788,7 @@ def _print_welcome_plain(tier: str) -> None:
     """Plain-text welcome — fallback when rich is unavailable."""
     lines = ["", f"  ASK Engine {__version__}   ·   {tier}   ·   CLI: ask",
              "  Actionable Software Knowledge Engine", "",
-             "  AI coding-agent context, instant.", "", "  Get started:"]
+             "  Deep Java/Spring semantics for AI coding agents.", "", "  Get started:"]
     for cmd, desc in _WELCOME_CMDS:
         lines.append(f"    {cmd.ljust(34)}{desc}")
     lines.append("")
@@ -812,7 +838,7 @@ def _print_welcome() -> None:
     t.append(_WELCOME_ENGINE, style="bold dim cyan")
     t.append("   Actionable Software Knowledge\n", style="dim")
 
-    t.append("\nAI coding-agent context, instant.\n\n", style="white")
+    t.append("\nDeep Java/Spring semantics for AI coding agents.\n\n", style="white")
 
     for cmd, desc in _WELCOME_CMDS:
         t.append("▸ ", style="cyan")
@@ -1483,23 +1509,60 @@ def main(
             # Step 1: try L1 to obtain the core_hash needed for L2 key
             _l1_result = _cache_mod.read_core(target, _core_key)
 
-            # P1-A: --env-map misses L1 when base (em=False) exists.
-            # Try the base key so env analysis can be injected lazily (<1 s)
-            # instead of triggering a 17 s full rescan.
+            # Additive overlays (--env-map / --git-context) miss L1 because they sit in
+            # the core key, yet neither changes the semantic core — env walks config
+            # files, git walks history; both only ATTACH a block. So when the base
+            # (em=False,gc=False) core exists, reuse it and inject the overlay lazily
+            # (<1 s each) instead of triggering a full rescan. (--changed-only is a
+            # different subsystem and is handled separately.)
+            # Try candidate bases that differ from the current flags only by having
+            # some subset of the requested overlays OFF, fewest flips first — so the
+            # RICHEST already-cached core wins (e.g. with --compact --git-context, the
+            # plain --compact core has em=True,gc=False, so we flip only gc and keep em).
+            # Injecting a flag whose base already has it ON would corrupt the reuse, so
+            # we inject exactly the overlays we flipped to land the hit.
             _l1_needs_env_inject = False
-            if _l1_result is None and env_map:
-                _base_flags = _core_flags_str.replace(",em=True,", ",em=False,")
-                _base_h8 = _hashlib.sha256(_base_flags.encode()).hexdigest()[:8]
+            _l1_needs_git_inject = False
+            if _l1_result is None and (env_map or git_context):
                 _sha_prefix = _git_sha if _git_sha else "nogit"
-                _base_key = f"{_sha_prefix}-{_base_h8}"
-                _base_result = _cache_mod.read_core(target, _base_key)
-                if _base_result is not None:
-                    _l1_result = _base_result
-                    _l1_needs_env_inject = True
+                _flippable = []
+                if git_context:
+                    _flippable.append("gc")   # inject git is cheap + additive
+                if env_map:
+                    _flippable.append("em")
+                # non-empty subsets, ascending size (fewest flips = richest base first)
+                import itertools as _it
+                _subsets = [
+                    s for n in range(1, len(_flippable) + 1)
+                    for s in _it.combinations(_flippable, n)
+                ]
+                for _subset in _subsets:
+                    _bf = _core_flags_str
+                    if "gc" in _subset:
+                        _bf = _bf.replace(",gc=True,", ",gc=False,")
+                    if "em" in _subset:
+                        _bf = _bf.replace(",em=True,", ",em=False,")
+                    _bk = f"{_sha_prefix}-{_hashlib.sha256(_bf.encode()).hexdigest()[:8]}"
+                    _br = _cache_mod.read_core(target, _bk)
+                    if _br is not None:
+                        _l1_result = _br
+                        _l1_needs_git_inject = "gc" in _subset
+                        _l1_needs_env_inject = "em" in _subset
+                        break
 
             if _l1_result is not None:
                 _core_dict_l1, _core_hash = _l1_result
                 _view_key = f"{_core_hash}-{_view_h}"
+                # On the lazy-inject path the core is a REUSED base whose _core_hash is
+                # shared with the base's overlay-free view — suffix the view key with the
+                # injected overlays so the injected body never collides with (or is served
+                # from) the base view. Non-inject runs keep their exact historical key, so
+                # existing cached views stay valid (no cross-version churn).
+                if _l1_needs_git_inject or _l1_needs_env_inject:
+                    _view_key = (
+                        f"{_view_key}-ov:gc{int(_l1_needs_git_inject)}"
+                        f"em{int(_l1_needs_env_inject)}"
+                    )
 
                 # Step 2: try L2 (exact view match).
                 # Skip L2 for --changed-only: the stored view is a previous
@@ -1553,6 +1616,23 @@ def main(
                                         ]
                             except Exception:
                                 pass  # env inject failed — continue without env data
+                        # P-gc: inject git context when a gc=False base L1 was reused.
+                        # GitAnalyzer walks history only — typically <1 s. Reuses the
+                        # serializer's own compact shaping (no duplication/drift).
+                        if _rebuilt is not None and _l1_needs_git_inject and compact:
+                            try:
+                                from types import SimpleNamespace as _NS_gc
+                                from sourcecode.git_analyzer import GitAnalyzer as _GitA_gc
+                                from sourcecode.serializer import _compact_git_context as _cgc
+                                _gc_obj = _GitA_gc().analyze(
+                                    target, depth=git_depth, days=git_days
+                                )
+                                _gc_block = _cgc(_NS_gc(git_context=_gc_obj))
+                                if _gc_block:
+                                    _rebuilt = dict(_rebuilt)
+                                    _rebuilt["git_context"] = _gc_block
+                            except Exception:
+                                pass  # git inject failed — continue without git data
                         if _rebuilt is not None:
                             # Apply redaction
                             if not no_redact:
@@ -1729,6 +1809,17 @@ def main(
     # 2. Filter .env and *.secret entries from file tree (SEC-02, all levels)
     file_tree = filter_sensitive_files(raw_tree, redactor)
     perf.stop("discovery", _perf_discovery)
+
+    # Cold-scan advisory (honest expectation-setting, NOT a speed claim). A cache
+    # hit short-circuits above (line ~1647) before this scan, so reaching here means
+    # a cold run: the full parse+analysis below scales with repo size. On a large
+    # repo, warn once on the TTY so the wait is expected — never on stdout (JSON) and
+    # never for agents/pipes. This does not assert a duration; it states the shape.
+    if sys.stderr.isatty() and not no_cache:
+        _advisory = _cold_scan_advisory_message(file_tree)
+        if _advisory:
+            typer.echo(_advisory, err=True)
+
     _perf_detection = perf.start()
     detector = ProjectDetector(build_default_detectors())
     workspace_analysis = WorkspaceAnalyzer().analyze(target, manifests)
@@ -5295,22 +5386,23 @@ def _render_spring_audit_github_comment(result: "SpringAuditResult", min_severit
         lines.append("")
 
     if not visible:
+        # No findings at/above severity — but a gate-coverage escape set (a separate
+        # signal, not a "finding") may still be worth surfacing before the footer.
         lines.append(f"_No findings at or above `{min_severity}` severity._")
-        return "\n".join(lines)
-
-    lines += [
-        "| Sev | Pattern | File | Symbol | Title |",
-        "|-----|---------|------|--------|-------|",
-    ]
-    for f in sorted(visible, key=lambda x: (SEVERITY_ORDER.get(x.severity, 3), x.source_file)):
-        icon = _ICONS.get(f.severity, "")
-        label = _LABELS.get(f.severity, f.severity.upper())
-        short_file = f.source_file.split("/")[-1] if "/" in f.source_file else f.source_file
-        short_sym = f.symbol.split(".")[-1] if "." in f.symbol else f.symbol
-        title_escaped = f.title.replace("|", "\\|")
-        lines.append(f"| {icon} {label} | `{f.pattern_id}` | `{short_file}` | `{short_sym}` | {title_escaped} |")
+    else:
+        lines += [
+            "| Sev | Pattern | File | Symbol | Title |",
+            "|-----|---------|------|--------|-------|",
+        ]
+        for f in sorted(visible, key=lambda x: (SEVERITY_ORDER.get(x.severity, 3), x.source_file)):
+            icon = _ICONS.get(f.severity, "")
+            label = _LABELS.get(f.severity, f.severity.upper())
+            short_file = f.source_file.split("/")[-1] if "/" in f.source_file else f.source_file
+            short_sym = f.symbol.split(".")[-1] if "." in f.symbol else f.symbol
+            title_escaped = f.title.replace("|", "\\|")
+            lines.append(f"| {icon} {label} | `{f.pattern_id}` | `{short_file}` | `{short_sym}` | {title_escaped} |")
 
-    lines.append("")
+        lines.append("")
 
     if visible:
         lines.append("<details>")
@@ -5327,6 +5419,8 @@ def _render_spring_audit_github_comment(result: "SpringAuditResult", min_severit
             lines.append("")
         lines.append("</details>")
 
+    lines += _render_gate_coverage_section(result)
+
     lines += [
         "",
         f"_Generated by [sourcecode](https://github.com/sourcecode-ai/sourcecode) · "
@@ -5335,6 +5429,57 @@ def _render_spring_audit_github_comment(result: "SpringAuditResult", min_severit
     return "\n".join(lines)
 
 
+_GATE_COVERAGE_RENDER_CAP = 25
+
+
+def _render_gate_coverage_section(result: "SpringAuditResult") -> list[str]:  # type: ignore[name-defined]
+    """Human-readable gate-coverage block: the controller handlers that do NOT carry
+    the auto-detected custom authorization gate — the escape set the JSON already
+    computes, surfaced so a reviewer sees it at a glance. Never says "unsecured": a
+    handler a servlet filter pattern covers is marked "possibly filter-covered", and the
+    unmatched ones are flagged for review, not condemned."""
+    gc = (result.security_posture or {}).get("gate_coverage")
+    if not gc:
+        return []
+    not_covered = gc.get("not_carrying_gate", 0)
+    gates = ", ".join(f"`{g}`" for g in gc.get("gate_annotations", [])) or "the detected gate"
+    total = gc.get("total_controller_handlers", 0)
+    lines: list[str] = ["", "---", ""]
+    if not_covered == 0:
+        lines.append(f"✅ **Gate coverage** — all {total} controller handlers carry {gates}.")
+        return lines
+
+    covered = gc.get("possibly_filter_covered", 0)
+    lines.append(
+        f"🔓 **Gate coverage** — {not_covered} of {total} controller handlers do not carry "
+        f"{gates}."
+    )
+    if gc.get("reconstructed_filter_patterns"):
+        lines.append(
+            f"_{covered} of those match a reconstructed servlet filter pattern "
+            f"(possibly filter-covered); {gc.get('no_matching_filter_pattern', 0)} match none._"
+        )
+    lines += ["", "<details>", "<summary>Handlers without the gate</summary>", ""]
+    lines += [
+        "| Method | Path | Filter pattern | Policy |",
+        "|--------|------|----------------|--------|",
+    ]
+    handlers = gc.get("handlers_without_gate", [])
+    for h in handlers[:_GATE_COVERAGE_RENDER_CAP]:
+        method = (h.get("method") or "").replace("|", "\\|")
+        path = (h.get("path") or "").replace("|", "\\|")
+        fpat = h.get("filter_pattern_match")
+        fcell = f"`{fpat}`" if fpat else "—"
+        policy = (h.get("policy") or "").replace("|", "\\|")
+        lines.append(f"| {method} | `{path}` | {fcell} | {policy} |")
+    if len(handlers) > _GATE_COVERAGE_RENDER_CAP:
+        lines.append(f"| … | _+{len(handlers) - _GATE_COVERAGE_RENDER_CAP} more_ | | |")
+    lines += ["", "</details>", ""]
+    if gc.get("note"):
+        lines.append(f"> {gc['note']}")
+    return lines
+
+
 @app.command("spring-audit")
 def spring_audit_cmd(
     path: Path = typer.Argument(
@@ -5804,7 +5949,14 @@ def impact_chain_cmd(
 
     _prog = Progress()
     _prog.start(f"analyzing impact ({len(file_list)} files)")
-    cir = ContextGraph.build(file_list, target).cir
+    # Reuse the shared context-cache CIR (same entry `cache warm` and `explain` use) so
+    # a warmed repo skips the expensive Java parse. Best-effort — any fault falls back to
+    # a fresh build, exactly as explain does, so impact-chain never breaks.
+    from sourcecode import context_cache as _ctxcache
+    try:
+        cir, _ = _ctxcache.get_or_build_cir(_resolve_repo_root(target), target, file_list)
+    except Exception:
+        cir = ContextGraph.build(file_list, target).cir
     _model = SpringSemanticModel.build(cir)
 
     if query_type == "events":
@@ -8215,6 +8367,22 @@ def cache_clear_cmd(
     typer.echo(f"Removed {removed} file(s).", err=True)
 
 
+def _warm_shared_cir(target: Path):
+    """Pre-populate the shared Canonical IR in the context cache (the entry explain and
+    other knowledge commands reuse). Returns the KnowledgeLookup, or None on any fault —
+    warming is best-effort and never fails the warm command."""
+    try:
+        from sourcecode.repository_ir import find_java_files as _fjf
+        from sourcecode import context_cache as _ctxcache
+        files = _fjf(target)
+        if not files:
+            return None
+        _cir, look = _ctxcache.get_or_build_cir(_resolve_repo_root(target), target, files)
+        return look
+    except Exception:
+        return None
+
+
 @cache_app.command("warm")
 def cache_warm_cmd(
     path: Path = typer.Argument(Path("."), help="Repository path to warm (default: current directory)"),
@@ -8245,6 +8413,18 @@ def cache_warm_cmd(
             typer.echo(result.stderr.strip(), err=True)
         raise typer.Exit(code=result.returncode)
 
+    # Also pre-populate the shared Canonical IR (context cache) — a DIFFERENT cache from
+    # the L1/L2 core cache warmed above. explain (and, going forward, other knowledge
+    # commands) reuse this CIR; without warming it here, the first explain rebuilds the
+    # expensive Java parse despite a "warm" cache (field-eval: explain MISS after warm).
+    _look = _warm_shared_cir(target)
+    if _look is not None:
+        typer.echo(
+            f"Shared CIR {'reused' if _look.hit else 'built'} "
+            "(explain/impact reuse this).",
+            err=True,
+        )
+
 
 @cache_app.command("freshness")
 def cache_freshness_cmd(
@@ -8386,6 +8566,23 @@ def _stderr_is_interactive() -> bool:
         return False
 
 
+def _force_utf8_streams() -> None:
+    """Force UTF-8 on stdout AND stderr so Unicode characters (em-dash, arrows, box
+    drawing) survive on Windows where the default console codec is cp1252 (BUG-1).
+
+    stderr matters as much as stdout: progress/warn/gap status text is emitted there,
+    and a cp1252 encoder turned its em-dashes into the replacement char (field-eval).
+    Best-effort and idempotent — a stream without ``reconfigure`` (already wrapped, or a
+    test buffer) is skipped silently.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            try:
+                stream.reconfigure(encoding="utf-8")
+            except Exception:
+                pass
+
+
 def main_entry() -> None:
     """CLI entry point for both the canonical ``ask`` command and the deprecated
     ``sourcecode`` compat alias — one implementation, no duplication.
@@ -8395,13 +8592,7 @@ def main_entry() -> None:
     can consume them as positional arguments (which would prevent subcommand
     routing for tokens like 'version' or 'config').
     """
-    # Force UTF-8 on stdout so Unicode characters (arrows, etc.) survive on
-    # Windows where the default console codec is cp1252 (BUG-1).
-    if hasattr(sys.stdout, "reconfigure"):
-        try:
-            sys.stdout.reconfigure(encoding="utf-8")
-        except Exception:
-            pass
+    _force_utf8_streams()
     # Deprecation notice when invoked through the legacy `sourcecode` alias.
     # One line, and only on an interactive terminal — pipes/agents that still call
     # `sourcecode` keep clean stderr (error envelopes are JSON on stderr), so the

{sourcecode-2.6.0 → sourcecode-2.6.2}/src/sourcecode/context_cache.py

@@ -620,6 +620,46 @@ def get_or_build_cir(
     return cir, KnowledgeLookup(hit=False, enabled=True, build_ms=build_ms)
 
 
+def peek_cir(
+    repo_root: Path,
+    *,
+    since: Optional[str] = None,
+) -> Optional[Any]:
+    """Return the shared ``CanonicalRepositoryIR`` **only if already cached**.
+
+    Get-only sibling of :func:`get_or_build_cir`: it never builds and never
+    writes. A caller that holds only a *bounded scope* of the repo (e.g. the
+    review-pr git-first path) must use this — routing a scoped build through
+    ``get_or_build_cir`` would store a truncated CIR under the repo-wide
+    knowledge key and poison every command that reads it. On a hit the caller
+    gets the full repo-wide CIR for free (O(1) reconstruction from raw IR); on
+    a miss it gets ``None`` and keeps its own scoped build, unshared.
+
+    The reconstructed CIR is left repo-consistent (``file_paths=None`` derives
+    the file list from the cached nodes, not from any caller scope).
+    """
+    from sourcecode.canonical_ir import ir_dict_to_canonical, validate_canonical_ir
+
+    cache = ContextCache.for_repo(repo_root)
+    if not cache.enabled:
+        return None
+    key = cache.knowledge_key(SCOPE_JAVA_CIR, options={"since": since} if since else None)
+    cached = cache.get(key)
+    if cached is None:
+        return None
+    raw = cached.payload.get("raw_ir")
+    if not isinstance(raw, dict):
+        return None
+    try:
+        cir = ir_dict_to_canonical(raw, file_paths=None)
+        # validate_canonical_ir returns a LIST of problems — empty means valid.
+        if not validate_canonical_ir(cir):
+            return cir
+    except Exception:
+        pass  # corrupt/incompatible payload — treat as miss
+    return None
+
+
 # ---------------------------------------------------------------------------
 # Module-level observability helper
 # ---------------------------------------------------------------------------