@amritk/nish-x86_64-linux 0.10.0

package/std/testing.ts

@@ -0,0 +1,347 @@
+/**
+ * `std/testing` — a test runner for Nish programs, written in Nish.
+ *
+ * The repository's own suite is `tests/run.js`, a Node program: it compiles the
+ * corpus, assembles it, links it and diffs the result against a golden, so it
+ * has to be able to spawn a compiler and read a directory. This module answers
+ * the other half of the question — a *program* that checks its own behaviour
+ * and reports it — and it answers it in the language, with no Node anywhere.
+ *
+ * Five language rules shape the API, and each of them removes a shape that a
+ * JavaScript test framework would have reached for first:
+ *
+ *   1. **A function is not a value** ([LANGUAGE.md](../docs/LANGUAGE.md) §
+ *      Functions), so there is no `test("name", () => { ... })`. A suite is an
+ *      object the test program drives with straight-line calls, and the test
+ *      names are arguments rather than closures. This is not a workaround: the
+ *      whole-program pass cannot prove purity, termination or escape facts
+ *      through an unknown callee, which is what keeps function types out of the
+ *      language in the first place.
+ *   2. **There is no `try` / `catch`**, so an assertion cannot throw and be
+ *      collected. Each one records its outcome and returns it, and `done`
+ *      turns the tally into the process exit code.
+ *   3. **Every assertion answers a `boolean`** for the reason that follows from
+ *      2: an out-of-range index and an empty `pop` *panic*, which ends the
+ *      process, so "check the length, then read the element" has to be a real
+ *      branch — `if (!suite.eqI32("len", a.length, 3)) { return suite.done(); }`
+ *      is how a test stops before the read that would abort the whole run.
+ *   4. **There are no generics**, so there is one assertion per type rather
+ *      than one `eq` over all of them. The alternative — a single `eq` taking
+ *      strings and asking every caller to interpolate — would report
+ *      `expected "3", got "4"` for two numbers and lose the type in the
+ *      message.
+ *   5. **There are no optional or default parameters**, so every assertion
+ *      takes its name and its detail in full.
+ *
+ * The output is deliberately the shape `tests/run.js` prints — `PASS  <name>`,
+ * `FAIL  <name>` with an indented detail line, `SKIP  <name> (<reason>)`, and a
+ * summary that ends `N passed, M failed, K skipped` — so a Nish test program
+ * reads like the rest of the suite and a skip is counted rather than merely
+ * mentioned. A green run that skipped half its checks should look different
+ * from one that proved everything.
+ *
+ * The widths are spelled explicitly (`i32`, `i64`, `f64`) rather than as
+ * `number`, so the module means the same thing under `--number-mode f64` as it
+ * does by default, exactly as `examples/arrays.ts` does — and every length this
+ * module reads from a builtin is converted with `toI32`, because `.length`
+ * answers `number` and spelling one's own widths is therefore necessary and not
+ * sufficient (`docs/wp26-stdlib.md` §4). Without the conversion the two
+ * comparisons against a length below would lower to `fcmp` on an `f64` in that
+ * mode and to `icmp` on an `i32` here, which is the same module compiling to
+ * two different programs.
+ *
+ *     import { Suite } from "../std/testing";
+ *
+ *     export const main = (): number => {
+ *       const t = new Suite("arrays");
+ *       const a: i32[] = [1, 2, 3];
+ *       if (!t.eqI32("length", a.length, 3)) {
+ *         return t.done();          // a[2] below would panic, not fail
+ *       }
+ *       t.eqI32("last", a[2], 3);
+ *       return t.done();            // 0 when nothing failed, 1 otherwise
+ *     };
+ */
+
+/**
+ * How much of a haystack a failure detail quotes.
+ *
+ * The haystack in every real use of `contains` is a captured stream or a module
+ * of generated text, and a detail line forty thousand bytes long is not a
+ * diagnostic — it is the output the reader was already searching by hand.
+ */
+const TESTING_EXCERPT: i32 = 200;
+
+/**
+ * `text` when it is short enough to read, and its first `TESTING_EXCERPT` bytes
+ * with the whole length named otherwise.
+ *
+ * The cut is at a byte, like every offset in this language, so a multi-byte
+ * character at the boundary is split — which is acceptable here and would not be
+ * anywhere else: this string is read by a person looking at a failure, not by a
+ * program.
+ *
+ * The name is deliberately not `excerpt`. A `std/` module is compiled into the
+ * program that imports it and the symbol namespace is flat, so a private helper
+ * called `excerpt` would stop any program that declares its own `excerpt` from
+ * compiling (`std/README.md`, "Name the private helpers as though they were
+ * exported").
+ */
+const testingExcerpt = (text: string): string => {
+  const length: i32 = toI32(text.length);
+  if (length <= TESTING_EXCERPT) {
+    return text;
+  }
+  return `${text.substring(0, TESTING_EXCERPT)}... (${length} bytes)`;
+};
+
+/**
+ * The index of the first line at which `actual` and `expected` differ, the
+ * shorter length when one is a prefix of the other, and `-1` when they are
+ * equal.
+ *
+ * `std/text` exports `firstDifference`, which is this loop, and this module
+ * deliberately does not import it: an import of a `std/` module is compiled into
+ * the program, so reaching for it here would put `trim`, `contains` and
+ * `replaceAll` into the namespace of every program that only wanted a `Suite`.
+ * Ten lines is the cheaper half of that trade.
+ */
+const testingFirstDifferentLine = (actual: string[], expected: string[]): i32 => {
+  const actualLength: i32 = toI32(actual.length);
+  const expectedLength: i32 = toI32(expected.length);
+  const shorter: i32 = actualLength < expectedLength ? actualLength : expectedLength;
+  let i: i32 = 0;
+  // Two bounds rather than `i < shorter`: they stop at the same index, and each
+  // is what proves one of the two reads below in range, where the minimum of
+  // the pair proves neither.
+  while (i < actualLength && i < expectedLength) {
+    if (actual[i] !== expected[i]) {
+      return i;
+    }
+    i += 1;
+  }
+  return actualLength === expectedLength ? -1 : shorter;
+};
+
+/**
+ * One run of checks, and the tally it reports.
+ *
+ * A program may hold several — one per family of behaviour — and sum their exit
+ * codes, because `done` answers a code rather than ending the process: a suite
+ * that called `process.exit` itself would make the second suite unreachable.
+ */
+export class Suite {
+  /** Names the summary line, so several suites in one program stay apart. */
+  name: string;
+  // These three have initializers because the constructor does not assign them,
+  // and every field holds a value once it returns. `name` does not, and an
+  // initializer there would only be a store the constructor overwrites.
+  passed: i32 = 0;
+  failed: i32 = 0;
+  skipped: i32 = 0;
+  /**
+   * The names of the checks that failed, recapped by `done`. The detail of
+   * each was printed when it happened; this is the list a reader wants after
+   * a hundred lines of output have scrolled the failures off the screen.
+   */
+  failures: string[];
+
+  constructor(name: string) {
+    this.name = name;
+    this.failures = [];
+  }
+
+  /** Records a pass. Public because a program with a check of its own shape still wants the tally. */
+  pass(name: string): boolean {
+    this.passed += 1;
+    console.log(`PASS  ${name}`);
+    return true;
+  }
+
+  /**
+   * Records a failure, with `detail` on its own indented line when there is
+   * one. An empty `detail` prints no second line, which is what a check whose
+   * name already says everything wants.
+   */
+  fail(name: string, detail: string): boolean {
+    this.failed += 1;
+    this.failures.push(name);
+    console.log(`FAIL  ${name}`);
+    if (toI32(detail.length) > 0) {
+      console.log(`      ${detail}`);
+    }
+    return false;
+  }
+
+  /**
+   * Records a check that did not run, and why. It answers `void` rather than a
+   * `boolean` because there is no outcome to branch on: the caller has already
+   * decided to skip, the way `tests/run.js` decides when `llvm-as` is missing.
+   */
+  skip(name: string, reason: string): void {
+    this.skipped += 1;
+    console.log(`SKIP  ${name} (${reason})`);
+  }
+
+  ok(name: string, condition: boolean): boolean {
+    if (condition) {
+      return this.pass(name);
+    }
+    return this.fail(name, "expected true, got false");
+  }
+
+  eqBool(name: string, actual: boolean, expected: boolean): boolean {
+    if (actual === expected) {
+      return this.pass(name);
+    }
+    return this.fail(name, `expected ${expected}, got ${actual}`);
+  }
+
+  eqI32(name: string, actual: i32, expected: i32): boolean {
+    if (actual === expected) {
+      return this.pass(name);
+    }
+    return this.fail(name, `expected ${expected}, got ${actual}`);
+  }
+
+  eqI64(name: string, actual: i64, expected: i64): boolean {
+    if (actual === expected) {
+      return this.pass(name);
+    }
+    return this.fail(name, `expected ${expected}, got ${actual}`);
+  }
+
+  /**
+   * Exact `f64` equality, which is `fcmp oeq`: `NaN` is equal to nothing, so a
+   * check of a computation that can produce one fails rather than passing by
+   * accident. Use `nearF64` for anything that went through arithmetic.
+   */
+  eqF64(name: string, actual: f64, expected: f64): boolean {
+    if (actual === expected) {
+      return this.pass(name);
+    }
+    return this.fail(name, `expected ${expected}, got ${actual}`);
+  }
+
+  /**
+   * `f64` equality within `tolerance`, the absolute difference. The tolerance
+   * is a parameter rather than a constant here because the right epsilon
+   * belongs to the computation, not to the harness.
+   */
+  nearF64(name: string, actual: f64, expected: f64, tolerance: f64): boolean {
+    let delta: f64 = actual - expected;
+    if (delta < 0) {
+      delta = -delta;
+    }
+    if (delta <= tolerance) {
+      return this.pass(name);
+    }
+    return this.fail(name, `expected ${expected} +/- ${tolerance}, got ${actual}`);
+  }
+
+  /**
+   * String equality by content (`nish_str_eq`), which is what `===` on two
+   * strings already means. The values are quoted in the message so that a
+   * trailing space or an empty string is visible in the diff.
+   */
+  eqStr(name: string, actual: string, expected: string): boolean {
+    if (actual === expected) {
+      return this.pass(name);
+    }
+    return this.fail(name, `expected "${expected}", got "${actual}"`);
+  }
+
+  /**
+   * Whether `needle` occurs anywhere in `haystack`, which is the assertion a
+   * check over captured output makes: the message a compiler prints is pinned by
+   * the sentence it has to contain and not by the whole stream, because the rest
+   * of that stream is a version line and a file path that change for reasons the
+   * check is not about.
+   *
+   * The detail quotes the needle in full and the haystack only to
+   * `TESTING_EXCERPT` bytes: the needle is what a reader compares, and the
+   * haystack is what they have already got.
+   */
+  contains(name: string, haystack: string, needle: string): boolean {
+    if (toI32(haystack.indexOf(needle)) >= 0) {
+      return this.pass(name);
+    }
+    return this.fail(name, `expected to contain "${needle}", got "${testingExcerpt(haystack)}"`);
+  }
+
+  /**
+   * Whether every one of `needles` occurs in `haystack` — one check for an
+   * expectation file that holds a fragment per line, which is the shape
+   * `tests/cases/<name>.err` and `tests/link/<name>/expected.ir` both have.
+   *
+   * An empty needle is ignored, so the blank lines of such a file cost the caller
+   * no filtering, and a list with nothing in it passes: an expectation that says
+   * nothing is met by anything. The detail names the first fragment that is
+   * missing and how many are, because a detail that quoted all of them would bury
+   * the one a reader fixes first.
+   */
+  containsAll(name: string, haystack: string, needles: string[]): boolean {
+    let looked: i32 = 0;
+    let missing: i32 = 0;
+    let first = "";
+    for (const needle of needles) {
+      if (toI32(needle.length) === 0) {
+        continue;
+      }
+      looked += 1;
+      if (toI32(haystack.indexOf(needle)) < 0) {
+        missing += 1;
+        if (toI32(first.length) === 0) {
+          first = needle;
+        }
+      }
+    }
+    if (missing === 0) {
+      return this.pass(name);
+    }
+    if (missing === 1) {
+      return this.fail(name, `missing "${first}"`);
+    }
+    // `looked` and not `needles.length`, because the blank lines this ignored are
+    // not fragments anybody expected to find.
+    return this.fail(name, `missing ${missing} of ${looked}, first "${first}"`);
+  }
+
+  /**
+   * Line-by-line equality of two texts already split into lines, reporting the
+   * first line that differs.
+   *
+   * It is `eqStr`'s answer for the case `eqStr` reports badly: a golden of four
+   * hundred lines against an emitted four hundred and one prints two walls of
+   * text under `expected ... got ...`, and the reader's next move is to diff them
+   * by hand. `<end of input>` is the side that ran out, which is what a missing
+   * or an extra line at the end looks like from here, and the line number is the
+   * one an editor takes.
+   */
+  eqLines(name: string, actual: string[], expected: string[]): boolean {
+    const at: i32 = testingFirstDifferentLine(actual, expected);
+    if (at < 0) {
+      return this.pass(name);
+    }
+    const wanted = at < toI32(expected.length) ? `"${expected[at]}"` : "<end of input>";
+    const saw = at < toI32(actual.length) ? `"${actual[at]}"` : "<end of input>";
+    return this.fail(name, `line ${at + 1}: expected ${wanted}, got ${saw}`);
+  }
+
+  /**
+   * Prints the recap and the summary, and answers the exit code: 0 when
+   * nothing failed, 1 otherwise. A skip is not a failure, so it does not move
+   * the code — it moves the count on the summary line, which is the whole
+   * reason the count is printed.
+   */
+  done(): i32 {
+    if (toI32(this.failures.length) > 0) {
+      console.log(`failed: ${this.failures.join(", ")}`);
+    }
+    console.log(`${this.name}: ${this.passed} passed, ${this.failed} failed, ${this.skipped} skipped`);
+    if (this.failed > 0) {
+      return 1;
+    }
+    return 0;
+  }
+}

package/std/text.ts

@@ -0,0 +1,193 @@
+/**
+ * `std/text` — the string operations a program has to write itself.
+ *
+ * The language gives a string `length`, `charCodeAt`, `substring`, `indexOf`,
+ * `startsWith`, `endsWith` and `===` by content, and an array `join`. It does
+ * **not** give `split`, `trim`, `toLowerCase` or a regular expression, and that
+ * is a decision rather than a gap: each of those allocates, and several of them
+ * need a locale or a character table that this runtime has no room for
+ * (`docs/wp7-runtime.md` keeps the runtime under a measured byte budget).
+ *
+ * So a program that reads a file and wants its lines writes the loop. This
+ * module is that loop, written once. Every offset here is a **byte** offset,
+ * like `s.length` itself, and every function is ASCII-only where it inspects
+ * characters at all — a UTF-8 string passes through `splitLines` and `split`
+ * untouched, because a newline and a space cannot appear inside a multi-byte
+ * sequence.
+ *
+ * Every width this module declares is spelled (`i32`, never `number`) *and*
+ * every value a builtin hands it is converted at the read: `s.length`,
+ * `a.length`, `s.charCodeAt(i)` and `s.indexOf(t)` all answer `number`
+ * (LANGUAGE.md, *Arrays and strings as receivers*), and `number` is `f64` under
+ * `--number-mode f64`. Spelling the declarations is therefore necessary and not
+ * sufficient — without the `toI32` at each read this module does not compile in
+ * that mode at all (`docs/wp26-stdlib.md` §4). A length a loop tests on every
+ * iteration is read into an `i32` local once rather than converted per
+ * iteration, which is both cheaper and how the loop wants to read; a string is
+ * immutable, so its length cannot change underneath the local.
+ */
+
+const NEWLINE: i32 = 10;
+const CARRIAGE_RETURN: i32 = 13;
+const SPACE: i32 = 32;
+const TAB: i32 = 9;
+
+/**
+ * Whether `code` is one of the four ASCII bytes this module treats as blank.
+ *
+ * The name is deliberately not `isBlank`. A `std/` module's private functions
+ * share the importing program's flat symbol namespace, so a program that
+ * declares its own `isBlank` could not compile against this module
+ * (`docs/wp26-stdlib.md` §3e); naming the module and the unit of inspection
+ * makes the collision unlikely instead.
+ */
+const isTextBlankByte = (code: i32): boolean =>
+  code === SPACE || code === TAB || code === NEWLINE || code === CARRIAGE_RETURN;
+
+/**
+ * The lines of `text`, without their terminators.
+ *
+ * A trailing newline does **not** produce a final empty line, because a text
+ * file that ends in one has as many lines as it has newlines and a caller
+ * comparing two files line by line would otherwise see a phantom difference at
+ * the end. A `\r\n` line ending keeps its `\r`: stripping it would make this
+ * function guess at the file's provenance, and a caller that needs it gone can
+ * `trimEnd` each line.
+ */
+export const splitLines = (text: string): string[] => {
+  const length: i32 = toI32(text.length);
+  const lines: string[] = [];
+  let start: i32 = 0;
+  let i: i32 = 0;
+  while (i < length) {
+    if (toI32(text.charCodeAt(i)) === NEWLINE) {
+      // `start` is never negative and never passes `i`, which is below
+      // `length`, so this test always holds. It is written because it is what
+      // proves `start` within `text`: the clamp on that bound is dead once it
+      // is proven, and the emitter drops it.
+      if (start >= 0 && start < length) {
+        lines.push(text.substring(start, i));
+      }
+      start = i + 1;
+    }
+    i += 1;
+  }
+  if (start < length) {
+    lines.push(text.substring(start, length));
+  }
+  return lines;
+};
+
+/**
+ * The runs of non-blank bytes in `text`, with every blank run as the separator.
+ * Leading, trailing and repeated blanks produce no empty elements, which is what
+ * splitting a line of command-line flags wants — and it is why this is not
+ * `split(text, " ")`, which would.
+ */
+export const splitWhitespace = (text: string): string[] => {
+  const length: i32 = toI32(text.length);
+  const parts: string[] = [];
+  let start: i32 = -1;
+  let i: i32 = 0;
+  while (i < length) {
+    if (isTextBlankByte(toI32(text.charCodeAt(i)))) {
+      // `start` is `-1` or a byte already passed, so the second half always
+      // holds when the first does; it proves the bound, as in `splitLines`.
+      if (start >= 0 && start < length) {
+        parts.push(text.substring(start, i));
+        start = -1;
+      }
+    } else if (start < 0) {
+      start = i;
+    }
+    i += 1;
+  }
+  if (start >= 0) {
+    parts.push(text.substring(start, length));
+  }
+  return parts;
+};
+
+/** `text` without its leading blank bytes. */
+export const trimStart = (text: string): string => {
+  const length: i32 = toI32(text.length);
+  let i: i32 = 0;
+  while (i < length && isTextBlankByte(toI32(text.charCodeAt(i)))) {
+    i += 1;
+  }
+  return text.substring(i, length);
+};
+
+/** `text` without its trailing blank bytes. */
+export const trimEnd = (text: string): string => {
+  let end: i32 = toI32(text.length);
+  while (end > 0 && isTextBlankByte(toI32(text.charCodeAt(end - 1)))) {
+    end -= 1;
+  }
+  return text.substring(0, end);
+};
+
+/** `text` without blank bytes at either end. */
+export const trim = (text: string): string => trimEnd(trimStart(text));
+
+/**
+ * Whether `needle` occurs anywhere in `haystack`. One `indexOf`, named, because
+ * `indexOf(...) >= 0` at a call site reads as arithmetic where the question is a
+ * yes or a no. `contains(s, "")` is `true`, as `indexOf("")` is `0`.
+ */
+export const contains = (haystack: string, needle: string): boolean => toI32(haystack.indexOf(needle)) >= 0;
+
+/**
+ * `text` with every occurrence of `needle` replaced by `replacement`.
+ *
+ * The parts are collected and `join`ed once rather than concatenated in the loop:
+ * `s = s + t` inside a loop is quadratic in time *and* in arena, which is the one
+ * string mistake this project has measured the cost of — 180 MB of peak memory
+ * for 88 KB of output (`docs/wp14-selfhost.md` §3).
+ *
+ * An empty `needle` answers `text` unchanged, because every other answer is a
+ * choice about how many empty matches a string contains.
+ */
+export const replaceAll = (text: string, needle: string, replacement: string): string => {
+  const needleLength: i32 = toI32(needle.length);
+  if (needleLength === 0) {
+    return text;
+  }
+  const parts: string[] = [];
+  let rest = text;
+  while (true) {
+    const at: i32 = toI32(rest.indexOf(needle));
+    // `indexOf` never answers past `rest.length`, so the second half never
+    // holds; it is written because its negation is what proves `at` within
+    // `rest` for the `substring` below, as in `splitLines`.
+    if (at < 0 || at > toI32(rest.length)) {
+      parts.push(rest);
+      return parts.join(replacement);
+    }
+    parts.push(rest.substring(0, at));
+    rest = rest.substring(at + needleLength, toI32(rest.length));
+  }
+};
+
+/**
+ * The index of the first line at which `left` and `right` differ, or `-1` when
+ * one is a prefix of the other and they have the same length — that is, when
+ * they are equal. A caller comparing generated text against a golden wants the
+ * first differing line and not a boolean, because printing two whole files is
+ * not a diagnostic.
+ */
+export const firstDifference = (left: string[], right: string[]): i32 => {
+  const leftLength: i32 = toI32(left.length);
+  const rightLength: i32 = toI32(right.length);
+  let i: i32 = 0;
+  // Two tests rather than one against the shorter length: each proves `i`
+  // within one of the arrays, and a minimum taken with a ternary proves
+  // neither. The loop ends with `i` at the shorter length.
+  while (i < leftLength && i < rightLength) {
+    if (left[i] !== right[i]) {
+      return i;
+    }
+    i += 1;
+  }
+  return leftLength === rightLength ? -1 : i;
+};