hypergumbo-lang-rust-analyzer 5.0.0__py3-none-any.whl

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/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/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/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

hypergumbo_lang_rust_analyzer/invoke.py

@@ -0,0 +1,165 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""Shell-out wrapper for ``rust-analyzer scip`` (WI-duzul Slice B-first).
+
+How It Works
+------------
+Calling ``rust-analyzer scip /path/to/workspace`` emits ``index.scip``
+in the current working directory. This module wraps that invocation in
+a single function, :func:`run_rust_analyzer_scip`, that:
+
+1. Confirms ``rust-analyzer`` is resolvable on ``PATH`` (or at the
+   explicit binary path the caller passes in).
+2. Invokes ``rust-analyzer scip <workspace>`` with stdout/stderr
+   captured, a configurable timeout, and a scratch cwd.
+3. Returns the emitted SCIP index as ``bytes`` suitable for feeding
+   straight into :func:`translate_scip_to_hg`.
+
+Failure modes are mapped to three dedicated exceptions so callers can
+discriminate between "binary not installed" (WI-nohah territory — fall
+through to ``rust.py``), "invocation failed or timed out" (genuine
+error — surface to the user), and "binary ran but produced no .scip
+file" (likely a cargo metadata error — surface with the captured
+stderr).
+
+Why This Design
+---------------
+* WI-zakub established that rust-analyzer SCIP indexing is 10x slower
+  than tree-sitter at every realistic size. The ``timeout`` argument
+  defaults to 600 seconds so an unexpectedly large workspace fails
+  visibly rather than hanging the analyzer pipeline.
+* A dedicated ``rust_analyzer_bin`` kwarg (default ``"rust-analyzer"``)
+  keeps the function testable without shell PATH mutations: tests
+  pass an absolute path to a fake script. Production callers use the
+  default to pick up the user's install.
+* The scratch ``cwd`` is supplied by the caller (typically a
+  ``tempfile.mkdtemp()``); this module does not own temporary
+  directories so callers can manage cleanup and reuse for caching if
+  they choose.
+
+Out of scope for this module (tracked under WI-duzul Slice C+):
+* Analyzer-registry wiring — ``RustAnalyzerAnalyzer`` class that hooks
+  into the analyzer base class and is registered at higher priority
+  than ``rust.py``.
+* The opt-in flag (``HYPERGUMBO_RUST_ANALYZER`` env var +
+  ``--backend rust-analyzer`` CLI flag) that gates whether the shell-
+  out fires at all.
+* Graceful-degrade when the binary is absent (WI-nohah). Callers
+  decide what to do with :class:`RustAnalyzerNotInstalled`.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess  # nosec B404 — required for rust-analyzer scip invocation
+from pathlib import Path
+from typing import Optional
+
+
+class RustAnalyzerError(Exception):
+    """Base class for :func:`run_rust_analyzer_scip` failures."""
+
+
+class RustAnalyzerNotInstalled(RustAnalyzerError):
+    """Raised when the ``rust-analyzer`` binary is not resolvable.
+
+    Callers should catch this and fall through to the tree-sitter
+    ``rust.py`` analyzer (WI-nohah). The message carries the binary
+    name the caller asked for so a misconfigured ``rust_analyzer_bin``
+    kwarg is visible in the error text.
+    """
+
+
+class RustAnalyzerInvocationFailed(RustAnalyzerError):
+    """Raised when the binary ran but exited non-zero or timed out.
+
+    The exception carries the captured stderr (best-effort; empty
+    bytes when the process was killed before producing any output) so
+    the caller can surface it to the user.
+    """
+
+    def __init__(self, message: str, stderr: bytes) -> None:
+        super().__init__(message)
+        self.stderr = stderr
+
+
+class RustAnalyzerNoOutput(RustAnalyzerError):
+    """Raised when the invocation succeeded but no ``index.scip`` was written.
+
+    This happens when ``rust-analyzer`` cannot parse the workspace
+    (e.g. missing ``Cargo.toml`` at the requested path, or a
+    ``cargo metadata`` error) but still exits 0. The captured stderr is
+    attached so the caller can surface the underlying cargo diagnostic.
+    """
+
+    def __init__(self, message: str, stderr: bytes) -> None:
+        super().__init__(message)
+        self.stderr = stderr
+
+
+def run_rust_analyzer_scip(
+    workspace: Path,
+    *,
+    cwd: Path,
+    rust_analyzer_bin: str = "rust-analyzer",
+    timeout_sec: float = 600.0,
+    which: Optional[callable] = None,  # type: ignore[valid-type]
+    runner: Optional[callable] = None,  # type: ignore[valid-type]
+) -> bytes:
+    """Run ``rust-analyzer scip`` on *workspace* and return the SCIP bytes.
+
+    ``cwd`` is the directory in which the subprocess runs; this is where
+    ``index.scip`` is written and subsequently read. Callers are
+    expected to pass a fresh empty directory (``tempfile.mkdtemp()`` is
+    the usual pattern) so the read is unambiguous.
+
+    ``rust_analyzer_bin`` is looked up via ``shutil.which`` unless it is
+    already an absolute path. The lookup is injectable via the ``which``
+    kwarg so tests can simulate a missing binary without mutating the
+    process environment.
+
+    ``runner`` is an injectable ``subprocess.run`` stand-in (signature
+    ``runner(cmd, *, cwd, capture_output, timeout) -> CompletedProcess``)
+    so tests can exercise the success / non-zero-exit / timeout /
+    no-output paths without actually spawning rust-analyzer.
+
+    Raises :class:`RustAnalyzerNotInstalled`, :class:`RustAnalyzerInvocationFailed`,
+    or :class:`RustAnalyzerNoOutput` per the module docstring.
+    """
+    resolve = which if which is not None else shutil.which
+    resolved = resolve(rust_analyzer_bin)
+    if resolved is None:
+        raise RustAnalyzerNotInstalled(
+            f"rust-analyzer binary not found on PATH "
+            f"(requested: {rust_analyzer_bin!r})",
+        )
+
+    # resolved comes from shutil.which (or caller-supplied absolute
+    # path); never shell=True; args are list-form.
+    run = runner if runner is not None else subprocess.run
+    cmd = [resolved, "scip", str(workspace)]
+    try:
+        completed = run(  # nosec B603
+            cmd,
+            cwd=str(cwd),
+            capture_output=True,
+            timeout=timeout_sec,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise RustAnalyzerInvocationFailed(
+            f"rust-analyzer scip timed out after {timeout_sec}s",
+            exc.stderr or b"",
+        ) from exc
+
+    if completed.returncode != 0:
+        raise RustAnalyzerInvocationFailed(
+            f"rust-analyzer scip exited {completed.returncode}",
+            completed.stderr or b"",
+        )
+
+    index_path = cwd / "index.scip"
+    if not index_path.is_file():
+        raise RustAnalyzerNoOutput(
+            "rust-analyzer scip exited 0 but produced no index.scip",
+            completed.stderr or b"",
+        )
+    return index_path.read_bytes()

hypergumbo_lang_rust_analyzer/translate.py

@@ -0,0 +1,170 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""SCIP bytes → hypergumbo ``(Symbol, Edge)`` translation with rust.py parity.
+
+How It Works
+------------
+``rust-analyzer scip`` emits a Protobuf-encoded ``scip.Index`` file
+describing every defined symbol, every reference, and every
+relationship in a Rust workspace. This module wraps the hypergumbo-core
+SCIP shim (``hypergumbo_core.scip.*``) with two things the generic
+shim cannot do on its own:
+
+1. **Stable-ID parity with rust.py.** The core shim fills
+   ``Symbol.stable_id`` with the raw SCIP symbol string. That string is
+   correct for cross-SCIP-pass dedup but does not match the
+   signature-derived stable_id rust.py computes for the same function
+   in the same source file. Without reassignment, enabling this
+   backend on a cached analysis double-counts every Rust symbol.
+   :func:`reassign_rust_stable_ids` replaces the SCIP-derived
+   ``stable_id`` with the rust.py-equivalent one whenever a Rust
+   function span can be located in the caller-provided source reader,
+   using
+   :func:`hypergumbo_lang_mainstream.rust_scip.compute_rust_stable_id_from_source`.
+   Non-Rust Symbols (SCIP can carry multiple languages in one index),
+   non-function Rust Symbols (structs, modules, constants — rust.py
+   has no signature-level parity for these), and Symbols whose source
+   cannot be read pass through unchanged.
+
+2. **One-shot translate.** :func:`translate_scip_to_hg` bundles the
+   three core shim calls (``scip_index_to_symbols``,
+   ``scip_index_to_edges``, ``scip_index_to_call_edges``) with the
+   parity reassignment so Slice-B's analyzer wrapper can consume a
+   single entry point.
+
+Why This Design
+---------------
+WI-zakub (2026-04-17 mini trial) established that rust-analyzer leaves
+``SymbolInformation.relationships`` empty; the primary edge source is
+therefore non-Definition ``Occurrence``s routed through
+``scip_index_to_call_edges``. Both ``scip_index_to_edges`` and
+``scip_index_to_call_edges`` are still called here — the former is
+zero-cost when the relationship set is empty, and keeping both in the
+pipeline lets the translator also work on SCIP indexes produced by
+other tools (scip-python, scip-java) that do populate relationships.
+
+The ``source_reader`` callable is a caller-owned I/O boundary:
+production callers pass a function that reads ``path`` bytes from the
+indexed workspace; tests pass a dict-backed fake so the whole
+translate path can be exercised without filesystem access. Reader
+failures (``OSError``, ``FileNotFoundError``, arbitrary exceptions)
+degrade to "skip this symbol's reassignment" rather than aborting the
+whole translate — the SCIP-derived ``stable_id`` remains as a
+best-effort fallback.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Iterable, List, Optional
+
+from hypergumbo_core.ir import Edge, Symbol
+from hypergumbo_core.scip._generated import scip_pb2
+from hypergumbo_core.scip.calls import scip_index_to_call_edges
+from hypergumbo_core.scip.edges import scip_index_to_edges
+from hypergumbo_core.scip.index import scip_index_to_symbols
+from hypergumbo_lang_mainstream.rust_scip import (
+    compute_rust_stable_id_from_source,
+)
+
+
+SourceReader = Callable[[str], Optional[bytes]]
+
+
+def _read_source(source_reader: SourceReader, path: str) -> Optional[bytes]:
+    """Invoke *source_reader*, swallowing I/O errors as ``None``.
+
+    Reader exceptions (FileNotFoundError, OSError, or anything the
+    caller's implementation chooses to raise) map to "source
+    unavailable, skip reassignment" — the translate pass still emits
+    the Symbol with the SCIP-derived stable_id rather than dropping it.
+    """
+    try:
+        return source_reader(path)
+    except (OSError, ValueError):
+        return None
+
+
+def reassign_rust_stable_ids(
+    symbols: Iterable[Symbol],
+    source_reader: SourceReader,
+) -> List[Symbol]:
+    """Return *symbols* with Rust function ``stable_id``s rust.py-compatible.
+
+    For each input Symbol, the reassignment applies only when:
+
+    - ``language == "rust"``
+    - ``kind == "function"`` or ``kind == "method"``
+    - ``span`` is present (SCIP Definition Occurrences always carry one)
+    - ``source_reader(path)`` returns bytes
+    - ``compute_rust_stable_id_from_source`` finds the function at the
+      span and returns a non-None stable_id
+
+    All other Symbols (non-Rust, non-function, span-less, source-less,
+    or parity-lookup-failed) pass through with their original
+    ``stable_id`` untouched. The return value is a new list — inputs
+    are not mutated.
+    """
+    reassigned: List[Symbol] = []
+    source_cache: dict[str, Optional[bytes]] = {}
+    for sym in symbols:
+        new_sym = sym
+        if (
+            sym.language == "rust"
+            and sym.kind in {"function", "method"}
+            and sym.span is not None
+            and sym.path
+        ):
+            if sym.path not in source_cache:
+                source_cache[sym.path] = _read_source(source_reader, sym.path)
+            source = source_cache[sym.path]
+            if source is not None:
+                parity = compute_rust_stable_id_from_source(
+                    source, sym.span.start_line, sym.span.end_line,
+                )
+                if parity is not None:
+                    new_sym = Symbol(
+                        id=sym.id,
+                        name=sym.name,
+                        kind=sym.kind,
+                        language=sym.language,
+                        path=sym.path,
+                        span=sym.span,
+                        origin=sym.origin,
+                        stable_id=parity,
+                        signature=sym.signature,
+                        meta=sym.meta,
+                    )
+        reassigned.append(new_sym)
+    return reassigned
+
+
+def translate_scip_to_hg(
+    scip_bytes: bytes,
+    source_reader: SourceReader,
+) -> tuple[List[Symbol], List[Edge]]:
+    """Parse *scip_bytes* and return ``(symbols, edges)`` with parity.
+
+    The three core SCIP shim passes are invoked in order:
+
+    1. :func:`scip_index_to_symbols` to build the Symbol list.
+    2. :func:`reassign_rust_stable_ids` to overwrite Rust function
+       ``stable_id`` fields with rust.py-compatible values.
+    3. :func:`scip_index_to_edges` for Relationship-derived edges.
+    4. :func:`scip_index_to_call_edges` for Occurrence-ref edges via
+       span-enclosure resolution.
+
+    The Edge list is the concatenation of the two edge sources; callers
+    expecting a deduplicated edge set should run the standard
+    ``deduplicate_edges`` pass themselves (not done here — translate
+    preserves the shim outputs verbatim so downstream passes can see
+    the raw signal and ``deduplicate_edges`` is the only place the
+    dedup rule lives).
+    """
+    index = scip_pb2.Index()
+    index.ParseFromString(scip_bytes)
+    symbols = reassign_rust_stable_ids(
+        scip_index_to_symbols(index), source_reader,
+    )
+    edges: List[Edge] = []
+    edges.extend(scip_index_to_edges(index))
+    edges.extend(scip_index_to_call_edges(index))
+    return symbols, edges

hypergumbo_lang_rust_analyzer-5.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+hypergumbo_lang_rust_analyzer/__init__.py,sha256=7e2d2EwdsWlN0yDYvYxyWvmVfVtqc_J69rA0aWcmfvg,1513
+hypergumbo_lang_rust_analyzer/analyzer.py,sha256=_HVAsSmWeMuYV9y5qhHcqV6-oqSQZSEG7lglWBZSQdA,4224
+hypergumbo_lang_rust_analyzer/gate.py,sha256=jw5sK4FDFQHvNSp8WpShS1lgHy5aM86n3lCPHTPoJ4E,3714
+hypergumbo_lang_rust_analyzer/graceful_degrade.py,sha256=QacACz2Yuakjje5GPAkizgpni3z5w-qrtgSqnY38PgI,4912
+hypergumbo_lang_rust_analyzer/invoke.py,sha256=HeyDkfxVN-_ztoX5KqSZRB_oVAwjv0blRZnZ5yHV-Ok,6569
+hypergumbo_lang_rust_analyzer/translate.py,sha256=_mJPxZmThaKwZUw5iC3xshkF-BdEhNrBtypuxCJezgA,7080
+hypergumbo_lang_rust_analyzer-5.0.0.dist-info/METADATA,sha256=twHOxfBPg1u36WgjbQ1SvRLzQlOyEOQTGwQ46X2cYic,2517
+hypergumbo_lang_rust_analyzer-5.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+hypergumbo_lang_rust_analyzer-5.0.0.dist-info/entry_points.txt,sha256=zJQjXxwrzFMhVWkXb5UbF8RzjcgnrdcOWepL6oewJog,86
+hypergumbo_lang_rust_analyzer-5.0.0.dist-info/RECORD,,

hypergumbo_lang_rust_analyzer-5.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hypergumbo_lang_rust_analyzer-5.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[hypergumbo.analyzers]
+rust_analyzer = hypergumbo_lang_rust_analyzer:ANALYZER_MODULES