Migrating existing JS
Nudo does not require annotations up front. The migration path is code-first: keep the implementation, generate reviewable contracts, tighten by hand, then lock CI.
existing JS → contract --draft → human review → *.nudo.js → check / health / IDE
0. Prerequisites
pnpm add -D nudojs @nudojs/lsp # or npx nudojs
# optional project config in package.json
{
"nudo": {
"analysis": {
"mode": "exports",
"diagnostics": "default",
"evalMissingSlot": "off"
},
"contract": { "autoBind": true }
}
}
See Coexistence with TypeScript if the repo already has tsc.
1. Inventory
nudo contract src/
nudo check src/
contract prints every top-level export with its tier; check prints signatures (including L2 entry throws).
Three tiers: handwritten (accepted sidecar / @nudo:contract — enforced by check), generated (@generated call-site snapshots — refresh with --emit when usage changes), and implicit (inference-only display — your draft candidates). Full tier table: nudo contract.
2. Draft contracts from code
nudo contract --draft src/lib.js
nudo contract --draft --write src/lib.js --fn greet --fn double
# or IDE: CodeLens ⚡ draft contract / VS Code “Nudo: Draft Contract”
Evidence in the draft module (never invents check obligations): callsite / directive evidence is the best starting point, body reads are suggestions only (fill types by hand), symbolic shapes cover the return slot when no cases exist, and slots without evidence stay TODO comments. Full evidence table: nudo contract.
Output lands in src/lib.nudo.draft.js — not ambient-loaded. Copy reviewed lines into src/lib.nudo.js.
Worked sample: docs/examples/contract-draft/.
Runnable demo (temp dir: inventory → draft → accept → check):
pnpm run migrate-demo
# from the nudo monorepo — scripts/migrate-demo.sh
3. Review checklist
For each draft export:
- Params — are call-site shapes too narrow for future callers? Widen (
number()vslit(21)). - Body-read fields — promote
shape({ name })only if every caller must provide them (that is a real obligation). - Returns — match the contract you want enforced, not every historical result.
- Handwritten clash — if
*.nudo.jsalready binds the name, keep handwritten (draft never overwrites).
Example accept:
// src/lib.nudo.js
import { fn, number, shape, string } from "@nudojs/core";
export const double = fn({ x: number() }, number());
export const greet = fn({ user: shape({ name: string() }) }, string());
4. Gate with check
nudo check src/
nudo check src/lib.js --json # CI
- Violations on handwritten contracts fail the build (L1).
- L2 entry may-throw on exports is an error by default — catch it, declare
@nudo:throws, or pass--ignore-throwsfor a single run. For the migration window, prefercheck --profile adoption: L2 drops to a warning (exit 0) while L1 stays error; return to strict (the default) once the migration settles. Details: nudo check. - generated segments report drift as warnings (facts + refresh), not as new obligations.
- implicit display never invents errors by itself.
Optional evaluation hints (default off):
{ "nudo": { "analysis": { "evalMissingSlot": "warning" } } }
Surfaces nudo:missing-slot when evaluation hits a closed object shape without a field — a hint to tighten drafts, not an automatic contract.
5. Freeze call-site domains (optional)
nudo contract --emit src/lib.js --fn double --from test/
nudo contract --emit src/lib.js --dry-run --exit-on-diff # CI drift gate
contract --emit writes @generated segments from observed arguments. Use it for usage sites you trust; keep handwritten contracts for API surface you want enforced.
6. IDE / agents
| Surface | Entry |
|---|---|
| Hover tier | ● contract / hw|gen|imp |
| CodeLens | persist / update / draft |
| VS Code | Output channel commands |
| Agent | nudo.contract, nudo.contract.draft, nudo.check |
| CLI | nudo contract (--draft / --emit), nudo check, nudo health, nudo test --freeze |
7. Ongoing health
nudo health src/ # uncovered fns, drift, analysis errors
nudo test src/lib.js --from test/ --freeze=update
Pin package versions per Versioning & Releases (0.x minors may break; the stable-line packages — core/service/nudojs, all 1.x today — follow SemVer; see the version table there).
What not to do
- Do not expect body
if (p.foo)reads to become check obligations (C0 model). - Do not commit
*.nudo.draft.jsas if it were a live contract — copy into*.nudo.jsfirst. - Do not treat
generatedsnapshots as the full API you intend to enforce — promote to handwritten when it matters.