跳到主要内容

语言语义

Nudo 通过执行你的代码来推断类型,所以推断质量正好等于求值器 JavaScript 语义的质量。本指南列出求值器在调用点路径上精确建模的语言行为——下方所有输出块均摘录自对上面代码真实运行 nudo test 的结果(nudo test <file> 头部与断言摘要已省略)——随后列出仍会退化为 unknown(推导失败 / 引擎债,不是无约束入口参数的默认值;入口默认为 any)、依赖前需要验证的构造。精确语义也是调用点发现生效的前提:采集到的调用形态只有求值器真的能跟下去才值钱。

信任边界​

推断就是执行:nudo check / nudo test 等价于在本机运行目标代码(evaluator 转译 + new Function)。

  • 不要对不可信代码运行 nudo(陌生 npm 包、用户提交、未经审查的 PR)。
  • CI 上只分析可信仓库。
  • 侧车契约(*.nudo.js)与 @nudo:mock / @nudo:mock-module 文件都是普通 JS,分析期同样会执行——同属一个信任边界。

这不是沙箱:Nudo 不隔离求值进程。分析预算只防失控推断,不是安全边界。唯一事实源:仓库 docs/design/kernel-merge.md →「执行模型与信任边界」。

已精确建模​

字面量上的字符串方法​

字面量接收者上的字符串方法在求值期折叠。

function upper() { return "hello".toUpperCase(); }
upper(); // → "HELLO"

function slen() { return "hello".length; }
slen(); // → 5

function sli() { return "hello".slice(1, 3); }
sli(); // → "el"
=== upper ===

call@L2 () => "HELLO"

toUpperCase、toLowerCase、slice、.length 与 split(字面量接收者 + 字面量分隔符)产生精确结果——"a,b,c".split(",") 在调用点路径折叠为 ["a", "b", "c"],无逗号的接收者如 "abc".split("b") 在 @nudo:case 指令路径折叠为 ["a", "c"]。指令路径无法表达含逗号的接收者:指令解析器按逗号拆分用例实参,@nudo:case "split" ("a,b,c") 会变成三个 unknown 形参而非一个字符串。前缀/后缀/包含检查——startsWith、endsWith、includes——对字面量接收者折叠为确定的布尔值。indexOf 只得 number 原语,丢字面量下标。

具体边界的循环​

具体边界的 for 循环求值出精确结果。

function sumTo(n) {
let sum = 0;
for (let i = 0; i < n; i++) {
sum = sum + i;
}
return sum;
}
sumTo(5);
=== sumTo ===

call@L8 (5) => 10

具体数组上的 for...of 同样精确:

function sumArr(arr) {
let s = 0;
for (const x of arr) {
s = s + x;
}
return s;
}
sumArr([1, 2, 3]); // → 6

break 保留跳出值​

循环跳转是信号:跳出迭代中绑定的值被保留。

function findBig() {
let found;
for (const x of [1, 2, 3, 4]) {
if (x > 2) {
found = x;
break;
}
}
return found;
}
findBig();
=== findBig ===

call@L11 () => 3

结果是字面量 3——循环跳出时绑定的值。

具体形状上的 Object.keys​

具体对象上的 Object.keys 返回精确的键元组。

function keysOf() { return Object.keys({ port: 3000, host: "x" }); }
keysOf();
=== keysOf ===

call@L2 () => ["port", "host"]

Math 方法​

字面量数值实参上的 Math 方法在求值期折叠——调用点与 @nudo:case 两条路径皆然。

function root(n) { return Math.sqrt(n); }
root(9);
=== root ===

call@L2 (9) => 3

sqrt、pow、abs、floor、ceil、round、sign、min、max 都在字面量实参上折叠为精确数值结果;符号实参拓宽为 number。

集合(Set / Map 迭代、Symbol.iterator)​

对具体 Set / Map 的 for...of 逐元素折叠;在已知接收者上,Symbol.iterator in x 协议探测折叠为确定布尔值:

function firstSet() {
const seen = new Set(["a", "b"]);
for (const x of seen) return x;
}
firstSet();

function firstMap() {
const m = new Map([["k", 1]]);
for (const [k, v] of m) return v;
}
firstMap();

function hasIter(x) { return Symbol.iterator in x; }
hasIter([1]);
=== firstSet ===

call@L5 () => "a"

=== firstMap ===

call@L11 () => 1

=== hasIter ===

call@L14 ([1]) => true

原始值转换与解析​

全局强制转换构造器与数值解析器在字面量上折叠为精确结果——调用点与 @nudo:case 两条路径皆然:

function strOf(x) { return String(x); }
strOf(5); // → "5"

function boolOf(x) { return Boolean(x); }
boolOf("hi"); // → true

function numOf(x) { return Number(x); }
numOf("42"); // → 42

function intOf(s) { return parseInt(s); }
intOf("42px"); // → 42

function floatOf(s) { return parseFloat(s); }
floatOf("3.14"); // → 3.14
=== strOf ===

call@L2 (5) => "5"

String(x)、Number(x)、Boolean(x) 把 number/string/boolean 字面量折叠为精确强转结果;parseInt(s) / parseFloat(s) 把 string/number 字面量折叠为精确数值前缀/解析结果。符号实参拓宽为目标原语(string / number / boolean)。仓库示例(CI 钉住):docs/examples/algebra/l-primitive-conversion.js。

方法调用与 this​

在函数体内进行的方法调用会把 this 绑定到 receiver——调用点与 @nudo:case 两条路径皆然。

class Circle {
constructor(r) { this.radius = r; }
area() { return this.radius * this.radius; }
}

function compute(r) {
const circle = new Circle(r);
return circle.area();
}
compute(5);
=== compute ===

call@L11 (5) => 25

指令路径在实参为字面量时同样精确(对 compute 写 @nudo:case "member" (5) → (5) => 25);空实参表 () 时形参是 unknown,结果退化为 unknown #partial。成员调用(circle.area()、obj.method())会作为调用点采集(Class.method / 裸 method),与具名调用一样合成 call@ case。

递归按调用点展开​

递归函数按观测到的调用求值:每个顶层调用被完整展开,作为独立的 call@ case 报告精确结果。

function walk(n) {
if (n <= 0) return 0;
return n + walk(n - 1);
}

walk(0);
walk(1);
walk(2);
=== walk ===

call@L6 (0) => 0
call@L7 (1) => 1
call@L8 (2) => 3

超过精确 case 上限的更多调用会聚合为一个实参拓宽的 call@symbolic case。

字面量相等、JSON.parse、数值格式化、**​

求值器在调用点路径与 @nudo:case 下执行的更多字面量折叠:

function eqCheck() { return 1 == "1"; }
eqCheck(); // → true

function jp() { return JSON.parse('{"port": 3000}'); }
jp(); // → { port: 3000 }

function fixed(cents) { return (cents / 100).toFixed(2); }
fixed(1050); // → "10.50"

function pow(x) { return x ** 2; }
pow(3); // → 9
  • == / != 在字面量操作数上折叠(1 == "1" → true、1 != "1" → false)。
  • JSON.parse 对字面量字符串折叠为解析出的对象形状。
  • toFixed 在字面量接收者上折叠("10.50");符号接收者拓宽为 string。
  • ** 在字面量操作数上折叠(3 ** 2 → 9);符号操作数拓宽为 number。
  • try/catch 已建模:catch (err) 绑定被抛出的 Abs,所以 throw new Error("boom") 之后 err.message 求值为 "boom"。
  • String.fromCharCode(...) 对字面量码点按 ToUint16 折叠(String.fromCharCode(65, 66) → "AB");抽象实参拓宽为 string。
  • Object.prototype 方法已建模:hasOwnProperty / isPrototypeOf / propertyIsEnumerable / valueOf / toString 在具体形状、元组、数组、字符串装箱上按自有槽/下标/length/holes 判定;Object.prototype.hasOwnProperty.call(o, k) 同语义;Object.create(null) 无这些方法(TypeError)。
  • Symbol() / Symbol("desc") 产生非具体 unique symbol:typeof 为 "symbol",.description 为字面量或 undefined,两个 Symbol() 的 === 为 false、同引用为 true;String(sym) 给出 Symbol(desc),隐式 ToString(+ / 模板)抛 TypeError。

收窄守卫​

=== 比较、typeof、Array.isArray 与 switch 按具体调用点收窄——已验证模式见控制流收窄。

尚未建模​

以下构造目前求值为 unknown(通常伴随 nudo:unknown-recv 或 nudo:builtin-unknown 诊断)。请优先使用旁边列出的已建模替代方案。

构造当前行为已建模替代
原始值自动装箱"nudo".constructor → unknown.length、上文的字符串方法
Promise 执行器new Promise((r) => r("done")) → promise<unknown>@nudo:mock + async 函数
箭头 arguments 且外层无直接引用→ unknown(见下文 arguments)具名参数

已建模:arguments(strict/ESM)​

非箭头函数内的 arguments 是已建模的类数组对象(tuple 投影):

模式结果
arguments.length精确实参个数(默认参/rest 不抬高 length)
arguments[i]第 i 个实参;越界 → undefined
typeof arguments"object"
[...arguments] / Array.from(arguments, mapFn)展开实参列表
Array.from(arguments).join(sep)可展开;join 精确折叠仍为抽象 string(既有数组 join 模型)
写 arguments[i] = v不写回形参
写形参不写回 arguments[i]
箭头 () => arguments…外层非箭头函数也直接引用 arguments 时沿词法外层;否则诚实 unknown
默认参arguments.length 只计实参(f() + f(a=1) → 0)
rest 形参arguments.length 为实参个数;rest 绑定路径不变

Nudo 分析按 ESM/strict:arguments 与形参是独立映射。sloppy 非严格是 mapped arguments object(两侧写回互通)——刻意不建模。

已建模:每迭代 let 闭包​

for (let i = …) 每迭代独立绑定——闭包捕获当次 i(fns.push(() => i) 后 fns[0]() / fns[1]() / fns[2]() 分别折 0 / 1 / 2)。for (var i = …) 仍是共享绑定(闭包读到最终值)。forEach((x) => …) 每回调参数语义保持。抽象边界循环在 $for 出口仍保守 join——不假装精确捕获。

Mock 边界(仍建议)​

env 模块与 @types harvester 覆盖了大量常见 Node/Web API,但并不消除对 mock 的需要。下列类别仍建议手写 mock(或保持诚实的 unknown / entry@ 结果)——与 docs/design/limitations.md §2 调用点天花板对齐:

类别为何 mock / 为何 unknown可用办法
Native bindingschild_process.spawn、原生 addon —— env 可有签名(ChildProcess pid/stdio/kill),无副作用模拟@nudo:mock,或把返回值当 opaque
动态 require字面量 / 常量折叠子集已解析;计算说明符诚实 unknown + nudo:builtin-unknown@nudo:mock-module / 静态 import
流机器回调Node Transform 内部由运行时驱动,无调用点记录可 harvest;transform/flush 钩子形参已可 refinemock 流工厂;不要期望内部回调被推断
browser/node 双入口变体调用点记录不跨文件(归因按文件)分析实际发布的入口;另一入口 mock
无调用现场的函数测试未触达的内部 helper → entry@ 兜底补调用现场,或接受 entry@ 为诚实结果
Promise executor 内部new Promise((r) => r(...)) → promise<unknown>@nudo:mock + async 包装

覆盖基线(pnpm run coverage:env → docs/reports/env-coverage-baseline.md)报告的是解析率,不是完备性。不要把高解析率当成 soundness 保证——另见 harvester API 中的 mock 边界。

小结​

能力示例结果
字符串方法"hello".toUpperCase()"HELLO"
具体边界循环sumTo(5)10
break循环跳出值3
Object.keys具体形状["port", "host"]
递归walk(2)3
字面量折叠1 == "1" · JSON.parse('{"port": 3000}') · 3 ** 2true · { port: 3000 } · 9
收窄typeof / === / Array.isArray / switch逐调用点精度

下一步​

  • Abs —— 这些规则背后的类型系统
  • 控制流收窄 —— 何处按调用点收窄
  • Mocking —— 外部依赖处的边界
  • 边界 —— 引擎不宣称什么