指令系统
指令是控制 Nudo 如何分析代码的结构化注释。它们使用 @nudo: 命名空间以避免与 JSDoc 和其他工具冲突。将指令放在函数上方的块注释中。
契约产品主路径在侧车文件——*.nudo.js 模块自动绑定源码同名导出,@nudo:contract 是其源码内形态。见 @nudo:contract 与 nudo contract 命令。
指令语法
所有指令都在 @nudo: 命名空间下,以结构化注释的形式编写:
/**
* @nudo:case "name" (arg1, arg2)
* @nudo:mock fetch = ...
*/
function myFunction(a, b) {
// ...
}
多个指令可以出现在同一个注释块中。解析器会在引擎运行前提取它们。
函数级指令(@nudo:case、@nudo:mock、@nudo:pure、@nudo:skip、@nudo:sample)也接受紧贴函数上方的单行 // @nudo:… 注释:
// @nudo:mock fetch = (url) => ({ ok: true, json: () => ({ id: 1 }) })
// @nudo:case "user" (1)
async function fetchUser(id) {
const res = await fetch(`/api/users/${id}`);
return res.json();
}
两种形态解析完全一致——尤其是 mock 表达式的单行规则对两者都适用(见 @nudo:mock)。当 // 前缀的指令可能被误读为被注释掉的代码时,优先使用块注释形态。
@nudo:case — 调试见证
case 是 debug 见证:Nudo 为场景执行而使用的具体输入。它不是契约产品——契约住在 *.nudo.js 侧车 / @nudo:contract(见 @nudo:contract)。@nudo:case 仍支持 nudo test 断言与 LSP 场景切换。case 实参使用具体值或约束构建器。
提供具名执行用例。每个用例定义具体输入,供 Nudo 调试场景执行函数时使用。
语法
@nudo:case "name" (arg1, arg2, ...)
@nudo:case "name" (arg1, arg2) => expectedType
- name — 用例的字符串标识符(如
"double digits")。 - args — 逗号分隔的具体参数(
5、"hello"、{…})。 - expected(可选)—
=>之后的类型表达式(具体字面量或约束构建器,与 args 同一文法),由nudo test对推断结果断言。
示例
/**
* @nudo:case "positive numbers" (5, 3)
* @nudo:case "negative result" (1, 10)
*/
function subtract(a, b) {
return a - b;
}
/**
* @nudo:case "strings" ("hello")
* @nudo:case "numbers" (42)
* @nudo:case "array" ([1, 2, 3])
*/
function process(x) {
if (typeof x === "string") return x.length;
if (typeof x === "number") return x * 2;
return x.length;
}
带有预期结果:
/**
* @nudo:case "basic" ("abc") => number()
* @nudo:case "empty" ("") => lit(0)
*/
function len(s) {
return s.length;
}
@nudo:mock — Mock 外部依赖
在求值期间将外部依赖替换为 mock 实现——fetch、文件系统 API 或其他 Nudo 无法直接执行的代码。完整语法(五种形式)、单行规则、evaluator 注意事项与可运行示例:模拟外部依赖。
@nudo:pure — 标记纯函数
将函数标记为纯函数。Abs fn 值携带纯标记,求值器按实参 Abs 记忆化调用结果(同实参命中缓存)。仅用于无副作用函数;加不加指令分析结果都正确。
语法
@nudo:pure
示例
/**
* @nudo:pure
* @nudo:case "add" (number(), number())
*/
function add(a, b) {
return a + b;
}
@nudo:skip — 跳过求值
跳过函数体的抽象解释:引擎不求值它,所以被跳过的函数不会产生引擎债(nudo:unknown-inference)噪声。没有返回类型表达式时,函数报告为 skipped (no return type declared),且 nudo check 把它的返回值打印为 any(无约束——不是保留给推导失败的 unknown);在指令后添加约束构造器表达式即可声明返回类型。
语法
@nudo:skip
@nudo:skip => returnsExpr
@nudo:skip (returnsExpr)
- returnsExpr(可选)— 用作返回类型的类型值表达式。须写成
=> expr或整段(…)包裹;@nudo:skip后的裸散文会被忽略(不是类型)。
范围
- 不求值函数体。 声明的类型(或
any)成为签名返回值;被跳过的函数体不参与入口 may-throw(L2)求值。 - 形参义务保留。
@nudo:contract前置条件仍会门禁调用点,形参展示仍来自手写契约——对带@nudo:contract x positive的被跳过函数needsPositive,nudo check报告needsPositive(x: number) => any。 - 返回契约仍被检查。
@nudo:contract return positive之下的@nudo:skip => lit(0)会报告nudo:constraint-violated。
示例
/**
* @nudo:skip
*/
function heavyComputation(data) {
// Complex algorithm Nudo should not evaluate
return processData(data);
}
推断输出(nudo test):
=== heavyComputation ===
skipped (no return type declared)
/**
* @nudo:skip => number()
*/
function unannotatedHeavy(x) {
// Explicit return type via the directive
return expensiveOp(x);
}
推断输出(nudo test):
=== unannotatedHeavy ===
skipped (declared): number
@nudo:sample — 循环采样(保留,无效果)
@nudo:sample 已被解析但没有消费者——analyzer 会丢弃它(service/src/analyzer-orchestrate-uncached.ts 中的 void sampleDirective)。它不会改变循环求值:循环本就通过有界展开(DEFAULT_MAX_LOOP_ITERS = 8)终止,不存在可切换的不动点阶段。该指令为源码兼容而被接受,但对输出无任何影响;不要依赖它在精度与性能之间权衡。
语法
@nudo:sample N
- N — 正整数。分析时被忽略。
@nudo:contract — 源内契约
把契约挂到参数或返回值。约束以 Pred 进入 Abs,参与代数(x>0 ⇒ x+1>1),不只是调用点挡板。
产品名:contract(侧车 *.nudo.js / @nudo:contract)。
主路径:侧车自动绑定
推荐形态把契约写在源码旁的侧车文件里:<file>.nudo.js(对应 .js/.mjs)或 <file>.nudo.ts(对应 .ts/.mts)。每个 export const <name> = fn({ ... }, ...) 自动绑定源码中同名本地 named export——源码零注解:
// calc.js
export function addTax(x) {
return x + 1;
}
export function greet(name) {
return name;
}
// std.nudo.js — 共享约束模板
import { number } from "@nudojs/core";
export const positive = number().gt(0);
// calc.nudo.js — 侧车契约
import { fn, lit, number, string, union } from "@nudojs/core";
import { positive } from "./std.nudo.js";
export const addTax = fn({ x: positive.shift(1) }, number());
export const greet = fn({ name: union(lit("ada"), lit("bob")) }, string());
$ nudo contract calc.js
calc.js
addTax [handwritten] (x: number().gt(1)) → number()
greet [handwritten] (name: union(lit("ada"), lit("bob"))) → string()
侧车是真实 JS 模块:可从 @nudojs/core 引入构建器、经相对 import 从其它侧车引入约束。加载失败、import 成环、不识别导出形态都是 error(nudo:contract-load、nudo:contract-cycle),不再静默回落。
构建器(@nudojs/core,裸包名同样注入):
| 构建器 | 含义 | 示例 |
|---|---|---|
number() / string() / boolean() | 原始类型域 | number() |
shape({ id: number() }) | 对象形状(字段递归) | shape({ id: number().gt(0) }) |
array(c) | 数组元素约束 | array(string()) |
lit(v) | 字面量域 | lit(42) / lit("ada") / lit(true) |
union(...cs) | 域之并 | union(lit(42), lit("a")) |
fn(params, returns?, { throws? }) | 一等函数契约 | fn({ x: number() }, number()) |
.gt(n) .ge(n) .lt(n) .le(n) .int() | 数值界(链式) | number().gt(0).int() |
.min(n) .max(n) | 长度界——length(s) pred(字符串/数组) | string().min(1) |
.length(n) | 长度等值界(length(s) = n) | string().length(3) |
.shift(n) | 每个常数界整体 +n 平移 | positive.shift(1) |
and(...cs) | 标量合取(顶层函数,不是链式方法) | and(positive, number().lt(10)) |
partial(c) / pick(c, keys) / omit(c, keys) | 形状工具 | partial(user) |
lazy(() => c) | 自引用模板(仅侧车 —— 指令文法不支持箭头函数) | shape({ object: lazy(() => node).optional() }) |
shift 只对数值标量链合法(每个界的右端是字面量),否则 throw。partial/pick/omit 接受 shape(...) 约束。
自动绑定规则:
- 只绑定源码文件同名本地 named export(
export function/export const)。re-export、export default、CJS 不参与。 fn({ ... })的键按参数名绑定:普通标识符、解构绑定名,或嵌套解构的点路径键。嵌套 pattern 的外层键仍可整体绑定shape(...);数组元素没有路径形态。平铺名与同拼写的点键冲突时平铺名优先。
// v.js
export function nested({ card: { grade } }) {
return grade + "#";
}
// v.nudo.js —— 'card.grade' 绑内层字段;'card' 绑整个对象
import { fn, string } from "@nudojs/core";
export const nested = fn({ "card.grade": string() }, string());
node_modules/下的侧车永不自动加载。- 源码注解与侧车对同参的约束合取;矛盾合取(如
x > 0∧x < 0)报nudo:contract-conflict。 - 合并序:手写(源码注解 ∪ 侧车绑定)> 生成段 > 隐式推导。
nudo contract按层标注([handwritten]/[generated]/[implicit])。
源码内形态
@nudo:contract <param> <constraint>
@nudo:contract return <constraint>
@nudo:contract return <rel> <expr>
- param — 参数名,或字面量
return表示后置 - constraint — 来自
*.nudo.js的导出名,经/// @nudo:import引入 return <rel> <expr>— 依赖式返回义务,比较对象是返回项(return >= x、return > x + 1)。x ± c上的>=/<=可由 IEEE 舍入单调性证明(c >= 0时round(b + c) >= b);无界操作数上的严格>/<诚实证不出(2^53 + 1 = 2^53),报nudo:unproven-return,绝不判违例。- 契约内 binder(侧车) —
bind("a", constraint)在单条约束树里给槽位域命名;ref("a")复用,ref("a").at("field")投影字段。作用域 = 单个侧车导出;找不到 binder 的reffail-closed(nudo:contract-load),绝不退化成any()。跨位形态:fn({ items: array(bind("a", any())), transform: fn({ x: ref("a") }, bind("b", any())) }, array(ref("b")))投影为<A, B>(items: A[], transform: (x: A) => B) => B[]。依赖式返回的侧车形态是rel(">", "x")。
示例
/// @nudo:import { positive, delay } from "./shapes.nudo.js"
/**
* @nudo:contract x positive
* @nudo:contract return positive
*/
function inc(x) {
return x + 1;
}
/**
* @nudo:contract ms delay
*/
function setDelay(ms) {
if (ms > 0) return ms;
return 0;
}
setDelay(0); // error: 0 ⊭ delay
setDelay(100); // ok
无需 interface 的 object 形状:
// shapes.nudo.js
export const user = shape({
id: number().gt(0),
name: string(),
});
/**
* @nudo:contract u user
*/
function register(u) {
return `${u.id}:${u.name}`;
}
@nudo:assume — 用户引理
声明一条引擎推导不出的跨变量引理——关于两个形参或顶层局部量的算法事实(编辑距离 ≤ 较长串的长度),普通区间传播表达不了它:那需要两个抽象值之间的相关性。前提参与除法关系折叠——d <= max ∧ max > 0 ⇒ d/max <= 1(镜像与负分母翻转不等号)——下游 + / - / * 折叠消费推出的界,于是 1 - d/max ∈ [0,1] 这类返回契约变得可证。
语法
@nudo:assume <expr> <= <expr>
@nudo:assume <expr> >= <expr>
<expr> 是 JS 绑定名、数值字面量,或简单算术表达式(name + number / name - number,左结合;括号、*、/ 不接受)。例:d <= max、i + 1 <= n、d <= 10。
- 函数级——写在紧邻函数上方的注释块里,与
@nudo:contract同一条扫描路径;锚定到最近的函数。 - 表达式里引用的每个名字都必须是锚定函数的形参或函数体顶层的
const/let/var局部绑定(d、max)——只收函数体直接子语句中VariableDeclaration的普通Identifier声明名;解构、嵌套块、for头声明不接受。否则 errornudo:assume-invalid。 - 局部量按 SSA 语义锚定——引理作用于绑定值,从定义点生效到作用域尾;重新赋值后相关性保守失效(不折)。
- 锚定只在目标函数自己的帧激活——callee 帧前提已清空,同名局部不会误匹配。
- 只接受
<=/>=(>=归一为le)。<、>、==非法;常数与简单算术合法(d <= 10、i + 1 <= n)。侧车够不到函数自己的局部量:局部量的常数界放在生产它的 callee 的返回上(如 levenshtein 侧车return number().ge(0))。 - 多行可叠加——前提合取。
语义——公理,不是被检验的事实
- 引擎从不验证引理。 证明依赖它时,
nudo check发 infonudo:assume-relied(sim: return contract proved via @nudo:assume d <= max),并建议用具体@nudo:case(nudo test)证伪。错误引理会让受影响的证明 unsound——引理要少、要可评审。 - 前提不跨调用边界继承。 callee 帧看到的前提槽为空(函数入口清空、退出恢复);递归调用保守清空。关于
sim的d/max的引理不会泄漏进别的函数的同名形参。前提激活期间,契约面采用(contract-face adoption)同样跳过:无信息实参不会被重锚到 callee 的形参名上,Fabricate 出的同名 term 无法流回 caller 帧冒充引理变量(否则sim内调用helper(d)会让helper自己的d与引理的d碰撞)。
示例——相似度得分
// sim.js
/**
* @nudo:assume d <= max
*/
export function sim(d, max) {
return max === 0 ? 1 : 1 - d / max;
}
// sim.nudo.js
import { fn, number } from "@nudojs/core";
export const sim = fn(
{ d: number().ge(0), max: number().ge(1) },
number().ge(0).le(1),
);
$ nudo check sim.js
OK
0 error · 0 warning · 1 info · 1 fn
signatures
sim(d: number, max: number) => number
issues
[INFO sim] sim: return contract proved via @nudo:assume d <= max (nudo:assume-relied)
→ @nudo:assume is a user-supplied axiom — falsify it with concrete @nudo:case runs (nudo test)
去掉 @nudo:assume 行,同一文件 + 侧车诚实保留为证不出——warning nudo:unproven-return:
[WARNING sim] sim: return value ⊭ @nudo:contract return number().ge(0).le(1) (nudo:unproven-return)
区间传播分别知道 d >= 0 与 max >= 1,但没有东西把两个值关联起来——这条相关性正是引理所提供的。
示例——局部量作引理名
引理名也可以是锚定函数函数体的顶层局部量:
// sim.js
/**
* @nudo:assume d <= max
*/
export function sim(a, b) {
const d = rawDist(a, b); // 编辑距离
const max = maxLen(a, b); // 较长串的长度
return 1 - d / max;
}
d、max 是函数体顶层 const 局部量——各自锚定在定义点(SSA 语义),引理相关性保持到作用域尾。它们的常数界来自各自生产 callee 的侧车——外层函数的侧车够不到自己的局部量:
// rawDist.nudo.js / maxLen.nudo.js
import { fn, number, string } from "@nudojs/core";
export const rawDist = fn({ a: string(), b: string() }, number().ge(0));
export const maxLen = fn({ a: string(), b: string() }, number().ge(1));
由 d >= 0(rawDist 侧车)、max >= 1(maxLen 侧车)与引理 d <= max,1 - d/max ∈ [0,1] 返回契约可折——与形参版同一证明形状(sim 自己的侧车照常携带 number().ge(0).le(1))。
与侧车契约的分工
| 事实 | 归属 |
|---|---|
常数界——d <= 10、max >= 1 | 侧车 / @nudo:contract 构建器(number().le(10)) |
跨变量引理——d <= max | @nudo:assume(引擎推导不出) |
循环携带界——dp[*][*] >= 0 | @nudo:invariant(循环 join/宽化丢区间证据) |
.le("max") 此前被静默接受,产出一个字符串字面量 pred(le(self, lit("max"))),从不参与任何证明。数值界构建器(gt / ge / lt / le / min / max / shift)现在在加载期拒绝非数值、非有限实参——侧车以 nudo:contract-load 失败:
sidecar './sim.nudo.js' failed to load: nudo le(): finite numeric bound expected, got "max" — variable references are not supported; express cross-variable lemmas with @nudo:assume (issue #152)
这类侧车请迁移到 @nudo:assume。
@nudo:invariant — 循环不变式
声明一条引擎推导不出的循环携带界——@nudo:assume 的循环类比物。循环 join 与宽化保留值域(number)但丢区间证据:连 let last = 0; for (let j = 1; j <= n; j++) last = j; return last 都证不出 last >= 1(自动推导循环不变式是 research-grade——Nudo 不尝试)。指令让用户供不变式;引擎在循环 join / 宽化位实施强化。
语法
@nudo:invariant <name><path> <rel> <expr>
@nudo:invariant dp[*][*] >= 0
@nudo:invariant last >= 1
@nudo:invariant i < n
<expr> 是数值字面量、绑定名(形参 / 顶层局部),或 name ± number——支持关系式右端(i < n)。
- 函数级——写在紧邻函数上方的注释块里,与
@nudo:contract/@nudo:assume同一条扫描路径;多行可叠加。 <name>必须是锚定函数的形参或函数体顶层const/let/var局部绑定;否则 warningnudo:invariant-invalid。<path>沿绑定下钻:[*]进数组元素 / tuple 成员 / union 数值臂;.ident进对象槽。空路径即标量本身。非数值叶子(字符串、对象)与结构不匹配静默跳过——写错方向的不变式由证明失败暴露,不上报。<rel>是>=/<=/>/<(==、!=、非数值形态如dp >= string非法 →nudo:invariant-invalid);右端可以是常数、绑定名或name ± number。- 强化叶子携带 fresh 符号 term 与声明的 pred(conf
path);字面量叶子不动——具体值自带真值。
语义——公理,不是被检验的事实
- 自动推断永不作为证明前提。 循环携带标量被宽化时,
nudo check发 info 候选(nudo:invariant-inferred),给出观测界与样本数——观测极值是单侧证据,不是已证不变式;只有显式@nudo:invariant行才进入证明。 - 引擎从不验证不变式。 证明依赖它时,
nudo check发 infonudo:invariant-relied(levenshtein: return contract proved via @nudo:invariant dp[*][*] >= 0),并建议用具体@nudo:case(nudo test)证伪。错误不变式会让受影响的证明 unsound——不变式要少、要可评审。 - 不变式不跨调用边界继承。 callee 帧看到的不变式槽为空(函数入口清空、退出恢复)——caller 的
dp引理不会泄漏进 callee 的同名局部。 - 不变式不顺手修的:OOB 读位事实保持诚实。抽象下标读
dp[m][n]仍合成undefined;if (out === undefined) return 0守卫在返回契约看到它之前先窄化。
示例——编辑距离
// levenshtein.js
/**
* @nudo:invariant dp[*][*] >= 0
*/
export function levenshtein(a, b) {
const m = a.length, n = b.length;
const dp = Array.from({ length: m + 1 }, (_, i) => [i]);
for (let j = 1; j <= n; j++) dp[0][j] = j;
for (let i = 1; i <= m; i++) {
for (let j = 1; j <= n; j++) {
dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1,
dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
}
}
const out = dp[m][n];
if (out === undefined) return 0;
return out;
}
// levenshtein.nudo.js
import { fn, number, string } from "@nudojs/core";
export const levenshtein = fn(
{ a: string(), b: string() },
number().ge(0),
);
$ nudo check levenshtein.js --ignore-throws RangeError
OK
0 error · 0 warning · 1 info · 1 fn
signatures
levenshtein(a: string, b: string) => 0 | number throws RangeError
issues
[INFO levenshtein] levenshtein: return contract proved via @nudo:invariant dp[*][*] >= 0 (nudo:invariant-relied)
→ @nudo:invariant is a user-supplied axiom — falsify it with concrete @nudo:case runs (nudo test)
--ignore-throws RangeError 为合法的 Array.from({ length: m + 1 }) array-like 长度 may-throw 拆分 L2 预期(抽象长度上界不可判,native { length: 2 ** 32 } 确实抛)——签名面仍诚实保留 throws RangeError。
去掉 @nudo:invariant 行,同一文件 + 侧车诚实保留为证不出——warning nudo:unproven-return(抽象 dp[m][n] 读合成 OOB undefined;守卫窄化它,但宽化后没有任何界存活来证 ge(0))。
@nudo:throws — 申报有意抛错
申报函数有意抛错。L2(nudo:entry-may-throw)要求入口/导出函数不携带未申报的 throw —— 与其藏起 fail-fast,不如把它申报出来。申报只解除已申报种类的 L2;throw 仍保留在签名上(是申报,不是抹除)。
语法
@nudo:throws Error
@nudo:throws Error, TypeError
@nudo:throws *
- kinds —— 逗号分隔的构造器名(空格或
|亦可分隔)。申报Error覆盖整个 Error 家族(TypeError、RangeError、ReferenceError、SyntaxError、URIError、EvalError、AggregateError),语义同instanceof Error;申报具体种类只覆盖自身。 *—— 申报任意 throw,L2 全部解除。- 未申报的种类照常报告 —— 申报是精确的,不是一刀切忽略。
指令为函数级:写在函数正上方的注释块里,与 @nudo:contract 同一条扫描路径。另有两个等价申报形态:
@nudo:case "name" (args) !! throws—— 用例后缀申报;裸!! throws申报任意 throw,!! throws Error按种类申报(@nudo:case仍是 debug 专用)。- 侧车选项 —— 同名
*.nudo.js绑定上的fn(params, returns, { throws: "Error" })。
申报 ≠ --ignore-throws:申报表达「这个 fail-fast 是有意的」,按种类生效;--ignore-throws 是迁移期的一揽子放行。两者同时存在时先应用申报。
示例
/**
* @nudo:throws RangeError
*/
export function clampPercent(n) {
if (n < 0 || n > 100) throw new RangeError("n must be within 0..100");
return n;
}
输出(nudo check):
nudo check clamp.js
OK
0 error · 0 warning · 0 info · 1 fn
signatures
clampPercent(n: any) => any throws RangeError
(no issues)
去掉申报后,同一函数 L2 失败 —— throw RangeError 未消化:
nudo check clamp.js
FAILED
1 error · 0 warning · 0 info · 1 fn
signatures
clampPercent(n: any) => any throws RangeError
issues
[ERROR L1 clampPercent] clampPercent (export): may throw RangeError (nudo:entry-may-throw)
actual: clampPercent(n: any) => any throws RangeError
expected: entry total, or @nudo:throws / try-catch
→ throw RangeError → @nudo:throws RangeError / refine / guard / try-catch
fix: nudo contract --draft (emit a sidecar draft you can edit)
docs
nudo:entry-may-throw → https://nudojs.github.io/nudo/docs/reference/diagnostics#nudo-entry-may-throw
报头里的 L1 是行号,不是契约层 —— 该诊断的层是 L2。L2 语义与其他解除路径(refine 收窄、try/catch 消化、--ignore-throws)见 L2 —— 入口 throws。
@nudo:import — 约束模板引入
为 @nudo:contract 从 *.nudo.js 模块引入约束模板。文件级指令,三斜线注释。
语法
/// @nudo:import { name1, name2 } from "./shapes.nudo.js"
/// @nudo:import * as ns from "./shapes.nudo.js"
- 具名 — 绑定
@nudo:contract使用的导出模板名 - 命名空间 —
@nudo:import * as ns from "…"展开为@nudo:contract中的ns.exportName引用
示例
/// @nudo:import { positive } from "./shapes.nudo.js"
/**
* @nudo:contract x positive
*/
function inc(x) {
return x + 1;
}
@nudo:env — 运行时环境
声明文件中可用的运行时环境 API。这是一个文件级指令,使用三斜线注释放在文件顶部。Nudo 内置了常见环境的类型定义,无需手动为标准 API 编写 mock。
语法
/// @nudo:env name1, name2, ...
- names — 逗号分隔的环境名称。内置环境:
es、web、node。 web和node自动包含es。- 除内置名称外,还可以指向一个 TypeScript 文件:
/// @nudo:env ./nudo-env.ts。该文件必须导出defineEnv()函数,返回{ globals, modules? }类型定义(与 Nudo 内置环境相同的形状)。
支持的环境
| 名称 | 提供的 API |
|---|---|
es | JSON、Math、Number、Array、console、Promise、Date、错误构造函数等 |
web | fetch、Request、Response、URL、localStorage、document、navigator、crypto、performance、定时器等 |
node | process、Buffer、__dirname、__filename、定时器,以及模块:fs、path、os、crypto、url、child_process、util |
示例
/// @nudo:env web
/**
* @nudo:case "test" (number())
*/
async function fetchUser(id) {
const res = await fetch(`/api/users/${id}`);
return res.json();
}
/// @nudo:env node
import { readFileSync } from "node:fs";
import { join } from "node:path";
/**
* @nudo:case "test" (string())
*/
function loadConfig(dir) {
const content = readFileSync(join(dir, "config.json"), "utf-8");
return JSON.parse(content);
}
项目级配置
也可以在 package.json 中设置环境,使项目中的所有文件都使用:
{
"nudo": {
"env": ["node"]
}
}
文件级 @nudo:env 指令会与项目级设置合并(取所有环境名称的并集)。
@nudo:mock-module — 模块级 Mock
替换或部分替换导入的模块为自定义 mock 文件。这是一个文件级指令,使用三斜线注释。
语法
完全替换:
/// @nudo:mock-module "original-module" from "./mock-file.js"
部分替换(仅指定的导出):
/// @nudo:mock-module "original-module" { export1, export2 } from "./mock-file.js"
- original-module — 要拦截的模块标识符(如
"lodash"、"node:fs")。 - exports(可选)— 要替换的特定命名导出。未指定的导出回退到原始模块。
- mock-file — 提供 mock 实现的文件路径。
示例
/// @nudo:mock-module "axios" from "./mocks/axios.js"
import axios from "axios";
/**
* @nudo:case "test" ()
*/
async function getUsers() {
const res = await axios.get("/api/users");
return res.data;
}
/// @nudo:mock-module "lodash" { debounce } from "./mocks/lodash-debounce.js"
import { debounce, throttle } from "lodash";
// debounce 来自 mock;throttle 正常解析
模块 mock 逐文件用 @nudo:mock-module 声明——不存在项目级 mock 配置。
@nudo:as — 类型断言
覆盖下一条语句的值类型。类似 TypeScript 的 as 关键字,但以行注释的形式放在语句上方。在 求值引擎上作用于被覆盖语句的 VariableDeclaration 初始化值与 ReturnStatement 返回值。
解构声明同样受支持:覆盖施加在初始化表达式上,且每个解构出的名字各自绑定自己推断出的类型。若标注在其它语句形态上(循环头、if/while 体、表达式语句、函数声明),那里没有可覆盖的值 ⇒ 指令会显式报 warning nudo:directive-syntax,不再被静默忽略。
语法
// @nudo:as typeValueExpr
示例
// @nudo:as shape({ port: number(), host: string() })
const config = JSON.parse(content);
// config 现在是 { port: number, host: string } 而不是 unknown
// @nudo:as array(shape({ id: number(), name: string() }))
return JSON.parse(response);
@nudo:replace — 子表达式类型替换
替换下一条语句中特定子表达式的类型。目标表达式通过源码文本与 AST 节点匹配,不会匹配部分标识符或字符串内容。
语法
// @nudo:replace targetExpr typeValueExpr
- targetExpr — 要替换的表达式源码文本(如
a、res.data、JSON.parse(input))。 - typeValueExpr — 用于替换的类型值。
示例
// @nudo:replace a number()
const x = a + b;
// 只有 `a` 被替换;`b` 正常求值
// @nudo:replace res.data array(shape({ id: number() }))
const items = res.data;
// @nudo:replace JSON.parse(input) shape({ name: string() })
const data = JSON.parse(input);
可以叠加多个替换:
// @nudo:replace a number()
// @nudo:replace b string()
const result = a + b;
注意: 每个 @nudo:replace 只影响紧跟的下一条语句。
汇总表
| 指令 | 语法 | 用途 |
|---|---|---|
@nudo:case | "name" (args...) 或 "name" (args) => type | 调试 / nudo test 见证(不是契约产品) |
@nudo:mock | name = expr 或 name from "path" | Mock 外部依赖 |
@nudo:pure | (无参数) | 标记纯函数 —— 求值器按实参记忆化调用结果 |
@nudo:skip | [=> returnsExpr] / [(returnsExpr)] | 跳过求值,使用已有类型信息 |
@nudo:sample | N | 保留的无效果指令(已解析,未消费) |
@nudo:contract | param constraint / return constraint | 源码内契约(主路径是 *.nudo.js 侧车自动绑定) |
@nudo:assume | <name> <= <name>(或 >=) | 声明跨变量用户引理(形参或函数体顶层局部量;公理,不被验证)——依赖它的证明带 nudo:assume-relied 审计标注 |
@nudo:invariant | <name><path> <rel> <number>(如 dp[*][*] >= 0) | 声明循环携带界(形参或函数体顶层局部量沿路径下钻;公理,不被验证)——依赖它的证明带 nudo:invariant-relied 审计标注 |
@nudo:throws | Error, TypeError 或 * | 申报有意抛错 —— 按申报种类解除 L2 nudo:entry-may-throw |
@nudo:import | { name } from "spec"(文件级 ///) | 为 @nudo:contract 引入 *.nudo.js 约束模板 |
@nudo:env | name1, name2(文件级 ///) | 声明运行时环境 API |
@nudo:mock-module | "module" from "path"(文件级 ///) | 替换导入的模块为 mock |
@nudo:as | typeValueExpr(行注释 //) | 覆盖下一条语句的值类型 |
@nudo:replace | targetExpr typeValueExpr(行注释 //) | 替换下一条语句中子表达式的类型 |