CLI 使用指南
nudo CLI 在 .js / .mjs / .ts 上的任务型导览。通过 npx 使用——见安装。完整 flag / 退出码表: CLI 参考。
一级动词
nudo — JavaScript types, computed
nudo check <path> [--watch|-w] # 门禁契约 + 入口 throws;打印 signatures
nudo test <path> [--watch|-w] # 报告全部推断用例;断言已声明期望
nudo contract <path> # 契约:打印 / draft / emit 侧车契约
nudo export <path> # 投影:dts / guard / schema / standard
nudo health [paths] # 体检:分析错误 + 固化漂移
观察落在 check / test 的输出与 IDE hover,不设独立观察动词。
初始化: nudo init [path] —— 向最近的 package.json 写入 adoption 基线(nudo.check.profile: "adoption")。幂等:已存在 nudo 键时只打印、绝不覆写;形状非法的 nudo 值(null / 标量 / 数组)被替换成基线并告警;祖先 package.json 已有可继承的 nudo 配置时拒绝写遮蔽键(exit 1);最近的 package.json 是 workspace / 容器根时拒绝越界写盘(exit 1)。显式指向容器根的 nudo init <容器根> 会写入基线并给作用域告警;只有「从子目录越界写」才拒绝。零配置、零指令项目里 nudo check 失败时会打印 onboarding 块指向这里。
观察层: nudo check(签名 + 门禁)。可选调试:nudo test(用例见证)。
契约层: nudo contract + nudo check。
生态: nudo export。
离 tsc: nudo migrate(单向 status → strip → verify → retire)。
| 想知道什么 | 跑什么 |
|---|---|
| 入口签名 / any / unknown / throws | nudo check <path>(成功也打印 signatures) |
| 逐调用点真值 / 窄化结果 | nudo test <path>(打印全部 case,含合成 call@ / entry@) |
| 使用处实参形态 | nudo check / test / contract --from <paths…> |
代数面(shape + conf;--generalize 附加 term/pred α) | nudo check --abs(或 test --abs) |
| 机器可读 | nudo check --json / nudo test --json |
| 交互 | IDE hover / inlay |
nudo check
门禁契约与入口 throws。成功与失败都会打印 signatures —— 不是静默。
nudo check <path> [--watch|-w] [--json] [--quiet] [--verbose] [--abs]
[--from paths…] [--ignore-throws names] [--entry-throws error|warning|off]
[--profile adoption|strict] [--capabilities strict|trusted] [--gha] [--gitlab] [--what-if name:type… [--target name]]
其余旗标各一句(完整表见 CLI 参考):
--profile adoption|strict—— 门禁 profile(默认strict):adoption把 L2 入口 may-throw 降为 warning、L1 仍为 error;显式--entry-throws值可覆盖。--quiet—— 压制 signatures 表(issues + summary + 门禁退出码不变;干净文件只打一行摘要),大仓 CI 日志降噪。--gha—— GitHub Actions 行内注解(::error/::warning);GITHUB_ACTIONS=true时自动启用。--gitlab—— GitLab Code Quality JSON 数组打到 stdout;CI 中重定向为gl-code-quality-report.json。--what-if <name:type…>—— 假设name:type绑定(如raw:string);配合--target <name>打印该绑定的推导类型(AI3)。
nudo check user.js
nudo check user.js
FAILED
2 error · 0 warning · 0 info · 3 fn
signatures
getName(user: any) => any throws TypeError
subtract(a: any, b: any) => number throws TypeError
clamp(n: any, lo: any, hi: any) => any
issues
[ERROR L1 getName] getName (export): may throw TypeError (nudo:entry-may-throw)
…
[ERROR L5 subtract] subtract (export): may throw TypeError (nudo:entry-may-throw)
…
摘录 —— 完整 transcript、user.js 源码与修复路径见 nudo check。
无约束入口参数显示为 any。unknown 表示推导失败(引擎债)—— 绝不是无约束入口参数的默认值。[ERROR L# name] 中 L# 是违规调用/声明的行号,不是契约层(L1/L2 才是层)。上方示例打印 L1 是因为该文件中 getName 声明在第 1 行 —— 其层是 L2。
- 语义(L1 显式契约 / L2 入口 throws、退出码、过滤):nudo check
- 选项与配置(
--watch/--json/--quiet/--abs/--from/--ignore-throws/--entry-throws/--profile/--gha/--gitlab/--what-if、package.json#nudo.check):CLI 参考
nudo check 是 CI 门禁。
nudo test
报告全部推断用例,并运行已声明的 @nudo:case 断言。
nudo test <path> [--watch|-w] [--from paths…] [--freeze[=mode]] [--dry-run] [--exit-on-diff] [--json] [--abs]
给定 math.js:
export function subtract(a, b) {
return a - b;
}
subtract(5, 3);
subtract(1, 10);
nudo test math.js
=== subtract ===
call@L5 (5, 3) => 2
call@L6 (1, 10) => -9
assertions
— 0 passed · 0 failed · 0 unchecked (no declared @nudo:case expectations; 2 synthetic case(s) printed above)
- 合成
call@/entry@默认打印 —— 这就是调用点观察面。 - 已有使用处
call@时,分析器不会再合成entry@。 - 仅
@nudo:case且带=> expected的进入 pass/fail;失败影响退出码。 --from <paths…>挖掘使用处调用形状。--freeze[=mode]把合成用例固化为指令:--freeze(不给值,add 模式)新增见证;--freeze=update重同步此前生成的指令。--dry-run(配合--freeze)打印 unified diff 而非写盘;--exit-on-diff(配合--freeze --dry-run)在 diff 非空时 exit 1。--json/--abs与check对齐;test --json含assertions摘要(passed/failed/unchecked),声明断言失败仍 exit 1。
完整走读 —— 合成用例生命周期、--freeze 工作流、断言编写:nudo test。
带声明断言的示例
/**
* @nudo:case "double" (2) => 4
*/
export function double(x) {
return x * 2;
}
nudo test file.js
=== double ===
debug "double" (2) => 4
assertions
✓ 1 passed · 0 failed · 0 unchecked
[ok] double case "double" → 4
nudo contract
打印、草稿或固化有效契约(handwritten / generated / implicit 分层)。
nudo contract <path> [--emit] [--draft] [--write] [--fn name] [--all]
[--dry-run] [--exit-on-diff] [--from paths…] [--from-dts]
nudo contract src/lib.js # 打印有效契约
nudo contract --draft src/lib.js # 可审阅的 *.nudo.draft.js
nudo contract --draft --write src/lib.js # 写盘草稿
nudo contract --from-dts ./my-pkg/src/index.ts # 把 .d.ts / TS 注解逆向为可审阅草稿
nudo contract --emit src/lib.js --fn add2 # 持久化 @generated 侧车段
nudo contract --emit src/lib.js --all --dry-run --exit-on-diff # CI 漂移门禁
- 手写侧车绑定始终优先于生成段。
--emit --exit-on-diff:将写盘且有 diff 时退出1。- 使用处证据:
--from <paths…>。 --from-dts <paths…>:把 TypeScript.d.ts/ 包类型逆向为可审阅的@nudo:draft—— 复制进*.nudo.js前不执法(TS 退役路径上的契约步骤,见从 TypeScript 迁移)。
nudo export
把 Abs 投影为生态产物。这是 CLI 上 .d.ts / guard / schema 投影的唯一路径。
nudo export <path> [--format dts|guard|schema|standard|all] [--dialect zod] [--out dir]
nudo export src/user.js --format dts --out dist/types
nudo export src/user.js --format schema --dialect zod
nudo export src/user.js --format standard --out dist
nudo export src/user.js --format all --out dist
| 格式 | 产物 |
|---|---|
dts | TypeScript 声明(每函数一条拓宽签名;case 精度保留在 JSDoc) |
guard | 运行时类型守卫 |
schema | 某 dialect 的 schema 源码投影(默认 dialect:zod)→ *.nudo.schema.<dialect>.ts |
standard | Standard Schema v1 运行时模块(~standard,vendor nudo)→ <fn>.nudo.standard.ts |
all | dts + guard + schema + standard |
--dialect 当前接受 zod。Abs 上可表达的常数界 / int / 字符串长度界会落入 schema;落不了的 pred 保留在基类型上,并列在 dropped preds 注释里。
.d.ts 与 schema 都是单向、有损投影 —— Abs 才是真理源。export 是一次性出货命令,不接受 --watch。
逐格式语义与退出码:CLI 参考。
nudo health
项目体检:分析错误与固化漂移。
nudo health [paths…] [--watch] [--from paths…] [--json]
漂移、分析错误或 --from 缺文件时退出 1;--json 下路径错误进顶层 pathErrors[] 并强制 ok: false。uncovered 函数仅为信息级。
nudo health src/ --from tests/
生成的 call@ 指令会变化时,health 报告漂移并建议:
nudo test lib.js --from test.js --freeze=update
典型工作流
观察层 —— 从现有 JS 读类型
nudo check src/app.js # 签名 + L2 入口 throws(门禁)
nudo test src/app.js # 可选调试:全部调用点用例
契约层 —— 显式契约
nudo contract --draft src/lib.js --write # 可审阅草稿
nudo check src/lib.js # L1 + L2 门禁
CI
nudo check src/ --json
# 迁移期可忽略噪声 L2 类型
nudo check src/ --ignore-throws TypeError
生态类型
nudo export src/api.js --format dts --out dist/types
持续开发
nudo check src/ --watch
# 或
nudo test src/ --watch
any 与 unknown
无约束入口参数显示为 any;unknown 表示推导失败(引擎债),绝不能被叙述为无约束参数的默认值。完整契约(来源、运算、窄化、产品话术)见 Abs — any vs unknown。
退出码
逐命令退出契约:CLI 参考。CI 门禁只认 check(及 test 的声明断言、health 的 drift)。
下一步
- 心智模型 —— 产品面
- nudo check —— CI 门禁详解
- CLI 参考 —— 每个 flag 与退出码
- 示例 —— 真实 check/test 输出