Introduction
Nudo exists for one outcome: see variables close to how they look at runtime, right in the source.
When reading code, one usually sees only broad type names (number, string), often with another layer of annotations. Nudo executes JavaScript on abstract values so each variable carries what it will actually compute — literals, shapes, constraints — surfaced next to the source as signatures, IDE inlays, and call-site evidence.
// calc.js
export function scale(x) {
return x + 1;
}
scale(5);
// calc.nudo.js — explicit contract (obligation)
import { number, fn } from "@nudojs/core";
export const scale = fn({ x: number().gt(0) }, number());
In the IDE, intermediates show a runtime-adjacent form per line, not a single type name:
scale(x) x: number · x > 0 // from contract or call sites
return x + 1 term (x + 1) · > 1 // derivation, not "number"
scale(5) => 6 #exact // call site is runtime truth
scale(0) ⊭ x > 0 // actual 0 · expected x > 0
nudo check provides the same observation face on the command line (signatures print even on success). When obligations are needed, declare them as sidecar contracts (*.nudo.js / @nudo:contract); violations report values and predicates, not type names. For per-call-site scenario debugging, nudo test is a separate case reporter, not the gate.
signatures
scale(x: number) => number
issues
[ERROR L7 scale] scale[x]: argument ⊭ precondition (nudo:constraint-violated)
actual: 0 #exact
expected: x > 0
Product face: Observation (Day 0) = nudo check (signatures and diagnostics). Contracts (Day 1) = nudo contract + nudo check (explicit contracts). Ecosystem = nudo export (one-way Abs projections to .d.ts / schemas). Observation lives in check signatures and IDE hover — there is no separate observation verb. nudo test is an optional debug case reporter.
How this is achieved: execution, not annotations
The goal is runtime-adjacent variables in the source. The method is executing code on abstract values (Abs):
- Execution produces facts. The engine evaluates on symbolic values and records each intermediate’s shape, value identity, and constraints — not inferred from annotations.
- Call sites are evidence.
scale(5) => 6comes from an actual call path, not a comment. - Constraints participate in algebra.
x ≥ 0implies(x + 1) ≥ 1(strict bounds are ulp-adjusted to stay sound under IEEE rounding), so inlays show relations that can be reasoned about, not only type names. - Annotations are never required. Sources stay plain
.js; contracts are JS modules.
Deeper: Abstract interpretation · Abs.
How to use these docs
| You are | Start here |
|---|---|
| JS engineer evaluating a type/check gate | Mental model → Quick Start → nudo check |
| TypeScript user | Nudo vs TypeScript → Migrate from TS |
| Existing JS package | Migrating existing JS → Contracts |
| Automated workflow / platform | Recipes → Diagnostics → Error faces |
| AI coding agent / tooling | Agents → Agent integration → API · agent |
Non-goals: Nudo is not a TypeScript compiler; it does not invent required slots from body AST scans; @nudo:case is debug-only and never the contract product. See Limits.
Observation vs Contracts
| Layer | What you write | What you get |
|---|---|---|
| Observation (Day 0) | Plain JS + call sites | check signatures and L2 entry may-throw diagnostics |
| Contracts (Day 1) | *.nudo.js / @nudo:contract | L1 obligations (actual ⊭ expected) |
| Ecosystem | nothing extra | export projections: dts / guard / schema |
| Advanced | Abs algebra, envs, mocks | String/number algebra, HOFs, module graphs |
Obligation increases; any is unconstrained, unknown is inference failure.
Relation to declared types
| TypeScript | Nudo | |
|---|---|---|
| Variable presentation | Declared type names | Runtime-adjacent values / shapes / constraints |
| Contracts | Type language + assignability | Sidecar builders + L2 entry throws |
| Precision | Often widens to string / number | Can keep literals, template structure, loop sums |
| Source of truth | Source annotations | Abs from execution; projections are lossy and one-way |
Comparison: Nudo vs TypeScript. Limits: what Nudo does not claim.
Next
- Why Nudo — needs and answers
- Mental model
- Installation
- Quick Start
- nudo check
- Contracts
- Abstract interpretation — how runtime-adjacent variables are computed
- Abs —
shape × term × pred × conf - Playground
- Diagnostics
- Agents