@jsenv/core 33.0.2 → 34.0.1

package/src/plugins/supervisor/html_supervisor_injection.js

@@ -0,0 +1,281 @@
+/*
+ * Jsenv needs to track js execution in order to:
+ * 1. report errors
+ * 2. wait for all js execution inside an HTML page before killing the browser
+ *
+ * A naive approach would rely on "load" events on window but:
+ * scenario                                    | covered by window "load"
+ * ------------------------------------------- | -------------------------
+ * js referenced by <script src>               | yes
+ * js inlined into <script>                    | yes
+ * js referenced by <script type="module" src> | partially (not for import and top level await)
+ * js inlined into <script type="module">      | not at all
+ * Same for "error" event on window who is not enough
+ *
+ * <script src="file.js">
+ * becomes
+ * <script>
+ *   window.__supervisor__.superviseScript('file.js')
+ * </script>
+ *
+ * <script>
+ *    console.log(42)
+ * </script>
+ * becomes
+ * <script inlined-from-src="main.html@L10-C5.js">
+ *   window.__supervisor.__superviseScript("main.html@L10-C5.js")
+ * </script>
+ *
+ * <script type="module" src="module.js"></script>
+ * becomes
+ * <script type="module">
+ *   window.__supervisor__.superviseScriptTypeModule('module.js')
+ * </script>
+ *
+ * <script type="module">
+ *   console.log(42)
+ * </script>
+ * becomes
+ * <script type="module" inlined-from-src="main.html@L10-C5.js">
+ *   window.__supervisor__.superviseScriptTypeModule('main.html@L10-C5.js')
+ * </script>
+ *
+ * Why Inline scripts are converted to files dynamically?
+ * -> No changes required on js source code, it's only the HTML that is modified
+ *   - Also allow to catch syntax errors and export missing
+ */
+
+import {
+  parseHtmlString,
+  stringifyHtmlAst,
+  visitHtmlNodes,
+  getHtmlNodeAttribute,
+  setHtmlNodeAttributes,
+  analyzeScriptNode,
+  injectScriptNodeAsEarlyAsPossible,
+  createHtmlNode,
+  getHtmlNodePosition,
+  getHtmlNodeText,
+  setHtmlNodeText,
+} from "@jsenv/ast"
+import { generateInlineContentUrl, urlToRelativeUrl } from "@jsenv/urls"
+
+import { injectSupervisorIntoJs } from "./js_supervisor_injection.js"
+
+export const supervisorFileUrl = new URL(
+  "./client/supervisor.js",
+  import.meta.url,
+).href
+
+export const injectSupervisorIntoHTML = async (
+  { content, url },
+  {
+    supervisorScriptSrc = supervisorFileUrl,
+    supervisorOptions,
+    webServer,
+    onInlineScript = () => {},
+    generateInlineScriptSrc = ({ inlineScriptUrl }) =>
+      urlToRelativeUrl(inlineScriptUrl, webServer.rootDirectoryUrl),
+    inlineAsRemote,
+  },
+) => {
+  const htmlAst = parseHtmlString(content)
+  const mutations = []
+  const actions = []
+
+  const scriptInfos = []
+  // 1. Find inline and remote scripts
+  {
+    const handleInlineScript = (
+      scriptNode,
+      { type, extension, textContent },
+    ) => {
+      const { line, column, lineEnd, columnEnd, isOriginal } =
+        getHtmlNodePosition(scriptNode, { preferOriginal: true })
+      const inlineScriptUrl = generateInlineContentUrl({
+        url,
+        extension: extension || ".js",
+        line,
+        column,
+        lineEnd,
+        columnEnd,
+      })
+      const inlineScriptSrc = generateInlineScriptSrc({
+        type,
+        textContent,
+        inlineScriptUrl,
+        isOriginal,
+        line,
+        column,
+      })
+      onInlineScript({
+        type,
+        textContent,
+        url: inlineScriptUrl,
+        isOriginal,
+        line,
+        column,
+        src: inlineScriptSrc,
+      })
+      if (inlineAsRemote) {
+        // prefere la version src
+        scriptInfos.push({ type, src: inlineScriptSrc })
+        const remoteJsSupervised = generateCodeToSuperviseScriptWithSrc({
+          type,
+          src: inlineScriptSrc,
+        })
+        mutations.push(() => {
+          setHtmlNodeText(scriptNode, remoteJsSupervised)
+          setHtmlNodeAttributes(scriptNode, {
+            "jsenv-cooked-by": "jsenv:supervisor",
+            "src": undefined,
+            "inlined-from-src": inlineScriptSrc,
+          })
+        })
+      } else {
+        scriptInfos.push({ type, src: inlineScriptSrc, isInline: true })
+        actions.push(async () => {
+          try {
+            const inlineJsSupervised = await injectSupervisorIntoJs({
+              webServer,
+              content: textContent,
+              url: inlineScriptUrl,
+              type,
+              inlineSrc: inlineScriptSrc,
+            })
+            mutations.push(() => {
+              setHtmlNodeText(scriptNode, inlineJsSupervised)
+              setHtmlNodeAttributes(scriptNode, {
+                "jsenv-cooked-by": "jsenv:supervisor",
+              })
+            })
+          } catch (e) {
+            if (e.code === "PARSE_ERROR") {
+              // mutations.push(() => {
+              //   setHtmlNodeAttributes(scriptNode, {
+              //     "jsenv-cooked-by": "jsenv:supervisor",
+              //   })
+              // })
+              // on touche a rien
+              return
+            }
+            throw e
+          }
+        })
+      }
+    }
+    const handleScriptWithSrc = (scriptNode, { type, src }) => {
+      scriptInfos.push({ type, src })
+      const remoteJsSupervised = generateCodeToSuperviseScriptWithSrc({
+        type,
+        src,
+      })
+      mutations.push(() => {
+        setHtmlNodeText(scriptNode, remoteJsSupervised)
+        setHtmlNodeAttributes(scriptNode, {
+          "jsenv-cooked-by": "jsenv:supervisor",
+          "src": undefined,
+          "inlined-from-src": src,
+        })
+      })
+    }
+    visitHtmlNodes(htmlAst, {
+      script: (scriptNode) => {
+        const { type, extension } = analyzeScriptNode(scriptNode)
+        if (type !== "js_classic" && type !== "js_module") {
+          return
+        }
+        if (getHtmlNodeAttribute(scriptNode, "jsenv-injected-by")) {
+          return
+        }
+        const noSupervisor = getHtmlNodeAttribute(scriptNode, "no-supervisor")
+        if (noSupervisor !== undefined) {
+          return
+        }
+
+        const scriptNodeText = getHtmlNodeText(scriptNode)
+        if (scriptNodeText) {
+          handleInlineScript(scriptNode, {
+            type,
+            extension,
+            textContent: scriptNodeText,
+          })
+          return
+        }
+        const src = getHtmlNodeAttribute(scriptNode, "src")
+        if (src) {
+          handleScriptWithSrc(scriptNode, { type, src })
+          return
+        }
+      },
+    })
+  }
+  // 2. Inject supervisor js file + setup call
+  {
+    const setupParamsSource = stringifyParams(
+      {
+        ...supervisorOptions,
+        serverIsJsenvDevServer: webServer.isJsenvDevServer,
+        rootDirectoryUrl: webServer.rootDirectoryUrl,
+        scriptInfos,
+      },
+      "        ",
+    )
+    injectScriptNodeAsEarlyAsPossible(
+      htmlAst,
+      createHtmlNode({
+        tagName: "script",
+        textContent: `
+      window.__supervisor__.setup({
+        ${setupParamsSource}
+      })
+      `,
+      }),
+      "jsenv:supervisor",
+    )
+    const supervisorScript = createHtmlNode({
+      tagName: "script",
+      src: supervisorScriptSrc,
+    })
+    injectScriptNodeAsEarlyAsPossible(
+      htmlAst,
+      supervisorScript,
+      "jsenv:supervisor",
+    )
+  }
+  // 3. Perform actions (transforming inline script content) and html mutations
+  if (actions.length > 0) {
+    await Promise.all(actions.map((action) => action()))
+  }
+  mutations.forEach((mutation) => mutation())
+  const htmlModified = stringifyHtmlAst(htmlAst)
+  return {
+    content: htmlModified,
+  }
+}
+
+const stringifyParams = (params, prefix = "") => {
+  const source = JSON.stringify(params, null, prefix)
+  if (prefix.length) {
+    // remove leading "{\n"
+    // remove leading prefix
+    // remove trailing "\n}"
+    return source.slice(2 + prefix.length, -2)
+  }
+  // remove leading "{"
+  // remove trailing "}"
+  return source.slice(1, -1)
+}
+
+const generateCodeToSuperviseScriptWithSrc = ({ type, src }) => {
+  if (type === "js_module") {
+    return `
+        window.__supervisor__.superviseScriptTypeModule(${JSON.stringify(
+          src,
+        )}, (url) => import(url));
+    `
+  }
+  return `
+        window.__supervisor__.superviseScript(${JSON.stringify(src)});
+    `
+}

package/src/plugins/supervisor/js_supervisor_injection.js

@@ -0,0 +1,283 @@
+/*
+ * ```js
+ * console.log(42)
+ * ```
+ * becomes
+ * ```js
+ * window.__supervisor__.jsClassicStart('main.html@L10-L13.js')
+ * try {
+ *   console.log(42)
+ *   window.__supervisor__.jsClassicEnd('main.html@L10-L13.js')
+ * } catch(e) {
+ *   window.__supervisor__.jsClassicError('main.html@L10-L13.js', e)
+ * }
+ * ```
+ *
+ * ```js
+ * import value from "./file.js"
+ * console.log(value)
+ * ```
+ * becomes
+ * ```js
+ * window.__supervisor__.jsModuleStart('main.html@L10-L13.js')
+ * try {
+ *   const value = await import("./file.js")
+ *   console.log(value)
+ *   window.__supervisor__.jsModuleEnd('main.html@L10-L13.js')
+ * } catch(e) {
+ *   window.__supervisor__.jsModuleError('main.html@L10-L13.js', e)
+ * }
+ * ```
+ *
+ * -> TO KEEP IN MIND:
+ * Static import can throw errors like
+ * The requested module '/js_module_export_not_found/foo.js' does not provide an export named 'answerr'
+ * While dynamic import will work just fine
+ * and create a variable named "undefined"
+ */
+
+import { urlToRelativeUrl } from "@jsenv/urls"
+import { applyBabelPlugins } from "@jsenv/ast"
+import { SOURCEMAP, generateSourcemapDataUrl } from "@jsenv/sourcemap"
+
+export const injectSupervisorIntoJs = async ({
+  webServer,
+  content,
+  url,
+  type,
+  inlineSrc,
+}) => {
+  const babelPluginJsSupervisor =
+    type === "js_module"
+      ? babelPluginJsModuleSupervisor
+      : babelPluginJsClassicSupervisor
+  const result = await applyBabelPlugins({
+    urlInfo: {
+      content,
+      originalUrl: url,
+      type,
+    },
+    babelPlugins: [[babelPluginJsSupervisor, { inlineSrc }]],
+  })
+  let code = result.code
+  let map = result.map
+  const sourcemapDataUrl = generateSourcemapDataUrl(map)
+  code = SOURCEMAP.writeComment({
+    contentType: "text/javascript",
+    content: code,
+    specifier: sourcemapDataUrl,
+  })
+  code = `${code}
+//# sourceURL=${urlToRelativeUrl(url, webServer.rootDirectoryUrl)}`
+  return code
+}
+
+const babelPluginJsModuleSupervisor = (babel) => {
+  const t = babel.types
+
+  return {
+    name: "js-module-supervisor",
+    visitor: {
+      Program: (programPath, state) => {
+        const { inlineSrc } = state.opts
+        if (state.file.metadata.jsExecutionInstrumented) return
+        state.file.metadata.jsExecutionInstrumented = true
+
+        const urlNode = t.stringLiteral(inlineSrc)
+        const startCallNode = createSupervisionCall({
+          t,
+          urlNode,
+          methodName: "jsModuleStart",
+        })
+        const endCallNode = createSupervisionCall({
+          t,
+          urlNode,
+          methodName: "jsModuleEnd",
+        })
+        const errorCallNode = createSupervisionCall({
+          t,
+          urlNode,
+          methodName: "jsModuleError",
+          args: [t.identifier("e")],
+        })
+
+        const bodyPath = programPath.get("body")
+        const importNodes = []
+        const topLevelNodes = []
+        for (const topLevelNodePath of bodyPath) {
+          const topLevelNode = topLevelNodePath.node
+          if (t.isImportDeclaration(topLevelNode)) {
+            importNodes.push(topLevelNode)
+          } else {
+            topLevelNodes.push(topLevelNode)
+          }
+        }
+
+        // replace all import nodes with dynamic imports
+        const dynamicImports = []
+        importNodes.forEach((importNode) => {
+          const dynamicImportConversion = convertStaticImportIntoDynamicImport(
+            importNode,
+            t,
+          )
+          if (Array.isArray(dynamicImportConversion)) {
+            dynamicImports.push(...dynamicImportConversion)
+          } else {
+            dynamicImports.push(dynamicImportConversion)
+          }
+        })
+
+        const tryCatchNode = t.tryStatement(
+          t.blockStatement([...dynamicImports, ...topLevelNodes, endCallNode]),
+          t.catchClause(t.identifier("e"), t.blockStatement([errorCallNode])),
+        )
+        programPath.replaceWith(t.program([startCallNode, tryCatchNode]))
+      },
+    },
+  }
+}
+
+const convertStaticImportIntoDynamicImport = (staticImportNode, t) => {
+  const awaitExpression = t.awaitExpression(
+    t.callExpression(t.import(), [
+      t.stringLiteral(staticImportNode.source.value),
+    ]),
+  )
+
+  // import "./file.js" -> await import("./file.js")
+  if (staticImportNode.specifiers.length === 0) {
+    return t.expressionStatement(awaitExpression)
+  }
+  if (staticImportNode.specifiers.length === 1) {
+    const [firstSpecifier] = staticImportNode.specifiers
+    if (firstSpecifier.type === "ImportNamespaceSpecifier") {
+      return t.variableDeclaration("const", [
+        t.variableDeclarator(
+          t.identifier(firstSpecifier.local.name),
+          awaitExpression,
+        ),
+      ])
+    }
+  }
+  if (staticImportNode.specifiers.length === 2) {
+    const [first, second] = staticImportNode.specifiers
+    if (
+      first.type === "ImportDefaultSpecifier" &&
+      second.type === "ImportNamespaceSpecifier"
+    ) {
+      const namespaceDeclaration = t.variableDeclaration("const", [
+        t.variableDeclarator(t.identifier(second.local.name), awaitExpression),
+      ])
+      const defaultDeclaration = t.variableDeclaration("const", [
+        t.variableDeclarator(
+          t.identifier(first.local.name),
+          t.memberExpression(
+            t.identifier(second.local.name),
+            t.identifier("default"),
+          ),
+        ),
+      ])
+      return [namespaceDeclaration, defaultDeclaration]
+    }
+  }
+
+  // import { name } from "./file.js" -> const { name } = await import("./file.js")
+  // import toto, { name } from "./file.js" -> const { name, default as toto } = await import("./file.js")
+  const objectPattern = t.objectPattern(
+    staticImportNode.specifiers.map((specifier) => {
+      if (specifier.type === "ImportDefaultSpecifier") {
+        return t.objectProperty(
+          t.identifier("default"),
+          t.identifier(specifier.local.name),
+          false, // computed
+          false, // shorthand
+        )
+      }
+      // if (specifier.type === "ImportNamespaceSpecifier") {
+      //   return t.restElement(t.identifier(specifier.local.name))
+      // }
+      const isRenamed = specifier.imported.name !== specifier.local.name
+      if (isRenamed) {
+        return t.objectProperty(
+          t.identifier(specifier.imported.name),
+          t.identifier(specifier.local.name),
+          false, // computed
+          false, // shorthand
+        )
+      }
+      // shorthand must be true
+      return t.objectProperty(
+        t.identifier(specifier.local.name),
+        t.identifier(specifier.local.name),
+        false, // computed
+        true, // shorthand
+      )
+    }),
+  )
+  const variableDeclarator = t.variableDeclarator(
+    objectPattern,
+    awaitExpression,
+  )
+  const variableDeclaration = t.variableDeclaration("const", [
+    variableDeclarator,
+  ])
+  return variableDeclaration
+}
+
+const babelPluginJsClassicSupervisor = (babel) => {
+  const t = babel.types
+
+  return {
+    name: "js-classic-supervisor",
+    visitor: {
+      Program: (programPath, state) => {
+        const { inlineSrc } = state.opts
+        if (state.file.metadata.jsExecutionInstrumented) return
+        state.file.metadata.jsExecutionInstrumented = true
+
+        const urlNode = t.stringLiteral(inlineSrc)
+        const startCallNode = createSupervisionCall({
+          t,
+          urlNode,
+          methodName: "jsClassicStart",
+        })
+        const endCallNode = createSupervisionCall({
+          t,
+          urlNode,
+          methodName: "jsClassicEnd",
+        })
+        const errorCallNode = createSupervisionCall({
+          t,
+          urlNode,
+          methodName: "jsClassicError",
+          args: [t.identifier("e")],
+        })
+
+        const topLevelNodes = programPath.node.body
+        const tryCatchNode = t.tryStatement(
+          t.blockStatement([...topLevelNodes, endCallNode]),
+          t.catchClause(t.identifier("e"), t.blockStatement([errorCallNode])),
+        )
+
+        programPath.replaceWith(t.program([startCallNode, tryCatchNode]))
+      },
+    },
+  }
+}
+
+const createSupervisionCall = ({ t, methodName, urlNode, args = [] }) => {
+  return t.expressionStatement(
+    t.callExpression(
+      t.memberExpression(
+        t.memberExpression(
+          t.identifier("window"),
+          t.identifier("__supervisor__"),
+        ),
+        t.identifier(methodName),
+      ),
+      [urlNode, ...args],
+    ),
+    [],
+    null,
+  )
+}