refactor(robot): extract Namespace into DTO with event-driven invalidation

Split the monolithic Namespace class into focused modules to reduce
complexity and improve maintainability. The Namespace is now a pure data
container built by NamespaceBuilder, with dedicated modules for import
resolution, AST analysis, variable scoping, and scope trees.

Author: d-biehl

packages/language_server/src/robotcode/language_server/robotframework/parts/code_action_refactor.py

@@ -502,7 +502,7 @@ def resolve_code_action_assign_result_to_variable(
         counter = 0
         namespace = self.parent.documents_cache.get_namespace(document)
         while True:
-            if namespace.find_variable(f"${{{var_name}}}", nodes, range.start, ignore_error=True) is None:
+            if namespace.find_variable(f"${{{var_name}}}", range.start) is None:
                 break
             counter += 1
             var_name = f"new_variable_{counter}"

packages/language_server/src/robotcode/language_server/robotframework/parts/completion.py

@@ -493,7 +493,7 @@ def resolve(self, completion_item: CompletionItem) -> CompletionItem:
 
                         elif (name := data.get("name", None)) is not None:
                             try:
-                                lib_doc = self.namespace.imports_manager.get_libdoc_for_resource_import(
+                                lib_doc = self.namespace.imports_manager.get_resource_doc_for_resource_import(
                                     name,
                                     str(document.uri.to_path().parent),
                                     variables=self.namespace.get_resolvable_variables(),
@@ -623,7 +623,7 @@ def create_variables_completion_items(
                 text_edit=TextEdit(range=range, new_text=s.name[2:-1]),
                 filter_text=s.name[2:-1] if range is not None else None,
             )
-            for s in (self.namespace.get_variable_matchers(list(reversed(nodes)), position)).values()
+            for s in (self.namespace.get_variable_matchers(position)).values()
             if s.name is not None and (s.name_token is None or not position.is_in_range(range_from_token(s.name_token)))
         ]
 
@@ -1705,7 +1705,7 @@ def complete_import() -> Optional[List[CompletionItem]]:
                 complete_list = self.namespace.imports_manager.complete_library_import(
                     first_part if first_part else None,
                     str(self.document.uri.to_path().parent),
-                    self.namespace.get_resolvable_variables(nodes_at_position, position),
+                    self.namespace.get_resolvable_variables(position),
                 )
                 if not complete_list:
                     return None
@@ -1907,7 +1907,7 @@ def complete_ResourceImport(  # noqa: N802
             complete_list = self.namespace.imports_manager.complete_resource_import(
                 first_part if first_part else None,
                 str(self.document.uri.to_path().parent),
-                self.namespace.get_resolvable_variables(nodes_at_position, position),
+                self.namespace.get_resolvable_variables(position),
             )
             if not complete_list:
                 return None
@@ -2031,7 +2031,7 @@ def complete_import() -> Optional[List[CompletionItem]]:
                 complete_list = self.namespace.imports_manager.complete_variables_import(
                     first_part if first_part else None,
                     str(self.document.uri.to_path().parent),
-                    self.namespace.get_resolvable_variables(nodes_at_position, position),
+                    self.namespace.get_resolvable_variables(position),
                 )
                 if not complete_list:
                     return None

packages/language_server/src/robotcode/language_server/robotframework/parts/debugging_utils.py

@@ -69,7 +69,7 @@ async def _get_evaluatable_expression(
         token_and_var = next(
             (
                 (t, v)
-                for t, v in self.iter_variables_from_token(token, namespace, nodes, position)
+                for t, v in self.iter_variables_from_token(token, namespace, position)
                 if position in range_from_token(t)
             ),
             None,
@@ -84,7 +84,7 @@ async def _get_evaluatable_expression(
             token_and_var = next(
                 (
                     (var_token, var)
-                    for var_token, var in self.iter_expression_variables_from_token(token, namespace, nodes, position)
+                    for var_token, var in self.iter_expression_variables_from_token(token, namespace, position)
                     if position in range_from_token(var_token)
                 ),
                 None,

packages/language_server/src/robotcode/language_server/robotframework/parts/diagnostics.py

@@ -51,6 +51,7 @@ def _on_initialized(self, sender: Any) -> None:
         self.parent.diagnostics.analyze.add(self.analyze)
         self.parent.documents_cache.namespace_initialized(self._on_namespace_initialized)
         self.parent.documents_cache.libraries_changed.add(self._on_libraries_changed)
+        self.parent.documents_cache.resources_changed.add(self._on_resources_changed)
         self.parent.documents_cache.variables_changed.add(self._on_variables_changed)
 
     def _on_libraries_changed(self, sender: Any, libraries: List[LibraryDoc]) -> None:
@@ -61,6 +62,14 @@ def _on_libraries_changed(self, sender: Any, libraries: List[LibraryDoc]) -> Non
                 if any(lib_doc in lib_docs for lib_doc in libraries):
                     self.parent.diagnostics.force_refresh_document(doc)
 
+    def _on_resources_changed(self, sender: Any, resources: List[LibraryDoc]) -> None:
+        for doc in self.parent.documents.documents:
+            namespace = self.parent.documents_cache.get_only_initialized_namespace(doc)
+            if namespace is not None:
+                lib_docs = (e.library_doc for e in namespace.get_resources().values())
+                if any(lib_doc.source == changed.source for lib_doc in lib_docs for changed in resources):
+                    self.parent.diagnostics.force_refresh_document(doc)
+
     def _on_variables_changed(self, sender: Any, variables: List[LibraryDoc]) -> None:
         for doc in self.parent.documents.documents:
             namespace = self.parent.documents_cache.get_only_initialized_namespace(doc)

packages/language_server/src/robotcode/language_server/robotframework/parts/hover.py

@@ -143,7 +143,7 @@ def _hover_default(self, nodes: List[ast.AST], document: TextDocument, position:
                                 real_value = namespace.imports_manager.resolve_variable(
                                     variable.name,
                                     str(document.uri.to_path().parent),
-                                    namespace.get_resolvable_variables(nodes, position),
+                                    namespace.get_resolvable_variables(position),
                                 )
 
                                 value = _my_repr.repr(real_value)

packages/language_server/src/robotcode/language_server/robotframework/parts/inline_value.py

@@ -16,7 +16,6 @@
 from robotcode.core.utils.logging import LoggingDescriptor
 from robotcode.robot.diagnostics.model_helper import ModelHelper
 from robotcode.robot.utils.ast import (
-    get_nodes_at_position,
     iter_nodes,
     range_from_node,
     range_from_token,
@@ -55,8 +54,6 @@ def collect(
 
         real_range = Range(range.start, min(range.end, context.stopped_location.end))
 
-        nodes = get_nodes_at_position(model, context.stopped_location.start)
-
         def get_tokens() -> Iterator[Tuple[Token, ast.AST]]:
             for n in iter_nodes(model):
                 r = range_from_node(n)
@@ -76,12 +73,12 @@ def get_tokens() -> Iterator[Tuple[Token, ast.AST]]:
         ):
             if token.type == RobotToken.ARGUMENT and isinstance(node, self.get_expression_statement_types()):
                 for t, var in self.iter_expression_variables_from_token(
-                    token, namespace, nodes, context.stopped_location.start
+                    token, namespace, context.stopped_location.start
                 ):
                     if var.name != "${CURDIR}":
                         result.append(InlineValueEvaluatableExpression(range_from_token(t), var.name))
 
-            for t, var in self.iter_variables_from_token(token, namespace, nodes, context.stopped_location.start):
+            for t, var in self.iter_variables_from_token(token, namespace, context.stopped_location.start):
                 if var.name != "${CURDIR}":
                     result.append(InlineValueEvaluatableExpression(range_from_token(t), var.name))
 

packages/language_server/src/robotcode/language_server/robotframework/parts/selection_range.py

@@ -55,7 +55,6 @@ def collect(self, sender: Any, document: TextDocument, positions: List[Position]
                             for var_token, _ in self.iter_variables_from_token(
                                 token,
                                 namespace,
-                                nodes,
                                 position,
                                 return_not_found=True,
                             ):

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

@@ -36,7 +36,7 @@
 from ..utils.stubs import Languages
 from .imports_manager import ImportsManager
 from .library_doc import LibraryDoc
-from .namespace import DocumentType, Namespace
+from .namespace import DocumentType, Namespace, NamespaceBuilder
 from .workspace_config import (
     AnalysisDiagnosticModifiersConfig,
     AnalysisRobotConfig,
@@ -351,7 +351,7 @@ def namespace_initialized(sender, namespace: Namespace) -> None: ...
     @event
     def namespace_invalidated(sender, namespace: Namespace) -> None: ...
 
-    def __invalidate_namespace(self, sender: Namespace) -> None:
+    def _invalidate_namespace(self, sender: Namespace) -> None:
         document = sender.document
         if document is not None:
             document.remove_cache_entry(self.__get_general_namespace)
@@ -360,10 +360,10 @@ def __invalidate_namespace(self, sender: Namespace) -> None:
 
             self.namespace_invalidated(self, sender)
 
-    def __namespace_initialized(self, sender: Namespace) -> None:
-        if sender.document is not None:
-            sender.document.set_data(self.INITIALIZED_NAMESPACE, sender)
-            self.namespace_initialized(self, sender)
+    def __namespace_initialized(self, namespace: Namespace) -> None:
+        if namespace.document is not None:
+            namespace.document.set_data(self.INITIALIZED_NAMESPACE, namespace)
+            self.namespace_initialized(self, namespace)
 
     def get_initialized_namespace(self, document: TextDocument) -> Namespace:
         result: Optional[Namespace] = document.get_data(self.INITIALIZED_NAMESPACE)
@@ -391,7 +391,7 @@ def __get_namespace_for_document_type(
 
         languages, workspace_languages = self.build_languages_from_model(document, model)
 
-        result = Namespace(
+        builder = NamespaceBuilder(
             imports_manager,
             model,
             str(document.uri.to_path()),
@@ -400,8 +400,15 @@ def __get_namespace_for_document_type(
             languages,
             workspace_languages,
         )
-        result.has_invalidated.add(self.__invalidate_namespace)
-        result.has_initialized.add(self.__namespace_initialized)
+
+        result = builder.build()
+
+        # When the namespace detects dependency changes, evict the
+        # document cache entry so it gets rebuilt on next access.
+        result.invalidated.add(self._invalidate_namespace)
+
+        # Mark as initialized for consumers that need early access
+        self.__namespace_initialized(result)
 
         return result