fix(compartment-mapper,bundle-source): async parser support

This fixes the half-implemented type defs and support for async parsers by introducing `AsyncParserImplementation`.

We needed sync-and-async-specific parse-mappers in `map-parser.js` and some type guards.

A sync-parser-specific `SyncParserForLanguage` is introduced as well.

Author: boneskull

.changeset/fuzzy-hornets-shout.md

@@ -0,0 +1,6 @@
+---
+'@endo/compartment-mapper': patch
+'@endo/bundle-source': patch
+---
+
+Fixes poorly-defined support for asynchronous parsers.

packages/bundle-source/src/endo.js

@@ -9,6 +9,7 @@ import { defaultParserForLanguage as transparentParserForLanguage } from '@endo/
 import tsBlankSpace from 'ts-blank-space';
 
 /** @import {Language} from '@endo/compartment-mapper/node-powers.js' */
+/** @import {AsyncParserImplementation} from '@endo/compartment-mapper' */
 /** @import {BundlingKit, BundlingKitIO, BundlingKitOptions, ModuleTransformsLike, ParserForLanguageLike, SourceMapDescriptor} from './types.js' */
 
 const textEncoder = new TextEncoder();
@@ -189,8 +190,9 @@ export const makeBundlingKit = (
     };
   }
 
+  /** @type {AsyncParserImplementation} */
   const mtsParser = {
-    parse(
+    async parse(
       sourceBytes,
       specifier,
       moduleLocation,
@@ -212,8 +214,9 @@ export const makeBundlingKit = (
     synchronous: false,
   };
 
+  /** @type {AsyncParserImplementation} */
   const ctsParser = {
-    parse(
+    async parse(
       sourceBytes,
       specifier,
       moduleLocation,

packages/compartment-mapper/src/import-hook.js

@@ -9,7 +9,15 @@
  *
  * @module
  */
-
+import { asyncTrampoline, syncTrampoline } from '@endo/trampoline';
+import { resolve } from './node-module-specifier.js';
+import {
+  attenuateModuleHook,
+  enforcePolicyByModule,
+  enforcePackagePolicyByCanonicalName,
+} from './policy.js';
+import { ATTENUATORS_COMPARTMENT } from './policy-format.js';
+import { unpackReadPowers } from './powers.js';
 /**
  * @import {
  *   ImportHook,
@@ -43,18 +51,19 @@
  *   CanonicalName,
  *   LocalModuleSource,
  *   ModuleSourceHook,
+ *   ParseFn,
+ *   AsyncParseFn,
  * } from './types.js'
  */
 
-import { asyncTrampoline, syncTrampoline } from '@endo/trampoline';
-import { resolve } from './node-module-specifier.js';
-import {
-  attenuateModuleHook,
-  enforcePolicyByModule,
-  enforcePackagePolicyByCanonicalName,
-} from './policy.js';
-import { ATTENUATORS_COMPARTMENT } from './policy-format.js';
-import { unpackReadPowers } from './powers.js';
+/**
+ * Type guard that narrows a `ParseFn | AsyncParseFn` to `ParseFn` by checking
+ * for the `isSyncParser` flag.
+ *
+ * @param {ParseFn | AsyncParseFn} parse
+ * @returns {parse is ParseFn}
+ */
+const isSyncParseFn = parse => 'isSyncParser' in parse && !!parse.isSyncParser;
 
 // q, as in quote, for quoting strings in error messages.
 const { quote: q } = assert;
@@ -324,8 +333,7 @@ const executeLocalModuleSourceHook = (
  * {@link StaticModuleType} for a particular {@link CompartmentDescriptor} (or
  * `undefined`).
  *
- * Supports both {@link SyncChooseModuleDescriptorOperators sync} and
- * {@link AsyncChooseModuleDescriptorOperators async} operators.
+ * Supports both sync and async operators.
  *
  * Used by both {@link makeImportNowHookMaker} and {@link makeImportHookMaker}.
  *
@@ -839,13 +847,14 @@ export function makeImportNowHookMaker(
       }
     };
 
-    if (!('isSyncParser' in parse)) {
+    if (!isSyncParseFn(parse)) {
       return function impossibleTransformImportNowHook() {
         throw new Error(
           'Dynamic requires are only possible with synchronous parsers and no asynchronous module transforms in options',
         );
       };
     }
+    const /** @type {ParseFn} */ syncParse = parse;
 
     const compartmentDescriptor =
       compartmentDescriptors[packageLocation] || create(null);
@@ -924,7 +933,7 @@ export function makeImportNowHookMaker(
           },
           {
             maybeRead: maybeReadNow,
-            parse,
+            parse: syncParse,
             shouldDeferError,
           },
         );

packages/compartment-mapper/src/link.js

@@ -404,8 +404,7 @@ export const link = (
     /** @type {ShouldDeferError} */
     const shouldDeferError = language => {
       if (language && has(parserForLanguage, language)) {
-        return /** @type {ParserImplementation} */ (parserForLanguage[language])
-          .heuristicImports;
+        return parserForLanguage[language].heuristicImports;
       } else {
         // If language is undefined or there's no parser, the error we could consider deferring is surely related to
         // that. Nothing to throw here.