Skip to main content

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:

  1. Params — are call-site shapes too narrow for future callers? Widen (number() vs lit(21)).
  2. Body-read fields — promote shape({ name }) only if every caller must provide them (that is a real obligation).
  3. Returns — match the contract you want enforced, not every historical result.
  4. Handwritten clash — if *.nudo.js already 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-throws for a single run. For the migration window, prefer check --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​

SurfaceEntry
Hover tier● contract / hw|gen|imp
CodeLenspersist / update / draft
VS CodeOutput channel commands
Agentnudo.contract, nudo.contract.draft, nudo.check
CLInudo 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.js as if it were a live contract — copy into *.nudo.js first.
  • Do not treat generated snapshots as the full API you intend to enforce — promote to handwritten when it matters.

See also​