概念分层
Nudo 的目标是在源码中看到变量接近运行时的样子。该结果可分层获得,只需学习当前用到的概念。
术语约定:观察层即 Day 0,契约层即 Day 1(保留 Day-N 别名,便于熟悉运维生命周期说法的读者对照)。
你需要哪一层?
| 你想要 | 层 | 从这开始 |
|---|---|---|
| 在签名 / inlay 中看到接近运行时的值 | 观察层(Day 0) | npx nudojs check / IDE hover |
| 义务——能报告违例的契约 | 契约层(Day 1) | *.nudo.js 侧车 + nudo check |
表示本身——term、pred、--abs | 进阶 | Abs(shape × term × pred × conf) |
经验法则:只需读接近运行时的变量,停在观察层。需要强制条件,再加契约层。只有在调试推断或基于内核做工具时,才打开进阶层。
观察层(Day 0)— 零概念
写普通 JavaScript,跑两条观察命令:
npx nudojs check ./src/app.js # 签名 + L2 入口 throws
npx nudojs test ./src/app.js # 全部推断用例
check 成功时也打印 signatures。无约束入口参数显示为 any。test 打印合成 call@ / entry@ 用例——这就是调用点观察面。无注解、无配置。
用装了 Nudo 扩展的 VS Code 打开同一文件,可获得 hover 与 inlay。
默认分析模式:
nudo.analysis.mode出厂默认"exports"(含 export / 侧车 / 指令的文件进 IDE 分析)。完整门禁语义与各模式何时用:与 TypeScript 共存。CLI 对指定路径的check/test仍会分析目标文件。
观察层要点: 从 check 签名与 test 用例读接近运行时的值。无约束入口参数上的 any 是诚实的——它的反面 unknown 意味着推导失败(见 Abs —— any vs unknown)。
契约层(Day 1)— 侧车义务
需要更强的义务(可在任意流程中检查的显式契约)时,在源码旁添加侧车:
// math.js
export function add2(x) {
return x + 2;
}
// math.nudo.js — function binding must be fn({ params }, returns?)
import { number, fn } from "@nudojs/core";
export const add2 = fn({ x: number().gt(0) }, number());
npx nudojs contract --draft ./src/math.js # 可选的代码优先草稿
npx nudojs check ./src/math.js
侧车函数绑定必须是一等 fn({ … }, …) 契约。裸的 number().gt(0) 是值级模板(如共享 *.nudo.js 中的 export const positive = number().gt(0))——经 @nudo:contract 或作为 fn 的参数槽使用,不可作为函数导出契约。非 fn 的函数侧车绑定会被拒绝(nudo:contract-load)。
显式契约来自:
- 侧车(
*.nudo.js)/@nudo:contract - 分析器观察到的调用点事实(定义域证据)
无显式契约时,契约退化为 JS 运行时边界:入口参数为 any,导出函数不得携带未消化的 may-throw(L2)。Nudo 不会从 body AST 扫描发明必填槽。
契约层要点: 侧车即契约产品。nudo check 强制 L1(显式契约)与 L2(入口 may-throw)。@nudo:case 仅调试 / nudo test 用——不是契约。
进阶 — Abs
内部类型是 Abs(shape × term × pred × conf):类型即可计算值。nudo check --abs 显示每函数的代数面(shape + conf);--generalize 追加符号 term/pred α。日常很少需要。
需要进阶层时:
- 签名看起来不对,要 intensional 面而非展示字符串
- 在代数里推理约束(
x>0⇒x+1>1) - 基于
@nudojs/core做工具
深入:Abs —— 类型系统 · 抽象解释。