code-analysis-client-dev 1.6.341__py3-none-any.whl

code_analysis_client/project.py

@@ -0,0 +1,59 @@
+"""
+Project-level typed methods on top of CodeAnalysisAsyncClient.
+
+Wraps ``project_documentation_server_override`` (per-project address override of the documentation
+server, used by live proofs that substitute an unreachable address).
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, Optional
+
+from code_analysis_client.exceptions import ClientValidationError
+from code_analysis_client.responses import FacadeCaller, unwrap_command_result
+
+if TYPE_CHECKING:
+    from code_analysis_client.client import CodeAnalysisAsyncClient
+
+
+class ProjectClient:
+    """Project-scoped commands that are not part of the session workflow."""
+
+    __slots__ = ("_client",)
+
+    def __init__(self, client: CodeAnalysisAsyncClient) -> None:
+        """Store the underlying async client."""
+        self._client = FacadeCaller(client)  # type: ignore[assignment]
+
+    async def documentation_server_override(
+        self,
+        project_id: str,
+        *,
+        host: Optional[str] = None,
+        port: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Set (``host`` and ``port``) or clear (neither) the documentation-server override.
+
+        Calls ``project_documentation_server_override``; returns ``project_id``, ``override``
+        (``None`` or ``{host, port}``) and ``effective`` (``None`` or ``{protocol, host, port}``).
+
+        Raises:
+            ClientValidationError: ``host`` and ``port`` were not supplied together.
+        """
+        if (host is None) != (port is None):
+            raise ClientValidationError(
+                "host and port must be supplied together or both omitted",
+                field="port" if host is not None else "host",
+            )
+        params: Dict[str, Any] = {"project_id": project_id}
+        if host is not None:
+            params["host"] = host
+            params["port"] = port
+        return unwrap_command_result(
+            await self._client.call_validated(
+                "project_documentation_server_override", params
+            )
+        )

code_analysis_client/queue_wait.py

@@ -0,0 +1,341 @@
+"""
+Queued-job handle and the single place that maps adapter results/errors onto client contracts.
+
+Waiting itself is NOT done here: every wait is the adapter's standard call
+(``JsonRpcClient.execute_command_unified`` for a new command, ``JsonRpcClient.wait_for_job_via_websocket``
+for an existing job id). This module only turns what the adapter returns or raises into the
+client's public result/exception contract:
+
+* inner ``success=false`` -> :class:`~code_analysis_client.exceptions.CommandFailedError`
+* job failed (the command's own error) -> :class:`~code_analysis_client.exceptions.CommandFailedError`
+* job stopped / cancelled -> :class:`~code_analysis_client.exceptions.JobFailedError`
+* caller wait timeout (job keeps running) -> :class:`~code_analysis_client.exceptions.JobTimeoutError`
+* server JSON-RPC refusal -> :class:`~code_analysis_client.exceptions.ClientValidationError`
+  (mapped in ``client.py`` next to the transport call)
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable, Dict, Optional, Union
+
+from mcp_proxy_adapter.client.jsonrpc_client.exceptions import (
+    ClientRemoteResponseError,
+    CommandInnerFailureError,
+    CommandSessionFailedError,
+    CommandSessionTimeoutError,
+)
+
+from code_analysis_client.exceptions import (
+    ClientValidationError,
+    CommandFailedError,
+    JobFailedError,
+    JobTimeoutError,
+)
+
+_FAILED_JOB_STATUSES = frozenset({"failed", "stopped", "cancelled"})
+_TERMINAL_JOB_STATUSES = frozenset({"completed"}) | _FAILED_JOB_STATUSES
+
+#: Terminal command-session event name -> job status, used when the status payload has none.
+_EVENT_STATUS = {
+    "command_failed": "failed",
+    "command_error": "failed",
+    "command_cancelled": "cancelled",
+    "job_failed": "failed",
+    "job_stopped": "stopped",
+}
+
+StatusHook = Callable[[Dict[str, Any]], Union[Any, Awaitable[Any]]]
+
+
+def check_wait_arguments(timeout: Optional[float], poll_interval: Optional[float]) -> None:
+    """Reject a negative ``timeout`` and a non-positive ``poll_interval`` before anything is sent."""
+    if timeout is not None and (isinstance(timeout, bool) or timeout < 0):
+        raise ValueError(f"timeout must be >= 0 or None, got {timeout!r}")
+    if poll_interval is not None and (isinstance(poll_interval, bool) or poll_interval <= 0):
+        raise ValueError(f"poll_interval must be > 0 or None, got {poll_interval!r}")
+
+
+def inner_command_result(value: Any) -> Dict[str, Any]:
+    """Return the command's own result envelope from a queued-job result value.
+
+    The queue stores ``{"job_id", "command", "result": <command envelope>, "status"}``; a value
+    without that wrapper is taken as the envelope itself. A non-dict result is wrapped as
+    ``{"result": value}`` so callers always get a dict.
+    """
+    inner = value["result"] if isinstance(value, dict) and "result" in value else value
+    return inner if isinstance(inner, dict) else {"result": inner}
+
+
+def _extract_inner_command_error(status_data: Dict[str, Any]) -> Any:
+    """Pull the failed command's own structured error out of a job status dict.
+
+    Looks at ``status_data["result"]["result"]["error"]`` first (outer ``result`` is the queue
+    wrapper, inner ``result`` is the command's own envelope), then ``status_data["result"]["error"]``.
+    """
+    result_field = status_data.get("result")
+    if not isinstance(result_field, dict):
+        return None
+    inner = result_field.get("result")
+    if isinstance(inner, dict) and inner.get("error") is not None:
+        return inner["error"]
+    if result_field.get("error") is not None:
+        return result_field["error"]
+    return None
+
+
+def remote_error_text(message: Any, code: Any) -> str:
+    """Text of a server JSON-RPC error, identical to the adapter's ``ClientRemoteResponseError``.
+
+    ``"JSON-RPC error: <message> (code: <code>)"`` - used for an error carried by a failed job so
+    that it reads exactly like the same error answered at the top level.
+    """
+    return f"JSON-RPC error: {message} (code: {code})"
+
+
+def invalid_params_error(
+    message: str, data: Any, *, code: str | int = -32602
+) -> ClientValidationError:
+    """Build the :class:`ClientValidationError` for a server refusal of a command's parameters.
+
+    The single constructor for the top-level -32602 refusal (``client.py``), a -32602 carried by a
+    failed job (``job_failure``) and a refused command-session open with the server's own error
+    code (``map_adapter_error``), so ``code`` / ``field`` / ``details`` have one shape: ``details``
+    is the server's error ``data`` object and ``field`` its ``field`` entry (else ``"command"``).
+    Callers select the public code according to the command contract.
+    """
+    payload = data if isinstance(data, dict) else {}
+    field = payload.get("field")
+    return ClientValidationError(
+        message,
+        field=field if isinstance(field, str) else "command",
+        details=payload,
+        code=code,
+    )
+
+
+def validation_error_code_for_command(command: Optional[str]) -> str | int:
+    """Return the command's public code for a remote invalid-parameter response."""
+    return -32602 if command in (None, "symbol_tree") else "VALIDATION_ERROR"
+
+
+def command_failed(
+    command: Optional[str], job_id: Optional[str], inner: Dict[str, Any]
+) -> CommandFailedError:
+    """Build the :class:`CommandFailedError` for an inner envelope with ``success`` false."""
+    error = inner.get("error")
+    if error is None:
+        error = {k: inner[k] for k in ("code", "message") if k in inner} or inner
+    return CommandFailedError(command, job_id, error, result=inner)
+
+
+def job_failure(
+    job_id: Optional[str],
+    status_data: Optional[Dict[str, Any]],
+    terminal_event: Optional[Dict[str, Any]] = None,
+    *,
+    command: Optional[str] = None,
+) -> Union[CommandFailedError, JobFailedError, ClientValidationError]:
+    """Build the error for a job that ended failed / stopped / cancelled.
+
+    A job whose structured error carries JSON-RPC ``-32602`` (the server validates after
+    enqueueing) yields :class:`ClientValidationError` exactly like a top-level refusal. A job that
+    ended ``failed`` (its command returned an error, or the job itself failed) yields
+    :class:`CommandFailedError` carrying the structured error, the same as an immediate command
+    that returns an error envelope (owner decision 2026-11-07, bug e58c5982, contract RC7). Only a
+    ``stopped`` / ``cancelled`` job yields :class:`JobFailedError`.
+
+    ``error`` is always the structured error object: the failed command's own error when the
+    status payload carries one, else the queue-level error (a bare string is wrapped as
+    ``{"message": ...}``), else ``{"message": "job <status>"}``.
+    """
+    status_data = status_data if isinstance(status_data, dict) else {}
+    terminal_event = terminal_event if isinstance(terminal_event, dict) else {}
+    status = str(status_data.get("status") or "").strip().lower()
+    if status not in _FAILED_JOB_STATUSES:
+        status = _EVENT_STATUS.get(str(terminal_event.get("event") or ""), status or "failed")
+    error = _extract_inner_command_error(status_data)
+    if error is None:
+        error = status_data.get("error")
+    if error is None:
+        error = terminal_event.get("error")
+    if not isinstance(error, dict):
+        error = {"message": str(error) if error else f"job {status}", "status": status}
+    if error.get("code") == -32602:
+        return invalid_params_error(
+            remote_error_text(error.get("message"), -32602),
+            error.get("data"),
+            code=validation_error_code_for_command(command),
+        )
+    if status == "failed":
+        return CommandFailedError(command, job_id, error)
+    return JobFailedError(job_id, error, status=status)
+
+
+def result_from_job_status(
+    command: Optional[str], job_id: str, status_data: Dict[str, Any]
+) -> Dict[str, Any]:
+    """Turn a terminal job status payload into the call result, or raise the matching error."""
+    status = str(status_data.get("status") or "").strip().lower()
+    if status in _FAILED_JOB_STATUSES or status_data.get("error"):
+        raise job_failure(job_id, status_data, command=command)
+    inner = inner_command_result(status_data.get("result"))
+    flagged = (
+        status_data.get("command_success") is False
+        or bool(status_data.get("completed_with_error"))
+        or bool(status_data.get("native_completed_with_error"))
+    )
+    if inner.get("success") is False or flagged:
+        raise command_failed(command, job_id, inner)
+    return inner
+
+
+def result_from_unified(
+    command: str, envelope: Dict[str, Any]
+) -> Dict[str, Any]:
+    """Return the command result from an ``execute_command_unified`` envelope.
+
+    An inner ``success=false`` raises :class:`CommandFailedError` (it never reaches the caller as
+    a dict), for the immediate and the queued mode alike.
+    """
+    value = envelope.get("result")
+    inner = value if envelope.get("mode") == "immediate" else inner_command_result(value)
+    if not isinstance(inner, dict):
+        inner = {"result": inner}
+    if inner.get("success") is False:
+        raise command_failed(command, envelope.get("job_id"), inner)
+    return inner
+
+
+def map_adapter_error(
+    exc: BaseException, command: str, timeout: Optional[float]
+) -> Optional[BaseException]:
+    """Map an adapter exception onto the client's public exception, or ``None`` to re-raise as is.
+
+    * ``CommandSessionTimeoutError`` / ``asyncio.TimeoutError`` -> ``JobTimeoutError`` (the job keeps running)
+    * ``CommandInnerFailureError`` -> ``CommandFailedError``
+    * ``CommandSessionFailedError`` with a terminal event -> ``CommandFailedError`` when the job
+      ``failed``, ``JobFailedError`` when it was stopped / cancelled (structured error)
+    * ``CommandSessionFailedError`` for a refused open (numeric ``code``) -> ``ClientRemoteResponseError``
+      so the caller's JSON-RPC handling (-32602, -32601) is the same as on the HTTP path
+    * ``CommandSessionFailedError`` for a refused open carrying the server's own string error
+      ``code`` (the adapter forwards ``exc.code`` of the refusing exception, e.g. ``VALIDATION_ERROR``
+      from a command's ``validate_params`` before enqueue) -> ``ClientValidationError`` with that
+      exact ``code``, the server message and ``details`` = the server's ``data`` (the documented
+      refusal shape of :class:`ClientValidationError`)
+    """
+    if isinstance(exc, CommandSessionTimeoutError):
+        details = exc.details if isinstance(exc.details, dict) else {}
+        return JobTimeoutError(details.get("job_id"), details.get("timeout", timeout))
+    if isinstance(exc, asyncio.TimeoutError):
+        return JobTimeoutError(None, timeout)
+    if isinstance(exc, CommandInnerFailureError):
+        inner = exc.result if isinstance(exc.result, dict) else {}
+        if not isinstance(inner.get("error"), dict):
+            inner = {
+                "success": False,
+                "error": {
+                    "code": exc.error_code,
+                    "message": exc.error_message,
+                    "data": exc.error_data,
+                },
+            }
+        return command_failed(exc.command, exc.job_id, inner)
+    if isinstance(exc, CommandSessionFailedError):
+        details = exc.details if isinstance(exc.details, dict) else {}
+        terminal = details.get("terminal_event")
+        if isinstance(terminal, dict):
+            job_id = terminal.get("job_id")
+            status_data = details.get("result_status")
+            if job_id is None and isinstance(status_data, dict):
+                job_id = status_data.get("job_id")
+            return job_failure(job_id, status_data, terminal, command=command)
+        code = details.get("code")
+        if isinstance(code, int) and not isinstance(code, bool):
+            return ClientRemoteResponseError(
+                f"JSON-RPC error: {exc} (code: {code})",
+                operation="command_session.open",
+                details={
+                    "code": code,
+                    "data": details.get("data"),
+                    "command": command,
+                },
+            )
+        if isinstance(code, str) and code.strip():
+            return invalid_params_error(
+                str(details.get("error") or exc),
+                details.get("data"),
+                code=code.strip(),
+            )
+    return None
+
+
+@dataclass
+class QueuedJob:
+    """Handle for a queued job returned when ``auto_poll=False`` detaches from the job.
+
+    Returned by ``CodeAnalysisAsyncClient`` calls made with ``auto_poll=False`` (for every
+    command, queued or formerly immediate). ``job_id`` is a non-empty string and ``envelope`` the
+    adapter's acceptance envelope. :meth:`wait` blocks on the job and returns/raises exactly like
+    the default (auto-polling) path.
+    """
+
+    job_id: str
+    envelope: Dict[str, Any]
+    rpc: Any = field(repr=False)
+    #: Command name, used in :class:`CommandFailedError`.
+    command: Optional[str] = None
+    #: Result already produced when the adapter ran the command without a job (WS unreachable).
+    resolved: Optional[Dict[str, Any]] = field(default=None, repr=False)
+
+    async def wait(
+        self,
+        *,
+        timeout: Optional[float] = None,
+        poll_interval: Optional[float] = None,
+        status_hook: Optional[StatusHook] = None,
+    ) -> Dict[str, Any]:
+        """Wait for the job and return the command result, like the default call path.
+
+        Uses only public adapter API: one status fetch
+        (``fetch_command_session_result``) and, when the job is still running, the adapter's
+        WebSocket wait (``wait_for_job_via_websocket``) followed by one result fetch. Raises
+        :class:`JobTimeoutError` when ``timeout`` expires (the job keeps running),
+        :class:`JobFailedError` / :class:`CommandFailedError` like a direct call.
+
+        ``timeout=None`` resolves to the client config ``websocket.job_wait_timeout`` (0 = no
+        bound). ``poll_interval`` is accepted for signature symmetry with the call path; the
+        public WebSocket wait for an existing job id has no poll cadence and no RPC-polling
+        fallback, so it is not used here.
+        """
+        check_wait_arguments(timeout, poll_interval)
+        if self.resolved is not None:
+            return self.resolved
+        status_data = await self.rpc.fetch_command_session_result(self.job_id)
+        if str(status_data.get("status") or "").strip().lower() not in _TERMINAL_JOB_STATUSES:
+            try:
+                await self.rpc.wait_for_job_via_websocket(
+                    self.job_id, timeout=timeout, on_inbound_message=status_hook
+                )
+            except (CommandSessionTimeoutError, asyncio.TimeoutError) as exc:
+                mapped = map_adapter_error(exc, self.command or "", timeout)
+                assert mapped is not None
+                if isinstance(mapped, JobTimeoutError) and mapped.job_id is None:
+                    mapped = JobTimeoutError(self.job_id, timeout)
+                raise mapped from exc
+            status_data = await self.rpc.fetch_command_session_result(self.job_id)
+        return result_from_job_status(self.command, self.job_id, status_data)
+
+    async def status(self) -> Dict[str, Any]:
+        """One-shot ``queue_get_job_status`` fetch (no waiting)."""
+        resp = await self.rpc.execute_command(
+            "queue_get_job_status", {"job_id": self.job_id}
+        )
+        data = resp.get("data") if isinstance(resp, dict) else None
+        if not isinstance(data, dict):
+            data = resp if isinstance(resp, dict) else {}
+        return data

code_analysis_client/responses.py

@@ -0,0 +1,126 @@
+"""Parse JSON-RPC command envelopes from code-analysis-server."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from code_analysis_client.exceptions import (
+    ClientValidationError,
+    CommandFailedError,
+    VectorizerUnavailableError,
+)
+
+
+def command_error_code(data: Dict[str, Any]) -> str:
+    """Return domain or JSON-RPC error code from a failed command response."""
+    if data.get("success") is True:
+        return ""
+    top = data.get("code")
+    if top is not None and str(top).strip():
+        return str(top).strip()
+    err = data.get("error")
+    if isinstance(err, dict):
+        nested = err.get("code")
+        if nested is not None:
+            return str(nested).strip()
+    if isinstance(err, str) and err.strip():
+        return err.strip()
+    return ""
+
+
+def vectorizer_error_details(data: Dict[str, Any]) -> Dict[str, Any]:
+    """Return the ``details`` object of a failed command response.
+
+    The server (mcp-proxy-adapter ``ErrorResult``) puts the details at ``error.data``; a flat
+    envelope may carry ``details`` at the top level or ``error.details``. All three are read, in
+    the order ``error.data``, ``error.details``, top-level ``details``.
+    """
+    err = data.get("error")
+    if isinstance(err, dict):
+        for key in ("data", "details"):
+            nested = err.get(key)
+            if isinstance(nested, dict):
+                return nested
+    top = data.get("details")
+    return top if isinstance(top, dict) else {}
+
+
+def unwrap_command_result(
+    data: Dict[str, Any],
+    *,
+    session_not_found_type: type[ClientValidationError] | None = None,
+) -> Dict[str, Any]:
+    """Return success ``data`` dict or raise :class:`ClientValidationError`.
+
+    A refusal raises with ``.code`` equal to the server error code and ``.details`` equal to the
+    server's error details object (``{}`` when it carries none).
+    """
+    if data.get("success"):
+        inner = data.get("data")
+        return inner if isinstance(inner, dict) else data
+    code = command_error_code(data)
+    message = data.get("message")
+    err = data.get("error")
+    if message is None and isinstance(err, dict):
+        message = err.get("message")
+    if message is None:
+        message = str(data)
+    server_details = vectorizer_error_details(data)
+    if code == "SESSION_NOT_FOUND" and session_not_found_type is not None:
+        raise session_not_found_type(
+            message, field="session_id", details=server_details, code=code
+        )
+    if code == "VECTORIZER_UNAVAILABLE":
+        details = vectorizer_error_details(data)
+        raise VectorizerUnavailableError(
+            message,
+            service=details.get("service"),
+            services=details.get("services", []),
+            reason=details.get("reason"),
+            since=details.get("since"),
+            last_probe_at=details.get("last_probe_at"),
+            retry_after_seconds=details.get("retry_after_seconds"),
+            details=details,
+        )
+    raise ClientValidationError(
+        message, field="command", details=server_details, code=code or None
+    )
+
+
+class FacadeCaller:
+    """Client view handed to the typed facades (sessions, worktrees, check chains, previews).
+
+    The facades map a server refusal (``SESSION_NOT_FOUND``, ``VECTORIZER_UNAVAILABLE``,
+    ``WORKTREE_SYNC_CONFLICT``, ...) from the failed inner envelope. The public ``call`` /
+    ``call_validated`` raise :class:`CommandFailedError` for such an envelope; this view hands the
+    envelope (``CommandFailedError.result``) back to the facade unchanged so its typed errors stay
+    exactly as they were.
+    """
+
+    __slots__ = ("_client",)
+
+    def __init__(self, client: Any) -> None:
+        """Wrap ``client``."""
+        self._client = client
+
+    def __getattr__(self, name: str) -> Any:
+        """Forward everything else to the real client."""
+        return getattr(self._client, name)
+
+    async def call_validated(self, *args: Any, **kwargs: Any) -> Any:
+        """``call_validated`` that returns a failed inner envelope instead of raising."""
+        try:
+            return await self._client.call_validated(*args, **kwargs)
+        except CommandFailedError as exc:
+            if isinstance(exc.result, dict):
+                return exc.result
+            raise
+
+    async def call(self, *args: Any, **kwargs: Any) -> Any:
+        """``call`` that returns a failed inner envelope instead of raising."""
+        try:
+            return await self._client.call(*args, **kwargs)
+        except CommandFailedError as exc:
+            if isinstance(exc.result, dict):
+                return exc.result
+            raise