@jsenv/core 26.0.1 → 27.0.0-alpha.2

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

@@ -0,0 +1,210 @@
+/*
+ * Needs to be updated so that it sill works in the following cases:
+ * - templates literals transformed to regular stuff by babel
+ * - tagged name renamed by rollup
+ * - the template named is minified by terser
+ * In the cases above I must remain capable to recoginize the template literal
+ * to be able to update the urls inside (and even version the urls)
+ * because url versioning happens after minification it can be challenging
+ *
+ * TODO: use "keep_classnames" https://github.com/terser/terser#compress-options
+ * so that new InlineContent can be recognized after minification
+ */
+
+import { createMagicSource } from "@jsenv/utils/sourcemap/magic_source.js"
+import { JS_QUOTES } from "@jsenv/utils/string/js_quotes.js"
+import { applyBabelPlugins } from "@jsenv/utils/js_ast/apply_babel_plugins.js"
+import { generateInlineContentUrl } from "@jsenv/utils/urls/inline_content_url_generator.js"
+
+export const jsenvPluginNewInlineContent = ({ allowEscapeForVersioning }) => {
+  return {
+    name: "jsenv:new_inline_content",
+    appliesDuring: "*",
+    transform: {
+      js_module: async (
+        { url, generatedUrl, content, originalContent },
+        { referenceUtils, cook, isSupportedOnRuntime },
+      ) => {
+        const { metadata } = await applyBabelPlugins({
+          babelPlugins: [babelPluginMetadataInlineContentCalls],
+          url,
+          generatedUrl,
+          content,
+        })
+        const { inlineContentCalls } = metadata
+        if (inlineContentCalls.length === 0) {
+          return null
+        }
+        const magicSource = createMagicSource(content)
+        await inlineContentCalls.reduce(async (previous, inlineContentCall) => {
+          await previous
+          const inlineUrl = generateInlineContentUrl({
+            url,
+            extension: {
+              "application/json": ".json",
+              "text/css": ".css",
+              "text/plain": ".txt",
+              "application/octet-stream": "",
+            }[inlineContentCall.contentType],
+            line: inlineContentCall.line,
+            column: inlineContentCall.column,
+            lineEnd: inlineContentCall.lineEnd,
+            columnEnd: inlineContentCall.columnEnd,
+          })
+          let { quote } = inlineContentCall
+          if (
+            quote === "`" &&
+            !isSupportedOnRuntime("transform-template-literals")
+          ) {
+            // if quote is "`" and template literals are not supported
+            // we'll use a regular string (single or double quote)
+            // when rendering the string
+            quote = JS_QUOTES.pickBest(inlineContentCall.content)
+          }
+          const [inlineReference, inlineUrlInfo] = referenceUtils.foundInline({
+            type: "js_inline_content",
+            isOriginal: content === originalContent,
+            line: inlineContentCall.line,
+            column: inlineContentCall.column,
+            specifier: inlineUrl,
+            contentType: inlineContentCall.contentType,
+            content: inlineContentCall.content,
+          })
+          inlineUrlInfo.jsQuote = quote
+          inlineReference.escape = (value) =>
+            JS_QUOTES.escapeSpecialChars(value.slice(1, -1), { quote })
+          await cook({
+            reference: inlineReference,
+            urlInfo: inlineUrlInfo,
+          })
+          magicSource.replace({
+            start: inlineContentCall.start,
+            end: inlineContentCall.end,
+            replacement: JS_QUOTES.escapeSpecialChars(inlineUrlInfo.content, {
+              quote,
+              allowEscapeForVersioning,
+            }),
+          })
+        }, Promise.resolve())
+        return magicSource.toContentAndSourcemap()
+      },
+    },
+  }
+}
+
+const babelPluginMetadataInlineContentCalls = () => {
+  return {
+    name: "metadata-inline-content-calls",
+    visitor: {
+      Program: (programPath, state) => {
+        const inlineContentCalls = []
+        programPath.traverse({
+          NewExpression: (path) => {
+            const newInlineContentCall = parseAsNewInlineContentCall(path)
+            if (newInlineContentCall) {
+              inlineContentCalls.push(newInlineContentCall)
+            }
+          },
+        })
+        state.file.metadata.inlineContentCalls = inlineContentCalls
+      },
+    },
+  }
+}
+
+const parseAsNewInlineContentCall = (path) => {
+  const node = path.node
+  if (node.callee.type === "Identifier") {
+    // terser rename import to use a shorter name
+    const name = getOriginalName(path, node.callee.name)
+    if (name !== "InlineContent") {
+      return null
+    }
+  } else if (node.callee.id) {
+    // terser might combine new InlineContent('') declaration and usage
+    if (node.callee.id.type !== "Identifier") {
+      return null
+    }
+    const name = getOriginalName(path, node.callee.id.name)
+    if (name !== "InlineContent") {
+      return null
+    }
+  }
+  if (node.arguments.length !== 2) {
+    return null
+  }
+  const [firstArg, secondArg] = node.arguments
+  if (secondArg.type !== "ObjectExpression") {
+    return null
+  }
+  const typePropertyNode = secondArg.properties.find((property) => {
+    return (
+      property.key.type === "Identifier" &&
+      property.key.name === "type" &&
+      property.type === "ObjectProperty" &&
+      property.value.type === "StringLiteral"
+    )
+  })
+  if (!typePropertyNode) {
+    return null
+  }
+  const type = typePropertyNode.value.value
+  if (firstArg.type === "StringLiteral") {
+    const position = getNodePosition(firstArg)
+    return {
+      nodeType: "StringLiteral",
+      quote: firstArg.extra.raw[0],
+      contentType: type,
+      content: firstArg.value,
+      ...position,
+    }
+  }
+  if (firstArg.type === "TemplateLiteral") {
+    const quasis = firstArg.quasis
+    if (quasis.length !== 1) {
+      return null
+    }
+    const templateElementNode = quasis[0]
+    const position = getNodePosition(firstArg)
+    return {
+      nodeType: "TemplateLiteral",
+      quote: "`",
+      contentType: type,
+      content: templateElementNode.value.cooked,
+      ...position,
+    }
+  }
+  return null
+}
+
+const getNodePosition = (node) => {
+  return {
+    start: node.start,
+    end: node.end,
+    line: node.loc.start.line,
+    column: node.loc.start.column,
+    lineEnd: node.loc.end.line,
+    columnEnd: node.loc.end.column,
+  }
+}
+
+const getOriginalName = (path, name) => {
+  const binding = path.scope.getBinding(name)
+  if (!binding) {
+    return name
+  }
+  if (binding.path.type === "ImportSpecifier") {
+    const importedName = binding.path.node.imported.name
+    if (name === importedName) {
+      return name
+    }
+    return getOriginalName(path, importedName)
+  }
+  if (binding.path.type === "VariableDeclarator") {
+    if (binding.path.node.init.type === "Identifier") {
+      const previousName = binding.path.node.init.name
+      return getOriginalName(path, previousName)
+    }
+  }
+  return name
+}

package/src/omega/core_plugins/leading_slash/jsenv_plugin_leading_slash.js

@@ -0,0 +1,12 @@
+export const jsenvPluginLeadingSlash = () => {
+  return {
+    name: "jsenv:leading_slash",
+    appliesDuring: "*",
+    resolve: ({ specifier }, { rootDirectoryUrl }) => {
+      if (specifier[0] !== "/") {
+        return null
+      }
+      return new URL(specifier.slice(1), rootDirectoryUrl).href
+    },
+  }
+}

package/src/omega/core_plugins/node_esm_resolution/jsenv_plugin_node_esm_resolution.js

@@ -0,0 +1,77 @@
+/*
+ * - should I restore eventual search params lost during node esm resolution
+ * - what about symlinks?
+ *   It feels like I should apply symlink (when we don't want to preserve them)
+ *   once a file:/// url is found, regardless
+ *   if that comes from node resolution or anything else (not even magic resolution)
+ *   it should likely be an other plugin happening after the others
+ */
+
+import {
+  applyNodeEsmResolution,
+  lookupPackageScope,
+  readPackageJson,
+} from "@jsenv/node-esm-resolution"
+
+export const jsenvPluginNodeEsmResolution = ({
+  // https://nodejs.org/api/esm.html#resolver-algorithm-specification
+  packageConditions = ["browser", "import"],
+} = {}) => {
+  const nodeEsmResolution = {
+    name: "jsenv:node_esm_resolve",
+    appliesDuring: "*",
+    resolve: {
+      js_import_export: ({ parentUrl, specifier }) => {
+        const { url } = applyNodeEsmResolution({
+          conditions: packageConditions,
+          parentUrl,
+          specifier,
+        })
+        return url
+      },
+    },
+    load: ({ url }) => {
+      if (url.startsWith("file:///@ignore/")) {
+        return {
+          content: "export default {}",
+        }
+      }
+      return null
+    },
+  }
+
+  const packageVersionInUrl = {
+    name: "jsenv:package_url_version",
+    appliesDuring: {
+      dev: true,
+      test: true,
+    },
+    transformReferencedUrl: ({ url }, { rootDirectoryUrl }) => {
+      if (!url.startsWith("file:")) {
+        return null
+      }
+      // without this check a file inside a project without package.json
+      // could be considered as a node module if there is a ancestor package.json
+      // but we want to version only node modules
+      if (!url.includes("/node_modules/")) {
+        return null
+      }
+      const urlObject = new URL(url)
+      if (urlObject.searchParams.has("v")) {
+        return null
+      }
+      const packageUrl = lookupPackageScope(url)
+      if (!packageUrl) {
+        return null
+      }
+      if (packageUrl === rootDirectoryUrl) {
+        return null
+      }
+      const packageVersion = readPackageJson(packageUrl).version
+      urlObject.searchParams.set("v", packageVersion)
+      return urlObject.href
+    },
+  }
+
+  return [nodeEsmResolution, packageVersionInUrl]
+}

package/src/omega/core_plugins/url_resolution/jsenv_plugin_url_resolution.js

@@ -0,0 +1,28 @@
+export const jsenvPluginUrlResolution = () => {
+  const urlResolver = ({ parentUrl, specifier }) => {
+    return new URL(specifier, parentUrl).href
+  }
+  return {
+    name: "jsenv:url_resolution",
+    appliesDuring: "*",
+    resolve: {
+      "entry_point": urlResolver,
+      "js_import_export": urlResolver,
+      "link_href": urlResolver,
+      "script_src": urlResolver,
+      "a_href": urlResolver,
+      "iframe_src": urlResolver,
+      "img_src": urlResolver,
+      "img_srcset": urlResolver,
+      "source_src": urlResolver,
+      "source_srcset": urlResolver,
+      "image_href": urlResolver,
+      "use_href": urlResolver,
+      "css_@import": urlResolver,
+      "css_url": urlResolver,
+      "sourcemap_comment": urlResolver,
+      "js_import_meta_url_pattern": urlResolver,
+      "js_inline_content": urlResolver,
+    },
+  }
+}

package/src/omega/core_plugins/url_version/jsenv_plugin_url_version.js

@@ -0,0 +1,50 @@
+export const jsenvPluginUrlVersion = ({
+  longTermCache = false, // will become true once things get more stable
+} = {}) => {
+  return {
+    name: "jsenv:url_version",
+    appliesDuring: "*", // maybe only during dev?
+    normalize: ({ url }) => {
+      // "v" search param goal is to enable long-term cache
+      // for server response headers
+      // it is also used by hmr to bypass browser cache
+      // this goal is achieved when we reach this part of the code
+      // We get rid of this params so that urlGraph and other parts of the code
+      // recognize the url (it is not considered as a different url)
+      const urlObject = new URL(url)
+      urlObject.searchParams.delete("v")
+      return urlObject.href
+    },
+    transformReferencedUrl: ({ url, data }) => {
+      if (!data.version) {
+        return null
+      }
+      const urlObject = new URL(url)
+      if (urlObject.searchParams.has("v")) {
+        return null
+      }
+      urlObject.searchParams.set("v", data.version)
+      return urlObject.href
+    },
+    augmentResponse: ({ url }) => {
+      if (!longTermCache) {
+        return null
+      }
+      const urlObject = new URL(url)
+      if (!urlObject.searchParams.has("v")) {
+        return null
+      }
+      if (urlObject.searchParams.has("hmr")) {
+        return null
+      }
+      // When url is versioned put it in browser cache for 30 days
+      return {
+        headers: {
+          "cache-control": `private,max-age=${SECONDS_IN_30_DAYS},immutable`,
+        },
+      }
+    },
+  }
+}
+
+const SECONDS_IN_30_DAYS = 60 * 60 * 24 * 30

package/src/omega/core_plugins.js

@@ -0,0 +1,39 @@
+import { jsenvPluginLeadingSlash } from "./core_plugins/leading_slash/jsenv_plugin_leading_slash.js"
+import { jsenvPluginImportmap } from "./core_plugins/importmap/jsenv_plugin_importmap.js"
+import { jsenvPluginUrlResolution } from "./core_plugins/url_resolution/jsenv_plugin_url_resolution.js"
+import { jsenvPluginNodeEsmResolution } from "./core_plugins/node_esm_resolution/jsenv_plugin_node_esm_resolution.js"
+import { jsenvPluginUrlVersion } from "./core_plugins/url_version/jsenv_plugin_url_version.js"
+import { jsenvPluginFileUrls } from "./core_plugins/file_urls/jsenv_plugin_file_urls.js"
+import { jsenvPluginFileSystemMagic } from "./core_plugins/filesystem_magic/jsenv_plugin_filesystem_magic.js"
+import { jsenvPluginInline } from "./core_plugins/inline/jsenv_plugin_inline.js"
+import { jsenvPluginHtmlSupervisor } from "./core_plugins/html_supervisor/jsenv_plugin_html_supervisor.js"
+import { jsenvPluginCommonJsGlobals } from "./core_plugins/commonjs_globals/jsenv_plugin_commonjs_globals.js"
+import { jsenvPluginImportAssertions } from "./core_plugins/import_assertions/jsenv_plugin_import_assertions.js"
+import { jsenvPluginImportMetaScenarios } from "./core_plugins/import_meta_scenarios/jsenv_plugin_import_meta_scenarios.js"
+import { jsenvPluginBabel } from "./core_plugins/babel/jsenv_plugin_babel.js"
+
+export const getCorePlugins = ({
+  htmlSupervisor,
+  nodeEsmResolution,
+  fileSystemMagicResolution,
+  babel,
+} = {}) => {
+  const asFewAsPossible = false // useful during dev
+  return [
+    ...(asFewAsPossible ? [] : [jsenvPluginImportAssertions()]),
+    ...(asFewAsPossible ? [] : [jsenvPluginHtmlSupervisor(htmlSupervisor)]), // before inline as it turns inline <script> into <script src>
+    ...(asFewAsPossible ? [] : [jsenvPluginInline()]), // before "file urls" to resolve and load inline urls
+    jsenvPluginImportmap(), // before node esm to handle bare specifiers before node esm
+    jsenvPluginFileUrls(),
+    jsenvPluginLeadingSlash(),
+    jsenvPluginNodeEsmResolution(nodeEsmResolution), // before url resolution to handle "js_import_export" resolution
+    jsenvPluginUrlResolution(),
+    ...(asFewAsPossible
+      ? []
+      : [jsenvPluginFileSystemMagic(fileSystemMagicResolution)]),
+    jsenvPluginUrlVersion(),
+    ...(asFewAsPossible ? [] : [jsenvPluginCommonJsGlobals()]),
+    ...(asFewAsPossible ? [] : [jsenvPluginImportMetaScenarios()]),
+    jsenvPluginBabel(babel),
+  ]
+}

package/src/omega/errors.js

@@ -0,0 +1,168 @@
+import { createDetailedMessage } from "@jsenv/logger"
+
+export const createResolveError = ({ pluginController, reference, error }) => {
+  const createFailedToResolveError = ({
+    code = error.code || "RESOLVE_ERROR",
+    reason,
+    ...details
+  }) => {
+    const resolveError = new Error(
+      createDetailedMessage(`Failed to resolve specifier`, {
+        reason,
+        ...details,
+        "specifier": `"${reference.specifier}"`,
+        "specifier trace": reference.trace,
+        ...detailsFromPluginController(pluginController),
+      }),
+    )
+    resolveError.name = "RESOLVE_ERROR"
+    resolveError.code = code
+    resolveError.reason = reason
+    return resolveError
+  }
+  if (error.message === "NO_RESOLVE") {
+    return createFailedToResolveError({
+      reason: `no plugin has handled the specifier during "resolve" hook`,
+    })
+  }
+  return createFailedToResolveError({
+    reason: `An error occured during specifier resolution`,
+    ...detailsFromValueThrown(error),
+  })
+}
+
+export const createLoadError = ({
+  pluginController,
+  reference,
+  urlInfo,
+  error,
+}) => {
+  const createFailedToLoadError = ({
+    code = error.code || "LOAD_ERROR",
+    reason,
+    ...details
+  }) => {
+    const loadError = new Error(
+      createDetailedMessage(`Failed to load url`, {
+        reason,
+        ...details,
+        "url": urlInfo.url,
+        "url reference trace": reference.trace,
+        ...detailsFromPluginController(pluginController),
+      }),
+    )
+    loadError.name = "LOAD_ERROR"
+    loadError.code = code
+    loadError.reason = reason
+    return loadError
+  }
+
+  if (error.message === "NO_LOAD") {
+    return createFailedToLoadError({
+      code: "NOT_FOUND",
+      reason: `no plugin has handled the url during "load" hook`,
+    })
+  }
+  if (error.code === "EPERM") {
+    return createFailedToLoadError({
+      code: "NOT_ALLOWED",
+      reason: `not allowed to read entry on filesystem`,
+    })
+  }
+  if (error.code === "EISDIR") {
+    return createFailedToLoadError({
+      code: "EISDIR",
+      reason: `found a directory on filesystem`,
+    })
+  }
+  if (error.code === "ENOENT") {
+    return createFailedToLoadError({
+      code: "NOT_FOUND",
+      reason: "no entry on filesystem",
+    })
+  }
+  return createFailedToLoadError({
+    reason: `An error occured during "load"`,
+    ...detailsFromValueThrown(error),
+  })
+}
+
+export const createParseError = ({ reference, urlInfo, error }) => {
+  const createFailedToParseError = ({
+    code = error.code || "PARSE_ERROR",
+    reason,
+    ...details
+  }) => {
+    const parseError = new Error(
+      createDetailedMessage(`Failed to parse ${urlInfo.type}`, {
+        reason,
+        ...details,
+        "url": urlInfo.url,
+        "url reference trace": reference.trace,
+      }),
+    )
+    parseError.name = "PARSE_ERROR"
+    parseError.code = code
+    parseError.reason = reason
+    return parseError
+  }
+  return createFailedToParseError({
+    reason: `An error occured while parsing content`,
+    ...detailsFromValueThrown(error),
+  })
+}
+
+export const createTransformError = ({
+  pluginController,
+  reference,
+  urlInfo,
+  error,
+}) => {
+  const createFailedToTransformError = ({
+    code = error.code || "TRANSFORM_ERROR",
+    reason,
+    ...details
+  }) => {
+    const transformError = new Error(
+      createDetailedMessage(`Failed to transform ${urlInfo.type}`, {
+        reason,
+        ...details,
+        "url": urlInfo.url,
+        "url reference trace": reference.trace,
+        ...detailsFromPluginController(pluginController),
+      }),
+    )
+    transformError.name = "TRANSFORM_ERROR"
+    transformError.code = code
+    transformError.reason = reason
+    return transformError
+  }
+  return createFailedToTransformError({
+    reason: `An error occured during "transform"`,
+    ...detailsFromValueThrown(error),
+  })
+}
+
+const detailsFromPluginController = (pluginController) => {
+  const currentPlugin = pluginController.getCurrentPlugin()
+  if (!currentPlugin) {
+    return null
+  }
+  return { "plugin name": `"${currentPlugin.name}"` }
+}
+
+const detailsFromValueThrown = (valueThrownByPlugin) => {
+  if (valueThrownByPlugin && valueThrownByPlugin instanceof Error) {
+    return {
+      "error stack": valueThrownByPlugin.stack,
+    }
+  }
+  if (valueThrownByPlugin === undefined) {
+    return {
+      error: "undefined",
+    }
+  }
+  return {
+    error: JSON.stringify(valueThrownByPlugin),
+  }
+}

package/src/omega/file_url_converter.js

@@ -0,0 +1,63 @@
+import { fileSystemPathToUrl, urlToFileSystemPath } from "@jsenv/filesystem"
+
+export const fileUrlConverter = {
+  asUrlWithoutSpecialParams: (fileUrl) => {
+    const urlObject = new URL(fileUrl)
+    let { origin, pathname, searchParams, hash } = urlObject
+    // origin is "null" for "file://" urls with Node.js
+    if (origin === "null" && urlObject.href.startsWith("file:")) {
+      origin = "file://"
+    }
+    if (searchParams.has("json_module")) {
+      searchParams.delete("json_module")
+      return `${origin}${pathname}.json_module${stringifyQuery(
+        searchParams,
+      )}${hash}`
+    }
+    if (searchParams.has("css_module")) {
+      searchParams.delete("css_module")
+      return `${origin}${pathname}.css_module${stringifyQuery(
+        searchParams,
+      )}${hash}`
+    }
+    if (searchParams.has("text_module")) {
+      searchParams.delete("text_module")
+      return `${origin}${pathname}.text_module${stringifyQuery(
+        searchParams,
+      )}${hash}`
+    }
+    return fileUrl
+  },
+  asFilePath: (fileUrl) => {
+    const fileUrlWithoutSpecialParam =
+      fileUrlConverter.asUrlWithoutSpecialParams(fileUrl)
+    const filePath = urlToFileSystemPath(fileUrlWithoutSpecialParam)
+    return filePath
+  },
+  asFileUrl: (filePath) => {
+    if (filePath.endsWith(".json_module")) {
+      const jsonFileUrl = fileSystemPathToUrl(
+        filePath.slice(0, -".json_module".length),
+      )
+      return `${jsonFileUrl}?json_module`
+    }
+    if (filePath.endsWith(".css_module")) {
+      const cssFileUrl = fileSystemPathToUrl(
+        filePath.slice(0, -".css_module".length),
+      )
+      return `${cssFileUrl}?css_module`
+    }
+    if (filePath.endsWith(".text_module")) {
+      const textFileUrl = fileSystemPathToUrl(
+        filePath.slice(0, -".text_module".length),
+      )
+      return `${textFileUrl}?text_module`
+    }
+    return fileSystemPathToUrl(filePath)
+  },
+}
+
+const stringifyQuery = (searchParams) => {
+  const search = searchParams.toString()
+  return search ? `?${search}` : ""
+}