Semantics decisions

  • Signed integer overflow is a checked panic; wrappingAdd, wrappingSub and wrappingMul from nish:unsafe wrap. Every user-level i32/i64 add/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, negate likewise), exit 1, the way checked integer division does. It is never undefined: x + 1 > x cannot be folded to true while x + 1 prints -2147483648 (tests/cases/ovf_repro, built at --profile speed; ovf_matrix for 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, toI32 of a u8 or u16, an integer<Lo, Hi>, a mask x & 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 += 1 under i < n for any i32 n, or i < xs.length — i is below INT_MAX (ovf_proven_below);
    • i - 1, i-- under i > 0, or n - 1 past if (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 for loop moves by a bounded step stays within the steps the loop can take — sum += toI32(buf[i]) over 256 bytes, count++ under i <= 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's Ok payload included, and a return r.value hands on the range of the payload the caller passed — clamp(a) + clamp(b), acc + orMinus(half(i & 0xff)) (ovf_proven_return; ovf_return_unproven keeps the checks when a return, or an argument, is unbounded);
    • i * i <= n bounds i by the square root of n's bound (ovf_proven_square).

    Anything else is llvm.s{add,sub,mul}.with.overflow and a branch on its flag to one cold block per function (per source location under -g) that calls nish_panic_overflow (ovf_checked). The check is not free where nothing proves the operation: a sum folded over a whole array, a recursive fib(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.md has 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 u32 or u64, which are defined to wrap and never checked (the conversions back are free), or write it as a wrappingAdd, wrappingSub or wrappingMul call from nish:unsafe, the plain instruction with no check, like Rust's wrapping_add (tests/cases/unsafe_wrapping; tests/cases/opt_nsw for 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 the wrapping* functions (tests/nish/cli.ts).

  • Unsigned integers never carry a no-wrap flag, in either mode. u8, u16, u32 and u64 are defined to wrap, so (255: u8) + 1 is 0 (tests/cases/u_arith_wrap): nuw would be a claim the language does not make, and nsw on 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 because llvm.abs is emitted with its poison flag off, the conversions, which trunc and therefore wrap by definition, and every piece of the compiler's own index, length and allocator arithmetic (tests/cases/opt_nsw pins exactly which operations are proven, which are checked, and which are neither).

  • f32 is a distinct type, not a rounding mode. It never mixes with f64 and is never what number means; every f32 result is a real 32-bit float, so 0.1 + 0.1 is 0.20000000298023224 there and 0.2 in f64 (f32, tests/differential/corpus/f32_round).

  • Shift counts are masked, never undefined. a << b uses b & 31 on a 32-bit type and b & 63 on a 64-bit one, so x << 33 is x << 1 and x << -1 is x << 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 & 7 on a u8, b & 15 on a u16): JavaScript has no u8 to 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 no and at 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).

  • >>> on i32 keeps the signed reading, and this is a deliberate divergence. lshr fills with zeros and the result is read back as the signed i32 it is, so -1 >>> 0 is -1 here and 4294967295 in 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 wart u32 exists to avoid: on an unsigned type >> and >>> are both lshr and both read back unsigned. i64 has no divergence to report, because JavaScript has no >>> for BigInt at all (tests/cases/bit_shift_fill, u_shift_logical; the differential rewrite adds | 0 around an i32 >>> 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 keeps readnone and willreturn (tests/cases/bit_attributes).

  • Integer division is checked: sdiv/srem truncating toward zero (-7 / 2 is -3, -7 % 2 is -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) or MIN / -1 (attempt to divide with overflow), like Rust and unlike JavaScript's 0 (tests/cases/div_checked, div_zero_panic, div_overflow_panic; Checked integer division).

  • Math.pow follows ECMAScript where C99 pow differs (pow(x, NaN), pow(±1, ±Infinity) are NaN; see the Math table).

  • f64 follows IEEE-754: x / 0 is Infinity, x !== x detects NaN (fcmp une), % is frem (tests/cases/f64_mode, conversions).

  • Strings are immutable UTF-8 byte sequences; .length is the byte length ("héllo".length is 6, not JavaScript's 5); === compares content; there is no implicit conversion ("a" + 1 is 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 (see console). For an f64 that 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-307 prints those sixteen digits and not the seventeen a round-and-check search settles for (tests/cases/f64_shortest_digits).

  • Math.round rounds half toward +infinity like JavaScript, and Math.round(-0.3) is -0 in both. Math.min/Math.max on a float answer NaN when either operand is NaN and order -0 below +0, as JavaScript does (tests/cases/math_minmax_nan, math_round_negzero). Both take exactly two arguments, and so does Math.hypot.

  • toI32/toI64 from f64 saturate (NaN -> 0, toI32(5e10) -> 2147483647) like a Rust as cast, not JavaScript's modulo-2^32 ToInt32. 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.mjs supplying 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 no throw and no unwinding, and a failure a caller should handle is a Result<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 -1 fails (tests/cases/arr_bounds_panic), and the same unsigned compare guards s.charCodeAt(i) and the two ends of s.slice(a, b) (tests/cases/str_slice_panic). uncheckedGet and uncheckedSet from nish:unsafe remove 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. Int32Array is i32[] with every array operation but push and pop, which a receiver spelled with the name refuses as TypeScript does (Typed-array names have no push or pop); there is no separate buffer type and no subarray. The alias names are exactly four — Int32Array, Float32Array, Float64Array, BigInt64Array — and an unsigned array has none: a program writes u8[], and Uint8Array is not a type it can spell. That asymmetry is only a spelling. u8[], u16[], u32[] and u64[] 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 scalar u32 result travels in an i32 value type and reaches JavaScript negative above 2^31 unless the loader restores it, while an element is a byte in data that Uint32Array reads unsigned. boolean[] still has no flat view at all, because an i1 must 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= e reads x before evaluating e (tests/cases/cf_compound_assign); a[i] = v evaluates a, i, v, then checks and stores; a[i] op= v evaluates a, i, checks, loads, evaluates v, stores (tests/cases/arr_index_read_write), and when v can push to or pop from a the store goes into a as v left it, its index checked again against the length then: xs[0] += grow(xs) writes the block grow moved the elements to, and an index v shrank past panics (tests/cases/cg_sec_compound_element_order); p.f op= v reads the field before v (tests/cases/cls_compound_field); the target expression is evaluated once whichever op= it is, so a[next()] |= 1 calls next() 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 through a (CLI only); assignment never copies.

  • Method dispatch is static. x.m() calls the m declared by x'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 typed T | null.

  • Parameters are immutable and used as SSA values; locals use alloca/load/store and are promoted by mem2reg.

  • Only an exported function is an external C symbol; the rest are internal unless --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.

  1. Stack allocation. A new C(...), object literal, array literal, or new Array<T>(<non-negative integer literal>) whose value provably does not outlive its function becomes an alloca in 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 into const-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 = p included), held by a reassigned let, 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). A Result is the exception to "held by a reassigned let": an Ok/Err, or a call returning a by-value Result, assigned to a let of the same function goes where that let goes, so a let 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. A let assigned from itself (r = c ? r : Ok(0)) keeps the arena answer (tests/cases/res_let_reassign, whose 100000 calls leave Arena.used() unchanged). Stack arrays are capped at 4096 bytes of data; a later push moves 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-alloc turns this off.

  2. Automatic arena scopes. A function whose arena temporaries all die with it (a dynamic new Array<T>(n), push growth on its own array, a string concatenation or template, a number printed by console.log, a callee's returned allocation), that neither returns nor leaks an allocation, and has no callee that leaks one, calls nish_arena_mark on entry and nish_arena_release before every ret (tests/cases/mem_scope_dynamic_array, mem_scope_string_temp: 100000 calls leave Arena.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 a return, which releases the outermost scope open. A switch's break stays in the pass. It needs nothing allocated during the pass to be reachable afterwards except through a number, a boolean or an enum, 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 for initialiser, the variable of the for...of being 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, the const variable of a nested for...of over such a value, a call to a function that allocates nothing, or a choice between two of those. s = s + x and every += on a string are refused;
    • push grows only an array the pass itself declared with a fresh literal or new Array;
    • a return in the body answers a scalar or a value older than the pass, and orReturn is refused;
    • the function does not call Arena.mark itself.

    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 or new Array and then uses it only as parts.push(...), parts.join(...) and parts.length, what it pushes is reachable only through parts. join copies 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 leave Arena.used() where one call left it). Any other use of parts keeps the pushed value stored, because it could hand a part back out: an element read (mem_join_parts_readback), a for...of (mem_join_parts_forof), passing parts to a function (mem_join_parts_passed), another method on it, such as parts.pop() (mem_join_parts_method), or a parts that names another local's array (mem_join_parts_alias). Assigning or returning parts, and an array the function did not build itself, count the same way. The same holds for a string parameter the function pushes onto such a parts directly (parts.push(word), parentheses seen through): join reads it before the call returns and nothing can reach it afterwards, so the callee does not keep it, the parameter is nocapture, 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 leave Arena.used() where one pass left it). Every negative above keeps the parameter kept as well (mem_join_parts_same_pass_kept reads 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 a string passed on is not followed into its callee. So jsonField(line, ...) and replaceAll on 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 xs to its own fresh literal or new Array and uses it only as xs[i] = v, xs.push(v), xs.length, an element read that is only tested (xs[i] === null), and return xs itself, what it stores is reachable only through xs, so it goes to the caller with the array and the function lets nothing else out. Only a string, or a string | 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 leave Arena.used() where one call left it). Any other use of xs keeps the stored value stored, because it could hand an element on: storing xs into a field, passing it to a function, reading an element back and keeping it, naming xs through another local, or returning it through a choice (mem_return_array_callee). An arrow argument that reads xs as a capture is a use too, since it may read xs when 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 an xs declared outside it keeps no pass scope, and a using a = arena() block that stores into an xs declared 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, so h.f = (xs[0] = v) keeps v stored.

    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 readdirSync listing's: an element read out of it and a for...of variable 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 but length, join, indexOf and push count 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_control covers every exit edge, nested loops and a switch; mem_loop_scope_forof the for...of rules; mem_loop_scope_escape a 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; and mem_loop_scope_threads the same round trip under --threads, where the arena, and so the scope, is per thread. A for loop's condition and update run outside the bracket. Like the function scope it is invisible to a program except through Arena.used(). A program that wants the same bracket around a block of its own writes using 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, an enum or 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, this included, is a number, a boolean, an enum, a string, 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 Yet List benchmark; mem_callee_scope_tree, its Storage benchmark, where 10000 runs leave Arena.used() where one left it). A callee that stores what it allocates into this or 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. A return g(...) whose arguments are every one a scalar — a number, a boolean or an enum — is the last thing its function does, and is emitted as tail 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 debug included, where no optimiser runs at all (tests/link/tail_call_depth_debug recurses a million levels at -O0 and segfaults without the marker, and tests/cases/cf_gcd is a golden small enough to read the marker out of). In a function with an automatic scope the same proof also moves nish_arena_release ahead of the call, because a release between the call and the ret is work after the call and would leave it not last after all (tests/cases/mem_scope_tail_call pins that order, and tests/link/tail_call_depth runs a million levels of it, which segfaults without the move).

    Refused when an argument is a string, an array, an object or a Result, 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 the return (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 but debug runs (wp6-memory.md §2b).

  3. 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_mark after the arguments, then nish_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 plain string, 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 a Result, 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).

  4. Explicit control with the Arena builtins, and nish_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 host writes target datalayout and target 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, and host on 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 running opt or llc by 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 -o and --link: fix first, then compile for the target. It refuses -g, --threads, --runtime-decls and --plain the same way, for the same reason.
  • --no-strict-exports: see Linkage above (tests/cases/export_no_strict).
  • --strict-exports is 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, --wrapping and --unchecked-indexing are 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 the nish:unsafe calls that skip one check at their own site: wrappingAdd, wrappingSub and wrappingMul, or uncheckedGet and uncheckedSet (tests/nish/cli.ts).
  • --no-stack-alloc: see Memory model above.

The CPU level

  • --cpu x86-64-v3 links 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-a and every other value are a usage error (exit 2, one line), and so is the flag with --profile wasi or with a --target that is not x86-64. Without --target the host's triple is the one checked, so a host that is not x86-64 refuses it the same way; an x86-64 --target on such a host is not refused, and fails at the link as a toolchain error. scripts/build.sh --cpu x86-64-v3 is the same build, and refuses the wasm and wasi profiles.
  • 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=off keeps 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 run takes 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-capabilities adds a "cpu" key after "entry"; a baseline report has none.
  • A release binary stays baseline. A binary linked with the flag stops with SIGILL on a CPU without AVX2, so it is for programs that run on machines whose CPU is known. The nish the project releases is built without it. The constant-time check reads the runtime and the nish:crypto-ct fixtures at this level as well as at the baseline (CT-16); a level it does not read is not offered (tests/run.js, the cpu level section).

Profile-guided builds

  • --pgo-generate links 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_FILE names 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-generate and --pgo-use are the same build.
  • Each needs --link and the speed or size profile, and the host. Both flags at once, either without --link, with --profile debug or wasi, with a --target that is not the host's, or in nish run is a usage error (exit 2, one line, nothing written). The --pgo-use file must exist and begin with the indexed profile's magic bytes, which llvm-profdata merge writes: a directory, a raw .profraw (named, with the merge that fixes it) or any other file is refused the same way, and so is one llvm-profdata show cannot read. llvm-profdata missing from PATH is 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, the pgo section).

The debug arena

  • --debug-arena links 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, with cap exact, 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 become PROT_NONE and 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 writes nish: --debug-arena: stale arena reference at 0x… to stderr, and the program dies of SIGSEGV. A fault elsewhere goes to the handler that was installed before.
  • It needs a link and a native profile. Without --link and outside nish run it is a usage error (exit 2), and so is --profile wasi; scripts/build.sh refuses it with the wasm, wasm-host, wasi and napi profiles. nish run takes 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 0xDB instead 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 an N errors line; a lone error prints exactly as before (tests/cases/reject_multi_error, reject_multi_forbidden, reject_multi_decl). A let x: T = <rejected> still declares x as T so 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 performance where error would 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-performance silences 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, and npm test fails 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 warnings and an N performance warnings line. 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 --json stream 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, a parallelMapInto body that allocates per element (Data parallelism), and the retired NL9014 and NL9015, which noted the removed --unchecked-indexing and --wrapping:

    • quadratic string building — s = <something built from s> where s is a string local declared outside the loop the assignment sits in, so every pass copies the whole accumulator. The hint is a string[] and one join (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-constant n declared 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 with using a = arena() (tests/cases/perf_alloc_loop). Not reported for a new C(...), an object or array literal, or a new 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) where p was 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 a const per value and, where the assignment is the point, a block around the body that opens with using 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") — a letholding 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, a return, 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, where x is a local declared outside that loop. Each pass drops the value the pass before gave x, and nothing frees it while the loop runs: the pass cannot take a scope, because its fresh value outlives it in x, and a using a = arena() block refuses the same assignment (NL2418). So memory grows with the number of passes; 10,000,000 passes of last = \item ${i}`peaked at 392 MB where the rewrite peaks at 11 MB. The hints are aconst inside 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). An Ok(...)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 a do ... 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, as head = 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 a for loop'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 calls Arena.mark itself, 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 can return what 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-arena marks "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 calls accept or respond, 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.ts grew 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) or switch (p) on a parameter p against a constant. K is a literal, a name that is neither a parameter nor a let, 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 "what readPost leaves behind on line 102 (the string built on line 69, in readPost) piles up". Its rewrite puts the block inside the function that builds the temporary. When that function is in std/ or a dependency, the rewrite puts the block in the loop body instead.

      tests/link/nl9018_server/helper_leaky.ts builds its reply in a readPost helper that also answers, so readPost is refused a scope of its own. method_leaky.ts reaches the same helper from the loop through App.ready and App.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 in const msg = ...; panic(msg).

      A loop is bounded, and NL9018 stays silent for it, when one of these holds:

      • It is a while, do or for whose condition has an order comparison (<, <=, >, >=) as a conjunct of its top-level && chain. The condition must call nothing but the numeric conversions (toI32 and its kin), and read nothing but locals, fields (.length among them) and constants. A call to any function of the program or of std/ anywhere in the condition makes the loop unbounded.

      • It is a for...of whose body cannot extend the collection it walks: an array or a map, named by a local or a field path such as log.items. The body extends it only through the same walked expression, by one of these:

        • adding to it: push, unshift, splice, set or add on it, or a write through walked[k];
        • ++ or -- on it, or spreading it;
        • passing it to a call or a new whose 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.

      Every other loop is unbounded:

      • while (true) and for (;;);
      • 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...of whose 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...of whose 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 grows this.items while it is walked, or when the walked expression is not a local, this or 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 push grows, 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, by return, throw or a break out 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 unlabelled break ends only its own loop, so a temporary that breaks out of a for...of inside a while (poll()) still counts, while a return or a break to a label on the outer loop leaves both. The walk that proves it gives up at a switch, a try or a nested loop, so a temporary that a return inside a switch leaves 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-arena prints, then keeps only the temporaries a pass drops, and changes no byte of the IR.

    • 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 a const per value, a block that opens with using 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 as for (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 by new; or when every loop that calls it releases what it kept — a pass with a scope of its own, or a call inside a using 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-memory lists 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 with using 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 the i32 it is computed in. By default that operation panics when it runs, so the hint is to widen the operands with toI64 or to write it as a wrapping* call from nish:unsafe (tests/cases/perf_overflow_const). Reported on the innermost expression that overflows, so 100000 * 100000 + 1 warns once. Silent for a wrapping* 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 named const, 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-level const needs 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) or toF64(a * b) where the operand expression is i32. The multiplication happens in i32, 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 << 32 on an i32. 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] or s.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 a u8, u16 or u32 index, which that i32 test 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 an f64, the bound is spelled toI32(a.length) (tests/wordings/nl9007_guard_f64_mode, and NL2457's nl2457_deny_panics_index_f64_i32 and _f64_ranged). The hint names only a guard that compiles and that the proof credits, so it names none for an i64, a u64 or a float index, which no spelling compares with the length in a credited way, nor where the module declares its own toU32 (or, under f64, toI32), which the guard would call instead of the builtin; it says so instead (tests/wordings/nl9007_guard_*, and NL2457's nl2457_deny_panics_index_*). Reported on the index, once per access. Where the index is an i32, an i32-based ranged integer or a u8, u16 or u32, 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 --fix inserts if (!(i >= 0 && i < toI32(xs.length))) { panic("index out of range") }, or if (!(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, with toI32(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 at i === -1, whose index i + 1 is 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), or if (k <= 99) for a range with no lower end — and anything computed is told to be bound to an i32 local and guarded there, or, when it is a counter or a cursor written back into its own range, to be declared i32 with 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 substring bound whose clamp could not be folded off — s.substring(a, b) inside a loop where the proof above could not place a or b in [0, s.length], so that bound keeps the llvm.smin / llvm.smax pair 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, and slice has no clamp at all but panics where substring would have clamped — it was measured 1.18x over an unfolded substring on 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, so s.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 literal 0 that 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 function internal linkage, 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 on bench/sieve, where opt -O3 deletes the out-of-line copy under the default and keeps it under the flag, and nothing at all on bench/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 a declare function, which is external because C defines it and so has neither rewrite available — export declare function is 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 class or interface whose 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 a boolean in front of an f64 throws 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 an interface it names the second half of the rewrite as well, because the interface's fields are the first fields of every class that implements it 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 that implements an 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 where implements puts 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-portability reports those sites, in the shape a performance warning has, with portability where performance would 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 warnings and an N portability warnings line, in the same order as the performance report. --no-warn-performance does not silence them, and --warn-portability does not change the performance report. The standard library is not walked: its sites are not the reader's to change, and a program that uses Map never runs std/collections.ts as TypeScript at all. A difference TypeScript reports loudly (orReturn, Ok and Err, a host global, a nish: 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 by main, 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 or parallelFrom's count — directly, through a function it is passed to, or through a helper that returns it; the exact predicate is below the table counts UTF-16 code units, so the number differs wherever the text is not ASCII
    NL8002 checked slice (3.2) a slice(a) or slice(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 a substring clamp nor by the receiver's own text: an ASCII string literal, a const bound to one, a const copied from such a const, 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 — a const or a let its 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 as slice(5, 2), a pair nothing orders, a let receiver and a non-ASCII literal still warn, port_str_slice_literal_past); one warning per call, at the first such bound clamps the bounds and counts a negative one from the end, where this panics
    NL8003 a record copied in (3.3) a local record p copied into a record array ps (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 table stores 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] = v into a record array while an element reference into the same array (const r = ps[j], or r of for (const r of ps)) is still read afterwards; i and j are not compared, and a field store ps[i].x = v is not a whole-slot store puts a new object in the slot and leaves r holding the old one
    NL8005 zero-fill (3.3) new Array<T>(n) of a number or a boolean, unless n's value is zero, however it is spelled: 0x0, -0, 0.0 or a const that 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 undefined
    NL8006 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, toU16 or toU32 (q /= d becomes q = 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 (a u8 divided into an i32), whose conversion would change a value, in a module that binds the conversion's name as anything but the builtin (a const, function, parameter, loop variable, member or import named toI32, renamed imports included), where the edit would call that binding, or for i64 and u64, 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, so toI32(a / 4) + 1 skips the overflow check a / 4 + 1 skips. The edits compose: a / b / c warns twice, both edits insert toI32( 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) + - *, their op= forms, ++ and -- on u8/u16/u32; a ranged integer is left out, because every write into its range is checked keeps counting past the range. No review: a mask ((a + b) & 0xff) or >>> 0 still warns and adds an and or lshr here, and toU8 and its kin saturate under Node where the native value wraps (tests/fix/port-nofix-wrap)
    NL8008 i32 >>> (3.1) >>> or >>>= whose result is i32, unless the count is a constant k — a literal, or a const that folds to one — with k & 31 not 0: such a shift is at most 2^31 − 1, so it reads back the same both ways (-16 >>> 2 is 1073741820 in each), and x >>> 0 or a count that is not a constant is reported reads the result back unsigned. No review: (x >>> k) | 0 still warns and adds an or here, and toI32 saturates 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 i64 or u64 holds a double, which rounds past 2^53
    NL8010 retired nothing: the row was Math.min, Math.max or Math.round of an f64 or f32, when min and max dropped a NaN operand and round answered 0 for a negative number that rounds to zero. They lower to a NaN test and a sign-bit pick (llvm.minimum/llvm.maximum on wasm) and a llvm.copysign.f64 now, which answer NaN and -0 as JavaScript does, so no site diverges (tests/cases/port_num_libm is quiet). The code stays reserved and is never reused —
    NL8011 retired nothing: the row was console.log or console.error of a float printing -0, and it marks no divergence in the reading the class is defined against. runtime/nish.mjs replaces both with shims that print String(x), and String(-0) is 0, which is what the native build prints. The code stays reserved and is never reused —
    NL8012 a stubbed generic (--emit-ts only) 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) or s.lastIndexOf(t) (an offset) or s.charCodeAt(i) (a code unit) on a string — an array's .length is 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" keeps s proven). 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.log or console.error, or a template literal's hole;
    • it is the exit code: the value main returns, 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 0 and -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 in width - 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 elements parallelFrom(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, do or for condition, 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++) over s.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 over other.charCodeAt(i) alone is reported);
    • it is a data-parallel body's answer: stored in the array parallelMap, parallelMapInto or parallelFrom fills, or folded by parallelReduce (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 spawn body, 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 + k on the offset an indexOf (with or without a start) or lastIndexOf of a provably ASCII needle answers, with 0 < 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, so const 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 interface no class implements, and not T | null. The two rows tell arrays apart by name — a local, or a member chain such as this.ps — except for an element type the body aliases: when a record array is declared or assigned from anything but a literal or a new, or used other than as an index or member receiver, a for … of iterable, 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 to ps.push, put in an array literal that initialises or is assigned to a binding, or stored by ps[i] = p. It is reported at p when a field write (x.f = e, x.f op= e, x.f++, x.f--) through p, or through ps[k] for any k, runs after the copy, and the other side is read after that write: any use of ps after a write through p; any use of p after a write through ps[k], and any use of ps too when p was 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 declare p. 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_push tracks, less pop()'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 a for … of variable (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 a let p rebound between the copy and the write, across if/else arms (which are ordered by source position), at a read of ps that is only ps.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 in tests/wordings/, but NL8012, which only --emit-ts reports: its cases are tests/emit-ts/records/generic-uncalled.ts (warned) and tests/emit-ts/identity/maps.ts (a standard-library stub, quiet), checked by tests/run.js's emit-ts section, and its pin is tests/wordings/nl8012_generic_stub.

  • 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-performance does not, and nish run prints 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 warnings and an N deprecation warnings line, 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, and npm test fails the day one of them does. Nothing is deprecated today: band NL7xxx holds only the retired NL7001 (Arena.release and Arena.reset) and NL7002 (--unchecked-indexing's sites), whose constructs were removed before 1.0 rather than kept behind a warning (tests/wordings/unreachable.txt).

  • --json prints 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 a syntax error: prefix in message), nothing else on stdout and nothing on stderr, with the same exit code. severity is "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; code is 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, after message (and before a fix), 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 -o layout — is {"severity","code","message"}. Two optional keys follow message, 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, which nish --fix applies; and then review, printed after fix (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 --fix never 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-ast prints the syntax tree of every module after Phase 0 as an indented <KIND> <start> <end> tree — the node kinds of src/nodes.ts and each node's span as byte offsets, identifier and literal text appended — and writes no IR (tests/cases/dump_ast).

  • --emit-checked checks 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-retention refuses 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.

  • --compat selects 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-memory prints, 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.

  • -g emits DWARF metadata: a DICompileUnit (DW_LANG_C99) and a DIFile per 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 — a DISubprogram per function, a DILocation on every instruction (each statement's and expression's start; the function's own position for the prologue), llvm.dbg.value for parameters and llvm.dbg.declare for let/const slots. number is int, i64 long, f64 double, boolean bool, string char*, a class or interface a pointer to a DICompositeType with the checker's layout, T[] a pointer to { long len; long cap; T* data; }. A function's own position — its DISubprogram's line and scopeLine, its parameters' DILocalVariables and the DILocation the prologue carries — is where its declaration starts, which is the export or the const and never the arrow's parameter list, so the two spellings of one function describe it identically (tests/cases/dbg_arrow). A DILocation column is a 1-based byte offset into its line, as clang -g writes 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 -g the IR is byte-identical. --link -g passes -g to scripts/build.sh, which compiles runtime.c with -g and skips the strip step of every profile (tests/cases/dbg_locals; the -g block of tests/run.js checks the linked binary's line table with llvm-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 under nish/ beside them (std/pair.ts as nish/pair.ts); a dependency package's module is not written. Last comes entry.ts, which imports nish/runtime/node, calls main and exits with what it answered. Imports are rewritten to match: a nish: specifier becomes nish/runtime, the one package the output names, nish:secret included (its std/secret.ts is not written: the runtime's wipe answers 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), save nish:async, which becomes nish/runtime/async.mjs because nish:process has a spawn of its own in nish/runtime; a nish/x or 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 written type 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 is tests/emit-ts/layout/); one row that touches an otherwise untouched module is the : string on an unannotated const bound to a string literal.
  • The flag turns --warn-portability on: 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 imports nish:net or calls a nish:net function, signalFd or readSignal, 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 an x op= e the TypeScript writes as x = 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, and pts[i + 1].n += 10 is 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 (P and P | null), or element types with different zeros in new Array<T>(n) (i32 and i64) (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 a bigint there, f32, a builtin call, arithmetic whose width wraps, a string's .length or methods, a Result'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 (insertAt of nish/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 fills new Array<T>(n) with T'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 imports nish: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-checked and the --emit-header/--emit-dts/--emit-napi/ --emit-napi-async sidecars are refused beside it with exit 2, and so is -o, once the program is known to be writable. --emit-ts without 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 and entry.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: substring clamps instead, and is not a site; an array's xs.slice is not a slice site but a call reaching std/array.ts's panic (Callback methods and slice) (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), or if (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 nsw with no check (tests/cases/panics_overflow_proven); every other one is checked (tests/cases/panics_overflow). A nish:unsafe wrappingAdd, wrappingSub or wrappingMul is 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; unwrapOr and orReturn are 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; readFileSyncOrNull is the twin that answers null instead (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 | null checks 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 | null reads NULL as null and is not a site (tests/cases/panics_ffi_null); the readStruct and readCString tests 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) where b is that buffer itself, a const local 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:unsafe import its module must write is the opt-in to that word, so it is listed with "allowed": true and, like oom, 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": true and never makes a function one that may panic (tests/cases/panics_oom)

  • A call names 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, so pick(xs, i) + 1, 1 + pick(xs, i), x += pick(xs, i) and 100 / pick(xs, i) reach pick's index before their own overflow or divide, while pick(xs, i - 1) reaches its argument's overflow before 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 are process.exit(n), which is a deliberate exit, or a call into a declare 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"}, where symbol is the function's LLVM name; per site {"kind","line","column"} and then "proven" for a check, "proven","callee" for parallel-length, "callee","via" for call and "allowed": true for oom and unchecked. Lines and columns are 1-based, in the units a diagnostic uses. The wrote <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-checked writes 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 do nish 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.json where 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 are noPanic, capabilities, host, compat and netRings, each written once, and anything else is an error (NL3036) where package.json writes 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 misspelt capabilites included (caps_policy_manifest_nish_unknown_key), a noPanic that is not an array (caps_policy_manifest_no_panic_not_array), and a manifest that mentions nish or carries a \u escape 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 as JSON.parse decodes it, so "ni\u0073h" is "nish"; an escape outside ASCII decodes to a byte no name contains, so it never matches one.
  • A nish:unsafe import is the opt-in. uncheckedGet and uncheckedSet are reached only through import { … } 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, as unchecked sites with "allowed": true, and a call into a function whose only unproven sites are unchecked is not a call site at all, from inside the scope or out of it (tests/cases/deny_panics_unsafe, tests/link/no_panic_unsafe_callee). The global spelling tsc accepts 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 -, ++, -- and op= the bounds walk has not proven to fit is an overflow site, refused like an index or a divisor, with a hint to bound its operands, compute in u32/u64 (the width's unsigned type), or write the operator's drop-in nish:unsafe form: wrappingAdd(x, y), wrappingSub(x, y), wrappingMul(x, y), x = wrappingAdd(x, y) for an op=, wrappingSub(0, x) for a negation and x = wrappingAdd(x, 1) or x = wrappingSub(x, 1) for ++ and --. A proven one is accepted, and so is every wrapping* 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:unsafe import says so.
  • --deny-panics changes 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.

  • --compat selects 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 run and --fix take the flag too.

  • "compat" in the root package's "nish" field selects it without the flag: true for every built feature, or an array of feature names for exactly those ([] for the dialect with no feature). The root package is the one whose package.json is 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, where package.json writes it (compat_manifest_unknown_feature). --compat on 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.json asks 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 bare number is the double, as a JavaScript engine computes it, and every rule of --number-mode f64 applies unchanged — its diagnostics included, so a main that returns a bare number is refused with NL2140 under --compat exactly as it is under --number-mode f64. A --number-mode on the command line wins, on either side of --compat. --number-mode i32 beside the dialect is honoured and priced: one performance warning, 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-performance silences 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-checked opens 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 is compat= ``).

  • optional-chaining admits 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() or a?.b.m(x), runs to its end when every link is there and does nothing from the first one that is null or undefined, as in Node: the arguments of a call it skips are not evaluated (tests/cases/compat_optional_chain_statement, refused in the strict dialect as reject_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, strict reject_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 answers undefined and 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 call f?.() is NL1068 (compat_optional_call).

  • nullish admits a ?? whose left operand is never missing: a value whose type is not nullable, or a nullable one narrowed past null (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 answer undefined for: a literal (number, string, true, false, template, array or object), a name, this, a new, 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: one performance warning, NL9021, at the ??, naming the default to drop (tests/cases/compat_nullish_never_missing, compat_nullish_narrowed; strict reject_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 reads undefined and answers the default, where the bounds check panics, so xs[i] ?? d keeps strict's refusal in the same words, naming no feature (reject_nullish_element_never_missing).

  • string-switch admits a switch whose discriminant is a string (tests/cases/compat_string_switch, strict reject_switch_string). Each case label is a string literal, a template with no substitution, or a module constant of type string, 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, are Duplicate `case` label as 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 a default in any place, an empty case group, return from a case, break and a labelled break out of an enclosing loop, and continue of 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 no string and keeps the strict refusal, naming no feature. The switch compares the discriminant with each label in source order, one nish_str_eq call each, and jumps to the first that matches, or to default: a chain, not a tree bucketed by length, because nish_str_eq already answers on a length mismatch before it reads a byte.

  • for-of-string admits for (const c of s) over a string (tests/cases/compat_for_of_string, strict reject_arr_forof_non_array). Each pass binds c to the next code point, as Node walks a string: a character outside the Basic Multilingual Plane is one pass, not two. c is a new string holding that code point's UTF-8 bytes. break, continue and 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), though c's bytes are nish's, not Node's UTF-16. c is fresh each pass, and the walk opens no arena pass of its own: each c stays 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 of n code points holds n small strings until then.

  • optional-params admits an x?: T parameter and a default that is not a constant (tests/cases/compat_optional_params, strict reject_param_default_expression, reject_param_default_array, reject_param_default_object). An x?: T parameter of a function, an arrow or a method is T | null inside, 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 passes undefined in Node and null here, and x ?? <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). An x? whose T has no null, a bare number or a boolean, is NL2804 (compat_optional_params_value): give it a default instead. A default of a top-level function, an arrow const included, 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 an x?. --emit-ts writes 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 an x? stays refused as before (compat_optional_params_feature).

  • overloads admits 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 are Functions 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, as tsc holds 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 than tsc, 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-napi and --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 f64 for 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.js checks both over every program in tests/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 a Result assigned over another, reject_deny_retention_result_drop and reject_deny_retention_result_reassign). The warning it restates is not printed as well, and --no-warn-performance does 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-retention changes no byte of the IR: a program it accepts is the one the build compiles without it (tests/cases/deny_retention_clean). nish run and --fix accept 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 unscoped site's memory: a loop whose pass is scoped takes back what its callees leave behind. Only in main is unscoped the end of the run.
  • --emit-arena changes no byte of the IR, and it is a product, as --emit-panics is: nish run and --fix refuse 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 (in main, 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 a using a = arena() block or a scoped loop inside its body keeps nothing past the pass and is not listed. A condition or for update 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; a do...while condition'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.js does with a case's <name>.memory (tests/cases/explain_memory).
  • The program's own modules only, as --deny-retention judges 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-elision no automatic scope is taken, so every allocating loop and function is listed except the passes and blocks the program brackets itself with using 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-memory changes no byte of the IR. nish run accepts 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).