python-delphi-lsp 3.6.0__cp310-abi3-win_amd64.whl

delphi_lsp/wiki_memory.py

@@ -0,0 +1,548 @@
+"""Process-tree memory measurement and escalation for wiki exports.
+
+The guard is deliberately independent of the exporter: its callbacks change
+execution strategy, while callers retain sole ownership of output payloads.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import subprocess
+import sys
+from collections import defaultdict, deque
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from enum import Enum
+from functools import lru_cache
+from pathlib import Path
+from time import monotonic
+
+from .agent_cache import current_process_rss_bytes, parse_memory_size
+
+GIB = 1024**3
+DEFAULT_MEMORY_LIMIT_BYTES = 4 * GIB
+WIKI_MAX_MEMORY_ENV = "DELPHI_LSP_WIKI_MAX_MEMORY"
+_PROC_PIDTBSDINFO = 3
+_PROC_PIDTASKINFO = 4
+
+
+@dataclass(frozen=True)
+class ProcessMemorySnapshot:
+    """One process's parent relationship and resident memory usage."""
+
+    parent_pid: int
+    rss_bytes: int
+
+
+class MemoryStage(str, Enum):
+    COMPACT = "compact"
+    REDUCE_WORKERS = "reduce_workers"
+    SEQUENTIAL = "sequential"
+
+
+@dataclass(frozen=True)
+class MemoryTransition:
+    """An escalation that callers may surface through progress reporting."""
+
+    stage: MemoryStage
+    phase: str
+    used_bytes: int
+    limit_bytes: int
+
+    @property
+    def utilization_percent(self) -> float:
+        return self.used_bytes * 100.0 / self.limit_bytes
+
+
+class WikiMemoryLimitExceeded(RuntimeError):
+    """Raised when memory remains over budget after sequentialization."""
+
+    def __init__(self, *, phase: str, used_bytes: int, limit_bytes: int) -> None:
+        self.phase = phase
+        self.used_bytes = used_bytes
+        self.limit_bytes = limit_bytes
+        super().__init__(
+            f"Wiki export exceeded its {limit_bytes} byte memory limit during "
+            f"{phase} after switching to sequential processing ({used_bytes} bytes)."
+        )
+
+
+def system_memory_bytes() -> int:
+    """Return physical memory without optional dependencies, or zero on failure."""
+    try:
+        if os.name == "nt":
+            return _windows_system_memory_bytes()
+        if sys.platform == "darwin":
+            return _darwin_system_memory_bytes()
+        if sys.platform.startswith("linux"):
+            return _linux_system_memory_bytes()
+    except Exception:  # noqa: BLE001, S110 - probes must never disrupt export.
+        pass
+    return 0
+
+
+def _linux_system_memory_bytes() -> int:
+    for line in Path("/proc/meminfo").read_text(encoding="ascii").splitlines():
+        field, _, value = line.partition(":")
+        if field == "MemTotal":
+            return int(value.split()[0]) * 1024
+    return 0
+
+
+def _darwin_system_memory_bytes() -> int:
+    result = subprocess.run(
+        ["/usr/sbin/sysctl", "-n", "hw.memsize"],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return int(result.stdout.strip())
+
+
+def _windows_system_memory_bytes() -> int:
+    class MemoryStatusEx(ctypes.Structure):
+        _fields_ = [
+            ("dwLength", ctypes.c_ulong),
+            ("dwMemoryLoad", ctypes.c_ulong),
+            ("ullTotalPhys", ctypes.c_ulonglong),
+            ("ullAvailPhys", ctypes.c_ulonglong),
+            ("ullTotalPageFile", ctypes.c_ulonglong),
+            ("ullAvailPageFile", ctypes.c_ulonglong),
+            ("ullTotalVirtual", ctypes.c_ulonglong),
+            ("ullAvailVirtual", ctypes.c_ulonglong),
+            ("ullAvailExtendedVirtual", ctypes.c_ulonglong),
+        ]
+
+    status = MemoryStatusEx()
+    status.dwLength = ctypes.sizeof(status)
+    windll = ctypes.windll  # type: ignore[attr-defined]
+    if not windll.kernel32.GlobalMemoryStatusEx(ctypes.byref(status)):
+        return 0
+    return int(status.ullTotalPhys)
+
+
+def default_memory_limit_bytes() -> int:
+    """Return 90% of physical memory, capped at 4 GiB, with a 4 GiB fallback."""
+    total = system_memory_bytes()
+    return min(DEFAULT_MEMORY_LIMIT_BYTES, total * 90 // 100) if total > 0 else DEFAULT_MEMORY_LIMIT_BYTES
+
+
+def parse_optional_memory_limit(value: str | None) -> int | None:
+    """Parse a user override without allowing an invalid optional value to crash setup."""
+    if value is None or not value.strip():
+        return None
+    try:
+        return parse_memory_size(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def resolve_memory_limit_bytes(
+    explicit_limit_bytes: int | None,
+    *,
+    environ: Mapping[str, str] | None = None,
+) -> int:
+    """Resolve an explicit or environment override, otherwise use the safe default."""
+    if explicit_limit_bytes is not None:
+        if explicit_limit_bytes <= 0:
+            raise ValueError("wiki max memory must be greater than zero")
+        return explicit_limit_bytes
+    selected_environment = os.environ if environ is None else environ
+    raw_value = selected_environment.get(WIKI_MAX_MEMORY_ENV)
+    if raw_value is None or not raw_value.strip():
+        return default_memory_limit_bytes()
+    try:
+        value = parse_memory_size(raw_value)
+    except (TypeError, ValueError) as error:
+        raise ValueError(
+            f"{WIKI_MAX_MEMORY_ENV} must be a positive memory size"
+        ) from error
+    if value <= 0:
+        raise ValueError(f"{WIKI_MAX_MEMORY_ENV} must be greater than zero")
+    return value
+
+
+def process_tree_rss_bytes(
+    root_pid: int | None = None,
+    *,
+    snapshot: Mapping[int, ProcessMemorySnapshot] | None = None,
+) -> int:
+    """Return resident memory for a process and all descendants, or zero on failure."""
+    if root_pid is None:
+        root_pid = os.getpid()
+    try:
+        if snapshot is not None:
+            processes = snapshot
+        else:
+            try:
+                processes = _process_memory_snapshot()
+            except Exception:  # noqa: BLE001 - fall back to the root process below.
+                processes = {}
+        if not processes and root_pid == os.getpid():
+            current = current_process_rss_bytes()
+            if current > 0:
+                return current
+            import resource
+
+            maximum = int(resource.getrusage(resource.RUSAGE_SELF).ru_maxrss)
+            return maximum if sys.platform == "darwin" else maximum * 1024
+        return _sum_descendant_rss(root_pid, processes)
+    except Exception:  # noqa: BLE001 - process inspection is best effort.
+        return 0
+
+
+def _sum_descendant_rss(
+    root_pid: int, snapshot: Mapping[int, ProcessMemorySnapshot]
+) -> int:
+    children: dict[int, list[int]] = defaultdict(list)
+    for pid, item in snapshot.items():
+        children[item.parent_pid].append(pid)
+    pending = deque([root_pid])
+    seen: set[int] = set()
+    total = 0
+    while pending:
+        pid = pending.popleft()
+        if pid in seen:
+            continue
+        seen.add(pid)
+        current = snapshot.get(pid)
+        if current is not None:
+            total += max(0, current.rss_bytes)
+        pending.extend(children.get(pid, ()))
+    return total
+
+
+def _process_memory_snapshot() -> dict[int, ProcessMemorySnapshot]:
+    if os.name == "nt":
+        return _windows_process_snapshot()
+    if sys.platform.startswith("linux"):
+        return _linux_process_snapshot()
+    if sys.platform == "darwin":
+        return _darwin_process_snapshot()
+    return {}
+
+
+def _linux_process_snapshot() -> dict[int, ProcessMemorySnapshot]:
+    result: dict[int, ProcessMemorySnapshot] = {}
+    for entry in Path("/proc").iterdir():
+        if not entry.name.isdecimal():
+            continue
+        try:
+            fields = entry.joinpath("status").read_text(encoding="ascii").splitlines()
+            values = {line.split(":", 1)[0]: line.split(":", 1)[1].split()[0] for line in fields if ":" in line}
+            result[int(entry.name)] = ProcessMemorySnapshot(
+                parent_pid=int(values["PPid"]), rss_bytes=int(values.get("VmRSS", 0)) * 1024
+            )
+        except (OSError, KeyError, ValueError, IndexError):
+            continue
+    return result
+
+
+def _darwin_process_snapshot() -> dict[int, ProcessMemorySnapshot]:
+    try:
+        return _darwin_libproc_process_snapshot()
+    except Exception:  # noqa: BLE001 - retain the portable command fallback.
+        return _darwin_ps_process_snapshot()
+
+
+@lru_cache(maxsize=1)
+def _load_darwin_libproc() -> ctypes.CDLL:
+    libproc = ctypes.CDLL("/usr/lib/libproc.dylib", use_errno=True)
+    libproc.proc_listallpids.argtypes = [ctypes.c_void_p, ctypes.c_int]
+    libproc.proc_listallpids.restype = ctypes.c_int
+    libproc.proc_pidinfo.argtypes = [
+        ctypes.c_int,
+        ctypes.c_int,
+        ctypes.c_uint64,
+        ctypes.c_void_p,
+        ctypes.c_int,
+    ]
+    libproc.proc_pidinfo.restype = ctypes.c_int
+    return libproc
+
+
+def _darwin_libproc_process_snapshot() -> dict[int, ProcessMemorySnapshot]:
+    """Read the macOS process table without spawning ``ps`` at every sample."""
+    libproc = _load_darwin_libproc()
+    process_count = int(libproc.proc_listallpids(None, 0))
+    if process_count <= 0:
+        raise OSError("libproc returned no process capacity")
+    capacity = max(64, process_count + 64)
+    while True:
+        pids = (ctypes.c_int * capacity)()
+        returned = int(libproc.proc_listallpids(pids, ctypes.sizeof(pids)))
+        if returned < 0:
+            raise OSError(ctypes.get_errno(), "proc_listallpids failed")
+        if returned < capacity:
+            break
+        capacity *= 2
+
+    result: dict[int, ProcessMemorySnapshot] = {}
+    bsd_info = (ctypes.c_ubyte * 512)()
+    task_info = (ctypes.c_ubyte * 256)()
+    for raw_pid in pids[:returned]:
+        pid = int(raw_pid)
+        if pid <= 0:
+            continue
+        bsd_size = int(
+            libproc.proc_pidinfo(
+                pid,
+                _PROC_PIDTBSDINFO,
+                0,
+                bsd_info,
+                ctypes.sizeof(bsd_info),
+            )
+        )
+        if bsd_size < 20:
+            continue
+        task_size = int(
+            libproc.proc_pidinfo(
+                pid,
+                _PROC_PIDTASKINFO,
+                0,
+                task_info,
+                ctypes.sizeof(task_info),
+            )
+        )
+        if task_size < 16:
+            continue
+        parent_pid = int(ctypes.c_uint32.from_buffer(bsd_info, 16).value)
+        rss_bytes = int(ctypes.c_uint64.from_buffer(task_info, 8).value)
+        result[pid] = ProcessMemorySnapshot(parent_pid, rss_bytes)
+    if not result:
+        raise OSError("libproc returned no readable processes")
+    return result
+
+
+def _darwin_ps_process_snapshot() -> dict[int, ProcessMemorySnapshot]:
+    output = subprocess.run(
+        ["/bin/ps", "-axo", "pid=,ppid=,rss="],
+        check=True,
+        capture_output=True,
+        text=True,
+    ).stdout
+    result: dict[int, ProcessMemorySnapshot] = {}
+    for line in output.splitlines():
+        try:
+            pid, parent_pid, rss_kib = line.split()
+            result[int(pid)] = ProcessMemorySnapshot(int(parent_pid), int(rss_kib) * 1024)
+        except ValueError:
+            continue
+    return result
+
+
+def _windows_process_snapshot() -> dict[int, ProcessMemorySnapshot]:
+    """Collect parent links and working sets with ToolHelp/PSAPI, no third-party API."""
+    from ctypes import wintypes
+
+    class ProcessEntry32(ctypes.Structure):
+        _fields_ = [
+            ("dwSize", wintypes.DWORD),
+            ("cntUsage", wintypes.DWORD),
+            ("th32ProcessID", wintypes.DWORD),
+            ("th32DefaultHeapID", ctypes.c_size_t),
+            ("th32ModuleID", wintypes.DWORD),
+            ("cntThreads", wintypes.DWORD),
+            ("th32ParentProcessID", wintypes.DWORD),
+            ("pcPriClassBase", ctypes.c_long),
+            ("dwFlags", wintypes.DWORD),
+            ("szExeFile", ctypes.c_wchar * 260),
+        ]
+
+    class ProcessMemoryCounters(ctypes.Structure):
+        _fields_ = [
+            ("cb", wintypes.DWORD),
+            ("PageFaultCount", wintypes.DWORD),
+            ("PeakWorkingSetSize", ctypes.c_size_t),
+            ("WorkingSetSize", ctypes.c_size_t),
+            ("QuotaPeakPagedPoolUsage", ctypes.c_size_t),
+            ("QuotaPagedPoolUsage", ctypes.c_size_t),
+            ("QuotaPeakNonPagedPoolUsage", ctypes.c_size_t),
+            ("QuotaNonPagedPoolUsage", ctypes.c_size_t),
+            ("PagefileUsage", ctypes.c_size_t),
+            ("PeakPagefileUsage", ctypes.c_size_t),
+        ]
+
+    windll = ctypes.windll  # type: ignore[attr-defined]
+    kernel32 = windll.kernel32
+    psapi = windll.psapi
+    kernel32.CreateToolhelp32Snapshot.argtypes = [wintypes.DWORD, wintypes.DWORD]
+    kernel32.CreateToolhelp32Snapshot.restype = wintypes.HANDLE
+    kernel32.Process32FirstW.argtypes = [wintypes.HANDLE, ctypes.POINTER(ProcessEntry32)]
+    kernel32.Process32FirstW.restype = wintypes.BOOL
+    kernel32.Process32NextW.argtypes = [wintypes.HANDLE, ctypes.POINTER(ProcessEntry32)]
+    kernel32.Process32NextW.restype = wintypes.BOOL
+    kernel32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
+    kernel32.OpenProcess.restype = wintypes.HANDLE
+    kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
+    kernel32.CloseHandle.restype = wintypes.BOOL
+    psapi.GetProcessMemoryInfo.argtypes = [
+        wintypes.HANDLE,
+        ctypes.POINTER(ProcessMemoryCounters),
+        wintypes.DWORD,
+    ]
+    psapi.GetProcessMemoryInfo.restype = wintypes.BOOL
+    snapshot = kernel32.CreateToolhelp32Snapshot(0x00000002, 0)
+    if not snapshot or snapshot == wintypes.HANDLE(-1).value:
+        return {}
+    result: dict[int, ProcessMemorySnapshot] = {}
+    try:
+        entry = ProcessEntry32()
+        entry.dwSize = ctypes.sizeof(entry)
+        has_process = kernel32.Process32FirstW(snapshot, ctypes.byref(entry))
+        while has_process:
+            process = kernel32.OpenProcess(0x0400 | 0x0010, False, entry.th32ProcessID)
+            rss_bytes = 0
+            if process:
+                try:
+                    counters = ProcessMemoryCounters()
+                    counters.cb = ctypes.sizeof(counters)
+                    if psapi.GetProcessMemoryInfo(process, ctypes.byref(counters), counters.cb):
+                        rss_bytes = int(counters.WorkingSetSize)
+                finally:
+                    kernel32.CloseHandle(process)
+            result[int(entry.th32ProcessID)] = ProcessMemorySnapshot(
+                int(entry.th32ParentProcessID), rss_bytes
+            )
+            entry.dwSize = ctypes.sizeof(entry)
+            has_process = kernel32.Process32NextW(snapshot, ctypes.byref(entry))
+    finally:
+        kernel32.CloseHandle(snapshot)
+    return result
+
+
+class ProcessTreeMemorySampler:
+    """Measure root RSS cheaply while periodically refreshing child RSS."""
+
+    def __init__(
+        self,
+        *,
+        interval_seconds: float = 5.0,
+        root_measure: Callable[[], int] = current_process_rss_bytes,
+        tree_measure: Callable[[], int] = process_tree_rss_bytes,
+        clock: Callable[[], float] = monotonic,
+    ) -> None:
+        if interval_seconds <= 0:
+            raise ValueError("interval_seconds must be greater than zero")
+        self.interval_seconds = interval_seconds
+        self._root_measure = root_measure
+        self._tree_measure = tree_measure
+        self._clock = clock
+        self._last_tree_sample = float("-inf")
+        self._cached_child_bytes = 0
+
+    def __call__(self) -> int:
+        root_bytes = self._root_measure()
+        now = self._clock()
+        if now - self._last_tree_sample >= self.interval_seconds:
+            return self._sample_tree(root_bytes, now)
+        return max(0, root_bytes) + self._cached_child_bytes
+
+    def force(self) -> int:
+        """Refresh the full process tree regardless of the sampling interval."""
+        root_bytes = self._root_measure()
+        return self._sample_tree(root_bytes, self._clock())
+
+    def _sample_tree(self, root_bytes: int, now: float) -> int:
+        tree_bytes = self._tree_measure()
+        self._last_tree_sample = now
+        if tree_bytes <= 0:
+            self._cached_child_bytes = 0
+            return max(0, root_bytes)
+        self._cached_child_bytes = max(0, tree_bytes - max(0, root_bytes))
+        return max(0, root_bytes) + self._cached_child_bytes
+
+
+class WikiMemoryGuard:
+    """Escalate wiki-export execution strategy without touching emitted data."""
+
+    def __init__(
+        self,
+        *,
+        limit_bytes: int | None = None,
+        measure: Callable[[], int] | None = None,
+        compact: Callable[[], None] | None = None,
+        reduce_workers: Callable[[], None] | None = None,
+        sequentialize: Callable[[], None] | None = None,
+        on_transition: Callable[[MemoryTransition], None] | None = None,
+    ) -> None:
+        self.limit_bytes = limit_bytes if limit_bytes is not None else default_memory_limit_bytes()
+        if self.limit_bytes <= 0:
+            raise ValueError("limit_bytes must be greater than zero")
+        self._measure = measure or ProcessTreeMemorySampler()
+        self._actions = {
+            MemoryStage.COMPACT: compact or (lambda: None),
+            MemoryStage.REDUCE_WORKERS: reduce_workers or (lambda: None),
+            MemoryStage.SEQUENTIAL: sequentialize or (lambda: None),
+        }
+        self._on_transition = on_transition
+        self._completed: set[MemoryStage] = set()
+        self.peak_bytes = 0
+        self.phase_peaks: dict[str, int] = {}
+
+    def check(
+        self,
+        used_bytes: int | None = None,
+        *,
+        phase: str,
+        force_process_tree: bool = False,
+    ) -> MemoryTransition | None:
+        """Apply at most one new stage and return it for progress reporting."""
+        if used_bytes is not None:
+            used = used_bytes
+        elif force_process_tree and isinstance(self._measure, ProcessTreeMemorySampler):
+            used = self._measure.force()
+        else:
+            used = self._measure()
+        self.peak_bytes = max(self.peak_bytes, used)
+        self.phase_peaks[phase] = max(self.phase_peaks.get(phase, 0), used)
+        if used <= 0:
+            return None
+        required_stage = self._required_stage(used)
+        if required_stage is None:
+            return None
+        ordered_stages = (
+            MemoryStage.COMPACT,
+            MemoryStage.REDUCE_WORKERS,
+            MemoryStage.SEQUENTIAL,
+        )
+        required_index = ordered_stages.index(required_stage)
+        if required_stage in self._completed:
+            if required_stage is MemoryStage.SEQUENTIAL:
+                if (
+                    used_bytes is None
+                    and not force_process_tree
+                    and isinstance(self._measure, ProcessTreeMemorySampler)
+                ):
+                    used = self._measure.force()
+                    self.peak_bytes = max(self.peak_bytes, used)
+                    self.phase_peaks[phase] = max(
+                        self.phase_peaks.get(phase, 0),
+                        used,
+                    )
+                    if self._required_stage(used) is not MemoryStage.SEQUENTIAL:
+                        return None
+                raise WikiMemoryLimitExceeded(phase=phase, used_bytes=used, limit_bytes=self.limit_bytes)
+            return None
+        latest_transition: MemoryTransition | None = None
+        for stage in ordered_stages[: required_index + 1]:
+            if stage in self._completed:
+                continue
+            transition = MemoryTransition(stage, phase, used, self.limit_bytes)
+            self._actions[stage]()
+            self._completed.add(stage)
+            if self._on_transition is not None:
+                self._on_transition(transition)
+            latest_transition = transition
+        return latest_transition
+
+    def _required_stage(self, used_bytes: int) -> MemoryStage | None:
+        utilization = used_bytes * 100 / self.limit_bytes
+        if utilization >= 90:
+            return MemoryStage.SEQUENTIAL
+        if utilization >= 80:
+            return MemoryStage.REDUCE_WORKERS
+        if utilization >= 60:
+            return MemoryStage.COMPACT
+        return None

delphi_lsp/workspace.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+
+from .consts import AttributeName
+from .nodes import SyntaxNode
+from .parser import DelphiParser
+from .preprocessor import IncludeLoader, PreprocessedSource
+from .semantic import Scope, ScopeKind, SymbolIndex
+from .semantic_builder import SemanticBuilder, SemanticModel
+
+
+@dataclass
+class WorkspaceSemanticResult:
+    models: dict[str, SemanticModel]
+    index: SymbolIndex
+    preprocessed: dict[str, PreprocessedSource] = field(default_factory=dict)
+
+
+def build_workspace_semantics(
+    sources: dict[str, str],
+    *,
+    include_paths: Iterable[str] = (),
+    defines: Iterable[str] = (),
+    include_loader: IncludeLoader | None = None,
+    preprocessor_options=None,
+    collect_references: bool = True,
+) -> WorkspaceSemanticResult:
+    parser = DelphiParser(
+        include_paths=include_paths,
+        defines=defines,
+        include_loader=include_loader,
+        preprocessor_options=preprocessor_options,
+    )
+    roots: dict[str, SyntaxNode] = {}
+    preprocessed_sources: dict[str, PreprocessedSource] = {}
+    for file_name, text in sources.items():
+        result = parser.parse(text, file_name, build_semantic=False)
+        roots[file_name] = result.root
+        preprocessed_sources[file_name] = result.preprocessed
+
+    return build_workspace_semantics_from_roots(
+        roots,
+        preprocessed_sources=preprocessed_sources,
+        collect_references=collect_references,
+    )
+
+
+def build_workspace_semantics_from_roots(
+    roots: dict[str, SyntaxNode],
+    *,
+    preprocessed_sources: Mapping[str, PreprocessedSource] | None = None,
+    collect_references: bool = True,
+) -> WorkspaceSemanticResult:
+    """Build project semantics from syntax roots that have already been parsed."""
+
+    index = SymbolIndex()
+    scopes: dict[str, Scope] = {}
+    for file_name, root in roots.items():
+        unit_name = root.get_attribute(AttributeName.anName) or file_name
+        unit_scope = Scope(kind=ScopeKind.UNIT, name=unit_name)
+        index.register_unit(unit_name, unit_scope, index_symbols=False)
+        scopes[file_name] = unit_scope
+
+    source_maps = preprocessed_sources or {}
+    builder = SemanticBuilder(
+        collect_references=collect_references,
+        source_maps=source_maps,
+    )
+    for file_name, root in roots.items():
+        builder.declare(root, index=index, unit_scope=scopes[file_name], reset_state=False)
+
+    models: dict[str, SemanticModel] = {}
+    for file_name, root in roots.items():
+        model = builder.resolve(root, scopes[file_name])
+        models[file_name] = model
+
+    return WorkspaceSemanticResult(
+        models=models,
+        index=index,
+        preprocessed=dict(source_maps),
+    )

delphi_lsp/writer.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from .consts import ATTRIBUTE_NAME_STRINGS, SYNTAX_NODE_NAMES
+from .nodes import CompoundSyntaxNode, SyntaxNode, ValuedSyntaxNode
+
+
+def _xml_encode(data: str) -> str:
+    result = []
+    for ch in data:
+        if ch == '<':
+            result.append('&lt;')
+        elif ch == '>':
+            result.append('&gt;')
+        elif ch == '&':
+            result.append('&amp;')
+        elif ch == '"':
+            result.append('&quot;')
+        elif ch == "'":
+            result.append('&apos;')
+        else:
+            result.append(ch)
+    return ''.join(result)
+
+
+class SyntaxTreeWriter:
+    @staticmethod
+    def to_xml(root: SyntaxNode, formatted: bool = False) -> str:
+        builder: list[str] = []
+        SyntaxTreeWriter._node_to_xml(builder, root, formatted, '')
+        return '<?xml version="1.0"?>\n' + ''.join(builder)
+
+    @staticmethod
+    def _node_to_xml(builder: list[str], node: SyntaxNode, formatted: bool, indent: str) -> None:
+        has_children = node.has_children
+        new_indent = indent + '  '
+        if formatted:
+            builder.append(indent)
+        builder.append('<' + SYNTAX_NODE_NAMES[node.typ].upper())
+
+        if isinstance(node, CompoundSyntaxNode):
+            builder.append(f' begin_line="{node.line}"')
+            builder.append(f' begin_col="{node.col}"')
+            builder.append(f' end_line="{node.end_line}"')
+            builder.append(f' end_col="{node.end_col}"')
+        else:
+            builder.append(f' line="{node.line}"')
+            builder.append(f' col="{node.col}"')
+
+        if node.file_name:
+            builder.append('  file="' + _xml_encode(node.file_name) + '"')
+
+        if isinstance(node, ValuedSyntaxNode):
+            builder.append(' value="' + _xml_encode(node.value) + '"')
+
+        for attr_key, attr_value in node.attributes:
+            builder.append(
+                ' ' + ATTRIBUTE_NAME_STRINGS[attr_key] + '="' + _xml_encode(attr_value) + '"'
+            )
+
+        if has_children:
+            builder.append('>')
+        else:
+            builder.append('/>')
+        if formatted:
+            builder.append('\n')
+        for child in node.child_nodes:
+            SyntaxTreeWriter._node_to_xml(builder, child, formatted, new_indent)
+        if has_children:
+            if formatted:
+                builder.append(indent)
+            builder.append('</' + SYNTAX_NODE_NAMES[node.typ].upper() + '>')
+            if formatted:
+                builder.append('\n')