@hyperfixi/testing-framework 3.3.0 → 4.0.1

package/src/multilingual/shipped-sources-validity.ts

@@ -1,30 +1,24 @@
 /**
- * Shipped-sources validity gate
- * -----------------------------
- * Every hyperscript source we ship in `examples/` and the doc trees, parsed
- * with hyperfixi, must not land in the *recovers-with-errors* state:
- * `ok === true` with a non-empty `errors`.
+ * Shipped sources: the hyperscript this repository ships to users
+ * ----------------------------------------------------------------
+ * Collects every hyperscript source in `examples/` and the doc trees, for the
+ * gates that read them:
  *
- * That state is the blind spot this gate exists for. The parser is
- * deliberately resilient — it recovers from some malformed input and returns a
- * usable-but-degraded AST plus diagnostics — so genuinely broken sources
- * neither throw nor report `ok: false`. Nothing in the existing suites looks at
- * the combination, which is how five malformed examples shipped undetected
- * (an `if` with no `end`, a `put` with no target, `{id}` where `${id}` was
- * meant, and a `*--css-var` neither engine supports). The same sweep is what
- * caught the `send`-vs-`trigger` divergence and the `parseTriggerCommand` hang
- * in #780, neither of which was reachable from the existing tests.
+ * - `shipped-sources-engine.test.ts`: every English source must parse on
+ *   `@hyperfixi/engine`, or be listed with a reason (`checkShippedSourcesOnEngine`);
+ * - `shipped-sources-localized.test.ts`: every source written in another
+ *   language must translate to English both engines parse (`collectLocalizedSources`);
+ * - the R4-style second opinion, upstream `hyperscript.org`, is
+ *   `loadCanonicalParser()` in canonical-validity.ts.
  *
- * Deliberately NOT gated: `ok === false`. That is a much larger and mostly
- * legitimate class — non-English sources (which need the multilingual path,
- * not `compileSync`), plugin syntax whose feature is not installed, and
- * intentionally-broken "this does not work" doc snippets. Gating it would
- * drown the signal. A source that fails outright is also loud; one that
- * silently recovers is not, and that asymmetry is the whole point.
+ * (The file is named for the gate it began with: core's "recovers with
+ * errors" ratchet, which flagged sources `@hyperfixi/core`'s resilient parser
+ * accepted with diagnostics — how five malformed examples were found, and the
+ * `send`-vs-`trigger` divergence and `parseTriggerCommand` hang of #780. It left
+ * with core's parser in Phase C4; the engine has no recovering mode, so a
+ * malformed source is simply rejected, and the engine gate sees it.)
  *
- * Node-only: the second-opinion path needs `loadCanonicalParser()`, which
- * imports the real `hyperscript.org` build off disk. Cannot run in a browser
- * suite.
+ * Node-only: walks the repo and reads git's index.
  */
 
 import fs from 'node:fs';
@@ -32,6 +26,7 @@ import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
+import { JSDOM } from 'jsdom';
 import { extractHyperscriptFromMarkup } from '@hyperfixi/patterns-reference';
 
 /** Repo root, from `packages/testing-framework/src/multilingual/`. */
@@ -60,30 +55,6 @@ export interface ShippedSource {
   source: string;
 }
 
-export interface ShippedSourceFinding extends ShippedSource {
-  /** Stable allowlist key: file plus a hash of the source. */
-  key: string;
-  /** First hyperfixi diagnostic. */
-  error: string;
-  /** Single-line excerpt, for reading the baseline without opening the file. */
-  excerpt: string;
-}
-
-export interface ShippedSourcesResult {
-  /** Sources extracted and compiled. */
-  checked: number;
-  /** Sources that compiled with no diagnostics. */
-  clean: number;
-  /** Sources in the recovers-with-errors state. */
-  findings: ShippedSourceFinding[];
-}
-
-/** Minimal shape of `hyperscript.compileSync`, injected so this stays testable. */
-export type CompileForValidity = (code: string) => {
-  ok: boolean;
-  errors?: Array<{ message: string }>;
-};
-
 /**
  * A stable key for an individual snippet.
  *
@@ -99,7 +70,7 @@ function keyFor(file: string, source: string): string {
 /**
  * The files git actually tracks under `repoRoot`, as absolute paths.
  *
- * This gate walks the working TREE, and a working tree is not a clean checkout:
+ * These gates walk the working TREE, and a working tree is not a clean checkout:
  * `examples/vite-plugin-multilingual/` is GITIGNORED, so a local run saw a
  * source CI could never see. That is unfixable from the allowlist — with an
  * entry for it the gate failed in CI as a STALE entry, and without one it
@@ -196,45 +167,58 @@ export function collectShippedSources(
   return out;
 }
 
+/** A shipped source written in another language: an `_` under a non-English `lang`. */
+export interface LocalizedSource extends ShippedSource {
+  /** The base language of the closest `lang` (`es` for `es-MX`). */
+  lang: string;
+}
+
 /**
- * Compile every shipped source and report the ones that recovered with errors.
+ * The shipped `_` attributes written in a language other than English. The
+ * other collectors hand every source to an English parser, which rejects
+ * these, so both shipped-sources gates skip them; on a page they run through
+ * the multilingual adapter, which translates a script under its element's
+ * `lang`. Pages are parsed as documents here, so a `lang` on `<html>` counts.
  */
-export function checkShippedSourcesValidity(
-  compile: CompileForValidity,
-  doc: Parameters<typeof extractHyperscriptFromMarkup>[0],
-  opts?: { roots?: string[]; repoRoot?: string }
-): ShippedSourcesResult {
-  const sources = collectShippedSources(doc, opts);
-  const findings: ShippedSourceFinding[] = [];
-  let clean = 0;
-
-  for (const s of sources) {
-    let result: ReturnType<CompileForValidity>;
-    try {
-      result = compile(s.source);
-    } catch {
-      // A throw is the loud failure mode, not this gate's business.
-      continue;
-    }
-    const errors = result.errors ?? [];
-    if (result.ok && errors.length > 0) {
-      findings.push({
-        ...s,
-        key: keyFor(s.file, s.source),
-        error: errors[0]?.message ?? 'recovered with errors',
-        excerpt: s.source.replace(/\s+/g, ' ').trim().slice(0, 100),
-      });
-    } else if (result.ok) {
-      clean++;
+export function collectLocalizedSources(opts?: {
+  roots?: string[];
+  repoRoot?: string;
+}): LocalizedSource[] {
+  const repoRoot = opts?.repoRoot ?? REPO_ROOT;
+  const roots = opts?.roots ?? DEFAULT_ROOTS;
+  const out: LocalizedSource[] = [];
+  const tracked = trackedFiles(repoRoot);
+  for (const root of roots) {
+    for (const full of walk(path.join(repoRoot, root), [], tracked)) {
+      const rel = path.relative(repoRoot, full);
+      if (EXCLUDED.some(e => e.match(rel))) continue;
+      const text = fs.readFileSync(full, 'utf8');
+      const kind: ShippedSource['kind'] = full.endsWith('.html')
+        ? 'html-attribute'
+        : 'markdown-html-block';
+      const parts =
+        kind === 'html-attribute'
+          ? [text]
+          : [...text.matchAll(/```html\n([\s\S]*?)```/g)].map(m => m[1] ?? '');
+      for (const html of parts) {
+        const { window } = new JSDOM(html);
+        const elements: Element[] = Array.from(window.document.querySelectorAll('[_]'));
+        for (const el of elements) {
+          const source = el.getAttribute('_') ?? '';
+          const lang = (el.closest('[lang]')?.getAttribute('lang') ?? '').split('-')[0];
+          if (!source.trim() || !lang || lang.toLowerCase() === 'en') continue;
+          out.push({ file: rel, kind, source, lang: lang.toLowerCase() });
+        }
+        window.close();
+      }
     }
   }
-
-  return { checked: sources.length, clean, findings };
+  return out;
 }
 
-/** A shipped source `packages/core` compiles clean and `@hyperfixi/engine` rejects. */
+/** A shipped English source `@hyperfixi/engine` rejects. */
 export interface EngineRejection extends ShippedSource {
-  /** Stable key: file plus a hash of the source, as the validity gate's. */
+  /** Stable key: file plus a hash of the source. */
   key: string;
   /** The engine's first parse error, first line. */
   error: string;
@@ -242,46 +226,50 @@ export interface EngineRejection extends ShippedSource {
 }
 
 export interface ShippedSourcesOnEngineResult {
-  /** Distinct (file, source) pairs core compiles clean. */
-  coreClean: number;
+  /** Distinct (file, source) pairs written in English: the denominator. */
+  checked: number;
   /** Of those, the ones the engine parses. */
   engineAccepts: number;
+  /** Distinct sources skipped because they are written in another language. */
+  localized: number;
   rejections: EngineRejection[];
 }
 
 /**
- * What replacing core's engine with `@hyperfixi/engine` would break in the
- * material we ship: every source core compiles clean, put to the engine's
- * parser. `engineErrors` returns the engine's parse errors ([] = it parses).
+ * Every shipped source written in English, put to the engine's parser.
+ * `engineErrors` returns the engine's parse errors ([] = it parses).
+ *
+ * A source under a non-English `lang` is not English hyperscript: on a page it
+ * runs through the multilingual adapter, and `shipped-sources-localized.test.ts`
+ * checks it that way. Every other source must parse, or be listed.
  *
- * The denominator is core-clean sources on purpose. A source core itself
- * rejects or recovers from is already broken where it is shipped, and is the
- * validity gate's business; the question here is only what would STOP working.
+ * (Until Phase C4 the denominator was the sources `@hyperfixi/core` compiled
+ * clean, which also excluded non-English snippets that carried no `lang` and
+ * malformed doc examples. Moving off core surfaced fourteen: eleven examples in
+ * another language without a `lang`, now marked, and three malformed ones, now
+ * fixed.)
  */
 export function checkShippedSourcesOnEngine(
-  compile: CompileForValidity,
   engineErrors: (code: string) => string[],
   doc: Parameters<typeof extractHyperscriptFromMarkup>[0],
   opts?: { roots?: string[]; repoRoot?: string }
 ): ShippedSourcesOnEngineResult {
+  const foreign = new Set(collectLocalizedSources(opts).map(s => keyFor(s.file, s.source)));
   const seen = new Set<string>();
   const rejections: EngineRejection[] = [];
-  let coreClean = 0;
+  let checked = 0;
   let engineAccepts = 0;
+  let localized = 0;
 
   for (const s of collectShippedSources(doc, opts)) {
     const key = keyFor(s.file, s.source);
     if (seen.has(key)) continue;
     seen.add(key);
-    let clean = false;
-    try {
-      const result = compile(s.source);
-      clean = result.ok && (result.errors ?? []).length === 0;
-    } catch {
-      /* not core-clean */
+    if (foreign.has(key)) {
+      localized++;
+      continue;
     }
-    if (!clean) continue;
-    coreClean++;
+    checked++;
     const errors = engineErrors(s.source);
     if (errors.length === 0) {
       engineAccepts++;
@@ -294,5 +282,5 @@ export function checkShippedSourcesOnEngine(
       excerpt: s.source.replace(/\s+/g, ' ').trim().slice(0, 100),
     });
   }
-  return { coreClean, engineAccepts, rejections };
+  return { checked, engineAccepts, localized, rejections };
 }

package/src/multilingual/validators/execution-validator.test.ts

@@ -1,14 +1,19 @@
 /**
  * R2 — execution smoke validator locks (session 5).
  *
+ * @vitest-environment node
+ * The node environment is required: under the suite default (happy-dom) the
+ * DOM constructors are happy-dom's, the per-execution jsdom's elements fail
+ * the hosts' `instanceof` checks, and every handler installs nothing.
+ *
  * Locks three things:
  *  1. The curated subset's MEMBERSHIP — expanding/shrinking it recalibrates
  *     every language's avgExecutionFidelity, so it must be a deliberate,
  *     baseline-regenerating change, never an accident.
- *  2. The en references EXECUTE: parse → buildAST → runtime.execute installs
- *     the click handler in jsdom and dispatch produces a non-empty,
- *     deterministic DOM-effect signature (the foundation every language is
- *     scored against).
+ *  2. The en references EXECUTE: upstream `_hyperscript` (the oracle) and
+ *     `@hyperfixi/engine` each install the handler in jsdom, dispatch produces
+ *     a non-empty, deterministic DOM-effect signature, and the two agree (the
+ *     foundation every language is scored against).
  *  3. Known cross-language behavior: a faithful translation reproduces the en
  *     signature exactly; a translation that drops the destination role lands
  *     its effect on `me` and MUST diverge (the failure class R2 exists to
@@ -18,6 +23,13 @@
 import { describe, it, expect, beforeAll } from 'vitest';
 import { ExecutionValidator, EXECUTION_SUBSET, loadExecutionSubset } from './execution-validator';
 
+/**
+ * Sources loaded off the db for the curated subset: en only, which
+ * `db:init:force` writes in CI before this suite runs (translations need a
+ * `populate`, which this suite does not have).
+ */
+let enSources: Map<string, string>;
+
 describe('R2 execution subset (lock)', () => {
   it('contains exactly the 49 curated patterns', () => {
     // Changing this list recalibrates avgExecutionFidelity for every language.
@@ -142,6 +154,43 @@ describe('R2 execution validator (lock)', () => {
 
   beforeAll(async () => {
     await validator.initialize();
+    enSources = (await loadExecutionSubset(['en'])).get('en')!;
+  });
+
+  it('every en reference runs on the engine exactly as on upstream, with an effect', async () => {
+    // The oracle check behind the reference: the orchestrator scores each
+    // translation (on the engine) against upstream's English. An en reference
+    // the engine runs differently would fail that pattern in every language
+    // at once — this names the engine instead. An empty or erroring reference
+    // is excluded from scoring, so it would silently shrink the subset.
+    const report: string[] = [];
+    for (const id of EXECUTION_SUBSET) {
+      const code = enSources.get(id);
+      if (!code) continue; // the loadExecutionSubset test below names it
+      const up = await validator.execute(id, code, 'en', 'upstream');
+      const eng = await validator.execute(id, code, 'en');
+      if (up.effects.length === 0)
+        report.push(`${id}: no effect on upstream (${up.error ?? 'no error'})`);
+      else if (up.error) report.push(`${id}: upstream reports ${up.error}`);
+      else if (JSON.stringify(eng.effects) !== JSON.stringify(up.effects)) {
+        report.push(
+          `${id}:\n  upstream ${up.effects.join(' | ')}\n  engine   ${eng.effects.join(' | ')}`
+        );
+      }
+    }
+    expect(report, report.join('\n')).toEqual([]);
+  });
+
+  it('upstream swaps the two elements: the signature records the order', async () => {
+    // `swap #a with #b` changes no class, attribute, style or text — only the
+    // two elements' places, which the order line carries.
+    const res = await validator.execute(
+      'swap-content',
+      'on click swap #a with #b',
+      'en',
+      'upstream'
+    );
+    expect(res.effects.at(-1)).toMatch(/^order\[.*,b,a\]$/);
   });
 
   it('en reference executes: on click add .highlight to me', async () => {
@@ -206,13 +255,13 @@ describe('R2 execution validator (lock)', () => {
 
   it('the announce-screen-reader cell executes via its custom-event trigger', async () => {
     // First non-click cell: `on success put event.detail.message into
-    // #sr-announce set @role to "alert" on #sr-announce`. PATTERN_TRIGGER
+    // #sr-announce set @role of #sr-announce to "alert"`. PATTERN_TRIGGER
     // dispatches a `success` CustomEvent carrying detail.message; the handler
     // writes that text into #sr-announce and sets role=alert on it. Locks both
     // the per-cell trigger wiring and the two-line effect signature.
     const res = await validator.execute(
       'announce-screen-reader',
-      'on success put event.detail.message into #sr-announce set @role to "alert" on #sr-announce',
+      'on success put event.detail.message into #sr-announce set @role of #sr-announce to "alert"',
       'en'
     );
     expect(res.error).toBeUndefined();
@@ -261,11 +310,13 @@ describe('R2 execution validator (lock)', () => {
   it('wave-6 en references execute with their locked signatures', async () => {
     // The six wave-6 additions. Each en reference must produce a non-empty,
     // deterministic signature against the existing fixture (the foundation every
-    // language is scored against). next/closest positionals fall back to `me`
-    // when no match exists in the fixture; set *opacity/*transform write inline
-    // style; caret-var-on-target writes `null` into #btn (the undefined
-    // `^count`), as upstream's put writes a null value (PR 54; it used to
-    // clear the text).
+    // language is scored against). A next/closest positional with no match
+    // throws on upstream (core fell back to `me`), so PATTERN_SETUP gives
+    // toggle-aria-expanded a following .panel and accordion-toggle an
+    // enclosing item; `toggle @attr` writes upstream's `undefined`; set
+    // *opacity/*transform write inline style; caret-var-on-target writes
+    // `null` into #btn (the undefined `^count`), as upstream's put writes a
+    // null value.
     const cases: ReadonlyArray<[string, string, string[]]> = [
       [
         'next-element',
@@ -275,7 +326,10 @@ describe('R2 execution validator (lock)', () => {
       [
         'toggle-aria-expanded',
         'on click toggle @aria-expanded on me toggle .open on next .panel',
-        ['Δ#btn cls[open] attr[aria-expanded=,id=btn] style[] text[Click]'],
+        [
+          'Δ#btn cls[] attr[aria-expanded=undefined,id=btn] style[] text[Click]',
+          'Δ#panel cls[open panel] attr[id=panel] style[] text[]',
+        ],
       ],
       [
         'set-opacity',
@@ -290,7 +344,10 @@ describe('R2 execution validator (lock)', () => {
       [
         'accordion-toggle',
         'on click toggle .open on closest .accordion-item toggle @aria-expanded',
-        ['Δ#btn cls[open] attr[aria-expanded=,id=btn] style[] text[Click]'],
+        [
+          'Δ#btn cls[] attr[aria-expanded=undefined,id=btn] style[] text[Click]',
+          'Δdiv[0] cls[accordion-item card open] attr[] style[] text[]',
+        ],
       ],
       [
         'caret-var-on-target',
@@ -368,11 +425,10 @@ describe('R2 execution validator (lock)', () => {
   it('wave-9 en references execute with their locked signatures', async () => {
     // The three wave-9 additions. Each en reference must produce a non-empty,
     // deterministic signature against the existing fixture. The `*opacity`
-    // hide/show STRATEGIES are synchronous (no timer): hide writes display:none
-    // on #btn (its data-original-display memo is engine bookkeeping, excluded
-    // from signatures since the shared effect-signature module — see
-    // ENGINE_ATTRS there); show adds the visibility class on #modal.
-    // chained-access-possessive-dot writes the parent (.card) display.
+    // hide/show STRATEGIES are synchronous (no timer) and, on upstream, write
+    // the opacity itself: 0 on #btn, 1 on #modal (core ignored the strategy
+    // and toggled display, OPEN_ITEMS C1). chained-access-possessive-dot
+    // writes the parent (.card) display.
     const cases: ReadonlyArray<[string, string, string[]]> = [
       [
         'chained-access-possessive-dot',
@@ -382,12 +438,12 @@ describe('R2 execution validator (lock)', () => {
       [
         'hide-with-transition',
         'on click hide me with *opacity',
-        ['Δ#btn cls[] attr[id=btn] style[display: none;] text[Click]'],
+        ['Δ#btn cls[] attr[id=btn] style[opacity: 0;] text[Click]'],
       ],
       [
         'show-with-transition',
         'on click show #modal with *opacity',
-        ['Δ#modal cls[show] attr[id=modal] style[] text[]'],
+        ['Δ#modal cls[] attr[id=modal] style[opacity: 1;] text[]'],
       ],
     ];
     for (const [id, code, expected] of cases) {
@@ -403,7 +459,9 @@ describe('R2 execution validator (lock)', () => {
     // pre-existing document-order indices are preserved). The ja translations
     // lock the exact failure class each fix closed: append's fronted content
     // literal (was a bogus `event` role → runtime "append requires content")
-    // and increment's trailing bare amount (was dropped → +1 instead of +10).
+    // and increment's bare amount (was dropped → +1 instead of +10). The
+    // increment row counts in `#score's textContent` since the examples moved
+    // to upstream's spelling (2026-10-02); its ja is the current render.
     const cases: ReadonlyArray<[string, string, string, string]> = [
       [
         'append-content',
@@ -413,8 +471,8 @@ describe('R2 execution validator (lock)', () => {
       ],
       [
         'increment-by-amount',
-        'on click increment #score by 10',
-        '#score を クリック で 増加 10',
+        "on click increment #score's textContent by 10",
+        'クリック を で #scoreのtextContent を 10 増加',
         'text[10]',
       ],
     ];