Skip to main content

Nudo

Welcome back to JavaScript.

Your JS stays JS. Nudo does not restrict how you write JavaScript — it faithfully observes intermediate values and results, and enforces contracts sharper than types.

nudo · pricing.js + sidecar
export function lineTotal(price, qty) {price: number · price > 0param priceshape numberpred price > 0 // sidecarconf pathqty number · qty ≥ 1
return price * qty;term (price × qty) · > 0return term (price * qty) pred (price * qty) > 0 // price>0 ∧ qty≥1 ⇒ product > 0 // aligns with sidecar return number().gt(0) conf path(no concrete case — algebraic entry vars)
}
export function applyCoupon(order, code) {order shape · code: stringparam order shape { subtotal ≥ 0; items ≥ 0 } conf path (sidecar)param code shape string conf path
const rate =
code === "VIP10" ? 0.1 :
code === "VIP20" ? 0.2 : 0;rate ∈ {0, 0.1, 0.2}term ratepred rate = 0 ∨ rate = 0.1 ∨ rate = 0.2 // path-narrowed on code === …conf path
return {
...order,
total: order.subtotal * (1 - rate),
coupon: rate > 0 ? code : "NONE",term subtotal×(1−rate) · ≥ 0field total term order.subtotal * (1 - rate) pred total ≥ 0 // sidecar number().ge(0) conf path
};coupon: stringfield coupon term rate>0 ? code : "NONE" pred string conf path
}
// call sites are evidence
lineTotal(12, 3);
applyCoupon({ subtotal: 100, items: 3 }, "VIP10");=> 36 #exactcall lineTotal(12, 3)result 36 #exactConcrete values live at the call site.
total 90 · coupon "VIP10"call applyCoupon({subtotal:100, items:3}, "VIP10")rate 0.1total 90coupon "VIP10" #exact
// L1 gate: price > 0 from pricing.nudo.js
lineTotal(0, 2);⊭ price > 0call lineTotal(0, 2)actual 0 #exactexpected price > 0 // sidecargate nudo:constraint-violated
$ npx nudojs check pricing.js
signatures
lineTotal(price: number, qty: number) => numberfrom sidecar + bodysignatures reflect Abs after contracts:price: number · price > 0 (sidecar)qty: number · qty ≥ 1// unconstrained entry params print as any// unknown = inference failed — not this
applyCoupon(order: { subtotal: number, items: number }, code: string)
=> { subtotal: number, items: number, total: number, coupon: string }
issuesL1 gatecall site lineTotal(0, 2) ⊭ sidecar predactual ⊭ expected on AbsCI: nudo check exits 1
[ERROR L21 lineTotal] lineTotal[price]: argument ⊭ precondition (nudo:constraint-violated)
actual: 0 #exactprice > 0expected pred from pricing.nudo.jsalgebraic — not a declared TS typecontracts are JS modules — no second language
expected: price > 0
→ use a value satisfying price > 0, or relax the precondition on price
fix: nudo contract --draft (emit a sidecar draft you can edit)

Hover a line — body inlays are algebraic Abs from the sidecar; call sites in the same file are evidence and the L1 gate.

98.6%precise signatures on @hapi/hoek source
0type annotations you write source
291 → 0contract check failures cleared source
0.19 msmedian file-edit re-analyze source
How call-site discovery works →

Cost, measured

Shorter repair loops, cheaper payloads

Variables show up close to runtime and violations carry actual / expected / actions — so agents detect earlier and iterate less. Numbers are in-repo baselines (OSS slice + micro probes), not a closed benchmark.

569kvs 993k

agent tokens to green (OSS historical-bug slice) source

45vs 63

gate rounds on the documented fix path source

0.19 msvs 10 ms+

median single-file analyze (vs tsc.LS in micro probe) source

TS “cheap” tokens are often silent green. Nudo pays tokens to report. Method and bounds →

Beyond declared types

Values TypeScript widens away

Nudo evaluates on Abs, so results track actual computation — literal strings, splits, loop sums — not a declared upper bound.

ExpressionTypeScriptNudo observes
"0x" + idstring`0x${string}`
"hello".slice(1, 3)string"el"
"a,b,c".split(",")string[]["a", "b", "c"]
for (let i = 0; i < 5; i++) sum += inumber10

The template `SAVE-${code.toUpperCase()}` is not plain string — when the call site is coupon("vip"), Nudo observes "SAVE-VIP".

Real code, real results

Call sites become signatures

Observation check prints unconstrained params as any. Point Nudo at real usage — tests, call sites — and the interpreter synthesizes precise signatures from evidence. No type annotations. No library rewrite.

What call-site discovery returns

couponfrom cart.js call site
beforeno call-site evidence → any
nudo("vip") => "SAVE-VIP"
deepEqualfrom @hapi/hoek usage
beforeno call-site evidence → any
nudo({a:1,b:{c:2}}, {a:1,b:{c:2}}) => boolean
flattenfrom recursive + loop usage
beforeno call-site evidence → any
nudo([1,[2,[3,4]]]) => [1,2,3,4]

Product path

Observation → Contracts → leave tsc

Observation: `nudo check` prints signatures and diagnoses entry may-throw. Contracts: sidecar contracts turn call-site facts into L1 obligations. Ecosystem: `export` projects artifacts from Abs. Exit: `migrate retire` — coexistence is not the end state.

  1. ObservationObserve + gatenpx nudojs check src/
  2. ContractsAdd contractslib.nudo.js · @nudo:contract · nudo check
  3. EcosystemProject artifactsnpx nudojs export src/ --format dts|schema
  4. ExitRetire tscnpx nudojs migrate status|strip|verify|retire
Logic first

Write logic, then generate contracts

Call sites are evidence. `contract --draft` can generate a reviewable contract draft; accept into `*.nudo.js`. Drafts never become check obligations by themselves.

npx nudojs contract --draft lib.js --from test/
Contracts first

Write contracts, then guide / constrain logic

Write `*.nudo.js` or `@nudo:contract` first. The same contract face guides implementation and constrains logic in `check`.

npx nudojs check src/

Validate vs. project

The flow is centered on the Abs contract face. `check` only validates. `export` projects `.d.ts` / Zod / Standard Schema / guards from Abs; IDE and agents read Abs directly.

nudo check

Validation / CI only. Does not generate artifacts.

export · dts

`.d.ts` for TypeScript consumers. Lossy projection.

export · Zod / guards

Runtime validators from Abs. Not a substitute for `check`.

export · Standard Schema

Standard Schema validators for runtime checks and downstream tooling.

IDE / LSP

Hover / inlay read Abs directly.

Agent / MCP

Coding agents read the same Abs via LSP / MCP — see the AI agents section.

AI agents

Agents that gate contracts — not invent types

Coding agents and editors read the same Abs face via LSP / MCP. They run `nudo check`, respect sidecar contracts, and parse stable diagnostic IDs — not a second type language.

Same Abs as the IDE

Hover / inlay and agent tools consume Abs directly. `export` projections stay lossy; Abs remains the source of truth.

npx nudojs check src/ --json

LSP + MCP surface

`@nudojs/lsp` exposes agent `executeCommand` tools. Wire MCP for Cursor, Claude Code, and other agent clients without a separate server protocol.

@nudojs/lsp · nudo.contract · nudo.whatIf

Stable product rules

Agents must not invent body-AST obligations or treat `@nudo:case` as contracts. Entry `any` ≠ `unknown`. Observation is `check`; Contracts is `contract` + `check`.

actual ⊭ expected · nudo:constraint-violated

Agent entrypoint

Publish `agents.md` + `llms.txt` so coding agents can set up Nudo without guessing product nouns. Paste the setup block into your agent and go.

nudojs.github.io/nudo/agents.md
Paste into your coding agent
Read https://nudojs.github.io/nudo/docs/reference/agents
Primary gate: npx nudojs check <path>
Contracts are *.nudo.js / @nudo:contract
Do not invent body-AST obligations. @nudo:case is debug-only.
Entry params print as any; unknown = inference failed.

Ready to come back to JS?

Observe intermediates in the browser, gate contracts on your own files with the CLI, or point a coding agent at the same Abs face. Your JS stays JS.

npx nudojs check ./pricing.js