Skip to main content

nudo check

nudo check is Nudo's gate on Abs. It enforces:

  1. L1 explicit contracts — refinements from *.nudo.js / @nudo:contract (Pred implication on Abs)
  2. L2 default JS contracts — undigested may-throw on entry/export functions

The report is Nudo-native (actual ⊭ expected), not a TypeScript diagnostic in disguise. On success and failure, check prints signatures — it is not silent.

npx nudojs check path/to/file.js
# exit 1 if any error
nudo check <path> [--watch|-w] [--json] [--quiet] [--verbose] [--abs]
[--from paths…] [--ignore-throws names] [--entry-throws error|warning|off]
[--profile adoption|strict]

check validate vs export project

check validates Abs (solid); export projects dts/guard/schema one-way and lossy (dashed). Nothing reads a projection back.

Default output (signatures + issues)​

engine-verifiedRun in Playground
export function getName(user) {
return user.name;
}

export function subtract(a, b) {
return a - b;
}
nudo check user.js
nudo check user.js
FAILED
2 error · 0 warning · 2 info · 3 fn

signatures
getName(user: any) => any throws TypeError
subtract(a: any, b: any) => number throws TypeError
clamp(n: any, lo: any, hi: any) => any

issues
[ERROR L1 getName] getName (export): may throw TypeError (nudo:entry-may-throw)
actual: getName(user: any) => any throws TypeError
expected: entry total, or @nudo:throws / try-catch
→ property 'name' on any (unconstrained value) → @nudo:throws TypeError | sidecar: fn({ … }): shape({ <body-read fields> }) | refine / guard / try-catch
fix: nudo contract --draft (emit a sidecar draft you can edit)
[ERROR L5 subtract] subtract (export): may throw TypeError (nudo:entry-may-throw)
actual: subtract(a: any, b: any) => number throws TypeError
expected: entry total, or @nudo:throws / try-catch
→ ToNumber coercion of abstract operand → @nudo:throws TypeError | sidecar: fn({ … }): shape({ <body-read fields> }) | refine / guard / try-catch
fix: nudo contract --draft (emit a sidecar draft you can edit)
[INFO L1] export 'getName' has no contract root and no call-site domain (entry-only) (nudo:contract-entry-only)
[INFO L5] export 'subtract' has no contract root and no call-site domain (entry-only) (nudo:contract-entry-only)

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 is printed only when the whole run is pristine — zero @nudo:* directives, zero nudo config — and every error is L2. It never changes the exit code and disappears once a directive or config exists.

L1 in [ERROR L1 getName] is the line number (the function is declared on line 1 here) — the layer is L2 (nudo:entry-may-throw). L# is always a location, never a contract layer.

  • Unconstrained entry parameters display as any.
  • unknown means inference failed (engine debt) — never the default for unconstrained entry params.
  • Throws always appear on the signature line when present.
  • [ERROR L# name] — L# is the line number of the offending call/declaration, not a contract layer (L1/L2 are the layers; L# is a location).

What it checks​

CodeLayerSeverityMeaning
nudo:constraint-violatedL1errorCall/return ⊭ @nudo:contract (scalar bounds / shape fields)
nudo:assign-mismatchL1errorAssignment ⊭ previous binding shape (leqAbs)
nudo:arg-structureL1error (explicit contract) / warning (body-promote)HOF: argument is not a callable fn / arity mismatch. Usage-driven body promotion is a warning suggestion; only explicit relation contracts make it an error
nudo:case-inconsistencyL1error@nudo:case witness ⊭ refine
nudo:constraint-unprovenL1warningCannot prove the argument satisfies the contract Pred (cannot prove … x > 0) — inconclusive, not failed. Add a call site / @nudo:case, or state preconditions via --assume
nudo:arg-opaqueL1warningArgument Abs is unknown (no term) — the constraint cannot even be checked. Add a call site / @nudo:case / --assume, or model the value's source
nudo:arg-countL1errorArity mismatch between the call and the generalized parameter face
nudo:fn-not-foundL1errorCall references a function the analyzer cannot resolve in scope
nudo:partial-resultL1infoResult Abs carries #partial confidence — observation only
nudo:contract-param-mismatchL1errorHandwritten contract param name is not on the formal surface
nudo:contract-conflictL1errorHandwritten contract conjunction unsatisfiable
nudo:contract-loadL1errorSidecar file failed to load (parse / import / resolution error)
nudo:contract-name-clashL1errorSidecar export name collides with a source export, or emit would overwrite a handwritten binding (handwritten wins, write skipped)
nudo:contract-cycleL1errorSidecar @nudo:import chain forms a cycle
nudo:contract-domain-exceedsL1errorCall records injected via --from ⊄ the handwritten contract domain
nudo:contract-driftL1warningPersisted @generated segment ≠ today's recomputed contract (also surfaced by nudo health; does not gate exit)
nudo:contract-entry-onlyL1infoExport has no contract root and no call-site domain (only synthesized entry@) — coverage gap, not a gate failure
nudo:dual-entryL1infoBrowser/node dual entrypoints: call-site records do not cross files — analysis observes only one entry variant
nudo:contract-emit-deniedL1warningcontract --emit target outside the package.json#nudo.contract.emit allowlist — write skipped
nudo:contract-multi-declaratorL1warning@generated section hand-merged into one multi-declarator export — kept verbatim
nudo:contract-not-projectableL1errorAssembled sidecar failed round-trip re-parse — nothing written (engine debt)
nudo:entry-may-throwL2error (default)Entry/export function has undigested may-throw
nudo:module-throwL2error (default)The module's top-level code always throws (syntactic unconditional throw) ⇒ the module can never be imported and was not analysed — every export is unavailable. Fail-closed; one per module; distinct from nudo:internal (engine fallback) and nudo:unsupported:* (capability boundary)
nudo:may-throwtest / L2 cluewarningCase path may throw (internal included); L2 can elevate entry throws
nudo:unknown-inferenceengine debtwarningTrue unknown on a signature (inference failed) — unconstrained entry params are any, not this code
nudo:unknown-recvengine debtwarningMember access on unknown receiver — does not replace L2 throws modeling
nudo:builtin-unknownengine debtwarningAPI not covered by env/inference (e.g. unmodeled global). Prefer @nudo:env / mock
nudo:opaque-resultengineinfoEvaluation returned opaque / uninformative Abs
nudo:recursion-truncatedengineinfoRecursive evaluation cut short — reason: cycle (same abstract args on stack; a budget cannot lift it) or depth/calls (budget ran out)
nudo:loop-truncatedengineinfoLoop exit condition stayed concrete-true past the iteration budget; loop state widened (not the call budget)
nudo:fork-truncatedengineinfoBranch-expansion ($fork) budget hit; result widened
nudo:host-effect-blockedengineinfoHost side-effect function (fetch / timers / …) not executed during analysis — result widened to unknown#opaque. Mock with @nudo:mock / @nudo:env
nudo:internalengineerrorThe check gate could not run to completion for this file (engine internal fallback — e.g. the module failed to evaluate) ⇒ the file's exports could not be verified ⇒ fail-closed: nudo check exits non-zero and nudo health reports Result: FAIL. Distinct from nudo:unsupported:* (capability boundary) and from nudo:opaque-result (inference precision)
nudo:no-signatureengine/L1warningFunction could not be generalized (CJS/anon forms still get L2 via entry fallback)
nudo:no-methodengineerror (primitive receivers) / warningMember access cannot resolve — Method 'x' does not exist on type 'T'. Distinct from nudo:unknown-recv
nudo:mock-invalidenginewarning@nudo:mock expression is not a known pattern (stub/spy/mock, arrow, type expression)
nudo:env-harvest-conflictenginewarningHandwritten @nudo:env and @types harvest supply the same module key — handwritten wins, harvest fills missing slots only
nudo:contract-underivableengineinfoDerived contract row has no source evidence (opaque / truncated / none) — row skipped; handwritten rows never flagged
nudo-unreachableinfoinfoCode after return/throw
nudo:module-cyclemodule graphwarningCircular module load — bindings inside the cycle resolve to partially evaluated types
nudo:module-depthmodule graphwarningModule load chain too deep — loading truncated, deeper modules typed unknown
nudo:module-missingmodule grapherrorImported module the loader cannot resolve — fix the spec or mock it (@nudo:mock-module)
nudo:missing-slotevalwarning (default off)Evaluation hit a closed object shape's missing field (opt in nudo.analysis.evalMissingSlot) — observation, never invents check errors
nudo:case-expectedtesterror (fails nudo test)Declared @nudo:case expected type ⊭ inferred result — synthetic call@ / entry@ cases never fail the run

Full list — per-code anchors, minimal repros, Abs views, and fixes: Diagnostics glossary.

L1 — explicit contracts​

Refinements are declared with @nudo:contract — Preds that enter Abs and participate in algebra.

/// @nudo:import { positive } from "./shapes.nudo.js"

/**
* @nudo:contract x positive
*/
function needsPositive(x) {
return x;
}

needsPositive(-1);
// [ERROR L12 needsPositive] needsPositive[x]: argument ⊭ precondition (nudo:constraint-violated)
// actual: -1 #exact
// expected: x > 0
// → use a value satisfying x > 0, or relax the precondition on x

if is not a refinement. Clamp-style guards accept out-of-range input when no refine is declared:

engine-verifiedRun in Playground
function clamp(n, lo, hi) {
if (n < lo) return lo;
if (n > hi) return hi;
return n;
}
clamp(-5, 0, 10); // OK — no @nudo:contract declared

Nudo does not invent required slots from body AST scans.

L2 — entry throws​

Without an explicit contract, the contract degrades to the JS runtime boundary:

Entry parameters are any. Operations on any/nullish values may throw. Exported functions must not silently carry undeclared, uncaptured throws.

export function getName(user) {
return user.name; // property access on unconstrained `user`
}

Key lines from the report — the full transcript lives in Default output:

signatures
getName(user: any) => any throws TypeError
subtract(a: any, b: any) => number throws TypeError
issues
[ERROR L1 getName] getName (export): may throw TypeError (nudo:entry-may-throw)
[ERROR L5 subtract] subtract (export): may throw TypeError (nudo:entry-may-throw)

Reminder: L1 in the header is the line number — this diagnostic's layer is L2.

What L2 gates​

  • Only entry/export functions — export / export default, CJS exports.x = / module.exports.
  • Internal helpers are not gated. They may throw; observe them in nudo test.
  • try/catch digests throws on a path (removed from exit effects).
  • Module load level: a module whose top-level statement sequence always throws (an unconditional throw) can never be imported — reported once per module as nudo:module-throw (fail-closed: every export is unavailable and the module was not analysed). Conditional throws stay silent (host-dependent), and only syntactic unconditional throw statements count — throws the engine infers from its own host-API approximation are never blamed on the program.
  • Refine narrowing the param to a shape removes or downgrades L2 (becomes L1).

The first fix path is declaring the intentional throw on the function with @nudo:throws — full syntax (Error-family coverage, * wildcard, !! throws case suffix, sidecar fn option) in the directive reference.

Filtering L2​

nudo check src/ --ignore-throws TypeError
nudo check src/ --ignore-throws TypeError,RangeError
nudo check src/ --entry-throws warning # demote L2 while migrating
nudo check src/ --entry-throws off

Semantics:

  • --ignore-throws only filters L2 entry throws — never L1 contract violations.
  • Default: do not ignore any throws.
  • Filters the throws type/shape, not the whole check.

Persist these in package.json#nudo.check — config block: CLI Reference.

Profiles: adoption vs strict​

--profile is a named L2 preset — it is not a way to turn the gate off:

  • strict (default) — L2 entry-may-throw is error.
  • adoption — migration profile: L2 entry may-throw demoted to warning (exit 0), while L1 explicit contract violations stay error. Adoption never swallows L1.
nudo check src/ --profile adoption

Persist it under package.json#nudo.check.profile instead of passing the flag:

{
"nudo": {
"check": {
"profile": "adoption"
}
}
}

L2 entry-throws severity resolves first-match:

  1. CLI --entry-throws — an explicit value overrides any profile
  2. CLI --profile (adoption → warning, strict → error)
  3. package.json#nudo.check.entryThrows
  4. package.json#nudo.check.profile
  5. default strict (error)

Full flag / config table: CLI Reference.

Node analogy​

An uncaught exception makes a Node process exit non-zero. Likewise, undeclared/uncaptured throws on the export boundary fail nudo check. Throws inside an internal call stack are implementation details, handled by the caller or by L1.

Options​

All flags and package.json#nudo.check config are specified once in the CLI Reference. Highlights:

OptionDescription
--watch / -wRe-run on changes (flag, not a verb)
--jsonMachine-readable signatures + diagnostics (CheckJson / CheckJsonMulti)
--quietSuppress the signature table — issues + summary + gate exit unchanged; a clean run prints one summary line (for large CI logs)
--verboseExpand Abs signatures (term/pred/conf detail)
--absPer-function algebra face (shape + conf; --generalize adds the symbolic term/pred α) — observation, still gates L1/L2
--fn <name>With --abs: restrict to one function
--assume <pred…>With --abs: assume constraints on entry params (e.g. x>0 y>=1)
--generalizeWith --abs: polymorphic signatures via symbolic execution
--from <paths…>Usage-site files injecting call records
--ignore-throws <names>Comma-separated L2 throw types to ignore (never swallows L1)
--entry-throws error|warning|offL2 severity (default error)
--profile adoption|strictGate profile (default strict); adoption ≡ L2 entry-throws warning, L1 stays error — see Profiles
--capabilities strict|trustedCapability policy for untrusted source (default strict): side-effectful host globals and node: modules are hidden (nudo:capability-denied, value unknown); trusted restores the legacy builtin-unknown surface. Not a sandbox.
--ghaGitHub Actions inline annotations (::error / ::warning); auto-enabled when GITHUB_ACTIONS=true
--gitlabGitLab Code Quality JSON array on stdout — redirect to gl-code-quality-report.json

Contract diagnostics​

The sidecar / contract-plumbing codes (nudo:contract-*, nudo:dual-entry) are all listed in What it checks. Two scoping rules:

  • Violations written in the analyzed file report nudo:constraint-violated.
  • nudo:contract-domain-exceeds covers call records injected from usage-site files (nudo check --from <paths...>).

CI integration​

nudo check is the CI gate for contracts and entry throws — aligned with tsc --noEmit, except check still prints signatures on success. --abs remains observation but still gates on L1/L2 errors. Exit codes: 0 = no error-level diagnostic, 1 = any error-level diagnostic (L1 or non-ignored L2) — full table in CLI Reference. On large repos, add --quiet to keep logs signal-only: it suppresses the signature table (issues + summary + gate exit unchanged; a clean file prints one summary line).

GitHub Actions​

name: nudo-check
on: [pull_request]
jobs:
nudo:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci
- run: npx nudojs check .

Diagnostics land as PR inline annotations (::error / ::warning) on the offending lines in Files changed — no extra flag needed: GitHub runners set GITHUB_ACTIONS=true, which auto-enables --gha. Pass --gha explicitly to force annotations when that variable is absent; combined with --json, stdout stays machine-readable while annotations still reach the log stream (stderr).

GitLab CI​

nudo:check:
script:
- npx nudojs check . --gitlab > gl-code-quality-report.json
artifacts:
reports:
codequality: gl-code-quality-report.json

--gitlab emits the GitLab Code Quality JSON array on stdout; the redirect writes gl-code-quality-report.json, and declaring it as a codequality artifact lets the pipeline's Code Quality tab render the diagnostics on merge-request diffs.

# machine-readable (1 file → CheckJson; N files → CheckJsonMulti envelope)
nudo check src/lib.js --json

CI wiring recipes​

Monorepo scan roots — gate source roots only, never node_modules, build output, or vendored corpora:

npx nudojs check packages/*/src

L2 adoption policy — by default L2 (nudo:entry-may-throw) is error. Adopting on legacy JS? --profile adoption demotes only entry may-throw to warning while L1 stays error — semantics, persistence, and resolution order in Profiles:

npx nudojs check . --profile adoption

Cache sizing — the analysis session cache is an in-process LRU (default 64 files). Cap it when CI analyzes many projects; raise it for warm hits on one large repo:

NUDO_CACHE_MAX_FILES=32 npx nudojs check packages/*/src # many projects
NUDO_CACHE_MAX_FILES=512 npx nudojs check . # one large repo

Full internal design note (in-repo, leaves this site): docs/ci-nudo-check.md.

Next​