feat(robot): introduce SemanticModel for richer Robot Framework analysis (Part 1)

Introduce the first part of an opt-in SemanticModel that provides deeper
static analysis of Robot Framework files, available behind a feature flag.

Enable via robot.toml:

    [tool.robotcode-analyze]
    semantic-model = true

or in VS Code settings:

    "robotcode.experimental.semanticModel": true

- Nested variable resolution: variables like ${DICT_${key}} are now
  statically resolved where possible, with diagnostics when resolution
  fails
- Richer semantic highlighting: token classification driven by the
  semantic model instead of syntactic heuristics
- RF 7.4 type hint support: KeywordName/KeywordArgument annotations are
  recognized for run-keyword detection
- Log output to verify which analyzer is active
- Robust deserialization of cached library data when new fields are added

The SemanticModel is disabled by default. Further parts will add
additional LSP feature migrations and extended analysis capabilities.

Author: d-biehl

docs/03_reference/cli.md

@@ -3156,6 +3156,27 @@ Examples:
 warning = ["VariableNotFound", "multiple-keywords"]
 ```
 
+## tool.robotcode-analyze.semantic-model
+
+Type: `bool | None`
+
+Enable the experimental Semantic Model for code analysis. When enabled, LSP features
+use the new SemanticAnalyzer instead of the legacy NamespaceAnalyzer. This provides
+richer analysis including static resolution of nested variables and improved semantic
+highlighting.
+
+**This is experimental and may change without notice.**
+
+Can also be set via VS Code setting `robotcode.experimental.semanticModel`.
+If set in both places, either `true` value enables the feature.
+
+Examples:
+
+```toml
+[tool.robotcode-analyze]
+semantic-model = true
+```
+
 ## variable-files
 
 Type: `list[str | StringExpression] | None`

docs/03_reference/config.md

@@ -144,6 +144,15 @@
           "default": null,
           "description": "Defines the modifiers for the analysis.\n\nExamples:\n\n```toml\n[tool.robotcode-analyze.modifiers]\nignore = [\"VariableNotFound\"]\nhint = [\"KeywordNotFound\"]\ninformation = [\"MultipleKeywords\"]\n```\n",
           "title": "Modifiers"
+        },
+        "semantic-model": {
+          "default": null,
+          "description": "Enable the experimental Semantic Model for code analysis. When enabled, LSP features\nuse the new SemanticAnalyzer instead of the legacy NamespaceAnalyzer. This provides\nricher analysis including static resolution of nested variables and improved semantic\nhighlighting.\n\n**This is experimental and may change without notice.**\n\nCan also be set via VS Code setting `robotcode.experimental.semanticModel`.\nIf set in both places, either `true` value enables the feature.\n\nExamples:\n\n```toml\n[tool.robotcode-analyze]\nsemantic-model = true\n```\n",
+          "title": "Semantic model",
+          "type": [
+            "boolean",
+            "null"
+          ]
         }
       },
       "title": "AnalyzeConfig",
@@ -162,6 +171,15 @@
             "null"
           ]
         },
+        "cache-namespaces": {
+          "default": null,
+          "description": "Enable or disable caching of fully analyzed namespace data to disk.\nCan speed up startup for large projects by skipping re-analysis of unchanged files.\nDefaults to enabled.\n\nExamples:\n\n```toml\n[tool.robotcode-analyze.cache]\ncache_namespaces = false\n```\n",
+          "title": "Cache namespaces",
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
         "extend-ignore-arguments-for-library": {
           "default": null,
           "description": "Extend the ignore arguments for library settings.",

etc/robot.toml.json

@@ -1284,6 +1284,17 @@
             "scope": "resource"
           }
         }
+      },
+      {
+        "id": "robotcode.experimental",
+        "properties": {
+          "robotcode.experimental.semanticModel": {
+            "type": "boolean",
+            "default": false,
+            "markdownDescription": "Enable the experimental Semantic Model for code analysis. When enabled, LSP features use the new SemanticAnalyzer instead of the legacy NamespaceAnalyzer. **This is experimental and may change without notice.**",
+            "scope": "resource"
+          }
+        }
       }
     ],
     "commands": [

package.json

@@ -347,6 +347,27 @@ class AnalyzeConfig(BaseOptions):
         description="Extend the global library search order setting."
     )
 
+    semantic_model: Optional[bool] = field(
+        description="""\
+            Enable the experimental Semantic Model for code analysis. When enabled, LSP features
+            use the new SemanticAnalyzer instead of the legacy NamespaceAnalyzer. This provides
+            richer analysis including static resolution of nested variables and improved semantic
+            highlighting.
+
+            **This is experimental and may change without notice.**
+
+            Can also be set via VS Code setting `robotcode.experimental.semanticModel`.
+            If set in both places, either `true` value enables the feature.
+
+            Examples:
+
+            ```toml
+            [tool.robotcode-analyze]
+            semantic-model = true
+            ```
+        """,
+    )
+
     load_library_timeout: Optional[int] = field(
         description="""\
             Specifies the timeout in seconds for loading (importing) libraries and variable files during
@@ -381,6 +402,7 @@ class AnalyzeConfig(BaseOptions):
     def to_workspace_analysis_config(self) -> WorkspaceAnalysisConfig:
         return WorkspaceAnalysisConfig(
             exclude_patterns=self.exclude_patterns or [],
+            semantic_model=self.semantic_model if self.semantic_model is not None else False,
             cache=(
                 WorkspaceCacheConfig(
                     # TODO savelocation

packages/analyze/src/robotcode/analyze/config.py

@@ -123,7 +123,7 @@ def _hover_default(self, nodes: List[ast.AST], document: TextDocument, position:
                 )
                 value = None
                 real_value = None
-                if found_range is not None:
+                if found_range is not None and (highlight_range is None or found_range.is_in_range(highlight_range)):
                     highlight_range = found_range
                     if variable.has_value or variable.resolvable:
                         if (

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

@@ -67,6 +67,8 @@
 )
 from robotcode.robot.diagnostics.model_helper import ModelHelper
 from robotcode.robot.diagnostics.namespace import Namespace
+from robotcode.robot.diagnostics.semantic_analyzer.enums import TokenKind
+from robotcode.robot.diagnostics.semantic_analyzer.model import SemanticModel
 from robotcode.robot.utils import RF_VERSION
 from robotcode.robot.utils.ast import (
     cached_isinstance,
@@ -1032,11 +1034,131 @@ class SemanticTokenGenerator:
     creating and managing its own token mapper and keyword analyzer.
     """
 
+    # Mapping from SemanticModel TokenKind to LSP semantic token types.
+    # Used by collect_tokens_from_model() for the new model-based path.
+    _TOKEN_KIND_TO_SEM_TOKEN: Dict[TokenKind, Tuple[AnyTokenType, Optional[Set[AnyTokenModifier]]]] = {
+        TokenKind.KEYWORD: (RobotSemTokenTypes.KEYWORD, None),
+        TokenKind.BDD_PREFIX: (RobotSemTokenTypes.BDD_PREFIX, None),
+        TokenKind.NAMESPACE: (RobotSemTokenTypes.NAMESPACE, None),
+        TokenKind.VARIABLE: (RobotSemTokenTypes.VARIABLE, None),
+        TokenKind.VARIABLE_NOT_FOUND: (RobotSemTokenTypes.VARIABLE, None),
+        TokenKind.VARIABLE_PREFIX: (RobotSemTokenTypes.VARIABLE_BEGIN, None),
+        TokenKind.VARIABLE_OPEN_BRACE: (RobotSemTokenTypes.VARIABLE_BEGIN, None),
+        TokenKind.VARIABLE_CLOSE_BRACE: (RobotSemTokenTypes.VARIABLE_END, None),
+        TokenKind.VARIABLE_BASE: (RobotSemTokenTypes.VARIABLE, None),
+        TokenKind.VARIABLE_EXTENDED: (RobotSemTokenTypes.VARIABLE, None),
+        TokenKind.VARIABLE_TYPE_SEPARATOR: (SemanticTokenTypes.OPERATOR, None),
+        TokenKind.VARIABLE_TYPE_HINT: (SemanticTokenTypes.TYPE, None),
+        TokenKind.VARIABLE_DEFAULT_SEPARATOR: (SemanticTokenTypes.OPERATOR, None),
+        TokenKind.VARIABLE_DEFAULT_VALUE: (RobotSemTokenTypes.ARGUMENT, None),
+        TokenKind.VARIABLE_PATTERN_SEPARATOR: (SemanticTokenTypes.OPERATOR, None),
+        TokenKind.VARIABLE_PATTERN: (RobotSemTokenTypes.ARGUMENT, None),
+        TokenKind.VARIABLE_ASSIGN_MARK: (RobotSemTokenTypes.VARIABLE, None),
+        TokenKind.VARIABLE_EXPRESSION_OPEN: (RobotSemTokenTypes.EXPRESSION_BEGIN, None),
+        TokenKind.VARIABLE_EXPRESSION_CLOSE: (RobotSemTokenTypes.EXPRESSION_END, None),
+        TokenKind.PYTHON_EXPRESSION: (RobotSemTokenTypes.VARIABLE_EXPRESSION, None),
+        TokenKind.PYTHON_VARIABLE_REF: (RobotSemTokenTypes.VARIABLE, None),
+        TokenKind.VARIABLE_INDEX: (RobotSemTokenTypes.VARIABLE, None),
+        TokenKind.VARIABLE_INDEX_OPEN: (RobotSemTokenTypes.VARIABLE_BEGIN, None),
+        TokenKind.VARIABLE_INDEX_CLOSE: (RobotSemTokenTypes.VARIABLE_END, None),
+        TokenKind.VARIABLE_INDEX_CONTENT: (RobotSemTokenTypes.VARIABLE, None),
+        TokenKind.TEXT_FRAGMENT: (RobotSemTokenTypes.ARGUMENT, None),
+        TokenKind.ARGUMENT: (RobotSemTokenTypes.ARGUMENT, None),
+        TokenKind.NAMED_ARGUMENT_NAME: (RobotSemTokenTypes.NAMED_ARGUMENT, None),
+        TokenKind.NAMED_ARGUMENT_VALUE: (RobotSemTokenTypes.ARGUMENT, None),
+        TokenKind.CONTROL_FLOW: (RobotSemTokenTypes.CONTROL_FLOW, None),
+        TokenKind.CONDITION: (RobotSemTokenTypes.ARGUMENT, None),
+        TokenKind.TEST_NAME: (RobotSemTokenTypes.TESTCASE_NAME, {SemanticTokenModifiers.DECLARATION}),
+        TokenKind.KEYWORD_NAME: (RobotSemTokenTypes.KEYWORD_NAME, {SemanticTokenModifiers.DECLARATION}),
+        TokenKind.VARIABLE_NAME: (RobotSemTokenTypes.VARIABLE, {SemanticTokenModifiers.DECLARATION}),
+        TokenKind.SETTING_NAME: (RobotSemTokenTypes.SETTING, None),
+        TokenKind.IMPORT_NAME: (RobotSemTokenTypes.SETTING_IMPORT, None),
+        TokenKind.HEADER: (RobotSemTokenTypes.HEADER, None),
+        TokenKind.SEPARATOR: (RobotSemTokenTypes.SEPARATOR, None),
+        TokenKind.CONTINUATION: (RobotSemTokenTypes.CONTINUATION, None),
+        TokenKind.COMMENT: (SemanticTokenTypes.COMMENT, None),
+        TokenKind.TAG: (RobotSemTokenTypes.ARGUMENT, None),
+        TokenKind.CONFIG: (RobotSemTokenTypes.CONFIG, None),
+        TokenKind.ERROR: (RobotSemTokenTypes.ERROR, None),
+    }
+
     def __init__(self) -> None:
         """Initialize the generator with its own dependencies."""
         self.token_mapper = SemanticTokenMapper()
         self.keyword_analyzer = KeywordTokenAnalyzer(self.token_mapper)
 
+    def collect_tokens_from_model(
+        self,
+        document: TextDocument,
+        semantic_model: SemanticModel,
+        range: Optional[Range],
+        token_types: Sequence[Enum],
+        token_modifiers: Sequence[Enum],
+    ) -> Union[SemanticTokens, SemanticTokensPartialResult, None]:
+        """Collect semantic tokens from the pre-built SemanticModel.
+
+        This is the Tier 1 model-based path, used when the semantic model
+        feature flag is enabled. It maps SemanticModel TokenKind values
+        to LSP semantic token types via _TOKEN_KIND_TO_SEM_TOKEN.
+        """
+        data: List[int] = []
+        last_line = 0
+        last_col = 0
+        lines = document.get_lines()
+
+        for stmt in semantic_model.statements:
+            check_current_task_canceled()
+
+            for token in stmt.tokens:
+                if token.length == 0:
+                    continue
+
+                # Range filtering
+                token_line_0 = token.line - 1
+                if range is not None:
+                    if token_line_0 < range.start.line:
+                        continue
+                    if token_line_0 > range.end.line:
+                        break
+
+                sem_info = self._TOKEN_KIND_TO_SEM_TOKEN.get(token.kind)
+                if sem_info is None:
+                    continue
+
+                sem_type, sem_mods = sem_info
+
+                # Convert to UTF-16 positions
+                token_range = range_to_utf16(
+                    lines,
+                    Range(
+                        start=Position(line=token_line_0, character=token.col_offset),
+                        end=Position(line=token_line_0, character=token.col_offset + token.length),
+                    ),
+                )
+
+                token_col_offset = token_range.start.character
+                token_length = token_range.end.character - token_range.start.character
+
+                current_line = token_line_0
+
+                data.append(current_line - last_line)
+
+                if last_line != current_line:
+                    last_col = token_col_offset
+                    data.append(last_col)
+                else:
+                    delta = token_col_offset - last_col
+                    data.append(delta)
+                    last_col += delta
+
+                last_line = current_line
+
+                data.append(token_length)
+                data.append(token_types.index(sem_type))
+                data.append(reduce(operator.or_, [2 ** token_modifiers.index(e) for e in sem_mods]) if sem_mods else 0)
+
+        return SemanticTokens(data=data)
+
     def _get_tokens_after(self, tokens: List[Token], target_token: Token) -> List[Token]:
         """Get all tokens after target token efficiently.
 
@@ -1640,6 +1762,16 @@ def _collect(
         model = self.parent.documents_cache.get_model(document)
         namespace = self.parent.documents_cache.get_namespace(document)
 
+        semantic_model = namespace.semantic_model
+        if semantic_model is not None:
+            return self.token_generator.collect_tokens_from_model(
+                document,
+                semantic_model,
+                range,
+                self.parent.semantic_tokens.token_types,
+                self.parent.semantic_tokens.token_modifiers,
+            )
+
         builtin_library_doc = next(
             (
                 library.library_doc

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

@@ -0,0 +1,26 @@
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Dict, List, Optional, Set
+
+from robotcode.core.lsp.types import Diagnostic, Location, Range
+
+from .entities import LibraryEntry, TestCaseDefinition, VariableDefinition
+from .library_doc import KeywordDoc
+from .scope_tree import ScopeTree
+
+if TYPE_CHECKING:
+    from .semantic_analyzer.model import SemanticModel
+
+
+@dataclass(slots=True, frozen=True)
+class AnalyzerResult:
+    diagnostics: List[Diagnostic]
+    keyword_references: Dict[KeywordDoc, Set[Location]]
+    variable_references: Dict[VariableDefinition, Set[Location]]
+    local_variable_assignments: Dict[VariableDefinition, Set[Range]]
+    namespace_references: Dict[LibraryEntry, Set[Location]]
+    test_case_definitions: List[TestCaseDefinition]
+    keyword_tag_references: Dict[str, Set[Location]]
+    testcase_tag_references: Dict[str, Set[Location]]
+    metadata_references: Dict[str, Set[Location]]
+    scope_tree: ScopeTree
+    semantic_model: Optional["SemanticModel"] = None

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

@@ -48,6 +48,7 @@
     AnalysisDiagnosticModifiersConfig,
     AnalysisRobotConfig,
     CacheConfig,
+    ExperimentalConfig,
     RobotConfig,
     WorkspaceAnalysisConfig,
 )
@@ -437,6 +438,7 @@ def __get_namespace_for_document_type(
             model = self.get_model(document)
 
         languages, workspace_languages = self.build_languages_from_model(document, model)
+        experimental_config = self.workspace.get_configuration(ExperimentalConfig, document.uri)
 
         builder = NamespaceBuilder(
             imports_manager,
@@ -447,6 +449,7 @@ def __get_namespace_for_document_type(
             languages,
             workspace_languages,
         )
+        builder.set_semantic_model_enabled(self.analysis_config.semantic_model or experimental_config.semantic_model)
 
         result = builder.build()
 

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

@@ -42,6 +42,9 @@ class Error:
     OVERRIDES_IMPORTED_VARIABLE = "OverridesImportedVariable"
     VARIABLE_ALREADY_DEFINED = "VariableAlreadyDefined"
     VARIABLE_OVERRIDDEN = "VariableOverridden"
+    VARIABLE_NAME_NOT_RESOLVABLE = "VariableNameNotResolvable"
+    VARIABLE_NAME_NOT_STATICALLY_RESOLVABLE = "VariableNameNotStaticallyResolvable"
+    VARIABLE_REFERENCE_NOT_STATICALLY_RESOLVABLE = "VariableReferenceNotStaticallyResolvable"
     MODEL_ERROR = "ModelError"
     TOKEN_ERROR = "TokenError"
     ASSIGN_MARK_ALLOWED_ONLY_ON_LAST_VAR = "AssignmentMarkAllowedOnlyOnLastVariable"