跳到主要内容

示例

读完你能带走: 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.js1(两行均为负例)
vs-ts/同一逻辑与 TypeScript 并排对照constraints/nudo.js · constraints/tsc.ts · structure/nudo.jsnudo 1 · tsc 0 / 2
mini-repo/多文件集成(ESM + class + async)user-service.js · store.js · validators.jsuser-service check 1(L2)· 其余 0
algebra/类型即计算(spread / HOF / reduce / mixin)0-add-intensional.js · b-hof-map.js · c-reduce-sum.js0
contract-derivation/契约分层推导(手写根 → 生成下游行)lib.js · lib.nudo.js · add.js0
contract-draft/代码优先:从逻辑生成可审阅契约草稿greet.js · README.md0(contract --draft)
migrate/退役 tsc 样板包(单向 before/after 门)before/src/math.ts · after/src/math.js · before/package.json0(status / strip / verify / retire)
errors/Top-10 错误面孔(Nudo 真实输出)01-constraint-gt.js · 04-entry-throws.js · 10-fix-path.js1(全部十例)
retire-real/真实包 ms 的 tsc 退役案例(非合成夹具)before/src/age.ts · after/src/age.js0
retire-debug/真实包 debug 的 tsc 退役案例(visionmedia/debug)before/src/logger.ts · after/src/logger.js0

根目录的 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仅可选调试见证