跳到主要内容

简介

Nudo 要解决的一件事:在源码里,就能看到变量接近运行时的样子。

阅读代码时,通常只能看到宽泛的类型名(number、string),或再叠一层标注。Nudo 在抽象值上执行 JavaScript,使每个变量携带它实际会算出的内容——字面量、形状、约束——并以签名、IDE inlay、调用点证据的形式呈现在源码旁。

// calc.js
export function scale(x) {
return x + 1;
}

scale(5);
// calc.nudo.js — explicit contract (obligation)
import { number, fn } from "@nudojs/core";
export const scale = fn({ x: number().gt(0) }, number());

在 IDE 中,中间量按行显示接近运行时的形态,而不是单一类型名:

scale(x) x: number · x > 0 // 契约或调用点带来的约束
return x + 1 term (x + 1) · > 1 // 推导结果,而非「number」
scale(5) => 6 #exact // 调用点即运行时真值
scale(0) ⊭ x > 0 // actual 0 · expected x > 0

nudo check 在命令行给出同一观察面(成功时亦打印 signatures)。需要义务时,以侧车契约(*.nudo.js / @nudo:contract)声明必须成立的条件;违例输出为值与谓词,而非类型名。

signatures
scale(x: number) => number

issues
[ERROR L7 scale] scale[x]: argument ⊭ precondition (nudo:constraint-violated)
actual: 0 #exact
expected: x > 0

在 Playground 中查看。

产品面: 观察层(Day 0)= nudo check(签名与诊断)。契约层(Day 1)= nudo contract + nudo check(显式契约)。生态 = nudo export(将 Abs 单向投影为 .d.ts / schema 等)。观察落在 check 签名与 IDE hover,不设独立观察动词。nudo test 为可选的调试用例报告。

如何实现:执行,而非标注​

目标是「源码中可见接近运行时的变量」。实现路径是在抽象值(Abs)上执行代码:

  1. 执行产生事实。 引擎在符号值上求值,记录每个中间量的形状、值身份与约束(而非从标注推断)。
  2. 调用点是证据。 scale(5) => 6 来自实际调用路径,不是注释中的声明。
  3. 约束参与代数。 x ≥ 0 可推出 (x + 1) ≥ 1(严格界会按 IEEE 舍入外推一 ulp 保持 sound),故 inlay 上的不只是类型名,而是可推理的关系。
  4. 标注非必写。 源码保持普通 .js;契约同为 JS 模块。

原理展开:抽象解释 · Abs。

如何使用这些文档​

你是从这里开始
评估类型/检查门禁的 JS 工程师心智模型 → 快速开始 → nudo check
TypeScript 用户Nudo vs TypeScript → 从 TS 迁移
现有 JS 包迁移现有 JS → 契约
自动化流水线 / 平台Recipes → 诊断 → 错误对照
AI 编码 agent / 工具链Agents → Agent integration → API · agent

非目标:Nudo 不是 TypeScript 编译器;不从 body AST 扫描发明必填槽;@nudo:case 仅调试,不是契约产品。见边界。

观察层与契约层​

层级你写什么你得到什么
观察层(Day 0)普通 JS + 调用点check 签名与 L2 入口 may-throw 诊断
契约层(Day 1)*.nudo.js / @nudo:contractL1 义务(actual ⊭ expected)
生态无需额外export 投影 dts / guard / schema
进阶Abs 代数、env、mock字符串/数字代数、高阶函数、模块图

观察层 → 契约层 → 生态

义务递增;any 为无约束,unknown 为推导失败。

与声明式类型的关系​

TypeScriptNudo
变量呈现声明类型名接近运行时的值 / 形状 / 约束
契约类型语言 + 可赋值性侧车构建器 + L2 入口 throws
精度常拓宽为 string / number可保留字面量、模板结构、循环求和
真源源码标注执行所得 Abs;投影有损且单向

对照:Nudo vs TypeScript。边界:Nudo 不宣称什么。

下一步​