Skip to main content

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 checknudo health
GatesL1 explicit contracts + L2 entry may-throwAnalysis errors + call-site solidification drift
TruthPred implication on AbsWhether generated call@ directives still match usage sites
Uncovered functionsEntry fallback (any params)Reported, informational only
CI roleThe product gateOptional evidence-freshness watch
Exit 1Any error-level diagnosticDrift 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​

FlagDescription
paths…Files or directories to health-check
--watchRe-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
--jsonStructured 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 drift count is the number of changed witness directives (added + removed), summed over all files — the same unit as the per-file drift: N witness directive(s) changed line 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 renders unknown — an inference failure, not any), and #widened witness(es) counts witnesses degraded to #widened (e.g. call sites folded beyond callSiteBudget). Neither gates the exit code; under --json they land in summary.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 ⇒ health reports the file with ✗ internal fallback(s) and the run ends with Result: 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 --freeze is an optional debug solidification tool — the product CI gate remains nudo 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​

CodeMeaning
0No drift, no analysis errors, no --from path errors
1Drift, 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​

SituationCommand
CI on every PR (Observation / Contracts)nudo check
CI after freezing call@ casesnudo check then nudo health --from
Local watch while editingnudo health --watch (or nudo check --watch)
Before a release, with frozen casesnudo health src/ --from tests/
No frozen cases yetnudo check only — health has nothing to re-solidify

More task recipes: Recipes.

Next​