@amritk/nish 0.11.0 → 0.12.0

package/README.md

@@ -88,6 +88,7 @@ export const main = (): number => {
 nish hello.ts --link hello    # writes hello.ll, then builds hello with clang -O3 -flto
 ./hello                            # hello from Nish
 nish hello.ts -o hello.ll     # IR only
+nish run hello.ts             # build into a cache and run it: a script, still native
 ```
 
 The IR is readable as is. `examples/add.ts` compiles to:
@@ -275,6 +276,7 @@ buys is the output: no GC, no runtime, and the sizes under
 
 ```
 nish <entry.ts> [more.ts ...] [options]
+nish run [options] <file.ts> [args ...]
        nish --version | --help
   -o, --output <file.ll>     output path for a single module (default: <input>.ll)
   -o, --output <dir>/        output directory: one <dir>/<module>.ll per module
@@ -327,6 +329,22 @@ with `2`. `-g` adds a DWARF line table and variables to the IR so
 Multi-file programs: `nish examples/multi/main.ts --link build/multi && ./build/multi; echo $?`
 prints `49`.
 
+**`nish run` is the scripting shape.** `nish run tool.ts a b` compiles
+`tool.ts`, links it into a cache, and starts it with `a b` as its arguments.
+Its stdin, stdout and stderr are the program's, and its exit status is the
+program's once it starts (`128 + n` for a signal). The options before the file
+are the compiler's (`--number-mode f64`, `--profile speed`, `-g`), and
+everything after it is the program's, `--help` included. Nothing is
+interpreted: every run compiles, which takes milliseconds, and links only when
+the IR, the recipe or the runtime is new, so the first run of an edit pays for
+one `--profile debug` link (the default here, and the fast one) and every run
+after that starts the cached binary. The cache is `$XDG_CACHE_HOME/nish/run`,
+or `~/.cache/nish/run`. Each entry is one program, so `rm -rf` of it is always
+safe. `-o`, `--link`, `--target`, the `--emit-*` sidecars and
+`--profile wasi` write something a run keeps to itself, so they are usage
+errors there, and performance warnings are not printed, because stderr belongs
+to the program.
+
 Without `--link`, build the IR yourself: `clang add.ll examples/main.c runtime/runtime.c runtime/runtime_os.c -o app`
 (the `overriding the module target triple` warning is harmless: the IR is
 target-neutral unless you pass `--target`; `-Wno-override-module` silences

package/docs/AI.md

@@ -37,6 +37,7 @@ and it is the only authority.
 nish program.ts --json            # one JSON object per diagnostic, on stdout
 nish program.ts -o out.ll         # emit LLVM IR
 nish program.ts --link prog       # build a native binary (needs clang)
+nish run program.ts a b           # build into a cache, then run it with `a b`
 nish --help                       # the full flag list, stdout, exit 0
 ```
 
@@ -58,7 +59,9 @@ exclusive:
   `NL0000` a diagnostic with no rule yet.
 - **Exit codes**: `0` ok, `1` the program was rejected, `2` usage, `3` the C
   toolchain is unusable, `70` an internal compiler error — that last one is a
-  bug in `nish`, not in your program, and is worth reporting.
+  bug in `nish`, not in your program, and is worth reporting. `nish run`
+  answers the same codes until the program starts, and the program's own
+  status after that.
 - Every failure is a `--json` object, toolchain and internal errors included,
   so you never have to parse stderr to find out why a run failed.
 
@@ -675,7 +678,7 @@ export const main = (): i32 => {
 threads as the array is long enough for. `f` is a [function parameter](#function-parameters).
 Importing the module compiles the program with `--threads`; there is nothing
 else to switch on and no thread count to choose. (A plain block: a program
-importing a `nish/` module writes two `.ll` files, so this one is compiled by
+importing `nish/threads` writes two `.ll` files, so this one is compiled by
 `tests/link/par_map` and `tests/link/par_reduce` instead.)
 
 ```ts
@@ -952,6 +955,11 @@ export const main = (): i32 => {
   annotation must match **exactly**. `const` freezes the binding, not the
   contents: `xs[0] = 1` and `xs.push(1)` on a `const xs` are fine.
 - `var` is forbidden. Destructuring is not supported.
+- **Semicolons are optional**, where TypeScript would insert one: at a line
+  break, before `}` and at the end of the file. It is TypeScript's rule, so a
+  line starting with `(` or `[` continues the one before it, and `return`
+  followed by a line break returns nothing. Here, the value left on the next
+  line is an unreachable-code error rather than a silent bug.
 - `for (init; cond; update)` with every clause optional, and
   `for (const x of xs)` over an **array** only — `x` gets the element type and
   must not be annotated. The array's `length` is re-read each iteration, so a
@@ -1159,6 +1167,37 @@ for (const e of m) {
 }
 ```
 
+Asking about one key twice costs one probe when the second call writes
+through the first: `m.set(k, E)` whose `E` reads `m.get(k)` or `m.has(k)`
+once, and `if (m.has(k)) { m.set(k, E); … }`, `if (!m.has(k)) { m.set(k, E); … }`
+or `if (!s.has(x)) { s.add(x); … }` with the write first in the branch. The
+receiver and key must be a local, a parameter or a `this.<field>` path (the key
+may be a literal), spelled the same in both calls, and nothing in between may
+call anything, allocate (`new`, a literal array or object, a template, a
+string `+`) or assign. Anything else still compiles, as one probe per call.
+`nish/map` adds `getOrInsert(m, k, v)` — the value of `k`, or `v` after
+inserting it — and `reserve(m, n)`, which sizes the table for `n` entries; both
+are one module with the program and run unchanged under Node.
+
+```ts nish:ok
+import { getOrInsert, reserve } from "nish/map";
+
+export const main = (): i32 => {
+  const words = ["to", "be", "or", "not", "to", "be"];
+  const counts = new Map<string, i32>();
+  reserve(counts, words.length);
+  for (const w of words) {
+    counts.set(w, (counts.get(w) ?? 0) + 1);   // one probe per word
+  }
+  const first = new Map<string, i32>();
+  for (let i = 0; i < words.length; i++) {
+    getOrInsert(first, words[i], i);           // one probe; inserts only the first time
+  }
+  console.log(`${counts.get("to") ?? 0} ${first.get("be") ?? -1}`);   // 2 1
+  return 0;
+};
+```
+
 ## Memory
 
 There is **no garbage collector and no `free`**, and nothing about this changes

package/docs/INSTALL.md

@@ -446,6 +446,21 @@ Other build profiles: `--profile size` (smallest binary), `--profile debug`
 (no optimisation, symbols kept). Run `nish --help` for every flag, and
 see the [README](../README.md) for the language subset.
 
+To use a program as a script rather than keep the binary, run it:
+
+```bash
+nish run hello.ts
+# hello from Nish
+```
+
+`nish run [options] <file.ts> [args ...]` compiles the file, links it into
+`$XDG_CACHE_HOME/nish/run` (or `~/.cache/nish/run`) when that program has not
+been linked before, and starts it with the arguments after the file. The first
+run of a new edit pays for one link, and later runs start the cached binary.
+It needs clang only for that link. It needs `HOME` or `XDG_CACHE_HOME` set,
+and refuses the run without them rather than keep a binary in a shared
+directory.
+
 ## 4. Exit codes
 
 | Code | Meaning |
@@ -454,6 +469,7 @@ see the [README](../README.md) for the language subset.
 | 1 | the program was rejected: compile error (`file:line:col: error: ...`), missing input file, or an `-o` layout that does not fit the module count |
 | 2 | usage error: unknown flag, missing argument, no input files |
 | 3 | toolchain error: `--link` found no `clang` (`CC` overrides), or `scripts/build.sh` failed (its output is shown; the `.ll` files are still written) — or the `nish` command found no prebuilt compiler for this platform, or one that would not start. Under `--json` all of these are one `NL0002` object |
+| | `nish run` answers these codes until the program starts, and the program's own exit status (`128 + n` for a signal) after that. With neither `HOME` nor `XDG_CACHE_HOME` set it answers 3 |
 | 70 | internal compiler error: an unexpected exception. Please report it at <https://github.com/amritk/nish/issues> with the input and command line; `NISH_DEBUG=1` prints the stack trace |
 
 ## Troubleshooting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/nish",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Nish: an ahead-of-time compiler from a static subset of TypeScript to LLVM IR",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,7 @@
     "!scripts/arrow-verify.mjs",
     "!scripts/arrowify.mjs",
     "!scripts/fetch-seed.sh",
+    "!scripts/check-filenames.mjs",
     "!scripts/check-pr-body.mjs",
     "!scripts/check-pr-body.test.mjs",
     "!scripts/changelog-gen.test.mjs",
@@ -45,7 +46,7 @@
     "test:nish": "build/nish tests/nish/run.ts -o build/nish-runner.ir/ --link build/nish-runner && build/nish-runner",
     "test:cli": "build/nish tests/nish/cli.ts -o build/nish-cli.ir/ --link build/nish-cli && build/nish-cli",
     "test:node": "node tests/differential/unmodified.js",
-    "lint": "biome check --formatter-enabled=false .",
+    "lint": "node scripts/check-filenames.mjs --advisory && biome check --formatter-enabled=false .",
     "format": "biome format --write .",
     "prepublishOnly": "npm run check && npm test",
     "changelog": "node scripts/changelog-gen.mjs"
@@ -74,10 +75,10 @@
     "nish"
   ],
   "optionalDependencies": {
-    "@amritk/nish-x86_64-linux": "0.11.0",
-    "@amritk/nish-aarch64-linux": "0.11.0",
-    "@amritk/nish-aarch64-darwin": "0.11.0",
-    "@amritk/nish-x86_64-darwin": "0.11.0"
+    "@amritk/nish-x86_64-linux": "0.12.0",
+    "@amritk/nish-aarch64-linux": "0.12.0",
+    "@amritk/nish-aarch64-darwin": "0.12.0",
+    "@amritk/nish-x86_64-darwin": "0.12.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.12",

package/runtime/nish.d.ts

@@ -34,6 +34,8 @@
  * only as the iterable of a `for...of`, and `get`'s `V | undefined` only as a
  * `const`'s initialiser, the left of `??` or an operand of `=== undefined`,
  * none of which `tsc` can know (docs/LANGUAGE.md -> `Map` and `Set`).
+ * `nish/map`'s `reserve` and `getOrInsert` are not declared here either: they
+ * are ordinary source, `std/map.ts`, which `tsconfig.json` maps `nish/*` to.
  */
 
 // ---- Numeric widths (docs/LANGUAGE.md -> Types) ------------------------------

package/runtime/nish.mjs

@@ -54,6 +54,7 @@
  * harness already uses, so the two cannot drift apart: a semantic fixed there
  * is fixed here in the same commit.
  */
+import { registerHooks } from "node:module";
 import * as shim from "./shim.mjs";
 
 /** Install `value` as a global unless the program declared its own. */
@@ -141,3 +142,15 @@ provide("Arena", {
   reset: shim.arenaReset,
   used: shim.arenaUsed,
 });
+
+// The standard library. A program imports it as `nish/<module>`, which the
+// compiler resolves to `std/<module>.ts` beside itself; this does the same for
+// Node, relative to this file rather than to the program, so the same
+// specifier works from any directory. Only the `nish/` package is answered
+// here, and every other specifier goes to Node as it was written.
+registerHooks({
+  resolve: (specifier, context, next) =>
+    specifier.startsWith("nish/")
+      ? next(new URL(`../std/${specifier.slice("nish/".length)}.ts`, import.meta.url).href, context)
+      : next(specifier, context),
+});

package/scripts/ci-profile.mjs

@@ -67,10 +67,11 @@ const takeLine = (line) => {
 
 const onData = (data) => {
   buffered += data;
-  let i;
-  while ((i = buffered.indexOf("\n")) >= 0) {
+  let i = buffered.indexOf("\n");
+  while (i >= 0) {
     takeLine(buffered.slice(0, i));
     buffered = buffered.slice(i + 1);
+    i = buffered.indexOf("\n");
   }
 };
 

package/std/README.md

@@ -1,8 +1,8 @@
 # `std/` — the standard library
 
 Nish modules written in Nish, for Nish programs to import. There is no magic
-here and — with two exceptions, `threads.ts` and `collections.ts` — nothing
-the compiler knows about: a module in this directory is an ordinary Nish source file, compiled as part of
+here and — with three exceptions, `threads.ts`, `collections.ts` and `map.ts` —
+nothing the compiler knows about: a module in this directory is an ordinary Nish source file, compiled as part of
 whatever program imports it, and subject to the same rules as `examples/` or
 `self/` ([`docs/LANGUAGE.md`](../docs/LANGUAGE.md) is the style guide).
 
@@ -12,7 +12,8 @@ whatever program imports it, and subject to the same rules as `examples/` or
 | [`text.ts`](./text.ts) | the string operations a program would otherwise write inline: `splitLines`, `splitWhitespace`, `trim` and its halves, `contains`, `replaceAll`, and `firstDifference` over two arrays of lines |
 | [`json.ts`](./json.ts) | `jsonField(object, name)`: the value of one field of one flat JSON object, which is the shape the compiler's own `--json` diagnostics have. A reader and not a parser — it answers text, answers `null` for a field that is not there, and does not validate |
 | [`pair.ts`](./pair.ts) | `Pair<A, B>`: an interface with `first` and `second`, for a function that answers two values from one call. A type and nothing else — the caller writes an object literal at the return — and for returning two values rather than storing them side by side |
-| [`collections.ts`](./collections.ts) | the global `Map<K, V>` and `Set<T>`: insertion-ordered tables whose buckets carry a hash fingerprint beside the entry index and whose entries keep their full hash, so every `get`, `set`, `add`, `has` and `delete` is one probe. `get` is not a method here: its `V | undefined` never crosses a call, so the compiler lowers it to `probe` and, where the key was found, `valueAt`. Nor are `keys()` and `values()`: an iterator is not a value, so a `for...of` over one is lowered to `walkOpen`, `walkNext`, `keyAt` or `valueAt`, and `walkClose`, and a count of live walks defers compaction until no loop is walking the table. A program never imports it: naming `Map` or `Set` loads it, and the compiler emits what a module uses of it into that module ([`docs/wp32-map.md`](../docs/wp32-map.md), [`docs/LANGUAGE.md`](../docs/LANGUAGE.md#map-and-set)). Its `hashKey` and `sameKey` are lowered by the compiler per key type |
+| [`collections.ts`](./collections.ts) | the global `Map<K, V>` and `Set<T>`: insertion-ordered tables whose buckets carry a hash fingerprint beside the entry index and whose entries keep their full hash, so every `get`, `set`, `add`, `has` and `delete` is one probe. `get` is not a method here: its `V | undefined` never crosses a call, so the compiler lowers it to `probe` and, where the key was found, `valueAt`. Nor are `keys()` and `values()`: an iterator is not a value, so a `for...of` over one is lowered to `walkOpen`, `walkNext`, `keyAt` or `valueAt`, and `walkClose`, and a count of live walks defers compaction until no loop is walking the table. A program never imports it: naming `Map` or `Set` loads it, and the compiler emits what a module uses of it into that module ([`docs/wp32-map.md`](../docs/wp32-map.md), [`docs/LANGUAGE.md`](../docs/LANGUAGE.md#map-and-set)). Its `hashKey`, `sameKey` and `storedKey` are lowered by the compiler per key type |
+| [`map.ts`](./map.ts) | `reserve(m, n)` and `getOrInsert(m, k, v)` for the global `Map`. Their bodies are the meaning, and what runs under Node: `reserve` does nothing, and `getOrInsert` is a `get`, and a `set` of `v` when the key was missing. Natively the compiler lowers every call in place — `reserve` to the table's `reserveSlots`, which grows the buckets once so that `n` entries fit without a rebuild, and `getOrInsert` to one `probe` and a `valueAt` or an `insertAt` through its answer — so, like `collections.ts`, it writes no `.ll` of its own ([`docs/wp32-map.md`](../docs/wp32-map.md) §9.2, [`docs/LANGUAGE.md`](../docs/LANGUAGE.md#map-and-set)) |
 | [`threads.ts`](./threads.ts) | `parallelMapInto(src, dst, f)` and `parallelReduce(src, f, identity)`: a function over every element of an array, on as many threads as the length is worth. Its bodies are the sequential meaning, which is what runs under Node; the compiler recognises the two templates by module and name, lowers the one loop in each onto `nish_parallel_range`, holds the function to the rules that make that safe, and compiles an importing program with `--threads` ([`docs/LANGUAGE.md`](../docs/LANGUAGE.md#data-parallelism-nishthreads)). `tests/link/par_*` are its programs |
 
 ## How a program imports it
@@ -64,12 +65,16 @@ reasons that are only true of it:
   package and is versioned with it, so "the `std/` beside this binary" is not a
   guess a resolver makes — it is the only `std/` that can be correct for the
   compiler reading it. No version can be skewed against it.
-- It **is** what Node resolves. `package.json` declares
-  `"./*": "./std/*.ts"` in `exports`, so `nish/text` is a package
-  self-reference: `import.meta.resolve("nish/text")` answers `std/text.ts`, and
-  `tsc` under `moduleResolution: node16` resolves it to the same file, which is
-  what gives an editor go-to-definition into the real source. The compiler
-  short-circuits to that answer rather than walking `node_modules` to reach it.
+- It **is** what Node and `tsc` resolve. The package is published as
+  `@amritk/nish`, so a bare `nish/text` is not a package self-reference on its
+  own; `runtime/nish.mjs`, the prelude a program runs under Node with
+  (`node --experimental-strip-types --import ./runtime/nish.mjs`), resolves
+  `nish/<module>` to `std/<module>.ts` beside itself, and the repository's
+  `tsconfig.json` maps `nish/*` to `./std/*`, which is what gives `tsc` and an
+  editor go-to-definition into the real source. `package.json` still declares
+  `"./*": "./std/*.ts"` in `exports`, so `@amritk/nish/text` reaches the same
+  file. The compiler short-circuits to that answer rather than walking
+  `node_modules` to reach it.
 
 So this is WP21's first slice rather than a detour around it: the spelling is
 the one WP21 specifies, and what is still missing is resolution for specifiers

package/std/collections.ts

@@ -394,7 +394,7 @@ export class Map<K, V> {
       this.rebuild();
       bucket = -1;
     }
-    this.entryKeys.push(key);
+    this.entryKeys.push(storedKey(key));
     this.entryValues.push(value);
     this.entryHashes.push(h);
     this.live = this.live + 1;
@@ -427,6 +427,33 @@ export class Map<K, V> {
     this.mask = toI32(slots.length) - 1;
     refile(slots, this.entryHashes);
   }
+
+  /**
+   * `reserve(m, n)` from `nish/map` (docs/wp32-map.md §9.2): grow the bucket
+   * table until `n` entries, dead ones included, fit under the load bound, so
+   * that the inserts up to `n` rebuild nothing. It only ever grows the buckets
+   * and re-files them from the stored hashes, so no entry moves and it is as
+   * safe under a walk as the doubling a walk already allows (§6.2). A count
+   * that is not positive, or not a number, does nothing, as `reserve` does
+   * under Node; one past the entry cap is the cap.
+   */
+  reserveSlots(n: number): void {
+    if (!(n > 0)) {
+      return;
+    }
+    const want: i32 = n >= 16777215 ? INDEX_CAP : toI32(n);
+    const have = toI32(this.slots.length);
+    let size = have;
+    while (want * 4 > size * 3) {
+      size = size * 2;
+    }
+    if (size > have) {
+      const slots = new Array<u32>(size);
+      this.slots = slots;
+      this.mask = size - 1;
+      refile(slots, this.entryHashes);
+    }
+  }
 }
 
 /** A set of keys in insertion order: `Map`'s table with no values, and the same probe. */
@@ -519,7 +546,7 @@ export class Set<T> {
       this.rebuild();
       bucket = -1;
     }
-    this.entryKeys.push(key);
+    this.entryKeys.push(storedKey(key));
     this.entryHashes.push(h);
     this.live = this.live + 1;
     this.size = this.size + 1;
@@ -546,3 +573,13 @@ export class Set<T> {
     refile(slots, this.entryHashes);
   }
 }
+
+/**
+ * The key as an entry stores it: a float's -0 becomes +0, as ECMA-262's
+ * `Map.prototype.set` and `Set.prototype.add` store it, so a walk over the
+ * keys yields +0 whichever zero was inserted. Lowered in place, like `hashKey`
+ * and `sameKey`: `fadd` of +0 for a float, and nothing at all for every other
+ * key. It sits last in the file so that adding it moved no line a `-g` build
+ * of an earlier function records.
+ */
+const storedKey = <K>(key: K): K => key;

package/std/map.ts

@@ -0,0 +1,37 @@
+/**
+ * `nish/map` — two operations on the global `Map` that JavaScript's does not
+ * have, written so that a program using them still runs unmodified under Node
+ * (docs/wp32-map.md §9.2).
+ *
+ * The bodies below are the meaning, and they are what runs under Node:
+ * `reserve` does nothing, and `getOrInsert` is a `get`, and a `set` when the
+ * key was missing. Natively neither body is ever called. The compiler lowers
+ * every call in place, as it lowers `hashKey` and `sameKey`: `reserve` is the
+ * table's `reserveSlots`, which grows the buckets so that `n` entries fit
+ * without a rebuild, and `getOrInsert` is one `probe` of the key, then the
+ * value it found or an insert through the empty bucket the probe stopped at,
+ * with the hash it already computed. So this module writes no `.ll` of its
+ * own, and a one-file program that imports it is still one module.
+ */
+
+/**
+ * Make room in `m` for `n` entries in all, so that inserting up to `n` never
+ * grows the table. Only the speed of a program depends on it: natively it
+ * presizes the bucket table, and under Node, which has no such call, it does
+ * nothing. A count that is not positive does nothing either way.
+ */
+export const reserve = <K, V>(m: Map<K, V>, n: number): void => {};
+
+/**
+ * The value of `key` in `m`; or, when `key` is missing, `value`, after
+ * setting `key` to it. One hash and one probe natively, whichever it was.
+ * `value` is evaluated either way, as every argument is.
+ */
+export const getOrInsert = <K, V>(m: Map<K, V>, key: K, value: V): V => {
+  const found = m.get(key);
+  if (found !== undefined) {
+    return found;
+  }
+  m.set(key, value);
+  return value;
+};