feat(robot): enable bottom-up navigation in the SemanticModel

Every SemanticNode now carries a `parent` back-pointer, so LSP features
that start from a token or statement can walk up to the enclosing block,
section, or definition without re-querying the model by line. Comes with
helpers `enclosing_definition_block`, `enclosing_block_of_kind`,
`enclosing_section`, and `path_from_root` on `SemanticModel`.

Parent is typed as `SemanticNode` (not `SemanticBlock`) so it can also
point at a Statement — `RunKeywordCallStatement.inner_calls` are
parented to their outer Run-Keyword statement.

Author: d-biehl

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

@@ -427,13 +427,15 @@ def _add_statement(self, stmt: SemanticStatement) -> None:
 
         If the current block is a control-flow block (For/While/If/Try/Group)
         and has no header yet, and the statement is the matching header kind,
-        it is also wired up as `block.header`.
+        it is also wired up as `block.header`. The header's parent is the block
+        it heads — matching "the block owns its header".
         """
         self._semantic_model.statements.append(stmt)
         if not self._block_stack:
             return
         parent = self._block_stack[-1]
         parent.body.append(stmt)
+        stmt.parent = parent
         if (
             parent.header is None
             and stmt.kind in self._CONTROL_FLOW_HEADER_KINDS
@@ -444,7 +446,9 @@ def _add_statement(self, stmt: SemanticStatement) -> None:
     def _add_block(self, block: SemanticBlock) -> None:
         """Append a child block to the currently open parent block."""
         if self._block_stack:
-            self._block_stack[-1].body.append(block)
+            parent = self._block_stack[-1]
+            parent.body.append(block)
+            block.parent = parent
 
     def _push_block(self, block: SemanticBlock) -> None:
         self._block_stack.append(block)
@@ -2388,7 +2392,10 @@ def visit_TestCase(self, node: TestCase) -> None:  # noqa: N802
         # Header goes into the flat list; the block goes into the parent's body.
         # _add_statement would also add to the parent body — we don't want that
         # for the header (it lives inside the block as `header`, not as a sibling).
+        # Wire the header's parent to its block manually (the block-owns-its-header
+        # invariant) since we bypass _add_statement here.
         self._semantic_model.statements.append(defn)
+        defn.parent = defn_block
         self._add_block(defn_block)
         self._push_block(defn_block)
 
@@ -2483,7 +2490,10 @@ def visit_Keyword(self, node: Keyword) -> None:  # noqa: N802
         self._current_definition = defn
         self._current_definition_block = defn_block
 
+        # See visit_TestCase: header bypasses _add_statement so its parent is
+        # set explicitly to the owning DefinitionBlock.
         self._semantic_model.statements.append(defn)
+        defn.parent = defn_block
         self._add_block(defn_block)
         self._push_block(defn_block)
 

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

@@ -1,14 +1,27 @@
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Dict, List, Optional
+from typing import TYPE_CHECKING, Dict, FrozenSet, List, Optional
 
+from .enums import NodeKind
 from .nodes import (
     DefinitionBlock,
     DefinitionStatement,
     SemanticBlock,
+    SemanticNode,
     SemanticStatement,
     SemanticToken,
 )
 
+_SECTION_KINDS: FrozenSet[NodeKind] = frozenset(
+    {
+        NodeKind.SETTING_SECTION,
+        NodeKind.TESTCASE_SECTION,
+        NodeKind.KEYWORD_SECTION,
+        NodeKind.VARIABLE_SECTION,
+        NodeKind.COMMENT_SECTION,
+        NodeKind.INVALID_SECTION,
+    }
+)
+
 if TYPE_CHECKING:
     from ...utils.variables import VariableMatcher
     from ..entities import VariableDefinition
@@ -25,8 +38,11 @@ class SemanticModel:
       queries (outline, folding, breadcrumbs, scoping).
     - Flat list (`statements`) provides O(1) indexed access via `statement_at()`.
 
-    Optimized for queries: statement_at(), token_at(), find_variable(),
-    block_at(), enclosing_definition().
+    Optimized for queries:
+    - line/position based: statement_at(), token_at(), token_path_at(),
+      block_at(), enclosing_definition(), find_variable(), get_variables_at()
+    - node-based parent walks: enclosing_definition_block(),
+      enclosing_block_of_kind(), enclosing_section(), path_from_root()
 
     Replaces ScopeTree by integrating variable scope tracking:
     - File-level variables are in `file_scope` (VariableScope)
@@ -207,6 +223,66 @@ def block_at(self, line: int) -> Optional[SemanticBlock]:
         """Get the most specific (smallest range) block at a given line. O(1)."""
         return self._block_line_index.get(line)
 
+    # --- Node-based parent walks (use SemanticNode.parent back-pointer) ---
+
+    @staticmethod
+    def enclosing_block_of_kind(
+        node: SemanticNode,
+        kinds: FrozenSet[NodeKind],
+    ) -> Optional[SemanticBlock]:
+        """Walk parent chain from `node` upward and return the first
+        SemanticBlock whose kind is in `kinds`, or None if no match exists
+        before reaching the root.
+
+        Use this for control-flow / section lookups when you already have a
+        node (e.g. from `statement_at()`) and don't want to round-trip
+        through a line-based query.
+        """
+        current = node.parent
+        while current is not None:
+            if isinstance(current, SemanticBlock) and current.kind in kinds:
+                return current
+            current = current.parent
+        return None
+
+    @staticmethod
+    def enclosing_definition_block(node: SemanticNode) -> Optional[DefinitionBlock]:
+        """Walk parent chain and return the enclosing DefinitionBlock
+        (TestCase / Keyword), or None if `node` is at file level (e.g. an
+        import statement or a section-header).
+
+        Cheaper than `enclosing_definition(line)` when you already have the
+        node — no line-range scan, just parent pointer hops.
+        """
+        current = node.parent
+        while current is not None:
+            if isinstance(current, DefinitionBlock):
+                return current
+            current = current.parent
+        return None
+
+    @staticmethod
+    def enclosing_section(node: SemanticNode) -> Optional[SemanticBlock]:
+        """Walk parent chain and return the enclosing section block
+        (SETTING / TESTCASE / KEYWORD / VARIABLE / COMMENT / INVALID),
+        or None if `node` is outside any section (i.e. on the FILE root)."""
+        return SemanticModel.enclosing_block_of_kind(node, _SECTION_KINDS)
+
+    @staticmethod
+    def path_from_root(node: SemanticNode) -> List[SemanticNode]:
+        """Return the chain `[root, ..., node]` by walking parents.
+
+        Useful for breadcrumb UI, debugging, and tests asserting structural
+        placement without depending on line ranges.
+        """
+        chain: List[SemanticNode] = [node]
+        current = node.parent
+        while current is not None:
+            chain.append(current)
+            current = current.parent
+        chain.reverse()
+        return chain
+
     def find_variable(
         self,
         name: str,

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

@@ -42,13 +42,26 @@ class SemanticNode:
     """Common base for all nodes in the SemanticModel.
 
     Both statements (leaf nodes with tokens) and blocks (structural containers
-    with children) share kind and position fields.
+    with children) share kind, position fields, and a back-pointer to their
+    direct parent in the tree.
     """
 
     kind: NodeKind
     line_start: int = 0  # 1-indexed
     line_end: int = 0  # 1-indexed, inclusive
 
+    # Back-pointer to the directly enclosing node (block OR statement).
+    # `None` only for the root SemanticBlock(kind=FILE).
+    #
+    # Type is `SemanticNode` (not `SemanticBlock`) because some statements
+    # logically contain other statements without a wrapping block:
+    # `RunKeywordCallStatement.inner_calls` are `KeywordCallStatement`s whose
+    # parent is the outer Run-Keyword statement, not a block.
+    #
+    # Excluded from `repr` / compare to avoid infinite recursion through the
+    # cycle (block → body → child → parent → block → …).
+    parent: Optional["SemanticNode"] = field(default=None, repr=False, compare=False)
+
 
 @dataclass(slots=True)
 class SemanticStatement(SemanticNode):
@@ -119,6 +132,13 @@ class RunKeywordCallStatement(KeywordCallStatement):
 
     inner_calls: List["KeywordCallStatement"] = field(default_factory=list)
 
+    def __post_init__(self) -> None:
+        # Wire up parent back-pointers for inner calls. Their direct parent is
+        # this Run-Keyword statement, not the enclosing block — that's why
+        # SemanticNode.parent is typed as SemanticNode (not SemanticBlock).
+        for inner in self.inner_calls:
+            inner.parent = self
+
 
 # --- Control flow statements ---