@hyperfixi/testing-framework 4.3.0 → 4.4.0

package/CHANGELOG.md

@@ -7,6 +7,67 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.4.0] - 2026-10-10
+
+Translations now read as their language. In 4.3.0, 19% of the corpus's translations and 24% of the
+command-shape scripts' translations kept at least one English word, and a third of the corpus kept an
+English event name. Counting only the English a recorded decision does not keep (type names, `url`,
+`debounced at`, …), every one of the 23 languages is now at or under 5% of corpus renders (0.7–4.6%)
+and 10% of command-shape renders (3.9–6.2%), and no translation writes an English event name its
+language has a word for. The words are the owner's vocabulary sheet
+(`docs-internal/multilingual/VOCABULARY_SHEET.md`), decided 2026-10-08.
+
+### Added
+
+- **`@hyperfixi/testing-framework`: the English left in a translation is gated.** `english-leaks.ts`
+  counts, per render, the English grammar words (the tokens the engine's own parser matched in the
+  source), English event names the language's lexicon has a word for, and a nominative `me` beside a
+  marker in the 13 languages where that case is wrong. Two shrink-only baselines (the corpus, in
+  `test:canonical`, and the command-shape cases, in their shards); `tools/regen-english-leaks-baseline.ts
+  --report` prints each language against M2's targets. An English alternative a profile keeps for
+  code-switched input, beside a primary that is the language's own, counts as English.
+- **`@lokascript/semantic`: `transition … from … to`** reads and writes in every language (a `source`
+  role), and the bare command reads in English. The schema's `destination` role is gone: upstream has
+  none, and SOV destination markers read an owned property's owner as an element (tr and qu swapped
+  `#foo's *width` silently). English writes `using` for an easing.
+- **`@lokascript/semantic`: `add/remove/hide/show … when <condition>`** in every language, through a
+  `condition` role marked with each profile's `when`. It was English in every translation, and refused
+  as a bare command.
+
+### Changed
+
+- **`@lokascript/semantic` writes each language's own words** for: loop heads (`repeat for x in`,
+  `while`, `until`; es `repetir para x en .items`), `I match` / `I am` (written as the third person, and
+  back in English as upstream's first person), `does not match`, `fetch … do not throw`, `on first`,
+  `go back`, `from elsewhere`, a loop's `index`, `start view transition`, a query's `in`, a conversion's
+  `as` (the type name stays English), `the X of Y` inside an expression (es `valor de #price`, ja
+  `#priceの値`), `catch` and `finally`, `element x`, and `def` (as the noun "function", es `función
+  greet(name)`). bn, th and vi have their own `document` and `window`; he has its own words for all of
+  these and for `matches`, `exists`, `or`, `not`, `first`, `next`, `previous`, `closest`, `empty`, `is`,
+  `document` and `window`; and the 15 languages that wrote English `forever` have their own (es
+  `repetir siempre`, de `endlos`, ja `ずっと`). Every reader still takes the English words. Where a word
+  would read back as another (es `en` is also a marker), the translation keeps English's.
+- **`@lokascript/semantic` writes native event names** in he, hi, it, pl, qu, ru, th, uk and vi where
+  the lexicon's word reads back; the rest are denylisted with their reasons.
+- **`@lokascript/semantic`: a foreign `put X at start of Y` is written with the language's `prepend`**,
+  which English writes back as `put … at start of`.
+
+### Fixed
+
+- **`@lokascript/semantic` reads `me` after a marker in the case the marker takes**, as authors write it:
+  de `zu mir`, pt `a mim`, pl `do mnie`, ru `ко мне`, uk `до мене`, hi `मुझ में`. Each was read as a
+  variable (`zu mir` ran as `to mir`) or refused. Translations still write the nominative.
+
+- **`@lokascript/semantic`: `put X at start of Y` translates.** It was refused in all 23 languages: no
+  language but English had a pattern for it, and the render wrote `at end of` in its place.
+- **`@lokascript/semantic`: a one-line handler's `put … at end of`** translates in es, id, it, pt, tl and
+  uk. The fused handler pattern took the end noun for the destination wherever the language's `at` word
+  is also a destination marker.
+- **`@lokascript/semantic`: `^x is …` keeps its copula** in ar, hi and th, which read the `is` word after a
+  `^` variable as the pronoun `it`.
+- **`@lokascript/semantic`: an SOV loop body may open with a variable named `index`** (ja `index を …`),
+  and `repeat` is never read as an event name.
+
 ## [4.3.0] - 2026-10-07
 
 More of what upstream reads now translates, and what does not is refused instead of lost. On the
@@ -1485,7 +1546,9 @@ _Synchronized version release. See git history for details._
 - npm access token stored in GitHub Secrets
 - 2FA recommended for npm organization
 
-[Unreleased]: https://github.com/codetalcott/hyperfixi/compare/v4.2.0...HEAD
+[Unreleased]: https://github.com/codetalcott/hyperfixi/compare/v4.4.0...HEAD
+[4.4.0]: https://github.com/codetalcott/hyperfixi/compare/v4.3.0...v4.4.0
+[4.3.0]: https://github.com/codetalcott/hyperfixi/compare/v4.2.0...v4.3.0
 [4.2.0]: https://github.com/codetalcott/hyperfixi/compare/v4.1.0...v4.2.0
 [4.1.0]: https://github.com/codetalcott/hyperfixi/compare/v4.0.1...v4.1.0
 [4.0.1]: https://github.com/codetalcott/hyperfixi/compare/v4.0.0...v4.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperfixi/testing-framework",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "Cross-platform behavior testing suite for LokaScript applications",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -40,7 +40,7 @@
     "analyze-failures": "tsx src/multilingual/tools/analyze-failures.ts",
     "typecheck": "tsc --noEmit",
     "test:check": "VITEST_TIMEOUT=240 VITEST_QUIET=1 bash ../../scripts/vitest-run.sh --reporter=dot",
-    "test:canonical": "FOREIGN_CANONICAL_VALIDITY=1 VITEST_TIMEOUT=300 bash ../../scripts/vitest-run.sh --reporter=dot src/multilingual/canonical-validity.test.ts src/multilingual/foreign-canonical-validity.test.ts src/multilingual/render-fidelity.test.ts src/multilingual/bare-render-fidelity.test.ts src/multilingual/en-reference-preservation.test.ts",
+    "test:canonical": "FOREIGN_CANONICAL_VALIDITY=1 VITEST_TIMEOUT=300 bash ../../scripts/vitest-run.sh --reporter=dot src/multilingual/canonical-validity.test.ts src/multilingual/foreign-canonical-validity.test.ts src/multilingual/render-fidelity.test.ts src/multilingual/bare-render-fidelity.test.ts src/multilingual/en-reference-preservation.test.ts src/multilingual/english-leaks.corpus.test.ts",
     "test:shipped-sources": "VITEST_TIMEOUT=300 bash ../../scripts/vitest-run.sh --reporter=dot src/multilingual/shipped-sources-engine.test.ts src/multilingual/shipped-sources-localized.test.ts src/multilingual/shipped-examples-execution.test.ts"
   },
   "keywords": [
@@ -57,10 +57,10 @@
   "author": "LokaScript Contributors",
   "license": "MIT",
   "dependencies": {
-    "@hyperfixi/patterns-reference": "^4.3.0",
-    "@lokascript/compilation-service": "^4.3.0",
-    "@lokascript/i18n": "^4.3.0",
-    "@lokascript/semantic": "^4.3.0",
+    "@hyperfixi/patterns-reference": "^4.4.0",
+    "@lokascript/compilation-service": "^4.4.0",
+    "@lokascript/i18n": "^4.4.0",
+    "@lokascript/semantic": "^4.4.0",
     "diff": "^8.0.3",
     "esbuild": "^0.25.12",
     "happy-dom": "^20.14.5",
@@ -72,8 +72,8 @@
     "vite": "^8.3.1"
   },
   "devDependencies": {
-    "@hyperfixi/engine": "^4.3.0",
-    "@lokascript/hyperscript-adapter": "^4.3.0",
+    "@hyperfixi/engine": "^4.4.0",
+    "@lokascript/hyperscript-adapter": "^4.4.0",
     "@types/diff": "^5.0.0",
     "@types/node": "^26.6.3",
     "@vitest/coverage-v8": "^5.0.0",

package/src/multilingual/README.md

@@ -294,6 +294,38 @@ npx tsx tools/regen-value-matrix-baseline.ts --dry-run --results /tmp/matrix.jso
 A lane that fails in `en-rt` fails in nearly every translation: semantic's English
 parse lost the value, and every translation is rendered from it. Fix that first.
 
+## English left in a translation
+
+Every gate above asks whether a translation means what the source means; none asks
+whether it reads as the language. `english-leaks.ts` counts, in each render, three kinds
+of finding:
+
+| Finding        | What it is                                                                                |
+| -------------- | ----------------------------------------------------------------------------------------- |
+| `<word>`       | an English word the engine reads as grammar in the source, written in English             |
+| `event:<name>` | an English event name where the language's lexicon has a word and the renderer may use it |
+| `case:me`      | the nominative `me` beside a role marker, in the 13 languages where that form is wrong    |
+
+"Grammar" is derived per source: the tokens the engine's own parser matched as words, plus
+the references in its parse. A word the language spells the same (es `a`, de `in`) and a
+name spelled like a keyword are never counted; strings, `js` blocks and brace interiors
+are not read. The report splits each word by context (`clause`: in a clause semantic keeps
+as written; `bracket`, `call`, `property`, `plain`) and by whether the language has its own
+word for it.
+
+Two halves, each with a shrink-only baseline: `baselines/english-leaks.corpus.json` (every
+non-markup corpus row, `render(parse(en), L)`; in `test:canonical`, after `populate`) and
+`baselines/english-leaks.shapes.json` (the renders the command-shape shards already make).
+
+```bash
+# The burn-down: per language, per word (with contexts), per event
+npx tsx tools/regen-english-leaks-baseline.ts --report
+
+# After a fix: prune the findings that are gone (refuses to add new ones)
+npx tsx tools/regen-english-leaks-baseline.ts            # both halves (corpus needs a fresh populate)
+npx tsx tools/regen-english-leaks-baseline.ts --shapes   # one half
+```
+
 ## Direct-path shapes on the text path
 
 Core's `src/multilingual/*-direct-path.test.ts` files pin shapes core's direct path ran

package/src/multilingual/command-shapes-gate.ts

@@ -13,6 +13,10 @@
  *
  * The cases file, the baseline's own consistency and the oracle are checked
  * in command-shapes.cases.test.ts and command-shapes.oracle.test.ts.
+ *
+ * Each shard also judges the English left in its renders (english-leaks.ts),
+ * against baselines/english-leaks.shapes.json: the same renders, a second
+ * question, so the gate costs no second translation pass.
  */
 
 import { readFileSync } from 'node:fs';
@@ -27,6 +31,16 @@ import {
   type CommandShapesBaseline,
   type PairChange,
 } from './command-shapes';
+import {
+  diffLeakBaseline,
+  gainedLeaks,
+  prunableLeaks,
+  initLeakScanner,
+  loadLeakBaseline,
+  shapeLeaks,
+  type LeakChange,
+  type LeakResults,
+} from './english-leaks';
 
 export const COMMAND_SHAPE_SHARDS = 3;
 
@@ -47,11 +61,16 @@ export function describeCommandShapesShard(shard: number): void {
     `${c.id} [${c.lane}] ${c.listed} → ${c.got}: ${sources.get(c.id)?.slice(0, 80)}` +
     (c.detail ? ` ⇒ ${JSON.stringify(collapse(c.detail).slice(0, 80))}` : '');
 
+  const leakLine = (c: LeakChange, words: string[]): string =>
+    `${c.id} [${c.language}] ${words.join(' ')}: ${sources.get(c.id)?.slice(0, 80)}`;
+
   describe(`command shapes [${shard + 1}/${COMMAND_SHAPE_SHARDS}]`, () => {
     let results: CaseResult[] = [];
+    let leaks: LeakResults = new Map();
 
     beforeAll(async () => {
       results = await runCommandShapes(own);
+      leaks = shapeLeaks(await initLeakScanner(), results, own);
       const pairs = results.reduce((n, r) => n + Object.keys(r.lanes).length, 0);
       const failing = results.reduce(
         (n, r) => n + Object.values(r.lanes).filter(l => l.outcome !== 'pass').length,
@@ -72,5 +91,18 @@ export function describeCommandShapesShard(shard: number): void {
       const { better } = diffBaseline(results, loadCommandShapesBaseline());
       expect(capped(better.map(line))).toEqual([]);
     });
+
+    it('no render holds English the leak baseline does not list (english-leaks.ts)', () => {
+      expect(leaks.size).toBeGreaterThan(300);
+      const gained = gainedLeaks(diffLeakBaseline(leaks, loadLeakBaseline('shapes')));
+      expect(capped(gained.map(c => leakLine(c, c.added)))).toEqual([]);
+    });
+
+    it('no listed English is gone, nor a listed refusal rendering now (prune with tools/regen-english-leaks-baseline.ts --shapes)', () => {
+      const prune = prunableLeaks(diffLeakBaseline(leaks, loadLeakBaseline('shapes')));
+      expect(capped(prune.map(c => leakLine(c, c.newRender ? ['now renders'] : c.gone)))).toEqual(
+        []
+      );
+    });
   });
 }

package/src/multilingual/command-shapes.ts

@@ -111,6 +111,8 @@ export interface LaneResult {
   /** The lane's English (a silent lane), or the error's first line (a refused one). */
   detail?: string;
   kind?: SilentKind;
+  /** The language's render (`translate(src, 'en', L)`), when there was one: what english-leaks.ts reads. */
+  rendered?: string;
 }
 
 export interface CaseResult {
@@ -497,11 +499,6 @@ export async function initCommandShapes(): Promise<CommandShapeRunner> {
   const readers = await loadEngineReaders();
   const { translate } = (await import('@lokascript/semantic')) as { translate: Translate };
 
-  const lane = (source: string, language: string): string =>
-    language === 'en'
-      ? translate(source, 'en', 'en')
-      : translate(translate(source, 'en', language), language, 'en');
-
   return {
     runCase(shape, lanes = LANES) {
       const engine = readers[readerOf(shape)];
@@ -516,14 +513,26 @@ export async function initCommandShapes(): Promise<CommandShapeRunner> {
         lanes: {},
       };
       for (const language of lanes) {
+        let rendered: string | undefined;
         let english: string;
         try {
-          english = lane(shape.source, language);
+          if (language === 'en') english = translate(shape.source, 'en', 'en');
+          else {
+            rendered = translate(shape.source, 'en', language);
+            english = translate(rendered, language, 'en');
+          }
         } catch (e) {
-          result.lanes[language] = { outcome: 'refused', detail: firstLine(e) };
+          result.lanes[language] = {
+            outcome: 'refused',
+            detail: firstLine(e),
+            ...(rendered !== undefined ? { rendered } : {}),
+          };
           continue;
         }
-        result.lanes[language] = judge(engine, want, wantPlain, english);
+        result.lanes[language] = {
+          ...judge(engine, want, wantPlain, english),
+          ...(rendered !== undefined ? { rendered } : {}),
+        };
       }
       return result;
     },
@@ -718,9 +727,8 @@ export const SILENT_FAMILIES: readonly SilentFamily[] = [
   {
     name: 'value-words',
     reason:
-      "a language's word inside a value reads back as another English word: `is not` → " +
-      '`it not` (ar/hi/ms/pl/th), pl `to` → `it`, qu `where` → `target`, ms/pl `undefined`, ' +
-      'ms `it` → `its`',
+      "a language's word inside a value reads back as another English word: pl `to` → " +
+      '`it`, qu `where` → `target`, ms/pl `undefined`',
     ids: [
       'a30e7d6174',
       '69537d01ae',
@@ -728,7 +736,6 @@ export const SILENT_FAMILIES: readonly SilentFamily[] = [
       'da24c9d768',
       'b948ed872b',
       'a4c56acf1e',
-      '87250fbc5e',
       '54a65f4602',
     ],
   },
@@ -741,8 +748,8 @@ export const SILENT_FAMILIES: readonly SilentFamily[] = [
     name: 'possessive-split',
     reason:
       "a possessive reads back split or reworded: qu `$data 's inner' s val`, id `my` → " +
-      "`me punya`, qu `#box's *opacity` → `#box … on *opacity`",
-    ids: ['76130fbf7d', '36e2294330', 'b839394853', '7bc08adb98'],
+      '`me punya`',
+    ids: ['76130fbf7d', '36e2294330', 'b839394853'],
   },
 ];
 

package/src/multilingual/english-leaks.corpus.test.ts

@@ -0,0 +1,74 @@
+/**
+ * The English-leak gate, corpus half (see english-leaks.ts): every non-markup
+ * corpus row rendered into each language as `populate` writes it, judged
+ * against baselines/english-leaks.corpus.json. Fails on a finding a pair did
+ * not have, and on a listed one that is gone (prune with
+ * tools/regen-english-leaks-baseline.ts --corpus), so the list only shrinks.
+ *
+ * Needs FOREIGN_CANONICAL_VALIDITY=1 and a freshly populated patterns.db: the
+ * SET of rows depends on `populate`, the same contract the other corpus gates
+ * carry (`npm run test:canonical`).
+ *
+ * @vitest-environment node
+ */
+import { describe, it, expect, beforeAll } from 'vitest';
+import { getAllPatterns } from '@hyperfixi/patterns-reference';
+import {
+  corpusLeaks,
+  diffLeakBaseline,
+  gainedLeaks,
+  prunableLeaks,
+  initLeakScanner,
+  loadLeakBaseline,
+  type LeakResults,
+} from './english-leaks';
+
+const DB_FRESHLY_POPULATED = process.env.FOREIGN_CANONICAL_VALIDITY === '1';
+
+/** 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`];
+}
+
+describe.skipIf(!DB_FRESHLY_POPULATED)('english-leaks: corpus renders', () => {
+  let results: LeakResults = new Map();
+  let skipped: string[] = [];
+  const sources = new Map<string, string>();
+
+  beforeAll(async () => {
+    const rows = await getAllPatterns({ limit: 5000 });
+    for (const row of rows) sources.set(row.id, row.rawCode.replace(/\s+/g, ' ').trim());
+    ({ results, skipped } = await corpusLeaks(await initLeakScanner(), rows));
+  }, 300_000);
+
+  it('scores the corpus (sanity: guards a false green)', () => {
+    expect(results.size).toBeGreaterThan(140);
+    // Rows the engine rejects have no grammar to read (worker, socket, eventsource, …).
+    expect(skipped.length).toBeLessThan(10);
+  });
+
+  it('no render holds English the baseline does not list', () => {
+    const gained = gainedLeaks(diffLeakBaseline(results, loadLeakBaseline('corpus')));
+    expect(
+      capped(
+        gained.map(
+          c => `${c.id} [${c.language}] ${c.added.join(' ')}: ${sources.get(c.id)?.slice(0, 80)}`
+        )
+      )
+    ).toEqual([]);
+  });
+
+  it('no listed English is gone (prune it with tools/regen-english-leaks-baseline.ts --corpus)', () => {
+    const prune = prunableLeaks(diffLeakBaseline(results, loadLeakBaseline('corpus')));
+    expect(
+      capped(
+        prune.map(c => `${c.id} [${c.language}] ${c.newRender ? 'now renders' : c.gone.join(' ')}`)
+      )
+    ).toEqual([]);
+  });
+
+  it('keeps no entry for a row the corpus no longer holds', () => {
+    const stale = Object.keys(loadLeakBaseline('corpus').entries).filter(id => !results.has(id));
+    expect(stale).toEqual([]);
+  });
+});