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

code_analysis_client/schema_disk_cache.py

@@ -0,0 +1,207 @@
+"""
+Cross-process on-disk cache for per-command JSON schemas (bug 8e6acb34, Fix 1).
+
+Root cause this addresses: :meth:`CodeAnalysisAsyncClient.get_command_schema`
+already memoizes a schema for the lifetime of one client instance
+(``self._command_schema_cache``), but that in-memory cache starts empty on
+every new process. Most real callers (one-shot CLI invocations, the
+``pipeline`` live checks, individual agent tool calls) construct a fresh
+:class:`~code_analysis_client.client.CodeAnalysisAsyncClient`, call a command
+once, and exit -- so the in-memory cache never pays for itself and every
+single ``call_validated``/``commands.<name>()`` invocation pays a full extra
+``help(cmdname)`` network round trip before the actual command call.
+
+Measured on the deployed server (192.168.254.26:15010), warm TCP connection,
+first ``call_validated("health", {})`` on a fresh client instance (schema
+cache miss) vs the same call with schema already cached in memory: the
+``help`` round trip costs ~2.7ms median -- matching bug 8e6acb34's reported
+~3.0ms "our own wrapper" figure almost exactly. This module removes that
+network round trip on repeat runs by persisting each fetched schema to a
+small JSON file on local disk, keyed by (server base URL, command name),
+with a bounded TTL so a stale schema is never trusted for long after a
+server-side deploy changes it.
+
+This does NOT weaken validation: the exact same schema shape is used either
+way, just fetched from local disk instead of the network when it is still
+fresh. ``refresh=True`` (existing :meth:`get_command_schema` parameter) and
+:meth:`CodeAnalysisAsyncClient.clear_command_schema_cache` (which now also
+purges the on-disk entries for that server) remain the explicit invalidation
+paths for when a caller knows the server's command schemas changed (e.g.
+after ``reload``).
+
+Configuration (env vars, all optional):
+    ``CODE_ANALYSIS_CLIENT_SCHEMA_CACHE_DIR`` -- override the cache root
+        (default: ``~/.cache/code_analysis_client/schema``).
+    ``CODE_ANALYSIS_CLIENT_SCHEMA_CACHE_TTL_SECONDS`` -- override the
+        freshness window (default: 300 seconds -- long enough to amortize
+        the round trip across a short-lived process's calls and across
+        back-to-back process invocations, short enough that a schema change
+        shipped by a deploy is picked up within five minutes without any
+        explicit action).
+    ``CODE_ANALYSIS_CLIENT_DISABLE_SCHEMA_CACHE`` -- set to ``1``/``true`` to
+        disable on-disk caching entirely and fall back to the original
+        per-instance-only, always-network behavior.
+
+Every function here is best-effort: any I/O or (de)serialization failure is
+swallowed and treated as a cache miss / no-op. A broken or unwritable cache
+directory must never break a command call, only forfeit the speedup.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+_ENV_CACHE_DIR = "CODE_ANALYSIS_CLIENT_SCHEMA_CACHE_DIR"
+_ENV_TTL_SECONDS = "CODE_ANALYSIS_CLIENT_SCHEMA_CACHE_TTL_SECONDS"
+_ENV_DISABLE = "CODE_ANALYSIS_CLIENT_DISABLE_SCHEMA_CACHE"
+
+_DEFAULT_TTL_SECONDS = 300.0
+_TRUTHY = {"1", "true", "yes", "on"}
+
+
+def _disabled() -> bool:
+    """Return True when on-disk schema caching is disabled via env var."""
+    return os.environ.get(_ENV_DISABLE, "").strip().lower() in _TRUTHY
+
+
+def _cache_root() -> Optional[Path]:
+    """Return the configured cache root directory, or None when disabled."""
+    if _disabled():
+        return None
+    override = os.environ.get(_ENV_CACHE_DIR)
+    if override:
+        return Path(override)
+    return Path.home() / ".cache" / "code_analysis_client" / "schema"
+
+
+def _ttl_seconds() -> float:
+    """Return the configured freshness window in seconds."""
+    raw = os.environ.get(_ENV_TTL_SECONDS)
+    if raw:
+        try:
+            return float(raw)
+        except ValueError:
+            pass
+    return _DEFAULT_TTL_SECONDS
+
+
+def _server_dir(root: Path, base_url: str) -> Path:
+    """Return the per-server subdirectory for ``base_url`` under ``root``."""
+    server_key = hashlib.sha256(base_url.encode("utf-8")).hexdigest()[:16]
+    return root / server_key
+
+
+def _safe_command_filename(command: str) -> str:
+    """Return a filesystem-safe file name for ``command``."""
+    safe = "".join(ch if ch.isalnum() or ch in "-_." else "_" for ch in command)
+    return f"{safe}.json"
+
+
+def _entry_path(base_url: str, command: str) -> Optional[Path]:
+    """Return the cache file path for (base_url, command), or None if disabled/invalid.
+
+    ``base_url`` must be a real string (a mock or other stand-in used by
+    tests is not, and is deliberately treated as "caching unavailable" so
+    unit tests exercising a mocked transport never touch the filesystem).
+    """
+    if not isinstance(base_url, str) or not base_url or not isinstance(command, str):
+        return None
+    root = _cache_root()
+    if root is None:
+        return None
+    return _server_dir(root, base_url) / _safe_command_filename(command)
+
+
+def load_cached_schema(base_url: str, command: str) -> Optional[Dict[str, Any]]:
+    """Return a fresh-enough disk-cached schema for (base_url, command), else None.
+
+    Args:
+        base_url: The server's base URL (``JsonRpcClient.base_url``), used as
+            the cache partition key.
+        command: Command name whose schema is wanted.
+
+    Returns:
+        The cached schema dict when a readable, unexpired entry exists;
+        ``None`` on any cache miss, staleness, or I/O/parse failure.
+    """
+    path = _entry_path(base_url, command)
+    if path is None:
+        return None
+    try:
+        if not path.exists():
+            return None
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    if not isinstance(raw, dict):
+        return None
+    fetched_at = raw.get("fetched_at")
+    schema = raw.get("schema")
+    if not isinstance(fetched_at, (int, float)) or not isinstance(schema, dict):
+        return None
+    if (time.time() - fetched_at) > _ttl_seconds():
+        return None
+    return schema
+
+
+def store_cached_schema(base_url: str, command: str, schema: Dict[str, Any]) -> None:
+    """Best-effort persist ``schema`` for (base_url, command) to local disk.
+
+    Writes to a process-unique temp file first and renames it over the final
+    path (atomic on the same filesystem) so a concurrent reader never sees a
+    partially written file. Never raises: a write failure only forfeits the
+    speedup, it must not break the calling command.
+
+    Args:
+        base_url: The server's base URL, used as the cache partition key.
+        command: Command name the schema belongs to.
+        schema: The schema dict to persist (as returned by the server's
+            ``help`` command for this command name).
+    """
+    path = _entry_path(base_url, command)
+    if path is None:
+        return
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp_path = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+        tmp_path.write_text(
+            json.dumps({"fetched_at": time.time(), "schema": schema}),
+            encoding="utf-8",
+        )
+        tmp_path.replace(path)
+    except OSError:
+        return
+
+
+def clear_cached_schemas(base_url: str) -> None:
+    """Best-effort delete every on-disk cached schema entry for ``base_url``.
+
+    Args:
+        base_url: The server's base URL whose cached entries should be
+            forgotten (e.g. after the caller learns the server reloaded its
+            command definitions).
+    """
+    if not isinstance(base_url, str) or not base_url:
+        return
+    root = _cache_root()
+    if root is None:
+        return
+    server_dir = _server_dir(root, base_url)
+    try:
+        if not server_dir.exists():
+            return
+        for entry in server_dir.iterdir():
+            try:
+                entry.unlink()
+            except OSError:
+                continue
+    except OSError:
+        return

code_analysis_client/server_api.py

@@ -0,0 +1,291 @@
+"""
+Canonical command names for the high-level client API vs the live server registry.
+
+**code-analysis-server** owns project trees, the index database, sessions, locks,
+and editor ingress (chunked transfer). It does **not** expose in-server content
+editing (``universal_file_open/edit/write/close``, CST/JSON tree modify/save,
+``format_code``, legacy line writers).
+
+**File content on CA** — read-only surface only:
+
+- :data:`FILE_CONTENT_READ_COMMANDS` — preview and project search (``search`` /
+  ``search_get_page``); on-disk grep is internal to ``search`` when enabled.
+- :data:`FS_COMMANDS` — filesystem operations (copy/move/remove/list/grep); not
+  the structured edit workflow.
+
+Editor clients use :data:`CLIENT_FACADE_COMMANDS` (sessions, transfer, locks,
+``universal_file_preview``).
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Dict, FrozenSet, Tuple
+
+# Removed from the public server surface — do not use in client facades or docs.
+LEGACY_REMOVED_COMMANDS: FrozenSet[str] = frozenset(
+    {
+        "universal_file_read",
+        "universal_file_save",
+        "universal_file_replace",
+        "universal_file_delete",
+        "read_project_text_file",
+        "write_project_text_lines",
+        "create_text_file",
+        "replace_file_lines",
+        "universal_file_search",
+        # TODO a7091850: removed from the public surface. GetFileLinesCommand
+        # still exists as an internal (unregistered) helper for
+        # read_project_text_file / universal_file_read Python-ecosystem
+        # line-range routing.
+        "get_file_lines",
+    }
+)
+
+# CST / JSON tree MCP workflow — modules may exist in the repo but are not registered.
+CST_REMOVED_COMMANDS: FrozenSet[str] = frozenset(
+    {
+        "cst_load_file",
+        "cst_save_tree",
+        "cst_modify_tree",
+        "cst_create_file",
+        "cst_find_node",
+        "cst_get_node_info",
+        "cst_get_node_by_range",
+        "cst_get_node_at_line",
+        "cst_reload_tree",
+        "cst_convert_and_save",
+        "cst_apply_buffer",
+        "cst_list_trees",
+        "cst_unload_tree",
+        "list_cst_blocks",
+        "query_cst",
+        "json_load_file",
+        "json_find_node",
+        "json_get_node_info",
+        "json_modify_tree",
+        "json_save_tree",
+        "json_reload_tree",
+    }
+)
+
+# Content editing on ai-editor-server only (not on code-analysis-server).
+EDITING_REMOVED_COMMANDS: FrozenSet[str] = frozenset(
+    {
+        "universal_file_open",
+        "universal_file_edit",
+        "universal_file_write",
+        "universal_file_close",
+        "universal_file_move_nodes",
+        "session_git_log",
+        "session_git_diff",
+        "session_git_show",
+        "session_git_status",
+        "session_git_revert",
+        "session_undo",
+        "session_redo",
+        "session_write",
+        # Bug 9ba69ede-a5fc-416a-a4db-f91fffad5aa2 (K6, commit 958c266c) re-registered delete_file, unmark_deleted_file,
+        # delete_files_by_mask, restore_deleted_files and cleanup_deleted_files; restore_backup_file, delete_backup and
+        # clear_all_backups are registered in hooks_register_part2 (F5 backup contract). They are served commands, so
+        # they are no longer listed here (live-deployed-server reported them as DISCREPANCY: listed removed but live-present).
+        "collapse_versions",
+        "format_code",
+    }
+)
+
+REMOVED_COMMANDS: FrozenSet[str] = (
+    LEGACY_REMOVED_COMMANDS | CST_REMOVED_COMMANDS | EDITING_REMOVED_COMMANDS
+)
+
+# Read-only file **content** on CA (no mutate/edit workflow). Includes on-disk search
+# (``fs_grep``, paginated ``search_*``) for paths not yet in the index.
+FILE_CONTENT_READ_COMMANDS: FrozenSet[str] = frozenset(
+    {
+        "universal_file_preview",
+        "search",
+        "search_get_page",
+        "search_get_status",
+        "search_cancel",
+        "search_close",
+    }
+)
+
+# Filesystem helpers — separate from structured content editing; may touch paths/bytes
+# via copy/move/remove but are not universal_file_edit / CST / format_code.
+FS_COMMANDS: FrozenSet[str] = frozenset(
+    {
+        "fs_copy",
+        "fs_move",
+        "fs_remove",
+        "cleanup_tree_sidecars",
+    }
+)
+
+# Client sessions + DB file locks — persisted on this server for editor/terminal clients.
+FILE_SESSION_COMMANDS: FrozenSet[str] = frozenset(
+    {
+        "session_create",
+        "session_validate",
+        "session_delete",
+        "session_worktrees_delete",
+        "session_list",
+        "session_view",
+        "session_open_file",
+        "session_open_documentation_document",
+        "session_close_file",
+        "session_list_file_locks",
+        "list_documentation_orphans",
+        "subordinate_session_create",
+        "subordinate_session_get",
+        "subordinate_session_update",
+        "subordinate_session_delete",
+        "subordinate_session_list",
+    }
+)
+
+TRANSFER_AND_LOCK_COMMANDS: FrozenSet[str] = frozenset(
+    {
+        "project_file_transfer_download_begin",
+        "project_file_transfer_upload_save",
+        "project_file_advisory_lock_batch",
+        "file_lock_write_check",
+    }
+)
+
+UNIVERSAL_FILE_COMMANDS: FrozenSet[str] = frozenset(
+    {
+        "universal_file_preview",
+    }
+)
+
+CLIENT_FACADE_COMMANDS: FrozenSet[str] = (
+    FILE_SESSION_COMMANDS | TRANSFER_AND_LOCK_COMMANDS | UNIVERSAL_FILE_COMMANDS
+)
+
+# ``FileSessionClient`` method names for each ``FILE_SESSION_COMMANDS`` entry.
+# ``session_list_file_locks`` is also used by ``assert_session_exists``.
+FILE_SESSION_FACADE_METHODS: Dict[str, str] = {
+    "session_create": "create_session",
+    "session_validate": "validate_session",
+    "session_delete": "delete_session",
+    "session_worktrees_delete": "session_worktrees_delete",
+    "session_list": "list_sessions",
+    "session_view": "view_session",
+    "session_open_file": "lock_file",
+    "session_open_documentation_document": "open_documentation_document",
+    "list_documentation_orphans": "list_documentation_orphans",
+    "session_close_file": "unlock_file",
+    "session_list_file_locks": "list_file_locks",
+    "subordinate_session_create": "create_subordinate_session",
+    "subordinate_session_get": "get_subordinate_session",
+    "subordinate_session_update": "update_subordinate_session",
+    "subordinate_session_delete": "delete_subordinate_session",
+    "subordinate_session_list": "list_subordinate_sessions",
+}
+
+# Transfer / advisory-lock commands may map to more than one façade method.
+TRANSFER_FACADE_METHODS: Dict[str, Tuple[str, ...]] = {
+    "project_file_transfer_download_begin": ("download",),
+    "project_file_transfer_upload_save": ("upload", "upload_new"),
+    "project_file_advisory_lock_batch": (
+        "lock_files_advisory",
+        "unlock_files_advisory",
+    ),
+    "file_lock_write_check": ("file_lock_write_check",),
+}
+
+
+def assert_file_session_facade_complete() -> None:
+    """Raise ``AssertionError`` if ``FILE_SESSION_FACADE_METHODS`` is incomplete."""
+    missing_cmds = FILE_SESSION_COMMANDS - set(FILE_SESSION_FACADE_METHODS)
+    extra_cmds = set(FILE_SESSION_FACADE_METHODS) - FILE_SESSION_COMMANDS
+    if missing_cmds or extra_cmds:
+        raise AssertionError(
+            "FILE_SESSION_FACADE_METHODS out of sync with FILE_SESSION_COMMANDS: "
+            f"missing={sorted(missing_cmds)!r} extra={sorted(extra_cmds)!r}"
+        )
+    from code_analysis_client.file_session import FileSessionClient
+
+    for command, method_name in FILE_SESSION_FACADE_METHODS.items():
+        if not hasattr(FileSessionClient, method_name):
+            raise AssertionError(
+                f"FileSessionClient missing method {method_name!r} for command {command!r}"
+            )
+
+
+def assert_transfer_facade_complete() -> None:
+    """Raise ``AssertionError`` if ``TRANSFER_FACADE_METHODS`` is incomplete."""
+    missing_cmds = TRANSFER_AND_LOCK_COMMANDS - set(TRANSFER_FACADE_METHODS)
+    extra_cmds = set(TRANSFER_FACADE_METHODS) - TRANSFER_AND_LOCK_COMMANDS
+    if missing_cmds or extra_cmds:
+        raise AssertionError(
+            "TRANSFER_FACADE_METHODS out of sync with TRANSFER_AND_LOCK_COMMANDS: "
+            f"missing={sorted(missing_cmds)!r} extra={sorted(extra_cmds)!r}"
+        )
+    from code_analysis_client.file_session import FileSessionClient
+
+    for command, method_names in TRANSFER_FACADE_METHODS.items():
+        for method_name in method_names:
+            if not hasattr(FileSessionClient, method_name):
+                raise AssertionError(
+                    f"FileSessionClient missing method {method_name!r} "
+                    f"for command {command!r}"
+                )
+
+
+def _command_registered(get_command: Callable[[str], object], name: str) -> bool:
+    """Return True when ``get_command`` can resolve a command name."""
+    try:
+        get_command(name)
+        return True
+    except KeyError:
+        return False
+
+
+def assert_facade_commands_registered(get_command: Callable[[str], object]) -> None:
+    """Raise ``KeyError`` if any facade command is missing from the server registry."""
+    missing = [
+        name
+        for name in sorted(CLIENT_FACADE_COMMANDS)
+        if not _command_registered(get_command, name)
+    ]
+    if missing:
+        raise KeyError(f"Client facade commands not registered on server: {missing}")
+
+
+def assert_removed_commands_absent(get_command: Callable[[str], object]) -> None:
+    """Raise ``AssertionError`` if a removed command is still registered."""
+    present = [
+        name
+        for name in sorted(REMOVED_COMMANDS)
+        if _command_registered(get_command, name)
+    ]
+    if present:
+        raise AssertionError(f"Removed commands still registered: {present}")
+
+
+def assert_file_content_read_commands_registered(
+    get_command: Callable[[str], object],
+) -> None:
+    """Raise ``KeyError`` if a read-only content command is missing from the registry."""
+    missing = [
+        name
+        for name in sorted(FILE_CONTENT_READ_COMMANDS)
+        if not _command_registered(get_command, name)
+    ]
+    if missing:
+        raise KeyError(f"File content read commands not registered: {missing}")
+
+
+def assert_fs_commands_registered(get_command: Callable[[str], object]) -> None:
+    """Raise ``KeyError`` if a filesystem helper command is missing from the registry."""
+    missing = [
+        name
+        for name in sorted(FS_COMMANDS)
+        if not _command_registered(get_command, name)
+    ]
+    if missing:
+        raise KeyError(f"Filesystem commands not registered: {missing}")

code_analysis_client/server_schema.py

@@ -0,0 +1,57 @@
+"""
+Load per-command JSON schema from the running server via ``help`` (cmdname).
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from code_analysis_client.exceptions import ClientValidationError
+
+
+def parse_schema_from_help_payload(
+    payload: Dict[str, Any], *, command_name: str
+) -> Dict[str, Any]:
+    """Extract ``get_schema()``-style dict from ``help`` JSON-RPC result."""
+    if not payload.get("success"):
+        raise ClientValidationError(
+            f"{command_name}: help returned success=false: {payload!r}",
+            field="help",
+            details={"payload": payload},
+        )
+    data = payload.get("data")
+    if not isinstance(data, dict):
+        raise ClientValidationError(
+            f"{command_name}: help response missing object 'data'",
+            field="help",
+        )
+    if data.get("error") and "schema" not in data:
+        raise ClientValidationError(
+            f"{command_name}: {data.get('error')}",
+            field="help",
+            details={"note": data.get("note"), "example": data.get("example")},
+        )
+    schema = data.get("schema")
+    if not isinstance(schema, dict):
+        raise ClientValidationError(
+            f"{command_name}: help response has no 'schema' object",
+            field="help",
+        )
+    return schema
+
+
+async def fetch_command_schema_from_server(
+    rpc: Any,
+    command_name: str,
+) -> Dict[str, Any]:
+    """Call server ``help`` with ``cmdname`` and return that command's input schema."""
+    raw = await rpc.help(command_name)
+    if not isinstance(raw, dict):
+        raise ClientValidationError(
+            f"{command_name}: help returned non-dict: {type(raw).__name__}",
+            field="help",
+        )
+    return parse_schema_from_help_payload(raw, command_name=command_name)

code_analysis_client/symbol_tree.py

@@ -0,0 +1,13 @@
+"""The uniform recursive declaration-tree result."""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class SymbolTreeNode(TypedDict):
+    """One declaration; kinds belong to language plugins."""
+
+    name: str
+    kind: str
+    children: list[SymbolTreeNode]

code_analysis_client/universal_file.py

@@ -0,0 +1,50 @@
+"""
+Read-only structured file preview on top of :class:`CodeAnalysisAsyncClient`.
+
+Wraps ``universal_file_preview`` only: a preview-only surface (project id and
+file path plus navigation parameters). Content editing is not served by this
+project's code-analysis server; that workflow lives in the ai-editor client.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict
+
+from code_analysis_client.responses import unwrap_command_result, FacadeCaller
+
+if TYPE_CHECKING:
+    from code_analysis_client.client import CodeAnalysisAsyncClient
+
+
+class UniversalFileClient:
+    """Read-only structured preview for project files.
+
+    Wraps ``universal_file_preview`` (the only ``universal_file_*`` command
+    registered on the code-analysis server). Content editing belongs to the
+    ai-editor client, not this package.
+    """
+
+    __slots__ = ("_client",)
+
+    def __init__(self, client: CodeAnalysisAsyncClient) -> None:
+        """Store the async client used for universal file preview commands."""
+        self._client = FacadeCaller(client)  # type: ignore[assignment]
+
+    async def preview(
+        self,
+        project_id: str,
+        file_path: str,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        """Structured read-only preview (``universal_file_preview``)."""
+        params: Dict[str, Any] = {
+            "project_id": project_id,
+            "file_path": file_path,
+        }
+        params.update(kwargs)
+        return unwrap_command_result(
+            await self._client.call_validated("universal_file_preview", params)
+        )