Skip to main content

Configuration reference

Nudo reads project configuration from the nudo key in package.json — there is no nudo.json, .nudorc, or nudo.config.js. Process-level knobs are NUDO_* environment variables.

Where the config is found: for each analyzed file, Nudo walks up the directory tree from that file and uses the nearest package.json that contains a nudo key. A package.json without a nudo key does not stop the search — in a monorepo, a config at the repository root stays visible to sub-packages that have their own nudo-less package.json.

Presence is what stops the search, not truthiness: a nudo key holding a falsy value (false / null / 0 / "") or a malformed value (a string, number, boolean, or array instead of an object) still stops the search — that package is then treated as having no nudo config, and ancestor configs are not inherited. A malformed key prints a note on stderr rather than being ignored silently.

Keys are normalized leniently: invalid values fall back to the default (and nudo.check.entryThrows additionally prints a warning on stderr) rather than failing the run.

Minimal example​

{
"name": "my-app",
"nudo": {
"check": {
"profile": "adoption",
"ignoreThrows": ["TypeError"]
},
"analysis": {
"mode": "exports",
"exclude": ["**/node_modules/**", "**/dist/**", "**/coverage/**"]
},
"sessionCache": {
"maxEvalRuns": 64
}
}
}

nudo.check — the CI gate​

KeyValuesDefaultMeaning
check.profile"adoption" | "strict""strict"Named gate preset. adoption demotes L2 entry-may-throw to warning; strict keeps it an error. Never swallows L1 contract violations — those stay errors under both profiles.
check.entryThrows"error" | "warning" | "off""error"Severity of the L2 nudo:entry-may-throw diagnostic. An explicit value beats profile at the same layer. Invalid values warn on stderr and use "error".
check.ignoreThrowsstring[] (throw type names)[]L2-only filter of throw type names (e.g. ["TypeError", "RangeError"]). The CLI flag --ignore-throws merges additively with this list (union), so a project config can be tightened or extended per invocation. Never filters L1 violations.

See CLI reference — nudo check for the flags these mirror and Diagnostics for the codes they gate.

L2 entryThrows resolution order​

The effective L2 severity is the first of these that is set:

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

The same explicit-beats-preset rule applies inside package.json alone (rule 3 before rule 4), so the IDE/LSP gate — which reads only the config — matches the CLI. L1 contract violations are unaffected at every step.

nudo.contract — sidecars​

KeyValuesDefaultMeaning
contract.autoBindbooleantrueAmbient binding of *.nudo.js sidecars for check, LSP enforcement, and contract printing. false stops sidecars from being ambient-loaded. A non-boolean value is invalid: it falls back to true and prints a note on stderr, so check and contract/export never disagree about whether sidecars are bound.
contract.emitstring | string[] (globs, relative to the project root)[]Allowlist for contract emit (nudo contract --emit and the LSP persist lens). Empty = no path filtering. Patterns match the source file path (not the sidecar path); an emit target outside the allowlist is refused with an emit-denied warning.

nudo.env — runtime environments​

KeyValuesDefaultMeaning
envstring[] of env names[]Project-level runtime env presets: built-in "es", "web", "node" (web and node imply "es"), or path-based env modules. Unioned — deduplicated — with file-level /// @nudo:env directives, so both layers always apply.

See @nudo:env for path-based env files and the built-in envs.

nudo.analysis — scope and noise (IDE / watch)​

KeyValuesDefaultMeaning
analysis.includestring[] (globs or paths)[] (no path filter)Path filter for IDE / vite-plugin / watch-scan analysis. A pattern with * / ? is a glob (same compiler and anchoring as analysis.exclude); a pattern without a wildcard is a path: it matches that exact file, or every file under it when it names a directory (src → src/**). A literal is never a substring search — include: ["src"] does not pull in src-other/x.js.
analysis.excludestring[] (globs)["**/node_modules/**", "**/dist/**", "**/coverage/**"]Paths excluded from IDE analysis. An explicitly empty array falls back to this default safety list — the node_modules guard cannot be turned off by accident.
analysis.mode"directives" | "exports" | "all""exports"Which files the IDE / build analyzes: exports = files with export / sidecar / @nudo: directives; directives = only annotated files; all = every target path. Named-path CLI commands (nudo check src/lib.js) analyze the named file regardless of mode.
analysis.diagnostics"off" | "errors" | "default" | "verbose""errors" when mode is "directives", else "default"Diagnostic noise level in the IDE.
analysis.evalMissingSlot"off" | "warning""off"C0.5: emit a nudo:missing-slot warning when evaluation actually hits a missing field on a known shape. Observation, never an obligation — see Limits.
analysis.callSiteBudgetinteger 1–643Precise call-site cases kept per function (polyvariance). Over-budget sites fold symbolically into #widened results.
analysis.maxForksinteger ≥ 15000Total branch-expansion ($fork) budget. When hit: nudo:fork-truncated info and widened results. NUDO_MAX_FORKS wins over this key; invalid values fall back to the default.

Scope tuning recipes (mixed TS/JS repos, directives vs exports) are in Coexisting with TypeScript; budget behavior in Performance.

nudo.inlayHints — IDE display​

KeyValuesDefaultMeaning
inlayHints.parametersbooleanfalseParameter contract inlay hints (the where … text after function parameters, from explicit *.nudo.js / @nudo:contract contracts). The hint shows the constraint's declared form — the sidecar template expression or the directive's constraint name (e.g. where nullable(astNode)) — instead of the fully expanded predicate; the full predicate travels as the hint tooltip (hover). Off by default: the folded text duplicates what hover and the ● contract CodeLens already show, and some contracts (derived parameters) still fall back to long predicate expansions. Return-type inlays (: …) are unaffected.

The VS Code setting nudo.inlayHints.parameters (and the Zed language-servers.nudo.initialization_options equivalent) only provides the default when the project does not set this key.

nudo.cache — project disk cache​

ValueMeaning
trueCache at <projectRoot>/.nudo/cache.
"some/dir"Custom cache root, resolved against the project root.
{ "dir": …, "sign": … }Object form: dir = true / directory string / false (root knob as above); sign = boolean entry-signing switch (below).
false / omittedDisabled (default).

Entry signing (opt-in, nudo.cache.sign: true + NUDO_CACHE_KEY): every cache entry is HMAC-SHA256-signed with a key derived from the NUDO_CACHE_KEY secret. A tampered or forged entry fails verification and is treated as a miss (recomputed, never trusted) — a structurally valid fake green can no longer pass the gate. Signed and unsigned entries live in separate key spaces, so rotating the key means a clean full miss, not a stale hit.

A security knob fails loudly, never silently: enabling sign without NUDO_CACHE_KEY, or a non-boolean sign value, is a configuration error — nudo check / contract / health refuse to run (exit 1, machine-readable on --json) instead of quietly running unsigned. Keep the key in env or a masked CI secret — never in the repo or inside the cache directory.

Off by default — a forged cache report could hide violations, so enable it only on trusted machines and gitignore .nudo/cache. What lands on disk, fail-open semantics, and CI guidance: Performance — the .nudo/cache disk cache.

Precedence note: unlike most keys, any explicit nudo.cache value (including false and the empty string "") wins over NUDO_CACHE_DIR; the env var is only consulted when nudo.cache is unset. An explicit "" means "off", the same as false.

nudo.sessionCache — in-process LRU limits​

KeyEnv varDefaultCaps
sessionCache.maxFilesNUDO_CACHE_MAX_FILES64Whole-file analysis-result LRU entries.
sessionCache.maxFnsNUDO_CACHE_MAX_FNS1024Per-function analysis LRU entries.
sessionCache.maxEvalRunsNUDO_CACHE_MAX_EVALRUNS32Evaluator-run LRU entries.

0 (or env "off" / "0") disables that layer; values are clamped to a hard cap of 65,536. This is a memory-vs-warm-hit tradeoff only — eviction recomputes honestly, results and diagnostics are identical. Details: Performance — session cache limits.

Environment variables​

VariableControlsDefaultValues
NUDO_MAX_FORKSBranch-expansion budget (same knob as nudo.analysis.maxForks)5000Integer ≥ 1; invalid falls back to the default — the default, not the config key (a set-but-invalid env value does not fall through to nudo.analysis.maxForks). Wins over the config key.
NUDO_CACHE_DIRProject disk cache root (same knob as nudo.cache)unset (off)Absolute path, or off / 0 to disable. Only read when nudo.cache is unset.
NUDO_CACHE_KEYHMAC secret for nudo.cache.sign: trueunsetNon-empty secret from env or a masked CI secret. Required when sign is enabled — missing key is a configuration error (the command refuses to run). Never commit it or store it inside the cache directory.
NUDO_CACHE_MAX_FILESSession LRU maxFiles64Integer; 0 / off disables the layer; clamped to 65,536.
NUDO_CACHE_MAX_FNSSession LRU maxFns1024Same rules as above.
NUDO_CACHE_MAX_EVALRUNSSession LRU maxEvalRuns32Same rules as above.
NUDO_DEPS_CACHE_DIRCross-project @types harvest cache root~/.cache/nudo/depsPath, or off / 0 to disable the deps layer. Fail-open; see Performance.
NUDO_HARVEST_NODE@types/node harvestenabledoff disables harvesting Node APIs (explicit skip, not a silent fallback).
NUDO_DRAFT_FORCEWrite guard for contract draftsunset1 allows contract --draft --write (and the agent draft-write tool) when no project root is found for the file, and allows contract --from-dts --write to overwrite an existing machine-generated draft that differs. A hand-edited draft is never overwritten.

Precedence​

The general order is CLI flag > environment variable > package.json#nudo > default, but several keys deviate — each of these is the verified behavior:

KnobActual precedence
L2 entryThrowsThe 5-step order above: CLI flag > CLI preset > config value > config preset > default.
ignoreThrowsAdditive, not overriding: CLI --ignore-throws is unioned with nudo.check.ignoreThrows.
maxForksNUDO_MAX_FORKS > nudo.analysis.maxForks > 5000 (no CLI flag).
sessionCache.*Explicit host API (setSessionCacheLimits) > NUDO_CACHE_MAX_* > nudo.sessionCache.* > default.
Disk cachenudo.cache (any explicit value, even false) > NUDO_CACHE_DIR (only when the key is unset) > off.
NUDO_DEPS_CACHE_DIR / NUDO_HARVEST_NODE / NUDO_DRAFT_FORCEEnv-only knobs; no package.json counterpart.

Config lookup itself (findProjectConfig) is keyed by the analyzed file's location, so different packages in one monorepo can sit under different configs by giving each its own nudo-bearing package.json.