nudo check
nudo check 是 Nudo 在 Abs 上的门禁。它执法:
- L1 显式契约 —— 来自
*.nudo.js/@nudo:contract的约束(Abs 上的 Pred 蕴含) - L2 默认 JS 契约 —— 入口/导出函数上未消化的 may-throw
报告是 Nudo 原生的(actual ⊭ expected),不是 TypeScript 诊断的伪装。成功与失败都打印 signatures —— 不是静默。
npx nudojs check path/to/file.js
# 任一 error 则 exit 1
nudo check <path> [--watch|-w] [--json] [--quiet] [--verbose] [--abs]
[--from paths…] [--ignore-throws names] [--entry-throws error|warning|off]
[--profile adoption|strict]
check 校验 Abs(实线);export 单向有损投影 dts/guard/schema(虚线)。没有东西读回投影。
默认输出(signatures + issues)
export function getName(user) {
return user.name;
}
export function subtract(a, b) {
return a - b;
}
nudo check user.js
nudo check user.js
FAILED
2 error · 0 warning · 2 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)
actual: getName(user: any) => any throws TypeError
expected: entry total, or @nudo:throws / try-catch
→ property 'name' on any (unconstrained value) → @nudo:throws TypeError | sidecar: fn({ … }): shape({ <body-read fields> }) | refine / guard / try-catch
fix: nudo contract --draft (emit a sidecar draft you can edit)
[ERROR L5 subtract] subtract (export): may throw TypeError (nudo:entry-may-throw)
actual: subtract(a: any, b: any) => number throws TypeError
expected: entry total, or @nudo:throws / try-catch
→ ToNumber coercion of abstract operand → @nudo:throws TypeError | sidecar: fn({ … }): shape({ <body-read fields> }) | refine / guard / try-catch
fix: nudo contract --draft (emit a sidecar draft you can edit)
[INFO L1] export 'getName' has no contract root and no call-site domain (entry-only) (nudo:contract-entry-only)
[INFO L5] export 'subtract' has no contract root and no call-site domain (entry-only) (nudo:contract-entry-only)
onboarding
every error above is an L2 entry may-throw — unconstrained entry points, not broken contracts.
no @nudo:* directives and no package.json#nudo config found in this project yet. next steps:
nudo init write an adoption baseline config (L2 → warning)
nudo contract --draft <file> draft a *.nudo.js sidecar contract for one file
nudo check --profile adoption preview the gate with L2 as warnings
onboarding 块只在整场运行「纯净」时打印——零 @nudo:* 指令、零 nudo 配置,且所有 error 都是 L2。它不改变退出码,出现任一指令或配置后即消失。
[ERROR L1 getName]里的L1是行号(此处函数声明在第 1 行)—— 该诊断的层是 L2(nudo:entry-may-throw)。L#永远是位置,不是契约层。
- 无约束入口参数显示为
any。 unknown表示推导失败(引擎债)—— 绝不是无约束入口参数的默认值。- 存在 throws 时必须上屏。
[ERROR L# name]——L#是违规调用/声明的行号,不是契约层(L1/L2 才是层;L#是位置)。
检查什么
| 码 | 层 | 严重级别 | 含义 |
|---|---|---|---|
nudo:constraint-violated | L1 | error | 调用/返回 ⊭ @nudo:contract(标量界 / shape 字段) |
nudo:assign-mismatch | L1 | error | 赋值 ⊭ 原绑定 shape(leqAbs) |
nudo:arg-structure | L1 | error(显式契约)/ warning(body-promote) | HOF:实参不是可调用 fn / 元数不匹配。用法驱动的 body 提升是警告建议;只有显式关系契约才升级为 error |
nudo:case-inconsistency | L1 | error | @nudo:case 见证 ⊭ refine |
nudo:constraint-unproven | L1 | warning | 无法证明实参满足契约 Pred(cannot prove … x > 0)—— 悬而未决,不是失败。补调用点 / @nudo:case,或用 --assume 声明前置条件 |
nudo:arg-opaque | L1 | warning | 实参 Abs 是 unknown(无 term)—— 约束根本无法检查。补调用点 / @nudo:case / --assume,或建模该值来源 |
nudo:arg-count | L1 | error | 调用元数与泛化参数面不匹配 |
nudo:fn-not-found | L1 | error | 调用引用了分析器在作用域内无法解析的函数 |
nudo:partial-result | L1 | info | 结果 Abs 携带 #partial 置信 —— 仅观察 |
nudo:contract-param-mismatch | L1 | error | 手写契约参数名不在形式参数面上 |
nudo:contract-conflict | L1 | error | 手写契约合取不可满足 |
nudo:contract-load | L1 | error | 侧车文件加载失败(解析 / import / 路径解析错误) |
nudo:contract-name-clash | L1 | error | 侧车导出名与源码导出冲突,或 emit 会覆盖手写绑定(手写优先,跳过写入) |
nudo:contract-cycle | L1 | error | 侧车 @nudo:import 链成环 |
nudo:contract-domain-exceeds | L1 | error | 经 --from 注入的调用记录 ⊄ 手写契约域 |
nudo:contract-drift | L1 | warning | 固化 @generated 段 ≠ 今日重算契约(nudo health 亦上浮;不挡 exit) |
nudo:contract-entry-only | L1 | info | 导出无契约根且无调用点域(仅合成 entry@)—— 覆盖缺口,不是门禁失败 |
nudo:dual-entry | L1 | info | browser/node 双入口:调用点记录不跨文件 —— 分析只观察一个入口变体 |
nudo:contract-emit-denied | L1 | warning | contract --emit 目标在 package.json#nudo.contract.emit 允许列表之外 —— 跳过写入 |
nudo:contract-multi-declarator | L1 | warning | @generated 段被手工合并成多声明导出 —— 原样保留 |
nudo:contract-not-projectable | L1 | error | 组装侧车 round-trip 重解析失败 —— 不写任何文件(引擎债) |
nudo:entry-may-throw | L2 | error(默认) | 入口/导出函数有未消化 may-throw |
nudo:module-throw | L2 | error(默认) | 模块顶层代码必然抛(句法上无条件的 throw)⇒ 模块永远无法被导入、未被分析 —— 所有导出都不可用。fail-closed;每模块一条;与 nudo:internal(引擎回落)、nudo:unsupported:*(能力边界)都不是一回事 |
nudo:may-throw | test / L2 线索 | warning | case 路径可能抛(含内部);L2 可升格入口 throws |
nudo:unknown-inference | 引擎债 | warning | 签名出现真 unknown(推导失败)—— 入口无约束参数是 any,不走此码 |
nudo:unknown-recv | 引擎债 | warning | unknown 接收者成员访问 —— 不得替代 L2 throws 建模 |
nudo:builtin-unknown | 引擎债 | warning | API 未被 env/推理覆盖(如未建模全局)。优先 @nudo:env / mock |
nudo:opaque-result | 引擎 | info | 求值返回 opaque / 无信息 Abs |
nudo:recursion-truncated | 引擎 | info | 递归求值被截断 —— reason: cycle(同抽象实参在栈上;预算解不开)或 depth/calls(预算用尽) |
nudo:loop-truncated | 引擎 | info | 循环退出条件越过迭代预算仍具体真;循环状态拓宽(不是调用预算) |
nudo:fork-truncated | 引擎 | info | 分支展开($fork)预算用尽;结果拓宽 |
nudo:host-effect-blocked | 引擎 | info | 宿主副作用函数(fetch / 定时器等)分析期不真实执行 —— 结果拓宽为 unknown#opaque。用 @nudo:mock / @nudo:env 打桩 |
nudo:internal | 引擎 | error | 该文件的检查闸门没能跑完(引擎内部回落 —— 例如模块求值失败)⇒ 该文件的导出无法被验证 ⇒ fail-closed:nudo check 以非零码退出、nudo health 报 Result: FAIL。与 nudo:unsupported:*(能力边界)、nudo:opaque-result(推断精度)都不是一回事 |
nudo:no-signature | 引擎/L1 | warning | 函数无法泛化为符号 Abs(CJS/匿名形态仍走入口 fallback 执法 L2) |
nudo:no-method | 引擎 | error(原始类型接收者)/ warning | 成员访问无法解析 —— Method 'x' does not exist on type 'T'。与 nudo:unknown-recv 不同 |
nudo:mock-invalid | 引擎 | warning | @nudo:mock 表达式不是已知形态(stub/spy/mock、箭头函数、类型表达式) |
nudo:env-harvest-conflict | 引擎 | warning | 手写 @nudo:env 与 @types harvest 提供同一模块键 —— 手写优先,harvest 只补缺失槽 |
nudo:contract-underivable | 引擎 | info | 派生契约行无源码证据(opaque / 截断 / 无证据)—— 该行跳过;手写行从不触发 |
nudo-unreachable | info | info | return/throw 之后的代码 |
nudo:module-cycle | 模块图 | warning | 循环模块装载 —— 环内绑定解析为部分求值类型 |
nudo:module-depth | 模块图 | warning | 模块装载链过深 —— 装载截断,更深模块为 unknown |
nudo:module-missing | 模块图 | error | import 了装载器无法解析的模块 —— 修 spec 或 mock(@nudo:mock-module) |
nudo:missing-slot | 求值 | warning(默认 off) | 求值命中闭对象 shape 缺字段(用 nudo.analysis.evalMissingSlot 打开)—— 观察,不凭空产生 check 错误 |
nudo:case-expected | test | error(nudo test 失败) | 声明的 @nudo:case 期望类型 ⊭ 推断结果 —— 合成 call@ / entry@ 永不导致运行失败 |
完整术语表(逐码锚点、最小复现、Abs 视图与修复):诊断术语表。
L1 —— 显式契约
契约由 @nudo:contract 声明 —— 进入 Abs、参与代数的 Pred。
/// @nudo:import { positive } from "./shapes.nudo.js"
/**
* @nudo:contract x positive
*/
function needsPositive(x) {
return x;
}
needsPositive(-1);
// [ERROR L12 needsPositive] needsPositive[x]: argument ⊭ precondition (nudo:constraint-violated)
// actual: -1 #exact
// expected: x > 0
// → use a value satisfying x > 0, or relax the precondition on x
if 不是契约。 未声明 refine 时,clamp 式守卫接受越界输入:
function clamp(n, lo, hi) {
if (n < lo) return lo;
if (n > hi) return hi;
return n;
}
clamp(-5, 0, 10); // OK — no @nudo:contract declared
Nudo 不从 body AST 扫描发明必填 slot。
L2 —— 入口 throws
无显式契约时,契约退化为 JS 运行时边界:
入口参数为
any。对any/可空值的操作可能抛。导出函数不得静默携带未声明、未捕获的 throws。
export function getName(user) {
return user.name; // 对无约束 `user` 的属性访问
}
报告关键行 —— 完整 transcript 见默认输出:
signatures
getName(user: any) => any throws TypeError
subtract(a: any, b: any) => number throws TypeError
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)
提醒:报头里的
L1是行号 —— 该诊断的层是 L2。
L2 门禁什么
- 仅入口/导出函数 ——
export/export default、CJSexports.x =/module.exports。 - 内部 helper 不门禁。 它们可以 throw;在
nudo test中观察。 try/catch消化路径上的 throws(从出口效果中移除)。- 模块装载层:顶层语句序列必然抛(无条件
throw)的模块永远无法被导入 —— 每模块报一条nudo:module-throw(fail-closed:所有导出都不可用、模块未被分析)。条件抛保持静默(取决于宿主);只有句法上无条件的throw语句才算证据 —— 引擎从自身宿主 API 近似推出的抛永不归咎于程序。 - refine 把参数收成 shape 后,L2 消失或降为 L1。
首选修复路径是用 @nudo:throws 在函数上申报有意的 throw —— 完整语法(Error 家族覆盖、* 通配、!! throws 用例后缀、侧车 fn 选项)见指令参考。
过滤 L2
nudo check src/ --ignore-throws TypeError
nudo check src/ --ignore-throws TypeError,RangeError
nudo check src/ --entry-throws warning # 迁移期降级 L2
nudo check src/ --entry-throws off
语义:
--ignore-throws只过滤 L2 入口 throws —— 绝不吞 L1 契约违例。- 默认:不忽略任何 throws。
- 过滤的是 throws 类型/形状,不是整个 check。
把这些持久化到 package.json#nudo.check —— 配置块见 CLI 参考。
门禁 profile:adoption 与 strict
--profile 是L2 命名档 —— 不是关掉门禁的方式:
strict(默认)—— L2entry-may-throw为 error。adoption—— 迁移档:L2 入口 may-throw 降为 warning(exit 0),L1 显式契约违例仍是 error。adoption 绝不吞 L1。
nudo check src/ --profile adoption
把策略固化到 package.json#nudo.check.profile,替代每次传旗标:
{
"nudo": {
"check": {
"profile": "adoption"
}
}
}
L2 entry-throws 严重级按首个命中解析:
- CLI
--entry-throws—— 显式值压过任何 profile - CLI
--profile(adoption→warning,strict→error) package.json#nudo.check.entryThrowspackage.json#nudo.check.profile- 默认
strict(error)
完整旗标 / 配置表见 CLI 参考。
与 Node 类比
未捕获异常使 Node 进程以非零码退出。同样,导出边界上的未声明/未捕获 throws 使 nudo check 失败。内部调用栈中的 throw 是实现细节,由调用方或 L1 处理。
选项
全部旗标与 package.json#nudo.check 配置都在 CLI 参考 里一次性说明。要点如下:
| 选项 | 说明 |
|---|---|
--watch / -w | 变更时重跑(旗标,不是动词) |
--json | 机器可读签名 + 诊断(CheckJson / CheckJsonMulti) |
--quiet | 压制 signatures 表 —— issues + summary + 门禁退出码不变;干净文件只打一行摘要(大仓 CI 日志降噪) |
--verbose | 展开 Abs 签名(term/pred/conf 细节) |
--abs | 逐函数代数面(shape + conf;--generalize 附加符号 term/pred α)——观察面,仍对 L1/L2 执法 |
--fn <name> | 搭配 --abs:限定单个函数 |
--assume <pred…> | 搭配 --abs:对入口参数假设约束(如 x>0 y>=1) |
--generalize | 搭配 --abs:符号执行的多态签名 |
--from <paths…> | 使用处文件注入调用记录 |
--ignore-throws <names> | 逗号分隔、可忽略的 L2 throws 类型 |
--entry-throws error|warning|off | L2 严重级别(默认 error) |
--profile adoption|strict | 门禁档(默认 strict);adoption ≡ L2 entry-throws warning,L1 仍 error —— 见门禁 profile |
--capabilities strict|trusted | 不可信源码的能力档(默认 strict):有副作用的宿主全局与 node: 模块被隐藏(nudo:capability-denied,值 unknown);trusted 退回旧 builtin-unknown 面。不是 sandbox。 |
--gha | GitHub Actions 行内注解(::error / ::warning);GITHUB_ACTIONS=true 时自动开 |
--gitlab | stdout 输出 GitLab Code Quality JSON 数组 —— 重定向到 gl-code-quality-report.json |
契约诊断
侧车 / 契约管线相关码(nudo:contract-*、nudo:dual-entry)已全部列在检查什么。两条归属规则:
- 写在被分析文件内的违例报告
nudo:constraint-violated。 nudo:contract-domain-exceeds覆盖从使用处文件注入的调用记录(nudo check --from <paths...>)。
CI 集成
nudo check 是契约与入口 throws 的 CI 门禁 —— 与 tsc --noEmit 对齐,但 check 成功时仍打印 signatures。--abs 仍是观察面,但 L1/L2 error 仍门禁。退出码:0 = 无 error 级诊断,1 = 任一 error 级诊断(L1 或未 ignore 的 L2)—— 完整表见 CLI 参考。大仓可加 --quiet 让日志只留信号:压制 signatures 表(issues + summary + 门禁退出码不变;干净文件只打一行摘要)。
GitHub Actions
name: nudo-check
on: [pull_request]
jobs:
nudo:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci
- run: npx nudojs check .
诊断以 PR 行内注解(::error / ::warning)落在 Files changed 对应行 —— 无需额外旗标:GitHub runner 会设 GITHUB_ACTIONS=true,--gha 自动生效。环境变量缺失时可显式传 --gha 强制注解;搭配 --json 时 stdout 保持机器契约,注解仍进入日志流(stderr)。
GitLab CI
nudo:check:
script:
- npx nudojs check . --gitlab > gl-code-quality-report.json
artifacts:
reports:
codequality: gl-code-quality-report.json
--gitlab 把 GitLab Code Quality JSON 数组打到 stdout;重定向写出 gl-code-quality-report.json,声明为 codequality 产物后,流水线的 Code Quality 标签页会在 MR diff 上渲染诊断。
# 机器可读(1 文件 → CheckJson;N 文件 → CheckJsonMulti 信封)
nudo check src/lib.js --json
CI 接线配方
Monorepo 扫描根 —— 只门禁源码根,绝不扫 node_modules、构建产物或 vendored 语料:
npx nudojs check packages/*/src
L2 渐进策略 —— L2(nudo:entry-may-throw)默认 error。在遗留 JS 上渐进采用?--profile adoption 只把入口 may-throw 降为 warning,L1 保持 error —— 语义、持久化与解析顺序见门禁 profile:
npx nudojs check . --profile adoption
缓存调参 —— 分析会话缓存是进程内 LRU(默认 64 文件)。CI 并行分析多个项目时封顶;单个大仓调高换 warm 命中:
NUDO_CACHE_MAX_FILES=32 npx nudojs check packages/*/src # 多项目
NUDO_CACHE_MAX_FILES=512 npx nudojs check . # 单个大仓
完整内部设计笔记(仓库内文档,离开本站):docs/ci-nudo-check.md。