Semantics decisions
-
Signed integer overflow is a checked panic;
wrappingAdd,wrappingSubandwrappingMulfromnish:unsafewrap. Every user-leveli32/i64add/sub/mul— the binary operators, unary minus,op=on locals, fields and elements,++/--— either fits its type or stops the program with Rust's words,attempt to add with overflow(subtract,multiply,negatelikewise), exit 1, the way checked integer division does. It is never undefined:x + 1 > xcannot be folded totruewhilex + 1prints-2147483648(tests/cases/ovf_repro, built at--profile speed;ovf_matrixfor every operator at both widths, on locals, elements and fields).An operation the compiler proves fits is the plain instruction with
nsw, and that flag is then a fact rather than an assumption: it is what lets LLVM widen an induction variable. The proof reads what the bounds analysis knows (Element access) and the declared ranges, as interval arithmetic: a literal, a folded constant,w.length,toI32of au8oru16, aninteger<Lo, Hi>, a maskx & c, a shift or a division by a literal, and a local narrowed by the facts in force. The shapes it proves (tests/cases/ovf_proven_*, one golden each):-
i + 1,i++,i += 1underi < nfor anyi32n, ori < xs.length—iis belowINT_MAX(ovf_proven_below); -
i - 1,i--underi > 0, orn - 1pastif (n < 2) return(ovf_proven_floor); -
arithmetic on declared ranges whose interval fits:
integer<0, 100>operands,toI32(hi) * 256 + toI32(lo)on bytes (ovf_proven_range); -
a local only ever assigned
(...) & c, at every pass of a loop (ovf_proven_mask); -
a bounded accumulation: a local that each pass of a counted
forloop moves by a bounded step stays within the steps the loop can take —sum += toI32(buf[i])over 256 bytes,count++underi <= n(ovf_proven_accumulate); -
what every caller passes: a parameter every call site bounds is bounded in
the callee, recursion included (
ovf_proven_callsite); -
what a function returns: a call to a plain function is the join of its
returns' ranges, a
Result'sOkpayload included, and areturn r.valuehands on the range of the payload the caller passed —clamp(a) + clamp(b),acc + orMinus(half(i & 0xff))(ovf_proven_return;ovf_return_unprovenkeeps the checks when a return, or an argument, is unbounded); -
i * i <= nboundsiby the square root ofn's bound (ovf_proven_square).
Anything else is
llvm.s{add,sub,mul}.with.overflowand a branch on its flag to one cold block per function (per source location under-g) that callsnish_panic_overflow(ovf_checked). The check is not free where nothing proves the operation: a sum folded over a whole array, a recursivefib(n - 1) + fib(n - 2), a counter in a field. Such a loop is not vectorised, and a sum the optimiser used to re-associate keeps its order (docs/BENCHMARKS.mdhas the cost measured).A program that overflows a signed integer on purpose — a hash, an LCG, a wrap-around counter — says so at the operation. Write the arithmetic in
u32oru64, which are defined to wrap and never checked (the conversions back are free), or write it as awrappingAdd,wrappingSuborwrappingMulcall fromnish:unsafe, the plain instruction with no check, like Rust'swrapping_add(tests/cases/unsafe_wrapping;tests/cases/opt_nswfor the default). There is no flag that changes the rule for a whole program:--nsw, which made overflow undefined, and--wrapping, which made every operator wrap, are both refused with exit 2 and a line naming thewrapping*functions (tests/nish/cli.ts). -
-
Unsigned integers never carry a no-wrap flag, in either mode.
u8,u16,u32andu64are defined to wrap, so(255: u8) + 1is0(tests/cases/u_arith_wrap):nuwwould be a claim the language does not make, andnswon a value that has merely passed 2^31 would poison an ordinary result. Write the deliberately-overflowing arithmetic in an unsigned type and it needs no flag at all. -
What is never flagged or checked, whatever the mode: division and remainder (which have checks of their own), shifts,
Math.abs(-2147483648), which still answers itself becausellvm.absis emitted with its poison flag off, the conversions, whichtruncand therefore wrap by definition, and every piece of the compiler's own index, length and allocator arithmetic (tests/cases/opt_nswpins exactly which operations are proven, which are checked, and which are neither). -
f32is a distinct type, not a rounding mode. It never mixes withf64and is never whatnumbermeans; everyf32result is a real 32-bit float, so0.1 + 0.1is0.20000000298023224there and0.2inf64(f32,tests/differential/corpus/f32_round). -
Shift counts are masked, never undefined.
a << busesb & 31on a 32-bit type andb & 63on a 64-bit one, sox << 33isx << 1andx << -1isx << 31, exactly as in JavaScript, rather than the poison LLVM produces for a shift at or beyond the operand's width. The narrow unsigned widths mask to their own width (b & 7on au8,b & 15on au16): JavaScript has nou8to be compatible with, and masking to the width is the rule the other types already follow. A constant count is masked at compile time and emits noandat all; a variable one costs one instruction, which is the price of a language whose premise is that if it compiles, the behaviour is known (tests/cases/bit_shifts,bit_shift_const,bit_shift_fill,bit_shift_narrow;tests/differential/corpus/bit_shifts). -
>>>oni32keeps the signed reading, and this is a deliberate divergence.lshrfills with zeros and the result is read back as the signedi32it is, so-1 >>> 0is-1here and4294967295in JavaScript, which promotes the unsigned 32-bit value into a double. It is the same honest choice the language already makes when integer arithmetic wraps instead of promoting, and it is the wartu32exists to avoid: on an unsigned type>>and>>>are bothlshrand both read back unsigned.i64has no divergence to report, because JavaScript has no>>>for BigInt at all (tests/cases/bit_shift_fill,u_shift_logical; the differential rewrite adds| 0around ani32>>>so Node and the native binary agree, wp13-differential.md). -
Bitwise operators cannot fail. They have no divisor check and no panic path, unlike
/and%, so a function whose arithmetic is all bitwise keepsreadnoneandwillreturn(tests/cases/bit_attributes). -
Integer division is checked:
sdiv/sremtruncating toward zero (-7 / 2is-3,-7 % 2is-1;tests/cases/cf_collatz,cf_do_while), preceded by a divisor check that exits with status 1 on a zero divisor (attempt to divide by zero) orMIN / -1(attempt to divide with overflow), like Rust and unlike JavaScript's0(tests/cases/div_checked,div_zero_panic,div_overflow_panic; Checked integer division). -
Math.powfollows ECMAScript where C99powdiffers (pow(x, NaN),pow(±1, ±Infinity)areNaN; see theMathtable). -
f64follows IEEE-754:x / 0isInfinity,x !== xdetects NaN (fcmp une),%isfrem(tests/cases/f64_mode,conversions). -
Strings are immutable UTF-8 byte sequences;
.lengthis the byte length ("héllo".lengthis6, not JavaScript's5);===compares content; there is no implicit conversion ("a" + 1is an error; write`a${1}`); no ordering (<) is defined (tests/cases/str_length,str_eq,reject_str_plus_number,reject_str_lt_str). -
Number formatting matches
String(x)in JavaScript (seeconsole). For anf64that means the fewest digits that read back as the same double, which is not the same as the correctly-rounded string of that length:7.120236347223045e-307prints those sixteen digits and not the seventeen a round-and-check search settles for (tests/cases/f64_shortest_digits). -
Math.roundrounds half toward +infinity like JavaScript, andMath.round(-0.3)is-0in both.Math.min/Math.maxon a float answer NaN when either operand is NaN and order-0below+0, as JavaScript does (tests/cases/math_minmax_nan,math_round_negzero). Both take exactly two arguments, and so doesMath.hypot. -
toI32/toI64fromf64saturate (NaN -> 0,toI32(5e10)->2147483647) like a Rustascast, not JavaScript's modulo-2^32ToInt32. Integer-to-integer conversions wrap (toI32(5000000000)->705032704) (tests/cases/conversions). -
A program can be run under Node as the TypeScript it is, in f64 mode and within a stated overlap, with
runtime/nish.mjssupplying the globals Node lacks and nothing rewritten (RUN_UNDER_NODE.md). Every decision on this page is a reason it is an overlap and not an equivalence. -
No exceptions. Functions are
nounwind, there is nothrowand no unwinding, and a failure a caller should handle is aResult<T, E>(tests/cases/res_basic); runtime failures (bounds check, integer division, file errors, out of memory) print a message to stderr and exit with status 1 (tests/cases/arr_bounds_panic:index out of range: <i> >= <len>;str_slice_panic:slice out of range: [<start>, <end>) of length <len>;div_zero_panic:attempt to divide by zero). -
Bounds checks on every
a[i]read and write, unsigned, so-1fails (tests/cases/arr_bounds_panic), and the same unsigned compare guardss.charCodeAt(i)and the two ends ofs.slice(a, b)(tests/cases/str_slice_panic).uncheckedGetanduncheckedSetfromnish:unsaferemove the one at their own site (tests/cases/unsafe_get_set), and past one, out-of-range is undefined behaviour. -
new Array<T>(n)zero-fills (0/false), no holes; pointer element types are rejected because a zeroed pointer would be null (tests/cases/arr_new_zeroed,reject_arr_new_string). -
Typed-array names are aliases, not views.
Int32Arrayisi32[]with every array operation butpushandpop, which a receiver spelled with the name refuses as TypeScript does (Typed-array names have nopushorpop); there is no separate buffer type and nosubarray. The alias names are exactly four —Int32Array,Float32Array,Float64Array,BigInt64Array— and an unsigned array has none: a program writesu8[], andUint8Arrayis not a type it can spell. That asymmetry is only a spelling.u8[],u16[],u32[]andu64[]cross a host boundary as the matching typed array (wp30-bytes-interop.md), and an element of one needs none of the masking its scalar twin needs: a scalaru32result travels in an i32 value type and reaches JavaScript negative above 2^31 unless the loader restores it, while an element is a byte indatathatUint32Arrayreads unsigned.boolean[]still has no flat view at all, because ani1must be 0 or 1 and that is a per-element check rather than a reinterpretation. At a host boundary the name is the JS typed array that crosses (wp8-interop.md). -
Evaluation order follows JavaScript:
x op= ereadsxbefore evaluatinge(tests/cases/cf_compound_assign);a[i] = vevaluatesa,i,v, then checks and stores;a[i] op= vevaluatesa,i, checks, loads, evaluatesv, stores (tests/cases/arr_index_read_write), and whenvcan push to or pop fromathe store goes intoaasvleft it, its index checked again against the length then:xs[0] += grow(xs)writes the blockgrowmoved the elements to, and an indexvshrank past panics (tests/cases/cg_sec_compound_element_order);p.f op= vreads the field beforev(tests/cases/cls_compound_field); the target expression is evaluated once whicheverop=it is, soa[next()] |= 1callsnext()a single time and pays for a single bounds check (tests/cases/arr_element_bitwise_assign); array literal elements are evaluated before the allocation (tests/cases/arr_literal);push's argument is evaluated before the length is read (tests/cases/arr_push). -
Arrays and objects are references:
===is identity;const b = a; b.push(2)is visible througha(CLI only); assignment never copies. -
Method dispatch is static.
x.m()calls themdeclared byx's type, decided at compile time. There is no vtable and no virtual dispatch, and since WP25 there is no inheritance either, so there is no override for one to disagree about: every method call in a program names one symbol (see Classes). -
Memory is one global bump arena plus the stack, decided at compile time (see Memory model); nothing is freed individually;
main's wrapper releases everything on exit. Objects, arrays, and strings are never null unless typedT | null. -
Parameters are immutable and used as SSA values; locals use
alloca/load/storeand are promoted bymem2reg. -
Only an
exported function is an external C symbol; the rest areinternalunless--no-strict-exports.
Memory model
There is no garbage collector. Every object, array, and runtime string is placed by one of four mechanisms, all decided at compile time (wp6-memory.md); none changes what a program computes, only where its memory lives and when it is reused.
-
Stack allocation. A
new C(...), object literal, array literal, ornew Array<T>(<non-negative integer literal>)whose value provably does not outlive its function becomes anallocain the entry block (tests/cases/mem_stack_struct,mem_stack_array_literal). "Provably" means the value only ever flows into uses that consume it on the spot (operands, conditions, field and element access,.length,for...of, arguments to callees that do not capture the parameter, runtime builtins) or intoconst-like locals that are never reassigned; it stays in the arena when it is returned, stored into a field or element, pushed, assigned to another variable (let q = pincluded), held by a reassignedlet, or passed to a callee that captures it (tests/cases/mem_stack_escape). A site inside a loop gets one slot, reused every iteration (tests/cases/mem_stack_loop). AResultis the exception to "held by a reassignedlet": anOk/Err, or a call returning a by-valueResult, assigned to aletof the same function goes where thatletgoes, so alet r = Ok(n)assigned again keeps its function's arena scope. Outside a loop each such site is its own alloca; inside one it is arena memory the scope gives back. Aletassigned from itself (r = c ? r : Ok(0)) keeps the arena answer (tests/cases/res_let_reassign, whose 100000 calls leaveArena.used()unchanged). Stack arrays are capped at 4096 bytes of data; a laterpushmoves the elements to the arena and the header stays valid. The slot's type spells the length out, and the length is read from the literal that made the site stackable in the first place, so--number-mode f64— where the same literal reaches the emitter as a converted register — allocates the same[n x T](tests/cases/arr_stack_f64).--no-stack-allocturns this off. -
Automatic arena scopes. A function whose arena temporaries all die with it (a dynamic
new Array<T>(n),pushgrowth on its own array, a string concatenation or template, a number printed byconsole.log, a callee's returned allocation), that neither returns nor leaks an allocation, and has no callee that leaks one, callsnish_arena_markon entry andnish_arena_releasebefore everyret(tests/cases/mem_scope_dynamic_array,mem_scope_string_temp: 100000 calls leaveArena.used()unchanged).A loop's pass gets a scope of its own. A loop whose body allocates, itself or through a callee that leaves memory behind, reads the bump position at the top of every pass and rewinds to it on every edge that leaves the pass: the back-edge,
continue,break, and areturn, which releases the outermost scope open. Aswitch'sbreakstays in the pass. It needs nothing allocated during the pass to be reachable afterwards except through a number, abooleanor anenum, which holds when every one of these does:- no allocation of the pass is stored into memory — a field, an element, an array or object literal, a capturing parameter — by the body or by any callee (the escape analysis above);
-
a local declared outside the body (a parameter, a
forinitialiser, the variable of thefor...ofbeing scoped) of a type that can hold a pointer is assigned only a value older than the pass: a literal,this, another outer local, a field or element read, theconstvariable of a nestedfor...ofover such a value, a call to a function that allocates nothing, or a choice between two of those.s = s + xand every+=on astringare refused; -
pushgrows only an array the pass itself declared with a fresh literal ornew Array; -
a
returnin the body answers a scalar or a value older than the pass, andorReturnis refused; - the function does not call
Arena.markitself.
A string pushed onto an array that is only joined is not stored into memory. When a function binds a
string[]local to its own fresh literal ornew Arrayand then uses it only asparts.push(...),parts.join(...)andparts.length, what it pushes is reachable only throughparts.joincopies every part into a new string, so the pushed values die with the frame, and a loop that calls the function keeps its scope (tests/cases/mem_join_parts_scope: 1000 calls leaveArena.used()where one call left it). Any other use ofpartskeeps the pushed value stored, because it could hand a part back out: an element read (mem_join_parts_readback), afor...of(mem_join_parts_forof), passingpartsto a function (mem_join_parts_passed), another method on it, such asparts.pop()(mem_join_parts_method), or apartsthat names another local's array (mem_join_parts_alias). Assigning or returningparts, and an array the function did not build itself, count the same way. The same holds for astringparameter the function pushes onto such apartsdirectly (parts.push(word), parentheses seen through):joinreads it before the call returns and nothing can reach it afterwards, so the callee does not keep it, the parameter isnocapture, and a loop that builds the argument in the same pass and passes it keeps its scope (tests/cases/mem_join_parts_same_pass: 1000 passes leaveArena.used()where one pass left it). Every negative above keeps the parameter kept as well (mem_join_parts_same_pass_keptreads a part back into an object). The rule stops at the push: a parameter that is first copied into a local (let rest = text), returned, or handed to another user function still counts as kept, since astringpassed on is not followed into its callee. SojsonField(line, ...)andreplaceAllon a line built in the pass still have no scope, and passing them a string older than the pass is what keeps it.A value stored into an array that is returned with it is returned, not stored. When a function binds a local
xsto its own fresh literal ornew Arrayand uses it only asxs[i] = v,xs.push(v),xs.length, an element read that is only tested (xs[i] === null), andreturn xsitself, what it stores is reachable only throughxs, so it goes to the caller with the array and the function lets nothing else out. Only a string, or astring | null, is carried this way: an array or an object holds pointers of its own, which no caller follows a level further down (mem_return_array_nested). So a loop that calls it keeps its scope (tests/cases/mem_return_array_scope: 1000 calls leaveArena.used()where one call left it). Any other use ofxskeeps the stored value stored, because it could hand an element on: storingxsinto a field, passing it to a function, reading an element back and keeping it, namingxsthrough another local, or returning it through a choice (mem_return_array_callee). An arrow argument that readsxsas a capture is a use too, since it may readxswhen the call runs, after a join could have released it (mem_join_parts_captured). Inside the function the value is in memory all the same, so a loop whose pass stores into anxsdeclared outside it keeps no pass scope, and ausing a = arena()block that stores into anxsdeclared before it is refused as any store into older memory is. Only a store that stands as its own statement is carried: an assignment's value is its right-hand side, soh.f = (xs[0] = v)keepsvstored.The caller is what makes this sound. Such a call answers an array whose elements are as new as the call, so the caller follows them as the call itself, as it follows a
readdirSynclisting's: an element read out of it and afor...ofvariable over it are that call's, and a function that returns the array on answers such an array in turn. Passing the array to a function,pop, and every method butlength,join,indexOfandpushcount as storing it, because each could hand an element back where the analysis does not follow (mem_return_array_caller). The same rules close four ways a listing's name used to outlive a scope that released it: returned through a function and kept by a pass, passed to a function that answers it, assigned to a local that is returned, and stored into a field (mem_return_array_readdir).An element of an array whose elements are inline is the address of a slot in that array, so keeping one keeps the array: it is followed as the array in every rule above, and in the function rule too (
tests/cases/mem_loop_scope_interior). A pointer-returning function gets no function scope, so a pass scope is what reclaims its loop (tests/cases/mem_loop_scope:Arena.used()moves as far after 4000 rounds as after one).mem_loop_scope_controlcovers every exit edge, nested loops and aswitch;mem_loop_scope_forofthefor...ofrules;mem_loop_scope_escapea pass value kept in an outer local, pushed into an outer array, stored into a field, stored by a callee, built up across passes and returned, each read back after the arena is reused; andmem_loop_scope_threadsthe same round trip under--threads, where the arena, and so the scope, is per thread. Aforloop's condition and update run outside the bracket. Like the function scope it is invisible to a program except throughArena.used(). A program that wants the same bracket around a block of its own writesusing a = arena(), which this rule checks and refuses rather than declines.A function whose callees are what allocate gets a scope too. One that allocates nothing of its own, returns a number, a
boolean, anenumor nothing, and calls a function that leaves arena memory behind, brackets itself the same way when nothing it or its callees allocate can outlive the call except through the return value. That holds when no allocation is stored into memory anywhere in the call (the escape analysis above), or when nothing the function was handed can hold a pointer at all: every parameter,thisincluded, is a number, aboolean, anenum, astring, or an object whose fields are all numbers, booleans and enums. The one mutable global is module storage, whose elements are pointer-free, so memory older than the call that has a slot a pointer fits in is reachable only through those parameters, and none of it has one (tests/cases/mem_callee_scope, the Are We Fast YetListbenchmark;mem_callee_scope_tree, itsStoragebenchmark, where 10000 runs leaveArena.used()where one left it). A callee that stores what it allocates intothisor a parameter, a function that returns a pointer, and one that manages the arena itself get none (mem_callee_scope_escape,mem_callee_scope_return,mem_callee_scope_control), and neither does a function that reads an allocation back out of what a callee returned and stores it (mem_callee_scope_nested). A callee that already has a scope of its own leaves nothing behind, so it earns its caller no second one.A tail call is marked
tail, and the release moves ahead of it. Areturn g(...)whose arguments are every one a scalar — a number, abooleanor anenum— is the last thing its function does, and is emitted astail call. The marker says the callee cannot reach this frame's stack slots, so the frame may be popped before the jump: the recursion it may be part of then costs one frame however deep it goes, in every build profile,--profile debugincluded, where no optimiser runs at all (tests/link/tail_call_depth_debugrecurses a million levels at-O0and segfaults without the marker, andtests/cases/cf_gcdis a golden small enough to read the marker out of). In a function with an automatic scope the same proof also movesnish_arena_releaseahead of the call, because a release between the call and theretis work after the call and would leave it not last after all (tests/cases/mem_scope_tail_callpins that order, andtests/link/tail_call_depthruns a million levels of it, which segfaults without the move).Refused when an argument is a
string, an array, an object or aResult, because that argument may be memory this frame owns; when the callee is a method, whose receiver is an argument the argument list does not carry and is a pointer by construction; when the callee reads the bump position (Arena.mark,Arena.used), which a release moved ahead of it would make answer a smaller number; and when the call is not the whole of thereturn(tests/cases/mem_scope_tail_call_guards). Like the reclaim below it is invisible to a program: it changes how much stack a recursion costs and when memory is reused, never what a value holds. Turning the recursion into an actual loop, rather than a jump back to the top of the frame, is then the optimiser's job, which every build profile butdebugruns (wp6-memory.md §2b). -
A reclaim at the call site. A function that returns a string can have no scope of its own — the string has to outlive it — so its caller takes the mark instead:
nish_arena_markafter the arguments, thennish_arena_keep(mark, s), which moves the returned string down onto the mark and releases every temporary the callee bumped underneath it. Emitted only when the callee returns a plainstring, allocates, and never lets an allocation out of its frame other than through its return value — so a callee that stores what it built into an object its caller holds gets no bracket, and neither does one returning an array, a struct or aResult, whose values name memory outside themselves (tests/cases/mem_reclaim_call,mem_reclaim_argument,mem_reclaim_guards). Independent of--no-stack-alloc(tests/cases/mem_reclaim_no_stack_alloc), and invisible to a program: it changes when memory is reused, never what it holds (wp6-memory.md §2a). -
Explicit control with the
Arenabuiltins, andnish_reset_arena()/nish_arena_mark()/nish_arena_release()for a C or Node host (wp8-interop.md).
Everything else is bumped from the arena by the inlined fast path, and the
arena is released when main returns. Objects stored into fields or arrays
never move to the stack, and a returned object is always arena memory owned
by the caller.
Target, overflow and linkage flags
-
--target <triple>/--target hostwritestarget datalayoutandtarget triple(the strings clang 18 emits for that triple) into every module:x86_64-unknown-linux-gnu,aarch64-unknown-linux-gnu,x86_64-apple-darwin,aarch64-apple-darwin,wasm32-unknown-unknown,wasm32-wasi, plus common aliases (x86_64-linux,arm64-apple-darwin,wasm32, ...); anything else, andhoston an unsupported machine, is a usage error (exit 2) listing the supported triples (tests/cases/opt_target_triple). The default emits neither line, so clang supplies them at link time; the flag matters when runningoptorllcby hand, which otherwise assume a generic layout and never vectorise (wp9-optimisation.md). It shapes what a compile emits and links, and--fix, which rewrites the sources and emits and links nothing, refuses it with a usage error (exit 2) rather than dropping it, as it refuses-oand--link: fix first, then compile for the target. It refuses-g,--threads,--runtime-declsand--plainthe same way, for the same reason. -
--no-strict-exports: see Linkage above (tests/cases/export_no_strict). -
--strict-exportsis still accepted and now says explicitly what the compiler does anyway; it exists so a build script written before the default changed still runs (tests/cases/export_strict). -
--nsw,--wrappingand--unchecked-indexingare refused, a usage error with exit 2. The first said that signed overflow was undefined behaviour the optimiser could assume away, the second made it a defined wrap, and the third dropped every bounds check in the entry package; the rule is a checked panic now, and no flag changes it. Each refusal names thenish:unsafecalls that skip one check at their own site:wrappingAdd,wrappingSubandwrappingMul, oruncheckedGetanduncheckedSet(tests/nish/cli.ts). --no-stack-alloc: see Memory model above.
The CPU level
-
--cpu x86-64-v3links the program for one CPU level above the baseline: the module and the runtime are both compiled, and linked, with-march=x86-64-v3 -ffp-contract=off, so the code generator may use AVX2, BMI2 and FMA. It is the one level:native,x86-64-v4,armv8.2-aand every other value are a usage error (exit 2, one line), and so is the flag with--profile wasior with a--targetthat is not x86-64. Without--targetthe host's triple is the one checked, so a host that is not x86-64 refuses it the same way; an x86-64--targeton such a host is not refused, and fails at the link as a toolchain error.scripts/build.sh --cpu x86-64-v3is the same build, and refuses thewasmandwasiprofiles. -
It changes the link and nothing else. The IR is byte for byte the IR
without it, so the flag changes no operation's meaning; and
-ffp-contract=offkeeps the code generator from contracting a multiply and an add into one fused, once-rounded instruction the source did not write, so a float prints the same at either level.nish runtakes it too, and both caches key on it: a run or a link at the level never reuses the baseline's binary or runtime objects.--emit-capabilitiesadds a"cpu"key after"entry"; a baseline report has none. -
A release binary stays baseline. A binary linked with the flag stops
with
SIGILLon a CPU without AVX2, so it is for programs that run on machines whose CPU is known. Thenishthe project releases is built without it. The constant-time check reads the runtime and thenish:crypto-ctfixtures at this level as well as at the baseline (CT-16); a level it does not read is not offered (tests/run.js, thecpu levelsection).
Profile-guided builds
-
--pgo-generatelinks an instrumented binary: the module, every runtime unit and, when the program calls it, SQLite are compiled, and linked, with-fprofile-generate, so each run writes a raw profile (LLVM_PROFILE_FILEnames it).--pgo-use <file.profdata>compiles and links the same units with-fprofile-use=<file>, the file's real path, so a relative path means the same file whichever unit compiles from which directory.scripts/build.sh --pgo-generateand--pgo-useare the same build. -
Each needs
--linkand thespeedorsizeprofile, and the host. Both flags at once, either without--link, with--profile debugorwasi, with a--targetthat is not the host's, or innish runis a usage error (exit 2, one line, nothing written). The--pgo-usefile must exist and begin with the indexed profile's magic bytes, whichllvm-profdata mergewrites: a directory, a raw.profraw(named, with themergethat fixes it) or any other file is refused the same way, and so is onellvm-profdata showcannot read.llvm-profdatamissing fromPATHis a toolchain failure (exit 3). -
It changes the link and nothing else. The IR is byte for byte the IR
without it. A profile-guided link compiles every runtime and SQLite unit
itself: it reads no entry of the runtime cache and writes none, so a plain
link after an instrumented one is byte for byte the plain link before it
(
tests/run.js, thepgosection).
The debug arena
-
--debug-arenalinks the program against a runtime compiled with-DNISH_ARENA_DEBUG(scripts/build.sh --debug-arena). The IR is byte for byte the IR without it. Under it every arena block is a chunk of its own, on pages no earlier block had, withcapexact, so the inline bump never fits again and every allocation and every scope's release reaches the runtime. A release or reset retires each chunk it frees: its pages becomePROT_NONEand go back to the system, but their addresses stay reserved, so a read or write through a reference that outlived its scope faults at that access. The runtime writesnish: --debug-arena: stale arena reference at 0x…to stderr, and the program dies ofSIGSEGV. A fault elsewhere goes to the handler that was installed before. -
It needs a link and a native profile. Without
--linkand outsidenish runit is a usage error (exit 2), and so is--profile wasi;scripts/build.shrefuses it with thewasm,wasm-host,wasiandnapiprofiles.nish runtakes it, and the run and runtime caches key on it, so a debug-arena build never reuses a normal binary or runtime. -
It is for tests, never a release. Each block takes at least a page and
no address is reused, so memory only grows; a process at its limit of
mappings fills a retired chunk with
0xDBinstead of unmapping it. The rules in Memory model mean no correct program reads released memory, so a trap under the mode is a compiler or runtime bug (security/runtime.md).
Diagnostics and debugging flags
-
Errors are collected, not thrown on the first. Phase 0 reports every forbidden construct in a file; pass 1 recovers per declaration (a rejected class, interface, import or function signature is skipped); pass 2 recovers per statement (the enclosing function is marked poisoned and the next statement is checked). A phase that found anything stops the pipeline before the next one, so pass 2 never sees a broken signature and the emitter never sees a poisoned function. Errors print in source order (files in load order), at most 20 before
...and N more errors, followed by anN errorsline; a lone error prints exactly as before (tests/cases/reject_multi_error,reject_multi_forbidden,reject_multi_decl). Alet x: T = <rejected>still declaresxasTso later uses do not cascade. -
Performance warnings are the one diagnostic that is not an error (WP15 §8). The compiler reports one whenever it had to take a slow path and a faster one was available, or whenever it can prove that a piece of arithmetic does not compute what it was written to compute, in the same anchored, excerpted shape an error has but with
performancewhereerrorwould be:file:line:col: performance: <text>. They are on by default, print on stderr, and never change the exit code: a program that trips one still compiles and still exits 0.--no-warn-performancesilences the class and changes nothing else — the IR is byte-identical either way. The standard library and the examples compile with none, in both number modes where they compile, andnpm testfails the day one of them warns; the compiler's own source is held to a per-code count that may only fall (.claude/testing.md, "The performance gate"). A compilation that failed prints its errors and none of its warnings; a report of more than one warning is capped at 20, like the error report, with...and N more performance warningsand anN performance warningsline. They print in the order a reader reads a file — by file, in the order files are first warned about, then by position in that file, then by diagnostic code where two rules report at one position — which is also the order of the--jsonstream and is a contract rather than a presentation detail. Within a file it is not the order the analysis finds them in: a generic's body is checked when one of its instantiations is finished, and the padding rule below is decided a whole pass earlier than the others (tests/cases/diag_order,tests/cases/diag_order_pass1). The fourteen below each name the rewrite; the class also holds NL9012, aparallelMapIntobody that allocates per element (Data parallelism), and the retired NL9014 and NL9015, which noted the removed--unchecked-indexingand--wrapping:-
quadratic string building —
s = <something built from s>wheresis a string local declared outside the loop the assignment sits in, so every pass copies the whole accumulator. The hint is astring[]and onejoin(tests/cases/perf_str_concat_loop). Not reported when the result does not include the target (line = part + "!"), when the accumulator is declared inside the loop and therefore reset every pass, or outside any loop (tests/cases/perf_str_concat_quiet). -
allocation in a loop — a
new Array<T>(n)with a non-constantndeclared inside a loop whose value never leaves the iteration. A dynamically sized array cannot be a stack slot, so the arena grows once per pass; the hint is to hoist it above the loop or to open the loop body withusing a = arena()(tests/cases/perf_alloc_loop). Not reported for anew C(...), an object or array literal, or anew Array<T>(<literal>), all of which the escape analysis already turns into one entry-block alloca whose slot is reused every pass, and not when the value is pushed, stored, returned or passed on, because then the program asked for one object per iteration (tests/cases/perf_alloc_quiet). -
an allocation dropped by an assignment —
p = new Point(n)wherepwas declared holding an allocation of its own. The value it held is unreachable from there and nothing frees it, and assigning a local is also what takes away the proof the automatic arena scope needs (Memory model), so the whole body's allocations live until the program exits. The hints are aconstper value and, where the assignment is the point, a block around the body that opens withusing a = arena()(tests/cases/perf_arena_drop). Not reported when the local was declared holding a literal and is then given its one value in a branch (let what = "unbound"; if (...) what = \long ${s}`;), which drops nothing and has no rewrite — that function still loses its arena scope and still retains its memory, silently, unless it earns the scope through its callees ([Memory model](#memory-model), item 2), which is a known gap rather than a guarantee ([wp6-memory.md](https://github.com/amritk/nish/blob/main/docs/wp6-memory.md), "Left out") — aletholding aResultis no longer in it ([Memory model](#memory-model), item 1); when the assigned value is not an allocation; when the function returns a pointer, because then its caller owns the memory; when the value being dropped may already be reachable from somewhere else, which is a question of order — a capture anywhere in the enclosing loop, or one that finishes before the assignment starts, leaves the old value reachable and theconstrewrite inapplicable (a capture is the value passed to a call or a constructor, either arm of a conditional included, a method called on it unless it is a string, an array or aResult, whose methods hand back a flag or the payload and never the box, areturn, an element of an array or object literal, or the right-hand side of an assignment or a declaration); or when the quadratic-string rule is already reporting the same line (tests/cases/perf_arena_quiet`). -
an allocation dropped on every pass (NL9016) —
x = <allocation>as a statement of its own at the top of a loop's body, wherexis a local declared outside that loop. Each pass drops the value the pass before gavex, and nothing frees it while the loop runs: the pass cannot take a scope, because its fresh value outlives it inx, and ausing a = arena()block refuses the same assignment (NL2418). So memory grows with the number of passes; 10,000,000 passes oflast = \item ${i}`peaked at 392 MB where the rewrite peaks at 11 MB. The hints are aconstinside the loop when only the pass reads the value, or numbers kept across passes and the value built once after the loop (tests/cases/perf_arena_pass_drop). AnOk(...)orErr(...)inside a loop is such an allocation unless itsResultis passed by value, so alet rgiven a new one on every pass is reported, and so is one assigned over another inside the pass (NL9003). Reported whatever the local was declared holding and whatever the function returns, since the dropped values are this assignment's own; a line the rule above already reports is its alone. Not reported for an assignment inside a branch, which may run once, as a search loop'sfound = ...before itsbreakdoes; in a body whose top level ends the loop withbreak,returnorthrow, or in ado ... while (false), either of which runs at most once; for a local declared inside the loop; when the assigned value is not an allocation; or when a capture anywhere in the loop, as the rule above counts one, may keep the old value reachable, ashead = new Node(i, head),picks.push(i > 0 ? tag : "none")andcur.attach(reg)do (tests/cases/perf_arena_pass_quiet`). -
a loop that leaves a callee's memory behind — a call inside a loop to a function that leaves arena memory behind (it allocates, lets none of it escape, and has no scope of its own) whose result dies with the pass, where neither a scope around the pass nor one around the function reclaims it (Memory model, item 2), in a function of any return type. Every pass adds memory that nothing releases before the function returns, and the function does not release it then either. The warning names what refused the pass its scope — the line of an allocation stored into memory, a callee that stores one, the line that keeps what the pass allocated in a local declared outside the loop or grows an array older than the pass, or a callee that releases or resets the arena — and what refused the function its own, and the hints are to keep what a pass allocates out of outer locals and older memory, or to open the loop body with
using a = arena()(tests/cases/perf_arena_loop). A call in aforloop's condition or update is outside the pass's bracket and is reported as such. It is found after the whole-program analysis rather than by the checker, because every half of it is that analysis's facts. Not reported in a function that callsArena.markitself, whose author is already managing the memory, whatever it returns (tests/cases/mem_callee_scope_control); when the callee stores what it allocates, because then the program is keeping it; when the result is returned, stored, pushed or passed on; or in a loop whose pass canreturnwhat it allocated, which no bracket could release, so there is no rewrite to name. -
a pass of an unbounded loop that keeps what it allocates (NL9018) — an allocation that
--emit-arenamarks"accumulates":true, where some loop between it and its release has nothing bounding how many passes it runs."accumulates"means the allocation runs on every pass of a loop that releases nothing per pass, and nothing reaches it once the pass ends.That is the shape of a request loop on
Http1Server. Its pass callsacceptorrespond, which store into the server's memory, so the pass is refused its scope. A reply string built in the handler then stays allocated for as long as the server runs:tests/link/nl9018_server/leaky.tsgrew 1,252 kB over 20,000 requests, and the rewrite grew none.What a pass keeps counts at any depth of calls. A function the pass calls leaves memory behind in the loop when all of these hold:
- it answers no memory (a number, a
boolean, an enum or nothing); - it has no scope of its own and manages no arena;
- it builds a temporary that it drops, or calls a function that leaves one behind by this same rule, on every call that returns.
"Every call" admits one kind of branch: an
if (p === K),if (p !== K)orswitch (p)on a parameterpagainst a constant.Kis a literal, a name that is neither a parameter nor alet, or a member of a name that is not a local, such as an enum's. A handler that dispatches on the event it is handed therefore counts. The warning names the call in the pass and the site, as in "whatreadPostleaves behind on line 102 (the string built on line 69, inreadPost) piles up". Its rewrite puts the block inside the function that builds the temporary. When that function is instd/or a dependency, the rewrite puts the block in the loop body instead.tests/link/nl9018_server/helper_leaky.tsbuilds its reply in areadPosthelper that also answers, soreadPostis refused a scope of its own.method_leaky.tsreaches the same helper from the loop throughApp.readyandApp.onEnd. Each grew 1,252 kB over 20,000 requests, and each rewrite (helper_flat.ts,method_flat.ts) grew none.These are not charged to the loop:
- what a function that answers memory builds, which goes to its caller with the result;
- a temporary under any other branch, or after a statement that can return, such as an error message, a table built on first use or one step of a handshake;
-
a temporary whose every path ends the program (
panic,process.exit), whether it is built in the call's arguments or in a statement before it, as inconst msg = ...; panic(msg).
A loop is bounded, and NL9018 stays silent for it, when one of these holds:
-
It is a
while,doorforwhose condition has an order comparison (<,<=,>,>=) as a conjunct of its top-level&&chain. The condition must call nothing but the numeric conversions (toI32and its kin), and read nothing but locals, fields (.lengthamong them) and constants. A call to any function of the program or ofstd/anywhere in the condition makes the loop unbounded. -
It is a
for...ofwhose body cannot extend the collection it walks: an array or a map, named by a local or a field path such aslog.items. The body extends it only through the same walked expression, by one of these:-
adding to it:
push,unshift,splice,setoraddon it, or a write throughwalked[k]; ++or--on it, or spreading it;-
passing it to a call or a
newwhose callee may resize an array, or that goes through a function reference; - assigning it, or storing it in a variable, field, array or object.
Any other use leaves the walk bounded, and so does a call in the body that resizes some other array.
-
adding to it:
Every other loop is unbounded:
while (true)andfor (;;);- a flag with no comparison (
while (running)); - equalities only (
while (a !== X && a !== Y)); - a top-level
||(while (next >= 0 || next === FULL)); -
a call in the condition (
while (more(log)),while (k < n && poll())); - a
for...ofwhose body extends what it walks, as above; - a bounded loop inside an unbounded one that releases nothing.
The rule has known blind spots. A comparison loop whose body never moves toward its bound still counts as bounded. So does a
for...ofwhose collection grows by a way the rule does not follow: through an alias (const a = q; for (const x of q) a.push(x)), through a method that growsthis.itemswhile it is walked, or when the walked expression is not a local,thisor a field path (a call result or an index expression).There is at most one warning per loop, at the innermost loop whose pass releases nothing. It names:
- the first site and its kind, and how many more there are;
- where the memory goes back;
- why the pass has no scope;
- the rewrite.
The rewrite moves the per-pass work that builds the temporary into a block inside the loop body that opens with
using a = arena(). The compiler refuses that block (NL2416 and its family) if anything allocated there could outlive it (tests/cases/perf_arena_unbounded_pass).Only a temporary the pass drops counts. These do not: an array a
pushgrows, a value stored or passed on, and a call to a function that stores what it allocates. A temporary handed to a callee that keeps it is passed on, so it is not counted. A temporary from which every path leaves the loop, byreturn,throwor abreakout of it, is built at most once each time the loop runs, so it is not counted either. Inside nested loops it has to leave every unbounded loop out to where its memory is released, not only the innermost: an unlabelledbreakends only its own loop, so a temporary that breaks out of afor...ofinside awhile (poll())still counts, while areturnor abreakto a label on the outer loop leaves both. The walk that proves it gives up at aswitch, atryor a nested loop, so a temporary that areturninside aswitchleaves with still counts.Not reported for:
- a bounded loop;
- the same temporary inside the block;
- a loop whose pass takes its scope;
-
a site NL9002, NL9003, NL9011 or NL9016 already reports, as the value
of the assignment or the call that warning sits on
(
tests/cases/perf_arena_unbounded_quiet).
It reads the
"accumulates"fact--emit-arenaprints, then keeps only the temporaries a pass drops, and changes no byte of the IR. - it answers no memory (a number, a
-
a function that keeps memory on every call (NL9019) — a function that keeps an allocation of its own past the call (a local assigned more than once, or an array of its own; a value it only hands to a function's parameter does not count, nor does one it only places in an array or object literal that is itself handed to a parameter or to
spawnSync, or only reads in place, as in[a, b].join(",")), so that it has no arena scope of its own, and that a loop pass which releases nothing calls directly. Every pass adds the allocation the call kept, and nothing releases it while the loop runs. Reported once, at the function's declaration, naming the line of the first allocation it holds; the hints are aconstper value, a block that opens withusing a = arena()around the work, or a region for what must outlive the call (tests/cases/perf_kept_memory). The rule counts passes, not their number: a short fixed loop such asfor (let i = 0; i < 3; i++)warns as an unbounded one does. Not reported when the function returns a value that is not a number, a boolean, an enum or nothing, because then its caller owns the memory; when it manages the arena itself, feeds tasks, or fills a parameter; when it is a constructor reached bynew; or when every loop that calls it releases what it kept — a pass with a scope of its own, or a call inside ausing a = arena()block. A loop nested in such a block, or in a pass of an outer loop that has a scope of its own, counts as released, because the memory goes back when that block or pass ends: a block around a loop that never ends silences the warning without bounding the growth. Only a loop's direct callees are judged, each on its own allocations: memory kept deeper in the chain, behind a direct callee that answers memory, is not this warning's, and--explain-memorylists it (tests/cases/perf_kept_memory_quiet). No call is excused for the object it receives: a function that does its work once, behind a guard on a field (if (s.ready) return; s.ready = true), still warns when it keeps an array of its own, because the rule does not prove which object reaches it on each pass; open a block withusing a = arena()around that work (tests/cases/perf_kept_memory_direct). A value handed to a callee's parameter is not counted as kept even when the callee stores it into something older (add(list, makeItem())): this rule does not report that retention. -
a constant computed with overflow — a
+,-or*over decimal literals whose exact value does not fit thei32it is computed in. By default that operation panics when it runs, so the hint is to widen the operands withtoI64or to write it as awrapping*call fromnish:unsafe(tests/cases/perf_overflow_const). Reported on the innermost expression that overflows, so100000 * 100000 + 1warns once. Silent for awrapping*call, where the wrap is the defined answer, silent for the unsigned widths, which are defined to wrap in both modes, and silent for anything the folder does not evaluate — a namedconst, a hexadecimal literal, or a value large enough that the fold itself would have to overflow to find out (tests/cases/perf_overflow_quiet). A module-levelconstneeds no warning: its fold is eager and an overflow there is a hard error. -
a product widened after it has already overflowed —
toI64(a * b)ortoF64(a * b)where the operand expression isi32. The multiplication happens ini32, where a product past its range panics before the conversion sees it, so the wider type never holds the value the reader expects; the hint is to convert the operands first (tests/cases/perf_overflow). Not reported when the arithmetic is already done in the wider type (toI64(a) * toI64(b)), which is the rewrite itself, and not for+or-, which can overflow too but whose shape is usually innocent:toI64(intBits(t) - 1)has nothing wrong with it, and a warning there would be the un-actionable kind. -
a shift count at or beyond the operand width —
x << 32on ani32. The count is masked to the width, so the shift that runs is not the shift that was written; the hint is to mask deliberately or to shift a wider value (tests/cases/perf_overflow). A count inside the width is silent. -
a bounds check that was not eliminated —
a[i]ors.charCodeAt(i)inside a loop where the proof above did not come off, so the length is loaded and compared on every iteration. The hint is the guard that always works —if (i >= 0 && i < a.length)reaching the access proves both ends, whatever took the proof away — with an unsigned index named beside it, since half the proof then comes off the declaration; for au8,u16oru32index, which thati32test does not type-check against, the hint is the other half alone,if (toU32(i) < toU32(a.length))(tests/cases/perf_bounds_loop,arr_bounds_unsigned_guard,reject_deny_panics_index_unsigned). Under--number-mode f64, where a length is anf64, the bound is spelledtoI32(a.length)(tests/wordings/nl9007_guard_f64_mode, and NL2457'snl2457_deny_panics_index_f64_i32and_f64_ranged). The hint names only a guard that compiles and that the proof credits, so it names none for ani64, au64or a float index, which no spelling compares with the length in a credited way, nor where the module declares its owntoU32(or, under f64,toI32), which the guard would call instead of the builtin; it says so instead (tests/wordings/nl9007_guard_*, and NL2457'snl2457_deny_panics_index_*). Reported on the index, once per access. Where the index is ani32, ani32-based ranged integer or au8,u16oru32, and nothing between the start of its statement and the access branches, loops, calls, allocates or assigns (the README below lists the rest of the conditions), the warning carries a fix:nish --fixinsertsif (!(i >= 0 && i < toI32(xs.length))) { panic("index out of range") }, orif (!(toU32(i) < toU32(xs.length))) { panic("index out of range") }for an unsigned index, at the start of that statement, a guard the proof credits, so an index in range runs as before and one out of range still exits 1, at the guard (tests/fix/guard-*,tests/fix/README.md). Silent outside a loop, where one check is not a cost anybody is paying, and silent unless the receiver is a plain local and the index a plain local or an offset from one,i + c, which are the shapes the analysis knows how to prove — a field receiver (this.source.charCodeAt(this.pos)) or any other computed index was never a candidate, and the rewrite there is to bind them to locals first (tests/cases/perf_bounds_quiet). An offset index is named as written and the guard offered is one on the sum,`if (i >= 0 && i + 1 < ys.length)` proves both ends, and so does a loop condition `i + 1 < ys.length` on a counter that starts at 0, withtoI32(ys.length)under f64 (tests/cases/perf_bounds_offset,tests/wordings/nl9007_offset,nl9007_offset_f64_mode). It carries no fix: an inserted guard would stop ati === -1, whose indexi + 1is in range, so it could change what a program that works today does. -
a range entry that was not proven — a value entering an
integer<Lo, Hi>inside a loop where the proof above did not place it in the range, so the compare and its cold panic run on every iteration. A local is named with the guard that proves it —if (k >= 0 && k <= 99), orif (k <= 99)for a range with no lower end — and anything computed is told to be bound to ani32local and guarded there, or, when it is a counter or a cursor written back into its own range, to be declaredi32with the range on the value that is used (tests/cases/perf_rng_loop,perf_rng_counter). Reported on the value, or on the target of a compound assignment or an increment, once per entry. Silent outside a loop; silent for a proven entry (tests/cases/perf_rng_quiet); and silent for a range whose lower end is neither 0 nor-2147483648, where no guard proves the entry. -
a
substringbound whose clamp could not be folded off —s.substring(a, b)inside a loop where the proof above could not placeaorbin[0, s.length], so that bound keeps thellvm.smin/llvm.smaxpair JavaScript's clamp needs and pays for it on every pass. Two hints, because they are not the same trade: a test that reaches the call (if (a >= 0 && a <= s.length)) keeps the semantics exactly and lets the compiler write the bound through, andslicehas no clamp at all but panics wheresubstringwould have clamped — it was measured 1.18x over an unfoldedsubstringon a lexer-shaped scan (wp15-performance.md §4), and the fold is what closes most of that gap for a bound the guard proves (tests/cases/perf_clamp). Reported on the bound, once per bound, sos.substring(from, to)with neither end proven warns twice. Silent outside a loop, where the clamp runs once; silent for a bound the proof came off, including the literal0that every string proves; and silent unless the receiver and the bound are both plain locals, which is the shape a guard could prove (tests/cases/perf_clamp_quiet). -
a function kept external by
--no-strict-exports— a call, inside a loop, to a function the module does not export, while that flag is in effect. The default gives such a functioninternallinkage, which is what lets the whole-program passes treat the call sites they can see as all of them: specialise the body to those arguments, and drop the out-of-line copy once the calls are inlined. The hint is to stop passing the flag (tests/cases/perf_inline). What it costs is measured as a size: 240 bytes onbench/sieve, whereopt -O3deletes the out-of-line copy under the default and keeps it under the flag, and nothing at all onbench/spectral, whose binary is in fact 64 bytes smaller with it. The wall clock does not move on either (wp15-performance.md §9), so the message names the missed specialisation and no speed figure. It is reported at a call in a loop rather than per function. Reported once per call site. Silent for an exported function, where the ABI is the point; silent outside a loop; silent for adeclare function, which is external because C defines it and so has neither rewrite available —export declare functionis refused, and the flag has no linkage to withdraw from a declaration with no body; and silent altogether under the default, so a build that did not ask for the flag never sees it (tests/cases/perf_inline_quiet,perf_inline_foreign). -
wasteful struct padding — a
classorinterfacewhose declared field order costs it bytes of padding that a different order would not spend. Fields are laid out in declaration order at natural alignment, exactly as clang lays out the equivalent C struct (Classes), so abooleanin front of anf64throws seven bytes of every value away. The message names the current size, the size the same fields reach in their best order, and that order — the fields widest first, same-width fields left where they were written (tests/cases/perf_padding). On aninterfaceit names the second half of the rewrite as well, because the interface's fields are the first fields of every class thatimplementsit and reordering it alone is what stops those classes compiling. It is the rule the report order above was written for, being the only one of the ten decided in pass 1 (tests/cases/diag_order_pass1). Silent wherever the two sizes are equal — fields already widest first, one alignment throughout, a single field, or trailing padding that belongs to the alignment rather than to the order; and silent for a generic instantiation, which shares one declaration with every other instantiation of the same class, so the caret would land on that declaration once per type argument and the order that suits one need not suit another (tests/cases/perf_padding_quiet). A class thatimplementsan interface is held to the part of its order that is its own: the fields of the longest interface it implements are its first fields, in that interface's order, so they stay put, and the rule warns when reordering only the fields after them would shrink the class. The message names the whole order and says the first fields stay whereimplementsputs them (tests/cases/perf_padding_suffix). The fields after them are laid out from where the prefix ends, which is not always widest first. A prefix that ends off alignment leaves a gap, and the order the message names fills that gap with the narrow fields first (tests/cases/perf_padding_suffix_gap). Padding inside that prefix is the interface's, and the class says nothing about it (tests/cases/perf_padding_suffix_quiet).
-
-
Portability warnings are the second diagnostic that is not an error (wp33-round-trip.md §5.2). A program here can also be read as TypeScript and run under Node with
runtime/nish.mjs, and at a few kinds of site the two readings both run to the end and quietly answer differently;--warn-portabilityreports those sites, in the shape a performance warning has, withportabilitywhereperformancewould be:file:line:col: portability: <text>, and"severity":"portability"under--json. They are off by default — the pass that finds them does not run without the flag — and never change the exit code or a byte of the IR. They print only for a compilation that checked cleanly, after the performance warnings and on the same streams, capped at 20 with...and N more portability warningsand anN portability warningsline, in the same order as the performance report.--no-warn-performancedoes not silence them, and--warn-portabilitydoes not change the performance report. The standard library is not walked: its sites are not the reader's to change, and a program that usesMapnever runsstd/collections.tsas TypeScript at all. A difference TypeScript reports loudly (orReturn,OkandErr, a host global, anish:specifier,export const main,enum) is not one of them, because the TypeScript tests already notice it. The rows, one code each in band NL8xxx:Code Row (wp33 §3) Where it is reported What the TypeScript reading does instead NL8001 UTF-8 offsets (3.2) an offset ( s.length,s.indexOf(t),s.lastIndexOf(t)) or a code unit (s.charCodeAt(i)) of a string that is not provably ASCII, where it meets a fact not counted in bytes: printed, returned bymain, stored (a data-parallel body's answer included), compared or combined with a number literal, taken from a width (width - s.length), used as an array index, a loop bound orparallelFrom's count — directly, through a function it is passed to, or through a helper that returns it; the exact predicate is below the tablecounts UTF-16 code units, so the number differs wherever the text is not ASCII NL8002 checked slice(3.2)a slice(a)orslice(a, b)on a string with a bound that is a negative literal, or that is placed inside[0, length]neither by the bounds proof which folds asubstringclamp nor by the receiver's own text: an ASCII string literal, aconstbound to one, aconstcopied from such aconst, or a module constant that folds to one has a known length, and a bound no larger than it is quiet when it is a non-negative literal, or a local the same bounds proof holds between 0 and that length — aconstor aletits initialiser bounds, or one a guard bounds — and, when the receiver's length is what proves either of two bounds, the first is known to be no larger than the second, from the largest the first can be and the smallest the second can be (tests/cases/port_str_slice_literal_quiet; past the end, a reversed pair such asslice(5, 2), a pair nothing orders, aletreceiver and a non-ASCII literal still warn,port_str_slice_literal_past); one warning per call, at the first such boundclamps the bounds and counts a negative one from the end, where this panics NL8003 a record copied in (3.3) a local record pcopied into a record arrayps(ps.push(p), an element of an array literal,ps[i] = p), when a field of one copy is written after the copy and the other copy is read after that write; the exact predicate is below the tablestores the same object, so a write through one is seen through the other NL8004 a store over a live element (3.3) a whole-slot store ps[i] = vinto a record array while an element reference into the same array (const r = ps[j], orroffor (const r of ps)) is still read afterwards;iandjare not compared, and a field storeps[i].x = vis not a whole-slot storeputs a new object in the slot and leaves rholding the old oneNL8005 zero-fill (3.3) new Array<T>(n)of a number or a boolean, unlessn's value is zero, however it is spelled:0x0,-0,0.0or aconstthat folds to 0 (tests/cases/port_array_zero_fill;[], a zero length and the typed arrays are silent,port_array_quiet,port_array_quiet_f64)fills it with holes, which read back as undefinedNL8006 integer /(3.1)/or/=on an integer type, not already the argument of its own type's conversion (toI32(a / b)does not warn)divides exactly and keeps the fraction. review: the division wrapped in its type's own conversion,toI32(a / b),toU8,toU16ortoU32(q /= dbecomesq = toI32(q / d)), which emits no instruction here and truncates the quotient under Node; none in a generic body, whose one rewrite would serve every instantiation, for/=on anything but a name (p.x /= 2), which the rewrite would evaluate twice, for a/=on a ranged target, whose type is the range and not the conversion's, for a/=whose divisor holds a/(q /= a / b), whose own edit would land inside this one, or with a comment before its/=, which the rewrite would drop, where the quotient's type or an operand's is not exactly the conversion's (au8divided into ani32), whose conversion would change a value, in a module that binds the conversion's name as anything but the builtin (aconst, function, parameter, loop variable, member or import namedtoI32, renamed imports included), where the edit would call that binding, or fori64andu64, which no conversion leaves alone here and truncates there. A ranged operand's/takes the edit: its quotient is the base type, and a quotient's conversion to its own type keeps the quotient's proven range, sotoI32(a / 4) + 1skips the overflow checka / 4 + 1skips. The edits compose:a / b / cwarns twice, both edits inserttoI32(at one offset, and applied together from the end they nest,toI32(toI32(a / b) / c)(tests/fix/port-div-*,port-nofix-div-*)NL8007 wrapping (3.1) + - *, theirop=forms,++and--onu8/u16/u32; a ranged integer is left out, because every write into its range is checkedkeeps counting past the range. No review: a mask ((a + b) & 0xff) or>>> 0still warns and adds anandorlshrhere, andtoU8and its kin saturate under Node where the native value wraps (tests/fix/port-nofix-wrap)NL8008 i32 >>>(3.1)>>>or>>>=whose result isi32, unless the count is a constantk— a literal, or aconstthat folds to one — withk & 31not 0: such a shift is at most 2^31 − 1, so it reads back the same both ways (-16 >>> 2is1073741820in each), andx >>> 0or a count that is not a constant is reportedreads the result back unsigned. No review:(x >>> k) | 0still warns and adds anorhere, andtoI32saturates under Node where the native bits read back signed (tests/fix/port-nofix-shift)NL8009 64-bit integers (3.1) a binding, parameter, field or return type declared i64oru64holds a double, which rounds past 2^53 NL8010 retired nothing: the row was Math.min,Math.maxorMath.roundof anf64orf32, whenminandmaxdropped a NaN operand androundanswered0for a negative number that rounds to zero. They lower to a NaN test and a sign-bit pick (llvm.minimum/llvm.maximumon wasm) and allvm.copysign.f64now, which answer NaN and-0as JavaScript does, so no site diverges (tests/cases/port_num_libmis quiet). The code stays reserved and is never reused— NL8011 retired nothing: the row was console.logorconsole.errorof a float printing-0, and it marks no divergence in the reading the class is defined against.runtime/nish.mjsreplaces both with shims that printString(x), andString(-0)is0, which is what the native build prints. The code stays reserved and is never reused— NL8012 a stubbed generic ( --emit-tsonly)a generic function or method of the program's own modules that no instance reaches, whose body needs the checker's types to translate (a 64-bit integer or a builtin call) throws when called, where the native build has no body to call at all NL8001, exactly. A source is
s.length,s.indexOf(t),s.indexOf(t, i)ors.lastIndexOf(t)(an offset) ors.charCodeAt(i)(a code unit) on astring— an array's.lengthis not one — whose receiver is not provably ASCII: a literal of bytes below 128, a module constant that folds to one, a template,+or?:built only of ASCII parts and number or boolean holes, or a local declared in the same body whose initialiser and every=to it are one of those (s = s + "x"keepssproven). A parameter proves nothing. From a source the value is followed outward through parentheses,toI32/toI64/toF64, either arm of a?:and arithmetic (+ - * / %and the bitwise operators) with an operand that is not a literal, and into a local and every read of it. It is reported where it meets an outside fact:-
it is printed: an argument of
console.logorconsole.error, or a template literal's hole; - it is the exit code: the value
mainreturns, or its concise body; - it is stored: into a field or an element, as an object literal's property or an array literal's element, or pushed on to an array;
-
it is compared or combined with a number — a literal, a signed one or
a module constant — whose value is, for an offset, anything but
0and-1(every string answers those two in both units:s.length === 0,s.indexOf(t) < 0), and for a code unit, 128 or more (a code below 128 names the same character in both units); -
it is taken from a width: the right operand of a
-whose left operand does not itself hold an offset, as inwidth - s.length, the room left in a column that was not counted in bytes; -
it indexes an array (
a[s.indexOf(t)]picks another element) or counts the elementsparallelFrom(n, f)makes — an offset or a code unit alike (table[s.charCodeAt(i) % n]reads another slot where the byte and the unit differ); -
it bounds a loop: either operand of a comparison in a
while,doorforcondition, unless the other operand also holds an offset or is the loop's cursor into the string it counted — a local the loop hands to that string's method, alone or in arithmetic — which counts in the string's own unit (for (let i = 0; i < s.length; i++)overs.charCodeAt(i)is quiet, and so is a bound that moves the cursor by a constant to look ahead,i + 1 < s.length; the same loop overother.charCodeAt(i)alone is reported); -
it is a data-parallel body's answer: stored in the array
parallelMap,parallelMapIntoorparallelFromfills, or folded byparallelReduce(with its identity) into the value the call answers, which is followed on from the call.
The walk crosses functions of the same module that are not generic or methods of a generic class, up to four calls deep. An offset passed as an argument — to a function, a method or a constructor — is followed through the parameter in the callee and reported at the argument, quoting the callee's reason (
`s.length` … and it is passed to `show`, where it is printed). An offset a function returns, or an arrow answers, is followed from every call of it in the module, and from the parallel call that runs the arrow as its body; a call whose string argument is provably ASCII is skipped. A name an arrow captures is provably ASCII when the function that hosts the arrow writes only ASCII to it.The walk is a lint, not a proof, and it is silent where it stops: past the fourth call (a recursive call ends there), into a generic function, a method of a generic class or a function of another module, at a parameter the callee never reads, or one it reads only inside an arrow it passes on, and at the answer of a
spawnbody, whose task is not followed into the value its scope hands back. A recursive helper that answers its parameter is still reported at the call that prints its answer. Once an offset has crossed into another function, the string it counted is out of reach, so a loop it bounds there takes any string's method as its cursor (tests/link/port_utf8_offset_walk_limits).One
+ kon the offset anindexOf(with or without a start) orlastIndexOfof a provably ASCII needle answers, with0 < k <= needle.length, steps inside the match and is not itself a fact from outside:line.substring(line.indexOf(":") + 1)is quiet, and the stepped offset is followed on like any other, so printing it is reported. Everything else is quiet: an offset handed to a string method, compared with another offset or with a cursor, or kept inside a function the walk does not cross, stays inside the program's own counting, soconst width = name.length;alone is not reported (tests/cases/port_str_length_printed,port_str_nonascii_charcode,port_str_needle_step_printed,port_utf8_offset_index,port_utf8_offset_argument,port_utf8_offset_loop_bound,port_utf8_offset_helper_return;tests/link/port_utf8_offset_parallel_body,port_utf8_offset_parallel_from,port_utf8_offset_parallel_reduce,port_utf8_offset_walk_limits; quiet:port_str_ascii_literal_quiet,port_str_offset_roundtrip_quiet,tests/link/port_utf8_offset_quiet; the form with a start:str_index_of_from_port).NL8003 and NL8004, exactly. A record array holds its records inline: its element type is an
interfaceno classimplements, and notT | null. The two rows tell arrays apart by name — a local, or a member chain such asthis.ps— except for an element type the body aliases: when a record array is declared or assigned from anything but a literal or anew, or used other than as an index or member receiver, afor … ofiterable, a call argument or such an assignment's target (const qs = ps,this.f = ps,return ps), every array of that element type is taken to be the same array. An arrow argument's body is its own.-
NL8003's copy site is a local
p, as written, passed tops.push, put in an array literal that initialises or is assigned to a binding, or stored byps[i] = p. It is reported atpwhen a field write (x.f = e,x.f op= e,x.f++,x.f--) throughp, or throughps[k]for anyk, runs after the copy, and the other side is read after that write: any use ofpsafter a write throughp; any use ofpafter a write throughps[k], and any use ofpstoo whenpwas copied in at two sites ([p, p]). "Runs after" is later in the source, or inside a loop that encloses the earlier node and does not declarep. A write through a nested record (p.inner.x) is not one: that field is a pointer in both readings. -
NL8004 tracks the element references
reject_arr_element_across_pushtracks, lesspop()'s, whose slot no in-bounds store reaches; each is live until its block ends, and inside a loop the loop's stores reach a reference that was live on entry. It is reported at the store, naming the reference and the line it is next read on.
Neither row sees an array that reaches a second name through a call, two parameters or fields that already hold one array on entry, a write done in a callee (
bump(p)), a write through an element reference or afor … ofvariable (for NL8003), or a copy whose source is not a local (ps.push(this.p)). They warn where nothing diverges at a self-copy (r = ps[0]; ps[0] = r), at alet prebound between the copy and the write, acrossif/elsearms (which are ordered by source position), at a read ofpsthat is onlyps.length, and at any two arrays of an aliased element type (tests/cases/port_rec_push_then_write,port_rec_literal_twice,port_rec_slot_store_live_ref,port_rec_alias_copy,port_rec_alias_store; quiet:port_rec_push_never_written_quiet,port_rec_slot_store_dead_ref_quiet,port_rec_pop_ref_quiet,port_rec_alias_arrow_quiet).Every row but the retired NL8010 and NL8011 is live, each with a warning case and a quiet counterpart among
tests/cases/port_*and a wording pin intests/wordings/, but NL8012, which only--emit-tsreports: its cases aretests/emit-ts/records/generic-uncalled.ts(warned) andtests/emit-ts/identity/maps.ts(a standard-library stub, quiet), checked bytests/run.js's emit-ts section, and its pin istests/wordings/nl8012_generic_stub. -
it is printed: an argument of
-
Deprecation warnings are the third diagnostic that is not an error. One marks a call the language still compiles, to exactly the IR it always did, and is going to take away in a later breaking release, naming what replaces it:
file:line:col: deprecation: <text>, with the excerpt, and"severity":"deprecation"under--json. They are on by default with no flag to silence them —--no-warn-performancedoes not, andnish runprints them too — and never change the exit code. They print only for a compilation that checked cleanly, before the performance warnings and on the same streams, capped at 20 with...and N more deprecation warningsand anN deprecation warningsline, in the order the other two reports use. A call in a generic body warns once, however many instantiations check it. The standard library and the examples call nothing deprecated, andnpm testfails the day one of them does. Nothing is deprecated today: band NL7xxx holds only the retired NL7001 (Arena.releaseandArena.reset) and NL7002 (--unchecked-indexing's sites), whose constructs were removed before 1.0 rather than kept behind a warning (tests/wordings/unreachable.txt). -
--jsonprints every diagnostic as one JSON object per line on stdout,{"file","line","column","endLine","endColumn","severity","code","message"}(1-based, end exclusive; syntax errors carry asyntax error:prefix inmessage), nothing else on stdout and nothing on stderr, with the same exit code.severityis"error"for every error,"performance"for a WP15 §8 warning,"portability"for a WP33 one and"deprecation"for a deprecated call, which is the field a tool filters on;codeis the stable identifier for the rule (NL1013,NL2231, ...) and is the field to key on, because the prose may improve between releases and the code may not. A diagnostic in a dependency's source — a module resolved into a package other than the root and the standard library — adds"package", the package's name, aftermessage(and before afix), and its human report adds a line under the excerpt,= note: this is in the dependency `pkg_broken` 0.3.1, not in this program's own source(WP21 S3,tests/link/package_dependency_error). A failure with no source position — an unusable C toolchain, an internal compiler error, a bad-olayout — is{"severity","code","message"}. Two optional keys followmessage, each a list of edits[{"line","column","endLine","endColumn","text"}]placed as the diagnostic is, and each absent rather than empty:fix, the rewrite that removes the diagnostic and keeps the program's meaning, whichnish --fixapplies; and thenreview, printed afterfix(WP33 R5), on a portability warning whose rewrite makes the site read the same under Node and compiles to the same IR byte for byte, but changes what the source says, so a person or an agent decides:nish --fixnever applies it. Which rows carry one is the portability table's last column. The bands and the registry are in wp10-ci.md. A clean compile with no warnings prints nothing. -
--emit-astprints the syntax tree of every module after Phase 0 as an indented<KIND> <start> <end>tree — the node kinds ofsrc/nodes.tsand each node's span as byte offsets, identifier and literal text appended — and writes no IR (tests/cases/dump_ast). -
--emit-checkedchecks the program and prints the side tables the emitter would consume: per module its structs (fields with index and byte offset, size, align, constructor and methods), imports, and functions (resolved signature, LLVM symbol, attribute facts, pointer-parameter facts, locals with types, callees) (tests/cases/dump_checked). -
--emit-panics <file.json>writes every panic site of the program, function by function, beside the IR, and changes no byte of it; see Panic sites below. -
--deny-retentionrefuses a program whose own code keeps arena memory that nothing can reach, for a long-running program that cannot afford it; see Retention as an error below. -
--compatselects the compatibility dialect, and--compat=<feature>,...selects it with only the features it names. It is a dialect flag, not a diagnostic one; the rules are The compatibility dialect below. -
--emit-arena <file.json>writes every allocation site of the program with where its memory goes, beside the IR, and changes no byte of it; see Arena placement below. -
--explain-memoryprints, beside the warnings, every loop and function of the program's own modules that keeps the memory it allocates past its scope, and why, and changes no byte of the IR; see Explaining kept memory below. -
-gemits DWARF metadata: aDICompileUnit(DW_LANG_C99) and aDIFileper source file a declaration comes from — the name as it was given on the command line, with.for the directory, so the metadata depends only on the command line and not on where the build ran — aDISubprogramper function, aDILocationon every instruction (each statement's and expression's start; the function's own position for the prologue),llvm.dbg.valuefor parameters andllvm.dbg.declareforlet/constslots.numberisint,i64long,f64double,booleanbool,stringchar*, a class or interface a pointer to aDICompositeTypewith the checker's layout,T[]a pointer to{ long len; long cap; T* data; }. A function's own position — itsDISubprogram'slineandscopeLine, its parameters'DILocalVariables and theDILocationthe prologue carries — is where its declaration starts, which is theexportor theconstand never the arrow's parameter list, so the two spellings of one function describe it identically (tests/cases/dbg_arrow). ADILocationcolumn is a 1-based byte offset into its line, asclang -gwrites it, so a position after a multi-byte character is counted in bytes and not in UTF-16 code units (tests/cases/dbg_utf8). Without-gthe IR is byte-identical.--link -gpasses-gtoscripts/build.sh, which compilesruntime.cwith-gand skips the strip step of every profile (tests/cases/dbg_locals; the-gblock oftests/run.jschecks the linked binary's line table withllvm-dwarfdump).
Writing the program out as TypeScript
-
--emit-ts <dir>writes the checked program back out as TypeScript that Node runs with its type stripping (wp33 §3), one file per module, and emits no IR (src/emit-ts.ts). Each module of the root package keeps its path relative to the directory they all share; each standard-library module the program reaches is written undernish/beside them (std/pair.tsasnish/pair.ts); a dependency package's module is not written. Last comesentry.ts, which importsnish/runtime/node, callsmainand exits with what it answered. Imports are rewritten to match: anish:specifier becomesnish/runtime, the one package the output names,nish:secretincluded (itsstd/secret.tsis not written: the runtime'swipeanswers it, a zero-fill that cannot reach a copy the engine made, so erasure is the native build's alone:docs/security/secret.md, SECRET-6), savenish:async, which becomesnish/runtime/async.mjsbecausenish:processhas aspawnof its own innish/runtime; anish/xor relative one becomes the relative path, with its.ts; and an imported name that is only a type (an interface, a generic interface, an alias) is writtentype X, because Node's type stripping does not know which names are types. A module that needs none of that and none of the rows below is written byte for byte (tests/emit-ts/identity/; the layout istests/emit-ts/layout/); one row that touches an otherwise untouched module is the: stringon an unannotatedconstbound to a string literal. -
The flag turns
--warn-portabilityon: those warnings name the sites where the TypeScript reading answers differently. -
Seven kinds of module are refused, and then nothing is written (exit 1):
one that declares C functions, whose bodies are not in the program
(NL4010,
tests/cases/reject_emit_ts_ffi), and one that importsnish:netor calls anish:netfunction,signalFdorreadSignal, imported or by its global name, whose translation is not local to its statement (NL4011,reject_emit_ts_net,reject_emit_ts_net_global,reject_emit_ts_signal), and one with anx op= ethe TypeScript writes asx = x op e(a width that wraps, a checked i32 operation, an integer/) whose target's index holds a call, a step or an element read, which would then run twice (NL4012,reject_emit_ts_compound). An index of names, their fields (seen.length), literals and their arithmetic is repeated, andpts[i + 1].n += 10is translated. The fourth is a generic whose instances would be written as different TypeScript, which is written once for them all: an element held inline in one instance and by reference in another (PandP | null), or element types with different zeros innew Array<T>(n)(i32andi64) (NL4013,reject_emit_ts_instances). Write a function per element type. A generic no instance reaches (a function, a method, or the methods and constructor of a class no type argument list names) has no types and no native body. Where no type would change its text it is written as it is, through the rewrites that need no type (a[i]is still checked); where a type would (a 64-bit integer, which is abigintthere,f32, a builtin call, arithmetic whose width wraps, a string's.lengthor methods, aResult's), it is written with a body that throws. Such a stub in the program's own modules is a portability warning naming it at its declaration (NL8012,tests/emit-ts/records/generic-uncalled.ts); the standard library's (insertAtofnish/collections) are written without one. The fifth refusal is such a generic in the program's own modules whose body copies an element into an array slot, in a module that holds records inline, or fillsnew Array<T>(n)withT's zero, which only an instance would decide, whatever else in it needs a type, a 64-bit integer or a builtin call included (NL4014,tests/emit-ts/refused/uncalled-zero.ts,uncalled-copy.ts,uncalled-ctor-zero.ts,uncalled-field-zero.ts,uncalled-wide-zero.ts); in the standard library the same body is a stub, without a warning, and the program is written. The sixth is a module that importsnish:region, whose regions the runtime the output imports (nish/runtime) does not answer yet, though a program run under Node as it is written does (NL4015,reject_emit_ts_region); keep it native. Every refusal in the program is reported before it exits. -
It answers in place of the other outputs.
--link,--emit-ast,--emit-checkedand the--emit-header/--emit-dts/--emit-napi/--emit-napi-asyncsidecars are refused beside it with exit 2, and so is-o, once the program is known to be writable.--emit-tswithout a directory is exit 2 as well, and so is a program that cannot be laid out under one directory: a module above the directory of the others, or two modules (or one andentry.ts) that would be written to one path, and so is a directory where a file it would write is one of the program's own modules (--emit-ts .beside the sources), checked before anything is written.
Panic sites
A compiled program can stop with exit 1 in more places than the panic calls
its author wrote: a bounds check the checker could not prove away, an integer
division, a value entering a range, r.expect, a readFileSync of a file that
is not there. Each such place is a panic site, and
--emit-panics <file.json> lists them all, per function, after the checker's
whole-program proofs have run. A site is listed exactly where the emitter
writes a check that can fail or calls into the runtime where it exits; it is
"proven": true where a proof table lets the emitter leave the check out, and
a function whose sites are all proven (or oom) has no panic path in its IR
— npm test holds every golden in tests/cases/ and tests/link/ to that
(tests/panics-oracle.js). The kinds:
index: a[i], read or written, and s.charCodeAt(i): i outside
[0, length); and the second check of a compound store a[i] += f() whose
right side may resize the array
-
What proves it away: the bounds proof of Element
access: a dominating guard, a loop bounded by the length,
or every call site proving the argument (
tests/cases/panics_index); nothing removes the second check of a compound store, which is made after the call however the first was proved (tests/cases/panics_index_recheck)
pop: a.pop() on an empty array
-
What proves it away: a dominating
if (a.length > 0), the length fact the bounds proof already keeps (tests/cases/panics_pop)
slice: s.slice(a, b), dst.set(src, at),
String.fromBytes(bytes, start, end) and the buffer range of netRead,
netWrite, netWrite2, writeBytes, udpSendTo and udpRecvFrom: the
range outside the receiver
-
What proves it away: nothing yet:
substringclamps instead, and is not a site; an array'sxs.sliceis not aslicesite but acallreachingstd/array.ts'spanic(Callback methods andslice) (tests/cases/panics_slice,str_from_bytes_oob,reject_deny_panics_from_bytes,io_write_bytes_bounds,net_write2_bounds)
divide: integer /, %, /= and %=: a zero divisor, or MIN / -1
when signed
-
What proves it away: a divisor that is not 0, and not -1 unless the
dividend is known non-negative: a constant (
a / 2,a % -3, a folded module constant), a ranged or unsigned divisor whose declared range leaves those values out, or a guard on a local divisor —if (d !== 0 && d !== -1),if (d > 0), orif (d !== 0)on an unsigned one. A float division is not a site (tests/cases/panics_divide)
overflow: a signed i32/i64 +, -, *, unary -, ++, -- or
op= whose result does not fit: attempt to add with overflow and its
siblings
-
What proves it away: the overflow proof of Semantics
decisions: an operation the bounds walk proves fits
is
nswwith no check (tests/cases/panics_overflow_proven); every other one is checked (tests/cases/panics_overflow). Anish:unsafewrappingAdd,wrappingSuborwrappingMulis checked nowhere and is not a site
range: a value entering integer<Lo, Hi>, the store of += or ++
into a ranged place, and an exported function's check of a ranged parameter on
entry
-
What proves it away: the range proof of
wp31-ranged-integers.md §8 (Types): a
dominating guard such as
if (n >= 0 && n <= 9), or every call site proving the argument (tests/cases/panics_range)
array-length: new Array<T>(n) whose length type could make a bad
header or a negative byte count (an i64, a float, an i32 or a ranged
integer, a u32 under --number-mode i32)
-
What proves it away: a narrower unsigned length or a literal up to 2^31 -
1, which is not checked and not a site (
tests/cases/panics_array_length)
panic: panic(message)
-
What proves it away: nothing: a path the program never takes is still a
site (
tests/cases/panics_panic)
expect: r.expect(message) on an Err
-
What proves it away: nothing;
unwrapOrandorReturnare not sites (tests/cases/panics_expect)
io-exit: readFileSync, writeFileSync, appendFileSync and
crypto.getRandomValues, which exit inside the runtime on failure
-
What proves it away: nothing;
readFileSyncOrNullis the twin that answersnullinstead (tests/cases/panics_io_exit)
parallel-length: a parallelMapInto call whose dst is shorter than
its src
-
What proves it away: nothing yet: the check is
std/threads.ts's own (tests/link/panics_parallel_length)
ffi-nul: a string argument to a declare function that
holds a NUL byte, which C would read as the end of the string:
`name`: argument N (param) holds a NUL byte, which C would read as the end of the string
-
What proves it away: a literal with no NUL in it, which is not checked and
not a site; every other string is checked, and
string | nullchecks only the string (tests/cases/panics_ffi_nul)
ffi-null: a string result of a declare function that
is NULL:
`name` returned NULL for a `string` result; declare it `string | null`;
or the pointer of a readStruct
call that is NULL: `readStruct` read a NULL pointer into a `Lconv`;
or the pointer of a
readCString call that is
NULL: `readCString` read a NULL pointer
-
What proves it away: nothing: a result declared
string | nullreadsNULLasnulland is not a site (tests/cases/panics_ffi_null); thereadStructandreadCStringtests stay at every call (tests/cases/panics_ffi_read_struct_null,tests/cases/panics_ffi_read_cstring_null)
ffi-length: a call to a
declare function whose count is
larger than a u8[] buffer of its run:
`name`: argument N (count) counts more bytes than argument M (buf) holds,
compared unsigned, so a count that wrapped below zero fails too
-
What proves it away: a count of
toU64(b.length)wherebis that buffer itself, aconstlocal or a parameter named alone, and no later argument may resize an array (tests/cases/ffi_buffer_count_proved,ffi_buffer_late_load); every other count is checked (tests/cases/panics_ffi_length,panics_ffi_length_wrapped,panics_ffi_length_shrink).
region: a call to nish:region's region, regionWith, enter,
enterWith or free: a handle that is 0, freed, another thread's or entered
already, a free of an entered region, or more live regions than the table
holds
-
What proves it away: nothing: the handle is a number the checker does not
follow, so every call checks it (
tests/cases/reject_deny_panics_region)
call: a call into a function that has a site that can panic, directly or
through further calls
- What proves it away: the callee having none (
tests/cases/panics_call)
unchecked: uncheckedGet and uncheckedSet from nish:unsafe: no
check at all, so nothing panics, but an index out of range is undefined
behaviour (readCString and readStruct test their pointer for NULL, so
each is an ffi-null site above)
-
What proves it away: nothing, and nothing needs to: the call is the
author's word that the index is in range, not a
proof, and the
nish:unsafeimport its module must write is the opt-in to that word, so it is listed with"allowed": trueand, likeoom, never makes a function one that may panic (tests/cases/deny_panics_unsafe)
oom: an arena allocation: the out-of-memory exit
-
What proves it away: nothing, and nothing needs to: it is listed with
"allowed": trueand never makes a function one that may panic (tests/cases/panics_oom) -
A
callnames its callee and the kind it reaches ("via"), and is decided over the whole program, the standard library and dependencies included. The kind is the one the callee reaches first at run time, its own checks and its calls taken together: an operation checks its operands once they are evaluated, sopick(xs, i) + 1,1 + pick(xs, i),x += pick(xs, i)and100 / pick(xs, i)reachpick'sindexbefore their ownoverflowordivide, whilepick(xs, i - 1)reaches its argument'soverflowbefore the call (tests/cases/panics_overflow_via). In a cycle of calls made before any check, the cycle's first function in declaration order with a site of its own or a call out of the cycle passes over its calls back into it, and the rest of the cycle reaches what it reaches (tests/cases/panics_call_cycle). The list itself stays in source order, by where each site starts. A generic function's sites are its instantiations', each under its own symbol and decided over its own side tables (tests/cases/panics_generic). -
Two ways a program can stop are not sites, because no proof the checker makes could remove them. Out of memory is listed, as
oom, but excluded: every allocation can fail and no guard in the source prevents it. Stack overflow is a fault the operating system raises, with no handler in the runtime and no check in the IR. Signed overflow is a site,overflow, because it is checked (see Signed integer overflow is a checked panic above). Neither areprocess.exit(n), which is a deliberate exit, or a call into adeclare function, whose body is C the compiler does not see. -
The file is a contract, like
--json: one{"functions":[...]}object, one function per line in module and declaration order, each{"name","symbol","module","line","panics"}, wheresymbolis the function's LLVM name; per site{"kind","line","column"}and then"proven"for a check,"proven","callee"forparallel-length,"callee","via"forcalland"allowed": trueforoomandunchecked. Lines and columns are 1-based, in the units a diagnostic uses. Thewrote <file>line is on stderr, like the IR's. It is written once the program is checked: a program that does not compile writes none, and--emit-checkedwrites it beside its dump.--emit-ast, which stops before the check, refuses it with a usage error (exit 2) rather than leaving the file unwritten, and so donish run, which keeps its build to itself, and--fix, which writes no IR.
The no-panic scope
A module can be required to have no panic site left. --deny-panics puts
every module of the program's own package in the scope; the root package's
package.json — the one nearest above the entry file — puts the modules it
lists there, by their path relative to that file:
{ "nish": { "noPanic": ["src/parser.ts", "src/lexer.ts"] } }
Both together put the union in scope; with neither, nothing changes. In a
module of the scope, every site of a kind above that is not proven is an
error, NL2457, which names the kind and, where a proof the checker makes would
remove the check, the guard that gives it — the same sentence the performance
warnings use for an index (NL9007) and a range entry (NL9013), so one way of
writing each is taught (tests/cases/reject_deny_panics_<kind>, one per kind;
tests/cases/deny_panics_clean is the module that passes, and its IR has no
nish_panic_ call and no panic tail). Where a refused site sits in a loop, the
performance warning about the same check is not printed beside the error.
-
A call out of the scope is refused at the call (NL2458): the standard
library and a dependency are not in the scope — their author, not this one,
proves them — but a call from the scope into one of their functions that may
panic names the callee and the site it reaches (
reject_deny_panics_call,tests/link/no_panic_transitive). A call into a function that is itself in the scope is not refused again: its own sites are. -
A module the list does not name keeps its checks: the same unproven index
is refused in a listed module and compiles in an unlisted one
(
tests/link/no_panic_module,tests/link/no_panic_unlisted). -
An entry that names no module of the program is an error (NL3031),
reported in
package.jsonwhere the entry is written: a typo would otherwise leave the module it meant outside the scope without a word (tests/link/no_panic_unknown_entry). -
The root package's
"nish"field is one object, written once, whose keys arenoPanic,capabilities,host,compatandnetRings, each written once, and anything else is an error (NL3036) wherepackage.jsonwrites it: a second"nish"even when neither holds a policy (caps_policy_manifest_repeated_nish_no_panic), a"nish"that is not an object (caps_policy_manifest_nish_not_object), a key it does not know, a misspeltcapabilitesincluded (caps_policy_manifest_nish_unknown_key), anoPanicthat is not an array (caps_policy_manifest_no_panic_not_array), and a manifest that mentionsnishor carries a\uescape and stops being JSON (caps_policy_manifest_broken_json). Each would otherwise leave part of what the package says about itself unread. A key is decoded asJSON.parsedecodes it, so"ni\u0073h"is"nish"; an escape outside ASCII decodes to a byte no name contains, so it never matches one. -
A
nish:unsafeimport is the opt-in.uncheckedGetanduncheckedSetare reached only throughimport { … } from "nish:unsafe"at the top of the module that calls them, which is the module's word, visible where a reader looks first, that its indexes are in range. So the scope allows them, asuncheckedsites with"allowed": true, and a call into a function whose only unproven sites areuncheckedis not acallsite at all, from inside the scope or out of it (tests/cases/deny_panics_unsafe,tests/link/no_panic_unsafe_callee). The global spellingtscaccepts has no import to show and is refused, scope or not (NL2456,reject_deny_panics_unsafe_no_import). -
Signed overflow is refused where it is not proven. Every signed
+,-,*, unary-,++,--andop=the bounds walk has not proven to fit is anoverflowsite, refused like an index or a divisor, with a hint to bound its operands, compute inu32/u64(the width's unsigned type), or write the operator's drop-innish:unsafeform:wrappingAdd(x, y),wrappingSub(x, y),wrappingMul(x, y),x = wrappingAdd(x, y)for anop=,wrappingSub(0, x)for a negation andx = wrappingAdd(x, 1)orx = wrappingSub(x, 1)for++and--. A proven one is accepted, and so is everywrapping*call, which is defined to wrap and is not a site (tests/cases/reject_deny_panics_overflow,tests/cases/reject_deny_panics_overflow_ops,tests/cases/deny_panics_overflow_proven,tests/cases/deny_panics_overflow_wrapping_add,tests/link/no_panic_overflow). -
What the scope does not cover. Out of memory is listed but never
refused: every allocation can fail and no guard prevents it. Stack overflow
is a fault the operating system raises, with no check in the IR to refuse.
So a module in the scope cannot panic except by running out of memory,
and that is the whole claim. Nor can it reach undefined behaviour through a
check the compiler left out, except where a
nish:unsafeimport says so. -
--deny-panicschanges no byte of the IR: a program it accepts is the one the build compiles without it. With--emit-ast, which stops before the checker, it is a usage error (exit 2).
The compatibility dialect
Nish has two dialects. The strict one is this document. The compatibility
dialect accepts more of TypeScript, feature by feature: it differs from the
strict dialect in the number a bare number is, and in what each feature it
allows admits. This compiler has built six features, nullish,
optional-chaining, string-switch, for-of-string, optional-params and
overloads.
-
--compatselects the dialect with every feature this compiler has built;--compat=<feature>,...selects it with only the features named. A name that is no feature is a usage error (exit 2) that names it and writes no IR, and so is an empty list (--compat=).nish runand--fixtake the flag too. -
"compat"in the root package's"nish"field selects it without the flag:truefor every built feature, or an array of feature names for exactly those ([]for the dialect with no feature). The root package is the one whosepackage.jsonis nearest above the entry module. A value that is neither is NL3036 (tests/link/compat_manifest_not_a_list), and a name in the array that is no feature is NL3056, wherepackage.jsonwrites it (compat_manifest_unknown_feature).--compaton the command line decides the dialect alone when it is given: the manifest's list is still checked, and not otherwise consulted. -
The root package's dialect is the program's ceiling. Every module of a program is compiled in one dialect, the root's. A dependency whose own
package.jsonasks for the compatibility dialect is refused under a strict root (NL3057, at the import that brings it in,tests/link/compat_ceiling_dialect), and one that lists a feature the root's dialect does not have is refused the same way (compat_ceiling_feature). A dependency that asks for no more than the root allows compiles (compat_manifest_program), and so does the first under a build that passes--compat. A dependency's"nish"field is read for this key alone. -
The dialect implies
--number-mode f64: a barenumberis the double, as a JavaScript engine computes it, and every rule of--number-mode f64applies unchanged — its diagnostics included, so amainthat returns a barenumberis refused with NL2140 under--compatexactly as it is under--number-mode f64. A--number-modeon the command line wins, on either side of--compat.--number-mode i32beside the dialect is honoured and priced: oneperformancewarning, NL9020, at the entry module's first character, because arithmetic that leaves 32 bits panics there where the double would carry on (tests/cases/perf_compat_number_i32).--no-warn-performancesilences it, as it does the rest of its class. -
Every module of a compat build says so. Its IR ends with the named metadata
!nish.compat, one node whose first operand is the number mode (!"f64"or!"i32") and whose others are the allowed features in the compiler's order:!nish.compat = !{!0} !0 = !{!"f64", !"nullish", !"optional-chaining", !"string-switch", !"for-of-string", !"optional-params", !"overloads"}A strict build carries no
!nish.compat.--emit-checkedopens with the same facts on one line,compat number=f64 features=[nullish,optional-chaining,string-switch,for-of-string,optional-params,overloads], and prints no such line for a strict build. -
A strict refusal of a construct a feature admits names the feature. It closes with the note
add `<feature>` to `nish.compat` in package.json to accept it, and under a compat build whose list leaves the feature out it also names that build's dialect (this program's dialect iscompat=- ``).
-
optional-chainingadmits a?.chain with no??default where the strict dialect has none to give it. A chain that is a statement of its own,a?.b,a?.m()ora?.b.m(x), runs to its end when every link is there and does nothing from the first one that isnullorundefined, as in Node: the arguments of a call it skips are not evaluated (tests/cases/compat_optional_chain_statement, refused in the strict dialect asreject_optional_chain_statement), so an enum value one of them assigns is, after the call, one the variable may or may not hold, as?:has it (tests/link/compat_optional_skipped_enum).?.[i]is admitted inside a chain that a member, a method call or a??default follows: the element is read, and bounds-checked, only when the array is there (compat_optional_chain_element, strictreject_optional_chain_element_inner). An index read inside a link the chain skips is not counted as checked for the reads after it. Two forms stay refused in the compatibility dialect too, because Node's answer and the build's would part. An element read the chain carries on past is NL1067, since past the end of the array Node answersundefinedand goes on where the bounds check panics: in a??chain or a statement chain, a?.[i]that ends it (tests/link/compat_optional_element_last); and in a statement chain any element read that ends it,a?.xs[i];(tests/link/compat_optional_element_statement), or an element read, plain or?., that a?.link tests,xs[i]?.m();(tests/link/compat_optional_element_before). In a??chain a plain element read a?.tests,xs[i]?.m() ?? d, is the strict dialect's own and keeps its meaning in both: the?.tests a nullable element, and the read is bounds-checked as every element read is. A?.[i]that ends a chain in any other place,const x = xs?.[0], is the?.refusal of a chain with no default, NL1049. And an optional callf?.()is NL1068 (compat_optional_call). -
nullishadmits a??whose left operand is never missing: a value whose type is not nullable, or a nullable one narrowed pastnull(the strict dialect refuses both, as a default with nothing to replace), when the left operand is one of the forms JavaScript can be seen not to answerundefinedfor: a literal (number, string,true,false, template, array or object), a name,this, anew, a unary or binary operation, or a plain member read of one of these, in parentheses or not. Any other left operand keeps the strict refusal in the same words whatever its type: a call,f(x) ?? 1, and a ternary,(c ? a : b) ?? d, are not on the list yet (tests/link/compat_nullish_call_left), nor is an element read, below. Node's answer is always the left operand, so the build keeps the left operand alone and says so: oneperformancewarning, NL9021, at the??, naming the default to drop (tests/cases/compat_nullish_never_missing,compat_nullish_narrowed; strictreject_nullish,reject_nullish_nullable). The default is never run, but it is still checked as the left operand's type, as TypeScript checks it (NL2370,tests/link/compat_nullish_never_missing). A??on a nullable left operand is the strict dialect's own and unchanged. An element read is not never missing, whatever its element type: past the end of the array Node readsundefinedand answers the default, where the bounds check panics, soxs[i] ?? dkeeps strict's refusal in the same words, naming no feature (reject_nullish_element_never_missing). -
string-switchadmits aswitchwhose discriminant is astring(tests/cases/compat_string_switch, strictreject_switch_string). Eachcaselabel is a string literal, a template with no substitution, or a module constant of typestring, parenthesised or not, because a label is compared without being run; any other label is NL2799 (tests/link/compat_string_switch_label_not_constant), a label of another type is the strict`case` label is f64 but the discriminant is string(compat_string_switch_label_type), and two labels with the same text, a constant's included, areDuplicate `case` labelas in an integer switch (compat_string_switch_duplicate): the text is what the label spells once its escapes are read, so"\u00e9"and"é", or a template and the literal it spells, are the same label (compat_string_switch_duplicate_spelling,compat_string_switch_duplicate_template). Fallthrough, into and out of adefaultin any place, an empty case group,returnfrom a case,breakand a labelledbreakout of an enclosing loop, andcontinueof an enclosing loop mean what they mean in Node, and the discriminant is run once, before the first comparison (tests/cases/compat_string_switch_flow). A nullable discriminant,string | null, is nostringand keeps the strict refusal, naming no feature. The switch compares the discriminant with each label in source order, onenish_str_eqcall each, and jumps to the first that matches, or todefault: a chain, not a tree bucketed by length, becausenish_str_eqalready answers on a length mismatch before it reads a byte. -
for-of-stringadmitsfor (const c of s)over astring(tests/cases/compat_for_of_string, strictreject_arr_forof_non_array). Each pass bindscto the next code point, as Node walks a string: a character outside the Basic Multilingual Plane is one pass, not two.cis a newstringholding that code point's UTF-8 bytes.break,continueand labels work as they do over an array. A destructuring head,for (const [a] of s), keeps the array walk's refusal (tests/link/compat_for_of_string_destructure), and so does a nullable iterable,string | null, naming no feature. A string that is not valid UTF-8 (String.fromCharCode(200),String.fromBytes) is walked a lead byte at a time: a pass takes the lead and only the continuation bytes (10xxxxxx) after it, up to the width the lead names, so a lead with none is a pass of one byte and the byte after it starts the next pass, a stray continuation byte is a pass alone, and a sequence cut short by the end is one pass of what is left. The number of passes is then Node's for the same characters (tests/cases/compat_for_of_string_invalid), thoughc's bytes are nish's, not Node's UTF-16.cis fresh each pass, and the walk opens no arena pass of its own: eachcstays until the scope around the loop releases its arena, so a code point kept past the loop, in a variable or returned, is still there (tests/cases/compat_for_of_string_fresh), and a walk ofncode points holdsnsmall strings until then. -
optional-paramsadmits anx?: Tparameter and a default that is not a constant (tests/cases/compat_optional_params, strictreject_param_default_expression,reject_param_default_array,reject_param_default_object). Anx?: Tparameter of a function, an arrow or a method isT | nullinside, and a call may leave it out. It is read only as the left operand of??, parenthesised or not, because a call that leaves it out passesundefinedin Node andnullhere, andx ?? <default>is the one read that gives both the same value; any other read is NL2803 (tests/link/compat_optional_params_read,compat_optional_params_read_paren). Anx?whoseThas nonull, a barenumberor aboolean, is NL2804 (compat_optional_params_value): give it a default instead. A default of a top-level function, an arrowconstincluded, that is not one the strict dialect accepts as a constant, a call, an array, an object or an arithmetic on earlier parameters, runs in the callee, once per call that leaves its argument out, after the arguments and left to right, as Node runs it: a call that writes the argument does not run it. The build gives the function one wrapper per argument count a call may stop at, and each call goes to the wrapper for the count it writes. Only a function every call to which the module sees and routes takes wrappers: an exported function (compat_optional_params_exported), whose callers in another module would pass the default themselves, an overloaded one (compat_optional_params_overloaded), whose signatures name the implementation, and one with a required parameter between two such defaults (compat_optional_params_required_between) keep the strict refusal, with a note that names the rule. So do a method's or a constructor's default, and a function whose earlier parameter is anx?.--emit-tswrites no wrapper: the TypeScript keeps each default where it was written. Without the feature, the refusal of such a default names it (compat_optional_params_default_feature), and anx?stays refused as before (compat_optional_params_feature). -
overloadsadmits overload signatures: a function, a method or a constructor written as bodiless signatures of one name followed by its implementation (tests/cases/compat_overloads; strict, the signatures areFunctions must have a body,tests/link/compat_overloads_feature). The signatures are checked and then dropped, so the build is the implementation's alone. Each signature is held to the implementation, astscholds it: it takes no rest parameter, every argument list it takes the implementation takes too, each parameter type is one the implementation's takes, and it writes the return type, which is the implementation's exactly, which is stricter thantsc, where a return type the implementation's is assignable to will do; otherwise NL2800 (compat_overloads_incompatible,compat_overloads_return). A call the implementation accepts is then held to the signatures: one that no signature takes is NL2801, because the implementation's own signature is not one a caller may call (compat_overloads_no_match,compat_overloads_method_no_match,compat_overloads_constructor_no_match). Only a call that names the function, the method or the class is held to the signatures: a call through a function value is held to the implementation alone. A function with signatures is refused by--emit-header,--emit-napiand--emit-dts, NL2802, since the file would spell only the implementation (compat_overloads_emit_header,compat_overloads_emit_dts). A generic function or class keeps the strict refusal. -
The dialect only adds. A strict build of a program the strict dialect accepts is unchanged by all of the above, byte for byte; what changed for a program it refuses is the refusal's words. A compat build is
--number-mode f64for every program the strict dialect accepts: the same IR but for the mark, the same refusals in the same words. And under one number mode a compat build and a strict build of such a program differ in the mark alone.tests/compat-erasure.jschecks both over every program intests/cases. A feature may accept a program the strict dialect refuses, and that runner compiles each such case with the feature, links it and runs it beside Node, which must print and exit the same; it may never change the answer for a program the strict dialect accepts.
Retention as an error
A program that runs for a long time, a server above all, cannot afford memory
that stays allocated after nothing can reach it: in a command-line tool it is
returned when main does, and in a server it grows until the process is
killed. Six performance warnings are exactly that finding, and
--deny-retention makes each of them an error (NL2462) in the program's own
modules:
| Warning | What stays allocated |
|---|---|
| NL9002, quadratic string building | every intermediate string of s = s + t in a loop |
| NL9003, an allocation dropped by an assignment | the value the local held |
| NL9011, a loop that leaves a callee's memory behind | what the callee left on every pass |
| NL9016, an allocation dropped on every pass | the value each pass replaced |
| NL9018, a pass of an unbounded loop that keeps what it allocates | the temporary each pass built, for as long as the loop runs |
| NL9019, a function that keeps memory on every call | what each call a loop makes keeps |
-
The error keeps the warning. Its text is the warning's, after the code of
the rule that found it, so it names the same rewrite:
`--deny-retention` refuses this NL9016 finding, because the arena memory it describes stays allocated after nothing in the program can reach it any more: `last` is given a new allocation on every pass of this loop …(tests/cases/reject_deny_retention_pass_drop,reject_deny_retention_drop,reject_deny_retention_loop,reject_deny_retention_concat,reject_deny_retention_unbounded_pass,reject_deny_retention_kept, and for aResultassigned over another,reject_deny_retention_result_dropandreject_deny_retention_result_reassign). The warning it restates is not printed as well, and--no-warn-performancedoes not silence the error. -
The program's own modules only. A module of the root package is held to
it; a dependency's warnings stay warnings, as its panic sites stay outside
the no-panic scope, because the program's author
cannot change that code (
tests/link/deny_retention_dependency). - What it does not promise. The five warnings are conservative in the direction of silence: each fires only where the compiler can name the memory and the rewrite, so a program it accepts can still retain memory in a shape no rule recognises (wp6-memory.md, "Left out"). Nor does it cover memory a program keeps on purpose: an array it pushes onto for its whole run is reachable, and so not retention.
-
--deny-retentionchanges no byte of the IR: a program it accepts is the one the build compiles without it (tests/cases/deny_retention_clean).nish runand--fixaccept it; with--emit-ast, which stops before the checker, it is a usage error (exit 2).
Arena placement
--emit-arena <file.json> writes where the memory of every allocation site
goes: the decisions the memory model made, read back in the
order the emitter applies them, so the file and the IR cannot disagree. It is
the audit for the cases no warning names: a site a rule stays silent about is
still in the file, with its placement.
The file is one JSON object, one function per line, in module order and, in
each module, in declaration order followed by the instantiations of its
generic functions, and its sites in source order. The keys and their order are
a contract, like --emit-panics':
{"functions":[
{"name":"main","symbol":"nish_main","module":"tests/cases/arena_placement.ts","line":32,"sites":[{"kind":"new","line":34,"column":13,"placement":"stack"},…,{"kind":"string","line":52,"column":12,"placement":"function","accumulates":true}]}
]}
Per function {"name","symbol","module","line","sites"}, as --emit-panics
writes them, and a generic function once per instantiation. Per site
{"kind","line","column","placement"}, then "callee" for a call and a
builtin, then "accumulates":true where it applies. A site's kind is
new, object, array, string (a concatenation or a template), push,
print (a number console.log formats), builtin (a runtime function that
allocates, such as join) or call (a user function whose memory the result
is). Its placement is the first of these that holds:
| Placement | Where the memory goes |
|---|---|
stack |
an entry-block alloca, reused on every pass of a loop |
pass |
released at the end of each pass of the innermost scoped loop around it |
block |
released when the block of the using a = arena() before it ends |
function |
released when the function returns: its arena scope |
returned |
handed to the caller with the return value, whose placement decides |
caller |
released when the function returns, by every caller's reclaim of the returned string |
kept |
stored into memory older than the function, and as long-lived as it |
unscoped |
released by nothing in this function: it lives as long as the caller's memory, which in main is the rest of the run |
accumulates marks a site that runs on every pass of a loop that releases
nothing per pass — or in that loop's condition or update, which run outside
the bracket a pass takes — and whose memory is unreachable before its
release: pass, block, function, caller or unscoped. Its memory piles up pass
after pass until then. last = `item ${i}` in a loop over ten million
passes is a function site that accumulates in a main that earns a scope
through its callees, and an unscoped one in a function that has none
(tests/cases/arena_placement, arena_placement_loops). A returned or kept
site is memory the program holds on purpose, so it is never marked.
An unscoped site in another function is marked too when that function is
reached from such a pass and leaves the site behind in it, by NL9018's rule for
callees: what the function leaves in its caller's memory piles up in the loop's.
-
The answer is about the site's own function. A scope in a caller can
still release an
unscopedsite's memory: a loop whose pass is scoped takes back what its callees leave behind. Only inmainisunscopedthe end of the run. -
--emit-arenachanges no byte of the IR, and it is a product, as--emit-panicsis:nish runand--fixrefuse it, and so does--emit-ast, which stops before the facts exist (exit 2).
Explaining kept memory
--explain-memory answers, before the program is deployed, the question a
memory budget turns on: which loops hand back what each pass allocated, and
which do not. The memory model gives a pass of a loop, and a
function, an arena scope of its own when it can prove what they allocated is
unreachable at the end; one stored allocation, in the loop or in any callee,
refuses the scope, and the memory the pass allocated then stays until the next
bracket out. The warnings name such a refusal only where they can also name a
rewrite; this report names every one, on stderr, after the warnings (an
excerpt of tests/cases/explain_memory):
tests/cases/explain_memory.ts:21:1: memory: `remember` keeps what it allocates until the memory of its caller is released, because the allocation on line 22 is stored into memory, where this analysis stops following it
tests/cases/explain_memory.ts:43:20: memory: this loop's condition allocates on every pass, outside the scope a pass takes, and keeps it until `extra` returns
tests/cases/explain_memory.ts:43:40: memory: this loop's update allocates on every pass, outside the scope a pass takes, and keeps it until `extra` returns
tests/cases/explain_memory.ts:60:3: memory: this loop keeps what each pass allocates until `main` returns, because line 61 keeps what the pass allocated in `last`, which is declared outside the loop
tests/cases/explain_memory.ts:76:10: memory: this loop's condition allocates on every pass, outside the scope a pass takes, and keeps it until `main` returns
explain-memory: 7 of 9 allocating loops keep what a pass allocates past the pass; 1 of 4 allocating functions with a scalar result keep what they allocate past the call
-
A loop is listed when its passes allocate — themselves, or through a
callee that leaves memory behind — and no scope releases it at the end of
each pass. The line says where it does go back: at the end of the pass of the
scoped loop around it, at the end of the
using a = arena()block around it, when the function returns, or, in a function with no scope, when its caller's memory is (inmain, never: "for the rest of the run"). The reason is the first refusal the analysis met, the one NL9011 names. A loop whose every allocation goes back with ausing a = arena()block or a scoped loop inside its body keeps nothing past the pass and is not listed. A condition orforupdate that allocates is listed on its own line — both, when both do — because it runs outside the bracket a pass takes whether or not the body has one; ado...whilecondition's line follows the lines of the loops in its body. - A listed loop with no bound — one that is not bounded, by NL9018's rule — is the loop NL9018 warns about when what its pass keeps is a temporary the pass drops, or one a function it calls leaves behind; the report lists it either way.
-
A function is listed when it answers a number, a
boolean, an enum or nothing, leaves memory behind, and has no scope of its own. A function that answers memory (a string, an array, an object) is not, nor is a constructor, which answers the object it builds: what it allocates goes to its caller with the result, and whether the caller gives it back is the caller's line. -
The summary counts the loops whose passes allocate and the functions that
answer no memory and allocate, and how many of each keep it. A budget in CI
can hold that count, or the listed lines, against a golden, as
tests/run.jsdoes with a case's<name>.memory(tests/cases/explain_memory). -
The program's own modules only, as
--deny-retentionjudges them. A generic function, or one that takes a function parameter, is explained once per instantiation, under its instantiated name (`each<twice>`), after the functions declared outright (tests/cases/explain_memory_calls). - A callee the analysis cannot see counts as allocating. In a function that allocates, a loop with no scope that calls one is listed, since nothing proves its passes leave no memory behind. A function that allocates nothing the analysis can see is not examined.
- A callee's leak is its caller's. A function whose kept allocation is a call names that callee. One whose own allocation is held where the analysis does not prove it dead names that first, whatever its callees do. One that keeps memory only because a function down its calls holds an allocation the analysis does not prove dead names that function, the one the doubt starts in, even when that function's own scope gives its memory back: the doubt passes up every call.
-
A function is judged by what it still holds when it returns. One with
no scope of its own keeps nothing when every allocation it leaves is inside
a scoped pass or a
using a = arena()block, so it is counted and not listed; one that is listed names the line of the first allocation it holds. -
Under
--no-elisionno automatic scope is taken, so every allocating loop and function is listed except the passes and blocks the program brackets itself withusing a = arena(). - What it does not promise. It reports the scopes the compiler takes, not the bytes: a listed loop over three passes costs nothing, and memory the program keeps on purpose — an array it pushes onto for its whole run — is listed with the line that keeps it. It does not measure memory at run time.
-
--explain-memorychanges no byte of the IR.nish runaccepts it. A build refused after the analysis has run (by--deny-retention, or a check that follows it) still prints the report after the errors, since it says why each refused loop keeps its memory; one refused earlier prints none. With--emit-ast, which stops before the facts exist, with--json, whose stderr is diagnostic objects only, and with--fix, which compiles nothing, it is a usage error (exit 2).

