feat(ses): Shim compatible with Hermes compiler

.github/workflows/ci.yml

@@ -231,6 +231,41 @@ jobs:
       - name: Run yarn test262
         run: exit 0 # TODO remove test262 from required tests for CI
 
+  test-hermes:
+    name: test-hermes
+
+    # begin macro
+
+    runs-on: ${{ matrix.platform }}
+    strategy:
+      fail-fast: false
+      matrix:
+        platform: [ubuntu-latest]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # without this, setup-node errors on mismatched yarn versions
+      - run: corepack enable
+
+      - name: Use Node.js 22.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          cache: yarn
+
+      - name: Install dependencies
+        run: yarn install --immutable
+
+      # end macro
+
+      - name: Run yarn build
+        run: yarn build
+
+      - name: Run SES/Hermes smoke test
+        run: cd packages/ses && yarn test:hermes
+
   viable-release:
     name: viable-release
 

packages/ses/package.json

@@ -55,24 +55,33 @@
         "default": "./dist/ses.cjs"
       }
     },
+    "./hermes": {
+      "require": {
+        "types": "./dist/types.d.cts",
+        "default": "./dist/ses-hermes.cjs"
+      }
+    },
     "./tools.js": "./tools.js",
     "./assert-shim.js": "./assert-shim.js",
     "./lockdown-shim.js": "./lockdown-shim.js",
     "./compartment-shim.js": "./compartment-shim.js",
     "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "node scripts/bundle.js",
+    "build:vanilla": "node scripts/bundle.js",
+    "build:hermes": "SES_BUILD_TYPE=hermes node scripts/bundle.js",
+    "build": "yarn build:vanilla && yarn build:hermes",
     "clean": "rm -rf dist",
     "cover": "c8 ava",
     "demo": "python3 -m http.server",
     "lint": "yarn lint:types && yarn lint:eslint",
     "lint-fix": "eslint --fix .",
     "lint:eslint": "eslint .",
     "lint:types": "tsc",
-    "prepare": "npm run clean && npm run build",
+    "prepare": "yarn clean && yarn build",
     "qt": "ava",
     "test": "tsd && ava",
+    "test:hermes": "./scripts/hermes.sh",
     "postpack": "git clean -f '*.d.ts*' '*.tsbuildinfo'"
   },
   "dependencies": {
@@ -91,6 +100,7 @@
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-eslint-comments": "^3.2.0",
     "eslint-plugin-import": "^2.29.1",
+    "hermes-engine-cli": "0.12.0",
     "prettier": "^3.2.5",
     "sinon": "^15.1.0",
     "terser": "^5.16.6",

packages/ses/scripts/bundle.js

@@ -1,10 +1,14 @@
+/** @import {ModuleTransforms} from '../../compartment-mapper/types.js' */
+
 /* global process */
 import '../index.js';
 import '../test/lockdown-safe.js';
 import fs from 'fs';
 import { makeBundle } from '@endo/compartment-mapper/bundle.js';
 import { minify } from 'terser';
 import { fileURLToPath, pathToFileURL } from 'url';
+import { getEnvironmentOption as getenv } from '@endo/env-options';
+import { hermesTransforms } from './hermesTransforms.js';
 
 const resolve = (rel, abs) => fileURLToPath(new URL(rel, abs).toString());
 const root = new URL('..', import.meta.url).toString();
@@ -15,40 +19,60 @@ const write = async (target, content) => {
   await fs.promises.writeFile(location, content);
 };
 
-const main = async () => {
+/**
+ * @param {object} [options]
+ * @param {string} [options.buildType] Suffix used to build special bundles (e.g. 'hermes')
+ */
+const writeBundle = async ({ buildType } = {}) => {
   const text = await fs.promises.readFile(
     fileURLToPath(`${root}/package.json`),
     'utf8',
   );
   const packageJson = JSON.parse(text);
   const version = packageJson.version;
 
+  /** @type ModuleTransforms */
+  const moduleTransforms = {};
+
+  let bundleFilePaths = [
+    'dist/ses.cjs',
+    'dist/ses.mjs',
+    'dist/ses.umd.js',
+    'dist/lockdown.cjs',
+    'dist/lockdown.mjs',
+    'dist/lockdown.umd.js',
+  ];
+  let terseFilePaths = ['dist/ses.umd.min.js', 'dist/lockdown.umd.min.js'];
+
+  if (buildType === 'hermes') {
+    bundleFilePaths = ['dist/ses-hermes.cjs'];
+    terseFilePaths = [];
+    Object.assign(moduleTransforms, hermesTransforms);
+  }
+
   const bundle = await makeBundle(
     read,
     pathToFileURL(resolve('../index.js', import.meta.url)).toString(),
+    { moduleTransforms },
   );
   const versionedBundle = `// ses@${version}\n${bundle}`;
 
-  const { code: terse } = await minify(versionedBundle, {
-    mangle: false,
-    keep_classnames: true,
-  });
-  assert.string(terse);
-
+  console.log(`-- Building '${buildType}' version of SES --`);
   console.log(`Bundle size: ${versionedBundle.length} bytes`);
-  console.log(`Minified bundle size: ${terse.length} bytes`);
 
-  await fs.promises.mkdir('dist', { recursive: true });
+  /** @type {string|undefined} */
+  let terse;
+  if (terseFilePaths.length) {
+    const { code } = await minify(versionedBundle, {
+      mangle: false,
+      keep_classnames: true,
+    });
+    terse = code;
+    assert.string(terse);
+    console.log(`Minified bundle size: ${terse.length} bytes`);
+  }
 
-  const bundleFilePaths = [
-    'dist/ses.cjs',
-    'dist/ses.mjs',
-    'dist/ses.umd.js',
-    'dist/lockdown.cjs',
-    'dist/lockdown.mjs',
-    'dist/lockdown.umd.js',
-  ];
-  const terseFilePaths = ['dist/ses.umd.min.js', 'dist/lockdown.umd.min.js'];
+  await fs.promises.mkdir('dist', { recursive: true });
 
   await Promise.all([
     ...bundleFilePaths.map(dest => write(dest, versionedBundle)),
@@ -81,6 +105,11 @@ const main = async () => {
   console.log(`Copied ${sourceDTS} to ${destDTS}`);
 };
 
+const main = async () => {
+  const buildType = getenv('SES_BUILD_TYPE', 'vanilla');
+  await writeBundle({ buildType });
+};
+
 main().catch(err => {
   console.error('Error running main:', err);
   process.exitCode = 1;

packages/ses/scripts/hermes.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+
+OS="$(uname -s)"
+
+case "$OS" in
+    Linux*)
+        OS_DIR="linux64-bin"
+        ;;
+    Darwin*)
+        OS_DIR="osx-bin"
+        ;;
+    CYGWIN*|MINGW*|MSYS*)
+        OS_DIR="win64-bin"
+        ;;
+    *)
+        echo "Unsupported OS: $OS"
+        exit 1
+        ;;
+esac
+
+# Paths relative to 'packages/ses'
+HERMESC="../../node_modules/hermes-engine-cli/$OS_DIR/hermesc"
+HERMES="../../node_modules/hermes-engine-cli/$OS_DIR/hermes"
+
+echo "Concatenating: dist/ses-hermes.cjs + test/hermes-smoke.js"
+cat dist/ses-hermes.cjs test/hermes-smoke.js > test/hermes-smoke-dist.js
+echo "Generated: test/hermes-smoke-dist.js"
+
+# Errors on async arrow functions and async generators
+# Both are unsupported on Hermes
+echo "Executing: test/hermes-smoke-dist.js on Hermes compiler"
+$HERMESC test/hermes-smoke-dist.js -emit-binary -out test/hermes-smoke-dist.hbc
+echo "Generated: test/hermes-smoke-dist.hbc"
+echo "Hermes compiler done"
+
+# TODO: Disabled until https://github.com/endojs/endo/issues/1891 complete
+# echo "Executing generated bytecode file on Hermes VM"
+# $HERMES -b test/hermes-smoke-dist.hbc
+# echo "Hermes VM done"
+echo "Skipping: Hermes VM"
+
+echo "Hermes tests complete"
+
+echo "Removing: test/hermes-smoke-dist.js"
+rm test/hermes-smoke-dist.js
+echo "Removing: test/hermes-smoke-dist.hbc"
+rm test/hermes-smoke-dist.hbc

packages/ses/scripts/hermesTransforms.js

@@ -0,0 +1,74 @@
+/* eslint-disable import/no-extraneous-dependencies */
+import { parse } from '@babel/parser';
+import babelGenerate from '@agoric/babel-generator';
+import babelTraverse from '@babel/traverse';
+import * as t from '@babel/types';
+
+// @ts-expect-error TS2339 Property 'default' does not exist
+const traverse = babelTraverse.default || babelTraverse;
+const generate = babelGenerate.default || babelGenerate;
+
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+
+const asyncArrowEliminator = {
+  ArrowFunctionExpression(path) {
+    if (path.node.async) {
+      let body = path.node.body;
+
+      path.traverse({
+        ThisExpression(innerPath) {
+          const { start } = innerPath.node.loc;
+          // throw path.buildCodeFrameError("..."); // https://github.com/babel/babel/issues/8617
+          throw Error(
+            `Hermes makeBundle Babel transform doesn't support 'this' keyword in async arrow functions.
+    at this (${path.state.filename}:${start.line}:${start.column})`,
+          );
+        },
+        // No need for an Identifier traversal on nodes matching 'arguments' to error on
+        // Since only non-arrow functions can access the `arguments` array-like object
+      });
+
+      // In case it's a ()=>expression style arrow function
+      if (!t.isBlockStatement(body)) {
+        body = t.blockStatement([t.returnStatement(body)]);
+      }
+
+      const functionExpression = t.functionExpression(
+        null,
+        path.node.params,
+        body,
+        path.node.generator,
+        path.node.async,
+      );
+
+      path.replaceWith(functionExpression);
+    }
+  },
+};
+
+export const hermesTransforms = {
+  mjs: (sourceBytes, specifier, location, _packageLocation, { sourceMap }) => {
+    const transforms = {
+      ...asyncArrowEliminator,
+      // Some transforms might be added based on the specifier later
+    };
+
+    const sourceString = decoder.decode(sourceBytes);
+
+    const ast = parse(sourceString, {
+      sourceType: 'module',
+    });
+
+    traverse(ast, transforms, null, { filename: location });
+
+    const { code } = generate(ast, {
+      // Nothing being done with sourcemaps as this point
+      retainLines: true,
+      compact: true,
+      verbatim: true,
+    });
+
+    return { bytes: encoder.encode(code), parser: 'mjs', sourceMap };
+  },
+};

packages/ses/src/commons.js

@@ -378,3 +378,32 @@ export const FERAL_STACK_GETTER = feralStackGetter;
  * @type {((newValue: any) => void) | undefined}
  */
 export const FERAL_STACK_SETTER = feralStackSetter;
+
+// Test for async generator function syntax support.
+let AsyncGeneratorNewFunctionInstance;
+try {
+  // Wrapping one in an new Function lets the `hermesc` binary file
+  // parse the Metro js bundle without SyntaxError, to generate the
+  // optimised Hermes bytecode bundle, when `gradlew` is called to
+  // assemble the release build APK for React Native prod Android apps.
+  // Delaying the error until runtime lets us customise lockdown behaviour.
+  AsyncGeneratorNewFunctionInstance = new FERAL_FUNCTION(
+    'return (async function* AsyncGeneratorFunctionInstance() {})',
+  )();
+} catch (e) {
+  // @ts-expect-error ts(2339) Property 'jsEngine' does not exist on type 'Error'. However it exists on Hermes.
+  if (Error.prototype.jsEngine === 'hermes' && e.name === 'SyntaxError') {
+    // Swallows Hermes error `async generators are unsupported` at runtime.
+    // @ts-expect-error ts(2554) Expected 0 arguments, but got 1. It refers to the Web API Window object, but on Hermes we expect 1 argument.
+    // eslint-disable-next-line no-undef
+    print('SES: Skipping async generators, unsupported on Hermes');
+    // Note: `console` is not a JS built-in, so Hermes engine throws:
+    // Uncaught ReferenceError: Property 'console' doesn't exist
+    // See: https://github.com/facebook/hermes/issues/675
+    // However React Native provides a `console` implementation:
+    // https://github.com/facebook/react-native/blob/main/packages/react-native/Libraries/Core/InitializeCore.js
+  } else {
+    throw e;
+  }
+}
+export const AsyncGeneratorFunctionInstance = AsyncGeneratorNewFunctionInstance;