Recognize derived .def names and show .def previews on completion resolve #48

Merged

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

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

Christoph commented

2026-09-25 06:17:05 +00:00

(Migrated from git.cbsk-tech.de)

Summary

Before: hover, Go to Definition and references for .def block templates and addresses only worked when the source token was a direct NX command argument (e.g. MOM_do_template steady_rest).
After: the language server also recognizes names that can be proven to flow to those NX command arguments through local variables (set, lappend, list, foreach) or through proc parameters (including nested wrapper procs). Completion items for .def symbols can now be resolved to include the same preview content as hover.

Key behavior changes

Hover / Go to Definition / References now also succeed when the token at the cursor is a literal that the analyzer can show flows into a .def argument (via variables or proc wrappers). These derived names are resolved for hover/definition/references only; they are not renamed (the code explicitly avoids treating derived occurrences as rename targets).
Completion items emitted for .def block templates and addresses include data: {"def": [kind, name]} and the server advertises resolve_provider=True. Selecting a completion item triggers textDocument/completionItem/resolve which populates the item documentation with the same Markdown preview used by hover.
A new analysis module, server/src/tools/def_flow.py, implements the flow solver, proc parameter flow extraction, and wrapper-table construction. The LSP server caches a def_wrapper_table() built from navigation indexes and uses it when resolving derived symbols.
Navigation/indexing was extended to collect per-proc def-flow summaries that feed the wrapper-table builder; tools/navigation.py re-exports the relevant helpers.
A CI workflow file was added at .gitea/workflows/tests.yml that runs the Python language-server tests and Node extension tests on push/pull_request to main.

Implementation notes (important for review)

The static analysis is implemented in def_flow.py:
- It extracts flow facts from commands (command_flow_facts), solves variable propagation, and computes where proc parameters end up (proc_def_flows).
- build_wrapper_table resolves nested wrapper calls so a proc parameter can be known to carry .def names of a given kind.
- derived_def_symbol(tree, position, table) returns (kinds, name, range) for a literal at position if the literal can be shown to reach a .def argument given table.
LSP integration:
- server/src/lsp_server.py adds COMPLETION_ITEM_RESOLVE handling and uses def_hover_markdown(...) to create the preview documentation when the completion item's data contains a .def target.
- _tcl_def_symbol in lsp_server.py uses the navigation context first; if none, it falls back to derived_def_symbol using the server's def_wrapper_table() to decide whether the token is a derived .def symbol.
- Completion items now include data={"def": [kind, name]} so resolve can locate the target.
The change keeps a conservative approach: only names provably reaching a .def argument are considered; many commands are treated as non-forwarding and the analysis omits renaming derived occurrences.

Tests

The patch updates test expectations / formatting (commit summary: test(completion_context): update test expectations and reflow formatting) and adds a CI workflow to run tests, but no test execution results are included with this change.

No test execution results were provided.

Recommended checks for reviewers

Run the server Python tests: from repository root run python -m pytest tests/python_tests -q (the same command the new workflow runs under server/ with PYTHONPATH=libs).
In an editor session, exercise hover/Go to Definition/References on tokens that are (a) direct NX args and (b) literals that flow via set, lappend, list, foreach, or through wrapper procs to ensure derived cases are resolved as expected.
Verify completion items for block templates and addresses show the preview on selection (completion resolve) and that rename continues to not touch derived occurrences.

Compatibility and risk notes

Derived occurrences are used only for hover/definition/references; the rename logic is unchanged and will not rename derived occurrences. This behavior is explicit in the implementation.
The flow analysis runs against the server's in-memory parse trees and uses cached wrapper tables keyed by index generation. Review for performance or cache-invalidation concerns if large indexes or frequent updates are expected.

Files and artifacts of interest

New analysis: server/src/tools/def_flow.py
LSP changes: server/src/lsp_server.py, server/src/lsp_tclserver.py
Navigation/index changes: server/src/tools/navigation.py
CI workflow: .gitea/workflows/tests.yml

If you'd like, I can point to specific diffs or walk through the derived_def_symbol logic step-by-step during review.

This change extends .def symbol resolution and completion previews to names that reach NX commands indirectly (via variables or proc parameters), and adds a completion-item resolve handler to show the same .def preview as hover. Summary - Before: hover, Go to Definition and references for .def block templates and addresses only worked when the source token was a direct NX command argument (e.g. `MOM_do_template steady_rest`). - After: the language server also recognizes names that can be proven to flow to those NX command arguments through local variables (`set`, `lappend`, `list`, `foreach`) or through proc parameters (including nested wrapper procs). Completion items for .def symbols can now be resolved to include the same preview content as hover. Key behavior changes - Hover / Go to Definition / References now also succeed when the token at the cursor is a literal that the analyzer can show flows into a .def argument (via variables or proc wrappers). These derived names are resolved for hover/definition/references only; they are not renamed (the code explicitly avoids treating derived occurrences as rename targets). - Completion items emitted for .def block templates and addresses include `data: {"def": [kind, name]}` and the server advertises `resolve_provider=True`. Selecting a completion item triggers `textDocument/completionItem/resolve` which populates the item `documentation` with the same Markdown preview used by hover. - A new analysis module, `server/src/tools/def_flow.py`, implements the flow solver, proc parameter flow extraction, and wrapper-table construction. The LSP server caches a `def_wrapper_table()` built from navigation indexes and uses it when resolving derived symbols. - Navigation/indexing was extended to collect per-proc def-flow summaries that feed the wrapper-table builder; `tools/navigation.py` re-exports the relevant helpers. - A CI workflow file was added at `.gitea/workflows/tests.yml` that runs the Python language-server tests and Node extension tests on push/pull_request to `main`. Implementation notes (important for review) - The static analysis is implemented in `def_flow.py`: - It extracts flow facts from commands (`command_flow_facts`), solves variable propagation, and computes where proc parameters end up (`proc_def_flows`). - `build_wrapper_table` resolves nested wrapper calls so a proc parameter can be known to carry `.def` names of a given kind. - `derived_def_symbol(tree, position, table)` returns `(kinds, name, range)` for a literal at `position` if the literal can be shown to reach a `.def` argument given `table`. - LSP integration: - `server/src/lsp_server.py` adds `COMPLETION_ITEM_RESOLVE` handling and uses `def_hover_markdown(...)` to create the preview documentation when the completion item's `data` contains a `.def` target. - `_tcl_def_symbol` in `lsp_server.py` uses the navigation context first; if none, it falls back to `derived_def_symbol` using the server's `def_wrapper_table()` to decide whether the token is a derived .def symbol. - Completion items now include `data={"def": [kind, name]}` so resolve can locate the target. - The change keeps a conservative approach: only names provably reaching a .def argument are considered; many commands are treated as non-forwarding and the analysis omits renaming derived occurrences. Tests - The patch updates test expectations / formatting (commit summary: `test(completion_context): update test expectations and reflow formatting`) and adds a CI workflow to run tests, but no test execution results are included with this change. No test execution results were provided. Recommended checks for reviewers 1. Run the server Python tests: from repository root run `python -m pytest tests/python_tests -q` (the same command the new workflow runs under `server/` with `PYTHONPATH=libs`). 2. In an editor session, exercise hover/Go to Definition/References on tokens that are (a) direct NX args and (b) literals that flow via `set`, `lappend`, `list`, `foreach`, or through wrapper procs to ensure derived cases are resolved as expected. 3. Verify completion items for block templates and addresses show the preview on selection (completion resolve) and that rename continues to not touch derived occurrences. Compatibility and risk notes - Derived occurrences are used only for hover/definition/references; the rename logic is unchanged and will not rename derived occurrences. This behavior is explicit in the implementation. - The flow analysis runs against the server's in-memory parse trees and uses cached wrapper tables keyed by index generation. Review for performance or cache-invalidation concerns if large indexes or frequent updates are expected. Files and artifacts of interest - New analysis: `server/src/tools/def_flow.py` - LSP changes: `server/src/lsp_server.py`, `server/src/lsp_tclserver.py` - Navigation/index changes: `server/src/tools/navigation.py` - CI workflow: `.gitea/workflows/tests.yml` If you'd like, I can point to specific diffs or walk through the `derived_def_symbol` logic step-by-step during review.