VS Code 扩展
nudo-vscode 扩展将 Nudo 的类型推断带入编辑器,提供悬停类型、补全、CodeLens 和内联提示。
定位(诚实): VS Code 是 Nudo 的旗舰 IDE 路径——@nudojs/lsp 上最完整的客户端面。门禁路径仍是 CLI / Agent:CI 里的 nudo check --json,以及给 agent 的 nudo.check / MCP 工具。IDE 是跑在同一服务器上的尽力而为观察面;它不替代门禁。其他编辑器:LSP 客户端矩阵。
安装
- 从最新 GitHub Release下载
nudo-vscode.vsix - VS Code → 扩展视图(
Cmd+Shift+X/Ctrl+Shift+X)→…菜单 → 从 VSIX 安装… - 选择刚下载的文件
或从命令行安装:
code --install-extension nudo-vscode.vsix
市场列表(VS Code Marketplace 与 Open VSX 上的 wmzy.nudo-vscode)是发布产物——搜得到时可直接从扩展视图安装,也可以从源码构建(pnpm --filter nudo-vscode run build && pnpm --filter nudo-vscode run package)。GitHub Release 上的 .vsix 才是真源。
激活
打开 JavaScript 文件时扩展会激活。它使用 @nudojs/lsp 包运行 Language Server Protocol(LSP)服务器,提供所有编辑器功能。
文件检测:语言服务器分析 .js、.ts 与 .mjs 文件。出厂默认 nudo.analysis.mode = "exports"(export / 侧车 / 指令);模式语义见与 TypeScript 共存。契约写在 *.nudo.js 侧车与源内 @nudo:contract;@nudo:case 是调试 / 可选 nudo test 子层。完整语法见指令参考。跨编辑器能力对比:LSP 客户端矩阵。
激活 vs 分析门:activationEvents(onLanguage:javascript / onLanguage:typescript)只负责启动客户端。缓冲区是否被分析由服务端 shouldAnalyzeFile 门决定(目标路径 + nudo.analysis.mode)。JSX/tsx 可激活扩展,但不是 Nudo 分析目标。
发布检查清单(维护者)
扩展打包与 Marketplace 发布步骤:贡献指南 — 发布。
功能
悬停类型
将鼠标悬停在表达式上可查看其推断类型。扩展通过 getTypeAtPosition 计算光标处的类型,并在悬停工具提示中显示。
活动 Case 装饰(LSP-G1)
通过 CodeLens 选中某个 @nudo:case 会高亮整个函数体加上该 case 注释行(不只是注释)。高亮会在每次文档编辑时按当前缓冲区重算,因此你边打字它边跟着走。服务端签名帮助也会投影真实的 paramTypes / 返回 shape。
与 tsserver 共存(LSP-G4)
命令面板 → Nudo: Apply coexistence settings (vs tsserver) 会在确认后(绝不静默)向工作区写入 javascript.validate.enable=false。完整配方:与 TypeScript 共存。
/**
* @nudo:case "test" (42)
*/
function double(x) {
return x * 2; // hover over x → number
}
补全
在表达式后输入 . 时会触发补全。LSP 会根据该位置的推断类型建议属性和方法。
/**
* @nudo:case "test" ("hello")
*/
function upper(s) {
return s. // completions: toUpperCase, toLowerCase, slice, etc.
}
CodeLens:观察选择器(contract + 各 case)
透镜行是一个观察选择器——contract 是与各 case 并排的一项,恰好一项激活(●):
- ● contract / hw|gen|imp —— 契约选项(handwritten / generated / implicit 档),默认激活。点击切回契约观察(
nudo.selectContract);已激活时点击幂等 - ⚡ persist contract / ↻ update contract —— 把调用点域固化进
*.nudo.js侧车 - ● / ○ case "name" —— 点击选择类型重放的激活 case(
nudo.selectCase);契约选项随之转○
悬停导出函数名时,hover 首行与 CodeLens 同源显示 ● contract / hw\|gen\|imp(A7)。VS Code 中当前激活 case 以不同样式高亮。这样可以在不修改文件的情况下查看不同输入下的类型。
内联提示
内联提示会在行内显示类型信息。在每个 case 的结果之后或相关位置,Nudo 会将推断的类型以灰色注释形式显示。
状态栏
右侧状态栏在扩展激活时显示 Nudo,悬停提示为 "Nudo Type Inference Engine"。
跳转到定义
跳转到函数、变量或类的定义。将光标放在标识符上并按 F12(或右键 -> Go to Definition)。
function process(data) {
return transform(data); // F12 on transform → jumps to its definition
}
查找引用
查找符号的所有使用——本文件及跨文件(其他已打开/已知文件中的导入方)。按 Shift+F12(或右键 -> Find All References)。
重命名符号
安全地重命名符号及其所有引用。按 F2(或右键 -> Rename Symbol)。Nudo 会验证新名称不会与现有符号冲突。
签名帮助
在函数调用的括号内输入时,Nudo 会显示参数提示。在输入 ( 或 , 时自动激活。
/**
* @nudo:case "test" (string(), number())
*/
function createUser(name, age) { ... }
createUser( // ← signature help shows: (name: string, age: number)
代码操作 / 快速修复
当 Nudo 报告诊断时,可使用快速修复建议。点击灯泡图标或按 Cmd+. / Ctrl+. 查看可用修复:
- 移除不可达代码 ——针对
return/throw之后的代码 - 给调用点 / 侧车形状补字段 ——在调用点与(若存在)
*.nudo.js形状里插入field: undefined - 放宽侧车契约 ——对 refine / domain 违例,把手写侧车上的数值 pred(
number().gt(0)→number())改写掉
语义标记
Nudo 根据推断类型提供语法高亮。函数、变量和死代码的高亮与标准语法着色不同。
命令:"Nudo: Select Case"
Nudo: Select Case(nudo.selectCase)就是 case CodeLens 背后的命令:透镜把文件、函数名与 case 下标一并传进来,扩展据此切换该函数的激活 case(并立刻在本地高亮)。
同一条命令也列在命令面板(Cmd+Shift+P / Ctrl+Shift+P)里,但面板执行不传任何参数——裸命令无从得知要选哪个函数、哪个 case。扩展会先用当前编辑器兜住文件,然后如实报告缺失的入参(Nudo: select case needs a function name (use the CodeLens))而不是猜:既不发请求,也不写本地高亮。因此切换 case 是 CodeLens 的动作。
另外两点:
- 该命令的处理器在语言服务器连上时才挂上(id 由客户端按服务端广告注册),所以面板项要等客户端就绪后才可点。
- 服务端拒绝一次 case 切换时,扩展会给出错误提示并回滚乐观的本地高亮——被拒的切换不会留下错误的高亮。
命令:Interface / Draft / Persist
| 面板标题 | 命令 | 行为 |
|---|---|---|
| Nudo: Show Contract | nudo.contract | 在 Nudo 输出通道打印分层(同 nudo contract) |
| Nudo: Select Contract (back to contract observation) | nudo.selectContract | 把函数切回契约观测(取消其激活的 case),并清掉本地 case 高亮 |
| Nudo: Trace Observation (entry@ / call@) | nudo.trace | 在 Nudo 输出通道打印该函数的逐用例观测(entry@ / call@)(同 nudo trace) |
| Nudo: Draft Contract (code-first) | nudo.contract.draft | Output 预览草稿;可选写入 *.nudo.draft.js / *.nudo.draft.ts(无项目根时写盘 fail-closed) |
| Nudo: Persist Contract (@generated) | nudo.contract.emit | 先 dry-run(dryRun: true,不写盘)→ Output 预览 → 确认 → 真实写入侧车。CodeLens persist/update 共用同一确认流程;从面板走时用 QuickPick 交互选函数,三步门禁不变 |
非手写导出上的 CodeLens 含 ⚡ draft contract——与 CLI --draft、agent nudo.contract.draft 同源。persist/update CodeLens 在确认对话框接受前绝不会写盘。
从命令面板触发时,这些命令作用于当前活动编辑器(不需要传文件参数):Show Contract 与 Draft Contract 是文件粒度的,而 Persist Contract (@generated) 会用 QuickPick 让你从该文件可固化的导出里选一个函数——与服务端 ⚡ persist contract / ↻ update contract CodeLens 给的是同一批函数。文件里没有可固化函数时,命令会如实报告没有(没有自由文本兜底)。两条路径的门禁完全一致:dry-run 绝不写盘,dry-run 失败时根本不提供写盘动作,侧车只在你确认之后才写。
资源占用
Nudo 语言服务器的设计目标是在你的其他工具旁保持轻量:
- 内存有界。 请求之间,服务器只持有轻量簿记 —— 文件路径、函数名和少量每文件记录 —— 你一关闭文件,它的分析结果即被丢弃。服务器绝不在内存中保留解析后的语法树,其定位是与 TypeScript 自身的语言功能并排运行,而非取而代之。
- 打开即出诊断。 打开文件就会立即分析;无需先编辑一次才能看到 Nudo 的诊断。
- 陈旧诊断在重开时消除。 你关闭的文件不会因其依赖发生变化而被重新分析 —— 它的诊断保持原样,直到你再次打开该文件时刷新。从磁盘删除的文件会自动清空诊断。
总结
| 功能 | 描述 |
|---|---|
| 悬停 | Abs / intension;导出函数名显示 ● contract / hw|gen|imp |
| 补全 | 在 . 后触发;属性和方法建议 |
| CodeLens | contract 档 + persist/update;case 副层 |
| 内联提示 | Abs 参数/返回;implicit 导出标 derived |
| 跳转到定义 | 跳转到符号定义(F12) |
| 查找引用 | 查找符号的所有使用(Shift+F12) |
| 重命名符号 | 重命名符号及其所有引用(F2) |
| 签名帮助 | 函数调用内的参数提示 |
| 代码操作 | 诊断的快速修复 |
| 语义标记 | 类型感知高亮 + contract 档 modifier |
| 状态栏 | 激活时显示 "Nudo" 指示器 |
| 命令 | nudo.selectCase / nudo.contract / nudo.contract.emit |
参见:LSP 客户端矩阵(其他编辑器)。