bareagent-cli 0.1.0__py3-none-any.whl

bareagent/lsp/config.py

@@ -0,0 +1,134 @@
+"""LSP server configuration parsing.
+
+Reads a ``[lsp]`` block (plus ``[[lsp.servers]]`` array) from a TOML-derived
+dict and returns typed dataclasses. Each server declares the multilspy
+``code_language`` and the file extensions that route to it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .errors import LSPError
+
+# 15s covers pyright startup + initial project scan on a medium repo. Larger
+# projects (or rust-analyzer / jdtls) may need to bump this in user config.
+_DEFAULT_START_TIMEOUT = 15.0
+
+
+@dataclass(slots=True)
+class LSPServerConfig:
+    """One language server entry."""
+
+    # multilspy ``code_language`` value (e.g. ``"python"`` / ``"typescript"`` /
+    # ``"rust"``). Must be unique across the config — duplicates are rejected
+    # by :func:`parse_lsp_config`.
+    language: str
+    # File suffixes (lowercased, leading dot) that route to this server.
+    extensions: list[str] = field(default_factory=list)
+    # Passed through to multilspy as ``initialization_options`` (LSP-specific
+    # config; e.g. pyright's ``python.pythonPath``). ``None`` means "send no
+    # options" — equivalent to ``null`` in LSP wire format.
+    initialization_options: dict[str, Any] | None = None
+
+
+@dataclass(slots=True)
+class LSPConfig:
+    """Top-level LSP configuration."""
+
+    servers: list[LSPServerConfig] = field(default_factory=list)
+    # Hybrid auto-diagnostics-on-edit feature flag. Parsed in this PR for
+    # forward compatibility; the actual consumer lands in child B.
+    auto_diagnostics_on_edit: bool = False
+    # Per-server start timeout (seconds). Each server handshake gets this
+    # budget independently inside ``LanguageServerManager.start_all``.
+    start_timeout: float = _DEFAULT_START_TIMEOUT
+
+
+def parse_lsp_config(raw: dict[str, Any]) -> LSPConfig:
+    """Parse a TOML-derived dict (the ``[lsp]`` section) into ``LSPConfig``.
+
+    Accepts either the full document (where ``lsp`` is a key) or the ``[lsp]``
+    block itself. Missing or empty ``lsp`` yields an empty config with
+    ``servers=[]``. Unknown keys are silently ignored to stay forward-compatible.
+    """
+    if not isinstance(raw, dict):
+        raise LSPError(f"lsp config must be a table, got {type(raw).__name__}")
+
+    block = raw.get("lsp", raw)
+    if block is None:
+        return LSPConfig()
+    if not isinstance(block, dict):
+        raise LSPError("'lsp' must be a table")
+
+    cfg = LSPConfig(
+        auto_diagnostics_on_edit=_bool(block, "auto_diagnostics_on_edit", False),
+        start_timeout=_float(block, "start_timeout", _DEFAULT_START_TIMEOUT),
+    )
+
+    servers_raw = block.get("servers", [])
+    if not isinstance(servers_raw, list):
+        raise LSPError("'lsp.servers' must be an array of tables")
+
+    seen: set[str] = set()
+    for index, entry in enumerate(servers_raw):
+        if not isinstance(entry, dict):
+            raise LSPError(f"lsp.servers[{index}] must be a table")
+        server = _parse_server(entry, index)
+        if server.language in seen:
+            raise LSPError(f"duplicate lsp server language: {server.language!r}")
+        seen.add(server.language)
+        cfg.servers.append(server)
+    return cfg
+
+
+def _parse_server(entry: dict[str, Any], index: int) -> LSPServerConfig:
+    language = entry.get("language")
+    if not isinstance(language, str) or not language:
+        raise LSPError(
+            f"lsp.servers[{index}].language is required and must be a non-empty string"
+        )
+
+    extensions_raw = entry.get("extensions")
+    if not isinstance(extensions_raw, list) or not extensions_raw:
+        raise LSPError(
+            f"lsp.servers[{language}].extensions is required and must be a "
+            "non-empty list of strings"
+        )
+    if not all(isinstance(ext, str) and ext for ext in extensions_raw):
+        raise LSPError(
+            f"lsp.servers[{language}].extensions must contain non-empty strings"
+        )
+    extensions = [ext.lower() for ext in extensions_raw]
+    for ext in extensions:
+        if not ext.startswith("."):
+            raise LSPError(
+                f"lsp.servers[{language}].extensions entries must start with '.', got {ext!r}"
+            )
+
+    init_options = entry.get("initialization_options")
+    if init_options is not None and not isinstance(init_options, dict):
+        raise LSPError(
+            f"lsp.servers[{language}].initialization_options must be a table if provided"
+        )
+
+    return LSPServerConfig(
+        language=language,
+        extensions=extensions,
+        initialization_options=dict(init_options) if init_options is not None else None,
+    )
+
+
+def _bool(block: dict[str, Any], key: str, default: bool) -> bool:
+    value = block.get(key, default)
+    if not isinstance(value, bool):
+        raise LSPError(f"lsp.{key} must be a boolean, got {value!r}")
+    return value
+
+
+def _float(block: dict[str, Any], key: str, default: float) -> float:
+    value = block.get(key, default)
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise LSPError(f"lsp.{key} must be a number, got {value!r}")
+    return float(value)

bareagent/lsp/coord.py

@@ -0,0 +1,118 @@
+"""Coordinate and URI helpers shared by every LSP tool handler.
+
+Tools take 1-based (line, column) from the LLM (matching editor convention)
+and convert to 0-based for LSP requests. Results are converted back to
+1-based before they reach the model.
+
+The URI helpers prefer multilspy's ``PathUtils`` when available; otherwise
+they fall back to a hand-written ``file:///`` construction that mirrors the
+forms multilspy / the major language servers accept (Windows drive letters
+upper-cased, no ``%3A`` encoding of the colon).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import cast
+from urllib.parse import unquote, urlparse
+
+
+def line_col_1_to_0(line: int, col: int) -> tuple[int, int]:
+    """Convert 1-based editor coordinates to 0-based LSP coordinates.
+
+    Position (1, 1) (the first character of the first line) maps to
+    (0, 0). Values < 1 are clamped to 0 — LSP servers tolerate clamping
+    better than they tolerate negative indices.
+    """
+    return (max(line - 1, 0), max(col - 1, 0))
+
+
+def line_col_0_to_1(line: int, col: int) -> tuple[int, int]:
+    """Convert 0-based LSP coordinates back to 1-based editor coordinates."""
+    return (line + 1, col + 1)
+
+
+def path_to_document_uri(path: str) -> str:
+    """Convert a filesystem path to a ``file://`` URI.
+
+    Prefers multilspy's ``PathUtils.path_to_uri`` when available so the URI
+    shape matches what multilspy internally sends to the server. The fallback
+    constructs ``file:///<abs-path>`` directly, leaving Windows drive letters
+    upper-cased and the colon un-encoded (the form rust-analyzer, pyright,
+    gopls all accept).
+    """
+    helper = _multilspy_path_to_uri()
+    if helper is not None:
+        try:
+            return helper(path)
+        except Exception:
+            pass  # fall through to manual construction
+
+    abs_path = os.path.abspath(path)
+    # Normalize separators to forward slashes for the URI form.
+    normalized = abs_path.replace("\\", "/")
+    if normalized.startswith("/"):
+        # POSIX absolute path: file:///abs/path
+        return f"file://{normalized}"
+    # Windows: D:/code/... → file:///D:/code/...
+    return f"file:///{normalized}"
+
+
+def document_uri_to_path(uri: str) -> str:
+    """Convert a ``file://`` URI back to a native filesystem path.
+
+    Handles both ``file:///D:/foo`` and ``file:///D%3A/foo`` (percent-encoded
+    drive letter) forms. Non-``file:`` URIs are returned unchanged so callers
+    can decide how to handle remote / virtual documents.
+    """
+    if not uri.startswith("file:"):
+        return uri
+    parsed = urlparse(uri)
+    raw = unquote(parsed.path)
+    # On Windows ``urlparse('file:///D:/foo').path`` yields ``/D:/foo``; strip
+    # the leading slash so the result is a real native path.
+    if os.name == "nt" and len(raw) >= 3 and raw[0] == "/" and raw[2] == ":":
+        raw = raw[1:]
+    return raw
+
+
+def to_repo_relative(path: str, repository_root: str) -> str:
+    """Convert an absolute or relative file path to a path relative to the
+    repository root.
+
+    multilspy's request_* methods expect a relative path. If ``path`` is
+    already relative, return it unchanged. If it cannot be made relative to
+    ``repository_root`` (e.g. on a different drive), return the original
+    ``path`` and let multilspy report the error.
+    """
+    try:
+        return os.path.relpath(path, start=repository_root)
+    except ValueError:
+        return path
+
+
+# ---------------------------------------------------------------------------
+# multilspy path-utils delegation
+# ---------------------------------------------------------------------------
+
+
+def _multilspy_path_to_uri():  # pragma: no cover — exercised only when multilspy is present
+    """Return ``multilspy.PathUtils.path_to_uri`` (or None) without crashing.
+
+    Kept in a helper so the import is attempted lazily and never raises out
+    to the caller. multilspy's exact module path differs across versions;
+    we probe the most common ones.
+    """
+    try:
+        from multilspy.multilspy_utils import PathUtils  # type: ignore
+    except Exception:
+        return None
+    helper = getattr(PathUtils, "path_to_uri", None)
+    if not callable(helper):
+        return None
+
+    def _bound(path: str) -> str:
+        return cast(str, helper(str(Path(path).resolve())))
+
+    return _bound

bareagent/lsp/diagnostics.py

@@ -0,0 +1,240 @@
+"""Diagnostic snapshot + diff helpers for the Hybrid auto-diagnostics hook.
+
+Surfaces three small primitives:
+
+* :func:`snapshot_diagnostics` — read whatever diagnostics the LSP manager has
+  for ``file_path`` right now, as a normalized list of :class:`Diagnostic`.
+* :func:`diff_diagnostics` — given two snapshots (before / after), return the
+  rows that appeared in ``after`` but not in ``before``. Equivalence is the
+  five-tuple ``(file, line, col, severity, message)`` (see :class:`DiagnosticKey`).
+* :func:`maybe_diagnostics_appendix` — handler-side entry point that wires the
+  pieces together and answers "should I append a diagnostics paragraph to my
+  tool result?". Returns ``None`` whenever LSP is unavailable, the config flag
+  is off, or there were no newly-introduced diagnostics — i.e. the **happy
+  path returns None** so the cost of feature-disabled callers is ~zero.
+
+multilspy 0.0.15 explicitly registers ``do_nothing`` for
+``textDocument/publishDiagnostics`` on every bundled language-server adapter
+(see ``multilspy/language_servers/*/<server>.py``). There is no public pull-
+diagnostics surface on ``SyncLanguageServer`` either. To bridge the gap, the
+manager hooks the underlying ``LanguageServerHandler.on_notification_handlers``
+post-handshake and routes publishDiagnostics into a per-server cache; this
+module just reads from there via ``manager.get_diagnostics_snapshot(...)``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .config import LSPConfig
+    from .manager import LanguageServerManager
+
+
+@dataclass(frozen=True, slots=True)
+class Diagnostic:
+    """Normalized view of one LSP diagnostic.
+
+    ``line`` / ``col`` are **1-based** (matching the rest of the LSP tool
+    surface). ``severity`` is the editor-friendly label produced by
+    :func:`_severity_label` (e.g. ``"Error"``).
+    """
+
+    file: str
+    line: int
+    col: int
+    severity: str
+    message: str
+    source: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class DiagnosticKey:
+    """Five-tuple identity for a diagnostic — see PRD diff algorithm.
+
+    Two ``Diagnostic`` values that produce the same ``DiagnosticKey`` are
+    treated as the same diagnostic for diff purposes. ``source`` is excluded
+    deliberately: pyright sometimes leaves it blank, so including it would
+    cause spurious "newly introduced" hits on otherwise identical rows.
+    """
+
+    file: str
+    line: int
+    col: int
+    severity: str
+    message: str
+
+    @classmethod
+    def from_diag(cls, diag: Diagnostic) -> DiagnosticKey:
+        return cls(
+            file=diag.file,
+            line=diag.line,
+            col=diag.col,
+            severity=diag.severity,
+            message=diag.message,
+        )
+
+
+_SEVERITY_LABELS = {1: "Error", 2: "Warning", 3: "Info", 4: "Hint"}
+
+
+def _severity_label(severity: Any) -> str:
+    try:
+        return _SEVERITY_LABELS.get(int(severity), "Diagnostic")
+    except (TypeError, ValueError):
+        return "Diagnostic"
+
+
+def _normalize(file_path: str, raw: Any) -> Diagnostic | None:
+    """Convert a raw multilspy / LSP payload dict into a :class:`Diagnostic`.
+
+    Returns ``None`` when the row is too malformed to be useful (e.g. no
+    ``range``). The handlers never trust LSP server output blindly — pyright
+    has been known to send notifications with empty arrays, and our diff
+    algorithm requires a numeric position to compare against.
+    """
+    if not isinstance(raw, dict):
+        return None
+    range_ = raw.get("range") or {}
+    start = range_.get("start") if isinstance(range_, dict) else None
+    if not isinstance(start, dict):
+        return None
+    try:
+        line0 = int(start.get("line", 0) or 0)
+        col0 = int(start.get("character", 0) or 0)
+    except (TypeError, ValueError):
+        return None
+    severity = _severity_label(raw.get("severity"))
+    message = str(raw.get("message", ""))
+    source = str(raw.get("source", "") or "")
+    return Diagnostic(
+        file=file_path,
+        line=line0 + 1,  # 0-based LSP → 1-based for display + diff
+        col=col0 + 1,
+        severity=severity,
+        message=message,
+        source=source,
+    )
+
+
+def snapshot_diagnostics(
+    manager: LanguageServerManager,
+    file_path: str,
+) -> list[Diagnostic]:
+    """Return the manager's cached diagnostics for ``file_path``.
+
+    Reads through :meth:`LanguageServerManager.get_diagnostics_snapshot`, which
+    drains whatever ``publishDiagnostics`` notifications have arrived from the
+    server so far. Returns an empty list when:
+
+    * the file does not route to any configured server,
+    * the routed server is not RUNNING,
+    * the server hasn't published any diagnostics for the file yet.
+    """
+    raw_rows = manager.get_diagnostics_snapshot(file_path)
+    out: list[Diagnostic] = []
+    for raw in raw_rows:
+        diag = _normalize(file_path, raw)
+        if diag is not None:
+            out.append(diag)
+    return out
+
+
+def diff_diagnostics(
+    before: list[Diagnostic],
+    after: list[Diagnostic],
+) -> list[Diagnostic]:
+    """Return rows in ``after`` whose five-tuple key is absent from ``before``.
+
+    Order follows ``after`` so the appendix reads top-to-bottom in source
+    order. The function is pure — both inputs may be reused.
+    """
+    before_keys = {DiagnosticKey.from_diag(d) for d in before}
+    return [d for d in after if DiagnosticKey.from_diag(d) not in before_keys]
+
+
+def format_diagnostics(file_path: str, diags: list[Diagnostic]) -> str:
+    """Render newly-introduced diagnostics as a stable text block.
+
+    The format is fixed by the PRD so downstream tooling (and the LLM) can
+    detect the appendix by prefix::
+
+        Newly introduced diagnostics in <file>:
+        - [pyright Error] Line 12:5 — Cannot assign to variable 'x' because of its type
+
+    ``source`` defaults to ``"lsp"`` when the server didn't include one. The
+    leading file header is always emitted even if ``diags`` is empty so callers
+    that pre-filter still produce a useful message; in practice the caller
+    (``maybe_diagnostics_appendix``) skips the empty case entirely.
+    """
+    header = f"Newly introduced diagnostics in {file_path}:"
+    if not diags:
+        return header
+    lines = [header]
+    for diag in diags:
+        source = diag.source or "lsp"
+        lines.append(
+            f"- [{source} {diag.severity}] Line {diag.line}:{diag.col} — {diag.message}"
+        )
+    return "\n".join(lines)
+
+
+def maybe_diagnostics_appendix(
+    manager: LanguageServerManager | None,
+    lsp_config: LSPConfig | None,
+    file_path: str,
+    before: list[Diagnostic] | None,
+) -> str | None:
+    """Best-effort hook for edit/write handlers.
+
+    Returns the formatted appendix (with leading ``\\n\\n`` so the caller can
+    just ``result + appendix``) when **all** of the following are true:
+
+    * ``manager`` and ``lsp_config`` are both provided,
+    * ``lsp_config.auto_diagnostics_on_edit`` is True,
+    * the file routes to a RUNNING server,
+    * the after-snapshot has rows that were absent in ``before``.
+
+    Returns ``None`` otherwise. The config gate is the first check so callers
+    that disabled the feature pay only an attribute access (≪ 1µs). Any
+    unexpected exception is swallowed — the handler must keep working even if
+    the LSP subsystem is misbehaving.
+    """
+    if manager is None or lsp_config is None:
+        return None
+    if not lsp_config.auto_diagnostics_on_edit:
+        return None
+    if manager.language_for_file(file_path) is None:
+        return None
+    # ``get_server_for_file`` returns None when the server isn't RUNNING,
+    # which we treat the same as "no diagnostics to compare" — drop out
+    # silently rather than spamming an Error line on every edit.
+    if manager.get_server_for_file(file_path) is None:
+        return None
+
+    try:
+        # Briefly wait for pyright/etc. to publish the latest analysis pass.
+        # The manager exposes the per-file Event; a 1.5s budget is enough for
+        # incremental analysis on a medium repo and short enough to avoid
+        # noticeable handler latency. Race condition mitigation modeled after
+        # Serena's analysis_complete Event (see PRD Technical Approach).
+        manager.wait_for_diagnostics(file_path, timeout=1.5)
+        after = snapshot_diagnostics(manager, file_path)
+    except Exception:
+        return None
+
+    new_diags = diff_diagnostics(before or [], after)
+    if not new_diags:
+        return None
+    return "\n\n" + format_diagnostics(file_path, new_diags)
+
+
+__all__ = [
+    "Diagnostic",
+    "DiagnosticKey",
+    "diff_diagnostics",
+    "format_diagnostics",
+    "maybe_diagnostics_appendix",
+    "snapshot_diagnostics",
+]

bareagent/lsp/errors.py

@@ -0,0 +1,24 @@
+"""LSP error hierarchy.
+
+Layered failure types: handshake (initialize lifecycle) and call (a request to
+the language server raised or timed out). LSP tool execution failures
+(``request_*`` returning empty or a server-side error) are NOT exceptions —
+they flow back to the LLM as text via the tool handlers (see ``tools.py``).
+"""
+
+from __future__ import annotations
+
+
+class LSPError(Exception):
+    """Base class for all LSP-related failures."""
+
+
+class LSPHandshakeError(LSPError):
+    """Language server initialize/start handshake failed: timeout, multilspy
+    refused to launch, or the underlying server crashed during startup."""
+
+
+class LSPCallError(LSPError):
+    """A ``request_*`` call (definition / references / outline / diagnostics)
+    raised inside multilspy. Handlers catch this and return ``str(exc)`` to the
+    LLM."""