nudo health
nudo health reports analysis errors and call-site solidification drift. It complements nudo check (contract gate): health watches whether recorded evidence still matches the code.
npx nudojs health [paths…] [--watch] [--from paths…] [--json]
Exit 1 on drift, analysis errors, or missing --from paths. Under --json, --from path errors land in top-level pathErrors[] and force ok: false. Uncovered functions are informational only.
What health watches vs what check gates
nudo check | nudo health | |
|---|---|---|
| Gates | L1 explicit contracts + L2 entry may-throw | Analysis errors + call-site solidification drift |
| Truth | Pred implication on Abs | Whether generated call@ directives still match usage sites |
| Uncovered functions | Entry fallback (any params) | Reported, informational only |
| CI role | The product gate | Optional evidence-freshness watch |
Exit 1 | Any error-level diagnostic | Drift or analysis errors |
check answers "do the contracts still hold?". health answers "does the recorded call-site evidence still describe how this code is used?". Keep check in the pipeline; add health when you have frozen call@ cases and want CI to notice when tests move.
Flags
| Flag | Description |
|---|---|
paths… | Files or directories to health-check |
--watch | Re-run on file changes |
--from paths… | Usage-site files (tests, apps). Health re-runs the same re-solidify chain as test --freeze=update and reports drift when generated call@ directives would change |
--json | Structured health report |
Without --from, health reports analysis errors and contract drift only — call-site drift needs usage-site files to re-harvest.
Worked example — drift after a code change
Start from a library and a test that exercises it. Freeze the harvested cases once:
npx nudojs test lib/slugify.js --from tests/ --freeze
# writes generated call@ directives into lib/slugify.js
Later the test changes its arguments — say slugify("Hello World") becomes slugify("Hello World") or the helper is called with a different shape. The frozen call@ directive no longer matches the usage site. health reports it:
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)
The
case driftcount is the number of changed witness directives (added + removed), summed over all files — the same unit as the per-filedrift: N witness directive(s) changedline above. (It used to count files with drift, which made the Summary number and the detail line two different units on the same screen.)The two precision counts are informational, like
uncovered:unknown signature(s)counts functions whose return the engine could not infer (the signature rendersunknown— an inference failure, notany), and#widened witness(es)counts witnesses degraded to#widened(e.g. call sites folded beyondcallSiteBudget). Neither gates the exit code; under--jsonthey land insummary.unknownSignatures/summary.widenedWitnesses.Engine internal fallback ⇒ FAIL. If a module could not be evaluated at all (engine internal fallback — e.g. the module failed to compile or evaluate), the affected file's exports could not be verified ⇒
healthreports the file with✗ internal fallback(s)and the run ends withResult: FAIL (engine internal fallback found)and a non-zero exit code. This is fail-closed: a file the engine could not analyze must not be reported as healthy.
The suggested refresh is exactly the re-solidify command:
npx nudojs test lib/slugify.js --from tests/ --freeze=update
--freeze=update strips previously generated call@ directives, re-analyzes the stripped source, and writes the refreshed set back. Hand-written @nudo:case directives are never touched (call@ is a reserved generated prefix). Both freeze and freeze=update are idempotent on a synced file (freeze: no changes.).
test --freezeis an optional debug solidification tool — the product CI gate remainsnudo check. Health is the watcher that tells you when the optional solidification went stale.
To turn drift detection into a gate without writing files, use the dry-run form from Call-site discovery:
npx nudojs test lib/ --from tests/ --freeze=update --dry-run --exit-on-diff
CI recipes
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 stays first: it is the product gate. health fails the job when recorded evidence drifted.
Exit codes
| Code | Meaning |
|---|---|
0 | No drift, no analysis errors, no --from path errors |
1 | Drift, analysis errors, or --from path errors (uncovered functions are informational only) |
Same exit surface as check for CI purposes — a non-zero run blocks the pipeline.
JSON
--json emits a structured health report for dashboards and agent tooling. Pair it with check --json when a bot needs both the contract gate and the drift watch in one parse.
When to run health vs check
| Situation | Command |
|---|---|
| CI on every PR (Observation / Contracts) | nudo check |
CI after freezing call@ cases | nudo check then nudo health --from |
| Local watch while editing | nudo health --watch (or nudo check --watch) |
| Before a release, with frozen cases | nudo health src/ --from tests/ |
| No frozen cases yet | nudo check only — health has nothing to re-solidify |
More task recipes: Recipes.
Next
- nudo check — the contract gate health complements
- Call-site discovery — harvest,
--freeze, and the re-solidify chain - Diagnostics — code index for analysis errors
- Recipes — CI gate and monorepo recipes
- CLI Reference — flag and exit-code contract