Cylc Flow Linker
A VSCode extension that converts references to Cylc configuration items into navigable links.
Features
1. Jinja2 Import Links
Converts Jinja2 import/include statements to links pointing to the imported files:
{% import "include/runtime.cylc" as runtime %}
{%- import "include/meta.cylc" -%}
{% include "include/parameters.cylc" %}
Cylc's native %include "include/runtime.cylc" lines are linked in the same way.
Clicking on the file path will open the corresponding file in your repository.
2. App Key Links
Converts --app-key= references to links pointing to the respective rose-app.conf:
[[my_task]]
script = rose task-run --app-key=myapp -vv
Clicking on myapp will open app/myapp/rose-app.conf.
3. Optional Config Key Links
Converts -O/--opt-conf-key and ROSE_APP_OPT_CONF_KEYS environment variables to links pointing to optional config files:
[[my_task]]
script = rose task-run --app-key=myapp --opt-conf-key=dump -vv
[[[environment]]]
ROSE_APP_OPT_CONF_KEYS = first
Clicking on dump or first will open the corresponding optional config file at:
app/myapp/opt/rose-app-dump.conf
app/myapp/opt/rose-app-first.conf
4. Graph Task Links
Links task names in the [scheduling] [[dependencies]] or [[graph]] sections to matching [[task_name]] definitions in [runtime]. Definitions in directly imported Jinja files are also supported. If a runtime task has no --app-key and a same-named app exists, its [[task_name]] header links to app/<task_name>/rose-app.conf; graph links still go to the runtime definition.
5. Jinja2 Python Imports
Links Python modules imported from lib/python ({% import mymodule %}, {% from "mymodule" import myfunc %}) to the module file. For from imports, each imported name links to its def, class or assignment line.
How It Works
Hover over parameter names in task references such as garden_<my_param> to see
their [task parameters] definitions and, when configured, their [[templates]]
entries. Definitions are read from the current document, without expanding values.
Hover over a variable in a Jinja expression or statement to see its value from
rose-suite.conf under [template variables], or an earlier {% set NAME = value %}
in the current document. For example, tooltips show FOO = 45 or
BAR = [1, 1, 3, 5]. Set expressions take precedence over Rose values.
Values are displayed as written, without evaluating Jinja or Python; template
scope, conditional execution, and assignments in included files are not resolved.
The extension:
- Scans each line of
.cylc files for recognized patterns
- Validates that target files exist before creating links
- For optional config keys, automatically detects the app context by searching backwards for the most recent
--app-key= reference
- Converts valid references into clickable links using VSCode's document link provider
Installation
From the VS Code Marketplace
(Coming soon)
Manual Installation (Development)
Clone this repository:
git clone https://github.com/wxtim/cylc-flow-linker.git
cd cylc-flow-linker
Install dependencies:
npm install
Build the extension:
npm run build
Open the repository folder in VS Code and press F5 to launch the Extension Development Host with the example/ folder and example/example-flow.cylc open. The launch configuration builds the extension before starting it.
Usage
- Open a Cylc workflow repository in VS Code. To try the included demo, open the
example/ folder.
- Open
example/example-flow.cylc for the demo, or any .cylc file in your workflow
- Hover over or click on linked items:
- File paths in Jinja2 imports (e.g.,
"include/runtime.cylc")
- App names after
--app-key= (e.g., myapp)
- Config keys after
-O, --opt-conf-key, or in ROSE_APP_OPT_CONF_KEYS (e.g., dump, first)
The extension will navigate to the corresponding file when clicked.
Supported Patterns
Jinja2 Imports
{% import "path/file.cylc" as var %}
{%- import "path/file.cylc" -%}
{% include "path/file.cylc" %}
Jinja2 Python Imports
{% import module %} / {% import "module" %}
{% from module import func, other as alias %}
Cylc Includes
%include "path/file.cylc" (quotes optional; resolved relative to the including file, then the workspace root)
App Key References
Optional Config Key References
-O=key_name or -O key_name
--opt-conf-key=key_name or --opt-conf-key key_name
ROSE_APP_OPT_CONF_KEYS = key1 key2 key3 (space-separated)
ROSE_APP_OPT_CONF_KEYS=key_name (environment variable assignment)
Graph Task References
- Task names in
[scheduling] [[dependencies]] or [[graph]] sections that have a matching runtime definition
- Runtime task headers without
--app-key link to a same-named existing app/<task_name>/rose-app.conf
License
MIT