跳到主要内容

nudo health

nudo health 报告分析错误与调用点固化漂移。它与 nudo check(契约门禁)互补:health 盯的是已记录证据是否仍与代码匹配。

npx nudojs health [paths…] [--watch] [--from paths…] [--json]

漂移、分析错误或 --from 缺文件时退出 1;--json 下路径错误进顶层 pathErrors[] 并强制 ok: false。未覆盖函数仅为信息级。

health 盯什么 vs check 门禁什么​

nudo checknudo health
门禁L1 显式契约 + L2 入口 may-throw分析错误 + 调用点固化漂移
真理Abs 上的 Pred 蕴含生成的 call@ 指令是否仍匹配使用点
未覆盖函数入口回落(any 参数)会报告,但仅为信息级
CI 角色产品门禁可选的证据新鲜度监视
退出 1任意 error 级诊断漂移或分析错误

check 回答「契约还成立吗?」。health 回答「已记录的调用点证据还描述得出这段代码怎么被用吗?」。管道里保留 check;当你固化了 call@ 用例、希望 CI 发现测试变动时,再加 health。

Flags​

Flag说明
paths…要做 health 检查的文件或目录
--watch文件变更时重跑
--from paths…使用点文件(测试、应用)。health 重跑与 test --freeze=update 相同的再固化链,生成的 call@ 指令会变化时报告漂移
--json结构化 health 报告

不带 --from 时,health 只报告分析错误与契约漂移 —— 调用点漂移需要使用点文件才能再 harvest。

走读示例 —— 代码改动后的漂移​

从一个库和覆盖它的测试开始。先把 harvest 到的用例固化一次:

npx nudojs test lib/slugify.js --from tests/ --freeze
# 在 lib/slugify.js 里写入生成的 call@ 指令

之后测试改了实参 —— 比如 slugify("Hello World") 变成 slugify("Hello World"),或换了另一种形状调用。固化的 call@ 指令不再匹配使用点。health 会报告:

npx nudojs health lib/ --from tests/
lib/slugify.js
· 1 function(s)
✗ drift: 3 witness directive(s) changed (+2 new, -1 removed) — refresh: nudo test lib/slugify.js --from tests/ --freeze=update

Summary: 1 file(s) · 3 case drift · 0 contract drift · 0 error(s) · 0 uncovered function(s) · 0 unknown signature(s) · 0 #widened witness(es)
Result: FAIL (drift or errors found)

case drift 计的是发生变化的见证指令条数(added + removed),对所有文件求和 —— 与上面每文件那行 drift: N witness directive(s) changed 同量纲。 (此前它计的是「有漂移的文件数」⇒ Summary 的数与明细行的数在同一屏上是两个量纲。)

两个精度计数与 uncovered 同为信息性指标:unknown signature(s) 计返回位 推断失败(签名渲染为 unknown —— 是推断失败,不是 any)的函数数; #widened witness(es) 计被降级成 #widened 的见证数(如超出 callSiteBudget 被折叠的调用点)。两者都不影响退出码;--json 下落在 summary.unknownSignatures / summary.widenedWitnesses。

引擎内部回落 ⇒ FAIL。 若某模块完全没能求值(引擎内部回落 —— 例如模块编译或 求值失败),该文件的导出无法被验证 ⇒ health 把该文件标成 ✗ internal fallback(s),整轮以 Result: FAIL (engine internal fallback found) 结束并以非零码退出。这是 fail-closed:引擎没能分析出来的文件不得被报成健康。

建议的 refresh 就是再固化命令:

npx nudojs test lib/slugify.js --from tests/ --freeze=update

--freeze=update 会先剥离此前生成的 call@ 指令,对剥离后的源码重新分析,再写回刷新后的集合。手写 @nudo:case 指令永不触碰(call@ 是保留的生成前缀)。freeze 与 freeze=update 在已同步文件上都是幂等的(freeze: no changes.)。

test --freeze 是可选的调试固化工具 —— 产品 CI 门禁仍是 nudo check。health 是那个在可选固化过期时提醒你的监视者。

若想把漂移检测变成不写文件的门禁,用调用点发现里的 dry-run 形态:

npx nudojs test lib/ --from tests/ --freeze=update --dry-run --exit-on-diff

CI 配方​

GitHub Actions​

# .github/workflows/nudo.yml
jobs:
nudo:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm i -g nudojs
- run: npx nudojs check src/
- run: npx nudojs health src/ --from tests/

check 放前面:它是产品门禁。health 在已记录证据漂移时让 job 失败。

退出码​

码含义
0无漂移、无分析错误、无 --from 路径错误
1漂移、分析错误或 --from 路径错误(未覆盖函数仅为信息级)

对 CI 而言退出面与 check 相同 —— 非零即挡流水线。

JSON​

--json 输出结构化 health 报告,供看板与 agent 工具使用。机器人需要同时解析契约门禁与漂移监视时,与 check --json 配对。

何时跑 health vs check​

场景命令
每个 PR 的 CI(观察层 / 契约层)nudo check
固化 call@ 用例之后的 CInudo check 然后 nudo health --from
编辑时本地 watchnudo health --watch(或 nudo check --watch)
发布前、已有固化用例nudo health src/ --from tests/
尚未固化用例只跑 nudo check —— health 没有可再固化的内容

更多任务配方:Recipes。

下一步​