cubyte-lsp 0.1.0__tar.gz

cubyte_lsp-0.1.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: cubyte-lsp
+Version: 0.1.0
+Summary: Language Server Protocol implementation for cubyte.
+Author: cubyte authors
+Requires-Python: >=3.10

cubyte_lsp-0.1.0/README.md

@@ -0,0 +1,83 @@
+# cubyte-lsp
+
+A Language Server Protocol implementation for [cubyte](../README.md), the
+high-level language whose runtime is a Rubik's cube. The server speaks LSP
+3.17 over stdin/stdout and provides:
+
+- **Diagnostics** — the server shells out to the `cubyte` compiler and
+  converts its `[stage] line N: message` errors into LSP diagnostics
+  published on `textDocument/publishDiagnostics`.
+- **Hover** — shows the type, required register order, and (when available)
+  the physical register the variable is bound to, plus a short description
+  of built-in pieces, keywords, and the I/O register.
+- **Completion** — completes keywords, type names, piece labels
+  (`UF, UFL, DBR, …`), and identifiers visible in the current document.
+- **Go-to-definition / document symbols** — jumps to the declaration of a
+  variable, function-free label, or algorithm literal.
+- **Formatting** — a minimal, opinionated formatter that re-indents blocks
+  and aligns `:=` in a column. It is safe to call on unsaved buffers
+  because it operates on a string in/out.
+
+## Layout
+
+```
+lsp/
+├── server.py           # Entry point: starts the LSP, dispatches requests.
+├── analyzer.py         # Re-runs the cubyte compiler, parses diagnostics.
+├── features/
+│   ├── __init__.py
+│   ├── completion.py   # textDocument/completion
+│   ├── definition.py   # textDocument/definition
+│   ├── diagnostics.py  # Background publishDiagnostics loop
+│   ├── formatting.py   # textDocument/formatting
+│   ├── hover.py        # textDocument/hover
+│   └── symbols.py      # textDocument/documentSymbol
+├── knowledge/
+│   ├── __init__.py
+│   ├── keywords.py     # Built-in keyword metadata
+│   ├── pieces.py       # Piece-label metadata
+│   └── types.py        # Type + register-order metadata
+├── protocol/
+│   ├── __init__.py
+│   ├── jsonrpc.py      # Minimal stdlib LSP/JSON-RPC framing
+│   └── types.py        # Request/response dataclasses
+├── utils.py            # URI <-> path, range helpers
+├── pyproject.toml      # `python -m cubyte_lsp` entry point
+└── tests/
+    └── test_jsonrpc.py # Round-trip framing test (placeholder)
+```
+
+## Running
+
+The server expects the `cubyte` binary on `PATH` (or set `CUBYTE_BIN`).
+It is meant to be launched by an editor client, not by hand:
+
+```bash
+python -m cubyte_lsp             # default: read PATH for cubyte
+CUBYTE_BIN=/path/to/cubyte \
+  python -m cubyte_lsp           # explicit path
+```
+
+### Editor configuration
+
+`neovim` (with `nvim-lspconfig`):
+
+```lua
+require('lspconfig').cubyte_lsp.setup{
+  cmd = { 'python', '-m', 'cubyte_lsp' },
+  filetypes = { 'cubyte' },
+  root_dir = function(fname) return vim.fs.dirname(fname) end,
+}
+```
+
+`vscode`: see `editors/vscode-cubyte/README.md` (out of scope for this
+skeleton — left to whoever wires the extension together).
+
+## Status
+
+This is a skeleton: the JSON-RPC framing, document-state plumbing, and
+feature modules are in place, but only diagnostics and hover are wired
+through to real behaviour. Completion, definition, symbols, and
+formatting ship with sensible stub responses that the editor will
+display; flesh them out by filling in the marked `TODO(stub)` blocks in
+`features/*.py`.

cubyte_lsp-0.1.0/cubyte_lsp/__init__.py

@@ -0,0 +1,10 @@
+"""cubyte_lsp — Language Server Protocol for cubyte.
+
+Entry point: ``python -m cubyte_lsp`` (see ``server.py``).
+
+The package is organised so that each LSP feature lives in its own module
+under :mod:`cubyte_lsp.features`. The package itself only re-exports
+public names; importing submodules directly is supported.
+"""
+
+__all__ = ["server", "analyzer"]

cubyte_lsp-0.1.0/cubyte_lsp/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point so ``python -m cubyte_lsp`` works."""
+
+from .server import main
+
+if __name__ == "__main__":
+    main()

cubyte_lsp-0.1.0/cubyte_lsp/analyzer.py

@@ -0,0 +1,136 @@
+"""cubyte_lsp.analyzer — runs the cubyte compiler and parses its output.
+
+The compiler is the source of truth for diagnostics. We invoke it on a
+temporary copy of the in-memory buffer (the editor's text might not yet
+be saved to disk) and translate its ``[stage] line N: message`` stderr
+output into LSP :class:`Diagnostic` objects.
+
+The diagnostic mapping table is intentionally explicit: the cubyte exit
+code determines the LSP ``severity`` (``Error`` for everything) and the
+stage name becomes the diagnostic ``code`` so the editor can group them.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import re
+import shutil
+import tempfile
+from dataclasses import dataclass
+from typing import Optional
+
+from .protocol.types import Diagnostic, Position, Range
+
+log = logging.getLogger("cubyte_lsp.analyzer")
+
+# Stages reported by cubyte on stderr. The first capture group is the
+# stage name; the second is the line number (1-based per the compiler,
+# which we convert to 0-based for LSP). Many compiler errors come out as
+# ``<Stage> error at line N, column M: message``; we accept that form too.
+_STAGE_RE = re.compile(
+    r"^(?:"
+    r"\[(?P<stage_bracketed>\w+)\]\s+line\s+(?P<line1>\d+)\s*:\s*(?P<msg1>.*)$"
+    r"|"
+    r"(?P<stage_plain>\w+)\s+error\s+at\s+line\s+(?P<line2>\d+)\s*,"
+    r"\s*column\s+(?P<col>\d+)\s*:\s*(?P<msg2>.*)$"
+    r")"
+)
+
+
+@dataclass(frozen=True)
+class AnalysisResult:
+    diagnostics: tuple[Diagnostic, ...]
+    raw_stderr: str
+    raw_stdout: str
+    exit_code: int
+
+
+class CubyteAnalyzer:
+    """Invokes the ``cubyte`` binary on a buffer and reports diagnostics.
+
+    The analyzer writes the buffer to a temporary ``.cbyte`` file because
+    the compiler expects a real path (it derives intermediate filenames
+    from it). The file is cleaned up after the run; the analyzer never
+    touches the editor's on-disk file.
+    """
+
+    def __init__(self, binary: Optional[str] = None) -> None:
+        self._binary = binary or os.environ.get("CUBYTE_BIN") or shutil.which("cubyte")
+
+    @property
+    def available(self) -> bool:
+        return self._binary is not None
+
+    async def analyze(self, uri: str, text: str) -> AnalysisResult:
+        """Run the compiler on ``text`` and return its diagnostics."""
+        if not self.available:
+            log.warning("cubyte binary not found on PATH and CUBYTE_BIN not set")
+            return AnalysisResult((), "", "", -1)
+
+        # The compiler derives ``<stem>-pp.cbyte`` and ``<stem>.cubin`` from
+        # the input path; passing the full ``.cbyte`` filename lets those
+        # siblings land in the same tmp directory we own.
+        with tempfile.TemporaryDirectory(prefix="cubyte-lsp-") as tmp:
+            src_path = os.path.join(tmp, "buf.cbyte")
+            with open(src_path, "w", encoding="utf-8") as f:
+                f.write(text)
+
+            cmd = [self._binary, src_path, os.path.join(tmp, "buf.cubin")]
+            try:
+                proc = await asyncio.create_subprocess_exec(
+                    *cmd,
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.PIPE,
+                )
+                stdout, stderr = await proc.communicate()
+            except FileNotFoundError:
+                log.error("cubyte binary %s could not be executed", self._binary)
+                return AnalysisResult((), "", "", -1)
+
+            stderr_text = stderr.decode("utf-8", errors="replace")
+            stdout_text = stdout.decode("utf-8", errors="replace")
+            diagnostics = _parse_stderr(stderr_text)
+            return AnalysisResult(
+                diagnostics=tuple(diagnostics),
+                raw_stderr=stderr_text,
+                raw_stdout=stdout_text,
+                exit_code=proc.returncode if proc.returncode is not None else -1,
+            )
+
+
+def _parse_stderr(stderr: str) -> list[Diagnostic]:
+    diagnostics: list[Diagnostic] = []
+    for line in stderr.splitlines():
+        m = _STAGE_RE.match(line)
+        if not m:
+            continue
+        if m.group("stage_bracketed") is not None:
+            stage = m.group("stage_bracketed")
+            line_no = int(m.group("line1"))
+            col = 0
+            message = m.group("msg1").strip()
+        else:
+            stage = m.group("stage_plain")
+            line_no = int(m.group("line2"))
+            col = max(0, int(m.group("col")) - 1)
+            message = m.group("msg2").strip()
+
+        if line_no <= 0:
+            range_ = Range(start=Position(0, 0), end=Position(0, 0))
+        else:
+            # 0-based for LSP.
+            end_char = max(col + 1, len(message))
+            range_ = Range(
+                start=Position(line=line_no - 1, character=col),
+                end=Position(line=line_no - 1, character=end_char),
+            )
+        diagnostics.append(Diagnostic(
+            range=range_,
+            message=message,
+            severity=1,  # DiagnosticSeverity.Error
+            source="cubyte",
+            code=stage.lower(),
+        ))
+    return diagnostics

cubyte_lsp-0.1.0/cubyte_lsp/documents.py

@@ -0,0 +1,52 @@
+"""In-memory store of open cubyte documents.
+
+The LSP server is single-process and shared across all open files, so a
+plain :class:`dict` keyed on URI is sufficient. We also keep a simple
+generation counter so an in-flight analysis for an older version of the
+buffer can be discarded when a newer one arrives.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class Document:
+    uri: str
+    version: int = 0
+    text: str = ""
+    language_id: str = "cubyte"
+    generation: int = 0  # bumped on every didChange
+    # Last diagnostics produced by the analyzer, kept so the client can
+    # be re-served them after a server restart of the editor session.
+    last_diagnostics: tuple = field(default_factory=tuple)
+
+
+class DocumentStore:
+    def __init__(self) -> None:
+        self._docs: dict[str, Document] = {}
+
+    def open(self, uri: str, version: int, text: str, language_id: str) -> Document:
+        doc = Document(uri=uri, version=version, text=text, language_id=language_id)
+        self._docs[uri] = doc
+        return doc
+
+    def update(self, uri: str, version: int, text: str) -> Optional[Document]:
+        doc = self._docs.get(uri)
+        if doc is None:
+            return None
+        doc.version = version
+        doc.text = text
+        doc.generation += 1
+        return doc
+
+    def close(self, uri: str) -> None:
+        self._docs.pop(uri, None)
+
+    def get(self, uri: str) -> Optional[Document]:
+        return self._docs.get(uri)
+
+    def all(self) -> list[Document]:
+        return list(self._docs.values())

cubyte_lsp-0.1.0/cubyte_lsp/features/__init__.py

@@ -0,0 +1,16 @@
+"""cubyte_lsp.features — per-LSP-method implementations.
+
+Each module exports a single coroutine that takes the
+:class:`cubyte_lsp.protocol.jsonrpc.JsonRpcHandler` params dict and the
+open :class:`~cubyte_lsp.documents.Document` (or documents) and returns
+the JSON-serialisable LSP response body.
+
+The convention is:
+
+    async def feature_<name>(params: dict, doc: Document) -> dict | list | None
+
+``server.py`` wires these into JSON-RPC handlers. The feature modules
+never touch the wire directly.
+"""
+
+from . import completion, definition, diagnostics, formatting, hover, symbols  # noqa: F401

cubyte_lsp-0.1.0/cubyte_lsp/features/completion.py

@@ -0,0 +1,157 @@
+"""Completion provider.
+
+Returns three kinds of items:
+
+* Keywords, with a snippet form for the common shapes
+  (``let int : 4 $1 := $2;`` etc.).
+* Type names (``int``, ``alg``).
+* Piece labels (the 20 corner/edge names).
+* Identifiers visible in the current document — declared variables and
+  labels. We use a regex pass for now; a proper parser would let us
+  scope these to the right block. cubyte's scoping rule is purely
+  textual (a name is in scope only after the line that declares it), so
+  we filter the document-symbols pass by the cursor's character offset
+  and drop any declaration that comes at or after the cursor.
+
+The order is: keywords, types, then user identifiers, then pieces. The
+detail field shows the kind so editors can render it in a column.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Iterable, Optional
+
+from ..knowledge import keywords as kw
+from ..knowledge import pieces as pc
+from ..knowledge import types as ty
+from ..protocol.types import (
+    COMPLETION_CONSTANT,
+    COMPLETION_KEYWORD,
+    COMPLETION_TEXT,
+    COMPLETION_VARIABLE,
+    CompletionItem,
+    Position,
+)
+
+
+# Snippets for keywords. ``$1``, ``$2`` are tab stops the editor fills in.
+_SNIPPETS: dict[str, str] = {
+    "let":   "let int : 4 $1 := $2;",
+    "if":    "if not ($1 = 0) {\n\t$2\n}",
+    "while": "while not ($1 = 0) {\n\t$2\n}",
+    "goto":  "goto $1;",
+    "input": "input \"$1\";",
+    "output":"output;",
+    "apply": "apply $1;",
+}
+
+
+async def completion(params: dict, doc) -> list[dict]:
+    items: list[CompletionItem] = []
+
+    for k in kw.KEYWORDS:
+        items.append(CompletionItem(
+            label=k.name,
+            kind=COMPLETION_KEYWORD,
+            detail="keyword",
+            documentation=k.doc,
+            insert_text=_SNIPPETS.get(k.name, k.name),
+        ))
+
+    for t in ty.TYPES:
+        items.append(CompletionItem(
+            label=t.name,
+            kind=COMPLETION_KEYWORD,
+            detail="type",
+            documentation=t.doc,
+        ))
+
+    for piece in pc.PIECES:
+        items.append(CompletionItem(
+            label=piece.name,
+            kind=COMPLETION_CONSTANT,
+            detail="piece",
+            documentation=piece.doc,
+        ))
+
+    # Document-level symbols are scoped to the cursor: cubyte's scoping
+    # rule is purely textual, so a declaration at or after the cursor
+    # is not yet in scope and must not be suggested. If the client omits
+    # the position we fall back to offering everything.
+    cursor_offset = _cursor_offset(params, doc.text)
+    items.extend(_document_symbols(doc.text, cursor_offset))
+
+    return [it.to_dict() for it in items]
+
+
+def _cursor_offset(params: dict, text: str) -> Optional[int]:
+    """Translate the completion request's ``position`` to a char offset.
+
+    Returns ``None`` if the position is missing or invalid, in which case
+    the caller should treat the buffer as having no scoping filter
+    (offer every declared symbol).
+    """
+    raw = params.get("position")
+    if not isinstance(raw, dict):
+        return None
+    try:
+        position = Position.from_dict(raw)
+    except (KeyError, TypeError, ValueError):
+        return None
+    if position.line < 0 or position.character < 0:
+        return None
+    return _offset_for_line_col(text, position)
+
+
+def _offset_for_line_col(text: str, position: Position) -> int:
+    """Convert an LSP ``Position`` to a 0-based char offset.
+
+    Clamps a column past the end of a line to that line's end (editors
+    may report the column one past the last glyph when triggering
+    completion on a trailing newline). Returns ``len(text)`` for
+    positions past the end of the buffer.
+    """
+    line = 0
+    pos = 0
+    while pos <= len(text):
+        nl = text.find("\n", pos)
+        line_end = nl if nl != -1 else len(text)
+        if line == position.line:
+            col = min(position.character, line_end - pos)
+            return pos + col
+        if nl == -1:
+            return len(text)
+        line += 1
+        pos = nl + 1
+    return len(text)
+
+
+def _document_symbols(text: str, cursor_offset: Optional[int] = None) -> Iterable[CompletionItem]:
+    seen: set[str] = set()
+    # Variable declarations: `let (int|alg) [ : <order> ] name := ...`.
+    # cubyte scoping is textual — a `let` is in scope only from the line
+    # *after* its declaration. So when the cursor is on or before the
+    # declaration, the name must not be suggested (using it would be a
+    # typecheck error).
+    for m in re.finditer(r"let\s+(int|alg)\s*(?::\s*\d+\s+)?([A-Za-z_][A-Za-z_0-9]*)\s*:=", text):
+        if cursor_offset is not None and m.start() >= cursor_offset:
+            continue
+        name = m.group(2)
+        if name in seen:
+            continue
+        seen.add(name)
+        kind = "variable"
+        if m.group(1) == "alg":
+            kind = "algorithm"
+        yield CompletionItem(label=name, kind=COMPLETION_VARIABLE, detail=kind)
+    # Labels: `name:` at the start of a line (no `=` after). Labels in
+    # cubyte are valid ``goto`` targets from anywhere in the program
+    # (the typechecker collects all of them in a pre-pass), so we
+    # always offer them, regardless of cursor position.
+    for m in re.finditer(r"^([A-Za-z_][A-Za-z_0-9]*)\s*:\s*(?!=)", text, flags=re.MULTILINE):
+        name = m.group(1)
+        if name in seen:
+            continue
+        seen.add(name)
+        yield CompletionItem(label=name, kind=COMPLETION_TEXT, detail="label")

cubyte_lsp-0.1.0/cubyte_lsp/features/definition.py

@@ -0,0 +1,78 @@
+"""Go-to-definition.
+
+Stub implementation: walks the document for the identifier under the
+cursor and jumps to its declaration site (variable ``let`` or label).
+The position reported is the *start* of the declaration so the editor
+centres on the keyword.
+"""
+
+from __future__ import annotations
+
+import re
+
+from ..protocol.types import Position
+from ..utils import position_at
+
+
+_VAR_RE = re.compile(r"let\s+(int|alg)\s*(?::\s*\d+\s+)?([A-Za-z_][A-Za-z_0-9]*)\s*:=")
+_LABEL_RE = re.compile(r"^([A-Za-z_][A-Za-z_0-9]*)\s*:\s*(?!=)", re.MULTILINE)
+_IDENT_RE = re.compile(r"[A-Za-z_][A-Za-z_0-9]*")
+
+
+async def definition(params: dict, doc) -> list[dict] | None:
+    position = Position.from_dict(params["position"])
+    word = _word_at(doc.text, position)
+    if word is None:
+        return None
+
+    # Prefer a variable declaration, fall back to a label, fall back to None.
+    for pattern in (_VAR_RE, _LABEL_RE):
+        for m in pattern.finditer(doc.text):
+            name = m.group(2) if pattern is _VAR_RE else m.group(1)
+            if name != word:
+                continue
+            line = doc.text.count("\n", 0, m.start())
+            return [{
+                "uri": doc.uri,
+                "range": {
+                    "start": {"line": line, "character": 0},
+                    "end": {"line": line, "character": m.end() - m.start()},
+                },
+            }]
+    return None
+
+
+def _word_at(text: str, position: Position) -> str | None:
+    # Approximate the same algorithm as in hover.py. We do not import
+    # it to keep this module independent; the spec only requires we
+    # return the right identifier, not be clever about column edges.
+    offset = _offset_for(text, position)
+    if offset is None:
+        return None
+    start = offset
+    while start > 0 and _IDENT_RE.match(text[start - 1]):
+        start -= 1
+    end = offset
+    while end < len(text) and _IDENT_RE.match(text[end]):
+        end += 1
+    if start == end:
+        return None
+    return text[start:end]
+
+
+def _offset_for(text: str, position: Position) -> int | None:
+    line = 0
+    offset = 0
+    while offset <= len(text):
+        line_start = text.rfind("\n", 0, offset) + 1
+        line_end = text.find("\n", offset)
+        if line_end == -1:
+            line_end = len(text)
+        if line == position.line:
+            col = position.character - (offset - line_start)
+            if 0 <= col <= line_end - line_start:
+                return line_start + col
+            return None
+        offset = line_end + 1
+        line += 1
+    return None

cubyte_lsp-0.1.0/cubyte_lsp/features/diagnostics.py

@@ -0,0 +1,63 @@
+"""Diagnostics.
+
+Runs the analyzer in the background whenever a document changes and
+publishes the results via ``textDocument/publishDiagnostics``.
+
+We use ``asyncio.create_task`` so the editor stays responsive while the
+compiler runs. The :class:`~cubyte_lsp.documents.DocumentStore`
+generation counter is consulted before pushing — a late result for an
+older buffer is dropped on the floor.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import uuid
+
+from ..analyzer import CubyteAnalyzer
+from ..protocol.jsonrpc import JsonRpcHandler
+
+log = logging.getLogger("cubyte_lsp.diagnostics")
+
+
+class DiagnosticPublisher:
+    """Schedule analysis runs and publish the results."""
+
+    def __init__(self, rpc: JsonRpcHandler, analyzer: CubyteAnalyzer) -> None:
+        self._rpc = rpc
+        self._analyzer = analyzer
+        # Generation counter so old runs can be discarded.
+        self._counters: dict[str, int] = {}
+
+    def schedule(self, doc) -> None:
+        """Schedule an analysis for ``doc``.
+
+        Multiple calls collapse: if a run is already in flight we let it
+        finish, then re-schedule. This keeps the editor responsive
+        during fast typing bursts.
+        """
+        gen = doc.generation
+        self._counters[doc.uri] = gen
+        asyncio.create_task(self._run(doc, gen))
+
+    async def _run(self, doc, generation: int) -> None:
+        try:
+            result = await self._analyzer.analyze(doc.uri, doc.text)
+        except Exception:  # noqa: BLE001
+            log.exception("analyzer crashed for %s", doc.uri)
+            return
+
+        # Bail if the document changed while we were running.
+        if self._counters.get(doc.uri) != generation:
+            log.debug("discarding stale diagnostics for %s", doc.uri)
+            return
+
+        doc.last_diagnostics = result.diagnostics
+        await self._rpc.send_notification(
+            "textDocument/publishDiagnostics",
+            {
+                "uri": doc.uri,
+                "diagnostics": [d.to_dict() for d in result.diagnostics],
+            },
+        )

cubyte_lsp-0.1.0/cubyte_lsp/features/formatting.py

@@ -0,0 +1,70 @@
+"""Formatting.
+
+A minimal, safe formatter:
+
+* Strips trailing whitespace.
+* Re-indents ``{ ... }`` blocks using the editor's tab size (default 4).
+* Leaves all other content alone — the LSP spec encourages providers
+  that only do a *subset* of formatting, and we don't want to fight
+  users' existing conventions on ``:=`` alignment or comment style.
+
+The function is total: it never raises, so the editor can call it on
+any buffer without a try/except.
+"""
+
+from __future__ import annotations
+
+
+async def formatting(params: dict, doc) -> list[dict] | None:
+    tab_size = int(params.get("options", {}).get("tabSize", 4))
+    text = doc.text
+
+    out_lines: list[str] = []
+    # The stack of indent levels, top of stack = current block's indent.
+    indent_stack: list[int] = [0]
+    for raw in text.splitlines():
+        line = raw.rstrip()
+        stripped = line.lstrip()
+
+        if not stripped:
+            out_lines.append("")
+            continue
+
+        # Pop any indent levels that are *strictly greater* than this
+        # line's indent. We compare on the line's *raw* indent so a
+        # correctly-indented block closer still pops cleanly.
+        leading = len(line) - len(stripped)
+        # If the line is a block closer (starts with ``}``) we will pop
+        # below; otherwise we pop anything whose indent is now too deep.
+        if stripped.startswith("}"):
+            while len(indent_stack) > 1 and indent_stack[-1] >= leading:
+                indent_stack.pop()
+            if len(indent_stack) > 1:
+                indent_stack.pop()
+            target = indent_stack[-1] if indent_stack else 0
+        else:
+            while len(indent_stack) > 1 and indent_stack[-1] > leading:
+                indent_stack.pop()
+            target = indent_stack[-1] if indent_stack else 0
+
+        out_lines.append(" " * target + stripped)
+
+        # After this line, any new block opener advances the stack.
+        if stripped.endswith("{") and not stripped.startswith("}"):
+            indent_stack.append(target + tab_size)
+
+    new_text = "\n".join(out_lines)
+    if text.endswith("\n"):
+        new_text += "\n"
+
+    # Whole-document edit, as required by LSP.
+    last_line = text.count("\n")
+    last_nl = text.rfind("\n")
+    end_col = len(text) - (last_nl + 1) if last_nl != -1 else len(text)
+    return [{
+        "range": {
+            "start": {"line": 0, "character": 0},
+            "end": {"line": last_line, "character": end_col},
+        },
+        "newText": new_text,
+    }]