示例
读完你能带走: Nudo 如何观察真实调用点、侧车契约如何门禁义务,以及哪些仍会退化为 unknown。
产品路径优先。 观察是 nudo check 签名(调用点是证据)。契约是 *.nudo.js / @nudo:contract。@nudo:case 仅是调试见证 —— 可选,不是契约产品。
下方每个输出块都摘录自对上面代码的真实引擎运行(nudo check / nudo test 头部行与 assertions 摘要按标注省略)。仓库内 CI 钉住的套件在 docs/examples/(pnpm run verify:examples);本指南按主题浏览同一引擎。
套件的主题目录一览(退出码是命令矩阵钉住的期望 —— 负例行故意非零退出,报出的行才是演示内容):
| 主题目录 | 演示什么 | 代表文件 | 期望 exit code |
|---|---|---|---|
constraints/ | @nudo:contract × Pred:标量 / 形状 / 返回精化;if 不是精化 | set-delay.js · register.js · return-contract.js · similarity.js · levenshtein.js | 负例 1 · register / test:cli / @nudo:assume / @nudo:invariant 为 0 |
structure/ | Abs leq:赋值 / 传参结构(宽度子类型) | assign.js · arg-structure.js | 1(两行均为负例) |
vs-ts/ | 同一逻辑与 TypeScript 并排对照 | constraints/nudo.js · constraints/tsc.ts · structure/nudo.js | nudo 1 · tsc 0 / 2 |
mini-repo/ | 多文件集成(ESM + class + async) | user-service.js · store.js · validators.js | user-service check 1(L2)· 其余 0 |
algebra/ | 类型即计算(spread / HOF / reduce / mixin) | 0-add-intensional.js · b-hof-map.js · c-reduce-sum.js | 0 |
contract-derivation/ | 契约分层推导(手写根 → 生成下游行) | lib.js · lib.nudo.js · add.js | 0 |
contract-draft/ | 代码优先:从逻辑生成可审阅契约草稿 | greet.js · README.md | 0(contract --draft) |
migrate/ | 退役 tsc 样板包(单向 before/after 门) | before/src/math.ts · after/src/math.js · before/package.json | 0(status / strip / verify / retire) |
errors/ | Top-10 错误面孔(Nudo 真实输出) | 01-constraint-gt.js · 04-entry-throws.js · 10-fix-path.js | 1(全部十例) |
retire-real/ | 真实包 ms 的 tsc 退役案例(非合成夹具) | before/src/age.ts · after/src/age.js | 0 |
retire-debug/ | 真实包 debug 的 tsc 退役案例(visionmedia/debug) | before/src/logger.ts · after/src/logger.js | 0 |
根目录的 l2-export-any.js 在目录之外钉住 L2 export-any 门禁:check 退出 1,--ignore-throws TypeError 退出 0。一条命令验证整个矩阵:pnpm run verify:examples。
在 Playground 试跑任意示例。
调用点与契约(产品路径)
1. 调用点减法 —— 观察层
普通 JS + 调用点。无注解。nudo check 打印签名;调用点提供证据。
export function subtract(a, b) {
return a - b;
}
subtract(5, 3);
subtract(1, 10);
npx nudojs check subtract.js
nudo check subtract.js
OK
0 error · 0 warning · 0 info · 1 fn
signatures
subtract(a: any, b: any) => number
(no issues)
无约束入口参数显示为 any。有更丰富的调用证据(或侧车)时,Abs 会保留字面量与代数 —— 跑 nudo check --abs 或在 IDE 打开该文件。
可选调试用例报告(nudo test —— 门禁不要求):
=== subtract ===
call@L5 (5, 3) => 2
call@L6 (1, 10) => -9
2. 侧车契约 —— 契约层义务
// pricing.js
export function lineTotal(price, qty) {
return price * qty;
}
lineTotal(12, 3);
lineTotal(0, 2);
// pricing.nudo.js — contract (also plain JS)
import { number, fn } from "@nudojs/core";
export const lineTotal = fn(
{ price: number().gt(0), qty: number().ge(1) },
number().gt(0)
);
npx nudojs check pricing.js
nudo check pricing.js
FAILED
1 error · 0 warning · 0 info · 1 fn
signatures
lineTotal(price: number, qty: number) => number
issues
[ERROR L6 lineTotal] lineTotal[price]: argument ⊭ precondition (nudo:constraint-violated)
actual: 0 #exact
expected: price > 0
→ use a value satisfying price > 0, or relax the precondition on price
if 守卫不是契约。义务来自侧车 / @nudo:contract。见契约与 nudo check。
3. 来自调用点的对象 shape
function greet(user) {
return user.name + " is " + user.age;
}
greet({ name: "Alice", age: 30 });
=== greet ===
call@L4 ({ name: "Alice", age: 30 }) => "Alice is 30"
拼接保留字面量结果 "Alice is 30" —— 不是被拍平的 string。参数解构同样拆开实参形状:
function addP({ x, y }) { return x + y; }
addP({ x: 1, y: 2 });
=== addP ===
call@L2 ({ x: 1, y: 2 }) => 3
spread 合并 shape:
function mixin(base, ext) {
return { ...base, ...ext };
}
mixin({ host: "localhost", port: 8080 }, { port: 3000, debug: true });
=== mixin ===
call@L9 ({ host: "localhost", port: 8080 }, { port: 3000, debug: true }) => { host: "localhost", port: 3000, debug: true }
字符串与模板
4. 模板字符串 —— 超越声明类型
export function coupon(code) {
return `SAVE-${code.toUpperCase()}`;
}
coupon("vip");
=== coupon ===
call@L5 ("vip") => "SAVE-VIP"
TypeScript 通常把它拓宽为 string。Nudo 在调用点观察到具体的模板结果。对照为什么选 Nudo 的表格与首页「超越声明类型」一节。
5. 精确的字符串方法
toUpperCase、toLowerCase、slice、.length 与 split(字面量接收者)在调用点路径上产生精确结果:"a,b,c".split(",") 折叠为 ["a", "b", "c"]。完整精确/退化地图见语言语义。
循环与范围
6. 具体边界的循环
function sumTo(n) {
let sum = 0;
for (let i = 0; i < n; i++) sum += i;
return sum;
}
sumTo(5);
=== sumTo ===
call@L6 (5) => 10
边界具体时循环求和保持字面量 —— 同一套 Abs 代数支撑 nudo check。
7. 范围收窄
路径谓词在分支内窄化 Abs(x > 5 → term 上的范围 pred)。详见控制流收窄。
联合与安全访问
8. typeof 判别
export function transform(x) {
if (typeof x === "string") return x.toUpperCase();
if (typeof x === "number") return x + 1;
return null;
}
transform("hi");
transform(41);
transform(null);
每个调用点保留自己的精确臂("HI"、42、null)。符号 unknown 条件目前会合并分支 —— 见语义。
9. 可选链
已知形状的接收者在任意深度折叠(a.b.c ?? 5 传 { b: {} } → 5);无约束(any)接收者上结果保持 any 并带 throws TypeError(引擎债 unknown 不适用 —— 见控制流收窄)。
运行时环境与 mock
10. 通过 @nudo:env web 使用 Web API
/// @nudo:env web
内置 es / web / node env 模块为常见 API 提供类型;第三方 @types 在分析期自动补洞。见依赖类型。Env/harvest 不是 mock 的替代品(尤其原生运行时回调)—— 见边界。
11. Mock 外部依赖
// @nudo:mock fetch = (url) => ({ ok: true, json: () => ({ id: 1 }) })
优先使用单行箭头函数 mock。完整语法:指令 —— mock。
调试见证(可选,不是产品)
@nudo:case 为 nudo test / LSP 用例切换注入场景输入。它不创建 CI 义务。
/**
* @nudo:case "double digits" (10)
*/
export function scale(x) {
return x + 1;
}
=== scale ===
debug "double digits" (10) => 11
优先使用具体值或约束构建器(number()、lit(42))。仅已声明 case 上的断言(=> expected)影响 nudo test 退出码 —— 合成 call@ / entry@ 绝不会让运行失败。
下一步去哪里
| 主题 | 页面 |
|---|---|
| 契约草稿 / 接受 / emit | 契约 |
| CI 门禁 + 诊断码 | nudo check · 诊断 |
哪些会退化为 unknown | 语言语义 |
| Abs 代数 | Abs |
| Recipes(CI、monorepo、export) | Recipes |
| 指令 | 在本指南中的角色 |
|---|---|
| 调用点 | 观察层证据(主要) |
*.nudo.js / @nudo:contract | 契约(主要) |
@nudo:env / @nudo:mock | 环境与边界 |
@nudo:case | 仅可选调试见证 |