codegraph-engine 3.0.0__2-py3-none-any.whl

codegraph/resources/__init__.py

@@ -0,0 +1,46 @@
+"""Resource Management, Concurrency Throttling, and Laptop Protection.
+
+Provides:
+- ResourceGovernor: Priority scheduling, cooperative yielding, process memory monitoring
+- ResourcePolicy: Profiles (LIGHT, BALANCED, PERFORMANCE), bounds, and thresholds
+- RequestCoalescer: De-duplicating identical concurrent flights
+- FileChangeDebouncer: Coalescing editor save bursts
+- BoundedMemoryCache: Memory-bounded LRU caches for parse results and graphs
+"""
+from __future__ import annotations
+
+from .cache import (
+    BoundedMemoryCache,
+    get_graph_cache,
+    get_parse_cache,
+)
+from .coalescer import RequestCoalescer, get_global_coalescer
+from .debouncer import FileChangeDebouncer
+from .governor import ResourceGovernor, get_global_governor
+from .monitor import get_process_memory_mb
+from .policy import (
+    ActivityMode,
+    PressureLevel,
+    ResourcePolicy,
+    ResourceProfile,
+    ResourceState,
+    TaskPriority,
+)
+
+__all__ = [
+    "ActivityMode",
+    "BoundedMemoryCache",
+    "FileChangeDebouncer",
+    "PressureLevel",
+    "RequestCoalescer",
+    "ResourceGovernor",
+    "ResourcePolicy",
+    "ResourceProfile",
+    "ResourceState",
+    "TaskPriority",
+    "get_global_coalescer",
+    "get_global_governor",
+    "get_graph_cache",
+    "get_parse_cache",
+    "get_process_memory_mb",
+]

codegraph/resources/cache.py

@@ -0,0 +1,117 @@
+"""Bounded LRU Memory Caches with Size Tracking and Eviction.
+
+Prevents unbounded memory growth from ParseResults, graph neighborhoods,
+and retrieval artifacts during sustained coding sessions.
+"""
+from __future__ import annotations
+
+import sys
+import threading
+from collections import OrderedDict
+from collections.abc import Callable
+from typing import Any
+
+
+def _approx_size(obj: Any) -> int:
+    """Approximate memory footprint of an object."""
+    try:
+        if isinstance(obj, (str, bytes)):
+            return len(obj)
+        elif hasattr(obj, "__sizeof__"):
+            return int(obj.__sizeof__())
+        return sys.getsizeof(obj, 128)
+    except Exception:
+        return 128
+
+
+class BoundedMemoryCache[K, V]:
+    """Thread-safe LRU cache with both item count and memory byte limits."""
+
+    def __init__(self, max_items: int = 500, max_bytes: int = 50 * 1024 * 1024) -> None:
+        self.max_items = max_items
+        self.max_bytes = max_bytes
+        self._lock = threading.Lock()
+        self._cache: OrderedDict[K, tuple[V, int]] = OrderedDict()
+        self._current_bytes: int = 0
+        self._hits: int = 0
+        self._misses: int = 0
+
+    def get(self, key: K) -> V | None:
+        with self._lock:
+            if key not in self._cache:
+                self._misses += 1
+                return None
+            val, size = self._cache.pop(key)
+            self._cache[key] = (val, size)  # move to end (MRU)
+            self._hits += 1
+            return val
+
+    def put(self, key: K, value: V, size_bytes: int | None = None) -> None:
+        sz = size_bytes if size_bytes is not None else _approx_size(value)
+        with self._lock:
+            if key in self._cache:
+                _, old_sz = self._cache.pop(key)
+                self._current_bytes -= old_sz
+
+            self._cache[key] = (value, sz)
+            self._current_bytes += sz
+
+            # Evict until limits are satisfied
+            while len(self._cache) > self.max_items or (self._current_bytes > self.max_bytes and len(self._cache) > 1):
+                _, (_, evicted_sz) = self._cache.popitem(last=False)  # pop LRU
+                self._current_bytes -= evicted_sz
+
+    def set(self, key: K, value: V, size_bytes: int | None = None) -> None:
+        """Alias for put."""
+        self.put(key, value, size_bytes)
+
+    def invalidate(self, predicate: Callable[[K], bool]) -> int:
+        removed = 0
+        with self._lock:
+            keys_to_del = [k for k in self._cache if predicate(k)]
+            for k in keys_to_del:
+                _, sz = self._cache.pop(k)
+                self._current_bytes -= sz
+                removed += 1
+        return removed
+
+    def clear(self) -> None:
+        with self._lock:
+            self._cache.clear()
+            self._current_bytes = 0
+
+    def stats(self) -> dict[str, object]:
+        with self._lock:
+            return {
+                "items": len(self._cache),
+                "max_items": self.max_items,
+                "current_mb": round(self._current_bytes / (1024 * 1024), 2),
+                "max_mb": round(self.max_bytes / (1024 * 1024), 2),
+                "hits": self._hits,
+                "misses": self._misses,
+            }
+
+
+# ---------------------------------------------------------------------------
+# Global Specialized Caches
+# ---------------------------------------------------------------------------
+
+# ParseResult cache: (source_hash, parser_version, language) -> ParseResult
+_PARSE_CACHE: BoundedMemoryCache[tuple[str, str, str], Any] = BoundedMemoryCache(
+    max_items=300,
+    max_bytes=30 * 1024 * 1024,  # 30 MB
+)
+
+# Graph neighborhood cache: (repo_generation, symbol_id, relationship, depth) -> list[dict]
+_GRAPH_CACHE: BoundedMemoryCache[tuple[int, str, str, int], Any] = BoundedMemoryCache(
+    max_items=500,
+    max_bytes=20 * 1024 * 1024,  # 20 MB
+)
+
+
+def get_parse_cache() -> BoundedMemoryCache[tuple[str, str, str], Any]:
+    return _PARSE_CACHE
+
+
+def get_graph_cache() -> BoundedMemoryCache[tuple[int, str, str, int], Any]:
+    return _GRAPH_CACHE

codegraph/resources/coalescer.py

@@ -0,0 +1,83 @@
+"""Thread-safe Request Coalescing and In-Flight Flight Sharing.
+
+Prevents duplicate concurrent executions of identical read or compilation requests
+by allowing concurrent callers to share a single in-flight computation.
+"""
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from typing import Any
+
+
+class _InFlight[T]:
+    def __init__(self) -> None:
+        self.event = threading.Event()
+        self.result: T | None = None
+        self.error: BaseException | None = None
+
+
+class RequestCoalescer:
+    """Coalesces identical concurrent tasks into a single execution."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._flights: dict[str, _InFlight[Any]] = {}
+        self._coalesced_count: int = 0
+        self._total_requests: int = 0
+
+    def coalesce[T](self, key: str, fn: Callable[[], T]) -> T:
+        """Execute fn() or wait for an identical in-flight execution under the given key."""
+        with self._lock:
+            self._total_requests += 1
+            flight: _InFlight[T] | None = self._flights.get(key)
+            if flight is not None:
+                is_leader = False
+                self._coalesced_count += 1
+            else:
+                is_leader = True
+                flight = _InFlight[T]()
+                self._flights[key] = flight
+
+        if not is_leader:
+            # Wait for leader to complete computation
+            flight.event.wait()
+            if flight.error is not None:
+                raise flight.error
+            return flight.result  # type: ignore[return-value]
+
+        # Leader executes fn()
+        try:
+            res = fn()
+            flight.result = res
+            return res
+        except BaseException as exc:
+            flight.error = exc
+            raise
+        finally:
+            with self._lock:
+                self._flights.pop(key, None)
+            flight.event.set()
+
+    def in_flight_count(self) -> int:
+        with self._lock:
+            return len(self._flights)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._flights.clear()
+
+    def stats(self) -> dict[str, object]:
+        with self._lock:
+            return {
+                "in_flight": len(self._flights),
+                "total_requests": self._total_requests,
+                "coalesced_requests": self._coalesced_count,
+            }
+
+
+_GLOBAL_COALESCER = RequestCoalescer()
+
+
+def get_global_coalescer() -> RequestCoalescer:
+    return _GLOBAL_COALESCER

codegraph/resources/debouncer.py

@@ -0,0 +1,98 @@
+"""File Change Debouncer and Burst Coalescer.
+
+Coalesces rapid file system save events from code editors into bounded batches
+to prevent repeated, wasteful index cycles.
+"""
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Callable
+from pathlib import Path
+
+
+class FileChangeDebouncer:
+    """Thread-safe debounce accumulator for editor save bursts."""
+
+    def __init__(
+        self,
+        debounce_ms: int = 500,
+        max_batch_size: int = 100,
+        on_batch: Callable[[set[str]], None] | None = None,
+    ) -> None:
+        self.debounce_ms = debounce_ms
+        self.max_batch_size = max_batch_size
+        self.on_batch = on_batch
+
+        self._lock = threading.Lock()
+        self._pending_paths: set[str] = set()
+        self._timer: threading.Timer | None = None
+        self._last_event_time: float = 0.0
+
+    def add_change(self, path: str | Path) -> None:
+        """Record a file modification or save event."""
+        p_str = path.as_posix() if isinstance(path, Path) else str(path)
+        with self._lock:
+            self._pending_paths.add(p_str)
+            self._last_event_time = time.time()
+
+            if len(self._pending_paths) >= self.max_batch_size:
+                self._dispatch_locked()
+                return
+
+            if self._timer is not None:
+                self._timer.cancel()
+
+            delay_sec = self.debounce_ms / 1000.0
+            self._timer = threading.Timer(delay_sec, self._on_timer_fired)
+            self._timer.daemon = True
+            self._timer.start()
+
+    def _on_timer_fired(self) -> None:
+        with self._lock:
+            self._dispatch_locked()
+
+    def _dispatch_locked(self) -> None:
+        if self._timer is not None:
+            self._timer.cancel()
+            self._timer = None
+
+        if not self._pending_paths:
+            return
+
+        batch = set(self._pending_paths)
+        self._pending_paths.clear()
+
+        if self.on_batch:
+            # Dispatch outside lock or in thread to avoid deadlocks
+            threading.Thread(target=self.on_batch, args=(batch,), daemon=True).start()
+
+    def flush(self) -> set[str]:
+        """Synchronously drain all pending coalesced paths."""
+        with self._lock:
+            if self._timer is not None:
+                self._timer.cancel()
+                self._timer = None
+            batch = set(self._pending_paths)
+            self._pending_paths.clear()
+            return batch
+
+    def pending_count(self) -> int:
+        with self._lock:
+            return len(self._pending_paths)
+
+    def record_change(self, path: str | Path) -> None:
+        """Alias for add_change."""
+        self.add_change(path)
+
+    def start(self, on_batch: Callable[[set[str]], None]) -> None:
+        """Configure or update batch callback."""
+        with self._lock:
+            self.on_batch = on_batch
+
+    def stop(self) -> None:
+        """Cancel any pending timer."""
+        with self._lock:
+            if self._timer is not None:
+                self._timer.cancel()
+                self._timer = None

codegraph/resources/governor.py

@@ -0,0 +1,219 @@
+"""Central Resource Governor for CodeGraph MCP.
+
+Protects developer laptop responsiveness during active coding by bounding concurrency,
+throttling background indexing, managing process memory, and cooperatively yielding.
+"""
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+from .monitor import get_process_memory_mb
+from .policy import (
+    ActivityMode,
+    PressureLevel,
+    ResourcePolicy,
+    ResourceProfile,
+    ResourceState,
+    TaskPriority,
+)
+
+
+class ResourceGovernor:
+    """Thread-safe central resource governor and priority scheduler."""
+
+    def __init__(self, policy: ResourcePolicy | None = None) -> None:
+        self.policy = policy or ResourcePolicy.for_profile(ResourceProfile.BALANCED)
+        self._lock = threading.RLock()
+        self._condition = threading.Condition(self._lock)
+
+        self._active_interactive: int = 0
+        self._active_background: int = 0
+        self._queued_tasks: int = 0
+        self._indexing_active: bool = False
+        self._watcher_active: bool = False
+
+        self._last_interactive_time: float = 0.0
+        self._last_file_change_time: float = 0.0
+
+        self._recent_cpu_time_ms: float = 0.0
+        self._recent_wall_time_ms: float = 0.0
+
+        self._interactive_sem = threading.Semaphore(self.policy.max_interactive_workers)
+        self._background_sem = threading.Semaphore(self.policy.max_background_workers)
+
+    def set_policy(self, policy: ResourcePolicy) -> None:
+        """Update runtime policy dynamically."""
+        with self._lock:
+            self.policy = policy
+            self._interactive_sem = threading.Semaphore(policy.max_interactive_workers)
+            self._background_sem = threading.Semaphore(policy.max_background_workers)
+            self._condition.notify_all()
+
+    def record_activity(self, kind: str = "interactive") -> None:
+        """Record non-invasive activity to maintain active coding state."""
+        now = time.time()
+        with self._lock:
+            if kind == "file_change":
+                self._last_file_change_time = now
+            else:
+                self._last_interactive_time = now
+
+    def get_activity_mode(self) -> ActivityMode:
+        """Infer activity mode from recent MCP and file change events."""
+        with self._lock:
+            now = time.time()
+            recent_interactive = (now - self._last_interactive_time) < 45.0
+            recent_files = (now - self._last_file_change_time) < 45.0
+            if recent_interactive or recent_files:
+                return ActivityMode.ACTIVE_CODING
+            if self._active_background > 0 or self._indexing_active:
+                return ActivityMode.BACKGROUND
+            return ActivityMode.IDLE
+
+    def is_active_coding(self) -> bool:
+        return self.get_activity_mode() == ActivityMode.ACTIVE_CODING
+
+    def get_pressure(self) -> PressureLevel:
+        """Compute system resource pressure with conservative hysteresis."""
+        mem_mb = get_process_memory_mb()
+        limit_mb = self.policy.max_memory_mb
+
+        with self._lock:
+            active_inter = self._active_interactive
+
+        if mem_mb is not None and limit_mb and mem_mb >= limit_mb * 0.90:
+            return PressureLevel.CRITICAL
+        if active_inter >= self.policy.max_interactive_workers * 2:
+            return PressureLevel.CRITICAL
+
+        if mem_mb is not None and limit_mb and mem_mb >= limit_mb * 0.75:
+            return PressureLevel.HIGH
+        if active_inter > self.policy.max_interactive_workers:
+            return PressureLevel.HIGH
+
+        if mem_mb is not None and limit_mb and mem_mb >= limit_mb * 0.60:
+            return PressureLevel.ELEVATED
+        if active_inter > 0:
+            return PressureLevel.ELEVATED
+
+        return PressureLevel.NORMAL
+
+    def should_throttle(self, priority: TaskPriority = TaskPriority.BACKGROUND) -> bool:
+        """Check whether a background or maintenance task should throttle or yield."""
+        if priority in (TaskPriority.INTERACTIVE_HIGH, TaskPriority.INTERACTIVE_NORMAL):
+            return False
+        pressure = self.get_pressure()
+        if pressure in (PressureLevel.CRITICAL, PressureLevel.HIGH):
+            return True
+        return self.is_active_coding()
+
+    def yield_if_needed(self, priority: TaskPriority = TaskPriority.BACKGROUND) -> None:
+        """Cooperative yield point for long-running iterative tasks."""
+        if priority in (TaskPriority.INTERACTIVE_HIGH, TaskPriority.INTERACTIVE_NORMAL):
+            return
+
+        pressure = self.get_pressure()
+        if pressure == PressureLevel.CRITICAL:
+            # Under critical pressure, background work yields for 100ms
+            time.sleep(0.10)
+        elif pressure == PressureLevel.HIGH or self.is_active_coding():
+            # Under high pressure or active coding, yield 20ms to free up CPU
+            time.sleep(0.02)
+        else:
+            # Minimal cooperative yield to let OS reschedule other threads
+            time.sleep(0.001)
+
+    def get_state(self) -> ResourceState:
+        """Snapshot current resource state."""
+        mem = get_process_memory_mb()
+        pressure = self.get_pressure()
+        mode = self.get_activity_mode()
+        with self._lock:
+            return ResourceState(
+                policy_profile=self.policy.profile.value,
+                active_interactive_requests=self._active_interactive,
+                active_background_tasks=self._active_background,
+                queued_tasks=self._queued_tasks,
+                recent_cpu_time_ms=round(self._recent_cpu_time_ms, 2),
+                recent_wall_time_ms=round(self._recent_wall_time_ms, 2),
+                estimated_memory_mb=mem,
+                pressure_level=pressure.value,
+                activity_mode=mode.value,
+                indexing_active=self._indexing_active,
+                watcher_active=self._watcher_active,
+            )
+
+    @contextmanager
+    def task_scope(
+        self,
+        priority: TaskPriority = TaskPriority.INTERACTIVE_HIGH,
+        task_id: str | None = None,
+    ) -> Iterator[None]:
+        """Scoped execution guard that handles priority scheduling, tracking, and yielding."""
+        del task_id
+        is_interactive = priority in (TaskPriority.INTERACTIVE_HIGH, TaskPriority.INTERACTIVE_NORMAL)
+        sem = self._interactive_sem if is_interactive else self._background_sem
+
+        with self._lock:
+            self._queued_tasks += 1
+            if is_interactive:
+                self.record_activity("interactive")
+
+        sem.acquire()
+        try:
+            throttle = False
+            with self._lock:
+                self._queued_tasks = max(0, self._queued_tasks - 1)
+                if is_interactive:
+                    self._active_interactive += 1
+                else:
+                    self._active_background += 1
+                    if self.is_active_coding() and self.policy.aggressive_throttling:
+                        throttle = True
+            if throttle:
+                time.sleep(0.01)
+
+            t0_cpu = time.process_time()
+            t0_wall = time.perf_counter()
+            try:
+                yield
+            finally:
+                elapsed_cpu = (time.process_time() - t0_cpu) * 1000
+                elapsed_wall = (time.perf_counter() - t0_wall) * 1000
+                with self._lock:
+                    if is_interactive:
+                        self._active_interactive = max(0, self._active_interactive - 1)
+                        self._last_interactive_time = time.time()
+                    else:
+                        self._active_background = max(0, self._active_background - 1)
+                    self._recent_cpu_time_ms = elapsed_cpu
+                    self._recent_wall_time_ms = elapsed_wall
+                    self._condition.notify_all()
+        finally:
+            sem.release()
+
+    def set_indexing_active(self, active: bool) -> None:
+        with self._lock:
+            self._indexing_active = active
+
+    def set_watcher_active(self, active: bool) -> None:
+        with self._lock:
+            self._watcher_active = active
+
+
+_GLOBAL_GOVERNOR: ResourceGovernor | None = None
+_GOVERNOR_LOCK = threading.Lock()
+
+
+def get_global_governor(policy: ResourcePolicy | None = None) -> ResourceGovernor:
+    """Access the singleton resource governor for the current process."""
+    global _GLOBAL_GOVERNOR
+    with _GOVERNOR_LOCK:
+        if _GLOBAL_GOVERNOR is None:
+            _GLOBAL_GOVERNOR = ResourceGovernor(policy)
+        elif policy is not None:
+            _GLOBAL_GOVERNOR.set_policy(policy)
+        return _GLOBAL_GOVERNOR

codegraph/resources/monitor.py

@@ -0,0 +1,102 @@
+"""Cross-platform process resource monitoring for CodeGraph.
+
+Provides portable resident memory (RSS) measurements across Windows, macOS,
+and Linux without requiring Unix-only APIs at import or runtime.
+"""
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+
+def _get_unix_memory_mb() -> float | None:
+    """Read process RSS using standard library resource module on Unix."""
+    try:
+        import resource  # Unix-only standard library module
+
+        usage = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
+        if sys.platform == "darwin":
+            # macOS ru_maxrss is returned in bytes
+            return round(usage / (1024 * 1024), 2)
+        else:
+            # Linux and BSD ru_maxrss is returned in kilobytes
+            return round(usage / 1024, 2)
+    except Exception:
+        return None
+
+
+def _get_psutil_memory_mb() -> float | None:
+    """Read process RSS using psutil if installed."""
+    try:
+        import psutil
+
+        rss_bytes = float(psutil.Process().memory_info().rss)
+        return round(rss_bytes / (1024 * 1024), 2)
+    except Exception:
+        return None
+
+
+def _get_windows_memory_mb_ctypes() -> float | None:
+    """Read process RSS on Windows using standard library ctypes (zero dependencies)."""
+    try:
+        import ctypes
+        from ctypes import wintypes
+
+        class PROCESS_MEMORY_COUNTERS(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: Any = getattr(ctypes, "windll", None)
+        if windll is None:
+            return None
+
+        handle = windll.kernel32.GetCurrentProcess()
+        counters = PROCESS_MEMORY_COUNTERS()
+        counters.cb = ctypes.sizeof(PROCESS_MEMORY_COUNTERS)
+
+        # On Windows 7+, K32GetProcessMemoryInfo is in kernel32; otherwise in psapi
+        get_info = getattr(windll.kernel32, "K32GetProcessMemoryInfo", None)
+        if get_info is None:
+            psapi = getattr(windll, "psapi", None)
+            if psapi is not None:
+                get_info = getattr(psapi, "GetProcessMemoryInfo", None)
+
+        if get_info is not None and bool(get_info(handle, ctypes.byref(counters), counters.cb)):
+            # WorkingSetSize is the resident set size in bytes
+            return round(float(counters.WorkingSetSize) / (1024 * 1024), 2)
+    except Exception:
+        return None
+    return None
+
+
+def get_process_memory_mb() -> float | None:
+    """Return estimated resident process memory in megabytes cross-platform.
+
+    Returns:
+        float: Estimated memory in MB if measurement is supported and succeeds.
+        None: If measurement is unsupported or fails (degrades gracefully to UNKNOWN).
+    """
+    if sys.platform == "win32":
+        # 1. On Windows: try psutil first, then ctypes Windows API
+        mem = _get_psutil_memory_mb()
+        if mem is not None:
+            return mem
+        return _get_windows_memory_mb_ctypes()
+
+    # 2. On Unix-like platforms (macOS, Linux): try standard resource module
+    mem = _get_unix_memory_mb()
+    if mem is not None:
+        return mem
+
+    # 3. Fallback to psutil on any platform if resource module failed or is unavailable
+    return _get_psutil_memory_mb()