跳到主要内容

Nudo

欢迎重回 JS 世界。

Nudo 不限制你的 JS 表达,只忠实反映中间量与结果,并提供比类型更精确的契约校验。

nudo · pricing.js + sidecar
export function lineTotal(price, qty) {price: number · price > 0param priceshape numberpred price > 0 // sidecarconf pathqty number · qty ≥ 1
return price * qty;term (price × qty) · > 0return term (price * qty) pred (price * qty) > 0 // price>0 ∧ qty≥1 ⇒ product > 0 // aligns with sidecar return number().gt(0) conf path(no concrete case — algebraic entry vars)
}
export function applyCoupon(order, code) {order shape · code: stringparam order shape { subtotal ≥ 0; items ≥ 0 } conf path (sidecar)param code shape string conf path
const rate =
code === "VIP10" ? 0.1 :
code === "VIP20" ? 0.2 : 0;rate ∈ {0, 0.1, 0.2}term ratepred rate = 0 ∨ rate = 0.1 ∨ rate = 0.2 // path-narrowed on code === …conf path
return {
...order,
total: order.subtotal * (1 - rate),
coupon: rate > 0 ? code : "NONE",term subtotal×(1−rate) · ≥ 0field total term order.subtotal * (1 - rate) pred total ≥ 0 // sidecar number().ge(0) conf path
};coupon: stringfield coupon term rate>0 ? code : "NONE" pred string conf path
}
// call sites are evidence
lineTotal(12, 3);
applyCoupon({ subtotal: 100, items: 3 }, "VIP10");=> 36 #exactcall lineTotal(12, 3)result 36 #exactConcrete values live at the call site.
total 90 · coupon "VIP10"call applyCoupon({subtotal:100, items:3}, "VIP10")rate 0.1total 90coupon "VIP10" #exact
// L1 gate: price > 0 from pricing.nudo.js
lineTotal(0, 2);⊭ price > 0call lineTotal(0, 2)actual 0 #exactexpected price > 0 // sidecargate nudo:constraint-violated
$ npx nudojs check pricing.js
signatures
lineTotal(price: number, qty: number) => numberfrom sidecar + bodysignatures reflect Abs after contracts:price: number · price > 0 (sidecar)qty: number · qty ≥ 1// unconstrained entry params print as any// unknown = inference failed — not this
applyCoupon(order: { subtotal: number, items: number }, code: string)
=> { subtotal: number, items: number, total: number, coupon: string }
issuesL1 gatecall site lineTotal(0, 2) ⊭ sidecar predactual ⊭ expected on AbsCI: nudo check exits 1
[ERROR L21 lineTotal] lineTotal[price]: argument ⊭ precondition (nudo:constraint-violated)
actual: 0 #exactprice > 0expected pred from pricing.nudo.jsalgebraic — not a declared TS typecontracts are JS modules — no second language
expected: price > 0
→ use a value satisfying price > 0, or relax the precondition on price
fix: nudo contract --draft (emit a sidecar draft you can edit)

悬停任意一行——函数体 inlay 是侧车代数 Abs;同文件调用点既是证据,也是 L1 门禁。

98.6%@hapi/hoek 上的精确签名 出处
0需要你写的类型标注 出处
291 → 0契约校验失败被清零 出处
0.19 ms文件编辑后中位重分析 出处
调用点发现如何工作 →

成本(已有实测)

修环更短,载荷更省

变量接近运行时,违例带 actual / expected / actions——agent 更早检出、更少往返。下列为仓库内基线(OSS 切片 + 微基准),不是封闭 benchmark。

569kvs 993k

修至绿灯的 agent tokens(OSS 历史 bug 切片) 出处

45vs 63

按文档化修复路径的门禁轮次 出处

0.19 msvs 10 ms+

单文件 analyze 中位(对比微基准中 tsc.LS 十毫秒级) 出处

TS 的「便宜 token」往往是假绿。Nudo 花 token 来报告。 口径与边界 →

超越声明式类型

TypeScript 会加宽掉的值

Nudo 在 Abs 上求值,结果跟随真实计算——字面量字符串、split、循环求和——不是声明的上界。

表达式TypeScriptNudo 观察到
"0x" + idstring`0x${string}`
"hello".slice(1, 3)string"el"
"a,b,c".split(",")string[]["a", "b", "c"]
for (let i = 0; i < 5; i++) sum += inumber10

模板字符串 `SAVE-${code.toUpperCase()}` 不是普通 string——当调用点是 coupon("vip") 时,Nudo 观察到 "SAVE-VIP"。

真实代码上的效果

调用点变成签名

观察层的 check 把无约束参数打印为 any。把 Nudo 指向真实用法——测试、调用点——解释器会从证据综合出精确签名。不改库、不补类型标注。

调用点发现会返回什么

coupon来自 cart.js 调用点
before无调用点证据 → any
nudo("vip") => "SAVE-VIP"
deepEqual来自 @hapi/hoek 用法
before无调用点证据 → any
nudo({a:1,b:{c:2}}, {a:1,b:{c:2}}) => boolean
flatten来自递归 + 循环用法
before无调用点证据 → any
nudo([1,[2,[3,4]]]) => [1,2,3,4]

产品路径

观察层 → 契约层 → 离开 tsc

观察层:nudo check 打印签名并诊断入口可能抛错。契约层:侧车契约把调用点事实变成 L1 义务。生态:export 从 Abs 投影产物。出口:migrate retire —— 共存不是终态。

  1. 观察层观察 + 门禁npx nudojs check src/
  2. 契约层加上契约lib.nudo.js · @nudo:contract · nudo check
  3. 生态投影产物npx nudojs export src/ --format dts|schema
  4. 出口退役 tscnpx nudojs migrate status|strip|verify|retire
逻辑优先

先写逻辑,再生成契约

调用点是证据。contract --draft 可生成可审阅的契约草稿,确认后写入 *.nudo.js。草稿不会自动成为校验义务。

npx nudojs contract --draft lib.js --from test/
契约优先

先写契约,再辅助/约束逻辑

先写 *.nudo.js 或 @nudo:contract,用同一契约面辅助实现,并在 check 中约束逻辑。

npx nudojs check src/

校验与产物

流程以 Abs 契约为核心。check 只做校验;export 从 Abs 投影 .d.ts / Zod / Standard Schema / guards;IDE 与 Agent 直读 Abs。

nudo check

只校验 / CI。不生成产物。

export · dts

投影给 TypeScript 消费方的 .d.ts。有损。

export · Zod / guards

由 Abs 得到的运行时校验。不能替代 check。

export · Standard Schema

Standard Schema 运行时校验器,可接入下游工具链。

IDE / LSP

hover / inlay 直读 Abs。

Agent / MCP

编码 agent 经 LSP / MCP 读同一套 Abs —— 见下方 AI Agents 专区。

AI Agents

帮 agent 门禁契约,而不是发明类型

编码 agent 与编辑器经 LSP / MCP 读同一套 Abs 面。它们跑 `nudo check`、尊重侧车契约、解析稳定诊断码 —— 不是第二套类型语言。

与 IDE 同一套 Abs

Hover / inlay 与 agent 工具直接消费 Abs。`export` 投影有损;Abs 仍是唯一真源。

npx nudojs check src/ --json

LSP + MCP 表面

`@nudojs/lsp` 提供 agent `executeCommand` 工具。可为 Cursor、Claude Code 等客户端接 MCP,无需另立协议。

@nudojs/lsp · nudo.contract · nudo.whatIf

稳定的产品规则

Agent 不得从 body AST 发明义务,也不得把 `@nudo:case` 当契约。入口 `any` ≠ `unknown`。观察层是 `check`;契约层是 `contract` + `check`。

actual ⊭ expected · nudo:constraint-violated

Agent 入口

发布 `agents.md` 与 `llms.txt`,让 coding agent 无需猜产品名词即可接入。把 setup 块粘进 agent 即可。

nudojs.github.io/nudo/agents.md
粘贴进你的 coding agent
Read https://nudojs.github.io/nudo/docs/reference/agents
Primary gate: npx nudojs check <path>
Contracts are *.nudo.js / @nudo:contract
Do not invent body-AST obligations. @nudo:case is debug-only.
Entry params print as any; unknown = inference failed.

准备重回 JS 了吗?

在浏览器里观察中间量,用 CLI 在自有文件上门禁契约,或把 coding agent 指向同一套 Abs 面。你的 JS 仍是 JS。

npx nudojs check ./pricing.js