@jsenv/core 25.6.2 → 27.0.0-alpha.0

package/src/omega/core_plugins/import_assertions/helpers/babel_plugin_metadata_import_assertions.js

@@ -0,0 +1,98 @@
+export const babelPluginMetadataImportAssertions = () => {
+  return {
+    name: "metadata-import-assertions",
+    visitor: {
+      Program: (programPath, state) => {
+        const importAssertions = collectProgramImportAssertions(programPath)
+        state.file.metadata.importAssertions = importAssertions
+      },
+    },
+  }
+}
+
+/*
+ * Jsenv wont touch code where "specifier" or "type" is dynamic (see code below)
+ * ```js
+ * const file ="./style.css"
+ * const type = "css"
+ * import(file, { assert: { type }})
+ * ```
+ * Jsenv could throw an error because we know browser will fail to execute the code
+ * because import assertions are not supported.
+ * But for now (as it is simpler to do so) we let the browser throw the error
+ */
+const collectProgramImportAssertions = (programPath) => {
+  const importAssertions = []
+  programPath.traverse({
+    CallExpression: (path) => {
+      if (path.node.callee.type !== "Import") {
+        // Some other function call, not import();
+        return
+      }
+      if (path.node.arguments[0].type !== "StringLiteral") {
+        // Non-string argument, probably a variable or expression, e.g.
+        // import(moduleId)
+        // import('./' + moduleName)
+        return
+      }
+      const args = path.node.arguments
+      const secondArg = args[1]
+      if (!secondArg) {
+        return
+      }
+      const { properties } = secondArg
+      const assertProperty = properties.find((property) => {
+        return property.key.name === "assert"
+      })
+      if (!assertProperty) {
+        return
+      }
+      const assertProperties = assertProperty.value.properties
+      const typePropertyNode = assertProperties.find((property) => {
+        return property.key.name === "type"
+      })
+      if (!typePropertyNode) {
+        return
+      }
+      const typePropertyValue = typePropertyNode.value
+      if (typePropertyValue.type !== "StringLiteral") {
+        return
+      }
+      const type = typePropertyValue.value
+      importAssertions.push({
+        path,
+        assert: {
+          type,
+        },
+      })
+    },
+
+    ImportDeclaration: (path) => {
+      const { assertions } = path.node
+      if (!assertions) {
+        return
+      }
+      if (assertions.length === 0) {
+        return
+      }
+      const typeAssertion = assertions.find(
+        (assertion) => assertion.key.name === "type",
+      )
+      if (!typeAssertion) {
+        return
+      }
+      const typeNode = typeAssertion.value
+      if (typeNode.type !== "StringLiteral") {
+        return
+      }
+      const type = typeNode.value
+      importAssertions.push({
+        path,
+        assert: {
+          type,
+        },
+      })
+    },
+  })
+  return importAssertions
+}

package/src/{internal/building → omega/core_plugins/import_assertions/helpers}/json_module.js

@@ -1,4 +1,4 @@
-export const convertJsonTextToJavascriptModule = ({ code }) => {
+export const convertJsonTextToJavascriptModule = ({ content }) => {
   // here we could do the following
   // return export default jsonText
   // This would return valid js, that would be minified later
@@ -6,6 +6,7 @@ export const convertJsonTextToJavascriptModule = ({ code }) => {
   // for js engine to parse JSON than JS
 
   return {
-    code: `export default JSON.parse(${JSON.stringify(code.trim())})`,
+    contentType: "application/javascript",
+    content: `export default JSON.parse(${JSON.stringify(content.trim())})`,
   }
 }

package/src/omega/core_plugins/import_assertions/helpers/text_module.js

@@ -0,0 +1,6 @@
+export const convertTextToJavascriptModule = ({ content }) => {
+  return {
+    contentType: "application/javascript",
+    content: `export default ${JSON.stringify(content)}`,
+  }
+}

package/src/omega/core_plugins/import_assertions/jsenv_plugin_import_assertions.js

@@ -0,0 +1,211 @@
+import { applyBabelPlugins } from "@jsenv/utils/js_ast/apply_babel_plugins.js"
+import { ContentType } from "@jsenv/utils/src/content_type.js"
+import { createMagicSource } from "@jsenv/utils/sourcemap/magic_source.js"
+import { injectQueryParamsIntoSpecifier } from "@jsenv/utils/urls/url_utils.js"
+import { JS_QUOTES } from "@jsenv/utils/string/js_quotes.js"
+
+import { babelPluginMetadataImportAssertions } from "./helpers/babel_plugin_metadata_import_assertions.js"
+import { convertJsonTextToJavascriptModule } from "./helpers/json_module.js"
+import { convertTextToJavascriptModule } from "./helpers/text_module.js"
+
+export const jsenvPluginImportAssertions = () => {
+  const importAssertions = [
+    {
+      name: "jsenv:import_assertions",
+      appliesDuring: "*",
+      transform: {
+        js_module: async (
+          { url, generatedUrl, content },
+          { scenario, isSupportedOnRuntime, referenceUtils },
+        ) => {
+          const importTypesToHandle = getImportTypesToHandle({
+            scenario,
+            isSupportedOnRuntime,
+          })
+          if (importTypesToHandle.length === 0) {
+            return null
+          }
+          const { metadata } = await applyBabelPlugins({
+            babelPlugins: [babelPluginMetadataImportAssertions],
+            url,
+            generatedUrl,
+            content,
+          })
+          const { importAssertions } = metadata
+          const magicSource = createMagicSource(content)
+          importAssertions.forEach((importAssertion) => {
+            const assertType = importAssertion.assert.type
+            if (!importTypesToHandle.includes(assertType)) {
+              return
+            }
+            const { path } = importAssertion
+            const { node } = path
+            const importType = `${assertType}_module`
+            if (node.type === "CallExpression") {
+              const importSpecifierPath = path.get("arguments")[0]
+              const specifier = importSpecifierPath.node.value
+              const newSpecifier = injectQueryParamsIntoSpecifier(specifier, {
+                [importType]: "",
+              })
+              const [newReference, newUrlInfo] = referenceUtils.updateSpecifier(
+                JSON.stringify(specifier),
+                newSpecifier,
+              )
+              newUrlInfo.data.importType = importType
+              magicSource.replace({
+                start: importSpecifierPath.node.start,
+                end: importSpecifierPath.node.end,
+                replacement: newReference.generatedSpecifier,
+              })
+              const secondArgPath = path.get("arguments")[1]
+              magicSource.remove({
+                start: secondArgPath.node.start,
+                end: secondArgPath.node.end,
+              })
+              return
+            }
+            const importSpecifierPath = path.get("source")
+            const specifier = importSpecifierPath.node.value
+            const newSpecifier = injectQueryParamsIntoSpecifier(specifier, {
+              [importType]: "",
+            })
+            const [newReference, newUrlInfo] = referenceUtils.updateSpecifier(
+              JSON.stringify(specifier),
+              newSpecifier,
+            )
+            newUrlInfo.data.importType = importType
+            magicSource.replace({
+              start: importSpecifierPath.node.start,
+              end: importSpecifierPath.node.end,
+              replacement: newReference.generatedSpecifier,
+            })
+            const assertionsPath = path.get("assertions")[0]
+            magicSource.remove({
+              start: assertionsPath.node.start,
+              end: assertionsPath.node.end,
+            })
+          })
+          return magicSource.toContentAndSourcemap()
+        },
+      },
+    },
+  ]
+
+  const importTypeJson = {
+    name: "jsenv:import_type_json",
+    appliesDuring: "*",
+    finalize: ({ url, contentType, content }) => {
+      if (!new URL(url).searchParams.has("json_module")) {
+        return null
+      }
+      if (contentType !== "application/json") {
+        throw new Error(
+          `Unexpected content type on ${url}, should be "application/json" but got ${contentType}`,
+        )
+      }
+      return convertJsonTextToJavascriptModule({
+        content,
+      })
+    },
+  }
+
+  // not standard but I expect this to happen one day?
+  const importTypeText = {
+    name: "jsenv:import_type_text",
+    appliesDuring: "*",
+    finalize: ({ url, contentType, content }) => {
+      if (!new URL(url).searchParams.has("text_module")) {
+        return null
+      }
+      if (ContentType.isTextual(contentType)) {
+        throw new Error(
+          `Unexpected content type on ${url}, should be "text/*" but got ${contentType}`,
+        )
+      }
+      return convertTextToJavascriptModule({
+        content,
+      })
+    },
+  }
+
+  return [
+    importAssertions,
+    importTypeJson,
+    jsenvPluginImportTypeCss(),
+    importTypeText,
+  ]
+}
+
+const jsenvPluginImportTypeCss = () => {
+  const inlineContentClientFileUrl = new URL(
+    "../inline/client/inline_content.js",
+    import.meta.url,
+  ).href
+
+  return {
+    name: "jsenv:import_type_css",
+    appliesDuring: "*",
+    // load the original css url
+    load: ({ data }, { urlGraph, load }) => {
+      if (data.importType !== "css_module") {
+        return null
+      }
+      return load({
+        reference: data.originalReference,
+        urlInfo: urlGraph.getUrlInfo(data.originalReference.url),
+      })
+    },
+    transform: ({ url, data, contentType, content }, { referenceUtils }) => {
+      if (data.importType !== "css_module") {
+        return null
+      }
+      if (contentType !== "text/css") {
+        throw new Error(
+          `Unexpected content type on ${url}, should be "text/css" but got ${contentType}`,
+        )
+      }
+      const [reference] = referenceUtils.inject({
+        type: "js_import_export",
+        specifier: inlineContentClientFileUrl,
+      })
+      const cssText = JS_QUOTES.escapeSpecialChars(content, {
+        // If template string is choosen and runtime do not support template literals
+        // it's ok because "jsenv:new_inline_content" plugin executes after this one
+        // and convert template strings into raw strings
+        canUseTemplateString: true,
+      })
+      return {
+        type: "js_module",
+        contentType: "application/javascript",
+        content: `import { InlineContent } from ${reference.generatedSpecifier}
+
+const css = new InlineContent(${cssText}, { type: "text/css" })
+const stylesheet = new CSSStyleSheet()
+stylesheet.replaceSync(css.text)
+export default stylesheet`,
+      }
+    },
+  }
+}
+
+const getImportTypesToHandle = ({ scenario, isSupportedOnRuntime }) => {
+  // during build always replace import assertions with the js:
+  // - means rollup can bundle more js file together
+  // - means url versioning can work for css inlined in js
+  // - avoid rollup to see import assertions
+  //   We would have to tell rollup to ignore import with assertion
+  if (scenario === "build") {
+    return ["json", "css", "text"]
+  }
+  const importTypes = []
+  if (!isSupportedOnRuntime("import_type_json")) {
+    importTypes.push("json")
+  }
+  if (!isSupportedOnRuntime("import_type_css")) {
+    importTypes.push("css")
+  }
+  if (!isSupportedOnRuntime("import_type_text")) {
+    importTypes.push("text")
+  }
+  return importTypes
+}

package/src/omega/core_plugins/import_meta_scenarios/jsenv_plugin_import_meta_scenarios.js

@@ -0,0 +1,80 @@
+/*
+ * Source code can contain the following
+ * - import.meta.dev
+ * - import.meta.test
+ * - import.meta.build
+ * They are either:
+ * - replaced by true: When scenario matches (import.meta.dev and it's the dev server)
+ * - left as is to be evaluated to undefined (import.meta.test but it's the dev server)
+ * - replaced by undefined (import.meta.dev but it's build; the goal is to ensure it's tree-shaked)
+ */
+
+import { applyBabelPlugins } from "@jsenv/utils/js_ast/apply_babel_plugins.js"
+import { createMagicSource } from "@jsenv/utils/sourcemap/magic_source.js"
+
+import { collectProgramImportMetas } from "@jsenv/utils/js_ast/program_import_metas.js"
+
+export const jsenvPluginImportMetaScenarios = () => {
+  return {
+    name: "jsenv:import_meta_scenario",
+    appliesDuring: "*",
+    transform: {
+      js_module: async ({ url, content }, { scenario }) => {
+        const { metadata } = await applyBabelPlugins({
+          babelPlugins: [babelPluginMetadataImportMetaScenarios],
+          url,
+          content,
+        })
+        const { dev = [], test = [], build = [] } = metadata.importMetaScenarios
+        const replacements = []
+        const replace = (path, value) => {
+          replacements.push({ path, value })
+        }
+        if (scenario === "dev") {
+          dev.forEach((path) => {
+            replace(path, true)
+          })
+        } else if (scenario === "test") {
+          test.forEach((path) => {
+            replace(path, true)
+          })
+        } else if (scenario === "build") {
+          dev.forEach((path) => {
+            replace(path, undefined)
+          })
+          test.forEach((path) => {
+            replace(path, undefined)
+          })
+          build.forEach((path) => {
+            replace(path, true)
+          })
+        }
+        const magicSource = createMagicSource(content)
+        replacements.forEach(({ path, value }) => {
+          magicSource.overwrite({
+            start: path.node.start,
+            end: path.node.end,
+            replacement: value,
+          })
+        })
+        return magicSource.toContentAndSourcemap()
+      },
+    },
+  }
+}
+
+const babelPluginMetadataImportMetaScenarios = () => {
+  return {
+    name: "metadata-import-meta-scenarios",
+    visitor: {
+      Program(programPath, state) {
+        const importMetas = collectProgramImportMetas(programPath)
+        state.file.metadata.importMetaScenarios = {
+          dev: importMetas.dev,
+          test: importMetas.test,
+          build: importMetas.build,
+        }
+      },
+    },
+  }
+}

package/src/omega/core_plugins/importmap/jsenv_plugin_importmap.js

@@ -0,0 +1,212 @@
+/*
+ * Plugin to read and apply importmap files found in html files.
+ * - feeds importmap files to jsenv kitchen
+ * - use importmap to resolve import (when there is one + fallback to other resolution mecanism)
+ * - inline importmap with [src=""]
+ *
+ * A correct importmap resolution should scope importmap resolution per html file.
+ * It would be doable by adding ?html_id to each js file in order to track
+ * the html file importing it.
+ * Considering it happens only when all the following conditions are met:
+ * - 2+ html files are using an importmap
+ * - the importmap used is not the same
+ * - the importmap contain conflicting mappings
+ * - these html files are both executed during the same scenario (dev, test, build)
+ * And that it would be ugly to see ?html_id all over the place
+ * -> The importmap resolution implemented here takes a shortcut and does the following:
+ * - All importmap found are merged into a single one that is applied to every import specifiers
+ */
+
+import {
+  resolveImport,
+  composeTwoImportMaps,
+  normalizeImportMap,
+} from "@jsenv/importmap"
+
+import {
+  parseHtmlString,
+  stringifyHtmlAst,
+  findNode,
+  getHtmlNodeAttributeByName,
+  htmlNodePosition,
+  removeHtmlNodeAttributeByName,
+  setHtmlNodeText,
+  assignHtmlNodeAttributes,
+  getHtmlNodeTextNode,
+  removeHtmlNode,
+} from "@jsenv/utils/html_ast/html_ast.js"
+import { generateInlineContentUrl } from "@jsenv/core/packages/utils/urls/inline_content_url_generator.js"
+
+export const jsenvPluginImportmap = () => {
+  let finalImportmap = null
+  const importmaps = {}
+  const onHtmlImportmapParsed = (importmap, htmlUrl) => {
+    importmaps[htmlUrl] = importmap
+      ? normalizeImportMap(importmap, htmlUrl)
+      : null
+    finalImportmap = Object.keys(importmaps).reduce((previous, url) => {
+      const importmap = importmaps[url]
+      if (!previous) {
+        return importmap
+      }
+      if (!importmap) {
+        return previous
+      }
+      return composeTwoImportMaps(previous, importmap)
+    }, null)
+  }
+
+  return {
+    name: "jsenv:importmap",
+    appliesDuring: "*",
+    resolve: {
+      js_import_export: ({ parentUrl, specifier }) => {
+        if (!finalImportmap) {
+          return null
+        }
+        try {
+          let fromMapping = false
+          const result = resolveImport({
+            specifier,
+            importer: parentUrl,
+            importMap: finalImportmap,
+            onImportMapping: () => {
+              fromMapping = true
+            },
+          })
+          if (fromMapping) {
+            return result
+          }
+          return null
+        } catch (e) {
+          if (e.message.includes("bare specifier")) {
+            // in theory we should throw to be compliant with web behaviour
+            // but for now it's simpler to return null
+            // and let a chance to other plugins to handle the bare specifier
+            // (node esm resolution)
+            // and we want importmap to be prio over node esm so we cannot put this plugin after
+            return null
+          }
+          throw e
+        }
+      },
+    },
+    transform: {
+      html: async (
+        { url, content, references },
+        { scenario, cook, urlGraph, referenceUtils },
+      ) => {
+        const htmlAst = parseHtmlString(content)
+        const importmap = findNode(htmlAst, (node) => {
+          if (node.nodeName !== "script") {
+            return false
+          }
+          const typeAttribute = getHtmlNodeAttributeByName(node, "type")
+          if (!typeAttribute || typeAttribute.value !== "importmap") {
+            return false
+          }
+          return true
+        })
+        if (!importmap) {
+          onHtmlImportmapParsed(null, url)
+          return null
+        }
+        const handleInlineImportmap = async (importmap, textNode) => {
+          const { line, column, lineEnd, columnEnd, isOriginal } =
+            htmlNodePosition.readNodePosition(importmap, {
+              preferOriginal: true,
+            })
+          const inlineImportmapUrl = generateInlineContentUrl({
+            url,
+            extension: ".importmap",
+            line,
+            column,
+            lineEnd,
+            columnEnd,
+          })
+          const [inlineImportmapReference, inlineImportmapUrlInfo] =
+            referenceUtils.foundInline({
+              type: "script_src",
+              line: line - 1,
+              column,
+              isOriginal,
+              specifier: inlineImportmapUrl,
+              contentType: "application/importmap+json",
+              content: textNode.value,
+            })
+          await cook({
+            reference: inlineImportmapReference,
+            urlInfo: inlineImportmapUrlInfo,
+          })
+          setHtmlNodeText(importmap, inlineImportmapUrlInfo.content)
+          onHtmlImportmapParsed(JSON.parse(inlineImportmapUrlInfo.content), url)
+        }
+        const handleImportmapWithSrc = async (importmap, src) => {
+          // Browser would throw on remote importmap
+          // and won't sent a request to the server for it
+          // We must precook the importmap to know its content and inline it into the HTML
+          // In this situation the ref to the importmap was already discovered
+          // when parsing the HTML
+          const importmapReference = references.find(
+            (reference) => reference.url === src,
+          )
+          const importmapUrlInfo = urlGraph.getUrlInfo(importmapReference.url)
+          await cook({
+            reference: importmapReference,
+            urlInfo: importmapUrlInfo,
+          })
+          onHtmlImportmapParsed(JSON.parse(importmapUrlInfo.content), url)
+          removeHtmlNodeAttributeByName(importmap, "src")
+          assignHtmlNodeAttributes(importmap, {
+            "content-src": src,
+            "inlined-by": "jsenv:importmap",
+          })
+          setHtmlNodeText(importmap, importmapUrlInfo.content)
+
+          const { line, column, lineEnd, columnEnd, isOriginal } =
+            htmlNodePosition.readNodePosition(importmap, {
+              preferOriginal: true,
+            })
+          const inlineImportmapUrl = generateInlineContentUrl({
+            url,
+            extension: ".importmap",
+            line,
+            column,
+            lineEnd,
+            columnEnd,
+          })
+          referenceUtils.becomesInline(importmapReference, {
+            line: line - 1,
+            column,
+            isOriginal,
+            specifier: inlineImportmapUrl,
+            contentType: "application/importmap+json",
+            content: importmapUrlInfo.content,
+          })
+        }
+
+        const srcAttribute = getHtmlNodeAttributeByName(importmap, "src")
+        const src = srcAttribute ? srcAttribute.value : undefined
+        if (src) {
+          await handleImportmapWithSrc(importmap, src)
+        } else {
+          const textNode = getHtmlNodeTextNode(importmap)
+          if (textNode) {
+            await handleInlineImportmap(importmap, textNode)
+          }
+        }
+        // once this plugin knows the importmap, it will use it
+        // to map imports. These import specifiers will be normalized
+        // by "formatReferencedUrl" making the importmap presence useless.
+        // In dev/test we keep importmap into the HTML to see it even if useless
+        // Duing build we get rid of it
+        if (scenario === "build") {
+          removeHtmlNode(importmap)
+        }
+        return {
+          content: stringifyHtmlAst(htmlAst),
+        }
+      },
+    },
+  }
+}

package/src/omega/core_plugins/inline/client/inline_content.js

@@ -0,0 +1,6 @@
+function InlineContent(content, { type = "text/plain" }) {
+  this.text = content
+  this.type = type
+}
+
+export { InlineContent }

package/src/omega/core_plugins/inline/jsenv_plugin_data_urls.js

@@ -0,0 +1,70 @@
+import { DataUrl } from "@jsenv/utils/urls/data_url.js"
+import { ContentType } from "@jsenv/utils/src/content_type.js"
+
+export const jsenvPluginDataUrls = () => {
+  return {
+    name: "jsenv:data_urls",
+    appliesDuring: "*",
+    resolve: ({ specifier }) => {
+      if (!specifier.startsWith("data:")) {
+        return null
+      }
+      return specifier
+    },
+    load: ({ url, data }) => {
+      if (!url.startsWith("data:")) {
+        return null
+      }
+      const { contentType, base64Flag, data: urlData } = DataUrl.parse(url)
+      data.base64Flag = base64Flag
+      return {
+        contentType,
+        content: contentFromUrlData({ contentType, base64Flag, urlData }),
+      }
+    },
+    formatReferencedUrl: (reference, { urlGraph, cook }) => {
+      if (!reference.url.startsWith("data:")) {
+        return null
+      }
+      if (reference.type === "sourcemap_comment") {
+        return null
+      }
+      return (async () => {
+        const urlInfo = urlGraph.getUrlInfo(reference.url)
+        await cook({
+          reference,
+          urlInfo,
+        })
+        if (urlInfo.originalContent === urlInfo.content) {
+          return reference.url
+        }
+        const specifier = DataUrl.stringify({
+          contentType: urlInfo.contentType,
+          base64Flag: urlInfo.data.base64Flag,
+          data: urlInfo.data.base64Flag
+            ? dataToBase64(urlInfo.content)
+            : String(urlInfo.content),
+        })
+        return specifier
+      })()
+    },
+  }
+}
+
+const contentFromUrlData = ({ contentType, base64Flag, urlData }) => {
+  if (ContentType.isTextual(contentType)) {
+    if (base64Flag) {
+      return base64ToString(urlData)
+    }
+    return urlData
+  }
+  if (base64Flag) {
+    return base64ToBuffer(urlData)
+  }
+  return Buffer.from(urlData)
+}
+
+const base64ToBuffer = (base64String) => Buffer.from(base64String, "base64")
+const base64ToString = (base64String) =>
+  Buffer.from(base64String, "base64").toString("utf8")
+const dataToBase64 = (data) => Buffer.from(data).toString("base64")