跳到主要内容

性能:预算与分析缓存

两个常被混淆的独立杠杆:

  • 预算管精度。Nudo 分析的是(可能无限的)执行的有限近似。预算用尽时,受影响的结果拓宽(#widened),并有诊断码说明 —— 绝不静默。
  • 磁盘缓存(.nudo/cache)管一部分冷路径的重复运行延迟。默认关闭,且绝不加速 test / export / health 背后的完整分析。

分析预算​

求值器(transpile → new Function)在你的代码上执行真实的 Abs 代数。预算为这份工作量设界:

预算默认旋钮触发时
调用总数(函数进入次数)20,000—nudo:recursion-truncated
调用深度64—nudo:recursion-truncated
分支展开($fork 总数)5,000NUDO_MAX_FORKS / package.json#nudo.analysis.maxForksnudo:fork-truncated
每函数合并的调用点数3package.json#nudo.analysis.callSiteBudget(1–64)超限调用点符号折叠 → #widened

只有 fork 预算可调(env NUDO_MAX_FORKS 优先于 nudo.analysis.maxForks;非法值回落默认)。调用总数与调用深度是硬上限 —— 请重构代码,而不是找旋钮。

何时触发截断 —— 该做什么​

nudo:recursion-truncated —— 递归求值被截断;受影响结果拓宽。reason 字段(check --json)与文案区分归因:cycle 表示同抽象实参的调用已在求值栈上——调用环,任何预算都解不开(让实参逐层变化、收窄基例,或声明 @nudo:contract);depth / calls 表示调用预算(深度 64 / 总进入 20,000)真的用尽——函数上的 @nudo:budget depth=… / calls=… 可抬。nudo:loop-truncated —— 循环退出条件越过迭代预算(抽象展开 8 / 具体 1024)仍具体真;循环状态拓宽。这是循环预算——@nudo:budget calls/depth 不适用;让上界依赖数据或用 @nudo:case / @nudo:contract 钉住。nudo:fork-truncated —— 分支展开预算用尽;受影响结果拓宽(info)。这些都出现在 nudo check / nudo test 输出里 —— 截断绝不静默降级结果。

三个杠杆,按值得尝试的顺序:

  1. 加约束。 契约(*.nudo.js / @nudo:contract)与调用点证据让集合早收窄 —— 更小的 Abs、更少的重求值、更少的 fork。这也是唯一能同时提升精度的修法。
  2. 拆函数 / 拍平分支。 深调用链烧调用深度;长 if/else 链与分支内循环让 $fork 计数组合式膨胀。抽取 helper、提前 return、拆分关注点。
  3. 调旋钮与 env。 调高 fork 预算(NUDO_MAX_FORKS=20000 或 package.json#nudo.analysis.maxForks);用 @nudo:env / mock 建模你触碰的 API,让分析留在已建模的精确路径上,而不是对 opaque 值反复 fork。

预算的存在是为了让分析在对抗性代码上可终止。如果你经常调 maxForks,真正的故事通常在代码(或缺的契约)上。

.nudo/cache 项目磁盘缓存​

默认关闭。通过 package.json 打开:

{
"nudo": {
"cache": true
}
}

nudo.cache 接受:

取值含义
true缓存在 <projectRoot>/.nudo/cache
"some/dir"自定义目录,相对项目根解析
{ "dir": …, "sign": true }对象形态 —— 自定义根与条目签名(见下)组合
false / 省略关闭(默认)

env 覆盖(配置未设时):NUDO_CACHE_DIR —— 绝对路径,或 off / 0 关闭。

落到磁盘的内容(缓存根下按命名空间分子目录):

命名空间内容服务的面
contract整文件 effectiveContract 表(导出 → 契约 JSON,或 implicit 负缓存)nudo contract 打印 / 契约读取冷启动
check整文件 CheckJson 报告未变更文件在 nudo check 冷路径 —— 带 --from 时绝不读写(现场注入的证据不可作为整报告复用)

键是内容寻址的:对源码 + 侧车 + 依赖内容 + 配置维度(如 contract.autoBind)取 sha256,并带分析 ABI 前缀(nudo-check-cache-v…+<version>,其中含 TypeScript 版本 —— 不是 package.json#version)。升级 @nudojs/* → 前缀变 → 整层干净 miss。改源码、侧车或任一依赖 → 键变 → 自然 miss。

fail-open 语义。 损坏的 JSON、ABI 不符、读不了的条目、被删的目录 —— 每种失败都是一次缓存 miss。分析重算;不抛任何东西;可观察行为完全一致。你随时可以 rm -rf .nudo/cache。被截断或 opaque 证据触及的条目绝不写入。

为什么默认关闭​

一份结构合法的伪造 CheckJson 能制造假阴性 —— 被投毒的缓存可能藏掉真实违例。因此:只在可信机器 / CI 上开启;.nudo/cache 必须 gitignore;不可信 runner 上保持 nudo.cache 未设/false,或设 NUDO_CACHE_DIR=off。

条目签名(nudo.cache.sign: true + NUDO_CACHE_KEY)​

给仍想用缓存的不可信 runner:打开逐条 HMAC-SHA256 签名。

// package.json —— 打开;秘密经 env 提供(CI secret,绝不入库)
{ "nudo": { "cache": { "sign": true } } }
# CI:打码 secret → env;check / contract / health 都读它
- run: pnpm exec nudo check src/
env:
NUDO_CACHE_KEY: ${{ secrets.NUDO_CACHE_KEY }}
  • 每条条目带内容签名;验签失败(值被篡改、签名被剥、密钥不对)= miss —— 重算,绝不采信。伪造的「绿」过不了签名,进不了门禁。
  • 签名与未签名条目键空间分离:轮换密钥(或开关签名)= 同路径干净的全量 miss —— 不脏命中、无孤儿要清理。
  • 配置 fail-closed:sign: true 却没有 NUDO_CACHE_KEY、或 sign 值不是布尔,check / contract / health 拒绝运行(exit 1;--json 面走既有信封)。安全旋钮绝不静默退回无签名。
  • 密钥卫生:只放 env 或打码 CI secret —— 永不进仓库、绝不放进缓存目录本身。

依赖层(默认开启)​

另一个跨项目缓存在 ~/.cache/nudo/deps(覆盖:NUDO_DEPS_CACHE_DIR;off / 0 关闭),存 @types harvest 的签名投影 —— 纯 JSON,绝不是 Abs 本体。默认开启、fail-open、跨项目共享 —— 重复分析的最大收益在这里。

缓存不加速什么​

诚实边界:

  • 服务的面:contract 打印 / 契约读取冷启动;opt-in 的 check 冷路径(未变更文件);harvest 依赖层。
  • 不服务的面:test / contract --emit / health 的完整求值器分析;export 的整条投影链。
  • 绝不进盘:Abs 本体、AST、PolyFn、AnalysisResult,以及截断 / opaque / mock 改道的分析结果。
  • --from(现场调用点证据)完全跳过 CheckJson 读写。

缓存让未变更文件的重复 check 在代数面上更便宜。它不是「让 Nudo 变快」的通用开关 —— 先看预算和契约。

CI:缓存目录要不要 restore?​

  • 默认配置:什么都不用 restore。 项目缓存关闭;nudo check 每次诚实重算。
  • 可信 CI runner 上的推荐配置:打开项目缓存并在多次运行之间 restore .nudo/cache。 键内容寻址(源码 + 侧车 + 依赖内容 + 配置维度的 sha256,带 ABI 前缀),restore 出来的层不可能给出陈旧或错误的结果 —— 最坏情况是干净 miss、诚实重算。始终 gitignore 该目录;绝不入库。契约文件(*.nudo.js)进 git;缓存不进。完整配方见下。
  • 不可信 runner: 要么保持关闭 —— nudo.cache: false(或不设)且 NUDO_CACHE_DIR=off —— 要么打开条目签名(见上「条目签名」一节:cache.sign: true + 打码 CI secret 的 NUDO_CACHE_KEY),被篡改的缓存会诚实地 miss,而不是毒害门禁。
  • 依赖层(~/.cache/nudo/deps)才是 CI 值得弄的那层:默认开启、跨项目、纯签名投影。把 NUDO_DEPS_CACHE_DIR 指到 restore 出来的目录即可跨 job 复用 harvest 成果;陈旧或损坏的副本只会 miss。

可信 runner 配方(GitHub Actions)​

在 package.json 里打开项目缓存(配置入库 —— 缓存目录绝不入库),并把目录加进 gitignore:

// package.json
{ "nudo": { "cache": true } } // → <projectRoot>/.nudo/cache
# .gitignore
.nudo/cache/

然后在门禁前 restore、门禁后 save:

# .github/workflows/nudo.yml —— 可信 runner
jobs:
nudo-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- run: pnpm install
# 先 restore。miss(首次运行、冷层)只是诚实重算。
- uses: actions/cache/restore@v4
with:
path: .nudo/cache
# 桶键 = lockfile + 受跟踪源码。它不必精确:nudo 的逐文件键
# (源码 + 侧车 + 依赖 + 配置的 sha256,带 ABI 前缀)负责真正
# 的失效判定;经 restore-keys 恢复的旧桶只会逐文件 miss。
key: nudo-check-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('src/**') }}
restore-keys: |
nudo-check-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-
nudo-check-${{ runner.os }}-
- run: pnpm exec nudo check src/
# 保存本次运行产出的层。check exit 1 时自动跳过;想让红的运行也
# 回填就加 `if: always()` —— 条目是内容键寻址的整文件报告,不是裁决。
- uses: actions/cache/save@v4
with:
path: .nudo/cache
key: nudo-check-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}-${{ hashFiles('src/**') }}

把 src/**(与 lockfile 文件名)换成你实际 check 的布局。用单个 actions/cache@v4 步骤也可以 —— restore/save 拆开只是把保存变成显式、可加条件的步骤。不可信 runner 上不要照抄这份配方:结构合法的伪造 CheckJson 能制造假阴性 —— 在那里保持缓存关闭(nudo.cache: false / NUDO_CACHE_DIR=off),或加条目签名(见上「条目签名」)。

会话缓存上限(进程内 LRU)​

与上面的磁盘缓存是两个不同的杠杆:每个 Nudo 进程内部都维护内存 LRU 缓存,服务热路径重分析 —— 整文件分析结果、逐函数分析、求值器 run。它们的条目数通过 package.json#nudo.sessionCache 封顶。这只是内存与 warm 命中之间的取舍,绝不是精度旋钮 —— 逐出只是诚实重算,结果与诊断完全不变。

键(nudo.sessionCache.*)环境变量封什么默认
maxFilesNUDO_CACHE_MAX_FILES整文件分析结果 LRU 条目64
maxFnsNUDO_CACHE_MAX_FNS逐函数分析 LRU 条目1024
maxEvalRunsNUDO_CACHE_MAX_EVALRUNS求值器 run LRU 条目32
  • 优先级:环境变量 > package.json#nudo.sessionCache > 默认。0 / off 关闭该层;数值钳制到 65,536。
  • 多项目共用一个 IDE/LSP 进程时调低;大单仓可调高换 warm 命中。
  • 与持久化磁盘缓存(上面的 nudo.cache / NUDO_CACHE_DIR)正交:会话上限随进程消失,绝不落盘。

配置速查​

想要设置
调高分支预算NUDO_MAX_FORKS=20000 或 package.json#nudo.analysis.maxForks
每函数合并更多调用点package.json#nudo.analysis.callSiteBudget(1–64,默认 3)
打开项目磁盘缓存package.json#nudo.cache: true(→ .nudo/cache)
自定义缓存目录nudo.cache: ".nudo-cache" 或 NUDO_CACHE_DIR=/abs/path
关闭依赖缓存NUDO_DEPS_CACHE_DIR=off
封顶进程内会话缓存package.json#nudo.sessionCache.* / NUDO_CACHE_MAX_FILES · NUDO_CACHE_MAX_FNS · NUDO_CACHE_MAX_EVALRUNS

完整配置表 —— 全部 package.json#nudo 键与 NUDO_* 变量 —— 见配置参考。

下一步​