Remap ESModule imports at link time in mdoc

build.sbt

@@ -14,6 +14,11 @@ def isScala212(v: Option[(Long, Long)]): Boolean = v.exists(_._1 == 2) && v.exis
 def isScala213(v: Option[(Long, Long)]): Boolean = v.exists(_._1 == 2) && v.exists(_._2 == 13)
 def isScala3(v: Option[(Long, Long)]): Boolean = v.exists(_._1 == 3)
 
+def jsoniter = List(
+  "com.github.plokhotnyuk.jsoniter-scala" %% "jsoniter-scala-core" % "2.13.5.2",
+  "com.github.plokhotnyuk.jsoniter-scala" %% "jsoniter-scala-macros" % "2.13.5.2"
+)
+
 val isScala212 = Def.setting {
   VersionNumber(scalaVersion.value).matchesSemVer(SemanticSelector("2.12.x"))
 }
@@ -129,6 +134,7 @@ val V = new {
   val fs2 = "3.10.2"
 
   val metaconfig = "0.12.0"
+
 }
 
 lazy val interfaces = project
@@ -250,7 +256,7 @@ lazy val mdoc = project
       "com.geirsson" %% "metaconfig-typesafe-config" % V.metaconfig,
       "com.lihaoyi" %% "fansi" % V.fansi,
       "com.lihaoyi" %% "pprint" % V.pprint
-    )
+    ) ++ jsoniter
   )
   .dependsOn(parser, runtime, cli)
   .enablePlugins(BuildInfoPlugin)
@@ -432,7 +438,10 @@ lazy val jsWorker =
     .settings(
       sharedSettings,
       moduleName := "mdoc-js-worker",
-      libraryDependencies += ("org.scala-js" %% "scalajs-linker" % scalaJSVersion % Provided) cross CrossVersion.for3Use2_13
+      libraryDependencies ++= Seq(
+        "org.scala-js" %% "scalajs-linker" % scalaJSVersion % Provided cross CrossVersion.for3Use2_13,
+        "com.armanbilge" %% "scalajs-importmap" % "0.1.1" cross CrossVersion.for3Use2_13
+      )
     )
 
 lazy val js = project
@@ -441,7 +450,8 @@ lazy val js = project
   .settings(
     sharedSettings,
     moduleName := "mdoc-js",
-    Compile / unmanagedSourceDirectories ++= multiScalaDirectories("js").value
+    Compile / unmanagedSourceDirectories ++= multiScalaDirectories("js").value,
+    libraryDependencies ++= jsoniter
   )
   .dependsOn(mdoc)
 

cli/src/main/scala/mdoc/internal/cli/MdocProperties.scala

@@ -36,8 +36,7 @@ object MdocProperties {
       out = getPath("out")
     )
   }
-  def default(cwd: AbsolutePath): MdocProperties = {
-    val path = "mdoc.properties"
+  def default(cwd: AbsolutePath, path: String): MdocProperties = {
     Option(this.getClass.getClassLoader.getResourceAsStream(path)) match {
       case Some(resource) =>
         val props = new java.util.Properties()

cli/src/main/scala/mdoc/internal/cli/Settings.scala

@@ -32,6 +32,7 @@ import mdoc.internal.markdown.{GitHubIdGenerator, ReplVariablePrinter}
 import mdoc.internal.cli.CliEnrichments._
 import pprint.TPrint
 import pprint.TPrintColors
+import java.nio.file.Path
 
 class Section(val name: String) extends StaticAnnotation
 
@@ -155,7 +156,15 @@ case class Settings(
     variablePrinter: Variable => String = ReplVariablePrinter,
     @Hidden()
     @Description("The Coursier logger used to report progress bars when downloading dependencies")
-    coursierLogger: coursierapi.Logger = coursierapi.Logger.progressBars()
+    coursierLogger: coursierapi.Logger = coursierapi.Logger.progressBars(),
+    @Description(
+      "The absolute path to a file containing an import map file in this format; https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap"
+    )
+    importMapPath: Option[AbsolutePath] = None,
+    @Description(
+      "Defaults to mdoc.properties. This is the name of the properties file the CLI will read. It is assumed to be a resource on the classpath. Use the --extra-jars flag to customise the directory it is found in"
+    )
+    propFileName: String = "mdoc.properties"
 ) extends mdoc.parser.ParserSettings {
 
   val isMarkdownFileExtension = markdownExtensions.toSet
@@ -261,9 +270,9 @@ object Settings { // extends MetaconfigScalametaImplicits with Decoders with Set
       cwd = cwd
     )
   }
-  def default(cwd: AbsolutePath): Settings = {
+  def default(cwd: AbsolutePath, filename: String): Settings = {
     val base = baseDefault(cwd)
-    val props = MdocProperties.default(cwd)
+    val props = MdocProperties.default(cwd, filename)
     base.withProperties(props)
   }
 
@@ -294,14 +303,20 @@ object Settings { // extends MetaconfigScalametaImplicits with Decoders with Set
     generic.deriveDecoder[Settings](base)
   }
 
-  def fromCliArgs(args: List[String], base: Settings): Configured[Settings] = {
+  def fromCliArgs(args: List[String], workingDirectory: Path): Configured[Settings] = {
     Conf
       .parseCliArgs[Settings](args)
       .andThen(conf => {
+        val base =
+          Settings.default(
+            AbsolutePath(workingDirectory),
+            conf.get[String]("propFileName").getOrElse("mdoc.properties")
+          )
         val cwd = conf.get[String]("cwd").map(AbsolutePath(_)(base.cwd)).getOrElse(base.cwd)
-        conf.as[Settings](decoder(base.copy(cwd = cwd)))
+        conf
+          .as[Settings](decoder(base.copy(cwd = cwd)))
+          .map(_.addSite(base.site))
       })
-      .map(_.addSite(base.site))
   }
 
   def write(set: Settings) = ConfEncoder[Settings].write(set)

docs/js.md

@@ -75,7 +75,9 @@ js-linker-classpath=$(coursier fetch org.scalameta:mdoc-js-worker_@SCALA_BINARY_
 EOT
 ```
 
-Note: For scala 3, you may need `js-scalac-options=--scala-js` - this is currently untested.
+Note: For scala 3, you may need `js-scalac-options=-scalajs` - instead of the XPlugin incantation - [Doc](https://docs.scala-lang.org/scala3/guides/migration/options-lookup.html#compiler-plugins).
+
+
 
 Next, create a basic Markdown files with an `mdoc:js` modifier:
 

mdoc-js-interfaces/src/main/java/ScalajsConfig.java

@@ -1,17 +1,20 @@
 package mdoc.js.interfaces;
 
+import java.util.Map;
+
 public class ScalajsConfig {
 	public ModuleType moduleType;
 	public boolean fullOpt;
 	public boolean sourceMap;
 	public boolean batchMode;
 	public boolean closureCompiler;
+	public Map<String, String> importMap;
 
 	public ScalajsConfig() {
 	}
-	
+
 	public ScalajsConfig withModuleKind(ModuleType kind) {
-		if(kind == ModuleType.ESModule)
+		if (kind == ModuleType.ESModule)
 			this.moduleType = ModuleType.ESModule;
 		else if (kind == ModuleType.NoModule)
 			this.moduleType = ModuleType.NoModule;
@@ -20,6 +23,11 @@ else if (kind == ModuleType.CommonJSModule)
 		return this;
 	}
 
+	public ScalajsConfig withImportMap(Map<String, String> importMap) {
+		this.importMap = importMap;
+		return this;
+	}
+
 	public ScalajsConfig withOptimized(boolean enabled) {
 		this.fullOpt = enabled;
 		return this;

mdoc-js-worker/src/main/scala/ScalaJSWorker.scala

@@ -18,11 +18,15 @@ import org.scalajs.logging.Logger
 import org.scalajs.logging.Level
 import org.scalajs.linker.standard.MemIRFileImpl
 import org.scalajs.linker.interface.Semantics
+import scala.collection.JavaConverters._
+import com.armanbilge.sjsimportmap.ImportMappedIRFile
+
 class ScalaJSWorker(
     config: ScalajsConfig,
     logger: Logger
 ) extends ScalajsWorkerApi {
   case class IFile(mem: IRFile) extends ScalajsWorkerApi.IRFile
+
   val linker = {
     val cfg =
       StandardConfig()
@@ -43,6 +47,12 @@ class ScalaJSWorker(
     StandardImpl.clearableLinker(cfg)
   }
 
+  lazy val remapFct = config.importMap.asScala.toSeq.foldLeft((in: String) => in) {
+    case (fct, (s1, s2)) =>
+      val fct2: (String => String) = (in => in.replace(s1, s2))
+      (in => fct(fct2(in)))
+  }
+
   var cachedFiles = Seq.empty[org.scalajs.linker.interface.IRFile]
 
   val cache = StandardImpl.irFileCache().newCache
@@ -62,10 +72,18 @@ class ScalaJSWorker(
     val mem = MemOutputDirectory()
     val report = Await.result(
       linker.link(
-        cachedFiles.toSeq ++
-          in.toSeq.collect { case IFile(o) =>
-            o
-          },
+        (
+          cachedFiles.toSeq ++
+            in.toSeq
+              .collect { case IFile(o) =>
+                o
+              }
+        ).map { ir =>
+          if (config.importMap.isEmpty)
+            ir
+          else
+            ImportMappedIRFile.fromIRFile(ir)(remapFct)
+        },
         Seq.empty,
         mem,
         logger

mdoc-js/src/main/scala/mdoc/modifiers/JsConfig.scala

@@ -7,6 +7,9 @@ import scala.meta.internal.io.PathIO
 import scala.meta.io.AbsolutePath
 import scala.meta.io.Classpath
 import mdoc.js.interfaces._
+import scala.collection.immutable.HashMap
+import com.github.plokhotnyuk.jsoniter_scala.core._
+import mdoc.modifiers.ImportMapJsonIr.ImportMap
 
 case class JsConfig(
     moduleKind: ModuleType = ModuleType.NoModule,
@@ -20,7 +23,8 @@ case class JsConfig(
     fullOpt: Boolean = true,
     htmlPrefix: String = "",
     relativeLinkPrefix: String = "",
-    batchMode: Boolean = false
+    batchMode: Boolean = false,
+    importMap: Map[String, String] = Map.empty
 ) {
   lazy val isCommonJS: Boolean = moduleKind == ModuleType.CommonJSModule
   lazy val isEsModule: Boolean = moduleKind == ModuleType.ESModule
@@ -99,7 +103,14 @@ object JsConfig {
           }
       },
       relativeLinkPrefix = ctx.site.getOrElse("js-relative-link-prefix", base.relativeLinkPrefix),
-      batchMode = ctx.site.getOrElse("js-batch-mode", "false").toBoolean
+      batchMode = ctx.site.getOrElse("js-batch-mode", "false").toBoolean,
+      importMap = ctx.settings.importMapPath match {
+        case None => new HashMap[String, String]()
+        case Some(value) =>
+          val importMapRaw = scala.io.Source.fromFile(value.toFile).getLines().mkString("\n")
+          val importMapParsed = readFromString[ImportMap](importMapRaw)
+          importMapParsed.imports
+      }
     )
   }
 }

mdoc-js/src/main/scala/mdoc/modifiers/JsImportMap.scala

@@ -0,0 +1,19 @@
+package mdoc.modifiers
+
+import com.github.plokhotnyuk.jsoniter_scala.core._
+import com.github.plokhotnyuk.jsoniter_scala.macros._
+
+object ImportMapJsonIr {
+
+  type Scope = Map[String, String]
+
+  final case class ImportMap(
+      val imports: Map[String, String],
+      val scopes: Option[Map[String, Scope]]
+  )
+
+  object ImportMap {
+    implicit val codec: JsonValueCodec[ImportMap] = JsonCodecMaker.make
+  }
+
+}

mdoc-js/src/main/scala/mdoc/modifiers/JsModifier.scala

@@ -73,7 +73,10 @@ class JsModifier extends mdoc.PreModifier {
       .withModuleKind(config.moduleKind)
       .withSourceMap(false)
       .withBatchMode(config.batchMode)
-      .withClosureCompiler(config.fullOpt)
+      .withClosureCompiler(
+        config.fullOpt && !(config.moduleKind == ModuleType.ESModule)
+      ) // Closure compiler dosen't work with ESModules
+      .withImportMap(config.importMap.asJava)
   }
 
   override def onLoad(ctx: OnLoadContext): Unit = {

mdoc-sbt/src/main/scala/mdoc/MdocPlugin.scala

@@ -157,6 +157,12 @@ object MdocPlugin extends AutoPlugin {
             case other => "org.scala-js" % s"scalajs-linker_$other" % sjsVersion
           }
 
+          val importMapDependency = binaryVersion match {
+            case "3" => "com.armanbilge" % "scalajs-importmap_2.13" % "0.1.1"
+            case other =>
+              "com.armanbilge" % s"scalajs-importmap_$other" % "0.1.1"
+          }
+
           val mdocJSDependency = binaryVersion match {
             case "3" => "org.scalameta" % "mdoc-js-worker_3" % BuildInfo.version
             case other => "org.scalameta" % s"mdoc-js-worker_$other" % BuildInfo.version
@@ -167,7 +173,8 @@ object MdocPlugin extends AutoPlugin {
           MdocJSConfiguration(
             scalacOptions = options.options,
             compileClasspath = options.classpath,
-            linkerClassPath = getJars(linkerDependency) ++ workerClasspath,
+            linkerClassPath =
+              getJars(linkerDependency) ++ workerClasspath ++ getJars(importMapDependency),
             moduleKind = options.moduleKind,
             jsLibraries = libraries
           ).writeTo(props)
@@ -188,7 +195,15 @@ object MdocPlugin extends AutoPlugin {
           classpath.mkString(java.io.File.pathSeparator)
         )
         IO.write(props, "mdoc properties", out)
-        List(out)
+        val esVersion = props.clone().asInstanceOf[java.util.Properties]
+        esVersion.put("js-module-kind", "ESModule")
+        val esOut = managedResourceDirectories.in(Compile).value.head / "es.properties"
+        IO.write(
+          esVersion,
+          "mdoc esmoddule properties",
+          esOut
+        )
+        List(out, esOut) // Both of these are used in the JsCliSuite Integration tests
       }
     )
 

mdoc/src/main/scala/mdoc/Main.scala

@@ -36,8 +36,7 @@ trait MainProcess {
     process(args, new ConsoleReporter(out), cwd)
   }
   def process(args: Array[String], reporter: Reporter, cwd: Path): Int = {
-    val base = Settings.default(AbsolutePath(cwd))
-    val ctx = Settings.fromCliArgs(args.toList, base)
+    val ctx = Settings.fromCliArgs(args.toList, cwd)
     MainOps.process(ctx, reporter)
   }
   def process(settings: MainSettings): Int = {

mdoc/src/main/scala/mdoc/MainSettings.scala

@@ -23,7 +23,7 @@ final class MainSettings private (
   def withArgs(args: List[String]): MainSettings = {
     if (args.isEmpty) this
     else {
-      Settings.fromCliArgs(args, settings) match {
+      Settings.fromCliArgs(args, settings.cwd.toNIO) match {
         case Configured.Ok(newSettings) =>
           copy(settings = newSettings)
         case Configured.NotOk(error) =>
@@ -121,12 +121,12 @@ final class MainSettings private (
 }
 
 object MainSettings {
-  def apply(workingDirectory: Path): MainSettings = {
-    val settings = Settings.default(AbsolutePath(workingDirectory))
+  def apply(workingDirectory: Path, propertiesFileName: String): MainSettings = {
+    val settings = Settings.default(AbsolutePath(workingDirectory), propertiesFileName)
     val reporter = ConsoleReporter.default
     new MainSettings(settings, reporter)
   }
   def apply(): MainSettings = {
-    MainSettings(PathIO.workingDirectory.toNIO)
+    MainSettings(PathIO.workingDirectory.toNIO, "mdoc.properties")
   }
 }

tests/unit-js/src/test/resources/importmap.json

@@ -0,0 +1,5 @@
+{
+  "imports": {
+    "@stdlib/blas": "https://cdn.jsdelivr.net/npm/@stdlib/[email protected]/+esm"
+  }
+}