跳到主要内容

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 / throwsnudo 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
格式产物
dtsTypeScript 声明(每函数一条拓宽签名;case 精度保留在 JSDoc)
guard运行时类型守卫
schema某 dialect 的 schema 源码投影(默认 dialect:zod)→ *.nudo.schema.<dialect>.ts
standardStandard Schema v1 运行时模块(~standard,vendor nudo)→ <fn>.nudo.standard.ts
alldts + 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)。

下一步​