Merge pull request 'Cross-file navigation and rename for PSC .def templates and addresses' (#46) from DEF_file into main

Add client and server support to navigate, inspect, reference, and rename block
template and address symbols declared in PSC .def files:

- Client: register language providers for .def (definition, hover, references,
  prepare/provide rename) and send the current document text with each request.
- Server: parse .def files into DefDocument/DefDeclaration/DefReference, expose
  def-specific LSP endpoints (definition/hover/references/prepareRename/rename),
  and integrate .def lookups into existing Tcl hover/definition/references/rename
  flows so Tcl calls jump to .def declarations.
- Tcl server keeps a snapshot API for .def documents (current editor content can
  replace file on request); only declared names in loaded .def files can be
  renamed. Name validation uses DEF_NAME_RE.

Update README and CHANGELOG to document navigation features.

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.701",
   "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_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"),