nudo contract
nudo contract 管理契约表面(*.nudo.js 侧车 + 源码内 @nudo:contract)。它不替代 nudo check —— check 是 CI 门禁;contract 负责打印、起草与固化义务。
npx nudojs contract <paths…> [--from paths…]
npx nudojs contract --draft <paths…> [--write] [--fn name] [--json]
npx nudojs contract --emit <paths…> [--fn name] [--all] [--dry-run] [--exit-on-diff]
npx nudojs contract --from-dts <paths…> [--write] [--dry-run]
产品规则: 手写契约即义务。草稿与 @generated 段是可审阅的快照 —— 它们绝不会静默变成 check 错误。
分层
| 层 | 来源 | 迁移动作 |
|---|---|---|
handwritten | *.nudo.js / @nudo:contract | 保留;用 nudo check 执法 |
generated | 调用点域固化进 @generated | 使用变化时用 --emit 刷新 |
implicit | 仅推断 —— 展示用 | 草稿候选 |
打印示例 —— 尚无任何契约时,contract 以 implicit 层展示它观察到的域(lineTotal [implicit] (qty: 3 | 2, price: 4.5 | 10) → 13.5 | 20)。侧车被接受后,同一命令打印 [handwritten] 与已接受的绑定。
npx nudojs contract src/lib.js
观察层 → 草稿(逻辑优先)
npx nudojs contract --draft src/lib.js
npx nudojs contract --draft --write src/lib.js --fn lineTotal
输出落在 src/lib.nudo.draft.js —— 不会 ambient 加载。将审阅过的行拷入 src/lib.nudo.js。
草稿里每个槽位都带证据标签,标明约束的来源:
| 证据 | 来源 | 落进草稿的内容 |
|---|---|---|
callsite | 真实调用点观测到的实参 —— 文件内,或经 --from <paths…> 从使用处文件注入 | fn({ … }) 行里一条加宽后的约束;原始观测保留为 /* observed … */ 注释 |
directive | 函数上声明的 @nudo:case 见证 | 与 callsite 同一条投影路径 —— 二者合称最佳起点 |
body | 实现读取的字段(user.name) | 仅一条注释建议(shape({ name: /* TODO */ }))—— 绝不进 DSL 义务 |
symbolic | 泛化返回 shape(generalizeFromAst) | 返回槽注释;返回类型手工补 |
| (省略) | 完全无证据 | 槽位不写入 fn({}),留 TODO 注释 |
不变式 —— 草稿永不发明 check 义务。 只有 callsite / directive 证据会投影进 DSL,且投影前先加宽(lit(3) + lit(2) → number()),单次演示调用绝无可能固化成硬契约。body 读取与 symbolic 返回停留在注释层(C0:禁止从 body AST 扫描发明义务)。从未被调用的导出,其返回槽可能打印 /* observed: string() — confirm before accepting */ —— 那是供你确认的求值事实,不是义务。手写契约永不被覆盖:已在 *.nudo.js 绑定的函数会列为 [handwritten] skipped。
人工审阅把 number() 收紧为 number().gt(0) 等。只有被接受的侧车才是 L1。
Playground 草稿故事 · 示例:docs/examples/contract-draft/
完整一圈:草稿 → 收紧 → 接受 → 门禁
在一个小模块上走完整个 Day 1 闭环。从纯 JS 起步 —— 零注解。(尚无契约时,nudo check 展示的是 Day 0 面 —— greet(user: any) => string throws TypeError,L2 入口 may-throw,因为 .name 读自无约束参数;完整故事见 nudo check。)
export function lineTotal(qty, price) {
return qty * price;
}
export function greet(user) {
return `Hello, ${user.name}`;
}
export function tag(label) {
return `[${label}]`;
}
lineTotal(3, 4.5);
lineTotal(2, 10);
1. 从证据起草。 --draft --write 把可审阅草稿落盘(Draft written → src/lib.nudo.draft.js);草稿模块内联展示每个证据标签 —— 头部从略,其内容重申该文件不是侧车、并重申证据策略:
import { fn, number, shape } from "@nudojs/core";
// lineTotal — param: callsite, return: callsite
// qty: number() /* observed: union(lit(2), lit(3)) */
// price: number() /* observed: union(lit(4.5), lit(10)) */
export const lineTotal = fn({ qty: number(), price: number() }, number());
// greet — param: body, return: symbolic
// user: /* body-read shape({ name: string() }) */
// suggested (uncomment to accept — body-read, not a contract):
// export const greet = fn({ user: shape({ name: string() }) });
// returns: /* symbolic: string — greet: (user: A1) => string */
export const greet = fn({});
// tag — param: none, return: body
// label: /* no evidence — tighten */
// returns: /* observed: string() — confirm before accepting */
export const tag = fn({});
拿证据表对照这三个函数:lineTotal 有真实调用点,参数与返回都被投影(加宽)。greet 从未被调用 —— 只有 body-read 建议与符号返回,DSL 因此保持 fn({})。tag 完全无证据;连它的观测返回都是确认后再接受的注释。
2. 人工收紧并接受。 逐行审阅,把你有意要求的部分加强,然后把结果拷进 src/lib.nudo.js —— 这个拷贝动作就是接受:
// src/lib.nudo.js — accepted after review
export const lineTotal = fn({ qty: number().int().gt(0), price: number().ge(0) }, number());
export const greet = fn({ user: shape({ name: string() }) }, string());
export const tag = fn({ label: string() }, string());
审阅在此处做的改变:qty 从加宽的 number() 收紧为 number().int().gt(0)(数量是正整数 —— 草稿无从知晓这一点);greet 的 body-read 建议 { name } 提升为真正的 shape 义务,同时消除 L2 throw;tag 的无证据槽位由人工填为 string()。
3. 门禁。 被接受的侧车自动绑定,check 转绿 —— 签名展示的是受约束后的面:
nudo check src/lib.js
OK
0 error · 0 warning · 0 info · 3 fn
signatures
lineTotal(qty: number, price: number) => number
greet(user: { name: string }) => string
tag(label: string) => string
4. 故意打破。 违反收紧后 pred 的调用以 1 error 让门禁失败(L1)—— 这是你接受的义务,不是草稿发明的:
lineTotal(-1, 5); // ⊭ qty > 0 → nudo:constraint-violated
issues
[ERROR L16 lineTotal] lineTotal[qty]: argument ⊭ precondition (nudo:constraint-violated)
actual: -1 #exact
expected: qty > 0
→ use a value satisfying qty > 0, or relax the precondition on qty
契约优先(契约层风格)
先手写侧车,再在同一契约面下实现:
// contract.nudo.js
import { number, fn } from "@nudojs/core";
export const positive = number().gt(0);
export const add2 = fn({ x: number().gt(0) }, number());
侧车中的函数绑定必须是一等 fn({ params }, returns?)。裸的 number().gt(0) 是值级模板(供 @nudo:contract / 共享槽使用),不是函数导出契约——上面 positive 是模板,add2 是绑定。
有限数(number().finite())
number() 包含 NaN 与 ±Infinity。因此顺序守卫
if (x < 1) return 0; return x + 1; 不能假设 x >= 1:NaN < 1 为假,
后续路径可能算出 NaN。当函数体的算术依赖守卫的补集时,把这条证据显式写出来:
export const amount = number().finite().ge(0);
有 number().finite()(或任意数值界——它本身就排除 NaN)时,求值器会在
运行时收紧后续路径(x >= 1);没有证据时同样的代码保持 unproven。
.finite() 只对数值链合法。
NaN 守卫提供同一类证据:Number.isNaN(x)、x !== x、x === x、
Number.isFinite(x)(仅真臂)与 !Number.isNaN(x) 在成立的那一臂上确立
x 不是 NaN(含 if (!Number.isNaN(x)) { … })。const / let / var 别名同样可用(别名与被守卫变量都不得被改写):
const ok = Number.isNaN(x); if (!ok) { … }。模块顶层的别名同样解析。
源码内形态:
/// @nudo:import { positive } from "./contract.nudo.js"
/**
* @nudo:contract x positive
*/
export function needsPositive(x) {
return x;
}
needsPositive(-1); // ⊭ x > 0 → nudo:constraint-violated
@nudo:contract 引用的模板必须用 @nudo:import 引入 —— 侧车只自动绑定同名 fn 导出。
@nudo:contract 是唯一的源内契约指令(历史拼写 @nudo:refine / @nudo:interface 已移除,没有别名层)。产品名:contract。
递归模板(lazy)
自引用结构 —— AST 节点、链式结构 —— 不再需要手写有限层嵌套。lazy(() => tpl) 把引用延迟:侧车以真实 JS 执行,thunk 只在契约被消费时求值,此时 const 已完成初始化(issue #120):
// ast.nudo.js — recursive AST template (issue #120)
// (builders are injected into sidecar execution; import kept in real files)
export const astNode = shape({
type: string(),
name: string().optional(),
computed: boolean().optional(),
object: lazy(() => astNode).optional(),
property: lazy(() => astNode).optional(),
callee: lazy(() => astNode).optional(),
arguments: array(lazy(() => astNode)).optional(),
});
export const staticName = fn({ node: nullable(astNode) }, nullable(string()));
lazy 模板按固定层数预算展开(顶层之下三层)。预算耗尽的字段成为缺席槽 —— 与手写有限层模板的产物完全一致 —— 因此守卫递归在边界处照常干净剪枝,而不是退化成 any:
export function deepType(node) {
if (node == null) return null;
const inner = node.object;
if (inner == null) return null;
const deep = inner.object;
if (deep == null) return null;
return deep.type; // 预算内 → null | string
}
lazy 与其他构建器一样是侧车构建器:接收一个 thunk(() => constraint),随侧车执行注入。源内指令文法不接受箭头函数,因此 @nudo:case / @nudo:mock 表达式用不了它(这类实参回落 unknown)—— 递归模板住在 *.nudo.js 里。
固化生成段
--emit 把观测到的调用点域固化进侧车 @generated 段 —— 关于用法的事实,不是义务。可信用法(演示调用、测试)用它;要执法的 API 面保持手写绑定。一个尚无契约的叶子模块:
export function wrap(text) {
return `(${text})`;
}
wrap(42);
固化观测域(默认模式只刷新已有段;--fn / --all 创建新段):
npx nudojs contract --emit src/tags.js --fn wrap
Updated src/tags.js → src/tags.nudo.js
written: wrap
re-run `nudo check src/tags.js` to see the persisted contracts in action
侧车此刻携带快照 —— 注意它固化的是观测到的精确字面量,与草稿的加宽不同:
// @generated by nudo — do not edit; regenerate with `nudo contract --emit`
// source: tags.js:wrap
// evidence: local
export const wrap = fn({ text: lit(42) }, lit("(42)"));
漂移
数周后演示调用变了 —— 如今跑的是 wrap("hot") 而不是 wrap(42):
export function wrap(text) {
return `(${text})`;
}
wrap("hot");
check 把已固化段与今日重算的域对比并警告 —— 调用本身不是错误,因为 generated 永不执法:
nudo check src/tags.js
OK
0 error · 2 warning · 0 info · 1 fn
signatures
wrap(text: number) => string
issues
[WARNING L5 wrap] wrap[text]: persisted @generated segment ≠ today's call-site domain (nudo:contract-drift)
→ re-run nudo contract --emit to refresh the generated segment, or check the call sites of text
[WARNING L5 wrap] wrap[return]: persisted @generated segment ≠ today's inferred return (nudo:contract-drift)
→ re-run nudo contract --emit to refresh the generated segment, or check the return value
nudo:contract-drift 是 warning —— 不挡 exit(上面这次运行退出码为 0)。新用法是有意的就刷新(nudo contract --emit src/tags.js 打印同样的 Updated … written: wrap 摘要,段变为 fn({ text: lit("hot") }, lit("(hot)")));证据未变时重跑为 no-op(src/tags.js: no contract changes)。
CI 漂移门禁
要让「本应刷新」在 CI 里可见,把 emit 当作 diff 即失败的 dry-run 跑:
npx nudojs contract --emit src/tags.js --dry-run --exit-on-diff
[dry-run] would update src/tags.js:
--- a/src/tags.nudo.js
+++ b/src/tags.nudo.js
@@ -1,4 +1,4 @@
// @generated by nudo — do not edit; regenerate with `nudo contract --emit`
// source: tags.js:wrap
// evidence: local
-export const wrap = fn({ text: lit("hot") }, lit("(hot)"));
+export const wrap = fn({ text: lit(7) }, lit("(7)"));
命令退出码为 1 —— 维护者在本地刷新并提交。--exit-on-diff 必须搭配 --emit --dry-run(裸传 --exit-on-diff 是用法错误);手写绑定始终优先 —— emit 若会覆盖某条绑定,会报 nudo:contract-name-clash 并跳过写入。使用处文件可以供证据:contract --emit src/lib.js --from test/(见调用点发现)。
逆向 TypeScript 声明(--from-dts)
正在迁出 TypeScript?--from-dts 把 .d.ts 文件、带注解的 .ts / .mts 源、目录、或 npm 包的类型逆向成可审阅的 @nudo:draft —— 这是 TypeScript 退役路径中的契约步骤。一个小型遗留模块:
export interface User {
id: number;
name: string;
}
export function lineTotal(qty: number, price: number): number {
return qty * price;
}
export function badge(user: { name: string; admin?: boolean }): string {
return user.admin ? `[${user.name}]` : user.name;
}
export function findUser(id: number): User {
return { id, name: "n" };
}
npx nudojs contract --from-dts legacy/pricing.ts
// @nudo:draft
// Generated by `nudo contract --from-dts` from pricing.ts
// Sources: pricing.ts
//
// Reverse-engineered from TypeScript declarations — NOT a sidecar contract.
// This file is never loaded for check. Review each export, then copy it
// into <target>.nudo.js to accept (that is when obligations go live).
//
// After accept: strengthen with Pred builders (number().gt(0) …) —
// dts cannot express algebraic implications (x>0 ⇒ x+1>1).
import { fn, number, string, boolean, any, shape } from "@nudojs/core";
// lineTotal — from TypeScript
export const lineTotal = fn({ qty: number(), price: number() }, number());
// badge — from TypeScript
export const badge = fn({ user: shape({ name: string(), admin: boolean().optional() }) }, string());
// findUser — from TypeScript
export const findUser = fn({ id: number() }, any());
// 3 projectable exports · 0 skipped · 1 d.ts
// pass --write to save as pricing.nudo.draft.js; copy into *.nudo.js to enforce
诚实地读这份投影:基元、字面量联合、数组与对象字面量映射为构建器;可选字段(admin?: boolean)变成 boolean().optional();但 findUser 的 User 返回退化为 any() —— 未建模的类型引用,如实标注而非猜测。interface 与 type alias 整体跳过(类型不是运行时契约)。
--from-dts 不执法。 草稿只打印(或经 --write 落为工作目录里的 pricing.nudo.draft.js —— next review, then copy exports into a *.nudo.js sidecar to accept (not enforced until then)),永不 ambient 加载。审阅后把接受的导出拷进 *.nudo.js 侧车,它们才成为 L1 —— 那也是加强 .d.ts 永远表达不了的东西的时刻:qty: number 对正负只字未提,number().int().gt(0) 才有(Pred 进入 Abs 参与代数 —— x>0 ⇒ x+1>1)。
旗标
| 旗标 | 配合 | 效果 |
|---|---|---|
--draft | — | 从现有代码打印可审阅草稿(代码优先) |
--write | --draft / --from-dts | 把 *.nudo.draft.js 写入磁盘 |
--emit | — | 写入/更新 @generated 段(默认:只刷新已有段) |
--fn <name> / --all | --draft / --emit | 限定导出名 / 目标为全部导出 |
--from <paths…> | 打印 / --draft / --emit | 供域证据的使用处文件 |
--from-dts | — | 逆向 .d.ts / 带注解 TS / 包类型为草稿(不执法) |
--dry-run | --emit / --draft --write | 只打印不写盘 |
--exit-on-diff | --emit --dry-run | 侧车将变化时退出码 1 |
--json | 打印 / --draft / --emit | 供 agent 审阅的 JSON 数组。顶层恒为数组(每个输入一个元素);--draft 下每个元素是 { file, draftPath, draftSource, diff, entries[] },--emit 下是 { file, sidecar, changed, written, skipped[], issues[], diff? },打印形态是 { file, entries[] }。失败的目标贡献 { file, errors: [{ code, message }] },用法 / 路径错误贡献 { pathErrors: [{ path, code, message, suggestion }] }。 |
打印 / --draft / --from-dts 仅在用法 / IO 错误时失败;--emit 另在 --exit-on-diff 且有 diff 时失败 —— emit 期间看到的分析诊断只打印,绝不挡 exit。完整表:CLI Reference。
用 check 门禁
同名侧车 *.nudo.js 自动绑定到 calc.js 导出,作为 L1 进入 nudo check。
npx nudojs check src/
见 nudo check 与诊断术语表。
下一步
- 迁移现有 JS —— 完整 draft → accept → CI 路径
- 从 TypeScript 迁移 —— 退役流水线中的
--from-dts - Recipes —— 渐进契约、monorepo
- 指令 ——
@nudo:contract文法 - 边界 —— promote ≠ 义务;诚实边界