feat(robot): add SQLite cache backend for library and namespace data

Replace file-based pickle caching with a single SQLite database per
workspace, consolidating all cache entries into one file instead of
many individual .pkl files scattered across directories.

Author: d-biehl

packages/robot/src/robotcode/robot/diagnostics/data_cache.py

@@ -1,4 +1,5 @@
 import pickle
+import sqlite3
 from abc import ABC, abstractmethod
 from enum import Enum
 from pathlib import Path
@@ -28,6 +29,9 @@ def read_cache_data(
     @abstractmethod
     def save_cache_data(self, section: CacheSection, entry_name: str, data: Any) -> None: ...
 
+    def close(self) -> None:
+        pass
+
 
 class FileCacheDataBase(DataCache, ABC):
     def __init__(self, cache_dir: Path) -> None:
@@ -89,3 +93,71 @@ def save_cache_data(self, section: CacheSection, entry_name: str, data: Any) ->
         cached_file.parent.mkdir(parents=True, exist_ok=True)
         with cached_file.open("wb") as f:
             pickle.dump(data, f)
+
+
+class SqliteDataCache(DataCache):
+    """Cache backend using a single SQLite database with zlib-compressed pickle blobs."""
+
+    _SCHEMA_VERSION = 1
+
+    def __init__(self, cache_dir: Path) -> None:
+        self.cache_dir = cache_dir
+
+        if not cache_dir.exists():
+            cache_dir.mkdir(parents=True)
+            (cache_dir / ".gitignore").write_text(
+                "# Created by robotcode\n*\n",
+                "utf-8",
+            )
+
+        db_path = cache_dir / "cache.db"
+        self._conn = sqlite3.connect(str(db_path), check_same_thread=False)
+        self._conn.execute("PRAGMA journal_mode=WAL")
+        self._conn.execute("PRAGMA synchronous=NORMAL")
+        self._conn.execute("PRAGMA cache_size=-8000")
+        self._conn.execute("PRAGMA mmap_size=67108864")
+        self._conn.execute(
+            "CREATE TABLE IF NOT EXISTS cache_entries ("
+            "  section TEXT NOT NULL,"
+            "  entry_name TEXT NOT NULL,"
+            "  data BLOB NOT NULL,"
+            "  PRIMARY KEY (section, entry_name)"
+            ")"
+        )
+        self._conn.commit()
+
+    def cache_data_exists(self, section: CacheSection, entry_name: str) -> bool:
+        row = self._conn.execute(
+            "SELECT 1 FROM cache_entries WHERE section = ? AND entry_name = ?",
+            (section.value, entry_name),
+        ).fetchone()
+        return row is not None
+
+    def read_cache_data(
+        self, section: CacheSection, entry_name: str, types: Union[Type[_T], Tuple[Type[_T], ...]]
+    ) -> _T:
+        row = self._conn.execute(
+            "SELECT data FROM cache_entries WHERE section = ? AND entry_name = ?",
+            (section.value, entry_name),
+        ).fetchone()
+
+        if row is None:
+            raise FileNotFoundError(f"No cache entry for {section.value}/{entry_name}")
+
+        result = pickle.loads(row[0])
+
+        if isinstance(result, types):
+            return cast(_T, result)
+
+        raise TypeError(f"Expected {types} but got {type(result)}")
+
+    def save_cache_data(self, section: CacheSection, entry_name: str, data: Any) -> None:
+        blob = pickle.dumps(data, protocol=pickle.HIGHEST_PROTOCOL)
+        self._conn.execute(
+            "INSERT OR REPLACE INTO cache_entries (section, entry_name, data) VALUES (?, ?, ?)",
+            (section.value, entry_name, blob),
+        )
+        self._conn.commit()
+
+    def close(self) -> None:
+        self._conn.close()

packages/robot/src/robotcode/robot/diagnostics/imports_manager.py

@@ -53,7 +53,7 @@
 from ..utils.robot_path import find_file_ex
 from ..utils.variables import contains_variable
 from .data_cache import CacheSection
-from .data_cache import PickleDataCache as DefaultDataCache
+from .data_cache import SqliteDataCache as DefaultDataCache
 from .entities import (
     CommandLineVariableDefinition,
     VariableDefinition,
@@ -612,6 +612,7 @@ def __init__(
             / f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
             / get_robot_version_str()
         )
+        weakref.finalize(self, DefaultDataCache.close, self.data_cache)
 
         self.cmd_variables = variables
         self.cmd_variable_files = variable_files

packages/robot/src/robotcode/robot/diagnostics/namespace.py

@@ -126,6 +126,14 @@ class NamespaceData:
     # --- ScopeTree (local scopes only, file_scope is reconstructed) ---
     local_scopes: List[LocalScope] = field(default_factory=list)
 
+    # --- Authoritative variable definitions (stable_id → VariableDefinition) ---
+    # Stores the exact VariableDefinition objects that were referenced during
+    # analysis. Used as fallback in from_data() when the re-parsed resource doc
+    # produces variables with different stable_ids (e.g. col_offset differences
+    # for variables with '=' suffix, or keyword argument definitions from
+    # imported keywords that aren't in the file's own scope).
+    variable_definitions: Dict[str, VariableDefinition] = field(default_factory=dict)
+
 
 class Namespace:
     """Data container holding all results of a namespace build.
@@ -450,6 +458,42 @@ def to_data(self) -> NamespaceData:
             key = f"{type(entry).__name__}:{entry.import_name}:{entry.args!r}:{entry.alias or ''}"
             ns_refs[key] = locs
 
+        # Collect all referenced variable definitions for stable_id → object lookup
+        all_var_defs: Dict[str, VariableDefinition] = {}
+        for var in self._variable_references:
+            all_var_defs[var.stable_id] = var
+        for var in self._local_variable_assignments:
+            all_var_defs[var.stable_id] = var
+
+        # Build keyword_references merging locations when different KeywordDoc
+        # objects share the same stable_id (e.g. same library imported with
+        # different aliases like "errorlib" and "noerrorlib").
+        kw_refs_merged: Dict[str, Set[Location]] = {}
+        for kw, locs in self._keyword_references.items():
+            sid = kw.stable_id
+            if sid in kw_refs_merged:
+                kw_refs_merged[sid].update(locs)
+            else:
+                kw_refs_merged[sid] = set(locs)
+
+        # Same merge for variable_references (different VariableDefinition
+        # objects could theoretically share a stable_id).
+        var_refs_merged: Dict[str, Set[Location]] = {}
+        for var, locs in self._variable_references.items():
+            sid = var.stable_id
+            if sid in var_refs_merged:
+                var_refs_merged[sid].update(locs)
+            else:
+                var_refs_merged[sid] = set(locs)
+
+        var_assigns_merged: Dict[str, Set[Range]] = {}
+        for var, ranges in self._local_variable_assignments.items():
+            sid = var.stable_id
+            if sid in var_assigns_merged:
+                var_assigns_merged[sid].update(ranges)
+            else:
+                var_assigns_merged[sid] = set(ranges)
+
         return NamespaceData(
             source=self.source,
             source_id=str(self.source_id) if self.source_id else None,
@@ -459,16 +503,15 @@ def to_data(self) -> NamespaceData:
             imports=list(self._import_entries.keys()),
             diagnostics=list(self._diagnostics),
             test_case_definitions=list(self._test_case_definitions),
-            keyword_references={kw.stable_id: set(locs) for kw, locs in self._keyword_references.items()},
-            variable_references={var.stable_id: set(locs) for var, locs in self._variable_references.items()},
-            local_variable_assignments={
-                var.stable_id: set(ranges) for var, ranges in self._local_variable_assignments.items()
-            },
+            keyword_references=kw_refs_merged,
+            variable_references=var_refs_merged,
+            local_variable_assignments=var_assigns_merged,
             namespace_references=ns_refs,
             keyword_tag_references={k: set(v) for k, v in self._keyword_tag_references.items()},
             testcase_tag_references={k: set(v) for k, v in self._testcase_tag_references.items()},
             metadata_references={k: set(v) for k, v in self._metadata_references.items()},
             local_scopes=list(self._scope_tree.local_scopes),
+            variable_definitions=all_var_defs,
         )
 
     @classmethod
@@ -528,11 +571,29 @@ def from_data(
         for var in scope.iter_all():
             var_by_id[var.stable_id] = var
 
+        # Add keyword argument_definitions from all resolved keywords
+        # to var_by_id. This covers ArgumentDefinition and
+        # LibraryArgumentDefinition objects that are created during
+        # Phase 3 analysis but aren't part of the file's own scope.
+        for kw in kw_by_id.values():
+            if kw.argument_definitions:
+                for arg_var in kw.argument_definitions:
+                    var_by_id[arg_var.stable_id] = arg_var
+
         # Variables from local scopes (block-level LOCAL_VARIABLE, arguments, etc.)
         for ls in data.local_scopes:
             for sv in ls.variables:
                 var_by_id[sv.variable.stable_id] = sv.variable
 
+        # Fallback: use stored variable definitions for any stable_ids
+        # not found in the rebuilt scope. This handles variables whose
+        # stable_ids differ due to re-parsing differences (e.g. col_offset
+        # for variables with '=' suffix) and keyword argument definitions
+        # from imported keywords that aren't in the file's own scope.
+        for sid, var_def in data.variable_definitions.items():
+            if sid not in var_by_id:
+                var_by_id[sid] = var_def
+
         # --- Reconstruct reference dicts ---
         keyword_references: Dict[KeywordDoc, Set[Location]] = {}
         for sid, locs in data.keyword_references.items():