java-codebase-rag 0.12.0__py3-none-any.whl → 0.12.2__py3-none-any.whl

java_codebase_rag/watch/lock.py

@@ -1,201 +0,0 @@
-"""Project-level pidfile + ``fcntl.flock`` mutual exclusion for ``jrag watch``.
-
-``ProjectLock`` is the single-writer primitive the watch daemon (Task 11)
-acquires so that at most one watcher — and no concurrent manual
-``jrag increment`` — runs per project.
-
-The lock is keyed on the project's index dir: the pidfile path comes from
-``paths.pid_path(index_dir)`` (Task 3). We hold an advisory exclusive flock on
-that file for the lifetime of the ``ProjectLock`` object; the file also carries
-the holder's pid so other tools can report who holds it (``read_holder``).
-
-Unix-only by design. The ``fcntl`` import is guarded so that, on a platform
-without it, constructing a ``ProjectLock`` fails cleanly with
-``WatchUnsupportedPlatform`` instead of crashing at import time.
-"""
-
-import os
-from pathlib import Path
-
-try:  # Unix-only; absent on Windows.
-    import fcntl
-except ImportError:  # pragma: no cover - exercised via monkeypatch in tests.
-    fcntl = None
-
-from .paths import pid_path
-
-
-def _read_pid_file(path: Path):
-    """Return the integer pid in ``path``, or ``None``.
-
-    ``None`` covers: missing file, empty contents, or non-integer contents.
-    """
-    try:
-        raw = path.read_text().strip()
-    except (FileNotFoundError, OSError):
-        return None
-    if not raw:
-        return None
-    try:
-        return int(raw)
-    except ValueError:
-        return None
-
-
-class LockHeldError(Exception):
-    """Raised by ``ProjectLock.acquire`` when the project lock is held elsewhere.
-
-    Attributes:
-        pid: the pid currently recorded in the pid file, or ``None`` if it could
-            not be read/parsed (e.g. the file was empty).
-        path: the pid file ``Path``.
-    """
-
-    def __init__(self, pid, path: Path):
-        self.pid = pid
-        self.path = path
-        super().__init__(f"project lock held by pid={pid!r} at {path}")
-
-
-class WatchUnsupportedPlatform(Exception):
-    """Raised when the host platform lacks ``fcntl`` (the daemon is Unix-only)."""
-
-
-class ProjectLock:
-    """Exclusive per-project lock backed by a pidfile + ``fcntl.flock``.
-
-    The flock is held for the lifetime of the object: ``acquire`` opens the pid
-    file and takes ``LOCK_EX | LOCK_NB`` on it, retaining the file handle;
-    ``release`` closes that handle (which releases the flock) and unlinks the
-    pid file if it still records our pid.
-    """
-
-    def __init__(self, index_dir: Path):
-        if fcntl is None:
-            raise WatchUnsupportedPlatform(
-                "jrag watch requires fcntl, which is unavailable on this platform"
-            )
-        self.index_dir = index_dir
-        self.pid_path: Path = pid_path(index_dir)
-        self._fh = None  # retained file handle while we hold the flock
-
-    # ------------------------------------------------------------------
-    # pid file helpers
-    # ------------------------------------------------------------------
-
-    def _read_pid(self):
-        """Return the integer pid recorded in our pid file, or ``None``."""
-        return _read_pid_file(self.pid_path)
-
-    # ------------------------------------------------------------------
-    # acquire / release
-    # ------------------------------------------------------------------
-
-    def acquire(self) -> None:
-        """Take the exclusive lock, writing our pid into the pid file.
-
-        Opens the pid file read/write (creating it if absent), then takes
-        ``LOCK_EX | LOCK_NB``. If another holder blocks us, raise
-        ``LockHeldError`` carrying the pid recorded in the file (or ``None`` if
-        unreadable). On success, (over)write our pid and keep the handle open.
-        """
-        # "r+" preserves an existing holder's pid so we can report it on
-        # contention; fall back to "w+" only when the file does not yet exist
-        # (so we never truncate a real pid file before reading it).
-        try:
-            fh = open(self.pid_path, "r+")
-        except FileNotFoundError:
-            fh = open(self.pid_path, "w+")
-
-        try:
-            fcntl.flock(fh.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
-        except BlockingIOError:
-            fh.close()
-            raise LockHeldError(self._read_pid(), self.pid_path)
-        except OSError:
-            # Unexpected flock failure — don't leak the handle.
-            fh.close()
-            raise
-
-        # We hold the lock: record our pid (overwriting any stale value).
-        fh.seek(0)
-        fh.truncate()
-        fh.write(f"{os.getpid()}\n")
-        fh.flush()
-        self._fh = fh
-
-    def release(self) -> None:
-        """Release the flock and, if the pid file still names us, unlink it.
-
-        Closing the handle releases the flock. We only unlink the pid file when
-        its contents still equal our pid, so we never clobber a successor's file
-        if they acquired between our close and our unlink.
-        """
-        if self._fh is not None:
-            try:
-                self._fh.close()
-            finally:
-                self._fh = None
-
-        if self._read_pid() == os.getpid():
-            try:
-                self.pid_path.unlink()
-            except FileNotFoundError:
-                pass
-
-    # ------------------------------------------------------------------
-    # introspection
-    # ------------------------------------------------------------------
-
-    def is_holder(self) -> bool:
-        """True iff this lock currently holds the project lock.
-
-        Implementation note on flock semantics: ``flock`` treats separate file
-        descriptors even within a single process as independent holders, so a
-        probe handle CANNOT acquire ``LOCK_EX | LOCK_NB`` while our retained
-        handle holds it. The probe therefore FAILS exactly when the lock is
-        held (by us or another). Combined with the pid file recording our own
-        pid, that means: probe blocked AND our pid on disk => we are the holder.
-
-        (The prose in the task brief said the probe would "succeed"; on Unix
-        flock the polarity is inverted. See the task-2 report.)
-        """
-        try:
-            probe = open(self.pid_path, "r+")
-        except FileNotFoundError:
-            return False
-        try:
-            try:
-                fcntl.flock(probe.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
-            except BlockingIOError:
-                # Held by someone; it is us iff our pid is on disk.
-                return self._read_pid() == os.getpid()
-            # Probe acquired the lock => it was free => we do not hold it.
-            fcntl.flock(probe.fileno(), fcntl.LOCK_UN)
-            return False
-        finally:
-            probe.close()
-
-    @classmethod
-    def read_holder(cls, index_dir: Path):
-        """Return the live holder's pid, or ``None`` if the lock is free/stale.
-
-        Reads the pid file and returns the recorded pid iff a process with that
-        pid is currently alive (``os.kill(pid, 0)``); otherwise ``None`` (file
-        missing, unreadable, or naming a dead/stale pid). Does NOT take or test
-        the flock, and does not require ``fcntl``.
-        """
-        path = pid_path(index_dir)
-        pid = _read_pid_file(path)
-        if pid is None:
-            return None
-        try:
-            os.kill(pid, 0)
-        except ProcessLookupError:
-            # No such process => stale.
-            return None
-        except PermissionError:
-            # The pid exists but is not ours to signal — it is alive, just owned
-            # by another user, so it is a legitimate holder.
-            return pid
-        return pid

java_codebase_rag/watch/paths.py

@@ -1,76 +0,0 @@
-"""Runtime socket/pid/state path derivation for the jrag watch daemon.
-
-Pure-path logic only — no sockets, no I/O except mkdir for the runtime dir.
-No dependencies on other watch modules.
-"""
-
-import getpass
-import hashlib
-import os
-import sys
-import tempfile
-from pathlib import Path
-
-
-def runtime_dir() -> Path:
-    """Return the per-user runtime directory, created if missing.
-
-    Resolution order:
-    1. env XDG_RUNTIME_DIR
-    2. env TMPDIR
-    3. ~/Library/Caches/JragWatch on macOS (sys.platform == "darwin")
-    4. tempfile.gettempdir() / f"jrag-watch-{getpass.getuser()}"
-
-    The directory is created with parents=True, exist_ok=True before returning.
-    """
-    # 1. XDG_RUNTIME_DIR
-    if "XDG_RUNTIME_DIR" in os.environ:
-        rt_dir = Path(os.environ["XDG_RUNTIME_DIR"])
-    # 2. TMPDIR
-    elif "TMPDIR" in os.environ:
-        rt_dir = Path(os.environ["TMPDIR"])
-    # 3. macOS-specific path
-    elif sys.platform == "darwin":
-        home = Path(os.environ.get("HOME") or os.path.expanduser("~"))
-        rt_dir = home / "Library" / "Caches" / "JragWatch"
-    # 4. Fallback
-    else:
-        rt_dir = Path(tempfile.gettempdir()) / f"jrag-watch-{getpass.getuser()}"
-
-    # Create if missing
-    rt_dir.mkdir(parents=True, exist_ok=True)
-    return rt_dir
-
-
-def project_key(index_dir: Path) -> str:
-    """Return the first 12 hex characters of SHA256 of the resolved index_dir path.
-
-    The path is resolved before hashing so symlinks/relative paths are stable.
-    """
-    resolved = str(index_dir.resolve())
-    hash_hex = hashlib.sha256(resolved.encode()).hexdigest()
-    return hash_hex[:12]
-
-
-def socket_path(index_dir: Path) -> Path:
-    """Return the Unix socket path for a given index_dir.
-
-    Format: runtime_dir() / "jrag-watch-{project_key(index_dir)}.sock"
-    """
-    return runtime_dir() / f"jrag-watch-{project_key(index_dir)}.sock"
-
-
-def pid_path(index_dir: Path) -> Path:
-    """Return the pidfile path for a given index_dir.
-
-    Format: runtime_dir() / "jrag-watch-{project_key(index_dir)}.pid"
-    """
-    return runtime_dir() / f"jrag-watch-{project_key(index_dir)}.pid"
-
-
-def state_path(index_dir: Path) -> Path:
-    """Return the state file path for a given index_dir.
-
-    Format: runtime_dir() / "jrag-watch-{project_key(index_dir)}.state"
-    """
-    return runtime_dir() / f"jrag-watch-{project_key(index_dir)}.state"

java_codebase_rag/watch/protocol.py

@@ -1,122 +0,0 @@
-"""IPC request/response contract + NDJSON codec for jrag watch daemon.
-
-Pure data + codec logic: dataclasses, protocol version, valid commands,
-encode/decode to newline-delimited JSON, and protocol mismatch exception.
-No sockets, no I/O, no dependency on other watch modules.
-"""
-
-import json
-from dataclasses import asdict, dataclass
-from typing import Any
-
-PROTOCOL_VERSION: int = 1
-
-VALID_CMDS: frozenset[str] = frozenset({
-    "search",
-    "find",
-    "inspect",
-    "callers",
-    "callees",
-    "flow",
-})
-
-# Error kind constants — used as Response.ErrorShape.kind values.
-ERR_UNKNOWN_COMMAND = "unknown_command"
-ERR_BAD_ARGS = "bad_args"
-ERR_BACKEND_ERROR = "backend_error"
-ERR_STALE_INDEX = "stale_index"
-ERR_BUSY = "busy"
-
-
-class ProtocolMismatch(Exception):
-    """Raised when the protocol version in a request/response doesn't match PROTOCOL_VERSION."""
-
-    def __init__(self, got: int):
-        self.got = got
-        super().__init__(f"Protocol version mismatch: expected {PROTOCOL_VERSION}, got {got}")
-
-
-@dataclass
-class Request:
-    """IPC request from client to daemon."""
-
-    v: int
-    cmd: str
-    args: dict[str, Any]
-
-
-@dataclass
-class ErrorShape:
-    """Error detail in a failed Response."""
-
-    kind: str
-    message: str
-
-
-@dataclass
-class Response:
-    """IPC response from daemon to client."""
-
-    v: int
-    ok: bool
-    result: Any | None = None
-    error: ErrorShape | None = None
-
-
-def encode_request(r: Request) -> bytes:
-    """Encode a Request to newline-delimited JSON."""
-    return (json.dumps(asdict(r), default=str) + "\n").encode("utf-8")
-
-
-def decode_request(line: bytes) -> Request:
-    """Decode a Request from newline-delimited JSON.
-
-    Raises:
-        ProtocolMismatch: if the protocol version doesn't match
-        ValueError: if the command is invalid or line is blank
-    """
-    if not line or line.strip() == b"":
-        raise ValueError("Blank line")
-
-    parsed = json.loads(line.decode("utf-8"))
-
-    if parsed["v"] != PROTOCOL_VERSION:
-        raise ProtocolMismatch(got=parsed["v"])
-
-    if parsed["cmd"] not in VALID_CMDS:
-        raise ValueError(f"Unknown command: {parsed['cmd']}")
-
-    return Request(**parsed)
-
-
-def encode_response(r: Response) -> bytes:
-    """Encode a Response to newline-delimited JSON."""
-    return (json.dumps(asdict(r), default=str) + "\n").encode("utf-8")
-
-
-def decode_response(line: bytes) -> Response:
-    """Decode a Response from newline-delimited JSON.
-
-    Raises:
-        ProtocolMismatch: if the protocol version doesn't match
-        ValueError: if the line is blank
-    """
-    if not line or line.strip() == b"":
-        raise ValueError("Blank line")
-
-    parsed = json.loads(line.decode("utf-8"))
-
-    if parsed["v"] != PROTOCOL_VERSION:
-        raise ProtocolMismatch(got=parsed["v"])
-
-    # Reconstruct ErrorShape if present
-    error = None
-    if parsed.get("error"):
-        error = ErrorShape(**parsed["error"])
-
-    return Response(
-        v=parsed["v"],
-        ok=parsed["ok"],
-        result=parsed.get("result"),
-        error=error,
-    )

java_codebase_rag/watch/server.py

@@ -1,273 +0,0 @@
-"""Unix-socket server for the ``jrag watch`` daemon.
-
-Accepts newline-delimited JSON requests (Task 4's protocol), dispatches each to
-the matching read-command payload core (Task 5), and writes the encoded
-response (Task 4's codec). Transport + dispatch only — the server stores nothing
-between requests except the warm resources and the operator config.
-
-Lifecycle (Task 11 wires this into the daemon process):
-
-  * ``start()``  binds an ``AF_UNIX`` / ``SOCK_STREAM`` socket to
-    :func:`paths.socket_path`, ``chmod 0o600``, ``listen(8)``, and spawns an
-    accept thread running :meth:`serve`.
-  * ``serve()``  is the accept loop. Each connection is handled INLINE (the read
-    commands are fast): read newline-delimited bytes, decode, dispatch, encode,
-    flush. Multiple pipelined requests on one connection are each answered; a
-    connection that closes mid-line is dropped silently.
-  * ``shutdown()``  closes the listening socket and joins the accept thread.
-"""
-
-from __future__ import annotations
-
-import argparse
-import dataclasses
-import logging
-import socket
-import threading
-from typing import TYPE_CHECKING, Any, Callable
-
-from java_codebase_rag.jrag import _IndexStale
-from java_codebase_rag.read_payloads import (
-    callers_payload,
-    callees_payload,
-    find_payload,
-    flow_payload,
-    inspect_payload,
-    search_payload,
-)
-from java_codebase_rag.watch import paths
-from java_codebase_rag.watch.lock import ProjectLock
-from java_codebase_rag.watch.protocol import (
-    ERR_BAD_ARGS,
-    ERR_BACKEND_ERROR,
-    ERR_STALE_INDEX,
-    ERR_UNKNOWN_COMMAND,
-    PROTOCOL_VERSION,
-    ErrorShape,
-    ProtocolMismatch,
-    Request,
-    Response,
-    decode_request,
-    encode_response,
-)
-
-if TYPE_CHECKING:
-    # Type-only: the server never constructs these (the daemon passes them in),
-    # so they are not needed at import time. Avoids coupling this transport
-    # module to the heavy warm-resources/config import chain on minimal installs.
-    from java_codebase_rag.config import ResolvedOperatorConfig
-    from java_codebase_rag.warm import WarmResources
-
-log = logging.getLogger(__name__)
-
-# cmd -> payload core (Task 5). ``dispatch`` looks cmds up here; it ALSO defends
-# in depth against an unknown cmd (returns ERR_UNKNOWN_COMMAND) even though
-# ``decode_request`` already rejects anything outside VALID_CMDS — so a direct
-# caller of ``dispatch`` (or a future divergence between the two sets) still
-# gets the right error kind instead of a KeyError.
-PAYLOAD_FNS: dict[str, Callable[[argparse.Namespace, Any, Any], Any]] = {
-    "search": search_payload,
-    "find": find_payload,
-    "inspect": inspect_payload,
-    "callers": callers_payload,
-    "callees": callees_payload,
-    "flow": flow_payload,
-}
-
-
-def serialize(payload: Any) -> Any:
-    """Return a JSON-safe representation of a payload core's return value.
-
-    The cold read path's ``--format json`` emits a rendered *Envelope* via
-    ``Envelope.to_json()`` (after ``project_envelope``). That requires the
-    handler-specific payload->Envelope projection, which lives in the ``jrag``
-    read handlers (``_cmd_search`` etc.) and is NOT a separable shared function
-    — it is tangled with the terminal-rendering code path. Per the task brief,
-    when that path is tangled we serialize the *payload* directly and let the
-    client (Task 8) reconstruct + render it locally with the same handler code:
-
-      * pydantic models  -> ``model_dump(mode="json")`` (search/find/inspect
-        ``*Output`` models, nested ``SymbolHit`` rows, etc.);
-      * dict / list      -> recursed element-wise;
-      * dataclass        -> ``dataclasses.asdict``;
-      * everything else  -> passed through (str/int/float/bool/None already
-        JSON-safe).
-
-    NOTE for Task 8: the daemon ships the serialized *payload*, not the rendered
-    envelope. The client must reconstruct the payload object and run the same
-    render path the cold ``jrag`` handler runs on it. ``encode_response`` then
-    ``json.dumps`` this structure, so the values here must already be JSON-safe.
-    """
-    if hasattr(payload, "model_dump"):
-        return payload.model_dump(mode="json")
-    if isinstance(payload, dict):
-        return {key: serialize(val) for key, val in payload.items()}
-    if isinstance(payload, (list, tuple)):
-        return [serialize(item) for item in payload]
-    if dataclasses.is_dataclass(payload) and not isinstance(payload, type):
-        return dataclasses.asdict(payload)
-    return payload
-
-
-class WatchServer:
-    """AF_UNIX socket server dispatching NDJSON requests to payload cores."""
-
-    def __init__(self, warm: "WarmResources", cfg: "ResolvedOperatorConfig") -> None:
-        self.warm = warm
-        self.cfg = cfg
-        self._sock: socket.socket | None = None
-        self._thread: threading.Thread | None = None
-        self._stopping = threading.Event()
-
-    # -- lifecycle ----------------------------------------------------------
-
-    def start(self) -> None:
-        """Bind the Unix socket (chmod 0o600), listen, spawn the accept thread."""
-        sock_path = paths.socket_path(self.cfg.index_dir)
-        # Unlink a stale socket ONLY when no live daemon holds the project lock
-        # (a live holder means another daemon owns this path — leave it alone).
-        if sock_path.exists() and ProjectLock.read_holder(self.cfg.index_dir) is None:
-            try:
-                sock_path.unlink()
-            except OSError:
-                log.warning("Could not unlink stale socket %s", sock_path, exc_info=True)
-
-        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
-        sock.bind(str(sock_path))
-        try:
-            sock_path.chmod(0o600)
-        except OSError:
-            log.warning("Could not chmod socket %s to 0o600", sock_path, exc_info=True)
-        sock.listen(8)
-        self._sock = sock
-
-        self._stopping.clear()
-        self._thread = threading.Thread(
-            target=self.serve, name="jrag-watch-accept", daemon=True
-        )
-        self._thread.start()
-
-    def serve(self) -> None:
-        """Accept loop: one inline connection at a time (commands are fast)."""
-        sock = self._sock
-        if sock is None:
-            return
-        while not self._stopping.is_set():
-            try:
-                conn, _ = sock.accept()
-            except OSError:
-                # Listening socket closed (shutdown) -> exit cleanly. Any other
-                # OSError here is transient; the loop retries while not stopping.
-                if self._stopping.is_set() or self._sock is None:
-                    break
-                log.debug("accept() failed; retrying", exc_info=True)
-                continue
-            try:
-                self._handle(conn)
-            except Exception:  # noqa: BLE001 — a handler crash must not kill the loop
-                log.exception("Unhandled error servicing watch connection")
-            finally:
-                try:
-                    conn.close()
-                except OSError:
-                    pass
-
-    def shutdown(self) -> None:
-        """Close the listening socket and join the accept thread."""
-        self._stopping.set()
-        if self._sock is not None:
-            try:
-                self._sock.close()
-            except OSError:
-                pass
-            self._sock = None
-        thread = self._thread
-        if thread is not None and thread is not threading.current_thread():
-            thread.join(timeout=2.0)
-        self._thread = None
-
-    # -- per-connection handling -------------------------------------------
-
-    def _handle(self, conn: socket.socket) -> None:
-        """Read newline-delimited requests, dispatch, write responses.
-
-        Loops so multiple pipelined requests on one connection are each
-        answered. A peer that closes mid-line (a partial buffer with no
-        trailing newline when recv returns empty) is dropped silently.
-        """
-        buffer = b""
-        while True:
-            # Answer every complete line currently buffered.
-            while b"\n" in buffer:
-                line, _, buffer = buffer.partition(b"\n")
-                response = self._respond_to_line(line)
-                try:
-                    conn.sendall(encode_response(response))
-                except OSError:
-                    return  # peer gone — stop servicing this connection
-            # Need more bytes.
-            try:
-                chunk = conn.recv(4096)
-            except OSError:
-                return
-            if not chunk:
-                return  # connection closed; any trailing partial line is dropped
-            buffer += chunk
-
-    def _respond_to_line(self, line: bytes) -> Response:
-        """Decode one request line and dispatch it, mapping decode errors."""
-        try:
-            req = decode_request(line)
-        except (ProtocolMismatch, ValueError) as exc:
-            # ProtocolMismatch (wrong v) and ValueError (blank line / unknown
-            # cmd as decode sees it) both surface to the client as bad_args.
-            return Response(
-                v=PROTOCOL_VERSION,
-                ok=False,
-                error=ErrorShape(ERR_BAD_ARGS, str(exc)),
-            )
-        return self.dispatch(req, self.warm, self.cfg)
-
-    # -- dispatch -----------------------------------------------------------
-
-    def dispatch(self, req: Request, warm: "WarmResources", cfg: Any) -> Response:
-        """Map a decoded :class:`Request` to a :class:`Response` via the cmd core.
-
-        Rebuilds ``args = argparse.Namespace(**req.args)`` (the client sends the
-        full parsed-namespace dict; keys are argparse ``dest`` names) and calls
-        ``<cmd>_payload(args, cfg, warm.graph())``. Error mapping (pinned
-        contract): ``_IndexStale`` -> ``stale_index``;
-        ``(ProtocolMismatch, ValueError)`` -> ``bad_args``; any other
-        ``Exception`` (incl. :class:`PayloadError`) -> ``backend_error``;
-        unknown cmd -> ``unknown_command`` (defense in depth).
-        """
-        payload_fn = PAYLOAD_FNS.get(req.cmd)
-        if payload_fn is None:
-            return Response(
-                v=PROTOCOL_VERSION,
-                ok=False,
-                error=ErrorShape(ERR_UNKNOWN_COMMAND, f"Unknown command: {req.cmd}"),
-            )
-
-        args = argparse.Namespace(**req.args)
-        try:
-            payload = payload_fn(args, cfg, warm.graph())
-        except _IndexStale as exc:
-            return Response(
-                v=PROTOCOL_VERSION,
-                ok=False,
-                error=ErrorShape(ERR_STALE_INDEX, str(exc)),
-            )
-        except (ProtocolMismatch, ValueError) as exc:
-            return Response(
-                v=PROTOCOL_VERSION,
-                ok=False,
-                error=ErrorShape(ERR_BAD_ARGS, str(exc)),
-            )
-        except Exception as exc:  # noqa: BLE001 — includes PayloadError; -> backend_error
-            return Response(
-                v=PROTOCOL_VERSION,
-                ok=False,
-                error=ErrorShape(ERR_BACKEND_ERROR, str(exc)),
-            )
-        return Response(v=PROTOCOL_VERSION, ok=True, result=serialize(payload))