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

code_analysis_client_dev-1.6.341.dist-info/METADATA

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: code-analysis-client-dev
+Version: 1.6.341
+Summary: Async JSON-RPC client for the code-analysis MCP server (mcp-proxy-adapter JsonRpcClient)
+Author-email: Vasiliy Zdanovskiy <vasilyvz@gmail.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp-proxy-adapter>=8.11.15
+Provides-Extra: dev
+Requires-Dist: pytest>=9.2.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.4.1.post1; extra == "dev"
+
+# code-analysis-client
+
+Async Python client for the **code-analysis** server. It wraps `mcp-proxy-adapter`’s `JsonRpcClient`, so you get the adapter’s built-in methods (queue, transfer, `help`, `health`, …) plus thin helpers to run any registered server command.
+
+## Install
+
+```bash
+pip install code-analysis-client
+```
+
+## Usage
+
+```python
+import asyncio
+from code_analysis_client import CodeAnalysisAsyncClient
+
+
+async def main() -> None:
+    client = CodeAnalysisAsyncClient(
+        protocol="https",
+        host="127.0.0.1",
+        port=15001,
+        cert="/path/client.crt",
+        key="/path/client.key",
+        ca="/path/ca.crt",
+        timeout=120.0,
+    )
+    async with client:
+        h = await client.rpc.help()
+        r = await client.call("list_projects", {"include_deleted": False})
+    print(h, r)
+
+
+asyncio.run(main())
+```
+
+Build client settings from the same JSON shape as the pipeline adapter settings (`host`, `port`, `protocol`, optional `ssl` with `cert` / `key` / `ca` or `*_path` aliases), or from a full server `config.json` object.
+
+```python
+from code_analysis_client import CodeAnalysisAsyncClient
+
+client = CodeAnalysisAsyncClient.from_server_config(config_dict, timeout=60.0)
+```
+
+### Every call is the adapter's standard call
+
+Every entry point — `call`, `call_validated`, `client.commands.<name>`, and the
+`file_sessions` / `universal_files` / `worktrees` / `check_chains` facades built on
+`call_validated` — goes through one core that uses `mcp-proxy-adapter`'s
+`JsonRpcClient.execute_command_unified`: the command runs in a WebSocket command
+session and the call returns when the terminal event arrives (no polling while the
+socket is up). If `/ws` is unreachable the adapter falls back to RPC polling of
+`queue_get_job_status` and logs one WARNING `WS_UNREACHABLE_RPC_POLLING_FALLBACK`;
+the result is identical. The client has no polling loop of its own.
+
+```python
+# Queued or not, this waits and returns the command's own result envelope.
+out = await client.call("some_long_running_command", {...})
+```
+
+Failures raise instead of returning an error envelope:
+
+* `CommandFailedError` — the command ran but its inner result is
+  `{"success": false}`, or a queued job ended `failed` (immediate and queued
+  commands alike; a failing result is never returned as a dict). Carries
+  `.command`, `.job_id`, `.error` (the server's error object, e.g. `.error["code"]`)
+  and `.result` (the inner envelope, when there is one).
+* `JobFailedError` — the job was stopped or cancelled, or the queue reported a
+  queue-level error. Carries `.job_id`, `.status` and `.error` (always a
+  structured error dict).
+* `JobTimeoutError` — only when a positive `timeout` elapses; the call detaches and
+  the job keeps running server-side (`websocket.on_timeout` is `detach`).
+* `ClientValidationError` — the server refused the parameters (JSON-RPC `-32602`),
+  answered at the top level or carried by the failed job of an in-process command
+  (same text `JSON-RPC error: <message> (code: -32602)`, `code` `VALIDATION_ERROR`);
+  `details` carries the server's error `data` (e.g. its `violation` payload). A
+  command the server refuses before starting it with its own error code (for
+  example `VALIDATION_ERROR` for an unknown `project_id`) raises it with that exact
+  `code` and the server's `data` as `details`.
+* `ValueError` — a negative `timeout` or a non-positive `poll_interval`, before
+  anything is sent.
+
+Optional keyword args on `call` / `call_validated` (and their `call_unified*`
+counterparts):
+
+* `timeout` — total wait in seconds. `None` (default) uses the client config
+  `websocket.job_wait_timeout`, shipped as `0` = no time limit, so a long queued
+  command is never cut off. A value above 0 raises `JobTimeoutError` and detaches.
+* `poll_interval` — safety-net status-poll cadence in seconds. `None` (default)
+  uses `websocket.terminal_poll_interval` (2 s); a value overrides it per call.
+* `status_hook` — sync or async callable invoked with each adapter WebSocket event
+  (at least the accepted event first and the terminal completed event last). An
+  exception raised by the hook propagates.
+
+`call` / `call_validated` also take `auto_poll` (default `True`). Pass
+`auto_poll=False` to detach as soon as the job id is known: the call returns a
+`QueuedJob` handle immediately — for every command, including ones that finish at
+once — and `timeout`, `poll_interval` and `status_hook` are ignored.
+
+```python
+from code_analysis_client import QueuedJob
+
+job = await client.call("some_long_running_command", {...}, auto_poll=False)
+assert isinstance(job, QueuedJob)
+# do other work here, then block on it whenever you're ready
+result = await job.wait()   # same result / errors as the default path
+```
+
+`QueuedJob` exposes `.job_id`, `.envelope` (the adapter's acceptance envelope) and two
+async methods: `.wait(timeout=None, poll_interval=None, status_hook=None)` — reads the
+job once and, if it is still running, uses the adapter's WebSocket wait for the job id
+(public API `wait_for_job_via_websocket`), then returns/raises exactly like the default
+path; there is no RPC-polling fallback for an existing job id (a WebSocket failure
+propagates) — and `.status()` — a single `queue_get_job_status` fetch.
+
+#### Explicit adapter timeout configuration
+
+The client hands `JsonRpcClient(ws_config=...)` the explicit defaults
+`code_analysis_client.DEFAULT_CLIENT_ADAPTER_CONFIG` (a `ws_config=` keyword you pass is
+merged over them key by key), so none of the adapter's own 60 s / `cancel` defaults is
+effective:
+
+| `websocket` key | value | meaning |
+|---|---|---|
+| `job_wait_timeout` | 0 | no total bound on a call's wait |
+| `on_timeout` | `detach` | a wait timeout leaves the job running |
+| `receive_timeout` / `receive_timeout_buffer` | 60 / 5 | one receive cap (never limits the total wait) |
+| `heartbeat_interval` | 30 | WebSocket heartbeat |
+| `terminal_poll_interval` | 2 | safety-net poll cadence |
+| `close_timeout` | 5 | socket close bound |
+| `subscribe_settle_delay` / `cancel_grace_seconds` | 0.5 / 0.5 | settle delay, cancel grace |
+
+`job_push`: `on_caller_loss` `detach` (a job survives a lost client), `poll_interval` `0.1`.
+The server ships and applies the same values.
+
+`call_unified` / `call_unified_validated` are kept as **deprecated aliases** of
+`call` / `call_validated` for backward compatibility and emit
+`DeprecationWarning` on every call. `expect_queue` remains accepted-and-ignored
+(documented no-op). `auto_poll` is the one canonical switch and is forwarded
+straight through to `call` / `call_validated` — `auto_poll=False` on an alias
+returns a `QueuedJob` the same way it does on the non-deprecated method.
+Prefer `call` / `call_validated` directly.
+
+## Validation using the server schema
+
+The authoritative input schema is whatever the running server returns from **`help`** with `cmdname` set to the command. The client calls that, optionally caches the result, performs the same shallow checks as the server’s `BaseMCPCommand` (types, `required`, `enum`, `additionalProperties`), then runs the command.
+
+```python
+async with CodeAnalysisAsyncClient(host="127.0.0.1", port=15001) as client:
+    # Explicit
+    out = await client.call_validated(
+        "list_projects",
+        {"include_deleted": False},
+    )
+    # Dynamic wrapper: same as call_validated("list_projects", {...})
+    out = await client.commands.list_projects(include_deleted=False)
+    # After server reload
+    client.clear_command_schema_cache()
+```
+
+Pass `refresh_schema=True` on a single call to bypass the in-memory schema cache.
+
+## High-level facades (aligned with live server registry)
+
+The client does **not** wrap CST commands (`cst_load_file`, …) or legacy file I/O
+(`universal_file_read`, `read_project_text_file`, …). Those commands are removed
+from the server registry. Use the facades below or generic `call` / `commands.*`.
+
+| Facade | Property | Server commands |
+|--------|----------|-----------------|
+| Client DB sessions + transfer | `client.file_sessions` | `session_*`, `subordinate_session_*`, `project_file_transfer_*`, `project_file_advisory_lock_batch` |
+| Universal file preview | `client.universal_files` | `universal_file_preview` (read-only) |
+| Any registered command | `client.call` / `client.commands.<name>` | schema from live `help()` |
+
+`update_indexes` has no typed wrapper (it goes through the generic call); its optional
+boolean `force` (default `false`) re-analyses every indexed file even when path+mtime are
+unchanged, rewriting the tree sidecar and refreshing DB node ids:
+
+```python
+await client.commands.update_indexes(project_id=pid, force=True)
+```
+
+Canonical command lists: `code_analysis_client.server_api` — exported as
+`FILE_SESSION_COMMANDS`, `FILE_SESSION_FACADE_METHODS`, `CLIENT_FACADE_COMMANDS`,
+`REMOVED_COMMANDS`.
+
+**Scope boundary:** this client manipulates files only as whole units — transfer,
+locks, sessions, and structured read-only preview — and analyzes them. Content
+editing is not served by this project's code-analysis server; use the ai-editor
+client for that.
+
+Sync checks (in-process registry):
+
+```bash
+pytest tests/test_client_server_api_sync.py tests/test_code_analysis_client.py -k session
+```
+
+Package version is in the root ``pyproject.toml``; before a client wheel build run
+``python scripts/sync_code_analysis_client_version.py`` (``./build.sh <VERSION>`` does it as its bump step).
+
+## Examples (this repository)
+
+Runnable scripts live under `client/examples/`. **Long-form “man page” style
+documentation** is embedded in the **module docstrings** of those Python files
+(see `client/examples/README.md` for how to read them).
+
+| Script | Purpose |
+|--------|---------|
+| `run_all_examples.py` | Full API tour + runs all live sibling scripts |
+| `ex_minimal_validated.py` | Smallest validated RPC example |
+| `ex_universal_files.py` | `UniversalFileClient.preview` (read-only structured preview) |
+| `ex_session_view_subordinates.py` | `session_view` and subordinate CRUD |
+| `ex_file_sessions.py` | Sessions, locks, transfer roundtrip |
+| `ex_config_only.py` | Parse `config.json` without TCP |
+
+```bash
+casmgr --config config.json start
+python client/examples/run_all_examples.py
+```
+
+## Development
+
+From the repository root:
+
+```bash
+pip install -e ./client
+pytest tests/test_code_analysis_client.py
+```
+
+### Releasing to PyPI (version = root ``code-analysis`` project)
+
+The client wheel version is read from ``client/code_analysis_client/version.txt``.
+That file must match ``[project].version`` in the **repository root**
+``pyproject.toml``. The client is published only by the repository release script,
+together with the server image (same version, already-published versions fail):
+
+```bash
+./build.sh [dev=yes|no] <VERSION>   # dev=yes (default) is the build pass that publishes the client
+```

code_analysis_client_dev-1.6.341.dist-info/RECORD

@@ -0,0 +1,24 @@
+code_analysis_client/__init__.py,sha256=zn0S9fMWGjUvJIE267ny1-IffRgs7LOHgGu_YCrIqIw,4066
+code_analysis_client/check_chain.py,sha256=AUgY7r1hDNLELn6vtP42uLTVPgWDR4GcmxqK57hn6DU,13643
+code_analysis_client/client.py,sha256=NWIp5ZyyFCz0ljckiSi0AoCSFY5n2wn5Yv5cPXo96xE,28079
+code_analysis_client/commands_proxy.py,sha256=x5gC68QqH_AjTXbnosGCf_5OQXxQv8XSiEWi7lya74c,2226
+code_analysis_client/config.py,sha256=I3jUYu8PDPKxazoJGUC13r7GfEBmzuCRuzPJz4jwe_E,7704
+code_analysis_client/exceptions.py,sha256=emG6eVQAfXDsfUVRVCjCvwCFd7yoVLYZ0nkMUwXlrNw,6760
+code_analysis_client/file_session.py,sha256=3EWzRIsB2rc33WjG-Psz6KeShVV-t97fPz4fglQA0A0,30623
+code_analysis_client/project.py,sha256=oXgMO5pfuOQw5RLGTgNRARXI81b1-AemQezhe6yHRj8,2096
+code_analysis_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+code_analysis_client/queue_wait.py,sha256=XLg_5qE82Y4u548iUCfNH3_tvJ7mhuO8JjrjgAd0jDw,15795
+code_analysis_client/responses.py,sha256=8xGS0ag7lwpJ6eW2IrsmaI4los8sgHlHBO5zxAGNUbI,4659
+code_analysis_client/schema_disk_cache.py,sha256=sJsy8pEgMTdcDVUr1fLmR8JFDKdcXE03GddQLLAInXw,8090
+code_analysis_client/server_api.py,sha256=ggYaThbjgblvpiaUvjl6MYOEVkjuC5Wr-b5PQJjaRA0,10558
+code_analysis_client/server_schema.py,sha256=6auc4WQFiA_2-XQDNVX-8edPtkYCZP4IOzVlePMfYj0,1862
+code_analysis_client/symbol_tree.py,sha256=nZpYSttb7IAGzfkfkZUG0GJ3Zt6QU0rNkfaGAMpJ4n4,279
+code_analysis_client/universal_file.py,sha256=Ha2XVZg3dcBSpnfRBiGpK1z_kVlHEPPjaRkpaNSxspU,1638
+code_analysis_client/validation.py,sha256=ETUaWW2aGEFaWoXHPWj1n4hwQMfpek3ua3PmrEQJ-yc,3918
+code_analysis_client/vectorizer_state.py,sha256=uZYbBnnsWt1-_gzGMVNaC2LGAEEzt69DpYI-o4GvDHI,5480
+code_analysis_client/version.txt,sha256=ULvJV3vkYhEKP-17egc0wT8VFUjJ8t9zRHmcg8V36Dw,8
+code_analysis_client/worktree.py,sha256=tpZDMxt2osS2WbLM9jE_QK-OSFoZbUtlNe7a2xFDtB4,15801
+code_analysis_client_dev-1.6.341.dist-info/METADATA,sha256=F9qFqP-qPYSwPz-rMrUj-qB-r5Pr9q_cYgvWDPFUNns,11336
+code_analysis_client_dev-1.6.341.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+code_analysis_client_dev-1.6.341.dist-info/top_level.txt,sha256=NXzwlTVdqyKm43HrnRqBc-DlAeSVkHifJihWZ9JZ2xs,21
+code_analysis_client_dev-1.6.341.dist-info/RECORD,,

code_analysis_client_dev-1.6.341.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

code_analysis_client_dev-1.6.341.dist-info/top_level.txt

@@ -0,0 +1 @@
+code_analysis_client