feat(robot): pre-resolve more semantic data so LSP features can read it once

Inlay Hints now read from the SemanticModel instead of doing a second
analysis pass. The model gains a real block hierarchy (FOR/WHILE/IF/TRY/
GROUP), pre-resolved init keyword docs on Library/Variables imports,
and consolidated header-token construction so future LSP feature
migrations stop re-walking the AST.

The old AST-walk path stays as fallback while
`robotcode.experimental.semanticModel` is off; both paths must produce
identical hints (covered by parametrized equivalence tests across all
supported RF versions).

Author: d-biehl

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

@@ -5,7 +5,7 @@
 
 from robotcode.core.concurrent import check_current_task_canceled
 from robotcode.core.language import language_id
-from robotcode.core.lsp.types import InlayHint, InlayHintKind, Range
+from robotcode.core.lsp.types import InlayHint, InlayHintKind, Position, Range
 from robotcode.core.text_document import TextDocument
 from robotcode.core.utils.logging import LoggingDescriptor
 from robotcode.robot.diagnostics.library_doc import (
@@ -14,6 +14,13 @@
     LibraryDoc,
 )
 from robotcode.robot.diagnostics.namespace import Namespace
+from robotcode.robot.diagnostics.semantic_analyzer.enums import ImportType, TokenKind
+from robotcode.robot.diagnostics.semantic_analyzer.model import SemanticModel
+from robotcode.robot.diagnostics.semantic_analyzer.nodes import (
+    ImportStatement,
+    KeywordCallStatement,
+    SemanticToken,
+)
 from robotcode.robot.utils.ast import (
     iter_nodes,
     range_from_node,
@@ -72,11 +79,30 @@ def collect(self, sender: Any, document: TextDocument, range: Range) -> Optional
         if config is None or (not config.parameter_names and not config.namespaces):
             return None
 
-        model = self.parent.documents_cache.get_model(document)
         namespace = self.parent.documents_cache.get_namespace(document)
 
-        result: List[InlayHint] = []
+        # Tier 2 model-based path — used when the experimental SemanticAnalyzer
+        # is enabled (semantic_model is populated). Falls back to the legacy
+        # ModelHelper-based path otherwise.
+        semantic_model = namespace.semantic_model
+        if semantic_model is not None:
+            return self._collect_from_model(document, range, namespace, semantic_model, config)
 
+        model = self.parent.documents_cache.get_model(document)
+        return self._collect_legacy(document, range, model, namespace, config)
+
+    def _collect_legacy(
+        self,
+        document: TextDocument,
+        range: Range,
+        model: ast.AST,
+        namespace: Namespace,
+        config: InlayHintsConfig,
+    ) -> List[InlayHint]:
+        """Legacy AST-walk based collection. Kept callable directly so that
+        tests can compare it against `_collect_from_model` for equivalence.
+        """
+        result: List[InlayHint] = []
         for node in iter_nodes(model):
             check_current_task_canceled()
 
@@ -92,6 +118,207 @@ def collect(self, sender: Any, document: TextDocument, range: Range) -> Optional
                 r = method(document, range, node, model, namespace, config)
                 if r is not None:
                     result.extend(r)
+        return result
+
+    # ------------------------------------------------------------------
+    # Tier 2 model-based collection
+    # ------------------------------------------------------------------
+
+    def _collect_from_model(
+        self,
+        document: TextDocument,
+        range: Range,
+        namespace: Namespace,
+        model: SemanticModel,
+        config: InlayHintsConfig,
+    ) -> List[InlayHint]:
+        """Iterate the SemanticModel statements and produce inlay hints
+        directly from the pre-resolved data (no second find_keyword pass,
+        no AST re-walk for imports).
+
+        Note: `RunKeywordCallStatement.inner_calls` are intentionally NOT
+        traversed here. The legacy AST-walk path also doesn't reach
+        Run-Keyword-If inner arguments (they live inside the parent's
+        argument tokens, not as standalone AST nodes), so doing so in the
+        model path would introduce a drift. If we want hints inside
+        `Run Keyword If    cond    Log    msg`, that's a future feature
+        and needs a separate equivalence story.
+        """
+        result: List[InlayHint] = []
+        for stmt in model.statements:
+            check_current_task_canceled()
+
+            # Range filter — `range` lines are 0-indexed, stmt.line_* are 1-indexed.
+            if stmt.line_end - 1 < range.start.line:
+                continue
+            if stmt.line_start - 1 > range.end.line:
+                break
+
+            if isinstance(stmt, KeywordCallStatement) and stmt.keyword_doc is not None:
+                hints = self._inlay_hints_for_keyword_call(stmt, namespace, config)
+                if hints:
+                    result.extend(hints)
+            elif (
+                config.parameter_names
+                and isinstance(stmt, ImportStatement)
+                and stmt.init_keyword_doc is not None
+                and stmt.import_type in (ImportType.LIBRARY, ImportType.VARIABLES)
+            ):
+                hints = self._inlay_hints_for_import(stmt, namespace, config)
+                if hints:
+                    result.extend(hints)
+
+        return result
+
+    def _inlay_hints_for_import(
+        self,
+        stmt: ImportStatement,
+        namespace: Namespace,
+        config: InlayHintsConfig,
+    ) -> Optional[List[InlayHint]]:
+        kw_doc = stmt.init_keyword_doc
+        if kw_doc is None:
+            return None
+
+        arg_tokens = [t for t in stmt.tokens if t.kind is TokenKind.ARGUMENT]
+        # Imports never get a namespace prefix hint — pass keyword_token=None
+        # so the namespace branch in the helper is skipped.
+        return self._get_inlay_hint_from_semantic_tokens(
+            keyword_token=None,
+            kw_doc=kw_doc,
+            arg_tokens=arg_tokens,
+            arg_values=[t.value for t in arg_tokens],
+            has_namespace_token=True,
+            namespace=namespace,
+            config=config,
+        )
+
+    def _inlay_hints_for_keyword_call(
+        self,
+        stmt: KeywordCallStatement,
+        namespace: Namespace,
+        config: InlayHintsConfig,
+    ) -> Optional[List[InlayHint]]:
+        kw_doc = stmt.keyword_doc
+        if kw_doc is None:
+            return None
+
+        # Top-level argument tokens carry positional/named args. NAMED_ARGUMENT_NAME
+        # tokens already imply the user wrote the name, so a parameter-name hint
+        # is redundant; we work from the parent ARGUMENT positions.
+        arg_tokens = [t for t in stmt.tokens if t.kind is TokenKind.ARGUMENT]
+
+        keyword_token = next((t for t in stmt.tokens if t.kind is TokenKind.KEYWORD), None)
+        has_namespace_token = any(t.kind is TokenKind.NAMESPACE for t in stmt.tokens)
+
+        return self._get_inlay_hint_from_semantic_tokens(
+            keyword_token=keyword_token,
+            kw_doc=kw_doc,
+            arg_tokens=arg_tokens,
+            arg_values=[t.value for t in arg_tokens],
+            has_namespace_token=has_namespace_token,
+            namespace=namespace,
+            config=config,
+        )
+
+    @staticmethod
+    def _get_inlay_hint_from_semantic_tokens(
+        keyword_token: Optional[SemanticToken],
+        kw_doc: KeywordDoc,
+        arg_tokens: List[SemanticToken],
+        arg_values: List[str],
+        has_namespace_token: bool,
+        namespace: Namespace,
+        config: InlayHintsConfig,
+    ) -> Optional[List[InlayHint]]:
+        """Model-based variant of `_get_inlay_hint`. Operates on SemanticTokens
+        rather than RF tokens. Pure function so it can be unit-tested without
+        the LSP protocol stack.
+        """
+        from robot.errors import DataError
+
+        result: List[InlayHint] = []
+
+        if config.parameter_names:
+            positional = None
+            if kw_doc.arguments_spec is not None:
+                try:
+                    positional, _ = kw_doc.arguments_spec.resolve(
+                        arg_values,
+                        None,
+                        resolve_variables_until=kw_doc.args_to_process,
+                        resolve_named=not kw_doc.is_any_run_keyword(),
+                        validate=False,
+                    )
+                except DataError:
+                    pass
+
+            if positional is not None:
+                kw_arguments = [
+                    a
+                    for a in kw_doc.arguments
+                    if a.kind
+                    not in [
+                        KeywordArgumentKind.NAMED_ONLY_MARKER,
+                        KeywordArgumentKind.POSITIONAL_ONLY_MARKER,
+                        KeywordArgumentKind.VAR_NAMED,
+                        KeywordArgumentKind.NAMED_ONLY,
+                    ]
+                ]
+                for i, _ in enumerate(positional):
+                    if i >= len(arg_tokens):
+                        break
+
+                    index = i if i < len(kw_arguments) else len(kw_arguments) - 1
+                    if index < 0:
+                        continue
+
+                    arg = kw_arguments[index]
+                    if i >= len(kw_arguments) and arg.kind != KeywordArgumentKind.VAR_POSITIONAL:
+                        break
+
+                    prefix = ""
+                    if arg.kind == KeywordArgumentKind.VAR_POSITIONAL:
+                        prefix = "*"
+                    elif arg.kind == KeywordArgumentKind.VAR_NAMED:
+                        prefix = "**"
+
+                    arg_token = arg_tokens[i]
+                    result.append(
+                        InlayHint(
+                            Position(line=arg_token.line - 1, character=arg_token.col_offset),
+                            f"{prefix}{arg.name}=",
+                            InlayHintKind.PARAMETER,
+                        )
+                    )
+
+        if keyword_token is not None and config.namespaces and not has_namespace_token:
+            # Only suggest a namespace prefix if the user didn't already write one.
+            if kw_doc.libtype == "LIBRARY":
+                lib = next(
+                    (
+                        lib
+                        for lib in namespace.libraries.values()
+                        if lib.name == kw_doc.libname and kw_doc in lib.library_doc.keywords.keywords
+                    ),
+                    None,
+                )
+            else:
+                lib = next(
+                    (
+                        lib
+                        for lib in namespace.resources.values()
+                        if lib.name == kw_doc.libname and kw_doc in lib.library_doc.keywords.keywords
+                    ),
+                    None,
+                )
+            if lib is not None:
+                result.append(
+                    InlayHint(
+                        Position(line=keyword_token.line - 1, character=keyword_token.col_offset),
+                        f"{lib.alias or lib.name}.",
+                    )
+                )
 
         return result
 

packages/robot/src/robotcode/robot/diagnostics/semantic_analyzer/__init__.py

@@ -5,7 +5,6 @@
     ImportType,
     NodeKind,
     OnLimitAction,
-    StatementKind,
     TokenKind,
     VarScope,
 )
@@ -14,9 +13,13 @@
     DefinitionBlock,
     DefinitionStatement,
     ExceptStatement,
+    ForBlock,
     ForStatement,
+    GroupBlock,
+    IfBlock,
     IfStatement,
     ImportStatement,
+    InlineIfStatement,
     KeywordCallStatement,
     ReturnStatement,
     RunKeywordCallStatement,
@@ -26,7 +29,9 @@
     SemanticToken,
     SettingStatement,
     TemplateDataStatement,
+    TryBlock,
     VarStatement,
+    WhileBlock,
     WhileStatement,
 )
 from .run_keyword import KeywordArgumentStrategy, get_keyword_argument_strategy
@@ -37,12 +42,16 @@
     "DefinitionBlock",
     "DefinitionStatement",
     "ExceptStatement",
+    "ForBlock",
     "ForFlavor",
     "ForStatement",
     "ForZipMode",
+    "GroupBlock",
+    "IfBlock",
     "IfStatement",
     "ImportStatement",
     "ImportType",
+    "InlineIfStatement",
     "KeywordArgumentStrategy",
     "KeywordCallStatement",
     "NodeKind",
@@ -56,11 +65,12 @@
     "SemanticStatement",
     "SemanticToken",
     "SettingStatement",
-    "StatementKind",
     "TemplateDataStatement",
     "TokenKind",
+    "TryBlock",
     "VarScope",
     "VarStatement",
+    "WhileBlock",
     "WhileStatement",
     "build_variable_sub_tokens",
     "get_keyword_argument_strategy",