@amritk/nish 0.10.0

package/std/README.md

@@ -0,0 +1,185 @@
+# `std/` — the standard library
+
+Nish modules written in Nish, for Nish programs to import. There is no magic
+here and 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).
+
+| Module | What it is |
+| --- | --- |
+| [`testing.ts`](./testing.ts) | a test runner: a `Suite` a program drives with straight-line assertions, printing the `PASS` / `FAIL` / `SKIP` lines the repository's own harness prints, and answering the exit code |
+| [`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 |
+
+## How a program imports it
+
+By its package specifier:
+
+```ts
+import { Suite } from "nish/testing";
+```
+
+`nish/<module>` resolves to `<module>.ts` in this directory, found beside the
+compiler that is running — not relative to the importing file, so the same
+specifier works at any depth and from outside this repository.
+
+**Source is the distribution format** ([`docs/wp21-packages.md`](../docs/wp21-packages.md)
+§2), so an import of a `std/` module is not a link against a built library: the
+module is compiled with the program that imports it, and the whole-program
+attribute pass sees through it exactly as it sees through the program's own
+functions. A `std/` function is inlined, specialised or dropped on the same
+terms as a local one — and a module you import but never call is dropped
+whole. Measured at the `speed` and `size` profiles, both of which link with
+`-flto -Wl,--gc-sections`: a program importing three `std/text` functions and
+calling none is **byte-identical** to the same program without the import.
+(`debug` keeps them, which is what `debug` is for.)
+
+A `std/` module is its own package (`nish`), so its symbols are scoped and a
+program may declare a function one of these modules also exports
+(`tests/link/std_package_scope`, `docs/wp21-packages.md` §5a). The package is
+decided by the `nish/` specifier rather than by the directory the file is found
+in — read off the path it would be `nish` from `node_modules/nish/std/` and the
+root package from a checkout, and the same program would compile against an
+installed compiler and be refused by a checkout of it.
+
+A relative specifier still works and means the same thing —
+`import { Suite } from "../std/testing"` — but it hard-codes the depth of the
+importing file and only reaches an installed library by the path the install
+put it at, so `nish/` is the form to write.
+
+### Why this is not the second module system this file used to warn about
+
+An earlier version of this section said a bare specifier was "deliberately not
+faked", because a resolver that special-cased this directory would be a second
+module system and the one WP21 is bringing has to agree with Node's. That
+reasoning still holds for third-party packages, which are still refused
+(`docs/wp21-packages.md` §5b). It does not hold for *this* package, for two
+reasons that are only true of it:
+
+- There is exactly one right answer. `std/` ships inside the compiler's own
+  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.
+
+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
+that are *not* this package.
+
+## Writing a module here
+
+- **Spell the widths — and then convert what the builtins hand you.** `i32`,
+  `i64`, `f64`, never `number`, so the module means the same thing under
+  `--number-mode f64` as it does by default (`examples/arrays.ts` says that half
+  for the same reason). It is necessary and **not sufficient**: `s.length`,
+  `a.length` and `s.charCodeAt(i)` answer `number`, which *is* `f64` in that
+  mode, so a module that declares every width of its own and still writes
+  `let end: i32 = text.length` or `while (i < text.length)` does not compile
+  there at all. Read each of those through `toI32` —
+  `const length: i32 = toI32(text.length)`, once per function rather than once
+  per iteration — and the module means one program in both modes. The default
+  mode pays nothing for it, because `toI32` on an `i32` is identity.
+  `tests/link/std_text_f64` is what keeps this from being prose;
+  [`docs/wp26-stdlib.md`](../docs/wp26-stdlib.md) §4 is the reasoning.
+- **Name the private helpers as though they were exported.** A function name is
+  unique across the whole program whether or not it is exported, because the
+  whole-program attribute analysis is keyed by symbol name — and a `std/` module
+  is compiled *into* the program that imports it, so its private helpers are not
+  private to the namespace. A helper called `isBlank` would stop any program that
+  declares its own `isBlank` from compiling (`` Function `isBlank` is also
+  defined in main.ts ``), which is why `text.ts` calls it `isTextBlankByte`. Keep
+  the helpers few and their names distinctive; a module whose internals want
+  `compare`, `next` or `parse` is asking for package-scoped symbols, which do not
+  exist yet ([`docs/wp26-stdlib.md`](../docs/wp26-stdlib.md) §3e). Module
+  constants are exempt — `NEWLINE` and `SPACE` fold at their uses, so a program
+  may declare those names itself.
+- **It is an Nish program**, so the constraints are the language's: a function is
+  an arrow bound to a module-level `const`, a function is never a value, there
+  is no `try` / `catch`, and there are no optional or default parameters. Those
+  three are what shape an API here more than any style preference — see the
+  header of `testing.ts` for what they did to that one, which was written before
+  WP18 added generic functions and classes
+  ([`docs/LANGUAGE.md`](../docs/LANGUAGE.md#generic-functions)) and still has
+  one assertion per type ([`docs/wp26-stdlib.md`](../docs/wp26-stdlib.md) §3c).
+  `pair.ts` is the first module here to export a generic type.
+- **Ship it with a `tests/link/` case.** `tests/link/<name>/` is the only place a
+  multi-module program is exercised end to end, and it is also what puts the
+  module into the corpus the stage1 oracles read
+  ([`.claude/selfhost.md`](../.claude/selfhost.md)): a `std/` module with no
+  importer in `tests/link/` is compiled by neither compiler on any run.
+  `testing.ts` has two, one per outcome — `tests/link/std_testing` (exit 0) and
+  `tests/link/std_testing_fail` (exit 1, and the wording of every failure
+  message) — and `text.ts` and `json.ts` have `tests/link/std_text` and
+  `tests/link/std_json`, each of which uses `Suite` to check the module, the way a
+  user would. `pair.ts` has five, `tests/link/std_pair_*`, one per shape of
+  instantiation, each returning a `Pair` from a sibling module and pinned by its
+  stdout. `tests/link/std_text_f64` is the same corpus under
+  `--number-mode f64`, which is where a module that spelled its widths and forgot
+  a `toI32` is caught.
+- **`std/` is not on the compiler's dependency list.** Nothing in `self/`
+  imports it, and nothing should: the compiler is the thing that has to
+  build before the library means anything.
+
+## Who reads the library, and what each reader proved
+
+Two programs in this repository are written on top of `std/`, and between them
+they are the reason the modules have the shape they do — a library with one
+consumer is a guess.
+
+| Program | What it does | What it uses |
+| --- | --- | --- |
+| [`tests/nish/run.ts`](../tests/nish/run.ts) | the golden cases and the `tests/link/` programs, compiled, assembled, linked, run and diffed | `Suite` (including `containsAll` for an `.err` file's fragments and `eqLines` for an IR golden), and all of `std/text` |
+| [`tests/nish/cli.ts`](../tests/nish/cli.ts) | the command line's own contract — the streams, the exit-code bands, and one flat `--json` object per diagnostic — read by a program in the language the compiler compiles | `Suite`, `jsonField`, `splitLines` / `trim` / `contains` |
+
+Three assertions exist because the first of those two had written them by hand:
+`contains` for a fragment of a captured stream, `containsAll` for an expectation
+file that holds one fragment per line, and `eqLines` for a generated text against
+a golden, which reports the first differing line instead of printing both texts.
+That is the rule the directory runs on — a `std/` function earns its place when a
+program in this repository would otherwise write the loop, and the loop is
+already written.
+
+`std/json` is the one module admitted with a single importer, and the reason is
+the *format* rather than the count: the object it reads is this project's own
+published surface (`AGENTS.md`, [`docs/wp12-release.md`](../docs/wp12-release.md)),
+so every Nish program that ever reads compiler output needs exactly this scan,
+and the next one would copy it out of `tests/nish/cli.ts`. The module is also
+where the format's one ambiguity is written down and tested —
+[`docs/wp26-stdlib.md`](../docs/wp26-stdlib.md) §7 question 3 is where that
+argument is recorded and where its second consumer is expected.
+
+## What `std/testing` is not, and what closed
+
+`std/testing` is a test *library*: it is how a compiled program checks itself.
+Driving the compiler — compiling a corpus, assembling it, linking it, running it
+and diffing stdout against a golden — needed three things the language did not
+have, and all three have since landed as builtins:
+
+| Was missing | Now |
+| --- | --- |
+| a directory listing | `readdirSync(path): string[] \| null`, sorted by bytes, because there is no `sort` for a caller to reach for |
+| a child's **output** — `spawnSync` answers a status and nothing else | `spawnSyncTo(argv, stdoutPath, stderrPath)`, each stream to a file, an empty path inheriting |
+| a clock | `monotonicNanos(): i64` |
+
+So the driver exists, in the language, and it is
+[`tests/nish/run.ts`](../tests/nish/run.ts): it discovers the golden cases with
+`readdirSync`, compiles each one by spawning the compiler, links and runs the ones
+with a `.out`, diffs the IR against the golden line by line, and reports through a
+`Suite`. It passes over the whole corpus — `npm run test:nish` — and `npm test`
+runs it over a handful of cases so that the three builtins are exercised together
+on a real workload on every run.
+
+It is still not a replacement for `tests/run.js`, and the difference is worth
+being precise about: it covers section A, the golden cases, and none of the
+pipeline checks — no interop sidecars, no layout assertions, no wasm profiles, no
+packaging and no self-hosting oracles. It also skips, by name and counted, the three
+sidecars it does not implement (`.env`, `.argv`, `.stdout`). What it demonstrates
+is that the language can host its own harness; what `tests/run.js` does is prove
+the compiler.

package/std/json.ts

@@ -0,0 +1,402 @@
+/**
+ * `std/json` — the value of one field of one flat JSON object.
+ *
+ * It exists because the compiler's own machine-readable surface is JSON: under
+ * `--json` every diagnostic is one flat object on a line of stdout, whose `code`
+ * is a stable rule identifier (`AGENTS.md`, and `docs/wp12-release.md` for the
+ * exit-code bands). A Nish program that reads that surface — a wrapper, an
+ * editor plug-in, or `tests/nish/cli.ts`, which pins the contract — needs the
+ * value of a named field and nothing else, and the language has no `JSON.parse`
+ * to give it.
+ *
+ * So this is a **reader, not a parser**, and the difference is worth stating:
+ *
+ *   - It answers **text**. A string field comes back with its escapes decoded
+ *     and without its quotes; a number, a `true` or a `null` comes back as the
+ *     bytes it was written with, for `parseInt` or `===` at the call site. A
+ *     field whose value is `null` and one whose value is the *string* `"null"`
+ *     therefore answer the same thing, which is the one ambiguity a program that
+ *     needs to tell them apart cannot live with — and the sign that it wants a
+ *     real parser rather than this.
+ *   - It answers `null` for a field that is not there, so "absent" and "empty"
+ *     stay apart the way they do in `getenv`.
+ *   - It **does not validate**. A nested object or array is stepped over so that
+ *     the fields after it are still reachable, and a truncated object still
+ *     answers the fields that precede the truncation. A program that has to know
+ *     whether the whole line was well-formed is asking a question this does not
+ *     answer.
+ *
+ * There is one exported function on purpose. A `std/` module is compiled into
+ * the program that imports it and the symbol namespace is flat
+ * (`std/README.md`), so every name here is a name its importer cannot use: the
+ * helpers are `json`-prefixed and the reader is the only export. Splitting a
+ * stream into lines and picking the ones that start with `{` is two calls the
+ * caller already has — `splitLines` from `std/text` and `startsWith` — and
+ * duplicating them here would cost more names than it saves.
+ *
+ *     import { jsonField } from "nish/json";
+ *
+ *     for (const line of splitLines(stdout)) {
+ *       if (!line.startsWith("{")) {
+ *         continue;
+ *       }
+ *       const code = jsonField(line, "code");
+ *       if (code !== null && code === "NL0003") {
+ *         panic("the compiler crashed");
+ *       }
+ *     }
+ *
+ * Every offset here is a **byte** offset and every width is spelled, with each
+ * length and byte a builtin answers read through `toI32` — `.length` and
+ * `charCodeAt` answer `number`, which is `f64` under `--number-mode f64`, so the
+ * conversion is what makes this one module in both modes rather than two
+ * (`docs/wp26-stdlib.md` §4).
+ */
+
+const JSON_TAB: i32 = 9;
+const JSON_NEWLINE: i32 = 10;
+const JSON_CARRIAGE_RETURN: i32 = 13;
+const JSON_SPACE: i32 = 32;
+const JSON_QUOTE: i32 = 34;
+const JSON_COMMA: i32 = 44;
+const JSON_COLON: i32 = 58;
+const JSON_BACKSLASH: i32 = 92;
+const JSON_OPEN_BRACKET: i32 = 91;
+const JSON_CLOSE_BRACKET: i32 = 93;
+const JSON_OPEN_BRACE: i32 = 123;
+const JSON_CLOSE_BRACE: i32 = 125;
+/**
+ * The UTF-8 tags a `\u` escape is rebuilt out of: a two-byte lead is
+ * `110xxxxx`, a three-byte lead `1110xxxx`, a continuation byte `10xxxxxx`, and
+ * `LOW_SIX` is the six bits each continuation carries.
+ *
+ * They are named constants rather than the literals `192`, `224`, `128` and `63`
+ * for a reason that is the module's rule and not a style preference: a bare
+ * numeric literal is a `number`, which is an `f64` under `--number-mode f64`, so
+ * `192 + (code >> 6)` adds an `f64` to an `i32` there and does not compile at all
+ * (`docs/wp26-stdlib.md` §4, and `tests/link/std_text_f64` is what says so). A
+ * constant declared `i32` means the same thing in both modes.
+ */
+const JSON_UTF8_TWO_BYTE_LEAD: i32 = 192;
+const JSON_UTF8_THREE_BYTE_LEAD: i32 = 224;
+const JSON_UTF8_CONTINUATION: i32 = 128;
+const JSON_UTF8_LOW_SIX: i32 = 63;
+/** The first code point that needs two UTF-8 bytes, and the first that needs three. */
+const JSON_UTF8_TWO_BYTE_FLOOR: i32 = 128;
+const JSON_UTF8_THREE_BYTE_FLOOR: i32 = 2048;
+/** The base `jsonHex4` accumulates in. */
+const JSON_HEX_BASE: i32 = 16;
+
+/** The four bytes JSON allows between tokens. */
+const jsonIsBlankByte = (code: i32): boolean =>
+  code === JSON_SPACE || code === JSON_TAB || code === JSON_NEWLINE || code === JSON_CARRIAGE_RETURN;
+
+/**
+ * The first index at or after `from` that is not blank, or the length.
+ *
+ * Every caller hands in an index it has already found, so `from` is never
+ * negative; the guard says so in a form the bounds proof reads, and is what
+ * lets the loop below read `text` without a check.
+ */
+const jsonSkipBlank = (text: string, from: i32): i32 => {
+  if (from < 0) {
+    return from;
+  }
+  const length: i32 = toI32(text.length);
+  let i: i32 = from;
+  while (i < length && jsonIsBlankByte(toI32(text.charCodeAt(i)))) {
+    i += 1;
+  }
+  return i;
+};
+
+/**
+ * The index just past the string literal whose opening quote is at `at`, or `-1`
+ * when the quote is never closed. A backslash takes the byte after it with it,
+ * which is all a scanner needs to know about escapes: `\"` cannot end the
+ * literal and `\\` cannot make the next quote an escape.
+ */
+const jsonEndOfString = (text: string, at: i32): i32 => {
+  const length: i32 = toI32(text.length);
+  if (at < 0) {
+    return -1;
+  }
+  let i: i32 = at + 1;
+  while (i < length) {
+    const code: i32 = toI32(text.charCodeAt(i));
+    if (code === JSON_BACKSLASH) {
+      i += 2;
+      continue;
+    }
+    if (code === JSON_QUOTE) {
+      return i + 1;
+    }
+    i += 1;
+  }
+  return -1;
+};
+
+/**
+ * The index just past the value that starts at `at`, or `-1` when it does not
+ * end.
+ *
+ * A string ends at its quote and an object or array at the closer that brings
+ * the depth back to zero, with strings inside it skipped whole so that a `}` in
+ * a message cannot close it. Anything else — a number, `true`, `false`, `null` —
+ * ends at the first byte that cannot be part of it, which is the comma, the
+ * closer or the blank that follows.
+ *
+ * The string skip inside an object is a flag in the one loop rather than a call
+ * to `jsonEndOfString` that moves the cursor to wherever it answers: a cursor
+ * that only ever steps forward keeps the lower bound the bounds proof needs,
+ * and one assigned a callee's answer does not.
+ */
+const jsonEndOfValue = (text: string, at: i32): i32 => {
+  const length: i32 = toI32(text.length);
+  if (at < 0 || at >= length) {
+    return -1;
+  }
+  const first: i32 = toI32(text.charCodeAt(at));
+  if (first === JSON_QUOTE) {
+    return jsonEndOfString(text, at);
+  }
+  if (first === JSON_OPEN_BRACE || first === JSON_OPEN_BRACKET) {
+    let depth: i32 = 0;
+    let inString: boolean = false;
+    let i: i32 = at;
+    while (i < length) {
+      const code: i32 = toI32(text.charCodeAt(i));
+      if (inString) {
+        // `jsonEndOfString`'s rule: a backslash takes the byte after it along.
+        if (code === JSON_BACKSLASH) {
+          i += 2;
+          continue;
+        }
+        if (code === JSON_QUOTE) {
+          inString = false;
+        }
+        i += 1;
+        continue;
+      }
+      if (code === JSON_QUOTE) {
+        inString = true;
+      } else if (code === JSON_OPEN_BRACE || code === JSON_OPEN_BRACKET) {
+        depth += 1;
+      } else if (code === JSON_CLOSE_BRACE || code === JSON_CLOSE_BRACKET) {
+        depth -= 1;
+        if (depth === 0) {
+          return i + 1;
+        }
+      }
+      i += 1;
+    }
+    return -1;
+  }
+  let i: i32 = at;
+  while (i < length) {
+    const code: i32 = toI32(text.charCodeAt(i));
+    if (code === JSON_COMMA || code === JSON_CLOSE_BRACE || code === JSON_CLOSE_BRACKET) {
+      return i;
+    }
+    if (jsonIsBlankByte(code)) {
+      return i;
+    }
+    i += 1;
+  }
+  return length;
+};
+
+/** The value of one lower-case or upper-case hex digit, or `-1`. */
+const jsonHexDigit = (code: i32): i32 => {
+  if (code >= 48 && code <= 57) {
+    return code - 48;
+  }
+  if (code >= 97 && code <= 102) {
+    return code - 87;
+  }
+  if (code >= 65 && code <= 70) {
+    return code - 55;
+  }
+  return -1;
+};
+
+/** The four hex digits at `at` as one code point, or `-1` when they are not four hex digits. */
+const jsonHex4 = (text: string, at: i32, end: i32): i32 => {
+  if (at + 4 > end) {
+    return -1;
+  }
+  let value: i32 = 0;
+  let i: i32 = 0;
+  while (i < 4) {
+    const digit: i32 = jsonHexDigit(toI32(text.charCodeAt(at + i)));
+    if (digit < 0) {
+      return -1;
+    }
+    value = value * JSON_HEX_BASE + digit;
+    i += 1;
+  }
+  return value;
+};
+
+/**
+ * `code` as UTF-8, one to three bytes.
+ *
+ * A surrogate pair is **not** recombined: each half becomes its own three-byte
+ * sequence, which is what `😀` reads as here. Nothing this module
+ * exists to read produces one — `JSON.stringify`, and `jsonQuote` in
+ * `self/strings.ts` which matches it byte for byte, escape only the seven short
+ * forms and `\u00xx` below `0x20`, and pass every other byte through as itself —
+ * so the alternative would be code with no caller to keep it honest.
+ */
+const jsonUtf8 = (code: i32): string => {
+  if (code < JSON_UTF8_TWO_BYTE_FLOOR) {
+    return String.fromCharCode(code);
+  }
+  if (code < JSON_UTF8_THREE_BYTE_FLOOR) {
+    const lead: string = String.fromCharCode(JSON_UTF8_TWO_BYTE_LEAD + (code >> 6));
+    return `${lead}${String.fromCharCode(JSON_UTF8_CONTINUATION + (code & JSON_UTF8_LOW_SIX))}`;
+  }
+  const lead: string = String.fromCharCode(JSON_UTF8_THREE_BYTE_LEAD + (code >> 12));
+  const middle: string = String.fromCharCode(JSON_UTF8_CONTINUATION + ((code >> 6) & JSON_UTF8_LOW_SIX));
+  return `${lead}${middle}${String.fromCharCode(JSON_UTF8_CONTINUATION + (code & JSON_UTF8_LOW_SIX))}`;
+};
+
+/**
+ * The bytes of `text[at..end)` with the JSON escapes decoded — the body of a
+ * string literal, without its quotes.
+ *
+ * A literal with no backslash in it is answered as a substring, which is the
+ * common case and the whole reason for the first loop: a diagnostic's `file` and
+ * `code` never carry an escape, and building them out of parts would allocate an
+ * array to copy a string that was already there. An unknown escape stands for
+ * the byte it escapes, which is what `\"`, `\\` and `\/` want and is the lenient
+ * reading of anything else.
+ */
+const jsonUnescape = (text: string, at: i32, end: i32): string => {
+  // Both callers pass the inside of a literal `jsonEndOfString` found, so
+  // `0 <= at` and `end <= text.length` always hold. Saying so here is what
+  // proves every read below in range and drops the `substring` clamps.
+  if (at < 0 || end > toI32(text.length)) {
+    return "";
+  }
+  let i: i32 = at;
+  while (i < end && toI32(text.charCodeAt(i)) !== JSON_BACKSLASH) {
+    i += 1;
+  }
+  if (i >= end) {
+    return text.substring(at, end);
+  }
+  const parts: string[] = [];
+  let start: i32 = at;
+  while (i < end) {
+    if (toI32(text.charCodeAt(i)) !== JSON_BACKSLASH) {
+      i += 1;
+      continue;
+    }
+    // `start === i` is an escape straight after another, and the empty run
+    // between them adds nothing to the join. The `start >= 0` half is always
+    // true — `start` is `at` or a cursor that has only moved forward — and is
+    // there because `start` is reassigned in the loop, which is where the
+    // bounds proof stops following it.
+    if (start >= 0 && start < i) {
+      parts.push(text.substring(start, i));
+    }
+    // A trailing backslash has nothing after it: `0` is no escape letter, so it
+    // falls to the default below and stands for itself.
+    const letter: i32 = i + 1 < end ? toI32(text.charCodeAt(i + 1)) : 0;
+    if (letter === 110) {
+      parts.push("\n");
+      i += 2;
+    } else if (letter === 116) {
+      parts.push("\t");
+      i += 2;
+    } else if (letter === 114) {
+      parts.push("\r");
+      i += 2;
+    } else if (letter === 98) {
+      parts.push(String.fromCharCode(8));
+      i += 2;
+    } else if (letter === 102) {
+      parts.push(String.fromCharCode(12));
+      i += 2;
+    } else if (letter === 117) {
+      const code: i32 = jsonHex4(text, i + 2, end);
+      if (code < 0) {
+        // Not four hex digits after the `u`: the escape is broken, and copying it
+        // through unchanged is the reading that loses nothing.
+        parts.push("\\u");
+        i += 2;
+      } else {
+        parts.push(jsonUtf8(code));
+        i += 6;
+      }
+    } else if (letter === 0) {
+      parts.push("\\");
+      i += 1;
+    } else {
+      parts.push(String.fromCharCode(letter));
+      i += 2;
+    }
+    start = i;
+  }
+  parts.push(text.substring(start, end));
+  return parts.join("");
+};
+
+/**
+ * The value of `name` in `object`, or `null` when the object does not have that
+ * field.
+ *
+ * A string value comes back unquoted and unescaped; any other value comes back
+ * as the bytes it was written with, so `parseInt` reads a number and `=== "true"`
+ * reads a boolean. The scan is left to right and answers the **first** field of
+ * that name, which is what a duplicated key means to every JSON reader that does
+ * not build a map.
+ *
+ * A nested value is stepped over rather than searched, so `name` is a field of
+ * this object and not a path into it: that is the "flat" in the module header,
+ * and it is the shape the compiler's `--json` line has.
+ */
+export const jsonField = (object: string, name: string): string | null => {
+  const length: i32 = toI32(object.length);
+  let i: i32 = jsonSkipBlank(object, 0);
+  if (i >= length || toI32(object.charCodeAt(i)) !== JSON_OPEN_BRACE) {
+    return null;
+  }
+  i = jsonSkipBlank(object, i + 1);
+  // `jsonSkipBlank` never answers a negative index for a non-negative one, but
+  // the bounds proof does not look inside a callee, so every cursor it answers
+  // is tested for `i < 0` beside `i >= length`: the pair is what lets each read
+  // below go without a check.
+  while (i >= 0 && i < length && toI32(object.charCodeAt(i)) === JSON_QUOTE) {
+    const keyEnd: i32 = jsonEndOfString(object, i);
+    if (keyEnd < 0) {
+      return null;
+    }
+    const key: string = jsonUnescape(object, i + 1, keyEnd - 1);
+    i = jsonSkipBlank(object, keyEnd);
+    if (i < 0 || i >= length || toI32(object.charCodeAt(i)) !== JSON_COLON) {
+      return null;
+    }
+    const valueAt: i32 = jsonSkipBlank(object, i + 1);
+    const valueEnd: i32 = jsonEndOfValue(object, valueAt);
+    // `jsonEndOfValue` answers `-1` for a `valueAt` outside the object and never
+    // answers past its end, so the last three tests change no answer: they are
+    // the range the value's first byte and its `substring` are proved in.
+    if (valueEnd < 0 || valueAt < 0 || valueAt >= length || valueEnd > toI32(object.length)) {
+      return null;
+    }
+    if (key === name) {
+      if (toI32(object.charCodeAt(valueAt)) === JSON_QUOTE) {
+        return jsonUnescape(object, valueAt + 1, valueEnd - 1);
+      }
+      return object.substring(valueAt, valueEnd);
+    }
+    i = jsonSkipBlank(object, valueEnd);
+    if (i < 0 || i >= length || toI32(object.charCodeAt(i)) !== JSON_COMMA) {
+      return null;
+    }
+    i = jsonSkipBlank(object, i + 1);
+  }
+  return null;
+};

package/std/pair.ts

@@ -0,0 +1,28 @@
+/**
+ * `std/pair` — two values answered by one call.
+ *
+ * It exists for the function that has two things to say, like the lexer's
+ * `scanEscape`: where an escape ended, and whether it was malformed. Without a
+ * pair, the second answer lives in a field on some object, written by the
+ * callee and read back by the caller three lines later. With one, both come
+ * back in the return:
+ *
+ *     import { Pair } from "nish/pair";
+ *
+ *     const scanEscape = (at: i32): Pair<i32, boolean> => ({ first: at + 2, second: true });
+ *
+ * It is **for returning two values, not for storing them**. A struct held in an
+ * array or a class field should have named fields, and parallel arrays are the
+ * house style for two values side by side (`docs/wp15-performance.md` §1a), so
+ * a `Pair[]` is usually the slower shape and the less readable one.
+ *
+ * It is an `interface` rather than a class, so there is no constructor to call
+ * and nothing to import but the type: an object literal takes its type from the
+ * annotation, and the checker holds it to setting `first` and `second` exactly
+ * once each. There is no tuple syntax behind it and no special case in the
+ * compiler; `docs/wp23-language-surface.md` §5 is the argument for that.
+ */
+export interface Pair<A, B> {
+  first: A;
+  second: B;
+}