codeboarding 0.13.4__tar.gz → 0.13.5__tar.gz

{codeboarding-0.13.4/codeboarding.egg-info → codeboarding-0.13.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeboarding
-Version: 0.13.4
+Version: 0.13.5
 Summary: Interactive Diagrams for Code
 Author: CodeBoarding Team
 License-Expression: MIT

{codeboarding-0.13.4 → codeboarding-0.13.5/codeboarding.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeboarding
-Version: 0.13.4
+Version: 0.13.5
 Summary: Interactive Diagrams for Code
 Author: CodeBoarding Team
 License-Expression: MIT

{codeboarding-0.13.4 → codeboarding-0.13.5}/codeboarding.egg-info/SOURCES.txt

@@ -160,7 +160,9 @@ static_analyzer/engine/hierarchy_builder.py
 static_analyzer/engine/language_adapter.py
 static_analyzer/engine/lsp_client.py
 static_analyzer/engine/lsp_constants.py
+static_analyzer/engine/lsp_recycler.py
 static_analyzer/engine/models.py
+static_analyzer/engine/process_memory.py
 static_analyzer/engine/progress.py
 static_analyzer/engine/protocols.py
 static_analyzer/engine/result_converter.py

{codeboarding-0.13.4 → codeboarding-0.13.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codeboarding"
-version = "0.13.4"
+version = "0.13.5"
 description = "Interactive Diagrams for Code"
 readme = "PYPI.md"
 license = "MIT"

{codeboarding-0.13.4 → codeboarding-0.13.5}/repo_utils/ignore.py

@@ -174,6 +174,7 @@ class RepoIgnoreManager:
 
     def reload(self):
         """Reload ignore patterns from .gitignore and .codeboardingignore."""
+        self._checked_paths: dict[str, bool] = {}
         gitignore_patterns = self._load_gitignore_patterns()
         codeboardingignore_patterns = self._load_codeboardingignore_patterns()
 
@@ -227,7 +228,21 @@ class RepoIgnoreManager:
         """Check if a given path should be ignored.
 
         Handles both absolute paths and paths relative to repo_root.
+
+        Records the result for each checked path until ``reload`` because callers
+        ask about the same files during discovery and again while converting
+        symbols and references.
         """
+        path_key = str(path)
+        should_ignore = self._checked_paths.get(path_key)
+        if should_ignore is not None:
+            return should_ignore
+
+        should_ignore = self._compute_should_ignore(path)
+        self._checked_paths[path_key] = should_ignore
+        return should_ignore
+
+    def _compute_should_ignore(self, path: Path) -> bool:
         try:
             # Convert to relative path if absolute
             if path.is_absolute():

{codeboarding-0.13.4 → codeboarding-0.13.5}/static_analyzer/__init__.py

@@ -232,6 +232,17 @@ class StaticAnalyzer:
 
         for engine_config in self._engine_configs:
             adapter, project_path = engine_config.adapter, engine_config.project_path
+            # Resolve file membership before paying for the server. A language
+            # the scanner detected from a handful of stray files still costs a
+            # full LSP process (tsserver + its node workers run ~350MB) that
+            # then analyzes nothing. Also reused by ``_run_full_analysis``, so
+            # the directory walk happens once per engine rather than twice.
+            if not engine_config.source_files:
+                engine_config.source_files = adapter.discover_source_files(project_path, self.ignore_manager)
+            if not engine_config.source_files:
+                logger.info(f"No {adapter.language} source files under {project_path}; skipping its LSP server.")
+                continue
+
             attempted.append(adapter.language)
             engine_client: LSPClient | None = None
             try:
@@ -289,12 +300,16 @@ class StaticAnalyzer:
                             f"Error shutting down partially-started {adapter.language} client during cleanup"
                         )
 
+        if not attempted:
+            logger.info(f"No source files for any detected language in {self.repository_path}; no LSP clients started.")
+            self._engine_clients = []
+            self._clients_started = True
+            return
+
         if not started:
             self._clients_started = False
             details = f"; failures: {'; '.join(failed_details)}" if failed_details else ""
-            raise RuntimeError(
-                f"Failed to start any engine LSP client (attempted: {', '.join(attempted) or 'none'}){details}"
-            )
+            raise RuntimeError(f"Failed to start any engine LSP client (attempted: {', '.join(attempted)}){details}")
 
         if failed_languages:
             details = f" Details: {'; '.join(failed_details)}." if failed_details else ""

{codeboarding-0.13.4 → codeboarding-0.13.5}/static_analyzer/engine/adapters/csharp_adapter.py

@@ -168,6 +168,11 @@ class CSharpAdapter(LanguageAdapter):
         """csharp-ls loads all files from the .sln — didOpen before workspace load kills it."""
         return True
 
+    @property
+    def workspace_owns_documents(self) -> bool:
+        """csharp-ls answers position queries from the loaded solution, opened or not."""
+        return True
+
     def get_lsp_default_timeout(self) -> int:
         """csharp-ls needs extra time to load Roslyn workspace for large solutions."""
         return 120

{codeboarding-0.13.4 → codeboarding-0.13.5}/static_analyzer/engine/call_graph_builder.py

@@ -13,6 +13,7 @@ from static_analyzer.engine.hierarchy_builder import HierarchyBuilder
 from static_analyzer.engine.language_adapter import LanguageAdapter
 from static_analyzer.engine.lsp_client import LSPClient
 from static_analyzer.engine.lsp_constants import DID_OPEN_BATCH_SIZE, EdgeStrategy
+from static_analyzer.engine.lsp_recycler import LSPRecycler
 from static_analyzer.engine.models import CallFlowGraph, LanguageAnalysisResult
 from static_analyzer.engine.source_inspector import SourceInspector
 from static_analyzer.engine.symbol_table import SymbolTable
@@ -60,7 +61,9 @@ class CallGraphBuilder:
         t_indices_done = time.monotonic()
         logger.info("Build indices: %.1fs", t_indices_done - t_symbols_done)
 
-        ctx = EdgeBuildContext(self._lsp, self._symbol_table, self._source_inspector)
+        ctx = EdgeBuildContext(
+            self._lsp, self._symbol_table, self._source_inspector, recycler=self._build_recycler(source_files)
+        )
         edge_set = self._build_edges(ctx, source_files)
         edge_set = self._postprocess_edges(edge_set)
         t_edges_done = time.monotonic()
@@ -118,28 +121,37 @@ class CallGraphBuilder:
             source_files=abs_files,
         )
 
+    def _build_recycler(self, source_files: list[Path]) -> LSPRecycler | None:
+        """A recycler for servers whose memory the references phase would otherwise grow without bound."""
+        if not self._adapter.workspace_owns_documents or not source_files:
+            return None
+        return LSPRecycler(self._lsp, source_files[0], self._probe_timeout(len(source_files)))
+
     def _build_edges(self, ctx: EdgeBuildContext, source_files: list[Path]) -> EdgeMap:
         """Dispatch to the edge-building strategy specified by the adapter."""
         if self._adapter.edge_strategy == EdgeStrategy.DEFINITIONS:
             return build_edges_via_definitions(self._adapter, ctx, source_files)
         return build_edges_via_references(self._adapter, ctx, source_files)
 
-    def _discover_symbols(self, source_files: list[Path]) -> None:
-        """Phase 0+1: Synchronize with the server, open files, and extract symbols."""
-        total = len(source_files)
+    def _probe_timeout(self, total_files: int) -> int:
+        """Seconds to allow a synchronization probe to block on LSP indexing.
 
-        # Synchronization probe — blocks until the LSP server has indexed
-        # the project. Scales linearly with file count (no OS branching);
-        # the per-file ceiling is picked conservatively to cover gopls on
-        # AV-heavy Windows and APFS macOS without being loose enough to
-        # let a hung LSP waste CI minutes. Adapters can raise the floor via
-        # ``get_probe_timeout_minimum()`` (e.g. csharp-ls needs extra time
-        # to load a Roslyn workspace).
+        Scales linearly with file count (no OS branching); the per-file ceiling
+        is picked conservatively to cover gopls on AV-heavy Windows and APFS
+        macOS without being loose enough to let a hung LSP waste CI minutes.
+        Adapters can raise the floor via ``get_probe_timeout_minimum()`` (e.g.
+        csharp-ls needs extra time to load a Roslyn workspace).
+        """
         _PROBE_STARTUP_BASE = 60  # seconds — LSP startup independent of file count
         _PROBE_PER_FILE = 2.0  # seconds — ceiling across OSes (Linux observed ~0.35s/file)
         _PROBE_MAX_TIMEOUT = 1800  # seconds — hard cap
-        probe_timeout = int(min(_PROBE_STARTUP_BASE + total * _PROBE_PER_FILE, _PROBE_MAX_TIMEOUT))
-        probe_timeout = max(probe_timeout, self._adapter.get_probe_timeout_minimum())
+        probe_timeout = int(min(_PROBE_STARTUP_BASE + total_files * _PROBE_PER_FILE, _PROBE_MAX_TIMEOUT))
+        return max(probe_timeout, self._adapter.get_probe_timeout_minimum())
+
+    def _discover_symbols(self, source_files: list[Path]) -> None:
+        """Phase 0+1: Synchronize with the server, open files, and extract symbols."""
+        total = len(source_files)
+        probe_timeout = self._probe_timeout(total)
 
         interleave_open = self._adapter.interleave_did_open_with_symbols
 
@@ -164,7 +176,7 @@ class CallGraphBuilder:
             # Interleaved adapters deliberately query again after didOpen so
             # that each overlay notification has a response barrier.
             should_reuse_probe = idx == 1 and not interleave_open
-            if should_reuse_probe and probe_result is not None:
+            if should_reuse_probe:
                 symbols = probe_result
             elif interleave_open:
                 symbols = self._lsp.document_symbol(file_path, timeout=probe_timeout)
@@ -193,9 +205,9 @@ class CallGraphBuilder:
         pbar.finish()
         logger.info("did_open %d files: %.1fs", total, time.monotonic() - t_open_start)
 
-    def _send_sync_probe(self, source_files: list[Path], probe_timeout: int) -> list[dict] | None:
+    def _send_sync_probe(self, source_files: list[Path], probe_timeout: int) -> list[dict]:
         """Send a documentSymbol probe to wait for the LSP server to finish indexing."""
-        probe_result: list[dict] | None = None
+        probe_result: list[dict] = []
         logger.info("Waiting for LSP server indexing (timeout=%ds)...", probe_timeout)
         t_probe = time.monotonic()
         if source_files:

{codeboarding-0.13.4 → codeboarding-0.13.5}/static_analyzer/engine/edge_build_context.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from dataclasses import dataclass
 
 from static_analyzer.engine.lsp_client import LSPClient
+from static_analyzer.engine.lsp_recycler import LSPRecycler
 from static_analyzer.engine.source_inspector import SourceInspector
 from static_analyzer.engine.symbol_table import SymbolTable
 
@@ -16,3 +17,6 @@ class EdgeBuildContext:
     lsp: LSPClient
     symbol_table: SymbolTable
     source_inspector: SourceInspector
+    # Set only for servers that may be restarted mid-phase; None means the
+    # strategy runs against a single server process for the whole phase.
+    recycler: LSPRecycler | None = None

{codeboarding-0.13.4 → codeboarding-0.13.5}/static_analyzer/engine/edge_builder.py

@@ -85,8 +85,13 @@ def build_edges_via_references(
     skipped_positions = 0
 
     pbar = ProgressLogger("Phase 2 (edges)", total_unique, unit="pos")
-    for batch_start in range(0, total_unique, batch_size):
-        batch_positions = unique_positions[batch_start : batch_start + batch_size]
+    batch_start = 0
+    while batch_start < total_unique:
+        # The recycler samples the server here — it decides both whether to
+        # restart it and how many queries this batch may carry.
+        size = batch_size if ctx.recycler is None else ctx.recycler.before_batch(batch_size)
+        batch_positions = unique_positions[batch_start : batch_start + size]
+        batch_start += len(batch_positions)
 
         # Filter out positions from files that already produced LSP errors
         filtered_positions: list[tuple[str, int, int]] = []
@@ -140,6 +145,14 @@ def build_edges_via_references(
         refs_total,
         (1 - refs_call_sites / max(refs_total, 1)) * 100,
     )
+    if ctx.recycler is not None and ctx.recycler.recycle_count:
+        # Worth one line at the end: a recycled run answered some queries from a
+        # different server process than the one it started with.
+        logger.info(
+            "Phase 2 (edges): the language server was recycled %d time(s); %d batches ran shrunk under memory pressure",
+            ctx.recycler.recycle_count,
+            ctx.recycler.shrunk_batches,
+        )
     return edge_set
 
 

{codeboarding-0.13.4 → codeboarding-0.13.5}/static_analyzer/engine/language_adapter.py

@@ -191,6 +191,18 @@ class LanguageAdapter(ABC):
         """If True, probe first, then pair each didOpen with its documentSymbol request."""
         return False
 
+    @property
+    def workspace_owns_documents(self) -> bool:
+        """If True, the server reads documents from the project, not from our didOpen.
+
+        Such a server answers position queries for files we never opened, which
+        makes a restarted process equivalent to the one it replaced — so the
+        references phase may recycle it to bound memory (see ``LSPRecycler``).
+        Servers that only know the documents we pushed must not be recycled:
+        they would come back empty.
+        """
+        return False
+
     def get_probe_timeout_minimum(self) -> int:
         """Return the minimum probe timeout in seconds for initial indexing.
 

{codeboarding-0.13.4 → codeboarding-0.13.5}/static_analyzer/engine/lsp_client.py

@@ -234,6 +234,36 @@ class LSPClient:
         self._opened_uris.clear()
         self._doc_versions.clear()
 
+    def restart(self) -> None:
+        """Replace the server process with a fresh one, same configuration.
+
+        Used to release memory a server accumulated and will not give back (see
+        ``LSPRecycler``). Diagnostics already collected are kept — they describe
+        the source, not the process. Open-document state is not: the new server
+        has nothing open, so only callers whose server reads documents from the
+        project itself may restart mid-analysis. Readiness is the caller's to
+        re-establish; this client has no view of what ready means per server.
+        """
+        self.shutdown()
+        self._shutdown_event.clear()
+        self._server_ready.clear()
+        self._server_health = None
+        self._server_health_message = None
+        self._work_done_progress_titles.clear()
+        self._work_done_progress_failures.clear()
+        self._init_failed = False
+        # Drop responses the dead server never got to be asked about, so a
+        # stale id cannot satisfy a pending request on the new connection.
+        self._msg_queue = queue.Queue()
+        self.start()
+
+    @property
+    def pid(self) -> int | None:
+        """OS pid of the running server process, or None when it is not running."""
+        if self._process is None or self._process.poll() is not None:
+            return None
+        return self._process.pid
+
     # ---- Document management ----
 
     def did_open(self, file_path: Path, language_id: str) -> None:
@@ -299,7 +329,7 @@ class LSPClient:
             return result
         return []
 
-    def references(self, file_path: Path, line: int, character: int) -> list[dict]:
+    def references(self, file_path: Path, line: int, character: int, timeout: int | None = None) -> list[dict]:
         """Find all references to the symbol at the given position."""
         result = self._send_request(
             "textDocument/references",
@@ -308,6 +338,7 @@ class LSPClient:
                 "position": {"line": line, "character": character},
                 "context": {"includeDeclaration": True},
             },
+            timeout=timeout,
         )
         if isinstance(result, list):
             return result

{codeboarding-0.13.4 → codeboarding-0.13.5}/static_analyzer/engine/lsp_constants.py

@@ -25,6 +25,18 @@ CALLABLE_KINDS: set[int] = {
 # Batch size for did_open to avoid overwhelming LSP servers
 DID_OPEN_BATCH_SIZE = 50
 
+# Share of RAM the language server may hold before it gets recycled. This
+# leaves room for Python, other language servers, and the operating system.
+MEMORY_BUDGET_FRACTION = 0.4
+MIN_MEMORY_BUDGET = 2 * 1024**3
+MAX_MEMORY_BUDGET = 12 * 1024**3
+
+# Reduce reference-query concurrency before reaching the recycle threshold.
+PRESSURE_FRACTION = 0.5
+PRESSURED_BATCH_DIVISOR = 10
+
+MEMORY_BUDGET_ENV_VAR = "CODEBOARDING_LSP_MEMORY_BUDGET_MB"
+
 
 class EdgeStrategy(StrEnum):
     """Edge-building strategy selection for Phase 2."""

codeboarding-0.13.5/static_analyzer/engine/lsp_recycler.py

@@ -0,0 +1,142 @@
+"""Bounds language-server memory during the references phase by restarting it.
+
+Answering ``textDocument/references`` across a large workspace makes Roslyn (and
+comparable engines) materialize a compilation per project and keep every one.
+Growth is linear in positions queried: on bitwarden/server csharp-ls climbed
+past 11GB and the run was OOM-killed on a 16GB runner. GC tuning halves the
+slope but the line still has no ceiling, so a big enough repo always wins.
+
+Restarting the server between batches drops the whole accumulation and costs one
+workspace reload. It is only sound for servers that read documents from the
+project itself rather than from our ``didOpen`` overlays -- those answer position
+queries for files we never opened, so a fresh process is equivalent to the old
+one. Adapters declare that via ``LanguageAdapter.workspace_owns_documents``.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from pathlib import Path
+
+from static_analyzer.engine.lsp_client import LSPClient
+from static_analyzer.engine.lsp_constants import (
+    MAX_MEMORY_BUDGET,
+    MEMORY_BUDGET_ENV_VAR,
+    MEMORY_BUDGET_FRACTION,
+    MIN_MEMORY_BUDGET,
+    PRESSURE_FRACTION,
+    PRESSURED_BATCH_DIVISOR,
+)
+from static_analyzer.engine.process_memory import format_bytes, physical_memory_bytes, process_tree_rss
+
+logger = logging.getLogger(__name__)
+
+
+def default_memory_budget() -> int:
+    """Bytes a language server may occupy before it gets recycled."""
+    override = os.environ.get(MEMORY_BUDGET_ENV_VAR, "").strip()
+    if override:
+        try:
+            return int(float(override) * 1024**2)
+        except ValueError:
+            logger.warning("Ignoring %s=%r: not a number of megabytes", MEMORY_BUDGET_ENV_VAR, override)
+    physical = physical_memory_bytes()
+    if not physical:
+        return MIN_MEMORY_BUDGET
+    return int(min(max(physical * MEMORY_BUDGET_FRACTION, MIN_MEMORY_BUDGET), MAX_MEMORY_BUDGET))
+
+
+class LSPRecycler:
+    """Restarts a language server whose process tree outgrows the budget."""
+
+    def __init__(
+        self,
+        lsp: LSPClient,
+        probe_file: Path,
+        probe_timeout: int,
+        budget_bytes: int = 0,
+    ) -> None:
+        self._lsp = lsp
+        self._probe_file = probe_file
+        self._probe_timeout = probe_timeout
+        self._budget = budget_bytes or default_memory_budget()
+        self.recycle_count = 0
+        self.shrunk_batches = 0
+        self._disarmed = False
+        logger.info("LSP recycler armed at a %s budget", format_bytes(self._budget))
+
+    def before_batch(self, full_batch_size: int) -> int:
+        """Sample the server, restart it if over budget, and size the next batch.
+
+        One sample per batch, not per N batches: a single batch of solution-wide
+        reference queries can allocate gigabytes, so a coarser interval sails
+        past the budget between checks. Reading the process table costs
+        milliseconds against a batch's own LSP round-trip.
+
+        Returns how many positions the next batch may carry. A batch is one
+        round-trip we cannot interrupt, so its own growth is the floor under any
+        bound we can offer; near the ceiling we carry fewer queries at once to
+        keep that floor low.
+        """
+        if self._disarmed:
+            return full_batch_size
+        used = self._server_rss()
+        if used >= self._budget:
+            self._recycle(used)
+            return full_batch_size
+        if used < self._budget * PRESSURE_FRACTION:
+            return full_batch_size
+        self.shrunk_batches += 1
+        return max(1, full_batch_size // PRESSURED_BATCH_DIVISOR)
+
+    def _recycle(self, used: int) -> None:
+        logger.warning(
+            "LSP holding %s (budget %s) — restarting it to release cached compilations",
+            format_bytes(used),
+            format_bytes(self._budget),
+        )
+        t_restart = time.monotonic()
+        self._lsp.restart()
+        # Blocks until the workspace is loaded again: a workspace-backed server
+        # cannot answer a documentSymbol until it has read the project files.
+        self._lsp.document_symbol(self._probe_file, timeout=self._probe_timeout)
+        # A loaded workspace is not a warm reference index — that is built on the
+        # first references query. Pay for it here, on a request we can give a long
+        # timeout, rather than losing a whole batch of real positions to the
+        # per-request deadline. Measured: recycling without this tripled the
+        # "Timeout waiting for references request" warnings.
+        try:
+            self._lsp.references(self._probe_file, 0, 0, timeout=self._probe_timeout)
+        except Exception as exc:
+            logger.debug("Post-restart references warmup failed (non-fatal): %s", exc)
+        self.recycle_count += 1
+        reloaded = self._server_rss()
+        logger.info(
+            "LSP restarted in %.0fs: %s -> %s (recycle #%d)",
+            time.monotonic() - t_restart,
+            format_bytes(used),
+            format_bytes(reloaded),
+            self.recycle_count,
+        )
+        if reloaded >= self._budget:
+            # A workspace whose freshly-loaded footprint already exceeds the
+            # budget cannot be helped by restarting: every batch would trigger
+            # another reload and the phase would make no progress. Say so and
+            # get out of the way — the budget is a fraction of RAM, so running
+            # on may still fit, and a livelock certainly will not.
+            self._disarmed = True
+            logger.warning(
+                "Loading this workspace alone needs %s, at or above the %s budget — memory can no longer be bounded. "
+                "Raise %s or analyze on a host with more RAM.",
+                format_bytes(reloaded),
+                format_bytes(self._budget),
+                MEMORY_BUDGET_ENV_VAR,
+            )
+
+    def _server_rss(self) -> int:
+        pid = self._lsp.pid
+        if pid is None:
+            return 0
+        return process_tree_rss(pid)

codeboarding-0.13.5/static_analyzer/engine/process_memory.py

@@ -0,0 +1,104 @@
+"""Process-tree memory helpers used to enforce the LSP budget."""
+
+import os
+import subprocess
+import sys
+
+_PAGE_SIZE = os.sysconf("SC_PAGE_SIZE") if hasattr(os, "sysconf") else 4096
+_IS_LINUX = sys.platform.startswith("linux")
+
+
+def physical_memory_bytes() -> int:
+    """Return total physical memory, or zero when it cannot be determined."""
+    try:
+        return os.sysconf("SC_PHYS_PAGES") * os.sysconf("SC_PAGE_SIZE")
+    except (ValueError, OSError, AttributeError):
+        return 0
+
+
+def format_bytes(num_bytes: float) -> str:
+    """Render a byte count as a short human-readable string."""
+    for unit in ("B", "KB", "MB", "GB"):
+        if abs(num_bytes) < 1024.0:
+            return f"{num_bytes:.0f}{unit}" if unit == "B" else f"{num_bytes:.1f}{unit}"
+        num_bytes /= 1024.0
+    return f"{num_bytes:.1f}TB"
+
+
+def _linux_process_table() -> dict[int, tuple[int, int]]:
+    """Return each readable Linux process as ``{pid: (ppid, rss_bytes)}``."""
+    table: dict[int, tuple[int, int]] = {}
+    try:
+        entries = os.listdir("/proc")
+    except OSError:
+        return table
+
+    for entry in entries:
+        if not entry.isdigit():
+            continue
+        pid = int(entry)
+        try:
+            with open(f"/proc/{pid}/stat", "rb") as handle:
+                stat = handle.read().decode("utf-8", errors="replace")
+        except OSError:
+            continue
+
+        close_paren = stat.rfind(")")
+        if close_paren == -1:
+            continue
+        fields = stat[close_paren + 2 :].split()
+        if len(fields) < 22:
+            continue
+        try:
+            table[pid] = (int(fields[1]), int(fields[21]) * _PAGE_SIZE)
+        except ValueError:
+            continue
+    return table
+
+
+def _ps_process_table() -> dict[int, tuple[int, int]]:
+    """Return each readable macOS/BSD process as ``{pid: (ppid, rss_bytes)}``."""
+    table: dict[int, tuple[int, int]] = {}
+    try:
+        output = subprocess.run(
+            ["ps", "-axo", "pid=,ppid=,rss="],
+            capture_output=True,
+            text=True,
+            timeout=20,
+        ).stdout
+    except (OSError, subprocess.SubprocessError):
+        return table
+
+    for line in output.splitlines():
+        parts = line.split()
+        if len(parts) != 3:
+            continue
+        try:
+            pid, ppid, rss_kb = int(parts[0]), int(parts[1]), int(parts[2])
+        except ValueError:
+            continue
+        table[pid] = (ppid, rss_kb * 1024)
+    return table
+
+
+def process_tree_rss(root_pid: int) -> int:
+    """Return resident memory held by a process and all its descendants."""
+    table = _linux_process_table() if _IS_LINUX else _ps_process_table()
+    if root_pid not in table:
+        return 0
+
+    children_by_parent: dict[int, list[int]] = {}
+    for pid, (parent_pid, _) in table.items():
+        children_by_parent.setdefault(parent_pid, []).append(pid)
+
+    total = 0
+    stack = [root_pid]
+    seen: set[int] = set()
+    while stack:
+        pid = stack.pop()
+        if pid in seen:
+            continue
+        seen.add(pid)
+        total += table[pid][1]
+        stack.extend(children_by_parent.get(pid, []))
+    return total