Recognize stored COMMANDBLOCK procs and warn on unknown .def names #49

Merged

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

2026-09-25 06:46:48 +00:00

Christoph commented

2026-09-25 06:46:11 +00:00

(Migrated from git.cbsk-tech.de)

Summary of changes and observable behavior

Stored procedures in COMMANDBLOCK properties are now treated as callable procedures:
- New module server/src/tools/stored_procs.py parses braced COMMANDBLOCK values and extracts the first word of each top-level braced list element as a candidate command name (with 1-based line/column positions).
- These stored names are fed into the symbol/indexing and highlighting paths:
  - server/src/tools/navigation.py adds those names into the file symbol index so they participate in Go to Definition, Find References and rename flows.
  - server/src/tools/semantic_tokens.py highlights recognized stored names as functions (only when they are known/custom or standard).
- Tests exercising stored proc extraction, goto-definition, references, and highlighting were added in server/tests/python_tests/test_stored_procs.py.
Warnings for undeclared block templates and addresses:
- A new helper unknown_def_names in server/src/tools/def_flow.py walks literal command arguments and returns (kind, name, range) tuples for literal NX command arguments naming a BLOCK_TEMPLATE or ADDRESS that are not declared in the currently-loaded .def documents. It only checks kinds for which declarations are available in the provided declared mapping.
- The language server now includes these as LSP diagnostics via TclLanguageServer._def_diagnostics in server/src/lsp_tclserver.py. Diagnostic entries use codes unknown-block-template and unknown-address and messages like "Block template 'name' is not declared in any loaded .def file".
- When the set of loaded .def documents changes, refresh_def_symbols clears cached diagnostics and requests a client-side diagnostic refresh (via workspace diagnostic refresh support) to ensure warnings update when .def files are added/removed/changed.
- The diagnostic logic only checks literal names. Dynamic/runtime-built names (for example $var or "CYCLE_$x") are not analyzed or warned about.
- Tests in server/tests/python_tests/test_def_flow.py were extended to assert these warnings and that they are suppressed when .def files are not loaded or when names are dynamic.

Files changed (high level)

Added: server/src/tools/stored_procs.py (parsing of stored command names)
Modified: server/src/tools/navigation.py (index stored names), server/src/tools/semantic_tokens.py (highlight stored names), server/src/tools/def_flow.py (unknown_def_names), server/src/lsp_tclserver.py (produce diagnostics and request refresh), CHANGELOG.md updated
Tests: new server/tests/python_tests/test_stored_procs.py, extended server/tests/python_tests/test_def_flow.py

Testing

Tests added or changed:
- server/tests/python_tests/test_stored_procs.py (new): unit tests for stored command extraction; LSP goto-definition and references for stored names; highlighting expectations.
- server/tests/python_tests/test_def_flow.py (updated): tests that unknown block template and address names produce warnings, that dynamic names do not, and that changing .def files invalidates cached diagnostics.
No test execution results were provided.

Recommended checks for the reviewer

Run the Python/unit test suite (the repository's test runner) to confirm the new/updated tests pass.
Start the language server against a small workspace with PSC .def files and a Tcl file containing:
- literal NX commands referencing existing and non-existing block templates/addresses to observe the new diagnostics and verify the diagnostic codes (unknown-block-template, unknown-address) and ranges.
- COMMANDBLOCK set properties with braced lists containing procedure names (e.g. CONF_CTRL_tool set auto_preselect_last_template {custom_header}) and verify Go to Definition, Find References and highlighting work for those stored names.
Verify client capability handling: the server requests a diagnostics refresh only if the client's workspace.diagnostics.refresh capability is advertised; confirm behavior on clients that do and do not advertise this capability.

Compatibility and notes

The unknown-name diagnostics are only produced when .def files are loaded into self.def_documents. If no .def files are loaded, no warnings are emitted (this is deliberate and covered by tests).
Only literal, statically-known names are checked; names built at runtime (variables, concatenations) are intentionally not warned about.
The server attempts to trigger an LSP workspace diagnostic refresh when .def documents change, but this request is conditional on client capability. Reviewers should confirm LSP clients used in development/tests advertise workspace.diagnostics.refresh if they expect immediate refresh behavior.

If you want, I can provide a minimal repro workspace and exact commands to run the server and exercise these behaviors locally.

This change adds recognition of procedure names stored in PostConfigurator COMMANDBLOCK properties and introduces diagnostics that warn when literal NX command arguments name a block template or address that no loaded `.def` file declares. Summary of changes and observable behavior - Stored procedures in COMMANDBLOCK properties are now treated as callable procedures: - New module `server/src/tools/stored_procs.py` parses braced COMMANDBLOCK values and extracts the first word of each top-level braced list element as a candidate command name (with 1-based line/column positions). - These stored names are fed into the symbol/indexing and highlighting paths: - `server/src/tools/navigation.py` adds those names into the file symbol index so they participate in Go to Definition, Find References and rename flows. - `server/src/tools/semantic_tokens.py` highlights recognized stored names as functions (only when they are known/custom or standard). - Tests exercising stored proc extraction, goto-definition, references, and highlighting were added in `server/tests/python_tests/test_stored_procs.py`. - Warnings for undeclared block templates and addresses: - A new helper `unknown_def_names` in `server/src/tools/def_flow.py` walks literal command arguments and returns (kind, name, range) tuples for literal NX command arguments naming a `BLOCK_TEMPLATE` or `ADDRESS` that are not declared in the currently-loaded `.def` documents. It only checks kinds for which declarations are available in the provided `declared` mapping. - The language server now includes these as LSP diagnostics via `TclLanguageServer._def_diagnostics` in `server/src/lsp_tclserver.py`. Diagnostic entries use codes `unknown-block-template` and `unknown-address` and messages like "Block template 'name' is not declared in any loaded .def file". - When the set of loaded `.def` documents changes, `refresh_def_symbols` clears cached diagnostics and requests a client-side diagnostic refresh (via workspace diagnostic refresh support) to ensure warnings update when `.def` files are added/removed/changed. - The diagnostic logic only checks literal names. Dynamic/runtime-built names (for example `$var` or `"CYCLE_$x"`) are not analyzed or warned about. - Tests in `server/tests/python_tests/test_def_flow.py` were extended to assert these warnings and that they are suppressed when `.def` files are not loaded or when names are dynamic. Files changed (high level) - Added: `server/src/tools/stored_procs.py` (parsing of stored command names) - Modified: `server/src/tools/navigation.py` (index stored names), `server/src/tools/semantic_tokens.py` (highlight stored names), `server/src/tools/def_flow.py` (unknown_def_names), `server/src/lsp_tclserver.py` (produce diagnostics and request refresh), `CHANGELOG.md` updated - Tests: new `server/tests/python_tests/test_stored_procs.py`, extended `server/tests/python_tests/test_def_flow.py` Testing - Tests added or changed: - `server/tests/python_tests/test_stored_procs.py` (new): unit tests for stored command extraction; LSP goto-definition and references for stored names; highlighting expectations. - `server/tests/python_tests/test_def_flow.py` (updated): tests that unknown block template and address names produce warnings, that dynamic names do not, and that changing `.def` files invalidates cached diagnostics. - No test execution results were provided. Recommended checks for the reviewer 1. Run the Python/unit test suite (the repository's test runner) to confirm the new/updated tests pass. 2. Start the language server against a small workspace with PSC `.def` files and a Tcl file containing: - literal NX commands referencing existing and non-existing block templates/addresses to observe the new diagnostics and verify the diagnostic codes (`unknown-block-template`, `unknown-address`) and ranges. - COMMANDBLOCK `set` properties with braced lists containing procedure names (e.g. `CONF_CTRL_tool set auto_preselect_last_template {custom_header}`) and verify Go to Definition, Find References and highlighting work for those stored names. 3. Verify client capability handling: the server requests a diagnostics refresh only if the client's `workspace.diagnostics.refresh` capability is advertised; confirm behavior on clients that do and do not advertise this capability. Compatibility and notes - The unknown-name diagnostics are only produced when `.def` files are loaded into `self.def_documents`. If no `.def` files are loaded, no warnings are emitted (this is deliberate and covered by tests). - Only literal, statically-known names are checked; names built at runtime (variables, concatenations) are intentionally not warned about. - The server attempts to trigger an LSP workspace diagnostic refresh when `.def` documents change, but this request is conditional on client capability. Reviewers should confirm LSP clients used in development/tests advertise `workspace.diagnostics.refresh` if they expect immediate refresh behavior. If you want, I can provide a minimal repro workspace and exact commands to run the server and exercise these behaviors locally.