Skip to main content

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.

30 seconds, no repo yet

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 test on untrusted code; in CI this is the same trust as running the project's tests.

1. Write plain JavaScript​

Create calc.js:

engine-verifiedRun in Playground
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:

engine-verifiedRun in Playground
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:

engine-verifiedRun in Playground
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:

Options​

  • .d.ts projection — 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/ --watch
    npx 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​