Quick Start
You'll leave with: signatures from nudo check, cases from nudo test, a sidecar contract, a nudo check failure you can read — and the green re-run that closes the loop.
Prefer the browser? Open the Playground.
Paste this against any existing JavaScript file (a util you already trust):
npx nudojs check /path/to/your/util.js
You should immediately see signatures (e.g. scale(x: any) => number | string throws TypeError), followed by either (no issues) or a list of L1/L2 findings. Entry params display as any, not unknown — unconstrained means unconstrained, not inference failure. (The export face differs by design: a generated .d.ts projects an uncalled export's params as unknown — an honest boundary, not an inference failure. See Export: bridge to the ecosystem.) The rest of this page explains what you just saw.
Trust boundary. Nudo analyzes by executing the target code (Abs semantics, in-process evaluation). Do not run
nudo check/nudo teston untrusted code; in CI this is the same trust as running the project's tests.
1. Write plain JavaScript
Create calc.js:
export function scale(x) {
return x + 1;
}
export function formatName(first, last) {
return first + " " + last;
}
formatName("Ada", "Lovelace");
scale(5);
No annotations. Call sites are evidence.
2. Observe (Day 0)
npx nudojs check calc.js
nudo check calc.js
FAILED
2 error · 0 warning · 0 info · 2 fn
signatures
scale(x: any) => number | string throws TypeError
formatName(first: any, last: any) => string throws TypeError
issues
[ERROR L1 scale] scale (export): may throw TypeError (nudo:entry-may-throw)
[ERROR L5 formatName] formatName (export): may throw TypeError (nudo:entry-may-throw)
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
The onboarding block appears only in a pristine project — no @nudo:* directives and no nudo config anywhere. Add either (the next section does) and it disappears; the gate result itself is unchanged.
That number | string is honest JavaScript, not a bug: an unconstrained (any) operand to + can drive numeric addition or string concatenation ("7" + 1), so Nudo keeps both branches. Constrain x — a sidecar contract or call-site evidence — and the union collapses to number. See Language semantics.
The two L2 findings are the honest flip side of the same coin: an unconstrained + operand's ToPrimitive can throw TypeError (native Symbol coercion), so check flags both exports until you constrain the params (next section) or declare @nudo:throws TypeError.
Optional debug cases (nudo test — not the product gate):
=== scale ===
call@L10 (5) => 6
=== formatName ===
call@L9 ("Ada", "Lovelace") => "Ada Lovelace"
assertions
— 0 passed · 0 failed · 0 unchecked (no declared @nudo:case expectations; 2 synthetic case(s) printed above)
Nudo executed the functions with the arguments it actually saw. Unconstrained entry params display as any (not unknown). Observation is check signatures + IDE hover; nudo test is an optional debug case reporter.
3. Add an explicit contract (Day 1)
Create calc.nudo.js next to the source:
import { number, string, fn } from "@nudojs/core";
export const scale = fn({ x: number().gt(0) }, number());
export const formatName = fn({ first: string(), last: string() }, string());
Both exports are constrained — formatName's + operands become string, clearing its L2 may-throw finding alongside scale's.
4. Gate with check
Add a call that violates the sidecar:
scale(0); // fails the sidecar — x must be > 0
Run the gate:
npx nudojs check calc.js
nudo check calc.js
FAILED
1 error · 0 warning · 0 info · 2 fn
signatures
scale(x: number) => number
formatName(first: string, last: string) => string
issues
[ERROR L12 scale] scale[x]: argument ⊭ precondition (nudo:constraint-violated)
actual: 0 #exact
expected: x > 0
→ use a value satisfying x > 0, or relax the precondition on x
The violation is reported against the call site. Fix the call (or widen the contract), and check passes — still printing signatures.
if guards are not refinements. Explicit contracts come from sidecars / @nudo:contract. Without them, L2 still gates undigested may-throw on exports (entry params are any).
5. Close the loop: green, CI, IDE
Fix the violating call — any value satisfying x > 0:
scale(2); // satisfies the sidecar — x must be > 0
Re-run the gate:
npx nudojs check calc.js
nudo check calc.js
OK
0 error · 0 warning · 0 info · 2 fn
signatures
scale(x: number) => number
formatName(first: string, last: string) => string
(no issues)
Green — and signatures still print; only the OK / FAILED line and the exit code (0) tell you the gate passed. Two places left to close the loop:
- CI — wire
nudo checkinto GitHub Actions: CI integration → GitHub Actions - IDE — hover, inlay hints, and case switching in VS Code: VS Code guide
Options
-
.d.tsprojection — ecosystem bridge (one-way, lossy; Abs is the truth):npx nudojs export calc.js --format dts --out dist/types -
Watch mode (flag, not a verb)
npx nudojs check src/ --watchnpx nudojs test src/ --watch
Export bridge + adoption profile (Contracts → ecosystem)
Once check is green (or while you are still migrating), project Abs outward — .d.ts for editors, Zod / Standard Schema / guards for boundary code:
npx nudojs export calc.js --format all --out dist
Schemas manage data at the boundary; Nudo manages facts computed inside. Full story: Export: bridge to the ecosystem.
Legacy JS too noisy under L2? Use the named migration gate profile — L1 contract violations stay error, only entry may-throw drops to warning:
npx nudojs check calc.js --profile adoption
Debug witnesses (optional)
@nudo:case is for scenario debugging (nudo test, LSP case switching) — not the contract product:
/**
* @nudo:case "double digits" (10)
*/
export function scale(x) {
return x + 1;
}
Prefer concrete values or constraint builders in cases.
Next
- Mental model
- Troubleshooting — first-hour FAQ
- How to use these docs
- Error faces — what violations look like
- nudo check
- nudo contract
- Directive cheatsheet — one-line syntax for every
@nudo:directive - Migrate from TypeScript — retire
tsc - Concept Layers
- Recipes
- Playground