OpenCML-Ext

VSCode extension for the Camel language, centered on two things:

• GraphIR visualization — an interactive graph view of your program's Graph IR
• Debugging — launch/attach debugging of Camel scripts via camel-db

Language features (completion, navigation, rename, semantic highlighting, diagnostics and formatting) are served by the standardized Camel language server (camel-ls).

Requirements

A Camel toolchain build (camel.exe, camel-ls.exe, camel-format.exe, camel-db.exe). Configure its location with opencmlLanguageServer.camelPath (point it at the camel executable or its bin directory); the other tools are auto-detected next to it. With the default camel setting, CAMEL_HOME/bin and then PATH are searched.

For a local Camel checkout, add this to VS Code settings:

{
    "opencmlLanguageServer.camelPath": "D:\\Projects\\Camel\\out\\latest\\bin\\camel.exe"
}

Use the compiled executable or its bin directory, not the source repository root. Toolchain path changes restart the language server automatically; Camel: Restart Language Server also reloads it after rebuilding Camel. An independent server can be selected with opencmlLanguageServer.camelLsPath.

CML semantic highlighting is enabled by default. It uses the runtime's symbol resolution, so function values such as [inc] are highlighted as functions even without a call. An explicit user setting disabling semantic highlighting still takes precedence. On extension 1.2.0, enable [cml].editor.semanticHighlighting.enabled manually and reload the window after changing the toolchain path.

Features

GraphIR visualization

Open a .cml file and use the graph button in the editor title, the editor context menu, or Ctrl+Shift+P → Camel: Visualize GraphIR. The panel opens beside the source:

• 连线类型: solid ordinary inputs, dashed context inputs, and dotted control dependencies, with directional arrows. Port indices appear on connected edges when hovering a node; type explanations remain in display options.

• 层级浏览 / 平铺视图: hierarchical browsing opens with child-graph cards; double-click a FUNC node to enter its uniquely matched child graph, or use the card when no unambiguous reference exists; click breadcrumbs to return. Each level remembers its viewport and inspector selection until recompilation. Cross-level connections remain visible as boundary inputs/outputs.

• 搜索: focus the graph and press Ctrl/Cmd+F (or click Search in the status bar) to search the entire module by node name, type or ID. Enter/Shift+Enter cycles matches across levels; use “返回搜索前位置” to restore your original view.

• 锁定高亮: Shift-click a node to retain its neighborhood while moving the pointer. Status-bar controls select upstream/downstream/both and one/two hops; Escape unlocks.

• 连线筛选 in display options fades ordinary/context/control edges independently, or hides unchecked types entirely. Node positions stay fixed and the status bar indicates active filtering.

• 模块函数: modules with an explicit entry show the entry flow first; other retained function graphs remain accessible in the expandable list beside breadcrumbs. Double-click FUNC or DATA function-value nodes to navigate to unambiguous local, cross-level or recursive targets, and use Back to return to the caller.

• 图排列 in display options switches between vertical module-level graphs (default, preserving the original layout inside functions) and the original Graphviz layout. Vertical mode fits the width; use Fit to see the full graph.

• 图 / 文本 switches between the interactive graph and the same raw GIR DOT output

• 复制 GIR copies the displayed GIR; 在编辑器打开 opens an editable document that can be saved

• current unsaved editor text is used; 刷新 recompiles it, and saving refreshes automatically

• compilation failures are displayed in the panel instead of leaving a blank or stale graph

• pan / zoom / node selection with attribute inspection

• pass picker: std::rgir (compact), std::agir (role-annotated), std::gir (styled)

• per-pass compile snapshots: while a debug session is active, a stage dropdown lists the GIR captured before and after each compiler pass (served by camel-db); node breakpoints, pause highlight and jump-to-source work in snapshot views too

• auto-refresh on save

• double-click a node to set a node breakpoint (used by the debugger)

• nested subgraphs (functions/closures) rendered as clusters; layout computed by Graphviz

Debugging

Full debug adapter (camel debug type). F5 on a .cml file launches camel-db and streams execution to the Debug Console. Supports launch (auto-spawns camel-db) and attach (to a running camel-db --serve <port>).

Capabilities:

• run / continue / restart / stop, natural termination when the script finishes
• line breakpoints: verified against GIR node source spans (unverified ones explain why and activate once a node maps to the line)
• node breakpoints: double-click a node in the GraphIR panel (synced by node origin — the same identity the debugger reports)
• stepping: step over (next node in the current graph) and step in (next node anywhere), mapped to camel-db node-level single-step
• stack frames mapped to source locations; the paused node is highlighted in the GraphIR panel
• pause detection with reason (breakpoint / step)

These require a Camel build with node-level debugging support (origin spans in rgir/gir-json, the always-on GIR node hook, and the /api/step endpoint — delivered on the Camel side in v0.1.23+).

Language features

• Scope-aware completion, member completion and signature help
• Hover types and documentation, go to definition, references and symbol search
• Rename with runtime safety checks, document highlights and semantic tokens
• Library editing does not require main: the entry-only missing-main diagnostic is omitted in the editor. Running a file still checks entry requirements.
• Diagnostics via camel check-equivalent pipeline (syntax + semantic errors with ranges and suggestions)
• Document formatting via camel-format
• Camel: Run Camel streams program output to an output channel

Runtime status and diagnostic advice

When a Camel source editor is active, the status bar shows Camel · LSP, 备用模式, or the current startup/failure state. Click it to inspect the runtime, restart the server or configure its path.

Camel: Runtime Info and Health Check writes the active executable paths, runtime/server versions, tool availability and Camel search-path environment to the Camel output channel. It also reports startup failures and mixed-installation paths.

Compiler suggestions appear below their diagnostic messages. Use the lightbulb's 查看 Camel 修复建议 action to open the full explanation beside the source. These are runtime-provided suggestions, not automatic source edits.

Run Camel saves the active file and other modified, open .cml/.psl buffers in the same workspace folder before execution, so open dependencies use their latest contents. It logs the files saved and cancels on a save failure. An untitled file must be saved first. A second run is ignored while the current run is still active.

Settings

Architecture

VSCode
├─ Language Client ──stdio──► camel-ls.exe        (standardized LSP, lives in Camel repo)
├─ Debug Adapter ────DAP────► this extension ──HTTP──► camel-db.exe (parent + worker)
└─ GraphIR Webview ◄─postMessage─ extension ──CLI/HTTP──► Camel (rgir passes / gir-json)

• Language server: camel-ls is spawned directly when available; otherwise the bundled Node server shells out to the Camel CLI (fallback: diagnostics and formatting only; no placeholder completion or hover).
• Debug adapter: an inline Node adapter translates DAP to the camel-db HTTP API (run/continue/step/restart/terminate, pause polling, log streaming). Line breakpoints and stack frames are resolved through gir-json source spans; panel breakpoints and debugger hits share the GIR node origin as their common identity.

Development

npm install
npm run build        # client + server + webview
npm run pub          # build + package vsix into rollup/
node scripts/e2e/run.mjs           # E2E (needs CAMEL_EXE_PATH or a local Camel build)
E2E_MODE=fallback node scripts/e2e/run.mjs   # fallback-path E2E
E2E_MODE=experience node scripts/e2e/run.mjs # runtime status, advice, save-before-run
E2E_MODE=gir node scripts/e2e/run.mjs        # real webview UI; needs playwright or PLAYWRIGHT_PATH
E2E_MODE=lsp node scripts/e2e/run.mjs        # language features + inc tokens + restart
# Set CAMEL_HOME (installation root) or CAMEL_LS_PATH for the native server test.
# Set CAMEL_EXE_PATH to include real compiler/formatter fallback tests.
npm run test:lsp

E2E launches a real VSCode instance with a throwaway workspace and exercises hover, diagnostics, formatting, the GraphIR panel and a full debug session lifecycle.

GIR 源码跟随与函数目录

• 在 CML 编辑器按 Ctrl+K Ctrl+G（macOS：Cmd+K Cmd+G），或点击编辑器右上角图标，复用 GIR 面板显示当前文件。
• 面板右上角默认“跟随”：切换 CML 源码时自动更新。点击变为“已固定”，可保持原图对照其他文件；再次点击恢复跟随。显式打开 GIR 命令始终显示当前文件。
• 每个文件、每种 GIR 格式分别记住层级、返回历史和缩放位置，当前面板最多保留 30 组。关闭面板后清除浏览位置；跟随开关保存在工作区。
• 自动刷新控制保存后的更新；跟随控制文件切换。图内跳转源码不会触发换图。
• 层级模式的“函数目录”始终可见，包含 main 等模块顶层函数，并标出入口和当前所在函数。目录表示保留的函数图，不代表调用顺序。