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

code_analysis_client/__init__.py

@@ -0,0 +1,142 @@
+"""
+Public async client for code-analysis-server (JSON-RPC via mcp-proxy-adapter).
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from code_analysis_client.client import CodeAnalysisAsyncClient
+from code_analysis_client.symbol_tree import SymbolTreeNode
+from code_analysis_client.commands_proxy import ValidatedCommandsProxy
+from code_analysis_client.config import (
+    DEFAULT_CLIENT_ADAPTER_CONFIG,
+    adapter_settings_from_server_config,
+    adapter_settings_to_jsonrpc_kwargs,
+    load_server_config,
+)
+from code_analysis_client.exceptions import (
+    ClientValidationError,
+    CommandFailedError,
+    JobFailedError,
+    JobTimeoutError,
+    QueueJobError,
+    VectorizerUnavailableError,
+)
+from code_analysis_client.file_session import FileSessionClient, SessionNotFoundError
+from code_analysis_client.check_chain import (
+    CheckChainClient,
+    CheckChainConfigInvalidError,
+    CheckChainError,
+    CheckChainGetResult,
+    CheckChainListResult,
+    ChainElement,
+    Degraded,
+    Diagnostic,
+    ExtensionChain,
+    FileCheckAndPromoteResult,
+)
+from code_analysis_client.worktree import WorktreeClient, WorktreeConflictError
+from code_analysis_client.project import ProjectClient
+from code_analysis_client.queue_wait import QueuedJob
+from code_analysis_client.server_api import (
+    CLIENT_FACADE_COMMANDS,
+    CST_REMOVED_COMMANDS,
+    FILE_SESSION_COMMANDS,
+    FILE_SESSION_FACADE_METHODS,
+    LEGACY_REMOVED_COMMANDS,
+    REMOVED_COMMANDS,
+    TRANSFER_FACADE_METHODS,
+    UNIVERSAL_FILE_COMMANDS,
+)
+from code_analysis_client.universal_file import UniversalFileClient
+from code_analysis_client.server_schema import (
+    fetch_command_schema_from_server,
+    parse_schema_from_help_payload,
+)
+from code_analysis_client.validation import (
+    prepare_params_for_schema,
+    validate_params_against_schema,
+)
+from code_analysis_client.vectorizer_state import (
+    ServiceState,
+    VectorizerState,
+    VectorizerWarning,
+    VectorizationWorkerBlock,
+    extract_vectorizer_state_from_response,
+    safe_get_vectorizer_state,
+    safe_get_warnings,
+    safe_get_vectorization_worker,
+)
+
+__all__ = [
+    "DEFAULT_CLIENT_ADAPTER_CONFIG",
+    "CLIENT_FACADE_COMMANDS",
+    "CST_REMOVED_COMMANDS",
+    "ClientValidationError",
+    "CodeAnalysisAsyncClient",
+    "SymbolTreeNode",
+    "CommandFailedError",
+    "FILE_SESSION_COMMANDS",
+    "FILE_SESSION_FACADE_METHODS",
+    "FileSessionClient",
+    "JobFailedError",
+    "JobTimeoutError",
+    "LEGACY_REMOVED_COMMANDS",
+    "QueueJobError",
+    "QueuedJob",
+    "REMOVED_COMMANDS",
+    "SessionNotFoundError",
+    "TRANSFER_FACADE_METHODS",
+    "UNIVERSAL_FILE_COMMANDS",
+    "UniversalFileClient",
+    "ValidatedCommandsProxy",
+    "VectorizerUnavailableError",
+    "ServiceState",
+    "VectorizerState",
+    "VectorizerWarning",
+    "VectorizationWorkerBlock",
+    "CheckChainClient",
+    "CheckChainConfigInvalidError",
+    "CheckChainError",
+    "CheckChainGetResult",
+    "CheckChainListResult",
+    "ChainElement",
+    "Degraded",
+    "Diagnostic",
+    "ExtensionChain",
+    "FileCheckAndPromoteResult",
+    "ProjectClient",
+    "WorktreeClient",
+    "WorktreeConflictError",
+    "adapter_settings_from_server_config",
+    "adapter_settings_to_jsonrpc_kwargs",
+    "extract_vectorizer_state_from_response",
+    "fetch_command_schema_from_server",
+    "load_server_config",
+    "parse_schema_from_help_payload",
+    "prepare_params_for_schema",
+    "safe_get_vectorizer_state",
+    "safe_get_warnings",
+    "safe_get_vectorization_worker",
+    "validate_params_against_schema",
+]
+
+
+def _read_package_version() -> str:
+    """Read installed client version from version.txt or package metadata."""
+    vf = Path(__file__).resolve().parent / "version.txt"
+    if vf.is_file():
+        return vf.read_text(encoding="utf-8").strip()
+    try:
+        import importlib.metadata as _imd
+
+        return _imd.version("code-analysis-client")
+    except Exception:
+        return "0.0.0"
+
+
+__version__ = _read_package_version()

code_analysis_client/check_chain.py

@@ -0,0 +1,374 @@
+"""
+Check-chain commands on top of CodeAnalysisAsyncClient.
+
+Typed wrappers for ``check_chain_list``, ``check_chain_get`` and
+``file_check_and_promote`` with full parameter mapping and result/error mapping:
+diagnostics, degraded outcomes, sync conflicts and the closed error enum of
+``file_check_and_promote``.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+from code_analysis_client.exceptions import ClientValidationError
+from code_analysis_client.responses import command_error_code, FacadeCaller
+from code_analysis_client.worktree import WorktreeConflictError
+
+if TYPE_CHECKING:
+    from code_analysis_client.client import CodeAnalysisAsyncClient
+
+EXTENSION_PATTERN = r"^\.[A-Za-z0-9]+(\.[A-Za-z0-9]+)*$"
+_EXTENSION_RE = re.compile(EXTENSION_PATTERN)
+
+FCP_ERROR_CODES = frozenset(
+    {
+        "VALIDATION_ERROR",
+        "PROJECT_NOT_FOUND",
+        "PROJECT_LOCKED",
+        "SESSION_NOT_FOUND",
+        "WORKTREE_CREATE_FAILED",
+        "WORKTREE_CREATE_TIMEOUT",
+        "WORKTREE_SYNC_CONFLICT",
+        "WORKTREE_MERGE_IN_PROGRESS",
+        "WORKTREE_REBASE_IN_PROGRESS",
+        "FCP_WRITE_FAILED",
+        "CHECK_CHAIN_CONFIG_INVALID",
+        "FCP_CHECK_TOOL_CRASHED",
+        "FCP_CHECK_TOOL_TIMEOUT",
+        "FCP_CHECK_TOOL_INSTALL_FAILED",
+        "WORKTREE_COMMIT_FAILED",
+        "FCP_PROMOTE_RACE",
+        "FCP_CANCELLED_BY_CLEANUP",
+        "GIT_NOT_AVAILABLE",
+        "GIT_NOT_A_REPO",
+        "FILE_LOCKED",
+        "LOCK_ACQUIRE_FAILED",
+        "LOCK_FILE_PATH_FORBIDDEN",
+    }
+)
+
+
+class CheckChainError(ClientValidationError):
+    """A check-chain command answered with a server error.
+
+    Attributes:
+        code: the server error code (e.g. ``FCP_PROMOTE_RACE``).
+        details: the server error details/data object.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str,
+        field: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Store the server error code with the message and details."""
+        super().__init__(message, field=field or "command", details=details)
+        self.code = code
+
+
+class CheckChainConfigInvalidError(CheckChainError):
+    """CHECK_CHAIN_CONFIG_INVALID with its section, extension and reason."""
+
+    def __init__(self, message: str, *, details: Optional[Dict[str, Any]] = None) -> None:
+        """Expose details.section/extension/reason as attributes."""
+        super().__init__(
+            message, code="CHECK_CHAIN_CONFIG_INVALID", field="check_chains", details=details
+        )
+        self.section = self.details.get("section")
+        self.extension = self.details.get("extension")
+        self.reason = self.details.get("reason")
+
+
+@dataclass(frozen=True)
+class ChainElement:
+    """One check-chain element."""
+
+    tool: str
+    config_source: str
+    blocking: bool
+    args: List[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class ExtensionChain:
+    """Resolved chain of one extension."""
+
+    extension: str
+    source: str
+    chain: List[ChainElement]
+
+
+@dataclass(frozen=True)
+class CheckChainListResult:
+    """Result of ``check_chain_list``."""
+
+    project_id: str
+    chains: List[ExtensionChain]
+
+
+@dataclass(frozen=True)
+class CheckChainGetResult:
+    """Result of ``check_chain_get``."""
+
+    project_id: str
+    extension: str
+    source: str
+    chain: List[ChainElement]
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    """One finding of a chain element."""
+
+    tool: str
+    path: str
+    line: Optional[int]
+    column: Optional[int]
+    code: Optional[str]
+    severity: Optional[str]
+    message: str
+
+
+@dataclass(frozen=True)
+class Degraded:
+    """Why a call degraded (nothing promoted)."""
+
+    reason: str
+    tool: Optional[str] = None
+    skipped_tools: List[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class FileCheckAndPromoteResult:
+    """Result of ``file_check_and_promote`` (outcome-discriminated).
+
+    ``outcome`` is ``promoted``, ``diagnostics`` or ``degraded``. ``promoted`` is
+    True only for ``promoted``. ``degraded`` may also be set on a promoted outcome
+    when only non-blocking tools were skipped (``skipped_tools``).
+    """
+
+    project_id: str
+    editor_session_id: str
+    path: str
+    outcome: str
+    promoted: bool
+    commit: Optional[str]
+    index_pending: bool
+    index_job_id: Optional[str]
+    index_trigger_error: Optional[str]
+    diagnostics: List[Diagnostic]
+    degraded: Optional[Degraded]
+    raw: Dict[str, Any] = field(default_factory=dict, compare=False, repr=False)
+    # Delivered write-back of a promoted documentation copy: {document_id, file_path,
+    # status "transferred"}; None for an ordinary file. A failed write-back is not a result:
+    # the server answers an error (CheckChainError, e.g. DOCUMENTATION_SERVER_UNAVAILABLE)
+    # whose details carry promoted, commit, edit_kept and holder_session_id.
+    documentation_transfer: Optional[Dict[str, Any]] = None
+    # Seconds spent waiting for the path lock and the project main lock
+    # ({path_waited_seconds, main_waited_seconds}); None from an older server.
+    lock_wait: Optional[Dict[str, float]] = None
+
+
+def _require_non_empty(value: Any, *, field_name: str) -> str:
+    """Return stripped text or raise ClientValidationError."""
+    text = str(value or "").strip()
+    if not text:
+        raise ClientValidationError(f"{field_name} is required", field=field_name)
+    return text
+
+
+def _error_parts(data: Dict[str, Any]) -> tuple[str, str, Dict[str, Any]]:
+    """Return (code, message, details) of a failed response."""
+    code = command_error_code(data)
+    err = data.get("error")
+    err_dict: Dict[str, Any] = err if isinstance(err, dict) else {}
+    message = data.get("message") or err_dict.get("message") or code or str(data)
+    details = (
+        err_dict.get("details")
+        or err_dict.get("data")
+        or data.get("details")
+        or data.get("data")
+        or {}
+    )
+    return code, str(message), details if isinstance(details, dict) else {}
+
+
+def _success_payload(data: Dict[str, Any], *, command: str) -> Dict[str, Any]:
+    """Return the success data dict, or raise the mapped error for a failure."""
+    if data.get("success"):
+        inner = data.get("data")
+        return inner if isinstance(inner, dict) else data
+    code, message, details = _error_parts(data)
+    if code == "WORKTREE_SYNC_CONFLICT":
+        raise WorktreeConflictError(
+            message,
+            conflicts=details.get("conflicts"),
+            preserved_locked_files=details.get("preserved_locked_files"),
+        )
+    if code == "CHECK_CHAIN_CONFIG_INVALID":
+        raise CheckChainConfigInvalidError(message, details=details)
+    raise CheckChainError(
+        message, code=code or "UNKNOWN", field=details.get("field") or command, details=details
+    )
+
+
+def _element(raw: Any) -> ChainElement:
+    """Map one raw chain element."""
+    item = raw if isinstance(raw, dict) else {}
+    return ChainElement(
+        tool=str(item.get("tool", "")),
+        config_source=str(item.get("config_source", "auto")),
+        blocking=bool(item.get("blocking", False)),
+        args=[str(a) for a in (item.get("args") or [])],
+    )
+
+
+def _diagnostic(raw: Any) -> Diagnostic:
+    """Map one raw diagnostic."""
+    item = raw if isinstance(raw, dict) else {}
+    return Diagnostic(
+        tool=str(item.get("tool", "")),
+        path=str(item.get("path", "")),
+        line=item.get("line"),
+        column=item.get("column"),
+        code=item.get("code"),
+        severity=item.get("severity"),
+        message=str(item.get("message", "")),
+    )
+
+
+def _degraded(raw: Any) -> Optional[Degraded]:
+    """Map the degraded object (None when absent)."""
+    if not isinstance(raw, dict):
+        return None
+    return Degraded(
+        reason=str(raw.get("reason", "")),
+        tool=raw.get("tool"),
+        skipped_tools=[str(t) for t in (raw.get("skipped_tools") or [])],
+    )
+
+
+class CheckChainClient:
+    """check_chain_list / check_chain_get / file_check_and_promote."""
+
+    __slots__ = ("_client",)
+
+    def __init__(self, client: CodeAnalysisAsyncClient) -> None:
+        """Store the underlying async client."""
+        self._client = FacadeCaller(client)  # type: ignore[assignment]
+
+    async def list(self, project_id: str) -> CheckChainListResult:
+        """Return the resolved chain of every configured extension.
+
+        Calls ``check_chain_list``. Raises CheckChainConfigInvalidError for a
+        malformed registry entry and CheckChainError for other server errors.
+        """
+        project_id = _require_non_empty(project_id, field_name="project_id")
+        data = await self._client.call_validated(
+            "check_chain_list", {"project_id": project_id}
+        )
+        payload = _success_payload(data, command="check_chain_list")
+        return CheckChainListResult(
+            project_id=str(payload.get("project_id", project_id)),
+            chains=[
+                ExtensionChain(
+                    extension=str(entry.get("extension", "")),
+                    source=str(entry.get("source", "empty")),
+                    chain=[_element(e) for e in (entry.get("chain") or [])],
+                )
+                for entry in (payload.get("chains") or [])
+                if isinstance(entry, dict)
+            ],
+        )
+
+    async def get(self, project_id: str, extension: str) -> CheckChainGetResult:
+        """Return the resolved chain of one extension (leading dot required).
+
+        Calls ``check_chain_get``. An unconfigured extension is source ``empty``
+        with an empty chain.
+        """
+        project_id = _require_non_empty(project_id, field_name="project_id")
+        extension = _require_non_empty(extension, field_name="extension")
+        if not _EXTENSION_RE.match(extension):
+            raise ClientValidationError(
+                f"extension must match {EXTENSION_PATTERN}", field="extension"
+            )
+        data = await self._client.call_validated(
+            "check_chain_get", {"project_id": project_id, "extension": extension}
+        )
+        payload = _success_payload(data, command="check_chain_get")
+        return CheckChainGetResult(
+            project_id=str(payload.get("project_id", project_id)),
+            extension=str(payload.get("extension", extension)),
+            source=str(payload.get("source", "empty")),
+            chain=[_element(e) for e in (payload.get("chain") or [])],
+        )
+
+    async def file_check_and_promote(
+        self,
+        project_id: str,
+        editor_session_id: str,
+        path: str,
+        content: str,
+        *,
+        check_only: bool = False,
+    ) -> FileCheckAndPromoteResult:
+        """Write, check and promote one file through the editor's worktree.
+
+        Calls ``file_check_and_promote``. Diagnostics and degraded outcomes are
+        successful results (``outcome`` / ``promoted``), never exceptions.
+        ``check_only=True`` checks the file in a temporary worktree and promotes
+        nothing (``promoted`` False, ``commit`` None).
+        Raises WorktreeConflictError on WORKTREE_SYNC_CONFLICT (with
+        ``conflicts`` and ``preserved_locked_files``), CheckChainConfigInvalidError
+        for a malformed registry entry, and CheckChainError (``code`` from the
+        closed enum, e.g. FCP_PROMOTE_RACE) for every other server error. A
+        documentation copy whose single write-back failed raises CheckChainError
+        too (DOCUMENTATION_SERVER_UNAVAILABLE, NOT_FOUND or INTERNAL_ERROR) although
+        the commit is promoted; the edit and the lock stay with the session.
+        """
+        project_id = _require_non_empty(project_id, field_name="project_id")
+        editor_session_id = _require_non_empty(
+            editor_session_id, field_name="editor_session_id"
+        )
+        path = _require_non_empty(path, field_name="path")
+        if not isinstance(content, str):
+            raise ClientValidationError("content must be a string", field="content")
+        if not isinstance(check_only, bool):
+            raise ClientValidationError("check_only must be a bool", field="check_only")
+        params: Dict[str, Any] = {
+            "project_id": project_id,
+            "editor_session_id": editor_session_id,
+            "path": path,
+            "content": content,
+        }
+        if check_only:
+            params["check_only"] = True
+        data = await self._client.call_validated("file_check_and_promote", params)
+        payload = _success_payload(data, command="file_check_and_promote")
+        outcome = str(payload.get("outcome", ""))
+        return FileCheckAndPromoteResult(
+            project_id=str(payload.get("project_id", project_id)),
+            editor_session_id=str(payload.get("editor_session_id", editor_session_id)),
+            path=str(payload.get("path", path)),
+            outcome=outcome,
+            promoted=bool(payload.get("promoted", outcome == "promoted")),
+            commit=payload.get("commit"),
+            index_pending=bool(payload.get("index_pending", False)),
+            index_job_id=payload.get("index_job_id"),
+            index_trigger_error=payload.get("index_trigger_error"),
+            diagnostics=[_diagnostic(d) for d in (payload.get("diagnostics") or [])],
+            degraded=_degraded(payload.get("degraded")),
+            raw=payload,
+            documentation_transfer=payload.get("documentation_transfer"),
+            lock_wait=payload.get("lock_wait"),
+        )