perf(server): avoid unnecessary reparses and cache navigation definitions

Introduce several changes to reduce full-document reparses, lock contention and
redundant work when handling TclOO analysis and navigation:

- Add a cheap may_contain_classes pre-check and several cursor/receiver
  heuristics so completions, signature help and tcloo definitions skip the
  expensive marker reparse when the document cannot contain useful OO info.
- Allow passing an existing parsed tree into tcloo completion/signature/definition
  helpers; update callers to use the server's cached tree when available.
- Use a thread-local parser for request-time parse_source to avoid blocking the
  shared parser during background indexing, and add navigation_state() which
  returns cached definition identities (invalidated on index generation changes).
- Add a cheap name pre-filter (_may_resolve_to) for symbol matching and only
  run class highlighting when classes may exist.

These changes reduce contention and repeated parsing, improve responsiveness for
requests during background indexing, and cache navigation definition identities.
Tests were added/updated to assert caching and non-blocking behavior.

server/src/tools/inlay_hint.py

@@ -200,7 +200,7 @@ class InlayHintGenerator(Visitor):
 
         walk(tree)
         if self.parameter_names != "none":
-            for call in resolved_method_calls(self.source, self.external_classes):
+            for call in resolved_method_calls(self.source, self.external_classes, tree):
                 if not self._node_intersects_requested_range(call.command):
                     continue
                 parameters = method_parameters(call.parameters)

server/src/tools/navigation.py

@@ -506,6 +506,15 @@ def resolve_identity(
     return occurrence.identity
 
 
+def _may_resolve_to(occurrence: SymbolOccurrence, identity: SymbolIdentity) -> bool:
+    """Cheap name pre-filter; resolve_identity only returns one of these two."""
+    name = identity.name
+    fallback = occurrence.fallback_identity
+    return occurrence.identity.name == name or (
+        fallback is not None and fallback.name == name
+    )
+
+
 def symbol_at_position(
     index: FileSymbolIndex,
     position: lsp.Position,
@@ -530,6 +539,8 @@ def matching_occurrences(
     matches = []
     for index in indexes.values():
         for occurrence in index.occurrences:
+            if not _may_resolve_to(occurrence, identity):
+                continue
             if resolve_identity(occurrence, definitions) == identity:
                 matches.append((index, occurrence))
     return matches
@@ -543,6 +554,8 @@ def document_highlights(
     """Return all occurrences of one symbol in the active document."""
     highlights = []
     for occurrence in index.occurrences:
+        if not _may_resolve_to(occurrence, identity):
+            continue
         if resolve_identity(occurrence, definitions) != identity:
             continue
 

server/src/tools/tcloo_arguments.py

@@ -38,14 +38,14 @@ def method_parameters(parameters: str) -> list[MethodParameter]:
         return []
 
 
-def method_signature_help(source: str, position: lsp.Position, external_classes=None) -> lsp.SignatureHelp | None:
+def method_signature_help(source: str, position: lsp.Position, external_classes=None, tree=None) -> lsp.SignatureHelp | None:
     lines = source.split("\n")
     if position.line >= len(lines):
         return None
     # AST columns are codepoints; LSP columns are UTF-16 code units.
     prefix = lines[position.line].encode("utf-16-le")[:position.character * 2].decode("utf-16-le", errors="ignore")
     cursor = (position.line, len(prefix))
-    candidates = [call for call in resolved_method_calls(source, external_classes)
+    candidates = [call for call in resolved_method_calls(source, external_classes, tree)
                   if _contains_cursor(call.command, lines, cursor)]
     if not candidates:
         return None

server/src/tools/tcloo_completion.py

@@ -1,6 +1,6 @@
 """Static TclOO inference using local and indexed classes, without executing Tcl."""
 
-from collections.abc import Sequence
+from collections.abc import Callable, Sequence
 from dataclasses import dataclass, field
 import re
 
@@ -9,8 +9,30 @@ from tclint.lexer import TclSyntaxError
 from tclint.syntax_tree import BracedWord, Command, CommandSub, Script, VarSub
 
 from tools.parser import CustomParser
+from tools.signature_help import _active_argument, _contains_cursor
 from tools.tcl_command_completion import line_prefix_at_position
 
+_LEADING_RECEIVER = re.compile(r"\s*([A-Za-z_]\w*)\s+[\w:]*$")
+
+
+def may_contain_classes(source, external_classes=None) -> bool:
+    """Cheap pre-check: without any class, TclOO analysis yields nothing."""
+    return bool(external_classes) or "oo::class" in source
+
+
+def _may_be_receiver(name, source_lines, external_classes) -> bool:
+    """Whether a bare command word can name a class, an object or `my`.
+
+    Objects and local classes only come from `... create <name>`, so a word
+    never created anywhere cannot resolve and needs no full-document parse.
+    """
+    if name in {"my", "self", "next"}:
+        return True
+    if any(key.rsplit("::", 1)[-1] == name for key in external_classes or ()):
+        return True
+    created = re.compile(rf"\bcreate\s+[{{\"]?(?:[\w:]*::)?{re.escape(name)}\b")
+    return any("create" in line and created.search(line) for line in source_lines)
+
 
 @dataclass
 class ClassInfo:
@@ -74,10 +96,42 @@ def _qualified(name, namespace):
     return name if name.startswith("::") else f"{namespace}::{name}"
 
 
+def _cursor_may_be_method_word(tree, source_lines, position) -> bool:
+    """Whether the innermost command at the cursor is at its first argument.
+
+    The marker parse below can only succeed there, and the current document's
+    tree has the same structure apart from the marker.
+    """
+    line = source_lines[position.line]
+    # AST columns are codepoints; LSP columns are UTF-16 code units.
+    prefix = line.encode("utf-16-le")[:position.character * 2].decode("utf-16-le", errors="ignore")
+    cursor = (position.line, len(prefix))
+    lines = list(source_lines)
+    innermost = None
+
+    def walk(node):
+        nonlocal innermost
+        start, end = getattr(node, "pos", None), getattr(node, "end_pos", None)
+        if start is not None and end is not None and not start[0] - 1 <= cursor[0] <= end[0] - 1:
+            return
+        if isinstance(node, Command) and _contains_cursor(node, lines, cursor):
+            innermost = node
+        for child in node.children:
+            walk(child)
+
+    walk(tree)
+    return innermost is None or _active_argument(innermost, cursor) == 0
+
+
 def tcloo_completions(
     source_lines: Sequence[str], position: lsp.Position, external_classes=None,
+    current_tree: Callable[[], Script | None] | None = None,
 ) -> list[lsp.CompletionItem] | None:
-    """Return receiver-specific methods, or None outside a known OO context."""
+    """Return receiver-specific methods, or None outside a known OO context.
+
+    `current_tree` lazily returns the parsed, unmodified document (or None) so
+    cursors that cannot hold a method name skip the full marker reparse.
+    """
     prefix = line_prefix_at_position(source_lines, position)
     if prefix is None:
         return None
@@ -87,6 +141,19 @@ def tcloo_completions(
     word_start = len(prefix) - len(typed)
     if word_start == 0 or prefix[word_start - 1] not in " \t":
         return None
+    if not external_classes and not any("oo::class" in line for line in source_lines):
+        return None
+    continued = position.line > 0 and source_lines[position.line - 1].endswith("\\")
+    if not continued:
+        # The first word is the command itself, never a method name.
+        if not prefix[:word_start].strip():
+            return None
+        receiver = _LEADING_RECEIVER.match(prefix)
+        if receiver is not None and not _may_be_receiver(receiver.group(1), source_lines, external_classes):
+            return None
+    tree = current_tree() if current_tree is not None else None
+    if tree is not None and not _cursor_may_be_method_word(tree, source_lines, position):
+        return None
     marker = "__nx_tcloo_completion_cursor__"
     lines = list(source_lines)
     suffix = lines[position.line][len(prefix):]
@@ -258,6 +325,9 @@ def _analyze(tree, typed="", marker="", external_classes=None, uri=None, source=
     return classes, result, calls
 
 
-def resolved_method_calls(source, external_classes=None):
-    tree = parse_completion_source(source)
+def resolved_method_calls(source, external_classes=None, tree=None):
+    if not may_contain_classes(source, external_classes):
+        return []
+    if tree is None:
+        tree = parse_completion_source(source)
     return _analyze(tree, external_classes=external_classes)[2] if tree is not None else []

server/src/tools/tcloo_navigation.py

@@ -1,11 +1,14 @@
 """Definition targets for literal TclOO classes and resolved method calls."""
 
-from tools.tcloo_completion import _analyze, name_location, parse_completion_source
+from tools.tcloo_completion import _analyze, may_contain_classes, name_location, parse_completion_source
 from tools.tcloo_symbols import class_symbols
 
 
-def tcloo_definition(source, uri, position, external_classes=None):
-    tree = parse_completion_source(source)
+def tcloo_definition(source, uri, position, external_classes=None, tree=None):
+    if not may_contain_classes(source, external_classes):
+        return None
+    if tree is None:
+        tree = parse_completion_source(source)
     if tree is None:
         return None
     classes, _, calls = _analyze(tree, external_classes=external_classes, uri=uri, source=source)