@amritk/nish-x86_64-linux 0.20.0 → 0.22.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/nish-x86_64-linux",
-  "version": "0.20.0",
+  "version": "0.22.1",
   "description": "The nish native compiler for Linux on x86_64",
   "license": "MIT",
   "os": [
@@ -17,6 +17,7 @@
     "runtime",
     "scripts",
     "std",
+    "docs",
     "LICENSE",
     "INSTALL.md"
   ],

package/runtime/browser.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `nish/runtime/browser`: importing it installs the browser host on the core
+ * in `nish/runtime` (docs/guide/using-nish/to-typescript.md).
+ */
+
+export { NishExit } from "./core/host.js";

package/runtime/browser.mjs

@@ -0,0 +1,77 @@
+/**
+ * The browser host (WP33 R3): importing this installs, on the core in
+ * `runtime/core.mjs`, the answers a web page can give. It names no `node:`
+ * module and reads only web globals (`console`, `performance`,
+ * `queueMicrotask`), so it loads in a page, a worker or any engine that has
+ * those.
+ *
+ *   - Output goes to the console a line at a time: what `write` leaves without
+ *     a newline waits for the next one, for `exit`, or for the program to yield.
+ *   - `exit(code)` throws a `NishExit` carrying the code, since a page cannot
+ *     end itself; the caller that started the program catches it, and does
+ *     not call the module again (docs/security/runtime-browser.md, BROWSER-2).
+ *   - `monotonicNanos` reads `performance.now()`, `getenv` answers `null`,
+ *     `isTerminal` answers `false` and `terminalSize` `[-25, 0]`, and `argv()`
+ *     is the program alone.
+ *   - Every file-system, process and machine call panics, naming itself and
+ *     the browser.
+ */
+import { installHost, NishExit, panic } from "./core/host.mjs";
+
+export { NishExit };
+
+/**
+ * One console stream, buffered to the next newline. The `"%s"` keeps a `%d`
+ * or `%o` in the program's text from being read as a format directive.
+ */
+function lineStream(print) {
+  let pending = "";
+  let scheduled = false;
+  const flush = () => {
+    scheduled = false;
+    if (pending !== "") print("%s", pending);
+    pending = "";
+  };
+  return {
+    write(s) {
+      // Only the text up to the last newline is split, so a run of writes
+      // with no newline costs their length once, not once per write.
+      const text = String(s);
+      const last = text.lastIndexOf("\n");
+      if (last < 0) {
+        pending += text;
+      } else {
+        const lines = (pending + text.slice(0, last)).split("\n");
+        pending = text.slice(last + 1);
+        for (const line of lines) print("%s", line);
+      }
+      if (pending !== "" && !scheduled) {
+        scheduled = true;
+        queueMicrotask(flush);
+      }
+    },
+    flush,
+  };
+}
+
+const out = lineStream((...a) => console.log(...a));
+const err = lineStream((...a) => console.error(...a));
+
+installHost({
+  writeOut: out.write,
+  writeErr: err.write,
+  exit(code) {
+    out.flush();
+    err.flush();
+    throw new NishExit(code);
+  },
+  argv: () => ["main"],
+  call(name) {
+    if (name === "getenv") return null;
+    if (name === "monotonicNanos") return BigInt(Math.round(performance.now() * 1e6));
+    // A page has no terminal, which `nish:term` answers as a pipe does.
+    if (name === "isTerminal") return false;
+    if (name === "terminalSize") return [-25, 0];
+    return panic(`${name} is not available in a browser`);
+  },
+});

package/runtime/core/arrays.d.ts

@@ -0,0 +1,36 @@
+/** The array half of the core: bounds-checked access, and the arena stubs. */
+import type { i32, i64 } from "./numbers.js";
+export declare function idx<T>(a: readonly T[], i: number | bigint): T;
+export declare function pop<T>(a: T[]): T;
+export declare function setIdx<T>(a: T[], i: number | bigint, v: T): T;
+export declare function updIdx<T>(a: T[], i: number | bigint, f: (old: T) => T): T;
+export declare function uncheckedGet<T extends number | bigint>(xs: readonly T[], i: i32): T;
+export declare function uncheckedSet<T extends number | bigint>(xs: T[], i: i32, v: T): void;
+export declare function copyIn<T>(v: T): T;
+export declare function storeIdx<T>(a: T[], i: number | bigint, v: T): T;
+export declare function arraySet<T>(dst: T[], src: readonly T[], offset?: number): void;
+/** `dst.set(src, offset)` as `--emit-ts` writes it: a 64-bit offset is a bigint, checked exactly. */
+export declare function arraySetAt<T>(dst: T[], src: readonly T[], offset?: number | bigint): void;
+/** `new Array<T>(n)`: `--emit-ts` writes `T` out, so the zero it fills with is not what `T` is read from. */
+export declare function newArray<T>(n: number | bigint, zero: unknown): T[];
+export declare function arenaUsed(): i64;
+export declare function arenaMark(): i64;
+export declare function arenaRelease(m?: unknown): void;
+export declare function arenaReset(): void;
+/**
+ * The protocol `using` reads, declared here as `nish.d.ts` does, so `using a =
+ * arena()` type-checks with no `"esnext.disposable"` in a program's `lib`.
+ */
+declare global {
+  interface SymbolConstructor {
+    readonly dispose: unique symbol;
+  }
+}
+
+/** What `arena()` answers: its `Symbol.dispose` does nothing. */
+export interface ArenaHandle {
+  [Symbol.dispose](): void;
+}
+
+/** `using a = arena()`: the arena is the collector's, so leaving it frees nothing. */
+export declare function arena(): ArenaHandle;

package/runtime/core/arrays.mjs

@@ -0,0 +1,153 @@
+import { panicIndex, panicSlice, toIndex } from "./checks.mjs";
+
+// The native check compares the index as an unsigned 64-bit number, so a
+// negative one fails, and prints, as that number: `-1` is 18446744073709551615.
+// A NaN or infinite `number` has no such number and prints as it is.
+function outOfRange(i, len) {
+  const n = toIndex(i);
+  if (typeof i !== "bigint" && !Number.isFinite(n)) panicIndex(n, len);
+  const k = typeof i === "bigint" ? i : BigInt(n);
+  panicIndex(k < 0n ? BigInt.asUintN(64, k) : k, len);
+}
+
+/** `a[i]` read with the WP4 bounds check (negative indices fail like the unsigned compare does). */
+export function idx(a, i) {
+  const k = toIndex(i);
+  if (!(k >= 0 && k < a.length)) outOfRange(i, a.length);
+  return a[k];
+}
+
+/** `a.pop()`: the last element, or the bounds panic — Nish has no `undefined` to return. */
+export function pop(a) {
+  if (a.length === 0) panicIndex(0, 0);
+  return a.pop();
+}
+
+/** `a[i] = v`: evaluates `a`, `i`, `v`, then checks and stores; yields `v`. */
+export function setIdx(a, i, v) {
+  const k = toIndex(i);
+  if (!(k >= 0 && k < a.length)) outOfRange(i, a.length);
+  a[k] = v;
+  return v;
+}
+
+/**
+ * `a[i] op= v`: evaluates `a`, `i`, checks, loads, then `f(old)` computes the
+ * new element, and checks again before the store, as `f` can shrink `a`.
+ */
+export function updIdx(a, i, f) {
+  const k = toIndex(i);
+  if (!(k >= 0 && k < a.length)) outOfRange(i, a.length);
+  const v = f(a[k]);
+  if (!(k < a.length)) outOfRange(i, a.length);
+  a[k] = v;
+  return v;
+}
+
+/** `nish:unsafe`'s `uncheckedGet(a, i)`: the element with no bounds check, as the native load is. */
+export function uncheckedGet(a, i) {
+  return a[i];
+}
+
+/** `nish:unsafe`'s `uncheckedSet(a, i, v)`: the store with no bounds check. */
+export function uncheckedSet(a, i, v) {
+  a[i] = v;
+}
+
+// A record an array holds inline is an object literal here, and nothing else
+// is a plain object: a class instance has its class's prototype, and an array
+// has Array's.
+function isRecord(v) {
+  return v !== null && typeof v === "object" && Object.getPrototypeOf(v) === Object.prototype;
+}
+
+/** A value put into an array slot from a generic body: a copy when it is a record, as a slot holds it inline. */
+export function copyIn(v) {
+  return isRecord(v) ? { ...v } : v;
+}
+
+/**
+ * `a[i] = v` from a generic body: as `setIdx`, but a record is written field
+ * by field into the record already in the slot, as an inline element is.
+ */
+export function storeIdx(a, i, v) {
+  const k = toIndex(i);
+  if (!(k >= 0 && k < a.length)) outOfRange(i, a.length);
+  const old = a[k];
+  if (isRecord(old) && isRecord(v)) Object.assign(old, v);
+  else a[k] = v;
+  return v;
+}
+
+/**
+ * `dst.set(src, offset)` as `nish --emit-ts` writes it: an `i64` or `u64`
+ * offset, a bigint here, is compared as one, so a value past 2^53 fails with
+ * the native panic rather than being rounded into range, and one in range is
+ * the number `arraySet` takes. `runtime/nish.mjs` keeps `arraySet`, whose
+ * bigint offset throws as `docs/LANGUAGE.md` says.
+ */
+export function arraySetAt(dst, src, offset) {
+  if (typeof offset === "bigint") {
+    const end = offset + BigInt(src.length);
+    if (offset < 0n || end > BigInt(dst.length)) panicSlice(offset, end, dst.length);
+    offset = Number(offset);
+  }
+  arraySet(dst, src, offset);
+}
+
+/**
+ * `dst.set(src, offset)` (WP34 N2): `TypedArray.prototype.set`'s copy on the
+ * plain array a `u8[]` is here. The source is copied first, so a self-copy or
+ * an overlapping one reads what was there before, as `memmove` does natively;
+ * a range past the end fails with the native panic and its words, where a
+ * typed array would throw a `RangeError` for the same offsets.
+ */
+export function arraySet(dst, src, offset) {
+  // `ToIntegerOrInfinity`: NaN is 0, as `llvm.fptosi.sat` makes it natively.
+  // `Math.trunc` rather than `toIndex`, which converts a bigint: an `i64` or
+  // `u64` offset is a bigint here, and it throws the `TypeError` the typed
+  // array and `Array.prototype.fill` throw for one, instead of being rounded
+  // to the nearest double past 2^53 (docs/RUN_UNDER_NODE.md).
+  const at = offset === undefined ? 0 : Math.trunc(offset) || 0;
+  const end = at + src.length;
+  if (!(at >= 0 && end <= dst.length)) panicSlice(...saturatedRange(at, src.length), dst.length);
+  // Two plain arrays overlap only when they are one array, which is the one
+  // case that must read the source before writing it.
+  const from = src === dst ? src.slice() : src;
+  for (let i = 0; i < from.length; i++) dst[at + i] = from[i];
+}
+
+/**
+ * `[at, at + n)` as the native panic spells it: the offset saturated into an
+ * `i64`, as `llvm.fptosi.sat` leaves it, and the end wrapped, so `1e300` is
+ * `9223372036854775807` and its end `-9223372036854775808`.
+ */
+function saturatedRange(at, n) {
+  if (Number.isSafeInteger(at + n)) return [at, at + n];
+  const max = 2n ** 63n - 1n;
+  const start = at === Infinity || at >= 2 ** 63 ? max : at <= -(2 ** 63) ? -max - 1n : BigInt(at);
+  return [start, BigInt.asIntN(64, start + BigInt(n))];
+}
+
+/** `new Array<T>(n)`: `n` zero-filled elements (`0`, `0n`, or `false`). */
+export function newArray(n, zero) {
+  return new Array(toIndex(n)).fill(zero);
+}
+
+// Arena introspection has no JS counterpart: the stubs keep programs that only
+// compare `Arena.used()` before/after (a "stayed flat" check) in agreement, while
+// programs that print raw byte counts are listed as known differences.
+//
+// `nish --threads` makes the native arena thread-local (WP20 T0) and nothing
+// here moves with it: a rewritten program runs on the one thread Node gives it,
+// so "the arena of the calling thread" and "the arena" are the same object, and
+// these stubs answer for both. If T1 ever lands a spawn the rewrite can reach,
+// that is when this file grows a second arena to keep count of.
+export function arenaUsed() { return 0n; }
+export function arenaMark() { return 0n; }
+export function arenaRelease() {}
+export function arenaReset() {}
+/** `using a = arena()`: a disposable whose disposal does nothing, because there is no arena to release. */
+export function arena() {
+  return { [Symbol.dispose]() {} };
+}

package/runtime/core/checks.mjs

@@ -0,0 +1,20 @@
+/**
+ * The checks the strings and arrays share: an index as the compiler converts
+ * it, and the two bounds panics with their native words. Internal to the core:
+ * `runtime/core.mjs` does not re-export them.
+ */
+import { panic } from "./host.mjs";
+
+/** Index conversion as in the compiler: `sext` from i32, `fptosi` (truncation) from f64. */
+export function toIndex(i) {
+  return typeof i === "bigint" ? Number(i) : Math.trunc(i);
+}
+
+export function panicIndex(i, len) {
+  panic(`index out of range: ${i} >= ${len}`);
+}
+
+/** `nish_panic_slice`: the failed range check of `s.slice(start, end)`; the offsets print signed. */
+export function panicSlice(start, end, len) {
+  panic(`slice out of range: [${start}, ${end}) of length ${len}`);
+}

package/runtime/core/host.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The host the core runs on, and every builtin that asks it. Import
+ * `nish/runtime/node` or `nish/runtime/browser` to install one; until then each
+ * of these throws a `NishNoHost`.
+ */
+import type { f64, i32, i64, u8 } from "./numbers.js";
+
+/** What an adapter installs: `exit` never returns, and `call` answers the builtin `name`. */
+export interface Host {
+  writeOut(s: string): void;
+  writeErr(s: string): void;
+  exit(code: number): never;
+  argv(): string[];
+  call(name: string, args: unknown[]): unknown;
+}
+
+/** What every member of the default host throws: no adapter has been imported. */
+export declare class NishNoHost extends Error {
+  constructor(name: string);
+  readonly requested: string;
+}
+
+/**
+ * What the browser host's `exit(code)`, and every panic there, throws: a page
+ * cannot end itself. Tell it apart with `instanceof`, not by its `name`.
+ */
+export declare class NishExit extends Error {
+  /** The 8-bit status a native exit would leave: `code & 0xff`. */
+  readonly code: number;
+  constructor(code: number);
+}
+
+export declare function installHost(next: Host): void;
+export declare function log(x: unknown): void;
+export declare function error(x: unknown): void;
+export declare function write(s: string): void;
+export declare function writeError(s: string): void;
+export declare function panic(message: string): never;
+export declare function exit(code: i32): never;
+export declare function argv(): string[];
+export declare function readFileSync(path: string): string;
+export declare function readFileSyncOrNull(path: string): string | null;
+export declare function readFileBytesSync(path: string): u8[] | null;
+export declare function writeFileSync(path: string, data: string): void;
+export declare function appendFileSync(path: string, data: string): void;
+export declare function mkdirSync(path: string): boolean;
+export declare function isDirectorySync(path: string): boolean;
+export declare function readdirSync(path: string): string[] | null;
+export declare function realpathSync(path: string): string | null;
+export declare function platform(): string;
+export declare function arch(): string;
+export declare function getenv(name: string): string | null;
+export declare function spawnSync(argv: string[]): number;
+export declare function spawnSyncTo(argv: string[], stdoutPath: string, stderrPath: string): number;
+export declare function kill(pid: i32, sig: i32): i32;
+export declare function availableParallelism(): i32;
+export declare function totalMemory(): i64;
+export declare function monotonicNanos(): i64;
+export declare function statMtimeSync(path: string): f64;
+export declare function lstatOwnerModeSync(path: string): i64;
+export declare function geteuid(): i64;
+export declare function isExecutableSync(path: string): boolean;
+export declare function isTerminal(fd: i32): boolean;
+export declare function terminalSize(): i32[];
+/** `crypto.getRandomValues(bytes)` for a `u8[]`; a typed array goes straight through. */
+export declare function getRandomValues<T extends u8[] | Uint8Array>(bytes: T): T;
+/** These four have no synchronous reading: each throws, naming itself, and is typed as `runtime/nish.d.ts` types it. */
+export declare function spawn(argv: string[]): i32;
+export declare function waitPid(pid: i32, flags: i32): i32[];
+export declare function signalFd(): i32;
+export declare function readSignal(fd: i32): i32;
+/** What each `nish:net` function is under the core: a throw naming `name`. */
+export declare function noNetReading(name: string): never;
+/** What `readStdin`, `waitStdin`, `setRawMode` and `setTerminalRestore` are under the core: a throw naming `name`. */
+export declare function noTermReading(name: string): never;
+/** `nish:term`'s four that have no reading under Node: each throws, naming itself. */
+export declare function readStdin(buf: u8[], off: i32, len: i32): i32;
+export declare function waitStdin(timeoutMs: i32): boolean;
+export declare function setRawMode(on: boolean): i32;
+export declare function setTerminalRestore(bytes: string): i32;