Delete .gitea/workflows/recover.yaml

Adjust tests to match current completion item labels and clean up formatting:
- Expect "nocomplain" (no leading dash) for the unset option case instead of {"-nocomplain", "--"}.
- Reflow several multi-line source literals into single-line/f-string forms.
- Normalize various assertions and generator expressions onto single lines.
- Reformat TextDocumentItem construction for readability.

These changes are limited to test code and reflect the updated shape/labels of completion items and stylistic cleanup; no production logic is modified.

CHANGELOG.md

@@ -1,56 +1,313 @@
+# Changelog
+
+All notable changes to NX Postprocessor Support are listed here, newest release first.
+Versions correspond to the Git tags of this repository.
+
 ## Unreleased
 
-- Reparse only the top-level TCL commands touched by an edit instead of the whole file
-- Cache the workspace index in the extension storage so restarts skip reparsing unchanged files; the cache is discarded automatically when the server or bundled tclint changes
+### Added
+
+- Go to Definition from block template and address arguments in Tcl (`MOM_do_template`, `MOM_force`, `MOM_suppress`, `MOM_ask_address_value`, ...) to the `BLOCK_TEMPLATE`/`ADDRESS` declaration in the PSC `.def` files
+- Hover over block templates shows the template body; hover over addresses shows format, leader, trailer, min/max, and modality
+- Find References and Rename for block templates and addresses across Tcl and `.def` files, including addresses used inside block templates
+- Go to Definition, hover, references, and rename also work inside `.def` files
+
+### Documentation
+
+- Document DEF block templates, addresses, `BLOCK_LIST`/`ADDR_LIST`, and the formatting changes in the README
+
+## [2026.9.700] - 2026-09-24
+
+### Added
+
+- `BLOCK_LIST` and `ADDR_LIST` completion keywords that list all loaded block templates or addresses; the keyword is replaced by the selected quoted name
+
+### Changed
+
+- Format comments with a space after `#` (`#Comment` becomes `# Comment`); `##` separators, `#!`, and comments that already start with whitespace stay unchanged
+
+## [2026.9.600] - 2026-09-24
+
+### Added
+
+- Read `BLOCK_TEMPLATE` and `ADDRESS` names from the `.def` files listed under `<DefinedEvents>` in PSC layers; changes to PSC and DEF files are picked up automatically
+- Suggest block templates for `MOM_do_template` and addresses for `MOM_ask_address_value`, `MOM_force`, and `MOM_suppress`, each followed by variables
+- Suggest `Always`, `Once`, and `Off` for the first argument of `MOM_force` and `MOM_suppress`
+- Insert block templates, addresses, and modes in quotes without doubling typed or auto-closed quotes; insert variables with a leading `$`
+- Persistent workspace index in the extension storage, so restarts skip reparsing unchanged files; the cache is discarded automatically when the server or bundled tclint changes
+
+### Changed
+
+- Reparse only the top-level Tcl commands touched by an edit instead of the whole file
 - Speed up TclOO completion, signature help, inlay hints, and Go to Definition by reusing the cached syntax tree and skipping files without classes
 - Speed up references, document highlights, and call hierarchy with cached definition lookups
 - Keep background indexing from blocking requests that need a fresh syntax tree
-- Add Go to Definition for TclOO classes, constructors, and resolved methods, including PSC library definitions
-- Index PSC layer scripts (including external paths and legacy Windows encoding) and share TclOO class metadata across files for completion, signatures, inlay hints, and highlighting
-- Add document-local TclOO method completion for `new`/`create` instances, `my`, and statically inferred return chains
+
+### Fixed
+
+- Format and lint `uplevel` bodies as Tcl scripts instead of leaving them untouched
+- Stop the Python debug bootstrap with a clear error instead of hanging when no debugpy listener or only a stale one is available
+
+## [2026.9.501] - 2026-09-21
+
+### Fixed
+
+- Highlight braced stored-procedure names in `lappend` arguments
+
+## [2026.9.500] - 2026-09-21
+
+### Added
+
+- Index Tcl scripts referenced by PSC layers, including external folders, environment-variable folders, and legacy Windows encoding
+- Share TclOO class metadata across files for completion, signature help, inlay hints, and highlighting
+- Go to Definition for TclOO classes, constructors, and resolved methods, including PSC library definitions
+- CDL event handler snippets declare an extra `<var>_defined` global for parameters marked `TOGGLE Off`
+- Allow `INVALID` in the CDL `CATEGORY` grammar
+
+## [2026.9.400] - 2026-09-11
+
+### Added
+
+- Document-local TclOO method completion for `new`/`create` instances, `my`, and statically inferred return chains
+- Signature help and parameter inlay hints for resolved TclOO methods and constructors, including optional and variadic arguments
 - Suggest TclOO class names as classes and semantically highlight their declarations and calls
-- Show signature help and parameter inlay hints for resolved TclOO methods and constructors, including optional and variadic arguments
-- Add incoming and outgoing call hierarchy for custom TCL procedures and MOM event handlers
-- Add document highlights for procedure and variable occurrences
-- Make completion context-aware and prioritize local, current-file, workspace, and built-in symbols
-- Add command-aware completion for Tcl subcommands, fixed arguments, and valid options
-- Add semantic argument completion for variables, procedures, namespaces, and local file paths
-- Add placeholder-based snippets for common Tcl structures and `dict for`
-- Integrate the NX Tcl Remote Debugger directly into NX Postprocessor Support
-- Add `nx-tcl` attach configurations and breakpoint support for TCL and DEF files
-- Support breakpoints, stepping, stack frames, variables, watches, evaluation, logpoints, hit conditions, and Tcl error stops
-- Add generation-safe stack and variable references so delayed VS Code requests cannot address stale NX frames
-- Add command-buffer breakpoint handling for `LIB_GE_command_buffer_edit_*` source bodies
-- Extend the README with launch configuration, path mapping, and debugger usage
-- Prevent truncated TCL inlay hints and add configurable parameter hint modes
-- Add inlay hints for built-in NX procedures, variadic arguments, and visible ranges
-- Add inlay hint documentation and navigation to custom procedure definitions
-- Add signature help for custom TCL procedures and built-in NX/MOM procedures
-- Clean stale TCL indexes on close, delete, and rename operations
-- Make background parsing and index updates thread-safe
-- Improve TCL response times with debounced edits and cached semantic, inlay, hover, completion, and variable indexes
-- Debounce CDL/DEF diagnostics and remove per-line diagnostic logging
+- Keep completion working while the file has syntax errors
 
-## [0.0.1]
+## [2026.9.300] - 2026-09-10
 
-- Initial release
+### Added
 
-## [0.0.2]
+- Array key completion, including keys built with substitutions
+- Generated CDL event handler snippets declare `args`
 
-- Add Autocomp for TYPE
+## [2026.9.220] - 2026-09-08
 
-## [0.1.0]
+### Fixed
 
-- Add Hover Feature
+- Completion inside unfinished braced arguments now recognizes nested commands
 
-## [0.2.0]
+## [2026.9.210] - 2026-09-04
 
-- Add DEF File Support
+### Added
 
-## [2026.6.100]
+- Highlight escaped quoted strings and embedded variables in DEF files
 
-- Fix several bugs
+## [2026.9.200] - 2026-09-03
 
-## [2026.6.200]
+### Added
 
-- Fix foramtting bug
+- Command-aware completion for Tcl subcommands, fixed argument values, and options such as `string compare -nocase`
+- Semantic argument completion for variables, procedures, namespaces, and local file paths
+- Placeholder-based snippets for `if`, `foreach`, `proc`, `switch`, `try`, and `dict for`
+
+## [2026.9.100] - 2026-09-03
+
+### Added
+
+- Incoming and outgoing call hierarchy for custom Tcl procedures and MOM event handlers
+- Document highlights for procedure and variable occurrences
+- Context-aware completion that ranks local, current-file, workspace, and built-in symbols in that order
+
+### Changed
+
+- Update lsprotocol to 2025.0.0
+
+## [2026.8.300] - 2026-08-28
+
+### Added
+
+- Integrate the NX Tcl Remote Debugger; the separate `local-nx.nx-tcl-debug` extension is no longer needed
+- `nx-tcl` attach configurations and breakpoints in Tcl and DEF files
+- Stepping, call stack, scopes, variables, watches, evaluation, logpoints, hit conditions, and Tcl error stops
+- Breakpoints in `LIB_GE_command_buffer_edit_*` bodies, mapped back to their source and owning procedure
+
+## [2026.8.200] - 2026-08-19
+
+### Added
+
+- Configurable parameter-name inlay hints (`inlayHints.parameterNames`, `inlayHints.suppressWhenArgumentMatchesName`) for custom and built-in NX procedures, including variadic arguments
+- Unlimited inlay hint length for Tcl files, so later parameter names are not truncated
+
+### Changed
+
+- Cache semantic tokens, inlay hints, hover, completion, and variable indexes and debounce edits and diagnostics for faster responses
+
+## [2026.8.100] - 2026-08-19
+
+### Added
+
+- Workspace symbol index with Go to Definition, references, and rename
+- Signature help for custom Tcl procedures and built-in NX/MOM procedures
+- CDL event handler snippets and hover with generated handler and `mom_` parameter hints
+- Keep indexes in sync when Tcl files are changed, deleted, or renamed on disk
+
+## [2026.6.201] - 2026-06-22
+
+### Fixed
+
+- Preserve whitespace inside single-line braced expressions when formatting
+
+## [2026.6.200] - 2026-06-22
+
+### Fixed
+
+- Tcl formatting bug caused by the formatter options
+
+## [2026.6.100] - 2026-06-18
+
+### Changed
+
+- Folding ranges for Tcl are computed by the language server, avoiding duplicate regions
+- Language server restarts are serialized so only one server runs at a time
+- Pin the Python dependencies of the server and update the bundled libraries
+
+### Fixed
+
+- Several stability fixes
+
+## [2025.9.200] - 2025-09-01
+
+### Changed
+
+- Install server dependencies with uv instead of pip
+- Relicense to AGPL-3.0-or-later
+
+## [2025.9.101] - 2025-08-16
+
+### Added
+
+- Signature help
+- Variable checks and additional semantic tokens
+
+### Fixed
+
+- `incr` on variables that already exist and `foreach` loop variables
+
+## [2025.8.400] - 2025-08-15
+
+### Added
+
+- Outline for DEF and CDL files
+
+### Fixed
+
+- Duplicate `MOM_add_to_block_buffer` entry renamed to `MOM_add_to_line_buffer`
+
+## [2025.8.300] - 2025-08-12
+
+### Added
+
+- Go to Definition and document outline for Tcl
+- Variable index with positions
+- Procedure documentation in hover
+
+### Fixed
+
+- Formatter deleting line continuations (`\`)
+- Wrong semantic highlighting in several cases
+
+## [2025.8.202] - 2025-08-12
+
+### Fixed
+
+- Formatter deleting line continuations (`\`)
+
+## [2025.8.201] - 2025-08-11
+
+### Fixed
+
+- Highlighting errors
+
+## [2025.8.200] - 2025-08-09
+
+- Version change only
+
+## [2025.8.2] - 2025-08-09
+
+- Version change only
+
+## [2025.08.1] - 2025-08-09
+
+### Added
+
+- Load procedures from all workspace files and PSC-referenced scripts for completion
+- Extension icon
+
+## [0.4.14] - 2025-08-04
+
+### Added
+
+- `LIB_GE_command_buffer_edit_*` support in the parser
+
+### Fixed
+
+- Namespace calls in POCO code
+- Semantic highlighting of variables in arrays
+
+## [0.4.12] - 2025-08-03
+
+### Added
+
+- More semantic tokens and completion items
+
+## [0.4.10] - 2025-07-28
+
+### Added
+
+- Linter based on tclint
+
+### Changed
+
+- Use tclint as parser and formatter
+
+## [0.4.9] - 2025-07-22
+
+### Added
+
+- More completion items
+
+## [0.4.8] - 2025-07-21
+
+### Added
+
+- More NX functions and hover documentation
+
+## [0.4.7] - 2025-07-21
+
+### Added
+
+- Formatter settings
+
+### Fixed
+
+- Formatter fixes
+
+## [0.4.6] - 2025-07-21
+
+### Fixed
+
+- `@` in buffers when formatting
+
+## [0.4.5] - 2025-07-21
+
+### Fixed
+
+- Formatting of buffers
+
+## [0.4.4] - 2025-07-21
+
+### Fixed
+
+- Formatter fixes
+
+## [0.4.3] - 2025-07-21
+
+### Fixed
+
+- Formatting fixes
+
+## [0.4.2] - 2025-07-20
+
+### Added
+
+- Initial release with syntax highlighting, formatting, auto-completion (including `TYPE`), hover, and DEF file support

README.md

@@ -14,6 +14,7 @@ A comprehensive VS Code extension providing language support and remote debuggin
 - **Document Highlights** - Highlights all reads, writes, and calls of the symbol under the cursor
 - **Context-aware Completion** - Prioritizes local symbols and suggests variables, procedures, namespaces, paths, Tcl subcommands, valid argument values, and options based on cursor context
 - **PSC and TclOO Classes** - Indexes Tcl scripts referenced by PSC layers, including external folders. Classes from indexed files provide method completion, signature help, parameter hints, and class highlighting in other files. PSC script names may omit `.tcl`; relative folders resolve from the PSC directory, and environment-variable folders are supported. Missing scripts are reported in the output channel; encrypted libraries cannot supply static class metadata.
+- **DEF Block Templates and Addresses** - Reads the `.def` files listed under `<DefinedEvents>` in PSC layers and suggests their `BLOCK_TEMPLATE` and `ADDRESS` names, see [DEF block templates and addresses](#def-block-templates-and-addresses)
 - **Tcl Snippets** - Inserts placeholder-based structures for `if`, `foreach`, `proc`, `switch`, `try`, and `dict for`
 - **NX Tcl Remote Debugger** - Breakpoints, stepping, call stack, scopes, variables, watches, evaluation, logpoints, hit conditions, and Tcl error stops directly in a running NX Post process
 
@@ -48,6 +49,52 @@ TCL files default to unlimited inlay hint length so that VS Code does not
 truncate later parameter names on a line. An explicit user setting for
 `editor.inlayHints.maximumLength` still takes precedence.
 
+## DEF Block Templates and Addresses
+
+The language server resolves the `.def` files of every PSC layer's `<DefinedEvents>` section the
+same way as layer scripts (relative to the PSC, `SubFolder`, environment variables, missing `.def`
+extension) and collects all `BLOCK_TEMPLATE` and `ADDRESS` declarations. Changes to PSC or DEF files
+are picked up automatically.
+
+| Command | Suggestions |
+|---|---|
+| `MOM_do_template` | Block templates, then variables |
+| `MOM_ask_address_value` | Addresses, then variables |
+| `MOM_force`, `MOM_suppress` | 1st argument: `Always`, `Once`, `Off`, then variables; further arguments: addresses, then variables |
+
+Block templates, addresses, and `Always|Once|Off` are inserted in quotes (`"steady_rest"`); a quote
+that is already typed or auto-closed is replaced instead of doubled. Variables are inserted with a
+leading `$`. Typing `$` yourself still shows variables only.
+
+Two keywords list all loaded names anywhere in a Tcl file:
+
+- `BLOCK_LIST` - shows all block templates
+- `ADDR_LIST` - shows all addresses
+
+Select the keyword from the completion list (or type it completely) to open the list; text typed
+directly after the keyword, such as `ADDR_LISTSP`, narrows it. The keyword is replaced by the
+selected quoted name.
+
+### Navigation between Tcl and DEF files
+
+Block template and address names are linked to their declarations in the PSC `.def` files:
+
+- **Go to Definition** (F12) on `MOM_do_template "steady_rest"` or `MOM_force Once X` jumps to
+  `BLOCK_TEMPLATE steady_rest` or `ADDRESS X`. Inside a `.def` file, an address used in a block
+  template (`X[$mom_pos(0)]`) jumps to its `ADDRESS` declaration.
+- **Hover** shows the body of a block template, or the format (resolved to its `FORMAT`
+  definition), leader, trailer, min/max, and modality (`FORCE`) of an address.
+- **Find All References** (Shift+F12) lists the declaration, all Tcl calls, and all block templates
+  that use an address.
+- **Rename** (F2) changes the declaration and all usages in Tcl and `.def` files together. Only
+  names declared in a loaded `.def` file can be renamed.
+
+Recognized Tcl commands: `MOM_do_template`, `MOM_add_to_block_buffer`, `MOM_polar_motion`,
+`MOM_force_block`, `MOM_ask_address_value`, `MOM_add_to_address_buffer`, `MOM_enable_address`,
+`MOM_disable_address`, `MOM_force`, `MOM_suppress`, `MOM_incremental`, and
+`MOM_ask_definition_element`/`MOM_has_definition_element` with `ADDRESS` or `BLOCK`. Names built
+from variables (`MOM_do_template $name`) cannot be resolved statically.
+
 ## NX Tcl Remote Debugger
 
 ### Add a VS Code attach configuration
@@ -98,13 +145,15 @@ Simply open any supported file type and enjoy:
 - Syntax highlighting
 - Error detection and linting
 - Code completion
-- Code formatting (Format Document command)
+- Code formatting (Format Document command), including `uplevel` bodies and a space after `#` in comments
 - Hover information
 - Signature help while entering procedure arguments
 - Incoming and outgoing call hierarchy for custom procedures and MOM event handlers
 - Document-wide highlights for procedure and variable occurrences
 - Context-aware completion with local symbols ranked before workspace and built-in symbols, plus semantic arguments, local paths, Tcl subcommands, and options such as `string compare -nocase`
 - Placeholder-based snippets for common Tcl control structures and procedures
+- Block template and address suggestions from PSC DEF files, including `BLOCK_LIST` and `ADDR_LIST`
+- Go to Definition, hover, references, and rename for block templates and addresses across Tcl and DEF files
 - Remote NX Tcl debugging with breakpoints and full stepping
 
 ## Contributing

client/src/common/defProviders.ts

@@ -0,0 +1,81 @@
+import * as vscode from "vscode"
+import { LanguageClient, Range, State } from "vscode-languageclient/node"
+
+// .def files are not synchronized with the language server, so each request
+// carries the current text of the document.
+const DEF_SELECTOR: vscode.DocumentSelector = { scheme: "file", language: "def" }
+
+function params(document: vscode.TextDocument, position: vscode.Position, extra: object = {}) {
+    return {
+        textDocument: { uri: document.uri.toString() },
+        position: { line: position.line, character: position.character },
+        text: document.getText(),
+        ...extra
+    }
+}
+
+export function registerDefProviders(getClient: () => LanguageClient | undefined): vscode.Disposable[] {
+    const request = async <T>(
+        method: string,
+        document: vscode.TextDocument,
+        position: vscode.Position,
+        token: vscode.CancellationToken,
+        extra: object = {}
+    ): Promise<{ client: LanguageClient; result: T } | undefined> => {
+        const client = getClient()
+        if (!client || client.state !== State.Running) {
+            return undefined
+        }
+        const result = await client.sendRequest<T>(method, params(document, position, extra), token)
+        return result ? { client, result } : undefined
+    }
+
+    return [
+        vscode.languages.registerDefinitionProvider(DEF_SELECTOR, {
+            async provideDefinition(document, position, token) {
+                const response = await request<any>("nxPostSupport/def/definition", document, position, token)
+                return response && response.client.protocol2CodeConverter.asDefinitionResult(response.result, token)
+            }
+        }),
+        vscode.languages.registerHoverProvider(DEF_SELECTOR, {
+            async provideHover(document, position, token) {
+                const response = await request<any>("nxPostSupport/def/hover", document, position, token)
+                return response && response.client.protocol2CodeConverter.asHover(response.result)
+            }
+        }),
+        vscode.languages.registerReferenceProvider(DEF_SELECTOR, {
+            async provideReferences(document, position, context, token) {
+                const response = await request<any>("nxPostSupport/def/references", document, position, token, {
+                    includeDeclaration: context.includeDeclaration
+                })
+                return response && response.client.protocol2CodeConverter.asReferences(response.result, token)
+            }
+        }),
+        vscode.languages.registerRenameProvider(DEF_SELECTOR, {
+            async prepareRename(document, position, token) {
+                const response = await request<{ range: Range; placeholder: string }>(
+                    "nxPostSupport/def/prepareRename",
+                    document,
+                    position,
+                    token
+                )
+                if (!response) {
+                    throw new Error("Only declared block templates and addresses can be renamed.")
+                }
+                return {
+                    range: response.client.protocol2CodeConverter.asRange(response.result.range),
+                    placeholder: response.result.placeholder
+                }
+            },
+            async provideRenameEdits(document, position, newName, token) {
+                const response = await request<any>("nxPostSupport/def/rename", document, position, token, {
+                    newName
+                })
+                if (!response) {
+                    throw new Error(`"${newName}" is not a valid block template or address name.`)
+                }
+                return response.client.protocol2CodeConverter.asWorkspaceEdit(response.result, token)
+            }
+        })
+    ]
+}

client/src/extension.ts

@@ -16,6 +16,7 @@ import {
     defDocumentSymbolProvider,
     definitionCdlEventHandler
 } from "./common/handlers"
+import { registerDefProviders } from "./common/defProviders"
 import { registerLogger, traceError, traceLog, traceVerbose } from "./common/log/logging"
 import {
     checkVersion,
@@ -234,6 +235,7 @@ export async function activate(context: vscode.ExtensionContext) {
     )
 
     context.subscriptions.push(formatDefProvider)
+    context.subscriptions.push(...registerDefProviders(() => client))
 
     const cdlSymbolProvider = vscode.languages.registerDocumentSymbolProvider(
         { scheme: "file", language: "cdl" },

package.json

@@ -2,7 +2,7 @@
   "name": "nx-post-support",
   "displayName": "NX Postprocessor Support",
   "description": "VS Code extension for NX CAM postprocessor development with language support and remote Tcl debugging for CDL, TCL, and DEF files",
-  "version": "2026.9.600",
+  "version": "2026.9.800",
   "publisher": "Christoph",
   "icon": "images/nx-1.png",
   "activationEvents": [

server/src/lsp_server.py

@@ -52,6 +52,15 @@ from tools.completion_items import (
     completion_context,
     ranked_completion_items,
 )
+from tools.def_navigation import (
+    all_def_target_locations,
+    def_declarations,
+    def_definition_locations,
+    def_hover_markdown,
+    def_rename_edits,
+    def_symbol_at,
+)
+from tools.def_symbols import parse_def_document
 from tools.folding_ranges import build_folding_ranges
 from tools.index_cache import IndexCache
 from tools.inlay_hint import (
@@ -59,6 +68,7 @@ from tools.inlay_hint import (
     build_builtin_inlay_signatures,
 )
 from tools.navigation import (
+    DEF_SYMBOL_KINDS,
     SymbolIdentity,
     call_hierarchy_identity,
     call_hierarchy_items,
@@ -295,6 +305,7 @@ SYMBOL_LIST_KEYWORDS = {
     "BLOCK_LIST": (lambda: LSP_SERVER.block_template_items(), "block templates"),
     "ADDR_LIST": (lambda: LSP_SERVER.address_items(), "addresses"),
 }
+DEF_NAME_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
 _WORD_BEFORE_CURSOR_RE = re.compile(r"(?<![$\w])[A-Za-z_]+$")
 
 
@@ -709,6 +720,10 @@ def hover(params: lsp.HoverParams) -> lsp.Hover:
     else:
         return None
 
+    def_hover = _tcl_def_hover(document_uri, pos, token)
+    if def_hover is not None:
+        return def_hover
+
     # 1) If token is a known MOM proc/variable, return built-in hover
     match = BUILTIN_HOVER_ITEMS.get(token)
     if match and match.get("kind") == "function":
@@ -748,6 +763,22 @@ def hover(params: lsp.HoverParams) -> lsp.Hover:
     return None
 
 
+def _def_target(identity: SymbolIdentity) -> tuple[str, str] | None:
+    return (identity.kind, identity.name) if identity.kind in DEF_SYMBOL_KINDS else None
+
+
+def _tcl_def_hover(uri: str, position: lsp.Position, token: str) -> lsp.Hover | None:
+    documents = LSP_SERVER.def_documents_snapshot()
+    if not any(token in document.names(kind) for document in documents.values() for kind in DEF_SYMBOL_KINDS):
+        return None
+    context = _navigation_context(uri, position)
+    target = context and _def_target(context[3])
+    markdown = target and def_hover_markdown(documents, target)
+    if not markdown:
+        return None
+    return lsp.Hover(lsp.MarkupContent(kind=lsp.MarkupKind.Markdown, value=markdown), range=context[2].range)
+
+
 @LSP_SERVER.feature(lsp.TEXT_DOCUMENT_DEFINITION)
 def goto_definition(params: lsp.DefinitionParams):
     """Resolve TclOO declarations, then indexed proc and variable definitions."""
@@ -770,6 +801,9 @@ def goto_definition(params: lsp.DefinitionParams):
         return None
 
     indexes, definitions, _, identity = context
+    target = _def_target(identity)
+    if target is not None:
+        return _sorted_locations(def_definition_locations(LSP_SERVER.def_documents_snapshot(), target)) or None
     locations = [lsp.Location(uri=index.uri, range=occurrence.range) for index, occurrence in matching_occurrences(identity, indexes, definitions) if occurrence.is_definition]
     return _sorted_locations(locations) or None
 
@@ -811,6 +845,11 @@ def references(params: lsp.ReferenceParams) -> list[lsp.Location]:
         return []
 
     indexes, definitions, _, identity = context
+    target = _def_target(identity)
+    if target is not None:
+        return all_def_target_locations(
+            LSP_SERVER.def_documents_snapshot(), indexes, target, params.context.include_declaration
+        )
     locations = [
         lsp.Location(uri=index.uri, range=occurrence.range)
         for index, occurrence in matching_occurrences(identity, indexes, definitions)
@@ -858,7 +897,11 @@ def prepare_rename(params: lsp.PrepareRenameParams):
         return None
 
     indexes, definitions, occurrence, identity = context
-    if not _is_renamable(identity, indexes, definitions):
+    target = _def_target(identity)
+    if target is not None:
+        if not def_declarations(LSP_SERVER.def_documents_snapshot(), target):
+            return None
+    elif not _is_renamable(identity, indexes, definitions):
         return None
     return lsp.PrepareRenamePlaceholder(range=occurrence.range, placeholder=occurrence.placeholder)
 
@@ -868,7 +911,7 @@ def prepare_rename(params: lsp.PrepareRenameParams):
     lsp.RenameOptions(prepare_provider=True),
 )
 def rename(params: lsp.RenameParams) -> lsp.WorkspaceEdit | None:
-    if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", params.new_name):
+    if not DEF_NAME_RE.fullmatch(params.new_name):
         return None
 
     context = _navigation_context(params.text_document.uri, params.position)
@@ -876,6 +919,9 @@ def rename(params: lsp.RenameParams) -> lsp.WorkspaceEdit | None:
         return None
 
     indexes, definitions, _, identity = context
+    target = _def_target(identity)
+    if target is not None:
+        return def_rename_edits(LSP_SERVER.def_documents_snapshot(), indexes, target, params.new_name)
     if not _is_renamable(identity, indexes, definitions):
         return None
 
@@ -905,6 +951,83 @@ def rename(params: lsp.RenameParams) -> lsp.WorkspaceEdit | None:
     return lsp.WorkspaceEdit(changes=changes)
 
 
+# .def files are not synchronized with the server; the client sends their
+# current text with each request.
+DEF_REQUEST_DEFINITION = "nxPostSupport/def/definition"
+DEF_REQUEST_HOVER = "nxPostSupport/def/hover"
+DEF_REQUEST_REFERENCES = "nxPostSupport/def/references"
+DEF_REQUEST_PREPARE_RENAME = "nxPostSupport/def/prepareRename"
+DEF_REQUEST_RENAME = "nxPostSupport/def/rename"
+
+
+def _def_request_context(params):
+    uri = params.textDocument.uri
+    position = lsp.Position(line=params.position.line, character=params.position.character)
+    path = uris.to_fs_path(uri)
+    documents = LSP_SERVER.def_documents_snapshot(path, params.text)
+    symbol = def_symbol_at(parse_def_document(params.text), position)
+    if symbol is None:
+        return None
+    target, range_, _ = symbol
+    current = next(key for key in documents if LSP_SERVER.paths_equal(key, path))
+    return documents, {current: uri}, target, range_
+
+
+@LSP_SERVER.feature(DEF_REQUEST_DEFINITION)
+def def_definition(params) -> list[lsp.Location] | None:
+    context = _def_request_context(params)
+    if context is None:
+        return None
+    documents, def_uris, target, _ = context
+    return _sorted_locations(def_definition_locations(documents, target, def_uris)) or None
+
+
+@LSP_SERVER.feature(DEF_REQUEST_HOVER)
+def def_hover(params) -> lsp.Hover | None:
+    context = _def_request_context(params)
+    if context is None:
+        return None
+    documents, _, target, range_ = context
+    markdown = def_hover_markdown(documents, target)
+    if markdown is None:
+        return None
+    return lsp.Hover(lsp.MarkupContent(kind=lsp.MarkupKind.Markdown, value=markdown), range=range_)
+
+
+@LSP_SERVER.feature(DEF_REQUEST_REFERENCES)
+def def_references(params) -> list[lsp.Location]:
+    context = _def_request_context(params)
+    if context is None:
+        return []
+    documents, def_uris, target, _ = context
+    include_declaration = bool(getattr(params, "includeDeclaration", True))
+    indexes, _ = LSP_SERVER.navigation_state()
+    return all_def_target_locations(documents, indexes, target, include_declaration, def_uris)
+
+
+@LSP_SERVER.feature(DEF_REQUEST_PREPARE_RENAME)
+def def_prepare_rename(params):
+    context = _def_request_context(params)
+    if context is None:
+        return None
+    documents, _, target, range_ = context
+    if not def_declarations(documents, target):
+        return None
+    return lsp.PrepareRenamePlaceholder(range=range_, placeholder=target[1])
+
+
+@LSP_SERVER.feature(DEF_REQUEST_RENAME)
+def def_rename(params) -> lsp.WorkspaceEdit | None:
+    if not DEF_NAME_RE.fullmatch(params.newName):
+        return None
+    context = _def_request_context(params)
+    if context is None:
+        return None
+    documents, def_uris, target, _ = context
+    indexes, _ = LSP_SERVER.navigation_state()
+    return def_rename_edits(documents, indexes, target, params.newName, def_uris)
+
+
 @LSP_SERVER.feature(lsp.WORKSPACE_SYMBOL)
 def workspace_symbol(params: lsp.WorkspaceSymbolParams):
     return workspace_symbols(LSP_SERVER.navigation_snapshot(), params.query)

server/src/lsp_tclserver.py

@@ -18,7 +18,7 @@ from tools import checks, incremental_parse, parser
 from tools.completion_items import CompletionCollector
 from tools.tcloo_symbols import class_completion_items
 from tools.tcloo_completion import indexed_classes
-from tools.def_symbols import DefSymbols, read_def_symbols
+from tools.def_symbols import ADDRESS, BLOCK_TEMPLATE, DefDocument, parse_def_document, read_def_source
 from tools.file_sourcing import get_all_psc_files, psc_defined_event_files, psc_script_files
 from tools.formatter import NxFormatter as Formatter
 from tools.index_cache import FileStat, IndexCache, file_stat
@@ -62,8 +62,8 @@ class TclLanguageServer(LanguageServer):
         self.psc_script_paths: list[str] = []
         self._psc_files: dict[str, list[pathlib.Path]] = {}
         self._psc_lock = threading.RLock()
-        # .def path -> BLOCK_TEMPLATE/ADDRESS names, in PSC DefinedEvents order.
-        self.def_symbols: dict[str, DefSymbols] = {}
+        # .def path -> parsed declarations, in PSC DefinedEvents order.
+        self.def_documents: dict[str, DefDocument] = {}
         self.navigation_indexes: dict[str, FileSymbolIndex] = {}
         self.variable_indexes: dict[
             str,
@@ -257,7 +257,7 @@ class TclLanguageServer(LanguageServer):
 
     def refresh_def_symbols(self, roots, report=LOGGER.warning):
         """Read the block templates and addresses of all .def files listed as PSC DefinedEvents."""
-        symbols: dict[str, DefSymbols] = {}
+        documents: dict[str, DefDocument] = {}
         for root in roots:
             for psc in get_all_psc_files(root):
                 try:
@@ -266,33 +266,40 @@ class TclLanguageServer(LanguageServer):
                     report(f"Could not read PSC {psc}: {error}")
                     continue
                 for def_file in def_files:
-                    if str(def_file) in symbols:
+                    if str(def_file) in documents:
                         continue
                     try:
-                        symbols[str(def_file)] = read_def_symbols(def_file)
+                        documents[str(def_file)] = parse_def_document(read_def_source(def_file))
                     except OSError as error:
                         report(f"Could not read DEF file {def_file}: {error}")
         with self._index_lock:
-            self.def_symbols = symbols
+            self.def_documents = documents
 
-    def _def_symbol_items(self, attribute: str, kind, description: str) -> list[lsp.CompletionItem]:
+    def def_documents_snapshot(self, current_path=None, current_source: str | None = None) -> dict[str, DefDocument]:
+        """Return the PSC .def documents; ``current_source`` replaces the file being edited."""
         with self._index_lock:
-            symbols = dict(self.def_symbols)
+            documents = dict(self.def_documents)
+        if current_path is not None and current_source is not None:
+            key = next((path for path in documents if self.paths_equal(path, current_path)), os.fspath(current_path))
+            documents[key] = parse_def_document(current_source)
+        return documents
+
+    def _def_symbol_items(self, kind: str, item_kind, description: str) -> list[lsp.CompletionItem]:
         return [
             lsp.CompletionItem(
                 label=name,
-                kind=kind,
+                kind=item_kind,
                 detail=f"{description} ({pathlib.Path(path).name})",
             )
-            for path, def_symbols in symbols.items()
-            for name in getattr(def_symbols, attribute)
+            for path, document in self.def_documents_snapshot().items()
+            for name in document.names(kind)
         ]
 
     def block_template_items(self) -> list[lsp.CompletionItem]:
-        return self._def_symbol_items("block_templates", lsp.CompletionItemKind.Struct, "Block template")
+        return self._def_symbol_items(BLOCK_TEMPLATE, lsp.CompletionItemKind.Struct, "Block template")
 
     def address_items(self) -> list[lsp.CompletionItem]:
-        return self._def_symbol_items("addresses", lsp.CompletionItemKind.Field, "Address")
+        return self._def_symbol_items(ADDRESS, lsp.CompletionItemKind.Field, "Address")
 
     def refresh_psc_scripts(self, roots, report=LOGGER.warning):
         """Index PSC dependencies through the same pipeline as workspace procs."""

server/src/tools/def_navigation.py

@@ -0,0 +1,191 @@
+"""Navigation between Tcl code and the block templates and addresses of .def files."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import lsprotocol.types as lsp
+
+from tools.def_symbols import ADDRESS, BLOCK_TEMPLATE, FORMAT, DefDeclaration, DefDocument
+from tools.navigation import FileSymbolIndex, SymbolOccurrence
+
+DefTarget = tuple[str, str]
+_KIND_LABELS = {BLOCK_TEMPLATE: "Block template", ADDRESS: "Address", FORMAT: "Format"}
+# Address properties in display order; others follow as declared.
+_ADDRESS_PROPERTIES = (
+    ("FORMAT", "Format"),
+    ("LEADER", "Leader"),
+    ("TRAILER", "Trailer"),
+    ("MIN", "Min"),
+    ("MAX", "Max"),
+    ("FORCE", "Modality"),
+    ("ZERO_FORMAT", "Zero format"),
+    ("INCREMENTAL", "Incremental"),
+    ("OMIT", "Omit"),
+)
+_MODALITY = {
+    "OFF": "modal, output only on change",
+    "ONCE": "output once, then modal",
+    "ALWAYS": "non-modal, always output",
+}
+
+
+def _range(line: int, start: int, end: int) -> lsp.Range:
+    return lsp.Range(
+        start=lsp.Position(line=line, character=start),
+        end=lsp.Position(line=line, character=end),
+    )
+
+
+def _contains(line: int, start: int, end: int, position: lsp.Position) -> bool:
+    return position.line == line and start <= position.character <= end
+
+
+def def_symbol_at(document: DefDocument, position: lsp.Position) -> tuple[DefTarget, lsp.Range, bool] | None:
+    """Return the block template or address at ``position`` of a .def document.
+
+    The flag tells whether the position is on a declaration.
+    """
+    for declaration in document.declarations:
+        if declaration.kind != FORMAT and _contains(declaration.line, declaration.start, declaration.end, position):
+            return (declaration.kind, declaration.name), _range(declaration.line, declaration.start, declaration.end), True
+    for reference in document.references:
+        if _contains(reference.line, reference.start, reference.end, position):
+            return (reference.kind, reference.name), _range(reference.line, reference.start, reference.end), False
+    return None
+
+
+def _uri(path: str, uris: dict[str, str]) -> str:
+    return uris.get(path) or Path(path).as_uri()
+
+
+def def_declarations(documents: dict[str, DefDocument], target: DefTarget) -> list[tuple[str, DefDeclaration]]:
+    kind, name = target
+    return [
+        (path, declaration)
+        for path, document in documents.items()
+        for declaration in document.declarations
+        if declaration.kind == kind and declaration.name == name
+    ]
+
+
+def def_definition_locations(
+    documents: dict[str, DefDocument], target: DefTarget, uris: dict[str, str] | None = None
+) -> list[lsp.Location]:
+    uris = uris or {}
+    return [
+        lsp.Location(uri=_uri(path, uris), range=_range(declaration.line, declaration.start, declaration.end))
+        for path, declaration in def_declarations(documents, target)
+    ]
+
+
+def def_reference_locations(
+    documents: dict[str, DefDocument],
+    target: DefTarget,
+    include_declaration: bool,
+    uris: dict[str, str] | None = None,
+) -> list[lsp.Location]:
+    """Return .def occurrences: declarations and addresses used in block templates."""
+    kind, name = target
+    uris = uris or {}
+    locations = def_definition_locations(documents, target, uris) if include_declaration else []
+    for path, document in documents.items():
+        for reference in document.references:
+            if reference.kind == kind and reference.name == name:
+                locations.append(
+                    lsp.Location(uri=_uri(path, uris), range=_range(reference.line, reference.start, reference.end))
+                )
+    return locations
+
+
+def tcl_def_occurrences(
+    indexes: dict[str, FileSymbolIndex], target: DefTarget
+) -> list[tuple[FileSymbolIndex, SymbolOccurrence]]:
+    kind, name = target
+    return [
+        (index, occurrence)
+        for index in indexes.values()
+        for occurrence in index.occurrences
+        if occurrence.identity.kind == kind and occurrence.identity.name == name
+    ]
+
+
+def all_def_target_locations(
+    documents: dict[str, DefDocument],
+    indexes: dict[str, FileSymbolIndex],
+    target: DefTarget,
+    include_declaration: bool,
+    uris: dict[str, str] | None = None,
+) -> list[lsp.Location]:
+    locations = def_reference_locations(documents, target, include_declaration, uris)
+    locations.extend(
+        lsp.Location(uri=index.uri, range=occurrence.range) for index, occurrence in tcl_def_occurrences(indexes, target)
+    )
+    unique = {}
+    for location in locations:
+        key = (location.uri, location.range.start.line, location.range.start.character)
+        unique.setdefault(key, location)
+    return sorted(unique.values(), key=lambda item: (item.uri, item.range.start.line, item.range.start.character))
+
+
+def def_rename_edits(
+    documents: dict[str, DefDocument],
+    indexes: dict[str, FileSymbolIndex],
+    target: DefTarget,
+    new_name: str,
+    uris: dict[str, str] | None = None,
+) -> lsp.WorkspaceEdit | None:
+    """Rename a block template or address in all .def and Tcl files, if it is declared."""
+    if not def_declarations(documents, target):
+        return None
+    changes: dict[str, list[lsp.TextEdit]] = {}
+    for location in all_def_target_locations(documents, indexes, target, True, uris):
+        changes.setdefault(location.uri, []).append(lsp.TextEdit(range=location.range, new_text=new_name))
+    for edits in changes.values():
+        edits.sort(key=lambda edit: (edit.range.start.line, edit.range.start.character), reverse=True)
+    return lsp.WorkspaceEdit(changes=changes)
+
+
+def _escape_cell(value: str) -> str:
+    return value.replace("|", "\\|") or " "
+
+
+def _address_table(declaration: DefDeclaration, formats: dict[str, DefDeclaration]) -> str:
+    properties = dict(declaration.properties)
+    rows = []
+    for key, label in _ADDRESS_PROPERTIES:
+        value = properties.pop(key, None)
+        if value is None:
+            continue
+        cell = f"`{value}`" if value else ""
+        if key == "FORMAT" and value in formats:
+            cell += f" → `{dict(formats[value].properties).get('FORMAT', '')}`"
+        if key == "FORCE":
+            cell += f" ({_MODALITY[value.upper()]})" if value.upper() in _MODALITY else ""
+        rows.append(f"| {label} | {_escape_cell(cell)} |")
+    rows.extend(f"| {key.title()} | {_escape_cell(f'`{value}`' if value else '')} |" for key, value in properties.items())
+    if not rows:
+        return "_No properties_"
+    return "\n".join(["| Property | Value |", "|---|---|", *rows])
+
+
+def def_hover_markdown(documents: dict[str, DefDocument], target: DefTarget) -> str | None:
+    declarations = def_declarations(documents, target)
+    if not declarations:
+        return None
+    formats = {
+        declaration.name: declaration
+        for document in documents.values()
+        for declaration in document.declarations
+        if declaration.kind == FORMAT
+    }
+    kind, name = target
+    sections = []
+    for path, declaration in declarations:
+        header = f"**{_KIND_LABELS[kind]}** `{name}` — {Path(path).name}:{declaration.line + 1}"
+        if kind == ADDRESS:
+            body = _address_table(declaration, formats)
+        else:
+            body = f"```def\n{declaration.text}\n```"
+        sections.append(f"{header}\n\n{body}")
+    return "\n\n---\n\n".join(sections)

server/src/tools/def_symbols.py

@@ -1,11 +1,53 @@
-"""Block templates and addresses declared in NX post definition (.def) files."""
+"""Block templates, addresses and formats declared in NX post definition (.def) files."""
 
 import re
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from pathlib import Path
 
-_BLOCK_TEMPLATE_RE = re.compile(r"^\s*BLOCK_TEMPLATE\s+([^\s{]+)", re.MULTILINE)
-_ADDRESS_RE = re.compile(r"^\s*ADDRESS\s+([^\s{]+)", re.MULTILINE)
+BLOCK_TEMPLATE = "block_template"
+ADDRESS = "address"
+FORMAT = "format"
+
+_KINDS = {"BLOCK_TEMPLATE": BLOCK_TEMPLATE, "ADDRESS": ADDRESS, "FORMAT": FORMAT}
+_HEADER_RE = re.compile(r"^\s*(BLOCK_TEMPLATE|ADDRESS|FORMAT)\s+([^\s{]+)")
+# A block template element is an address followed by its expression: X[$mom_pos(0)].
+_ELEMENT_RE = re.compile(r"^\s*([A-Za-z_]\w*)\[")
+_PROPERTY_RE = re.compile(r"^\s*([A-Za-z_]+)\s*(.*?)\s*$")
+
+
+@dataclass(frozen=True)
+class DefDeclaration:
+    kind: str
+    name: str
+    # 0-based line and UTF-16 columns of the name.
+    line: int
+    start: int
+    end: int
+    end_line: int
+    text: str
+    # ADDRESS: body properties such as ("LEADER", '"X"'); FORMAT: (("FORMAT", '"%d"'),).
+    properties: tuple[tuple[str, str], ...] = ()
+
+
+@dataclass(frozen=True)
+class DefReference:
+    """An address used as element of a block template."""
+
+    kind: str
+    name: str
+    line: int
+    start: int
+    end: int
+    container: str
+
+
+@dataclass(frozen=True)
+class DefDocument:
+    declarations: tuple[DefDeclaration, ...] = ()
+    references: tuple[DefReference, ...] = ()
+
+    def names(self, kind: str) -> tuple[str, ...]:
+        return tuple(dict.fromkeys(item.name for item in self.declarations if item.kind == kind))
 
 
 @dataclass(frozen=True)
@@ -14,23 +56,125 @@ class DefSymbols:
     addresses: tuple[str, ...] = ()
 
 
-def _names(pattern: re.Pattern, source: str) -> tuple[str, ...]:
-    return tuple(dict.fromkeys(pattern.findall(source)))
+def _utf16_length(text: str) -> int:
+    return len(text.encode("utf-16-le")) // 2
+
+
+def _is_comment(line: str) -> bool:
+    return line.lstrip().startswith("#")
+
+
+def _body(lines: list[str], header: int, rest: str) -> tuple[int, int, int] | None:
+    """Return (first body line, first body column, closing line) of a braced body.
+
+    The body starts after the first "{" on the header line or on a following
+    line and ends at the next line starting with "}".
+    """
+    if "{" in rest:
+        after = rest.split("{", 1)[1]
+        if "}" in after:
+            return None
+        start = header + 1
+    else:
+        start = header + 1
+        while start < len(lines) and (not lines[start].strip() or _is_comment(lines[start])):
+            start += 1
+        if start >= len(lines) or not lines[start].lstrip().startswith("{"):
+            return None
+        start += 1
+    end = start
+    while end < len(lines) and not lines[end].lstrip().startswith("}"):
+        end += 1
+    return start, 0, min(end, len(lines) - 1)
+
+
+def parse_def_document(source: str) -> DefDocument:
+    """Parse the block templates, addresses and formats of a .def source."""
+    lines = source.splitlines()
+    declarations: list[DefDeclaration] = []
+    references: list[DefReference] = []
+    index = 0
+    while index < len(lines):
+        line = lines[index]
+        match = None if _is_comment(line) else _HEADER_RE.match(line)
+        if match is None:
+            index += 1
+            continue
+
+        kind = _KINDS[match.group(1)]
+        name = match.group(2)
+        start = _utf16_length(line[: match.start(2)])
+        end = start + _utf16_length(name)
+        rest = line[match.end(2) :]
+
+        if kind == FORMAT:
+            declarations.append(
+                DefDeclaration(kind, name, index, start, end, index, line.strip(), (("FORMAT", rest.strip()),))
+            )
+            index += 1
+            continue
+
+        body = _body(lines, index, rest)
+        end_line = index if body is None else body[2]
+        properties: list[tuple[str, str]] = []
+        if body is not None:
+            for number in range(body[0], body[2]):
+                body_line = lines[number]
+                if _is_comment(body_line) or not body_line.strip():
+                    continue
+                if kind == BLOCK_TEMPLATE:
+                    element = _ELEMENT_RE.match(body_line)
+                    if element is not None:
+                        element_start = _utf16_length(body_line[: element.start(1)])
+                        references.append(
+                            DefReference(
+                                ADDRESS,
+                                element.group(1),
+                                number,
+                                element_start,
+                                element_start + _utf16_length(element.group(1)),
+                                name,
+                            )
+                        )
+                else:
+                    prop = _PROPERTY_RE.match(body_line)
+                    if prop is not None:
+                        properties.append((prop.group(1).upper(), prop.group(2)))
+
+        declarations.append(
+            DefDeclaration(
+                kind,
+                name,
+                index,
+                start,
+                end,
+                end_line,
+                "\n".join(lines[index : end_line + 1]),
+                tuple(properties),
+            )
+        )
+        index = end_line + 1
+
+    return DefDocument(tuple(declarations), tuple(references))
 
 
 def parse_def_symbols(source: str) -> DefSymbols:
     """Return the BLOCK_TEMPLATE and ADDRESS names of a .def source in declaration order."""
+    document = parse_def_document(source)
     return DefSymbols(
-        block_templates=_names(_BLOCK_TEMPLATE_RE, source),
-        addresses=_names(_ADDRESS_RE, source),
+        block_templates=document.names(BLOCK_TEMPLATE),
+        addresses=document.names(ADDRESS),
     )
 
 
-def read_def_symbols(path: Path) -> DefSymbols:
+def read_def_source(path: Path) -> str:
     data = path.read_bytes()
     try:
-        source = data.decode("utf-8-sig")
+        return data.decode("utf-8-sig")
     except UnicodeDecodeError:
         # Older Windows NX layers use the ANSI code page.
-        source = data.decode("cp1252")
-    return parse_def_symbols(source)
+        return data.decode("cp1252")
+
+
+def read_def_symbols(path: Path) -> DefSymbols:
+    return parse_def_symbols(read_def_source(path))

server/src/tools/navigation.py

@@ -114,6 +114,49 @@ def _name_range(node: Node, raw_name: str, *, variable_sub: bool = False) -> lsp
     )
 
 
+DEF_BLOCK_TEMPLATE = "block_template"
+DEF_ADDRESS = "address"
+DEF_SYMBOL_KINDS = frozenset({DEF_BLOCK_TEMPLATE, DEF_ADDRESS})
+
+# NX commands taking .def names: command -> (first argument index, last index or
+# None for all following arguments, kind).
+_DEF_ARGUMENTS: dict[str, tuple[tuple[int, int | None, str], ...]] = {
+    "MOM_do_template": ((0, 0, DEF_BLOCK_TEMPLATE),),
+    "MOM_add_to_block_buffer": ((0, 0, DEF_BLOCK_TEMPLATE),),
+    "MOM_polar_motion": ((0, 0, DEF_BLOCK_TEMPLATE),),
+    "MOM_force_block": ((1, None, DEF_BLOCK_TEMPLATE),),
+    "MOM_ask_address_value": ((0, 0, DEF_ADDRESS),),
+    "MOM_add_to_address_buffer": ((0, 0, DEF_ADDRESS),),
+    "MOM_enable_address": ((0, None, DEF_ADDRESS),),
+    "MOM_disable_address": ((0, None, DEF_ADDRESS),),
+    "MOM_force": ((1, None, DEF_ADDRESS),),
+    "MOM_suppress": ((1, None, DEF_ADDRESS),),
+    "MOM_incremental": ((1, None, DEF_ADDRESS),),
+}
+_DEFINITION_ELEMENT_KINDS = {"ADDRESS": DEF_ADDRESS, "BLOCK": DEF_BLOCK_TEMPLATE}
+
+
+def def_argument_kinds(command: Command) -> list[tuple[Node, str]]:
+    """Return the arguments of ``command`` that name a .def block template or address."""
+    routine = _static_contents(command.routine)
+    if routine in {"MOM_ask_definition_element", "MOM_has_definition_element"}:
+        kind = _DEFINITION_ELEMENT_KINDS.get((_static_contents(command.args[0]) or "").upper()) if command.args else None
+        return [(command.args[1], kind)] if kind and len(command.args) >= 2 else []
+    result = []
+    for first, last, kind in _DEF_ARGUMENTS.get(routine or "", ()):
+        for position, argument in enumerate(command.args):
+            if position >= first and (last is None or position <= last):
+                result.append((argument, kind))
+    return result
+
+
+def _def_name(node: Node) -> str | None:
+    name = _static_contents(node)
+    if not name or node.contents_pos is None or any(char.isspace() or char in "$[]{}\\\"" for char in name):
+        return None
+    return name
+
+
 def _node_range(node: Node) -> lsp.Range | None:
     if node.pos is None or node.end_pos is None:
         return None
@@ -436,6 +479,23 @@ def build_file_symbol_index(
         if routine:
             add_proc(command.routine, routine, scope, is_definition=False)
 
+        for node, kind in def_argument_kinds(command):
+            name = _def_name(node)
+            if name is None:
+                continue
+            line, column = node.contents_pos
+            occurrences.append(
+                SymbolOccurrence(
+                    identity=shared(SymbolIdentity(kind=kind, name=name)),
+                    range=lsp.Range(
+                        start=lsp.Position(line=line - 1, character=column - 1),
+                        end=lsp.Position(line=line - 1, character=column - 1 + len(name)),
+                    ),
+                    placeholder=name,
+                    symbol_kind=lsp.SymbolKind.Struct if kind == DEF_BLOCK_TEMPLATE else lsp.SymbolKind.Field,
+                )
+            )
+
         declaration_nodes = _variable_declaration_nodes(command)
         declaration_ids = {id(node) for node in declaration_nodes}
         for node in declaration_nodes:

server/src/tools/tcl_command_completion.py

@@ -430,6 +430,7 @@ VALUES_BY_POSITION: dict[tuple[tuple[str, ...], int], tuple[str, ...]] = {
     (("array", "names"), 3): ("-exact", "-glob", "-regexp"),
     (("MOM_force",), 1): ("Always", "Once", "Off"),
     (("MOM_suppress",), 1): ("Always", "Once", "Off"),
+    (("MOM_do_template",), 2): ("CREATE", "BUFFER"),
     (("close",), 2): ("read", "write"),
     (("open",), 2): ("r", "r+", "w", "w+", "a", "a+"),
     (("package", "prefer"), 2): ("latest", "stable"),
@@ -475,11 +476,14 @@ DYNAMIC_COMPLETION_RULES = (
     DynamicCompletionRule(("rename",), frozenset({1}), DynamicCompletionKind.PROCEDURE),
     # Namespace-taking commands.
     DynamicCompletionRule(("MOM_do_template",), frozenset({1}), DynamicCompletionKind.BLOCK_TEMPLATE),
+    DynamicCompletionRule(("MOM_do_template",), frozenset({2}), DynamicCompletionKind.VALUE),
     DynamicCompletionRule(("MOM_ask_address_value",), frozenset({1}), DynamicCompletionKind.ADDRESS),
     DynamicCompletionRule(("MOM_force",), frozenset({1}), DynamicCompletionKind.VALUE),
     DynamicCompletionRule(("MOM_force",), _REPEATED_SUBCOMMAND_ARGUMENTS, DynamicCompletionKind.ADDRESS),
     DynamicCompletionRule(("MOM_suppress",), frozenset({1}), DynamicCompletionKind.VALUE),
     DynamicCompletionRule(("MOM_suppress",), _REPEATED_SUBCOMMAND_ARGUMENTS, DynamicCompletionKind.ADDRESS),
+    DynamicCompletionRule(("MOM_disable_address",), frozenset(range(1, 33)), DynamicCompletionKind.ADDRESS),
+    DynamicCompletionRule(("MOM_enable_address",), _REPEATED_SUBCOMMAND_ARGUMENTS, DynamicCompletionKind.ADDRESS),
     DynamicCompletionRule(("namespace", "children"), frozenset({2}), DynamicCompletionKind.NAMESPACE),
     DynamicCompletionRule(
         ("namespace", "delete"),

server/tests/python_tests/test_completion_context.py

@@ -47,20 +47,9 @@ def _document(path: Path, source: str) -> TextDocument:
     )
 
 
-def _completion_server(
-    tmp_path: Path, monkeypatch
-) -> tuple[TclLanguageServer, TextDocument, str]:
+def _completion_server(tmp_path: Path, monkeypatch) -> tuple[TclLanguageServer, TextDocument, str]:
     declared_builtin = standard_items.nx_variables[0].label
-    current_source = (
-        "set globalValue 1\n"
-        "proc localProc {} { return }\n"
-        "proc caller {argument} {\n"
-        f"    global {declared_builtin}\n"
-        "    set localValue 2\n"
-        "    puts $local\n"
-        "    localP\n"
-        "}\n"
-    )
+    current_source = f"set globalValue 1\nproc localProc {{}} {{ return }}\nproc caller {{argument}} {{\n    global {declared_builtin}\n    set localValue 2\n    puts $local\n    localP\n}}\n"
     workspace_source = """set ::workspaceValue 1
 proc workspaceProc {} { return }
 """
@@ -113,14 +102,10 @@ def test_unset_space_shows_options_then_variables(tmp_path, monkeypatch):
         items = _complete(document, lsp.Position(line=1, character=len(tail)))
         labels = {item.label for item in items}
         if tail in {"unset ", "unset -"}:
-            assert labels == {"-nocomplain", "--"}
+            assert labels == {"nocomplain"}
         else:
             assert "globalValue" in labels
             assert "-nocomplain" not in labels
-            if tail == "unset -nocomplain ":
-                assert "--" in labels
-            else:
-                assert "--" not in labels
 
 
 def test_array_keys_complete_in_set_and_substitution(tmp_path: Path, monkeypatch):
@@ -130,19 +115,16 @@ def test_array_keys_complete_in_set_and_substitution(tmp_path: Path, monkeypatch
         "set ::lib_flag(enabled) 1\nset ::lib_flag(external) 1\n",
     )
     assert server.update_poco_completion_for_file(workspace)
-    source = (
-        "set lib_flag(enabled) 0\n"
-        "set lib_flag(empty) 1\n"
-        "set other(wrong) 1\n"
-        "proc hidden {} { set lib_flag(private) 1 }\n"
-        "set lib_flag()\n"
-        "puts $lib_flag(en)\n"
-        "puts 😀; set lib_flag(em\n"
-    )
+    source = "set lib_flag(enabled) 0\nset lib_flag(empty) 1\nset other(wrong) 1\nproc hidden {} { set lib_flag(private) 1 }\nset lib_flag()\nputs $lib_flag(en)\nputs 😀; set lib_flag(em\n"
     current = _document(tmp_path / "arrays-current.tcl", source)
-    server.workspace.put_text_document(lsp.TextDocumentItem(
-        uri=current.uri, language_id="tcl", version=1, text=source,
-    ))
+    server.workspace.put_text_document(
+        lsp.TextDocumentItem(
+            uri=current.uri,
+            language_id="tcl",
+            version=1,
+            text=source,
+        )
+    )
     assert server.update_poco_completion_for_file(current)
     items = _complete(current, _position_after(source, "set lib_flag(", 3))
     assert [item.label for item in items] == ["empty", "enabled", "external"]
@@ -179,32 +161,28 @@ def test_dynamic_array_index_keeps_variable_identity(tmp_path: Path, monkeypatch
     assert variable_name(tree.children[3].args[0]) is None
     path = tmp_path / "dynamic.tcl"
     index = build_file_symbol_index(str(path), path.as_uri(), tree)
-    definition = next(
-        item for item in index.occurrences
-        if item.identity.name == "::custom_flag" and item.is_definition
-    )
+    definition = next(item for item in index.occurrences if item.identity.name == "::custom_flag" and item.is_definition)
     assert definition.range.start.character == 4
     assert definition.range.end.character == 15
     assert definition.array_element is None
     assert any(item.identity.name == "::mom_path_name" for item in index.occurrences)
     highlighter = _Highlighter([], {})
     tree.accept(highlighter, recurse=True)
-    assert any(
-        position == (0, 4) and length == 11 and kind == "variable"
-        for position, length, kind, _ in highlighter._tokens
-    )
+    assert any(position == (0, 4) and length == 11 and kind == "variable" for position, length, kind, _ in highlighter._tokens)
     server, _, _ = _completion_server(tmp_path, monkeypatch)
     current = _document(path, source)
-    server.workspace.put_text_document(lsp.TextDocumentItem(
-        uri=current.uri, language_id="tcl", version=1, text=source,
-    ))
+    server.workspace.put_text_document(
+        lsp.TextDocumentItem(
+            uri=current.uri,
+            language_id="tcl",
+            version=1,
+            text=source,
+        )
+    )
     assert server.update_poco_completion_for_file(current)
     items = _complete(current, _position_after(source, "puts $custom"))
     assert "custom_flag" in {item.label for item in items}
-    workspace_items = next(
-        items for item_path, items in server.completion_items_by_file_snapshot().items()
-        if server.paths_equal(item_path, str(path))
-    )
+    workspace_items = next(items for item_path, items in server.completion_items_by_file_snapshot().items() if server.paths_equal(item_path, str(path)))
     assert {"quoted_flag", "command_flag"} <= {item.label for item in workspace_items}
 
 
@@ -236,18 +214,25 @@ def test_literal_array_components_complete_around_substitutions(tmp_path: Path,
         offset = marked.index("|")
         line = marked.replace("|", "")
         items = array_element_completions(
-            [line], lsp.Position(line=0, character=offset),
-            server.navigation_snapshot().values(), str(tmp_path / "caller.tcl"),
+            [line],
+            lsp.Position(line=0, character=offset),
+            server.navigation_snapshot().values(),
+            str(tmp_path / "caller.tcl"),
         )
         assert {item.label for item in items} == labels
         edit = next(item.text_edit for item in items if item.label == selected)
         item = next(item for item in items if item.label == selected)
         assert item.insert_text_format == lsp.InsertTextFormat.PlainText
-        assert line[:edit.range.start.character] + edit.new_text + line[edit.range.end.character:] == expected
-    assert array_element_completions(
-        ["set custom_flag(from_move,$::mom"], lsp.Position(line=0, character=31),
-        server.navigation_snapshot().values(), str(tmp_path / "caller.tcl"),
-    ) is None
+        assert line[: edit.range.start.character] + edit.new_text + line[edit.range.end.character :] == expected
+    assert (
+        array_element_completions(
+            ["set custom_flag(from_move,$::mom"],
+            lsp.Position(line=0, character=31),
+            server.navigation_snapshot().values(),
+            str(tmp_path / "caller.tcl"),
+        )
+        is None
+    )
 
 
 def _argument_completion_request(source: str):
@@ -277,9 +262,7 @@ def test_variable_completion_filters_and_ranks_candidates(tmp_path: Path, monkey
     other_builtin = standard_items.nx_variables[1]
     assert declared_builtin.label in by_label
     assert other_builtin.label in by_label
-    assert by_label[declared_builtin.label].documentation == (
-        declared_builtin.documentation
-    )
+    assert by_label[declared_builtin.label].documentation == (declared_builtin.documentation)
     assert by_label["localValue"].sort_text.startswith("000:")
     assert by_label["globalValue"].sort_text.startswith("100:")
     assert by_label["workspaceValue"].sort_text.startswith("200:")
@@ -307,18 +290,9 @@ def test_command_completion_filters_and_ranks_candidates(tmp_path: Path, monkeyp
 
 
 def test_completion_context_handles_nested_commands_and_utf16():
-    assert (
-        completion_context(["set result [work"], lsp.Position(line=0, character=16))
-        == CompletionContext.COMMAND
-    )
-    assert (
-        completion_context(["😀 puts $value"], lsp.Position(line=0, character=14))
-        == CompletionContext.VARIABLE
-    )
-    assert (
-        completion_context(["puts value"], lsp.Position(line=0, character=10))
-        == CompletionContext.GENERAL
-    )
+    assert completion_context(["set result [work"], lsp.Position(line=0, character=16)) == CompletionContext.COMMAND
+    assert completion_context(["😀 puts $value"], lsp.Position(line=0, character=14)) == CompletionContext.VARIABLE
+    assert completion_context(["puts value"], lsp.Position(line=0, character=10)) == CompletionContext.GENERAL
 
 
 def test_string_subcommands_and_compare_options_are_context_aware():
@@ -330,9 +304,7 @@ def test_string_subcommands_and_compare_options_are_context_aware():
         "-length",
         "-nocase",
     }
-    assert _argument_completion_labels("string compare -nocase ") == {
-        "-length"
-    }
+    assert _argument_completion_labels("string compare -nocase ") == {"-length"}
     assert _argument_completion_labels("string compare -length ") is None
 
 
@@ -356,22 +328,14 @@ def test_string_completion_inside_braced_conditions_and_bodies():
         subcommands = _argument_completion_labels(prefix + "[string ")
         assert subcommands is not None
         assert {"compare", "equal", "is"} <= subcommands
-        assert _argument_completion_labels(prefix + "[string compare -") == {
-            "-length", "-nocase"
-        }
-        assert _argument_completion_labels(
-            prefix + "[string compare -nocase "
-        ) == {"-length"}
+        assert _argument_completion_labels(prefix + "[string compare -") == {"-length", "-nocase"}
+        assert _argument_completion_labels(prefix + "[string compare -nocase ") == {"-length"}
 
 
 def test_closed_braced_arguments_do_not_change_completion_context():
     assert _argument_completion_labels("puts {[string compare }") is None
-    assert _argument_completion_labels(
-        "if {[string equal a b]} {string compare "
-    ) == {"-length", "-nocase"}
-    assert _argument_completion_labels(
-        "if {[string equal a b] && [string is integer "
-    ) == {"-failindex", "-strict"}
+    assert _argument_completion_labels("if {[string equal a b]} {string compare ") == {"-length", "-nocase"}
+    assert _argument_completion_labels("if {[string equal a b] && [string is integer ") == {"-failindex", "-strict"}
 
 
 def test_dict_array_namespace_file_and_info_subcommands():
@@ -413,9 +377,7 @@ def test_dict_array_namespace_file_and_info_subcommands():
     assert {"args", "body", "commands", "exists", "procs", "vars"} <= info_items
 
 
-def test_variable_context_still_takes_priority_inside_tcl_command(
-    tmp_path: Path, monkeypatch
-):
+def test_variable_context_still_takes_priority_inside_tcl_command(tmp_path: Path, monkeypatch):
     _, current, source = _completion_server(tmp_path, monkeypatch)
     command_source = source.replace(
         "    puts $local\n",
@@ -437,9 +399,7 @@ def test_variable_context_still_takes_priority_inside_tcl_command(
     assert "localValue" in {item.label for item in items}
 
 
-def test_lsp_completion_returns_only_matching_command_options(
-    tmp_path: Path, monkeypatch
-):
+def test_lsp_completion_returns_only_matching_command_options(tmp_path: Path, monkeypatch):
     _, current, _ = _completion_server(tmp_path, monkeypatch)
     source = "string compare "
     current = _document(tmp_path / "current.tcl", source)
@@ -459,9 +419,7 @@ def test_lsp_completion_returns_only_matching_command_options(
     assert all(item.sort_text.startswith("000:") for item in items)
 
 
-def test_space_trigger_does_not_open_broad_fallback_completion(
-    tmp_path: Path, monkeypatch
-):
+def test_space_trigger_does_not_open_broad_fallback_completion(tmp_path: Path, monkeypatch):
     _, current, _ = _completion_server(tmp_path, monkeypatch)
     source = "set value "
     current = _document(tmp_path / "current.tcl", source)
@@ -550,9 +508,7 @@ def test_path_completion_is_relative_filtered_and_tcl_safe(tmp_path: Path):
     assert items[0].text_edit.range.start.character == len("source ")
 
 
-def test_lsp_source_completion_reads_paths_from_document_directory(
-    tmp_path: Path, monkeypatch
-):
+def test_lsp_source_completion_reads_paths_from_document_directory(tmp_path: Path, monkeypatch):
     server, current, _ = _completion_server(tmp_path, monkeypatch)
     scripts = tmp_path / "scripts"
     scripts.mkdir()
@@ -576,9 +532,7 @@ def test_lsp_source_completion_reads_paths_from_document_directory(
     assert "scripts/ignored.txt" not in labels
 
 
-def test_command_and_dict_for_snippets_use_lsp_snippet_placeholders(
-    tmp_path: Path, monkeypatch
-):
+def test_command_and_dict_for_snippets_use_lsp_snippet_placeholders(tmp_path: Path, monkeypatch):
     _, current, source = _completion_server(tmp_path, monkeypatch)
     command_items = _complete(current, _position_after(source, "localP", occurrence=1))
     command_by_label = {item.label: item for item in command_items}
@@ -595,14 +549,10 @@ def test_command_and_dict_for_snippets_use_lsp_snippet_placeholders(
 
     switch_arguments = _argument_completion_request("switch ")
     assert switch_arguments is not None
-    assert {"switch block", "-exact", "-glob", "-regexp"} <= {
-        item.label for item in switch_arguments.items
-    }
+    assert {"switch block", "-exact", "-glob", "-regexp"} <= {item.label for item in switch_arguments.items}
 
 
-def test_semantic_variable_and_procedure_argument_completion(
-    tmp_path: Path, monkeypatch
-):
+def test_semantic_variable_and_procedure_argument_completion(tmp_path: Path, monkeypatch):
     _, current, source = _completion_server(tmp_path, monkeypatch)
 
     variable_items = _complete(current, _position_after(source, "    set "))
@@ -633,9 +583,7 @@ def test_semantic_variable_and_procedure_argument_completion(
     assert "string" not in procedure_labels
 
 
-def test_namespace_argument_completion_uses_navigation_index(
-    tmp_path: Path, monkeypatch
-):
+def test_namespace_argument_completion_uses_navigation_index(tmp_path: Path, monkeypatch):
     server, current, _ = _completion_server(tmp_path, monkeypatch)
     namespace_source = "namespace eval tools { proc helper {} { return } }\n"
     namespace_document = _document(tmp_path / "namespaces.tcl", namespace_source)

server/tests/python_tests/test_def_navigation.py

@@ -0,0 +1,242 @@
+"""Go to Definition, hover, references and rename between Tcl and .def files."""
+
+from collections import namedtuple
+from pathlib import Path
+
+import lsprotocol.types as lsp  # type: ignore
+from pygls.workspace import Workspace
+
+import lsp_server
+from lsp_tclserver import TclLanguageServer
+from tools.def_symbols import ADDRESS, BLOCK_TEMPLATE, FORMAT, parse_def_document
+
+PSC = """<?xml version="1.0" encoding="UTF-8"?>
+<Configuration>
+  <Sourcing><Sequence>
+    <Layer Name="Service" SubFolder="service">
+      <DefinedEvents><Filename Name="service"/></DefinedEvents>
+    </Layer>
+  </Sequence></Sourcing>
+</Configuration>
+"""
+
+DEF = """MACHINE Default
+
+FORMATTING
+{
+    FORMAT Coordinate "&__4.3_"
+    ADDRESS SPOS
+    {
+        FORMAT      Coordinate
+        FORCE       off
+        MAX         99999.999 Abort
+        MIN         -99999.999 Abort
+        LEADER      "SPOS="
+    }
+    # ADDRESS commented_out
+    BLOCK_TEMPLATE steady_rest
+    {
+        SPOS[$mom_pos(0)]
+        Text[M60]\\opt
+    }
+}
+"""
+
+TCL = """proc MOM_steady {} {
+    MOM_do_template steady_rest
+    MOM_force Once SPOS X
+    MOM_ask_address_value "SPOS"
+    set name steady_rest
+}
+"""
+
+
+def _project(tmp_path: Path, monkeypatch):
+    (tmp_path / "service").mkdir()
+    (tmp_path / "post.psc").write_text(PSC, encoding="utf-8")
+    def_file = tmp_path / "service" / "service.def"
+    def_file.write_text(DEF, encoding="utf-8")
+    tcl_file = tmp_path / "caller.tcl"
+    tcl_file.write_text(TCL, encoding="utf-8")
+
+    server = TclLanguageServer(name="def-navigation-test", version="1", max_workers=1)
+    server.protocol._workspace = Workspace(  # pylint: disable=protected-access
+        root_uri=tmp_path.as_uri(),
+        sync_kind=lsp.TextDocumentSyncKind.Incremental,
+        workspace_folders=[lsp.WorkspaceFolder(uri=tmp_path.as_uri(), name="root")],
+        position_encoding=lsp.PositionEncodingKind.Utf16,
+    )
+    monkeypatch.setattr(lsp_server, "LSP_SERVER", server)
+    server.refresh_psc_scripts([tmp_path])
+    server.workspace.put_text_document(
+        lsp.TextDocumentItem(uri=tcl_file.as_uri(), language_id="tcl", version=1, text=TCL)
+    )
+    server.update_poco_completion_for_file(server.workspace.get_text_document(tcl_file.as_uri()))
+    return server, def_file, tcl_file
+
+
+def _position(source: str, needle: str, occurrence: int = 0, offset: int = 1) -> lsp.Position:
+    index = -1
+    for _ in range(occurrence + 1):
+        index = source.index(needle, index + 1)
+    line = source.count("\n", 0, index)
+    column = index - (source.rfind("\n", 0, index) + 1)
+    return lsp.Position(line=line, character=column + offset)
+
+
+def _tcl_params(tcl_file: Path, needle: str, occurrence: int = 0):
+    return lsp.TextDocumentIdentifier(uri=tcl_file.as_uri()), _position(TCL, needle, occurrence)
+
+
+# The client sends custom .def requests as plain JSON; pygls exposes them as namedtuples.
+_Doc = namedtuple("Object", ["uri"])
+_Pos = namedtuple("Object", ["line", "character"])
+_Params = namedtuple("Object", ["textDocument", "position", "text", "includeDeclaration", "newName"])
+
+
+def _def_params(def_file: Path, needle: str, occurrence: int = 0, text: str = DEF, offset: int = 1, **extra):
+    position = _position(text, needle, occurrence, offset)
+    return _Params(
+        _Doc(def_file.as_uri()),
+        _Pos(position.line, position.character),
+        text,
+        extra.get("includeDeclaration", True),
+        extra.get("newName", ""),
+    )
+
+
+def _lines(locations):
+    return sorted((Path(location.uri).name, location.range.start.line, location.range.start.character) for location in locations)
+
+
+def test_parse_def_document_declarations_and_references():
+    document = parse_def_document(DEF)
+    kinds = [(item.kind, item.name) for item in document.declarations]
+    assert kinds == [(FORMAT, "Coordinate"), (ADDRESS, "SPOS"), (BLOCK_TEMPLATE, "steady_rest")]
+    address = document.declarations[1]
+    assert (address.line, address.start, address.end) == (5, 12, 16)
+    assert dict(address.properties)["LEADER"] == '"SPOS="'
+    assert [(ref.name, ref.line, ref.container) for ref in document.references] == [
+        ("SPOS", 16, "steady_rest"),
+        ("Text", 17, "steady_rest"),
+    ]
+    assert document.declarations[2].text.splitlines()[-1].strip() == "}"
+
+
+def test_tcl_goto_definition_of_template_and_address(tmp_path, monkeypatch):
+    _, def_file, tcl_file = _project(tmp_path, monkeypatch)
+    document, position = _tcl_params(tcl_file, "steady_rest")
+    result = lsp_server.goto_definition(lsp.DefinitionParams(text_document=document, position=position))
+    assert _lines(result) == [("service.def", 14, 19)]
+
+    for needle, occurrence in (("SPOS", 0), ("SPOS", 1)):
+        document, position = _tcl_params(tcl_file, needle, occurrence)
+        result = lsp_server.goto_definition(lsp.DefinitionParams(text_document=document, position=position))
+        assert _lines(result) == [("service.def", 5, 12)]
+
+
+def test_tcl_goto_definition_ignores_plain_words_and_unknown_names(tmp_path, monkeypatch):
+    _, _, tcl_file = _project(tmp_path, monkeypatch)
+    # "set name steady_rest" is no template argument.
+    document, position = _tcl_params(tcl_file, "steady_rest", 1)
+    assert lsp_server.goto_definition(lsp.DefinitionParams(text_document=document, position=position)) is None
+    document, position = lsp.TextDocumentIdentifier(uri=tcl_file.as_uri()), _position(TCL, "SPOS X", offset=5)
+    assert lsp_server.goto_definition(lsp.DefinitionParams(text_document=document, position=position)) is None
+
+
+def test_tcl_hover_shows_template_body_and_address_properties(tmp_path, monkeypatch):
+    _, _, tcl_file = _project(tmp_path, monkeypatch)
+    document, position = _tcl_params(tcl_file, "steady_rest")
+    hover = lsp_server.hover(lsp.HoverParams(text_document=document, position=position))
+    assert "Block template" in hover.contents.value
+    assert "SPOS[$mom_pos(0)]" in hover.contents.value
+    assert "```def" in hover.contents.value
+
+    document, position = _tcl_params(tcl_file, "SPOS")
+    value = lsp_server.hover(lsp.HoverParams(text_document=document, position=position)).contents.value
+    assert "| Format | `Coordinate` → `\"&__4.3_\"` |" in value
+    assert '| Leader | `"SPOS="` |' in value
+    assert "| Min | `-99999.999 Abort` |" in value
+    assert "| Max | `99999.999 Abort` |" in value
+    assert "| Modality | `off` (modal, output only on change) |" in value
+
+
+def test_tcl_references_include_def_declaration_and_template_elements(tmp_path, monkeypatch):
+    _, _, tcl_file = _project(tmp_path, monkeypatch)
+    document, position = _tcl_params(tcl_file, "SPOS")
+    result = lsp_server.references(
+        lsp.ReferenceParams(
+            text_document=document,
+            position=position,
+            context=lsp.ReferenceContext(include_declaration=True),
+        )
+    )
+    assert _lines(result) == [
+        ("caller.tcl", 2, 19),
+        ("caller.tcl", 3, 27),
+        ("service.def", 5, 12),
+        ("service.def", 16, 8),
+    ]
+    result = lsp_server.references(
+        lsp.ReferenceParams(
+            text_document=document,
+            position=position,
+            context=lsp.ReferenceContext(include_declaration=False),
+        )
+    )
+    assert ("service.def", 5, 12) not in _lines(result)
+
+
+def test_tcl_rename_updates_def_and_tcl(tmp_path, monkeypatch):
+    _, def_file, tcl_file = _project(tmp_path, monkeypatch)
+    document, position = _tcl_params(tcl_file, "SPOS")
+    prepared = lsp_server.prepare_rename(lsp.PrepareRenameParams(text_document=document, position=position))
+    assert prepared.placeholder == "SPOS"
+
+    edit = lsp_server.rename(lsp.RenameParams(text_document=document, position=position, new_name="STEADY_POS"))
+    edits = {Path(uri).name: [(e.range.start.line, e.range.start.character) for e in items] for uri, items in edit.changes.items()}
+    assert edits == {"caller.tcl": [(3, 27), (2, 19)], "service.def": [(16, 8), (5, 12)]}
+    assert all(e.new_text == "STEADY_POS" for items in edit.changes.values() for e in items)
+
+
+def test_undeclared_names_are_not_renamed(tmp_path, monkeypatch):
+    _, _, tcl_file = _project(tmp_path, monkeypatch)
+    document = lsp.TextDocumentIdentifier(uri=tcl_file.as_uri())
+    position = _position(TCL, "SPOS X", offset=5)
+    assert lsp_server.prepare_rename(lsp.PrepareRenameParams(text_document=document, position=position)) is None
+
+
+def test_def_requests_resolve_declarations_and_elements(tmp_path, monkeypatch):
+    _, def_file, _ = _project(tmp_path, monkeypatch)
+    # Address element inside a block template -> ADDRESS declaration.
+    result = lsp_server.def_definition(_def_params(def_file, "SPOS[", offset=1))
+    assert _lines(result) == [("service.def", 5, 12)]
+
+    hover = lsp_server.def_hover(_def_params(def_file, "steady_rest"))
+    assert "Text[M60]" in hover.contents.value
+
+    references = lsp_server.def_references(_def_params(def_file, "ADDRESS SPOS", offset=9))
+    assert _lines(references) == [
+        ("caller.tcl", 2, 19),
+        ("caller.tcl", 3, 27),
+        ("service.def", 5, 12),
+        ("service.def", 16, 8),
+    ]
+    assert lsp_server.def_hover(_def_params(def_file, "MACHINE")) is None
+
+
+def test_def_requests_use_unsaved_text(tmp_path, monkeypatch):
+    _, def_file, _ = _project(tmp_path, monkeypatch)
+    text = DEF.replace("BLOCK_TEMPLATE steady_rest", "BLOCK_TEMPLATE steady_rest_new")
+    params = _def_params(def_file, "steady_rest_new", text=text, newName="rest")
+    assert lsp_server.def_prepare_rename(params).placeholder == "steady_rest_new"
+    edit = lsp_server.def_rename(params)
+    assert list(edit.changes) == [def_file.as_uri()]
+
+
+def test_def_rename_updates_tcl_callers(tmp_path, monkeypatch):
+    _, def_file, _ = _project(tmp_path, monkeypatch)
+    edit = lsp_server.def_rename(_def_params(def_file, "steady_rest", newName="lunette"))
+    edits = {Path(uri).name: [(e.range.start.line, e.range.start.character) for e in items] for uri, items in edit.changes.items()}
+    assert edits == {"caller.tcl": [(1, 20)], "service.def": [(14, 19)]}
+    assert lsp_server.def_rename(_def_params(def_file, "steady_rest", newName="bad name")) is None