code-atlas-forge 1.1.0__py3-none-any.whl

code_atlas/resolvers/lsp/lifecycle.py

@@ -0,0 +1,251 @@
+"""Ciclo de vida do cliente LSP (lf-0018).
+
+spawn → initialize (handshake) → capability negotiation → requests com
+timeout + ``$/cancelRequest`` → shutdown/exit → cleanup de processo.
+Um servidor que trava ou morre vira ``unavailable`` — nunca bloqueia o
+pipeline de indexação.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import itertools
+import threading
+from dataclasses import dataclass, field
+from typing import Any
+
+from code_atlas.resolvers.lsp.spawn import (
+    LspProcess,
+    LspServerSpec,
+    SpawnError,
+    release_server,
+    spawn_server,
+)
+from code_atlas.resolvers.lsp.transport import (
+    JsonRpcTransport,
+    TransportError,
+)
+
+INIT_TIMEOUT_S = 15.0
+SHUTDOWN_TIMEOUT_S = 5.0
+
+# métodos que o Atlas usa — cada um só é chamado se o servidor anunciar
+_METHOD_TO_CAP = {
+    "textDocument/definition": "definitionProvider",
+    "textDocument/references": "referencesProvider",
+    "textDocument/documentSymbol": "documentSymbolProvider",
+    "workspace/symbol": "workspaceSymbolProvider",
+}
+
+
+class LspError(RuntimeError):
+    """Falha de protocolo/servidor — sempre diagnóstico, nunca crash."""
+
+
+@dataclass
+class ServerCapabilities:
+    """Subconjunto negociado do resultado de ``initialize``."""
+
+    definition: bool = False
+    references: bool = False
+    document_symbol: bool = False
+    workspace_symbol: bool = False
+    server_name: str = ""
+    server_version: str = ""
+
+    def supports(self, method: str) -> bool:
+        cap = _METHOD_TO_CAP.get(method)
+        return bool(getattr(self, {
+            "definitionProvider": "definition",
+            "referencesProvider": "references",
+            "documentSymbolProvider": "document_symbol",
+            "workspaceSymbolProvider": "workspace_symbol",
+        }.get(cap or "", ""), False)) if cap else False
+
+
+@dataclass
+class LspClient:
+    """Cliente stdio de um servidor LSP (um por spec habilitada)."""
+
+    spec: LspServerSpec
+    _proc: LspProcess | None = field(default=None, init=False)
+    _transport: JsonRpcTransport | None = field(default=None, init=False)
+    _ids: itertools.count[int] = field(
+        default_factory=lambda: itertools.count(1), init=False)
+    _caps: ServerCapabilities = field(
+        default_factory=ServerCapabilities, init=False)
+    _available: bool = field(default=False, init=False)
+    _lock: threading.Lock = field(default_factory=threading.Lock,
+                                  init=False)
+    # textDocument/publishDiagnostics por uri (lf-0029)
+    _diagnostics: dict[str, list[dict[str, Any]]] = field(
+        default_factory=dict, init=False)
+
+    # -- ciclo de vida ----------------------------------------------------
+
+    def start(self) -> None:
+        """Spawn + handshake initialize; falhas → unavailable."""
+        try:
+            self._proc = spawn_server(self.spec)
+        except SpawnError as exc:
+            raise LspError(str(exc)) from exc
+        assert self._proc.stdin and self._proc.stdout
+        self.attach(JsonRpcTransport(self._proc.stdout, self._proc.stdin))
+
+    def attach(self, transport: JsonRpcTransport) -> None:
+        """Conecta um transporte pronto (testes injetam pipes in-process)
+        e faz o handshake initialize."""
+        self._transport = transport
+        try:
+            self.handshake()
+        except (LspError, TimeoutError, TransportError):
+            self.close()
+            raise
+
+    def handshake(self) -> None:
+        """``initialize`` → negocia capabilities → ``initialized``."""
+        result = self.request(
+            "initialize",
+            {
+                "processId": None,
+                "rootUri": self.spec.root_uri,
+                "capabilities": {},
+            },
+            timeout=min(INIT_TIMEOUT_S, self.spec.request_timeout_s),
+        )
+        self._parse_initialize(result)
+        self.notify("initialized", {})
+        self._available = True
+
+    def _parse_initialize(self, result: Any) -> None:
+        caps = (result or {}).get("capabilities", {})
+        info = (result or {}).get("serverInfo", {})
+        self._caps = ServerCapabilities(
+            definition=bool(caps.get("definitionProvider")),
+            references=bool(caps.get("referencesProvider")),
+            document_symbol=bool(caps.get("documentSymbolProvider")),
+            workspace_symbol=bool(caps.get("workspaceSymbolProvider")),
+            server_name=info.get("name", self.spec.name),
+            server_version=info.get("version", ""),
+        )
+
+    @property
+    def available(self) -> bool:
+        """Servidor respondendo: handshake feito + transporte vivo +
+        processo rodando (quando há processo real)."""
+        if not self._available or self._transport is None:
+            return False
+        if self._proc is not None:
+            return self._proc.poll() is None
+        return True  # transporte injetado (testes)
+
+    @property
+    def capabilities(self) -> ServerCapabilities:
+        return self._caps
+
+    # -- requests ---------------------------------------------------------
+
+    def request(
+        self, method: str, params: dict[str, Any] | None = None,
+        timeout: float | None = None,
+    ) -> Any:
+        """Request com timeout obrigatório + cancelamento LSP."""
+        if self._transport is None:
+            raise LspError("transport not started")
+        timeout = timeout or self.spec.request_timeout_s
+        rid = next(self._ids)
+        payload: dict[str, Any] = {"jsonrpc": "2.0", "id": rid, "method": method}
+        if params is not None:
+            payload["params"] = params
+        try:
+            self._transport.send(payload)
+            while True:
+                msg = self._transport.recv(timeout)
+                if msg.is_notification or msg.request_id != rid:
+                    self._capture_notification(msg)
+                    continue  # notificações/server-requests não correlacionados
+                if msg.error:
+                    raise LspError(
+                        f"{method}: rpc error {msg.error.get('code')}: "
+                        f"{msg.error.get('message')}")
+                return msg.result
+        except TimeoutError:
+            self._cancel(rid)
+            raise
+        except TransportError as exc:
+            self._available = False  # stream morreu → crash detectado
+            raise LspError(f"{method}: transport died: {exc}") from exc
+
+    def notify(self, method: str, params: dict[str, Any] | None = None) -> None:
+        if self._transport is None:
+            return
+        payload: dict[str, Any] = {"jsonrpc": "2.0", "method": method}
+        if params is not None:
+            payload["params"] = params
+        try:
+            self._transport.send(payload)
+        except TransportError:
+            self._available = False
+
+    def _cancel(self, rid: int) -> None:
+        """``$/cancelRequest`` — cancelamento real LSP após timeout."""
+        self.notify("$/cancelRequest", {"id": rid})
+
+    def _capture_notification(self, msg: Any) -> None:
+        """lf-0029: ``textDocument/publishDiagnostics`` é a única
+        notificação que guardamos — por uri, para o adapter anexar."""
+        method = getattr(msg, "method", "")
+        if method == "textDocument/publishDiagnostics":
+            params = getattr(msg, "params", None) or {}
+            uri = params.get("uri")
+            if isinstance(uri, str):
+                self._diagnostics[uri] = list(
+                    params.get("diagnostics") or [])
+
+    def diagnostics_for(self, uri: str) -> list[dict[str, Any]]:
+        """Diagnostics publicados para o documento (se o server envia)."""
+        return list(self._diagnostics.get(uri, ()))
+
+    def document_symbol(self, uri: str) -> Any:
+        """``textDocument/documentSymbol`` — só se capability anunciada."""
+        if not self._caps.document_symbol:
+            raise LspError("documentSymbolProvider not advertised")
+        return self.request(
+            "textDocument/documentSymbol",
+            {"textDocument": {"uri": uri}})
+
+    def restart(self) -> None:
+        """lf-0029: recovery pós-crash — fecha tudo e refaz
+        spawn+handshake. Bounded: quem chama decide tentativas."""
+        self.close()
+        self.start()
+
+    def shutdown(self) -> None:
+        """Sequência ordenada shutdown → exit."""
+        if self._transport is None:
+            return
+        with contextlib.suppress(LspError, TimeoutError, TransportError):
+            self.request("shutdown", None, timeout=SHUTDOWN_TIMEOUT_S)
+        self.notify("exit")
+        self.close()
+
+    def close(self) -> None:
+        """Fecha transporte e mata processo (zombie cleanup)."""
+        self._available = False
+        if self._transport is not None:
+            self._transport.close()
+            self._transport = None
+        self._diagnostics.clear()
+        if self._proc is not None:
+            release_server(self._proc)
+            self._proc = None
+
+
+def make_client(spec: LspServerSpec) -> LspClient | None:
+    """Fábrica segura: spec desabilitado → None; spawn/handshake falho →
+    ``LspError`` (caller vira diagnóstico)."""
+    if not spec.enabled:
+        return None
+    client = LspClient(spec)
+    client.start()
+    return client

code_atlas/resolvers/lsp/spawn.py

@@ -0,0 +1,92 @@
+"""Único site de subprocess para servidores LSP (lf-0018).
+
+Mesmo padrão de confinamento de ``gitbin.py``: argv sem shell, binário
+resolvido via ``shutil.which``, comando NUNCA derivado do conteúdo do
+repositório indexado — somente de configuração explícita do usuário
+(``config.toml [resolvers.lsp]``). Este arquivo está na whitelist do
+teste de confinamento de subprocess.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from dataclasses import dataclass
+
+# Guardrails de recursos (documentados no review):
+MAX_LSP_SERVERS = 4            # processos simultâneos máximos
+SPAWN_ENV_PREFIXES = ("PATH=", "HOME=", "LANG=", "LC_", "SYSTEMROOT=",
+                      "WINDIR=", "TEMP=", "TMP=")
+
+_active_count = 0
+
+
+# Tipo do processo spawnado — lifecycle anota via este alias (o audit
+# confina `import subprocess` a este arquivo).
+LspProcess = subprocess.Popen[bytes]
+
+
+class SpawnError(RuntimeError):
+    """Binário ausente, limite atingido ou falha de spawn."""
+
+
+@dataclass(frozen=True)
+class LspServerSpec:
+    """Configuração explícita de um servidor LSP (opt-in do usuário)."""
+
+    name: str
+    cmd: tuple[str, ...]            # argv completo — nunca do repo
+    languages: frozenset[str]       # linguagens cobertas ("" = qualquer)
+    root_uri: str = "file:///"      # rootUri do initialize
+    enabled: bool = False           # opt-in: desligado por padrão
+    request_timeout_s: float = 10.0
+
+
+def _leak_env() -> dict[str, str]:
+    """Ambiente minimizado — só variáveis necessárias para stdio."""
+    import os
+
+    env: dict[str, str] = {}
+    for k, v in os.environ.items():
+        if any((k.startswith(p.rstrip("=")) and k == p.rstrip("=")) or
+               k.startswith(p) for p in SPAWN_ENV_PREFIXES):
+            env[k] = v
+    return env
+
+
+def spawn_server(spec: LspServerSpec) -> subprocess.Popen[bytes]:
+    """Spawna o servidor stdio; nunca levanta por binário ausente —
+    devolve erro tipado via ``SpawnError``."""
+    global _active_count
+    if not spec.cmd:
+        raise SpawnError(f"lsp {spec.name}: empty command")
+    binary = shutil.which(spec.cmd[0])
+    if binary is None:
+        raise SpawnError(f"lsp {spec.name}: binary {spec.cmd[0]!r} not found")
+    if _active_count >= MAX_LSP_SERVERS:
+        raise SpawnError(
+            f"lsp: server limit {MAX_LSP_SERVERS} reached")
+    try:
+        proc = subprocess.Popen(
+            [binary, *spec.cmd[1:]],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            env=_leak_env(),
+        )
+    except OSError as exc:
+        raise SpawnError(f"lsp {spec.name}: spawn failed: {exc}") from exc
+    _active_count += 1
+    return proc
+
+
+def release_server(proc: subprocess.Popen[bytes]) -> None:
+    """Encerra e reaps o processo (sem zombies)."""
+    global _active_count
+    try:
+        if proc.poll() is None:
+            proc.kill()
+        proc.wait(timeout=5)
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+    _active_count = max(0, _active_count - 1)

code_atlas/resolvers/lsp/transport.py

@@ -0,0 +1,240 @@
+"""Transporte JSON-RPC 2.0 sobre stdio com framing Content-Length (lf-0018).
+
+Funciona sobre qualquer par (reader, writer) de streams com ``fileno()``
+— pipes reais de um processo filho ou pipes in-process dos testes.
+Regras de segurança:
+
+- Leitura via ``select`` sobre o fd + ``os.read`` — a thread daemon
+  acorda a cada 100ms para conferir o flag de fechamento: ``close()``
+  nunca depende do lock de um BufferedReader bloqueado (deadlock).
+- Recebimento sempre com timeout — um servidor travado nunca bloqueia
+  o caller para sempre.
+- Payload máximo configurável (DoS).
+- Erros de framing/JSON viram ``TransportError`` com contexto.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import queue
+import select
+import threading
+from dataclasses import dataclass
+from typing import IO, Any
+
+MAX_MESSAGE_BYTES = 16 * 1024 * 1024  # 16 MiB por mensagem
+_POLL_S = 0.1
+_IS_WINDOWS = os.name == "nt"  # select() no Windows só aceita sockets
+# Windows: readers cujo fd não pode ser fechado com read pendente —
+# mantidos vivos até o exit do processo para não travar o close().
+_LEAKED_READERS: set[IO[bytes]] = set()
+
+
+class TransportError(RuntimeError):
+    """Framing inválido, stream fechado ou mensagem corrompida."""
+
+
+@dataclass(frozen=True)
+class RpcResponse:
+    """Resposta JSON-RPC (result OU error, nunca os dois)."""
+
+    request_id: int | str | None
+    result: Any = None
+    error: dict[str, Any] | None = None
+    is_notification: bool = False
+    method: str = ""
+    params: Any = None
+
+
+class _FdReader:
+    """Reader incremental sobre um fd — ``os.read``+``select``, sem o
+    lock de BufferedReader que causava deadlock em ``close()``."""
+
+    def __init__(self, fd: int, closed: threading.Event) -> None:
+        self._fd = fd
+        self._closed = closed
+        self._buf = bytearray()
+
+    def _read_some(self) -> bytes | None:
+        """Chunk novo ou None (EOF/fechado). Polla ``_closed`` a cada
+        100ms para shutdown limpo. No Windows ``select`` não aceita
+        pipes — usa ``os.read`` bloqueante; ``close()`` destrava a
+        thread fechando o fd."""
+        while not self._closed.is_set():
+            if _IS_WINDOWS:
+                try:
+                    return os.read(self._fd, 65536) or None
+                except OSError:
+                    return None
+            try:
+                ready, _, _ = select.select([self._fd], [], [], _POLL_S)
+            except (OSError, ValueError):
+                return None
+            if not ready:
+                continue
+            try:
+                data = os.read(self._fd, 65536)
+            except OSError:
+                return None
+            if not data:
+                return None
+            return data
+        return None
+
+    def readline(self) -> bytes | None:
+        """Linha terminada em \\n ou None (EOF/fechado)."""
+        while True:
+            idx = self._buf.find(b"\n")
+            if idx >= 0:
+                line = bytes(self._buf[: idx + 1])
+                del self._buf[: idx + 1]
+                return line
+            chunk = self._read_some()
+            if chunk is None:
+                return None
+            self._buf += chunk
+
+    def read_exact(self, n: int) -> bytes | None:
+        """Exatamente ``n`` bytes ou None (EOF/fechado)."""
+        while len(self._buf) < n:
+            chunk = self._read_some()
+            if chunk is None:
+                return None
+            self._buf += chunk
+        out = bytes(self._buf[:n])
+        del self._buf[:n]
+        return out
+
+
+class JsonRpcTransport:
+    """Framing LSP: ``Content-Length: N\\r\\n\\r\\n<json>``.
+
+    Thread daemon lê mensagens continuamente e as deposita numa queue;
+    ``recv`` consome com timeout — servidor pendurado → ``TimeoutError``.
+    """
+
+    def __init__(
+        self,
+        reader: IO[bytes],
+        writer: IO[bytes],
+        *,
+        max_bytes: int = MAX_MESSAGE_BYTES,
+    ) -> None:
+        self._writer = writer
+        self._max = max_bytes
+        self._inbox: queue.Queue[RpcResponse | BaseException] = queue.Queue()
+        self._write_lock = threading.Lock()
+        self._closed = threading.Event()
+        try:
+            fd = reader.fileno()
+        except (OSError, AttributeError) as exc:
+            raise TransportError(
+                f"reader has no usable fileno: {exc}") from exc
+        # guarda o objeto reader — se ele for coletado, o fd morre junto
+        # e o transport fica surdo silenciosamente
+        self._reader = reader
+        self._reader_fd = fd
+        self._fd_reader = _FdReader(fd, self._closed)
+        self._reader_thread = threading.Thread(
+            target=self._read_loop, daemon=True, name="atlas-lsp-reader")
+        self._reader_thread.start()
+
+    # -- leitura ---------------------------------------------------------
+
+    def _read_loop(self) -> None:
+        try:
+            while not self._closed.is_set():
+                msg = self._read_message()
+                if msg is None:
+                    break
+                self._inbox.put(msg)
+        except BaseException as exc:  # stream morreu → erro na inbox
+            self._inbox.put(exc)
+        finally:
+            self._closed.set()
+
+    def _read_headers(self) -> int | None:
+        """None quando o stream fecha de forma limpa."""
+        length: int | None = None
+        while True:
+            line = self._fd_reader.readline()
+            if line is None:
+                return None
+            line = line.strip()
+            if not line:
+                break
+            if line.lower().startswith(b"content-length:"):
+                try:
+                    length = int(line.split(b":", 1)[1].strip())
+                except ValueError as exc:
+                    raise TransportError(
+                        f"bad Content-Length: {line!r}") from exc
+        if length is None:
+            raise TransportError("missing Content-Length header")
+        if length > self._max or length <= 0:
+            raise TransportError(f"message size {length} out of bounds")
+        return length
+
+    def _read_message(self) -> RpcResponse | None:
+        length = self._read_headers()
+        if length is None:
+            return None
+        body = self._fd_reader.read_exact(length)
+        if body is None or len(body) != length:
+            raise TransportError("truncated body / stream closed")
+        try:
+            obj = json.loads(body.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+            raise TransportError(f"invalid json payload: {exc}") from exc
+        if not isinstance(obj, dict):
+            raise TransportError("json-rpc payload is not an object")
+        return RpcResponse(
+            request_id=obj.get("id"),
+            result=obj.get("result"),
+            error=obj.get("error"),
+            is_notification="id" not in obj,
+            method=obj.get("method", ""),
+            params=obj.get("params"),
+        )
+
+    # -- API pública ------------------------------------------------------
+
+    def send(self, payload: dict[str, Any]) -> None:
+        """Serializa e envia uma mensagem JSON-RPC."""
+        body = json.dumps(payload, separators=(",", ":")).encode("utf-8")
+        frame = f"Content-Length: {len(body)}\r\n\r\n".encode() + body
+        with self._write_lock:
+            try:
+                self._writer.write(frame)
+                self._writer.flush()
+            except (OSError, ValueError) as exc:
+                raise TransportError(f"send failed: {exc}") from exc
+
+    def recv(self, timeout: float) -> RpcResponse:
+        """Próxima mensagem com timeout obrigatório."""
+        try:
+            item = self._inbox.get(timeout=timeout)
+        except queue.Empty as exc:
+            raise TimeoutError(
+                f"no LSP message within {timeout}s") from exc
+        if isinstance(item, BaseException):
+            raise item
+        return item
+
+    def close(self) -> None:
+        """Acorda a thread leitora (≤100ms) e fecha os streams — sem
+        deadlock: o fd é fechado depois do poll sair. No Windows o
+        read é bloqueante e fechar um handle com I/O pendente trava —
+        o fd fica vivo até o exit do processo (daemon thread morre
+        junto; pipes de teste recebem EOF quando o peer fecha)."""
+        self._closed.set()
+        self._reader_thread.join(timeout=1.0)
+        if _IS_WINDOWS:
+            _LEAKED_READERS.add(self._reader)
+        else:
+            with contextlib.suppress(OSError):
+                os.close(self._reader_fd)
+        with contextlib.suppress(OSError):
+            self._writer.close()

code_atlas/resolvers/registry.py

@@ -0,0 +1,33 @@
+"""Registro de resolvedores (resolver_id → SemanticResolver)."""
+
+from __future__ import annotations
+
+from code_atlas.resolvers.contracts import SemanticResolver
+
+
+class ResolverRegistry:
+    """Registro explícito — nenhum resolvedor é ativado por padrão.
+
+    Resolvers opt-in (SCIP/LSP) são registrados pelo caller; o registro
+    nunca os constrói sozinho a partir do conteúdo do repositório.
+    """
+
+    def __init__(self) -> None:
+        self._resolvers: dict[str, SemanticResolver] = {}
+
+    def register(self, resolver: SemanticResolver) -> None:
+        self._resolvers[resolver.resolver_id] = resolver
+
+    def get(self, resolver_id: str) -> SemanticResolver | None:
+        return self._resolvers.get(resolver_id)
+
+    def resolvers(self) -> tuple[SemanticResolver, ...]:
+        return tuple(self._resolvers.values())
+
+    def capable(self, language: str, relation_type: str) -> list[SemanticResolver]:
+        """Resolvers que cobrem a linguagem+relação, ordenados por tier."""
+        ok = [
+            r for r in self._resolvers.values()
+            if r.capabilities().covers(language, relation_type)
+        ]
+        return sorted(ok, key=lambda r: r.capabilities().tier)

code_atlas/resolvers/scip/__init__.py

@@ -0,0 +1,49 @@
+"""Integração SCIP (opt-in) — decoder stdlib + resolver semântico.
+
+Cobertura do schema ``scip.proto`` (documentada por campo):
+
+Interpretados:
+- Index.metadata{version, tool_info{name,version,arguments},
+  project_root, text_document_encoding}
+- Index.documents[] e Index.external_symbols[]
+- Document{language, relative_path, occurrences, symbols, text(ignorado
+  na correlação), position_encoding}
+- Occurrence{range(deprec.), single_line_range, multi_line_range, symbol,
+  symbol_roles, override_documentation, enclosing_range}
+- SymbolInformation{symbol, documentation, relationships, kind,
+  display_name, signature_documentation, enclosing_symbol}
+- Relationship{symbol, is_reference, is_implementation,
+  is_type_definition, is_definition}
+
+Preservados-na-decodificação mas não semânticos hoje:
+- syntax_kind, diagnostics (occurrence)
+- quaisquer campos futuros: skipados por wire-type (forward-compat)
+
+Símbolos ``local N`` permanecem locais — nunca promovidos a identidade
+global.
+"""
+
+from code_atlas.resolvers.scip.decoder import DecodeError
+from code_atlas.resolvers.scip.importer import (
+    ScipDocument,
+    ScipIndex,
+    ScipOccurrence,
+    ScipRange,
+    ScipSymbolInfo,
+    parse_index,
+)
+from code_atlas.resolvers.scip.loader import load_index
+from code_atlas.resolvers.scip.resolver import RESOLVER_ID, ScipResolver
+
+__all__ = [
+    "RESOLVER_ID",
+    "DecodeError",
+    "ScipDocument",
+    "ScipIndex",
+    "ScipOccurrence",
+    "ScipRange",
+    "ScipResolver",
+    "ScipSymbolInfo",
+    "load_index",
+    "parse_index",
+]