Cross-file navigation and rename for PSC .def templates and addresses #46

Merged

Christoph merged 0 commits from refs/pull/46/head into main

2026-09-24 20:56:28 +00:00

Christoph commented

2026-09-24 20:56:23 +00:00

(Migrated from git.cbsk-tech.de)

This change adds language-server and client support for navigating, hovering, finding references, and renaming PSC .def block templates and addresses across Tcl and .def files.

The combined change implements these behaviors:

Recognize .def symbols in the server:
- server/src/tools/def_symbols.py now parses .def sources into a structured DefDocument with declarations (block templates, addresses, formats) and references (addresses used inside block templates). It also exposes helpers to read .def source and produce the previous name-only view.
- New UTF-16 column handling, body extraction and property parsing allow producing precise ranges and hover text from .def files.
Indexing and navigation integration:
- server/src/tools/navigation.py is extended with DEF_BLOCK_TEMPLATE/DEF_ADDRESS kinds, a mapping of Tcl commands that accept .def names, and logic to add symbol occurrences for .def usages in Tcl commands (so Go to Definition / Find References work from Tcl code).
- The language server (server/src/lsp_server.py) uses these new symbol kinds and adds handlers to resolve .def-specific requests and to return definition/hover/reference/rename results for .def symbols. The server exposes request names nxPostSupport/def/definition, .../hover, .../references, .../prepareRename, and .../rename to accept the current .def text from the client (since .def files are not synchronized).
- Rename handling is extended to allow renames of .def symbols; the server validates identifier syntax using DEF_NAME_RE.
Client-side providers and activation:
- client/src/common/defProviders.ts registers Definition, Hover, Reference and Rename providers for .def files. Each provider forwards the current document text and cursor position to the language server via the new nxPostSupport/def/* requests and converts protocol results back to editor types.
- client/src/extension.ts registers these providers during activation.
Completion and service updates:
- server/src/lsp_tclserver.py and server/src/tools/tcl_command_completion.py are updated to use the richer .def document representation (addresses/block template completion, and completion for commands that accept .def names).
Documentation and changelog updates:
- README.md and CHANGELOG.md updated to document Go to Definition, hover, references, and Rename across Tcl and .def files and list the recognized Tcl commands.

Why this matters (supported by diff evidence):

Before: .def files were only partially handled (previous code exposed only name lists), and Tcl-side occurrences referencing .def names were not indexed for cross-file navigation.
After: the server parses full .def sources, indexes declarations and references, recognizes Tcl commands that take .def names, and exposes cross-file language features through new LSP request routes. The client registers corresponding .def language providers and forwards the current .def text with each request.

Files and implementation notes (only where helpful to assess correctness):

New client file: client/src/common/defProviders.ts (registers providers and forwards doc text).
Extension activation updated: client/src/extension.ts calls registerDefProviders(() => client).
Server parsing: server/src/tools/def_symbols.py introduces DefDeclaration, DefReference, DefDocument and parse_def_document, plus read_def_source.
Server handlers and integration: server/src/lsp_server.py adds helper functions and LSP features for the nxPostSupport/def/* requests and calls into tools.def_navigation helpers.
Navigation index: server/src/tools/navigation.py adds recognition for command argument positions that name block templates/addresses and creates SymbolOccurrence entries for those arguments.

Testing

No test execution results were provided.

Recommended manual checks for a reviewer (focused, reproducible):

Open a workspace containing a PSC .def file and a Tcl file that calls a recognized command (e.g. MOM_do_template "steady_rest").
- Place cursor on the template name in Tcl and press F12: it should open the BLOCK_TEMPLATE declaration in the .def file.
Hover on a block template name in Tcl: hover should show the template body. Hover on an address name should show format/leader/trailer/min/max/modality parsed from the .def file.
Use Find All References (Shift+F12) on a .def declaration: it should list the declaration, usages in Tcl, and block-template usages inside .def bodies.
Rename (F2) a declared block template or address (only when the .def file is loaded by the server): the declaration and all usages in Tcl and .def files should be updated together.
Open and edit a .def file without saving; confirm that Go to Definition / Hover / References still work (the client sends current unsaved text to the server).

Compatibility / reviewer notes

.def files are not synchronized in the server; the client sends the current document text with each specialized nxPostSupport/def/* request. The server provides def_documents_snapshot(current_path, current_source) to replace the current file content during requests.
Rename is only allowed for names declared in a loaded .def file (the server returns prepareRename only for declarations present in the parsed .def documents).
Identifier validation uses DEF_NAME_RE when renaming.

If you want, I can list focused unit or integration tests to add for the server/parser and for the client providers to make the behavior repeatable under CI.

This change adds language-server and client support for navigating, hovering, finding references, and renaming PSC .def block templates and addresses across Tcl and .def files. The combined change implements these behaviors: - Recognize .def symbols in the server: - `server/src/tools/def_symbols.py` now parses `.def` sources into a structured `DefDocument` with declarations (block templates, addresses, formats) and references (addresses used inside block templates). It also exposes helpers to read `.def` source and produce the previous name-only view. - New UTF-16 column handling, body extraction and property parsing allow producing precise ranges and hover text from `.def` files. - Indexing and navigation integration: - `server/src/tools/navigation.py` is extended with `DEF_BLOCK_TEMPLATE`/`DEF_ADDRESS` kinds, a mapping of Tcl commands that accept `.def` names, and logic to add symbol occurrences for `.def` usages in Tcl commands (so Go to Definition / Find References work from Tcl code). - The language server (`server/src/lsp_server.py`) uses these new symbol kinds and adds handlers to resolve `.def`-specific requests and to return definition/hover/reference/rename results for `.def` symbols. The server exposes request names `nxPostSupport/def/definition`, `.../hover`, `.../references`, `.../prepareRename`, and `.../rename` to accept the current `.def` text from the client (since `.def` files are not synchronized). - Rename handling is extended to allow renames of `.def` symbols; the server validates identifier syntax using `DEF_NAME_RE`. - Client-side providers and activation: - `client/src/common/defProviders.ts` registers Definition, Hover, Reference and Rename providers for `.def` files. Each provider forwards the current document text and cursor position to the language server via the new `nxPostSupport/def/*` requests and converts protocol results back to editor types. - `client/src/extension.ts` registers these providers during activation. - Completion and service updates: - `server/src/lsp_tclserver.py` and `server/src/tools/tcl_command_completion.py` are updated to use the richer `.def` document representation (addresses/block template completion, and completion for commands that accept `.def` names). - Documentation and changelog updates: - `README.md` and `CHANGELOG.md` updated to document Go to Definition, hover, references, and Rename across Tcl and `.def` files and list the recognized Tcl commands. Why this matters (supported by diff evidence): - Before: `.def` files were only partially handled (previous code exposed only name lists), and Tcl-side occurrences referencing `.def` names were not indexed for cross-file navigation. - After: the server parses full `.def` sources, indexes declarations and references, recognizes Tcl commands that take `.def` names, and exposes cross-file language features through new LSP request routes. The client registers corresponding `.def` language providers and forwards the current `.def` text with each request. Files and implementation notes (only where helpful to assess correctness): - New client file: `client/src/common/defProviders.ts` (registers providers and forwards doc text). - Extension activation updated: `client/src/extension.ts` calls `registerDefProviders(() => client)`. - Server parsing: `server/src/tools/def_symbols.py` introduces `DefDeclaration`, `DefReference`, `DefDocument` and `parse_def_document`, plus `read_def_source`. - Server handlers and integration: `server/src/lsp_server.py` adds helper functions and LSP features for the `nxPostSupport/def/*` requests and calls into `tools.def_navigation` helpers. - Navigation index: `server/src/tools/navigation.py` adds recognition for command argument positions that name block templates/addresses and creates `SymbolOccurrence` entries for those arguments. Testing No test execution results were provided. Recommended manual checks for a reviewer (focused, reproducible): 1. Open a workspace containing a PSC `.def` file and a Tcl file that calls a recognized command (e.g. `MOM_do_template "steady_rest"`). - Place cursor on the template name in Tcl and press F12: it should open the `BLOCK_TEMPLATE` declaration in the `.def` file. 2. Hover on a block template name in Tcl: hover should show the template body. Hover on an address name should show format/leader/trailer/min/max/modality parsed from the `.def` file. 3. Use Find All References (Shift+F12) on a `.def` declaration: it should list the declaration, usages in Tcl, and block-template usages inside `.def` bodies. 4. Rename (F2) a declared block template or address (only when the `.def` file is loaded by the server): the declaration and all usages in Tcl and `.def` files should be updated together. 5. Open and edit a `.def` file without saving; confirm that Go to Definition / Hover / References still work (the client sends current unsaved text to the server). Compatibility / reviewer notes - `.def` files are not synchronized in the server; the client sends the current document text with each specialized `nxPostSupport/def/*` request. The server provides `def_documents_snapshot(current_path, current_source)` to replace the current file content during requests. - Rename is only allowed for names declared in a loaded `.def` file (the server returns prepareRename only for declarations present in the parsed `.def` documents). - Identifier validation uses `DEF_NAME_RE` when renaming. If you want, I can list focused unit or integration tests to add for the server/parser and for the client providers to make the behavior repeatable under CI.