sourcecode 2.6.1__tar.gz → 2.6.3__tar.gz

{sourcecode-2.6.1 → sourcecode-2.6.3}/CHANGELOG.md

@@ -1,5 +1,87 @@
 # Changelog
 
+## [2.6.3] — 2026-07-24
+
+**`ask verify-edit` — the in-loop semantic diff gate lands (the read-context → write-loop
+verification pivot), plus a content-addressed parse cache and one field-test correctness
+fix.** New user-facing capability; no change to any existing command's contract. Suite:
+**3731 passed, 5 skipped, 1 deselected** (the deselected chunker test is a pre-existing
+external-fixture flake).
+
+### Added
+
+- **`ask verify-edit` — a deterministic, in-loop semantic diff gate.** Verdict over the
+  diff of the working tree against HEAD, built for the agent write-loop and CI. Each axis
+  is a diff over two Canonical IRs (working vs a throwaway `git worktree` checkout of
+  HEAD), reporting only regressions the edit **introduced** — pre-existing debt never
+  fails an unrelated commit:
+  - `contract_broken` — a public symbol removed, its visibility downgraded, or (when
+    unambiguous) its signature changed.
+  - `tx_boundary_changed` — a `@Transactional` proxy boundary broken (e.g. a
+    `@Transactional` method flipped `public` → `private` → a silently inert CGLIB proxy).
+  - `security_delta` — a security-posture finding the edit introduced.
+  - `new_orphan_bean` — a bean that lost all its injection wiring.
+  - `custom_rule_violated` — the client's own invariants, declared in
+    `.ask/verify-rules.json` (below).
+  - plus an informational `blast_radius` (entry points reachable from the changed files).
+
+  Exit codes under `--ci` (default): `0` pass, `1` break, `2` unverified (a blocking axis
+  could not be computed — never a silent pass). JSON verdict to stdout, prose to stderr.
+- **Custom domain rules (`.ask/verify-rules.json`).** Declare invariants of *your*
+  codebase and have `verify-edit` enforce them — `forbidden_edge` ("no `@RestController`
+  injects a `*DaoJpa`") and `require_endpoint_security` ("every `/payroll` endpoint
+  requires role X"). Selectors reason by structure (annotation / fqn-regex / kind /
+  modifier / source-file); the concrete names are config data, never branched on in the
+  engine. Zero-config: no rules file ⇒ nothing to enforce; a malformed ruleset degrades
+  to *unverified*, never a silent pass.
+- **MCP tool `verify_edit`** (report-only) so an agent can call the gate after each edit,
+  and **`ask verify-edit --install-hook pre-commit|pre-push`** to install a git hook that
+  runs the same binary and blocks on a break (bypass with `git --no-verify`).
+- **Content-addressed per-file parse cache.** Symbol extraction and the body-fact bundle
+  of an unchanged file are pure functions of its bytes, so they are memoised by a content
+  hash — a 1-file edit re-parses 1 file, not the whole repo. It **never changes the
+  result** (a miss just re-parses; the CIR is byte-identical whether the cache is cold,
+  warm, or disabled) and it accelerates every CIR consumer, not only `verify-edit`.
+  Measured on a 1076-file repo: the working-CIR build drops ~59% warm.
+
+### Fixed
+
+- **`verify-edit` contract axis no longer false-breaks on overloaded methods** (found in
+  a field-test of a real repo with a clean tree). An fqn carries no signature, so
+  overloaded methods/constructors share one id across several graph nodes; the axis now
+  aggregates visibility per fqn as *any overload public* instead of picking an
+  order-dependent representative, so a public name that also has a non-public overload no
+  longer reads as a downgrade on an unchanged tree.
+
+## [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

{sourcecode-2.6.1 → sourcecode-2.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 2.6.1
+Version: 2.6.3
 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.1 → sourcecode-2.6.3}/pyproject.toml

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

{sourcecode-2.6.1 → sourcecode-2.6.3}/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.1"
+__version__ = "2.6.3"

{sourcecode-2.6.1 → sourcecode-2.6.3}/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.1 → sourcecode-2.6.3}/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)
@@ -253,6 +254,8 @@ _SUBCOMMANDS: frozenset[str] = frozenset(
         "explain",
         # Spring Boot 2→3 migration readiness
         "migrate-check",
+        # In-loop semantic diff gate (working tree vs HEAD)
+        "verify-edit",
         # Native file rename (BLOCKER-A)
         "rename-class",
         # Large file semantic chunking (BLOCKER-B)
@@ -725,6 +728,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 +790,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 +840,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 +1511,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 +1618,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 +1811,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 +5388,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 +5421,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 +5431,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(
@@ -5533,6 +5680,85 @@ def spring_audit_cmd(
         raise typer.Exit(code=1)
 
 
+# ── verify-edit: in-loop semantic diff gate ───────────────────────────────────
+
+
+@app.command("verify-edit")
+def verify_edit_cmd(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository path (default: current directory). Diffs the working tree vs HEAD.",
+    ),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o", help="Write the verdict JSON to a file instead of stdout."
+    ),
+    format: str = typer.Option("json", "--format", help="Output format: json."),
+    ci: bool = typer.Option(
+        True,
+        "--ci/--no-ci",
+        help="Exit non-zero on a broken/unverified verdict (default on — for gates and hooks).",
+    ),
+    install_hook: Optional[str] = typer.Option(
+        None,
+        "--install-hook",
+        help="Install a git hook (pre-commit|pre-push) that runs this gate, then exit. Does not verify.",
+    ),
+) -> None:
+    """Semantic diff gate: did the working-tree edits change runtime behavior?
+
+    Deterministic, in-loop verdict over the diff of the working tree against HEAD:
+    public contract, @Transactional proxy boundary, security surface, bean wiring,
+    custom domain rules, and blast radius. Built for the agent write-loop (MCP) and
+    git hooks. Only regressions the edit INTRODUCED (vs HEAD) block — pre-existing
+    debt never fails an unrelated commit.
+
+    Custom rules: drop a `.ask/verify-rules.json` at the repo root to enforce your own
+    invariants (e.g. "no @RestController injects a *DaoJpa", "every /payroll endpoint
+    requires role X"). They gate the same way as the built-in axes.
+
+    Exit codes (with --ci, the default): 0 = pass, 1 = break (a blocking axis proved
+    a regression), 2 = unverified (a blocking axis could not be computed — never a
+    silent pass) or the path is not a git repository.
+
+    Examples:
+      ask verify-edit                       # verify the current working tree
+      ask verify-edit /path/to/repo
+      ask verify-edit --no-ci               # always exit 0 (report only)
+      ask verify-edit --install-hook pre-commit
+    """
+    from sourcecode import verify_edit as _ve
+
+    if install_hook is not None:
+        try:
+            _hook_path = _ve.install_git_hook(path, install_hook)
+        except _ve.VerifyEditError as exc:
+            _emit_error_json(
+                INVALID_INPUT_CODE,
+                str(exc),
+                hint=f"Choose a hook type: {' | '.join(_ve.HOOK_TYPES)}. The repo must be a git repository.",
+            )
+            raise typer.Exit(code=2)
+        typer.echo(f"Installed verify-edit {install_hook} hook: {_hook_path}", err=True)
+        typer.echo(f"It runs `ask verify-edit --ci` and blocks on a break; bypass with git --no-verify.", err=True)
+        return
+
+    try:
+        v = _ve.verify_edit(path)
+    except _ve.VerifyEditError as exc:
+        _emit_error_json(
+            INVALID_INPUT_CODE,
+            str(exc),
+            hint="verify-edit needs a git repository with a HEAD commit (it diffs the working tree vs HEAD).",
+        )
+        raise typer.Exit(code=2 if ci else 0)
+
+    output = _serialize_dict(v.to_dict(), format)
+    _emit_command_output(output, output_path, False,
+                         success_msg=f"verify-edit verdict written to {output_path}")
+    if ci and v.exit_code != 0:
+        raise typer.Exit(code=v.exit_code)
+
+
 # ── Spring Boot Migration Check ───────────────────────────────────────────────
 
 
@@ -5804,7 +6030,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 +8448,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 +8494,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 +8647,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 +8673,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.1 → sourcecode-2.6.3}/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
 # ---------------------------------------------------------------------------