feat(ses): Shim compatible with Hermes compiler

.github/workflows/ci.yml

@@ -213,6 +213,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: yarn test:hermes
+
   viable-release:
     name: viable-release
 

packages/compartment-mapper/src/bundle.js

@@ -233,6 +233,7 @@ export const makeBundle = async (readPowers, moduleLocation, options) => {
 
   const {
     moduleTransforms,
+    syncModuleTransforms,
     dev,
     tags: tagsOption,
     conditions: conditionsOption = tagsOption,
@@ -333,6 +334,7 @@ export const makeBundle = async (readPowers, moduleLocation, options) => {
     resolve,
     makeImportHook,
     moduleTransforms,
+    syncModuleTransforms,
     parserForLanguage,
   });
   await compartment.load(entryModuleSpecifier);

packages/ses/package.json

@@ -56,6 +56,12 @@
         "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": {
@@ -70,7 +76,9 @@
     "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "node scripts/bundle.js",
+    "build:vanilla": "node scripts/bundle.js",
+    "build:hermes": "node scripts/bundle.js hermes",
+    "build": "yarn build:vanilla && yarn build:hermes",
     "clean": "rm -rf dist",
     "cover": "c8 ava",
     "demo": "python3 -m http.server",
@@ -81,6 +89,7 @@
     "prepare": "npm run clean && npm run build",
     "qt": "ava",
     "test": "tsd && ava",
+    "test:hermes": "./scripts/hermes-test.sh",
     "test:xs": "xst dist/ses.umd.js test/_lockdown-safe.js && node scripts/generate-test-xs.js && xst tmp/test-xs.js && rm -rf tmp",
     "postpack": "git clean -f '*.d.ts*' '*.tsbuildinfo'"
   },
@@ -100,6 +109,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.3.3",
     "terser": "^5.16.6",
     "tsd": "^0.31.2",

packages/ses/scripts/bundle.js

@@ -4,6 +4,7 @@ import fs from 'fs';
 import { makeBundle } from '@endo/compartment-mapper/bundle.js';
 import { minify } from 'terser';
 import { fileURLToPath, pathToFileURL } from 'url';
+import { hermesTransforms } from './hermes-transforms.js';
 
 lockdown();
 
@@ -16,40 +17,59 @@ 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;
 
+  let syncModuleTransforms;
+
+  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 = [];
+    syncModuleTransforms = hermesTransforms;
+  }
+
   const bundle = await makeBundle(
     read,
     pathToFileURL(resolve('../index.js', import.meta.url)).toString(),
+    { syncModuleTransforms },
   );
   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)),
@@ -82,6 +102,11 @@ const main = async () => {
   console.log(`Copied ${sourceDTS} to ${destDTS}`);
 };
 
+const main = async () => {
+  const buildType = process.argv[2];
+  await writeBundle({ buildType });
+};
+
 main().catch(err => {
   console.error('Error running main:', err);
   process.exitCode = 1;

packages/ses/scripts/hermes-test.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+
+# Creates a JS smoke test to be compiled into Hermes bytecode (hbc).
+#
+# Usage: scripts/hermes-test.sh
+
+set -ueo pipefail
+
+DIR=$(dirname -- "${BASH_SOURCE[0]}")
+cd "$DIR/.."
+
+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
+
+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/hermes-transforms.js

@@ -0,0 +1,89 @@
+/* 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';
+
+// TODO The following is sufficient on Node.js, but for compatibility with
+// `node -r esm`, we must use the pattern below.
+// Remove after /~https://github.com/Agoric/agoric-sdk/issues/8671.
+// OR, upgrading to Babel 8 probably addresses this defect.
+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(
+        undefined,
+        path.node.params,
+        body,
+        path.node.generator,
+        path.node.async,
+      );
+
+      path.replaceWith(functionExpression);
+    }
+  },
+};
+
+const destroyAsyncGenerators = path => {
+  if (path.node.async && path.node.generator) {
+    path.replaceWith(t.identifier('undefined'));
+  }
+};
+
+const asyncGeneratorDestroyer = {
+  FunctionExpression: destroyAsyncGenerators,
+  FunctionDeclaration: destroyAsyncGenerators,
+};
+
+export const hermesTransforms = {
+  mjs: (sourceBytes, specifier, location, _packageLocation, { sourceMap }) => {
+    const transforms = {
+      ...asyncArrowEliminator,
+      ...asyncGeneratorDestroyer,
+      // Some transforms might be added based on the specifier later
+    };
+
+    const sourceString = decoder.decode(sourceBytes);
+
+    const ast = parse(sourceString, {
+      sourceType: 'module',
+    });
+
+    traverse(ast, transforms, undefined, { 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

@@ -386,3 +386,52 @@ export const FERAL_STACK_GETTER = feralStackGetter;
  * @type {((newValue: any) => void) | undefined}
  */
 export const FERAL_STACK_SETTER = feralStackSetter;
+
+const getAsyncGeneratorFunctionInstance = () => {
+  // Test for async generator function syntax support.
+  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.
+    return new FERAL_FUNCTION(
+      'return (async function* AsyncGeneratorFunctionInstance() {})',
+    )();
+  } catch (error) {
+    // Note: `Error.prototype.jsEngine` is only set by React Native runtime, not Hermes:
+    // /~https://github.com/facebook/react-native/blob/main/packages/react-native/ReactCommon/hermes/executor/HermesExecutorFactory.cpp#L224-L230
+    if (error.name === 'SyntaxError') {
+      // Swallows Hermes error `async generators are unsupported` at runtime.
+      if (globalThis.console !== undefined) {
+        // eslint-disable-next-line @endo/no-polymorphic-call
+        console.warn('SES Skipping async generators');
+      }
+      if (globalThis.print !== undefined) {
+        // @ts-expect-error Hermes defines a print fn that accepts one or more arguments.
+        // eslint-disable-next-line no-undef
+        print('SES Skipping async generators');
+      }
+      // 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 when setting up error handling:
+      // /~https://github.com/facebook/react-native/blob/main/packages/react-native/Libraries/Core/InitializeCore.js
+      return undefined;
+    } else if (error.name === 'EvalError') {
+      // eslint-disable-next-line no-empty-function
+      return async function* AsyncGeneratorFunctionInstance() {};
+    } else {
+      throw error;
+    }
+  }
+};
+
+/**
+ * If the platform supports async generator functions, this will be an
+ * async generator function instance. Otherwise, it will be `undefined`.
+ *
+ * @type {AsyncGeneratorFunction | undefined}
+ */
+export const AsyncGeneratorFunctionInstance =
+  getAsyncGeneratorFunctionInstance();