跳到主要内容

快速开始

读完你能带走: nudo check 的签名、nudo test 的用例、一份侧车契约、一条可读的 nudo check 失败信息,以及让门禁重新变绿的收尾闭环。

更想在浏览器里试?打开 Playground。

30 秒,不开仓库

直接对任何一份你信任的 JavaScript 文件粘贴:

npx nudojs check /path/to/your/util.js

应立刻看到签名(如 scale(x: any) => number | string throws TypeError),然后要么 (no issues),要么一行 L1/L2 发现。入口参数显示为 any 而不是 unknown——未约束就是未约束,不是推断失败。(导出面则另有口径:生成的 .d.ts 会把未被调用的导出参数投影为 unknown——那是诚实边界,不是推断失败。见 Export:通向生态的桥。)后文逐项解释你刚看到的东西。

信任边界。 Nudo 通过执行目标代码来分析(Abs 语义,进程内求值)。不要对不可信代码运行 nudo check / nudo test;在 CI 里这与跑项目测试是同一信任级别。

1. 写普通 JavaScript​

创建 calc.js:

export function scale(x) {
return x + 1;
}

export function formatName(first, last) {
return first + " " + last;
}

formatName("Ada", "Lovelace");
scale(5);

没有标注。调用点就是证据。

2. 观察(Day 0)​

npx nudojs check calc.js
nudo check calc.js
FAILED
2 error · 0 warning · 0 info · 2 fn

signatures
scale(x: any) => number | string throws TypeError
formatName(first: any, last: any) => string throws TypeError

issues
[ERROR L1 scale] scale (export): may throw TypeError (nudo:entry-may-throw)
[ERROR L5 formatName] formatName (export): may throw TypeError (nudo:entry-may-throw)

onboarding
every error above is an L2 entry may-throw — unconstrained entry points, not broken contracts.
no @nudo:* directives and no package.json#nudo config found in this project yet. next steps:
nudo init write an adoption baseline config (L2 → warning)
nudo contract --draft <file> draft a *.nudo.js sidecar contract for one file
nudo check --profile adoption preview the gate with L2 as warnings

onboarding 块只出现在「纯净」项目——没有任何 @nudo:* 指令、任何位置都没有 nudo 配置。加上二者之一(下一节就会加)它即消失;门禁结果本身不变。

这个 number | string 是老实的 JavaScript 语义,不是 bug:+ 的操作数无约束(any)时,既可能走数值相加,也可能走字符串拼接("7" + 1),Nudo 两条分支都保留。给 x 加约束——侧车契约或调用点证据——联合就会坍缩为 number。见语言语义。

两个 L2 发现是同一枚硬币的反面:无约束 + 操作数的 ToPrimitive 可能抛 TypeError(原生 Symbol 强制转换),因此在约束参数(下一节)或声明 @nudo:throws TypeError 之前,check 会标记这两个导出。

可选调试用例(nudo test —— 不是产品门禁):

=== scale ===
call@L10 (5) => 6

=== formatName ===
call@L9 ("Ada", "Lovelace") => "Ada Lovelace"

assertions
— 0 passed · 0 failed · 0 unchecked (no declared @nudo:case expectations; 2 synthetic case(s) printed above)

Nudo 用实际看到的实参执行了这些函数。无约束入口参数显示为 any(不是 unknown)。观察 = check 签名 + IDE hover;nudo test 是可选的调试用例报告器。

3. 加上显式契约(Day 1)​

在源码旁创建 calc.nudo.js:

import { number, string, fn } from "@nudojs/core";

export const scale = fn({ x: number().gt(0) }, number());
export const formatName = fn({ first: string(), last: string() }, string());

两个导出都加了约束——formatName 的 + 操作数变为 string,其 L2 may-throw 发现与 scale 的一并清除。

4. 用 check 把关​

加一个违反侧车的调用:

scale(0); // fails the sidecar — x must be > 0

跑门禁:

npx nudojs check calc.js
nudo check calc.js
FAILED
1 error · 0 warning · 0 info · 2 fn

signatures
scale(x: number) => number
formatName(first: string, last: string) => string

issues
[ERROR L12 scale] scale[x]: argument ⊭ precondition (nudo:constraint-violated)
actual: 0 #exact
expected: x > 0
→ use a value satisfying x > 0, or relax the precondition on x

违例按调用点上报。修正调用(或放宽契约)后 check 通过——仍会打印签名。

if 守卫不是 refinement。显式契约只来自侧车 / @nudo:contract。没有它们时,L2 仍门禁导出上的未消化 may-throw(入口参数为 any)。

5. 收尾闭环:变绿、CI、IDE​

修正违规调用——任何满足 x > 0 的值都行:

scale(2); // satisfies the sidecar — x must be > 0

再跑一次门禁:

npx nudojs check calc.js
nudo check calc.js
OK
0 error · 0 warning · 0 info · 2 fn

signatures
scale(x: number) => number
formatName(first: string, last: string) => string

(no issues)

变绿了——签名照常打印;只有 OK / FAILED 行和退出码(0)说明门禁是否通过。闭环还剩两个落点:

选项​

  • .d.ts 投影 —— 生态桥(单向有损;Abs 才是真理源):

    npx nudojs export calc.js --format dts --out dist/types
  • Watch 模式(旗标,不是动词)

    npx nudojs check src/ --watch
    npx nudojs test src/ --watch

Export bridge + adoption profile(契约层 → 生态)​

check 变绿之后(或迁移进行中),把 Abs 向外投影——编辑器要的 .d.ts,边界代码要的 Zod / Standard Schema / 守卫:

npx nudojs export calc.js --format all --out dist

schema 管边界数据;Nudo 管内部算出来的事实。完整故事:Export:通向生态的桥。

遗留 JS 在 L2 下太吵?用命名的迁移门禁档位——L1 契约违例保持 error,只有入口 may-throw 降到 warning:

npx nudojs check calc.js --profile adoption

调试见证(可选)​

@nudo:case 用于场景调试(nudo test、LSP 用例切换)——不是契约产品:

/**
* @nudo:case "double digits" (10)
*/
export function scale(x) {
return x + 1;
}

case 实参请用具体值或约束构建器。

下一步​