跳到主要内容

nudo check

nudo check 是 Nudo 在 Abs 上的门禁。它执法:

  1. L1 显式契约 —— 来自 *.nudo.js / @nudo:contract 的约束(Abs 上的 Pred 蕴含)
  2. 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 校验 vs export 投影

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-violatedL1error调用/返回 ⊭ @nudo:contract(标量界 / shape 字段)
nudo:assign-mismatchL1error赋值 ⊭ 原绑定 shape(leqAbs)
nudo:arg-structureL1error(显式契约)/ warning(body-promote)HOF:实参不是可调用 fn / 元数不匹配。用法驱动的 body 提升是警告建议;只有显式关系契约才升级为 error
nudo:case-inconsistencyL1error@nudo:case 见证 ⊭ refine
nudo:constraint-unprovenL1warning无法证明实参满足契约 Pred(cannot prove … x > 0)—— 悬而未决,不是失败。补调用点 / @nudo:case,或用 --assume 声明前置条件
nudo:arg-opaqueL1warning实参 Abs 是 unknown(无 term)—— 约束根本无法检查。补调用点 / @nudo:case / --assume,或建模该值来源
nudo:arg-countL1error调用元数与泛化参数面不匹配
nudo:fn-not-foundL1error调用引用了分析器在作用域内无法解析的函数
nudo:partial-resultL1info结果 Abs 携带 #partial 置信 —— 仅观察
nudo:contract-param-mismatchL1error手写契约参数名不在形式参数面上
nudo:contract-conflictL1error手写契约合取不可满足
nudo:contract-loadL1error侧车文件加载失败(解析 / import / 路径解析错误)
nudo:contract-name-clashL1error侧车导出名与源码导出冲突,或 emit 会覆盖手写绑定(手写优先,跳过写入)
nudo:contract-cycleL1error侧车 @nudo:import 链成环
nudo:contract-domain-exceedsL1error经 --from 注入的调用记录 ⊄ 手写契约域
nudo:contract-driftL1warning固化 @generated 段 ≠ 今日重算契约(nudo health 亦上浮;不挡 exit)
nudo:contract-entry-onlyL1info导出无契约根且无调用点域(仅合成 entry@)—— 覆盖缺口,不是门禁失败
nudo:dual-entryL1infobrowser/node 双入口:调用点记录不跨文件 —— 分析只观察一个入口变体
nudo:contract-emit-deniedL1warningcontract --emit 目标在 package.json#nudo.contract.emit 允许列表之外 —— 跳过写入
nudo:contract-multi-declaratorL1warning@generated 段被手工合并成多声明导出 —— 原样保留
nudo:contract-not-projectableL1error组装侧车 round-trip 重解析失败 —— 不写任何文件(引擎债)
nudo:entry-may-throwL2error(默认)入口/导出函数有未消化 may-throw
nudo:module-throwL2error(默认)模块顶层代码必然抛(句法上无条件的 throw)⇒ 模块永远无法被导入、未被分析 —— 所有导出都不可用。fail-closed;每模块一条;与 nudo:internal(引擎回落)、nudo:unsupported:*(能力边界)都不是一回事
nudo:may-throwtest / L2 线索warningcase 路径可能抛(含内部);L2 可升格入口 throws
nudo:unknown-inference引擎债warning签名出现真 unknown(推导失败)—— 入口无约束参数是 any,不走此码
nudo:unknown-recv引擎债warningunknown 接收者成员访问 —— 不得替代 L2 throws 建模
nudo:builtin-unknown引擎债warningAPI 未被 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引擎/L1warning函数无法泛化为符号 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-unreachableinfoinforeturn/throw 之后的代码
nudo:module-cycle模块图warning循环模块装载 —— 环内绑定解析为部分求值类型
nudo:module-depth模块图warning模块装载链过深 —— 装载截断,更深模块为 unknown
nudo:module-missing模块图errorimport 了装载器无法解析的模块 —— 修 spec 或 mock(@nudo:mock-module)
nudo:missing-slot求值warning(默认 off)求值命中闭对象 shape 缺字段(用 nudo.analysis.evalMissingSlot 打开)—— 观察,不凭空产生 check 错误
nudo:case-expectedtesterror(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、CJS exports.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(默认)—— L2 entry-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 严重级按首个命中解析:

  1. CLI --entry-throws —— 显式值压过任何 profile
  2. CLI --profile(adoption → warning,strict → error)
  3. package.json#nudo.check.entryThrows
  4. package.json#nudo.check.profile
  5. 默认 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|offL2 严重级别(默认 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。
--ghaGitHub Actions 行内注解(::error / ::warning);GITHUB_ACTIONS=true 时自动开
--gitlabstdout 输出 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。

下一步​