@hyperfixi/testing-framework 3.1.1 → 3.3.0

package/src/multilingual/value-matrix-gate.ts

@@ -0,0 +1,118 @@
+/**
+ * The value matrix gate (see value-matrix.ts), one position per test file —
+ * `value-matrix.<position>.test.ts`, and a position's operator-phrase cells in
+ * `value-matrix.<position>-phrases.test.ts` — so vitest runs the shards in
+ * parallel. Each shard judges only its own cells against the shared baseline.
+ *
+ * Assertions:
+ *   1. every cell has an oracle: upstream runs its English source (the
+ *      generator only produces upstream-valid cells);
+ *   2. no failing (cell, lane) pair is missing from the baseline;
+ *   3. no listed pair passes now — prune it, so the list only shrinks;
+ *   4. no listed cell is gone from the generator.
+ *
+ * After an intentional change: `npx tsx tools/regen-value-matrix-baseline.ts`
+ * (shrink-only; `--allow-new` to accept new failures, with a reason in the PR).
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, it, expect, beforeAll } from 'vitest';
+import {
+  diffBaseline,
+  failingLanes,
+  generateCells,
+  isPhraseCell,
+  orphanedEntries,
+  runValueMatrix,
+  type CellResult,
+  type Position,
+  type ValueMatrixBaseline,
+} from './value-matrix';
+
+export const BASELINE_PATH = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../baselines/value-matrix.json'
+);
+
+export function loadBaseline(): ValueMatrixBaseline {
+  return JSON.parse(readFileSync(BASELINE_PATH, 'utf8')) as ValueMatrixBaseline;
+}
+
+/** At most `max` lines, then a count: a broad regression must not print thousands. */
+function capped(lines: string[], max = 40): string[] {
+  return lines.length <= max ? lines : [...lines.slice(0, max), `… and ${lines.length - max} more`];
+}
+
+/**
+ * One shard: a position's cells without the operator phrases (`values`), or
+ * its phrase cells (`phrases`), which add half again to the matrix and would
+ * double a position's shard.
+ */
+export function describeValueMatrixShard(
+  position: Position,
+  part: 'values' | 'phrases' = 'values'
+): void {
+  const all = generateCells();
+  const cells = all.filter(
+    cell => cell.position === position && isPhraseCell(cell) === (part === 'phrases')
+  );
+  const shard = part === 'phrases' ? `${position}-phrases` : position;
+  const baseline = loadBaseline();
+
+  describe(`value matrix: ${shard}`, () => {
+    let results: CellResult[] = [];
+
+    beforeAll(async () => {
+      results = await runValueMatrix(cells);
+      const pairs = results.reduce((n, r) => n + Object.keys(r.lanes).length, 0);
+      const failing = results.reduce((n, r) => n + failingLanes(r).length, 0);
+      console.log(
+        `value matrix [${shard}]: ${cells.length} cells, ${pairs} (cell, lane) pairs, ${failing} failing`
+      );
+    }, 900_000);
+
+    it('every cell has an oracle', () => {
+      expect(cells.length).toBeGreaterThan(50);
+      expect(results).toHaveLength(cells.length);
+      expect(results.filter(r => r.invalid).map(r => `${r.id}: ${r.invalid}`)).toEqual([]);
+    });
+
+    it('no failing pair is missing from the baseline', () => {
+      const { added } = diffBaseline(results, baseline);
+      expect(
+        capped(
+          added.map(
+            a => `${a.id} [${a.lane}] want ${JSON.stringify(a.want)}, got ${JSON.stringify(a.got)}`
+          )
+        )
+      ).toEqual([]);
+    });
+
+    it('no listed pair passes now (prune it with tools/regen-value-matrix-baseline.ts)', () => {
+      const { fixed } = diffBaseline(results, baseline);
+      expect(capped(fixed.map(f => `${f.id} [${f.lane}]`))).toEqual([]);
+    });
+
+    // The values shard owns its position's entries, phrase cells included.
+    it('no listed cell is gone from the generator', () => {
+      if (part === 'phrases') return;
+      const own = Object.fromEntries(
+        Object.entries(baseline.entries).filter(([id]) => id.startsWith(`${position}|`))
+      );
+      expect(orphanedEntries({ entries: own }, all)).toEqual([]);
+    });
+
+    // A phrase added to a position with no phrases shard would run nowhere.
+    it('every phrase cell of the position has its shard', () => {
+      if (part === 'phrases') return;
+      const phrases = all.filter(cell => cell.position === position && isPhraseCell(cell));
+      const file = path.join(
+        path.dirname(fileURLToPath(import.meta.url)),
+        `value-matrix.${position}-phrases.test.ts`
+      );
+      expect(phrases.length === 0 || existsSync(file), file).toBe(true);
+    });
+  });
+}

package/src/multilingual/value-matrix.accepted.test.ts

@@ -0,0 +1,65 @@
+/**
+ * The value matrix's accepted pairs (ACCEPTED in value-matrix.ts): failures the
+ * owner decided to keep. A cell's entry carries the reason only when every
+ * failing lane is accepted, so a new failure in an accepted cell still reads as
+ * open work.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  ACCEPTED,
+  acceptedReason,
+  baselineFrom,
+  expandLanes,
+  generateCells,
+  type CellResult,
+} from './value-matrix';
+import { loadBaseline } from './value-matrix-gate';
+
+describe('value matrix: accepted pairs', () => {
+  const [known, ambiguity] = ACCEPTED;
+
+  it('tags a cell whose failing lanes are all accepted', () => {
+    expect(acceptedReason('put|the textContent of #a as Int', ['en', 'es', 'ja'])).toBe(
+      known!.reason
+    );
+    expect(acceptedReason('increment|#a.textContent', ['it', 'it/up'])).toBe(ambiguity!.reason);
+    expect(acceptedReason('increment|#a.textContent', ['it', 'it/up', 'it/eng'])).toBe(
+      ambiguity!.reason
+    );
+  });
+
+  it('leaves it open when one failing lane is not', () => {
+    expect(acceptedReason('increment|#a.textContent', ['it', 'es'])).toBeUndefined();
+    expect(acceptedReason('put|the textContent of #a as Int', ['en', 'es/up'])).toBeUndefined();
+  });
+
+  it('a regenerated baseline carries the reason, and counts the pairs', () => {
+    const result = (lanes: Record<string, string>): CellResult => ({
+      id: 'increment|#a.textContent',
+      want: '7',
+      lanes: { en: '7', es: '7', ...lanes },
+    });
+    const kept = baselineFrom([result({ it: '1', 'it/up': '1' })], '');
+    expect(kept.entries['increment|#a.textContent']?.accepted).toBe(ambiguity!.reason);
+    expect(kept.accepted).toBe(2);
+    const open = baselineFrom([result({ it: '1', es: '1' })], '');
+    expect(open.entries['increment|#a.textContent']?.accepted).toBeUndefined();
+    expect(open.accepted).toBe(0);
+  });
+
+  it('accepts only the cells it names', () => {
+    expect(acceptedReason('put|textContent of #a', ['en'])).toBeUndefined();
+  });
+
+  it('names cells the generator makes, and the baseline lists them as accepted', () => {
+    const ids = new Set(generateCells().map(cell => cell.id));
+    const baseline = loadBaseline();
+    for (const entry of ACCEPTED) {
+      for (const id of entry.cells) {
+        expect(ids.has(id), id).toBe(true);
+        expect(baseline.entries[id]?.accepted, id).toBe(entry.reason);
+        expect(expandLanes(baseline.entries[id]!.lanes).length, id).toBeGreaterThan(0);
+      }
+    }
+  });
+});

package/src/multilingual/value-matrix.assign.test.ts

@@ -0,0 +1,13 @@
+/**
+ * Value matrix gate — the `assign` cells. See value-matrix.ts for the matrix and
+ * value-matrix-gate.ts for the assertions; one position per file so the
+ * shards run in parallel.
+ *
+ * @vitest-environment node
+ * Required, not a preference: under happy-dom the engines bind happy-dom's
+ * DOM constructors, not the jsdom window's (see
+ * shipped-examples-execution.test.ts).
+ */
+import { describeValueMatrixShard } from './value-matrix-gate';
+
+describeValueMatrixShard('assign');

package/src/multilingual/value-matrix.chain-phrases.test.ts

@@ -0,0 +1,13 @@
+/**
+ * Value matrix gate — the `chain` position's operator-phrase cells (`is equal
+ * to`, `includes`, `is an Element`, …). See value-matrix.ts for the matrix
+ * and value-matrix-gate.ts for the assertions.
+ *
+ * @vitest-environment node
+ * Required, not a preference: under happy-dom the engines bind happy-dom's
+ * DOM constructors, not the jsdom window's (see
+ * shipped-examples-execution.test.ts).
+ */
+import { describeValueMatrixShard } from './value-matrix-gate';
+
+describeValueMatrixShard('chain', 'phrases');

package/src/multilingual/value-matrix.chain.test.ts

@@ -0,0 +1,13 @@
+/**
+ * Value matrix gate — the `chain` cells: a `set` value in the second command
+ * of a chain. See value-matrix.ts for the matrix and value-matrix-gate.ts for
+ * the assertions; one position per file so the shards run in parallel.
+ *
+ * @vitest-environment node
+ * Required, not a preference: under happy-dom the engines bind happy-dom's
+ * DOM constructors, not the jsdom window's (see
+ * shipped-examples-execution.test.ts).
+ */
+import { describeValueMatrixShard } from './value-matrix-gate';
+
+describeValueMatrixShard('chain');

package/src/multilingual/value-matrix.count.test.ts

@@ -0,0 +1,13 @@
+/**
+ * Value matrix gate — the `count` cells. See value-matrix.ts for the matrix and
+ * value-matrix-gate.ts for the assertions; one position per file so the
+ * shards run in parallel.
+ *
+ * @vitest-environment node
+ * Required, not a preference: under happy-dom the engines bind happy-dom's
+ * DOM constructors, not the jsdom window's (see
+ * shipped-examples-execution.test.ts).
+ */
+import { describeValueMatrixShard } from './value-matrix-gate';
+
+describeValueMatrixShard('count');

package/src/multilingual/value-matrix.get-phrases.test.ts

@@ -0,0 +1,13 @@
+/**
+ * Value matrix gate — the `get` position's operator-phrase cells (`is equal
+ * to`, `includes`, `is an Element`, …). See value-matrix.ts for the matrix
+ * and value-matrix-gate.ts for the assertions.
+ *
+ * @vitest-environment node
+ * Required, not a preference: under happy-dom the engines bind happy-dom's
+ * DOM constructors, not the jsdom window's (see
+ * shipped-examples-execution.test.ts).
+ */
+import { describeValueMatrixShard } from './value-matrix-gate';
+
+describeValueMatrixShard('get', 'phrases');

package/src/multilingual/value-matrix.get.test.ts

@@ -0,0 +1,13 @@
+/**
+ * Value matrix gate — the `get` cells, what a `get` reads. See value-matrix.ts
+ * for the matrix and value-matrix-gate.ts for the assertions; one position per
+ * file so the shards run in parallel.
+ *
+ * @vitest-environment node
+ * Required, not a preference: under happy-dom the engines bind happy-dom's
+ * DOM constructors, not the jsdom window's (see
+ * shipped-examples-execution.test.ts).
+ */
+import { describeValueMatrixShard } from './value-matrix-gate';
+
+describeValueMatrixShard('get');

package/src/multilingual/value-matrix.if-phrases.test.ts

@@ -0,0 +1,13 @@
+/**
+ * Value matrix gate — the `if` position's operator-phrase cells (`is equal
+ * to`, `includes`, `is an Element`, …). See value-matrix.ts for the matrix
+ * and value-matrix-gate.ts for the assertions.
+ *
+ * @vitest-environment node
+ * Required, not a preference: under happy-dom the engines bind happy-dom's
+ * DOM constructors, not the jsdom window's (see
+ * shipped-examples-execution.test.ts).
+ */
+import { describeValueMatrixShard } from './value-matrix-gate';
+
+describeValueMatrixShard('if', 'phrases');

package/src/multilingual/value-matrix.if.test.ts

@@ -0,0 +1,13 @@
+/**
+ * Value matrix gate — the `if` cells. See value-matrix.ts for the matrix and
+ * value-matrix-gate.ts for the assertions; one position per file so the
+ * shards run in parallel.
+ *
+ * @vitest-environment node
+ * Required, not a preference: under happy-dom the engines bind happy-dom's
+ * DOM constructors, not the jsdom window's (see
+ * shipped-examples-execution.test.ts).
+ */
+import { describeValueMatrixShard } from './value-matrix-gate';
+
+describeValueMatrixShard('if');

package/src/multilingual/value-matrix.increment.test.ts

@@ -0,0 +1,13 @@
+/**
+ * Value matrix gate — the `increment` cells. See value-matrix.ts for the matrix and
+ * value-matrix-gate.ts for the assertions; one position per file so the
+ * shards run in parallel.
+ *
+ * @vitest-environment node
+ * Required, not a preference: under happy-dom the engines bind happy-dom's
+ * DOM constructors, not the jsdom window's (see
+ * shipped-examples-execution.test.ts).
+ */
+import { describeValueMatrixShard } from './value-matrix-gate';
+
+describeValueMatrixShard('increment');

package/src/multilingual/value-matrix.isolation.test.ts

@@ -0,0 +1,57 @@
+/**
+ * The value matrix runs every (cell, lane) pair in one process, so no run may
+ * see another's writes. Two ways one did:
+ *   - hyperfixi keeps global variables in a Map that every context shares, so
+ *     one lane's `increment n` made every later run read `n` as 7, core's own
+ *     English included;
+ *   - a lane can remove the body (tr read `increment i by 2 * 2` as
+ *     `increment *`), and the next run's reset then threw.
+ *
+ * One set of engines for the file: the engines bind the window they are first
+ * loaded with, so a second initMatrixEngines() would run on a stale document.
+ *
+ * @vitest-environment node
+ * Required, not a preference: see value-matrix.put.test.ts.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { initMatrixEngines, type MatrixCell, type MatrixEngines } from './value-matrix';
+
+const cell = (id: string, source: string): MatrixCell => ({
+  id,
+  position: 'put',
+  group: 'operand',
+  source,
+});
+
+const read = cell('reads', 'on click put n into #out');
+
+describe('value matrix: runs are isolated', () => {
+  let engines: MatrixEngines;
+  beforeAll(async () => {
+    engines = await initMatrixEngines();
+  }, 120_000);
+  afterAll(async () => {
+    await engines.close();
+  });
+
+  it('a global one run writes is gone in the next', async () => {
+    const before = await engines.runCell(read);
+    // A cell whose oracle writes nothing runs no lane, so this one puts.
+    const writes = await engines.runCell(
+      cell('writes', 'on click increment n then put n into #out')
+    );
+    const after = await engines.runCell(read);
+    expect(writes.lanes.en).toBe('7');
+    expect(before.want).toBe('6');
+    expect(before.lanes.en).toBe('6');
+    expect(after.lanes).toEqual(before.lanes);
+  }, 120_000);
+
+  it('a run that removes the body leaves the next its fixture', async () => {
+    const before = await engines.runCell(read);
+    await engines.runCell(cell('removes', 'on click remove document.body'));
+    const after = await engines.runCell(read);
+    expect(before.lanes.en).toBe('6');
+    expect(after.lanes).toEqual(before.lanes);
+  }, 120_000);
+});

package/src/multilingual/value-matrix.names.test.ts

@@ -0,0 +1,62 @@
+/**
+ * The value matrix's colliding names (collidingNames in value-matrix.ts). The
+ * list is derived, so these pin what each source puts in and what each rule
+ * leaves out; the matrix shards run the names themselves.
+ */
+import { describe, it, expect } from 'vitest';
+import { collidingNames, generateCells } from './value-matrix';
+
+const names = new Map(collidingNames().map(entry => [entry.name, entry]));
+
+describe('value matrix: colliding names', () => {
+  it('takes a word a tokenizer reads as structure', () => {
+    expect(names.has('a')).toBe(true); // es, it, pt `to`; a tr particle
+    expect(names.has('y')).toBe(true); // es `and`
+    expect(names.has('wo')).toBe(true); // de `where`
+  });
+
+  it('takes a longer name as code writes it, which a tokenizer splits', () => {
+    expect(names.get('userData')?.pronounIn).toEqual([]); // qu `userDa` + `ta`
+  });
+
+  it('takes a schema marker the tokenizer leaves an identifier', () => {
+    expect(names.has('um')).toBe(true); // de `increment … by`
+  });
+
+  it('leaves out English keywords, but not the articles', () => {
+    expect(names.has('in')).toBe(false);
+    expect(names.has('on')).toBe(false);
+    expect(names.has('an')).toBe(true);
+  });
+
+  it("leaves out upstream's `no` and the templates' variables", () => {
+    expect(names.has('no')).toBe(false);
+    expect(names.has('i')).toBe(false);
+  });
+
+  it('leaves out a name that only ever collides with a pronoun', () => {
+    expect(names.has('eu')).toBe(false); // pt `me`
+    expect(names.has('io')).toBe(false); // it `me`
+  });
+
+  it("keeps a name that is a pronoun elsewhere, without that language's lanes", () => {
+    expect(names.get('o')?.pronounIn).toEqual(['tr']); // es and it `or`; tr `it`
+    expect(names.get('es')?.pronounIn).toEqual(['de']); // es `is`; de `it`
+    const cells = generateCells().filter(cell => cell.name === 'o');
+    expect(cells.map(cell => `${cell.position}|${cell.expression}`)).toEqual([
+      'put|o',
+      'set|o',
+      'if|o',
+      'increment|o',
+      'chain|o',
+      'get|o',
+      'assign|o',
+      'count|o',
+      'put|o + 1',
+      'set|1 + o',
+      'if|o < 3',
+      'if|not o',
+    ]);
+    expect(cells.every(cell => cell.skip?.join() === 'tr')).toBe(true);
+  });
+});

package/src/multilingual/value-matrix.put-phrases.test.ts

@@ -0,0 +1,13 @@
+/**
+ * Value matrix gate — the `put` position's operator-phrase cells (`is equal
+ * to`, `includes`, `is an Element`, …). See value-matrix.ts for the matrix
+ * and value-matrix-gate.ts for the assertions.
+ *
+ * @vitest-environment node
+ * Required, not a preference: under happy-dom the engines bind happy-dom's
+ * DOM constructors, not the jsdom window's (see
+ * shipped-examples-execution.test.ts).
+ */
+import { describeValueMatrixShard } from './value-matrix-gate';
+
+describeValueMatrixShard('put', 'phrases');

package/src/multilingual/value-matrix.put.test.ts

@@ -0,0 +1,13 @@
+/**
+ * Value matrix gate — the `put` cells. See value-matrix.ts for the matrix and
+ * value-matrix-gate.ts for the assertions; one position per file so the
+ * shards run in parallel.
+ *
+ * @vitest-environment node
+ * Required, not a preference: under happy-dom the engines bind happy-dom's
+ * DOM constructors, not the jsdom window's (see
+ * shipped-examples-execution.test.ts).
+ */
+import { describeValueMatrixShard } from './value-matrix-gate';
+
+describeValueMatrixShard('put');

package/src/multilingual/value-matrix.set-phrases.test.ts

@@ -0,0 +1,13 @@
+/**
+ * Value matrix gate — the `set` position's operator-phrase cells (`is equal
+ * to`, `includes`, `is an Element`, …). See value-matrix.ts for the matrix
+ * and value-matrix-gate.ts for the assertions.
+ *
+ * @vitest-environment node
+ * Required, not a preference: under happy-dom the engines bind happy-dom's
+ * DOM constructors, not the jsdom window's (see
+ * shipped-examples-execution.test.ts).
+ */
+import { describeValueMatrixShard } from './value-matrix-gate';
+
+describeValueMatrixShard('set', 'phrases');

package/src/multilingual/value-matrix.set.test.ts

@@ -0,0 +1,13 @@
+/**
+ * Value matrix gate — the `set` cells. See value-matrix.ts for the matrix and
+ * value-matrix-gate.ts for the assertions; one position per file so the
+ * shards run in parallel.
+ *
+ * @vitest-environment node
+ * Required, not a preference: under happy-dom the engines bind happy-dom's
+ * DOM constructors, not the jsdom window's (see
+ * shipped-examples-execution.test.ts).
+ */
+import { describeValueMatrixShard } from './value-matrix-gate';
+
+describeValueMatrixShard('set');

package/src/multilingual/value-matrix.times.test.ts

@@ -0,0 +1,13 @@
+/**
+ * Value matrix gate — the `times` cells, a loop's count. See value-matrix.ts
+ * for the matrix and value-matrix-gate.ts for the assertions; one position per
+ * file so the shards run in parallel.
+ *
+ * @vitest-environment node
+ * Required, not a preference: under happy-dom the engines bind happy-dom's
+ * DOM constructors, not the jsdom window's (see
+ * shipped-examples-execution.test.ts).
+ */
+import { describeValueMatrixShard } from './value-matrix-gate';
+
+describeValueMatrixShard('times');