hypergumbo-lang-rust-analyzer 5.0.0__tar.gz

hypergumbo_lang_rust_analyzer-5.0.0/.gitignore

@@ -0,0 +1,97 @@
+# python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+
+# tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+
+# hypergumbo
+.hypergumbo/
+hypergumbo_capsule/
+hypergumbo.results.json
+hypergumbo.results.*.json
+slice.json
+slice.*.json
+
+# Agent configuration
+**/*.local.json
+**/*.local.md
+**/.claude/cache/
+**/.gemini/cache/
+**/.cursor/state/
+**/*-session/
+AUTONOMOUS_MODE.txt
+autonomous_intent.txt
+.agent/LOOP
+.agent/disabled.LOOP
+.agent/invariant-ledger.md
+# Per-session transcript pipeline (ADR-0018, per-session amendment 2026-04-08).
+# Each session writes per-session-keyed files. The .last_*/.second_to_last_*
+# global slots are written at session END by rotate-on-session-end.sh.
+.agent/.current_session_transcript.*.jsonl
+.agent/.current_injection_history.*.jsonl
+.agent/.transcript-sync.*.pid
+.agent/.transcript-sync-state.*.json
+.agent/.transcript-poll-state.*
+.agent/.transcript-injection-state.*.json
+.agent/.transcript-injection-state.*.lock
+.agent/.last_session_transcript.jsonl
+.agent/.second_to_last_transcript.jsonl
+.agent/.last_injection_history.jsonl
+.agent/.second_to_last_injection_history.jsonl
+.agent/.archived-transcripts/
+.agent/.rotation.lock
+# Legacy paths from before the per-session amendment (ignored for one-time
+# upgrade-cleanup safety; may be removed once no repo still has these).
+.agent/.current_session_transcript.jsonl
+.agent/.transcript-sync.pid
+.agent/.transcript-sync-state.json
+.agent/.transcript-poll-state
+.agent/.transcript-injection-state.json
+.agent/.transcript-session-token
+.agent/.current_injection_history.jsonl
+hook-canary.txt
+
+# Coverage
+.coverage
+.coverage.*
+htmlcov/
+coverage-report.txt
+
+# Snapshot reports (pytest-textual-snapshot)
+snapshot_report.html
+
+# Node (bats testing)
+node_modules/
+package.json
+package-lock.json
+
+# htrac-frontend: allow tracked JS/TS project files
+!packages/htrac-frontend/package.json
+!packages/htrac-frontend/package-lock.json
+
+# Hypergumbo cache
+.hypergumbo_cache/
+.ci/pytest-output.log
+.ci/pytest-results.xml
+.ci/smart-test-fallback.log
+
+# Tracker
+**/config.yaml
+!**/config.yaml.template
+.agent/.cache-*.db
+.agent/.sync-logs/
+.agent/.training-data.jsonl
+.agent/.training-data-selected.jsonl
+.agent/.training-data-v1-snapshot-*.jsonl
+.agent/.deprecated-datasets/
+.agent/finetuned-model/
+.agent/transcript-model.gguf

hypergumbo_lang_rust_analyzer-5.0.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: hypergumbo-lang-rust-analyzer
+Version: 5.0.0
+Summary: SCIP-backed Rust analyzer for hypergumbo (rust-analyzer integration)
+Author: Hypergumbo contributors
+License: AGPL-3.0-or-later
+Keywords: code-graph,rust,rust-analyzer,scip,static-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Requires-Dist: hypergumbo-core==5.0.0
+Requires-Dist: hypergumbo-lang-mainstream==5.0.0
+Description-Content-Type: text/markdown
+
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+# hypergumbo-lang-rust-analyzer
+
+SCIP-backed Rust analyzer for hypergumbo.
+
+This optional package integrates `rust-analyzer scip` output into hypergumbo,
+providing precise type-resolved symbols and call edges for Rust workspaces
+beyond what the tree-sitter `rust.py` analyzer can recover. It is designed
+as an opt-in alternative to `rust.py`, not a replacement.
+
+## Status
+
+Slice A: pure-Python translation surface from parsed SCIP `Index` bytes to
+`(symbols, edges)`. No live `rust-analyzer` invocation yet — that arrives
+in Slice B alongside analyzer-registry wiring and the opt-in flag
+(`HYPERGUMBO_RUST_ANALYZER` env var or `--backend rust-analyzer` CLI flag).
+
+## Why SCIP, not LSP
+
+Rust-analyzer emits SCIP with a single shot of `rust-analyzer scip` instead
+of requiring a long-lived LSP session. SCIP is slower than tree-sitter
+(~10× at every realistic size per WI-zakub), so this backend is opt-in and
+falls through to `rust.py` when unavailable or not requested.
+
+## Stable-ID parity
+
+`rust.py` and this analyzer both produce `stable_id`s via
+`hypergumbo_lang_mainstream.rust_scip.compute_rust_stable_id_from_source`,
+so cross-pass dedup works. Shared symbols carry the same `stable_id` under
+both backends; rust-analyzer-only symbols (e.g. trait-resolved method
+dispatch) extend the id space with SCIP-only suffixes.
+
+## Upstream shim
+
+Symbol / edge emission builds on `hypergumbo_core.scip.*`:
+
+- `scip_index_to_symbols` — `Document` walk → `Symbol` objects.
+- `scip_index_to_edges` — `SymbolInformation.relationships` → `Edge`s.
+- `scip_index_to_call_edges` — non-Definition `Occurrence` → calls / references
+  edges via span-enclosure resolution.
+
+Rust-analyzer's `Relationship` set is empty (per WI-zakub), so the primary
+edge source here is `scip_index_to_call_edges`.

hypergumbo_lang_rust_analyzer-5.0.0/README.md

@@ -0,0 +1,43 @@
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+# hypergumbo-lang-rust-analyzer
+
+SCIP-backed Rust analyzer for hypergumbo.
+
+This optional package integrates `rust-analyzer scip` output into hypergumbo,
+providing precise type-resolved symbols and call edges for Rust workspaces
+beyond what the tree-sitter `rust.py` analyzer can recover. It is designed
+as an opt-in alternative to `rust.py`, not a replacement.
+
+## Status
+
+Slice A: pure-Python translation surface from parsed SCIP `Index` bytes to
+`(symbols, edges)`. No live `rust-analyzer` invocation yet — that arrives
+in Slice B alongside analyzer-registry wiring and the opt-in flag
+(`HYPERGUMBO_RUST_ANALYZER` env var or `--backend rust-analyzer` CLI flag).
+
+## Why SCIP, not LSP
+
+Rust-analyzer emits SCIP with a single shot of `rust-analyzer scip` instead
+of requiring a long-lived LSP session. SCIP is slower than tree-sitter
+(~10× at every realistic size per WI-zakub), so this backend is opt-in and
+falls through to `rust.py` when unavailable or not requested.
+
+## Stable-ID parity
+
+`rust.py` and this analyzer both produce `stable_id`s via
+`hypergumbo_lang_mainstream.rust_scip.compute_rust_stable_id_from_source`,
+so cross-pass dedup works. Shared symbols carry the same `stable_id` under
+both backends; rust-analyzer-only symbols (e.g. trait-resolved method
+dispatch) extend the id space with SCIP-only suffixes.
+
+## Upstream shim
+
+Symbol / edge emission builds on `hypergumbo_core.scip.*`:
+
+- `scip_index_to_symbols` — `Document` walk → `Symbol` objects.
+- `scip_index_to_edges` — `SymbolInformation.relationships` → `Edge`s.
+- `scip_index_to_call_edges` — non-Definition `Occurrence` → calls / references
+  edges via span-enclosure resolution.
+
+Rust-analyzer's `Relationship` set is empty (per WI-zakub), so the primary
+edge source here is `scip_index_to_call_edges`.

hypergumbo_lang_rust_analyzer-5.0.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hypergumbo-lang-rust-analyzer"
+version = "5.0.0"
+description = "SCIP-backed Rust analyzer for hypergumbo (rust-analyzer integration)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "AGPL-3.0-or-later" }
+authors = [{ name = "Hypergumbo contributors" }]
+keywords = ["static-analysis", "code-graph", "rust", "rust-analyzer", "scip"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+]
+dependencies = [
+  "hypergumbo-core==5.0.0",
+  "hypergumbo-lang-mainstream==5.0.0",
+]
+
+[project.entry-points."hypergumbo.analyzers"]
+rust_analyzer = "hypergumbo_lang_rust_analyzer:ANALYZER_MODULES"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hypergumbo_lang_rust_analyzer"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "B", "C4", "S", "RUF"]
+ignore = ["E501", "S101", "S105", "S106", "S110", "RUF059", "RUF005", "B028"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S101", "S105", "S106", "S603", "S108", "E741", "F401", "F841", "RUF005"]

hypergumbo_lang_rust_analyzer-5.0.0/src/hypergumbo_lang_rust_analyzer/__init__.py

@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Hypergumbo SCIP-backed Rust analyzer.
+
+Slice A surface: :func:`translate_scip_to_hg` converts a serialized SCIP
+``Index`` blob into ``(symbols, edges)`` using the in-core shim modules
+plus the ``rust.py`` stable-id parity helper. Later slices add a live
+``rust-analyzer`` invocation, analyzer-registry wiring, and the opt-in
+flag machinery.
+"""
+
+from hypergumbo_lang_rust_analyzer.gate import (
+    ENV_VAR_NAME,
+    should_use_rust_analyzer_backend,
+)
+from hypergumbo_lang_rust_analyzer.graceful_degrade import (
+    try_analyze_with_rust_analyzer,
+)
+from hypergumbo_lang_rust_analyzer.invoke import (
+    RustAnalyzerError,
+    RustAnalyzerInvocationFailed,
+    RustAnalyzerNoOutput,
+    RustAnalyzerNotInstalled,
+    run_rust_analyzer_scip,
+)
+from hypergumbo_lang_rust_analyzer.translate import (
+    reassign_rust_stable_ids,
+    translate_scip_to_hg,
+)
+
+__version__ = "5.0.0"
+
+# Module paths for analyzer discovery via entry-points (ADR-0012 Step 1).
+# Importing the listed module triggers the @register_analyzer decorator.
+ANALYZER_MODULES = [
+    "hypergumbo_lang_rust_analyzer.analyzer",
+]
+
+__all__ = [
+    "ANALYZER_MODULES",
+    "ENV_VAR_NAME",
+    "RustAnalyzerError",
+    "RustAnalyzerInvocationFailed",
+    "RustAnalyzerNoOutput",
+    "RustAnalyzerNotInstalled",
+    "__version__",
+    "reassign_rust_stable_ids",
+    "run_rust_analyzer_scip",
+    "should_use_rust_analyzer_backend",
+    "translate_scip_to_hg",
+    "try_analyze_with_rust_analyzer",
+]

hypergumbo_lang_rust_analyzer-5.0.0/src/hypergumbo_lang_rust_analyzer/analyzer.py

@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Registered analyzer entry point for the SCIP-backed Rust backend (WI-duzul Slice C-final).
+
+This module threads the four primitives the earlier slices delivered
+into the hypergumbo-core analyzer-registry surface:
+
+1. :func:`hypergumbo_lang_rust_analyzer.gate.should_use_rust_analyzer_backend`
+   gates the whole function on the user's opt-in + binary availability.
+2. :func:`hypergumbo_lang_rust_analyzer.graceful_degrade.try_analyze_with_rust_analyzer`
+   handles the actual shell-out + SCIP → IR translation and returns
+   ``None`` on any of the WI-nohah fall-through conditions.
+3. Stable-id parity is already threaded inside
+   :func:`~hypergumbo_lang_rust_analyzer.translate.translate_scip_to_hg`,
+   so the Symbol objects this analyzer emits are deduplicable against
+   the tree-sitter ``rust.py`` analyzer's output when cross-pass dedup
+   runs (WI-bajuz).
+
+Registration
+------------
+Registered as analyzer name ``"rust_analyzer"`` (distinct from
+``rust.py``'s ``"rust"`` registration) so both analyzers coexist in
+the registry: ``rust.py`` remains the default, this one only produces
+output when the user opts in. Priority 45 (vs. the registry default
+50) so the SCIP pass runs slightly earlier when active — not load-
+bearing, just consistent with the "higher quality backend runs first"
+convention.
+
+When the opt-in gate returns False (the default for every session
+that hasn't set ``HYPERGUMBO_RUST_ANALYZER=1`` or passed
+``--backend rust-analyzer``), this analyzer returns an empty
+:class:`AnalysisResult` immediately. No file walk, no subprocess.
+``rust.py`` takes care of Rust analysis in that case.
+
+Provenance
+----------
+Successful SCIP-sourced Symbols already carry ``origin="scip"`` from
+:func:`~hypergumbo_core.scip.index.scip_index_to_symbols`, which
+preserves the provenance marker the WI-nohah description calls out.
+Downstream tools can filter on ``symbol.origin`` to trust-weight SCIP-
+derived symbols separately from tree-sitter-derived ones.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from hypergumbo_core.analyze.base import AnalysisResult
+from hypergumbo_core.analyze.registry import register_analyzer
+
+from hypergumbo_lang_rust_analyzer.gate import should_use_rust_analyzer_backend
+from hypergumbo_lang_rust_analyzer.graceful_degrade import (
+    try_analyze_with_rust_analyzer,
+)
+
+
+def _disk_source_reader(path: str) -> bytes | None:
+    """Read *path* from disk, swallowing I/O errors as ``None``.
+
+    The translate-layer's reassign_rust_stable_ids takes a caller-owned
+    reader callable so tests can inject in-memory fakes. Production
+    callers (this function) pass a disk-backed reader with exception
+    handling that matches the reassignment pass's contract: any read
+    failure maps to "source unavailable, skip parity rewrite" rather
+    than crashing the analyzer.
+    """
+    try:
+        return Path(path).read_bytes()
+    except (OSError, ValueError):  # pragma: no cover — pure defensive
+        return None
+
+
+@register_analyzer("rust_analyzer", priority=45)
+def analyze_rust_with_scip(repo_root: Path) -> AnalysisResult:
+    """Entry point for the SCIP-backed Rust analyzer.
+
+    Returns an empty result when the opt-in gate is False; otherwise
+    shells out to ``rust-analyzer scip <repo_root>``, translates the
+    emitted SCIP index into hypergumbo ``Symbol`` / ``Edge`` objects
+    (with rust.py stable_id parity), and returns them. All three
+    WI-nohah fall-through conditions are handled inside
+    :func:`try_analyze_with_rust_analyzer` and surface here as a
+    ``None`` return — this function swallows that to an empty
+    AnalysisResult so the registry treats "no SCIP run" identically
+    to "SCIP run produced nothing".
+
+    The registry calls this with ``repo_root`` being the workspace
+    root, which is exactly what ``cargo metadata`` + ``rust-analyzer
+    scip`` expect.
+    """
+    if not should_use_rust_analyzer_backend():
+        return AnalysisResult()
+
+    result = try_analyze_with_rust_analyzer(repo_root, _disk_source_reader)
+    if result is None:
+        return AnalysisResult()
+
+    symbols, edges = result
+    return AnalysisResult(symbols=symbols, edges=edges)

hypergumbo_lang_rust_analyzer-5.0.0/src/hypergumbo_lang_rust_analyzer/gate.py

@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Opt-in gate for the SCIP-backed Rust analyzer (WI-duzul Slice C gate).
+
+The rust-analyzer backend is opt-in because SCIP indexing is ~10x slower
+than tree-sitter at every realistic size (WI-zakub §4). Activating it
+requires two conditions:
+
+1. The user explicitly asked for it, either via the
+   ``HYPERGUMBO_RUST_ANALYZER`` environment variable (``"1"`` / ``"true"``
+   / ``"yes"``, case-insensitive) OR via the ``--backend rust-analyzer``
+   CLI flag (which the caller resolves to a string and passes in).
+2. The ``rust-analyzer`` binary is resolvable on ``PATH``
+   (:func:`hypergumbo_core.rust_analyzer_install.is_rust_analyzer_available`).
+
+:func:`should_use_rust_analyzer_backend` is the single decision point.
+The function is pure — ``environ`` / ``is_available`` are injected so
+tests can exercise every branch without mutating ``os.environ`` or
+shelling out to ``shutil.which``. Production callers pass ``None`` for
+both and pick up :data:`os.environ` + the real availability check.
+
+The split between this module and :mod:`graceful_degrade` is
+intentional: graceful-degrade answers "the user asked; did it work?"
+(handling runtime failures), while this gate answers "did the user
+actually ask?" (handling opt-in). Slice C's analyzer-registry wrapper
+chains them in that order.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Callable, Mapping, Optional
+
+ENV_VAR_NAME = "HYPERGUMBO_RUST_ANALYZER"
+
+# Strings accepted as "yes, opt in" (case-insensitive). Matches the
+# convention used by other tools' truthy-env-var parsing.
+_TRUTHY_VALUES = frozenset({"1", "true", "yes", "on"})
+
+# Backend-selector strings accepted by the --backend CLI flag. ``None`` /
+# empty string means "use the default (tree-sitter rust.py)".
+_RUST_ANALYZER_FLAG_VALUES = frozenset({"rust-analyzer", "rust_analyzer", "scip"})
+
+
+def _is_env_enabled(environ: Mapping[str, str]) -> bool:
+    """Return True when the opt-in env var resolves to a truthy value."""
+    raw = environ.get(ENV_VAR_NAME, "")
+    return raw.strip().lower() in _TRUTHY_VALUES
+
+
+def _is_flag_enabled(backend_flag: Optional[str]) -> bool:
+    """Return True when the caller-supplied ``--backend`` flag selects SCIP."""
+    if backend_flag is None:
+        return False
+    return backend_flag.strip().lower() in _RUST_ANALYZER_FLAG_VALUES
+
+
+def should_use_rust_analyzer_backend(
+    *,
+    backend_flag: Optional[str] = None,
+    environ: Optional[Mapping[str, str]] = None,
+    is_available: Optional[Callable[[], bool]] = None,
+) -> bool:
+    """Return True iff the rust-analyzer backend should run.
+
+    Two conditions must both hold:
+
+    - The user opted in, via either ``backend_flag`` or the
+      ``HYPERGUMBO_RUST_ANALYZER`` env var. Either one alone is enough.
+    - The ``rust-analyzer`` binary is resolvable on ``PATH`` (so
+      activating the backend cannot fail at spawn-time for a configuration
+      error the user can fix with ``hypergumbo install-rust-analyzer``).
+
+    When the user opted in but the binary is missing, this helper
+    returns False silently — the opt-in is honoured up to the limits of
+    what is installed, and the analyzer-registry wrapper falls through
+    to ``rust.py``. Callers that want to warn the user about the
+    mismatch should check the two conditions separately.
+    """
+    env = environ if environ is not None else os.environ
+    if not (_is_flag_enabled(backend_flag) or _is_env_enabled(env)):
+        return False
+
+    if is_available is None:
+        from hypergumbo_core.rust_analyzer_install import (
+            is_rust_analyzer_available,
+        )
+        is_available = is_rust_analyzer_available
+    return is_available()

hypergumbo_lang_rust_analyzer-5.0.0/src/hypergumbo_lang_rust_analyzer/graceful_degrade.py

@@ -0,0 +1,121 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Graceful-degrade orchestrator for the SCIP-backed Rust analyzer (WI-nohah).
+
+When a caller wants "use rust-analyzer if available, otherwise tell me
+to fall through to :mod:`hypergumbo_lang_mainstream.rust`", it should
+call :func:`try_analyze_with_rust_analyzer`. The helper returns
+``(symbols, edges)`` on the happy path and ``None`` on any of the
+three fall-through conditions WI-nohah enumerates:
+
+1. ``rust-analyzer`` is not resolvable on ``PATH`` (no install, or
+   install in a dir we don't scan).
+2. ``rust-analyzer scip`` exits non-zero / times out
+   (:class:`RustAnalyzerInvocationFailed`), or the workspace does not
+   produce an ``index.scip`` file (:class:`RustAnalyzerNoOutput` —
+   typically a ``cargo metadata`` error on a workspace with private
+   deps or an unusual target triple).
+3. The SCIP bytes decode fails
+   (:class:`google.protobuf.message.DecodeError`) — defensive; the
+   only known way to trip this is a truncated file from a killed
+   ``rust-analyzer`` process, so treat it identically to failure
+   mode 2.
+
+Returning ``None`` is the contract — the caller (WI-duzul Slice C's
+analyzer-registry wrapper) is responsible for the actual fall-through
+to ``rust.py``. Keeping the decision point pure lets the fall-through
+logic stay testable without mounting a real analyzer registry.
+
+The ``invoke`` and ``translate`` callables are injectable so tests can
+exercise every failure mode without shelling out to a real
+``rust-analyzer`` binary. Production callers pass ``None`` to pick up
+the default :func:`run_rust_analyzer_scip` /
+:func:`translate_scip_to_hg` surfaces.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+from typing import Callable, List, Optional, Tuple
+
+from google.protobuf.message import DecodeError
+
+from hypergumbo_core.ir import Edge, Symbol
+
+from .invoke import (
+    RustAnalyzerError,
+    run_rust_analyzer_scip,
+)
+from .translate import SourceReader, translate_scip_to_hg
+
+InvokeFn = Callable[..., bytes]
+TranslateFn = Callable[[bytes, SourceReader], Tuple[List[Symbol], List[Edge]]]
+
+# One-time log marker so repeated fall-through attempts don't spam the
+# user's terminal. A set because the helper may be called across
+# multiple workspaces in a single process (monorepo analysis).
+_LOGGED_FALLBACK: set[str] = set()
+
+
+def _reset_logged_fallback_for_tests() -> None:
+    """Clear the once-per-process log marker; test-only helper."""
+    _LOGGED_FALLBACK.clear()
+
+
+def try_analyze_with_rust_analyzer(
+    workspace: Path,
+    source_reader: SourceReader,
+    *,
+    invoke: Optional[InvokeFn] = None,
+    translate: Optional[TranslateFn] = None,
+    log: Optional[Callable[[str], None]] = None,
+) -> Optional[Tuple[List[Symbol], List[Edge]]]:
+    """Run rust-analyzer + SCIP translate on *workspace*, or ``None``.
+
+    The return type is intentionally ``None | (symbols, edges)`` rather
+    than raising — the caller wants the decision "was this a real
+    result, or should I fall through?" packaged as a single expression.
+    Every failure mode WI-nohah lists maps to ``None``; only a
+    successful invoke+translate produces a non-None return.
+
+    ``source_reader`` is forwarded to :func:`translate_scip_to_hg` for
+    the rust.py stable-id parity pass.
+
+    ``invoke`` defaults to :func:`run_rust_analyzer_scip`;
+    ``translate`` defaults to :func:`translate_scip_to_hg`. Both are
+    injected in tests to simulate each failure shape without spawning
+    a subprocess or constructing a SCIP fixture.
+
+    ``log`` defaults to a no-op; tests (and the future analyzer
+    registry wrapper) pass a real logger so the user sees one line
+    explaining why the backend degraded.
+    """
+    invoke_fn = invoke if invoke is not None else run_rust_analyzer_scip
+    translate_fn = translate if translate is not None else translate_scip_to_hg
+    emit = log if log is not None else (lambda _msg: None)
+
+    with tempfile.TemporaryDirectory(prefix="hg_rust_analyzer_") as tmpdir:
+        scratch = Path(tmpdir)
+        try:
+            scip_bytes = invoke_fn(workspace, cwd=scratch)
+        except RustAnalyzerError as exc:
+            key = f"{type(exc).__name__}:{workspace}"
+            if key not in _LOGGED_FALLBACK:
+                _LOGGED_FALLBACK.add(key)
+                emit(
+                    f"rust-analyzer backend unavailable for {workspace}: "
+                    f"{type(exc).__name__} — falling through to rust.py",
+                )
+            return None
+
+    try:
+        return translate_fn(scip_bytes, source_reader)
+    except DecodeError as exc:
+        key = f"DecodeError:{workspace}"
+        if key not in _LOGGED_FALLBACK:
+            _LOGGED_FALLBACK.add(key)
+            emit(
+                f"rust-analyzer SCIP decode failed for {workspace}: "
+                f"{exc} — falling through to rust.py",
+            )
+        return None