@jsenv/core 38.1.0 → 38.2.0

package/README.md

@@ -1,32 +1,19 @@
 # @jsenv/core [![npm package](https://img.shields.io/npm/v/@jsenv/core.svg?logo=npm&label=package)](https://www.npmjs.com/package/@jsenv/core)
 
-Jsenv was created to provide a tool that can be used both for the web and Node.js.
-It has naturally evolved to cover the core needs of a JavaScript project: developement, testing and building for production.
+Jsenv is a tool to develop test and build projects using JavaScript. Jsenv is simple, easy to understand and well documented.
 
-- :ok_hand: Seamless integration with standard HTML, CSS and JS.
-- :sparkles: Same developer experience on source files and test files.
-- :exploding_head: Can execute tests on Chrome, Firefox, Safari and Node.js.
+[Documentation](<https://github.com/jsenv/core/wiki/A)-Introduction>) · [Changelog](./CHANGELOG.md)
 
-[Documentation](<https://github.com/jsenv/core/wiki/A)-Getting-started>) · [Changelog](./CHANGELOG.md)
+See also
 
-# Installation
+- [Documentation for contributors](./docs/contributors/README.md)
+- [Documentation for maintainers](./docs/maintainers/README.md)
+
+<!-- # Installation
 
 ```console
 npm install --save-dev @jsenv/core
 ```
 
 _@jsenv/core_ is tested on Mac, Windows, Linux with Node.js 18.
-Other operating systems and Node.js versions are not tested.
-
-# Name
-
-The name "jsenv" stands for JavaScript environments.<br />
-"jsenv" without capital letter because "JSEnv" would be too painful to type.
-
-# Logo
-
-The logo is composed by the name at the center and two circles orbiting around it.
-One of the circle is web browsers, the other is Node.js.
-It represents the two JavaScript runtimes supported by jsenv.
-
-![jsenv logo with legend](./docs/jsenv_logo_legend.png)
+Other operating systems and Node.js versions are not tested. -->

package/dist/jsenv_core.js

@@ -14797,214 +14797,6 @@ const createRepartitionMessage = ({ html, css, js, json, other, total }) => {
 - `)}`;
 };
 
-const placeholderSymbol = Symbol.for("jsenv_placeholder");
-const PLACEHOLDER = {
-  optional: (value) => {
-    return { [placeholderSymbol]: "optional", value };
-  },
-};
-
-const replacePlaceholders = (content, replacements, urlInfo) => {
-  const magicSource = createMagicSource(content);
-  for (const key of Object.keys(replacements)) {
-    let index = content.indexOf(key);
-    const replacement = replacements[key];
-    let isOptional;
-    let value;
-    if (replacement && replacement[placeholderSymbol]) {
-      const valueBehindSymbol = replacement[placeholderSymbol];
-      isOptional = valueBehindSymbol === "optional";
-      value = replacement.value;
-    } else {
-      value = replacement;
-    }
-    if (index === -1) {
-      if (!isOptional) {
-        urlInfo.context.logger.warn(
-          `placeholder "${key}" not found in ${urlInfo.url}.
---- suggestion a ---
-Add "${key}" in that file.
---- suggestion b ---
-Fix eventual typo in "${key}"?
---- suggestion c ---
-Mark injection as optional using PLACEHOLDER.optional()
-
-import { PLACEHOLDER } from "@jsenv/core"
-
-return {
-  "${key}": PLACEHOLDER.optional(${JSON.stringify(value)})
-}`,
-        );
-      }
-      continue;
-    }
-
-    while (index !== -1) {
-      const start = index;
-      const end = index + key.length;
-      magicSource.replace({
-        start,
-        end,
-        replacement:
-          urlInfo.type === "js_classic" ||
-          urlInfo.type === "js_module" ||
-          urlInfo.type === "html"
-            ? JSON.stringify(value, null, "  ")
-            : value,
-      });
-      index = content.indexOf(key, end);
-    }
-  }
-  return magicSource.toContentAndSourcemap();
-};
-
-const injectGlobals = (content, globals, urlInfo) => {
-  if (urlInfo.type === "html") {
-    return globalInjectorOnHtml(content, globals);
-  }
-  if (urlInfo.type === "js_classic" || urlInfo.type === "js_module") {
-    return globalsInjectorOnJs(content, globals, urlInfo);
-  }
-  throw new Error(`cannot inject globals into "${urlInfo.type}"`);
-};
-
-const globalInjectorOnHtml = (content, globals) => {
-  // ideally we would inject an importmap but browser support is too low
-  // (even worse for worker/service worker)
-  // so for now we inject code into entry points
-  const htmlAst = parseHtmlString(content, {
-    storeOriginalPositions: false,
-  });
-  const clientCode = generateClientCodeForGlobals(globals, {
-    isWebWorker: false,
-  });
-  injectHtmlNodeAsEarlyAsPossible(
-    htmlAst,
-    createHtmlNode({
-      tagName: "script",
-      textContent: clientCode,
-    }),
-    "jsenv:inject_globals",
-  );
-  return stringifyHtmlAst(htmlAst);
-};
-
-const globalsInjectorOnJs = (content, globals, urlInfo) => {
-  const clientCode = generateClientCodeForGlobals(globals, {
-    isWebWorker:
-      urlInfo.subtype === "worker" ||
-      urlInfo.subtype === "service_worker" ||
-      urlInfo.subtype === "shared_worker",
-  });
-  const magicSource = createMagicSource(content);
-  magicSource.prepend(clientCode);
-  return magicSource.toContentAndSourcemap();
-};
-
-const generateClientCodeForGlobals = (globals, { isWebWorker = false }) => {
-  const globalName = isWebWorker ? "self" : "window";
-  return `Object.assign(${globalName}, ${JSON.stringify(
-    globals,
-    null,
-    "  ",
-  )});`;
-};
-
-const jsenvPluginInjections = (rawAssociations) => {
-  let resolvedAssociations;
-
-  return {
-    name: "jsenv:injections",
-    appliesDuring: "*",
-    init: (context) => {
-      resolvedAssociations = URL_META.resolveAssociations(
-        { injectionsGetter: rawAssociations },
-        context.rootDirectoryUrl,
-      );
-    },
-    transformUrlContent: async (urlInfo) => {
-      const { injectionsGetter } = URL_META.applyAssociations({
-        url: asUrlWithoutSearch(urlInfo.url),
-        associations: resolvedAssociations,
-      });
-      if (!injectionsGetter) {
-        return null;
-      }
-      if (typeof injectionsGetter !== "function") {
-        throw new TypeError("injectionsGetter must be a function");
-      }
-      const injections = await injectionsGetter(urlInfo);
-      if (!injections) {
-        return null;
-      }
-      const keys = Object.keys(injections);
-      if (keys.length === 0) {
-        return null;
-      }
-      let someGlobal = false;
-      let someReplacement = false;
-      const globals = {};
-      const replacements = {};
-      for (const key of keys) {
-        const { type, name, value } = createInjection(injections[key], key);
-        if (type === "global") {
-          globals[name] = value;
-          someGlobal = true;
-        } else {
-          replacements[name] = value;
-          someReplacement = true;
-        }
-      }
-
-      if (!someGlobal && !someReplacement) {
-        return null;
-      }
-
-      let content = urlInfo.content;
-      let sourcemap;
-      if (someGlobal) {
-        const globalInjectionResult = injectGlobals(content, globals, urlInfo);
-        content = globalInjectionResult.content;
-        sourcemap = globalInjectionResult.sourcemap;
-      }
-      if (someReplacement) {
-        const replacementResult = replacePlaceholders(
-          content,
-          replacements,
-          urlInfo,
-        );
-        content = replacementResult.content;
-        sourcemap = sourcemap
-          ? composeTwoSourcemaps(sourcemap, replacementResult.sourcemap)
-          : replacementResult.sourcemap;
-      }
-      return {
-        content,
-        sourcemap,
-      };
-    },
-  };
-};
-
-const wellKnowGlobalNames = ["window", "global", "globalThis", "self"];
-const createInjection = (value, key) => {
-  for (const wellKnowGlobalName of wellKnowGlobalNames) {
-    const prefix = `${wellKnowGlobalName}.`;
-    if (key.startsWith(prefix)) {
-      return {
-        type: "global",
-        name: key.slice(prefix.length),
-        value,
-      };
-    }
-  }
-  return {
-    type: "replacement",
-    name: key,
-    value,
-  };
-};
-
 const jsenvPluginReferenceExpectedTypes = () => {
   const redirectJsReference = (reference) => {
     const urlObject = new URL(reference.url);
@@ -18353,6 +18145,104 @@ const jsenvPluginProtocolHttp = () => {
   };
 };
 
+const jsenvPluginInjections = (rawAssociations) => {
+  let resolvedAssociations;
+
+  return {
+    name: "jsenv:injections",
+    appliesDuring: "*",
+    init: (context) => {
+      resolvedAssociations = URL_META.resolveAssociations(
+        { injectionsGetter: rawAssociations },
+        context.rootDirectoryUrl,
+      );
+    },
+    transformUrlContent: async (urlInfo) => {
+      const { injectionsGetter } = URL_META.applyAssociations({
+        url: asUrlWithoutSearch(urlInfo.url),
+        associations: resolvedAssociations,
+      });
+      if (!injectionsGetter) {
+        return null;
+      }
+      if (typeof injectionsGetter !== "function") {
+        throw new TypeError("injectionsGetter must be a function");
+      }
+      const injections = await injectionsGetter(urlInfo);
+      if (!injections) {
+        return null;
+      }
+      const keys = Object.keys(injections);
+      if (keys.length === 0) {
+        return null;
+      }
+      return replacePlaceholders(urlInfo.content, injections, urlInfo);
+    },
+  };
+};
+
+const injectionSymbol = Symbol.for("jsenv_injection");
+const INJECTIONS = {
+  optional: (value) => {
+    return { [injectionSymbol]: "optional", value };
+  },
+};
+
+// we export this because it is imported by jsenv_plugin_placeholder.js and unit test
+const replacePlaceholders = (content, replacements, urlInfo) => {
+  const magicSource = createMagicSource(content);
+  for (const key of Object.keys(replacements)) {
+    let index = content.indexOf(key);
+    const replacement = replacements[key];
+    let isOptional;
+    let value;
+    if (replacement && replacement[injectionSymbol]) {
+      const valueBehindSymbol = replacement[injectionSymbol];
+      isOptional = valueBehindSymbol === "optional";
+      value = replacement.value;
+    } else {
+      value = replacement;
+    }
+    if (index === -1) {
+      if (!isOptional) {
+        urlInfo.context.logger.warn(
+          `placeholder "${key}" not found in ${urlInfo.url}.
+--- suggestion a ---
+Add "${key}" in that file.
+--- suggestion b ---
+Fix eventual typo in "${key}"?
+--- suggestion c ---
+Mark injection as optional using INJECTIONS.optional()
+
+import { INJECTIONS } from "@jsenv/core";
+
+return {
+  "${key}": INJECTIONS.optional(${JSON.stringify(value)}),
+}`,
+        );
+      }
+      continue;
+    }
+
+    while (index !== -1) {
+      const start = index;
+      const end = index + key.length;
+      magicSource.replace({
+        start,
+        end,
+        replacement:
+          urlInfo.type === "js_classic" ||
+          urlInfo.type === "js_module" ||
+          urlInfo.type === "html"
+            ? JSON.stringify(value, null, "  ")
+            : value,
+      });
+      index = content.indexOf(key, end);
+    }
+  }
+  return magicSource.toContentAndSourcemap();
+};
+
 const jsenvPluginInliningAsDataUrl = () => {
   return {
     name: "jsenv:inlining_as_data_url",
@@ -18885,9 +18775,9 @@ const babelPluginMetadataImportMetaScenarios = () => {
 
 /*
  * Source code can contain the following
- * - __dev__
- * - __build__
- * A global will be injected with true/false when needed
+ * - __DEV__
+ * - __BUILD__
+ * That will be replaced with true/false
  */
 
 
@@ -18896,8 +18786,8 @@ const jsenvPluginGlobalScenarios = () => {
     return replacePlaceholders(
       urlInfo.content,
       {
-        __DEV__: PLACEHOLDER.optional(urlInfo.context.dev),
-        __BUILD__: PLACEHOLDER.optional(urlInfo.context.build),
+        __DEV__: INJECTIONS.optional(urlInfo.context.dev),
+        __BUILD__: INJECTIONS.optional(urlInfo.context.build),
       },
       urlInfo,
     );
@@ -20926,7 +20816,7 @@ const createBuildSpecifierManager = ({
             const urlInfo = finalKitchen.graph.getUrlInfo(finalUrl);
             if (!urlInfo) {
               logger.warn(
-                `remove resource hint because cannot find "${href}" in the graph`,
+                `${UNICODE.WARNING} remove resource hint because cannot find "${href}" in the graph`,
               );
               mutations.push(() => {
                 removeHtmlNode(node);
@@ -20937,7 +20827,7 @@ const createBuildSpecifierManager = ({
               const rawUrlInfo = rawKitchen.graph.getUrlInfo(rawUrl);
               if (rawUrlInfo && rawUrlInfo.data.bundled) {
                 logger.warn(
-                  `remove resource hint on "${href}" because it was bundled`,
+                  `${UNICODE.WARNING} remove resource hint on "${href}" because it was bundled`,
                 );
                 mutations.push(() => {
                   removeHtmlNode(node);
@@ -20945,7 +20835,7 @@ const createBuildSpecifierManager = ({
                 return;
               }
               logger.warn(
-                `remove resource hint on "${href}" because it is not used anymore`,
+                `${UNICODE.WARNING} remove resource hint on "${href}" because it is not used anymore`,
               );
               mutations.push(() => {
                 removeHtmlNode(node);
@@ -22982,4 +22872,4 @@ const createBuildFilesService = ({ buildDirectoryUrl, buildMainFilePath }) => {
 
 const SECONDS_IN_30_DAYS = 60 * 60 * 24 * 30;
 
-export { build, startBuildServer, startDevServer };
+export { INJECTIONS, build, startBuildServer, startDevServer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/core",
-  "version": "38.1.0",
+  "version": "38.2.0",
   "description": "Tool to develop, test and build js projects",
   "license": "MIT",
   "author": {
@@ -71,8 +71,7 @@
     "@jsenv/runtime-compat": "1.2.0",
     "@jsenv/server": "15.1.0",
     "@jsenv/sourcemap": "1.2.1",
-    "@jsenv/plugin-injections": "1.0.0",
-    "@jsenv/plugin-bundling": "2.5.1",
+    "@jsenv/plugin-bundling": "2.5.2",
     "@jsenv/plugin-minification": "1.5.0",
     "@jsenv/plugin-transpilation": "1.3.2",
     "@jsenv/plugin-supervisor": "1.3.2",
@@ -99,6 +98,6 @@
     "eslint-plugin-react": "7.33.1",
     "open": "9.1.0",
     "playwright": "1.36.2",
-    "prettier": "3.0.0"
+    "prettier": "3.0.1"
   }
 }

package/src/build/build_specifier_manager.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { createDetailedMessage } from "@jsenv/log";
+import { createDetailedMessage, UNICODE } from "@jsenv/log";
 import { comparePathnames } from "@jsenv/filesystem";
 import { createMagicSource, generateSourcemapFileUrl } from "@jsenv/sourcemap";
 import {
@@ -790,7 +790,7 @@ export const createBuildSpecifierManager = ({
             const urlInfo = finalKitchen.graph.getUrlInfo(finalUrl);
             if (!urlInfo) {
               logger.warn(
-                `remove resource hint because cannot find "${href}" in the graph`,
+                `${UNICODE.WARNING} remove resource hint because cannot find "${href}" in the graph`,
               );
               mutations.push(() => {
                 removeHtmlNode(node);
@@ -801,7 +801,7 @@ export const createBuildSpecifierManager = ({
               const rawUrlInfo = rawKitchen.graph.getUrlInfo(rawUrl);
               if (rawUrlInfo && rawUrlInfo.data.bundled) {
                 logger.warn(
-                  `remove resource hint on "${href}" because it was bundled`,
+                  `${UNICODE.WARNING} remove resource hint on "${href}" because it was bundled`,
                 );
                 mutations.push(() => {
                   removeHtmlNode(node);
@@ -809,7 +809,7 @@ export const createBuildSpecifierManager = ({
                 return;
               }
               logger.warn(
-                `remove resource hint on "${href}" because it is not used anymore`,
+                `${UNICODE.WARNING} remove resource hint on "${href}" because it is not used anymore`,
               );
               mutations.push(() => {
                 removeHtmlNode(node);

package/src/main.js

@@ -3,3 +3,6 @@ export { startDevServer } from "./dev/start_dev_server.js";
 // build
 export { build } from "./build/build.js";
 export { startBuildServer } from "./build/start_build_server.js";
+
+// others
+export { INJECTIONS } from "./plugins/injections/jsenv_plugin_injections.js";

package/src/plugins/global_scenarios/jsenv_plugin_global_scenarios.js

@@ -1,19 +1,22 @@
 /*
  * Source code can contain the following
- * - __dev__
- * - __build__
- * A global will be injected with true/false when needed
+ * - __DEV__
+ * - __BUILD__
+ * That will be replaced with true/false
  */
 
-import { replacePlaceholders, PLACEHOLDER } from "@jsenv/plugin-injections";
+import {
+  replacePlaceholders,
+  INJECTIONS,
+} from "../injections/jsenv_plugin_injections.js";
 
 export const jsenvPluginGlobalScenarios = () => {
   const transformIfNeeded = (urlInfo) => {
     return replacePlaceholders(
       urlInfo.content,
       {
-        __DEV__: PLACEHOLDER.optional(urlInfo.context.dev),
-        __BUILD__: PLACEHOLDER.optional(urlInfo.context.build),
+        __DEV__: INJECTIONS.optional(urlInfo.context.dev),
+        __BUILD__: INJECTIONS.optional(urlInfo.context.build),
       },
       urlInfo,
     );

package/src/plugins/injections/internal/inject_globals.js

@@ -0,0 +1,59 @@
+import { createMagicSource } from "@jsenv/sourcemap";
+import {
+  parseHtmlString,
+  injectHtmlNodeAsEarlyAsPossible,
+  createHtmlNode,
+  stringifyHtmlAst,
+} from "@jsenv/ast";
+
+export const injectGlobals = (content, globals, urlInfo) => {
+  if (urlInfo.type === "html") {
+    return globalInjectorOnHtml(content, globals, urlInfo);
+  }
+  if (urlInfo.type === "js_classic" || urlInfo.type === "js_module") {
+    return globalsInjectorOnJs(content, globals, urlInfo);
+  }
+  throw new Error(`cannot inject globals into "${urlInfo.type}"`);
+};
+
+const globalInjectorOnHtml = (content, globals) => {
+  // ideally we would inject an importmap but browser support is too low
+  // (even worse for worker/service worker)
+  // so for now we inject code into entry points
+  const htmlAst = parseHtmlString(content, {
+    storeOriginalPositions: false,
+  });
+  const clientCode = generateClientCodeForGlobals(globals, {
+    isWebWorker: false,
+  });
+  injectHtmlNodeAsEarlyAsPossible(
+    htmlAst,
+    createHtmlNode({
+      tagName: "script",
+      textContent: clientCode,
+    }),
+    "jsenv:inject_globals",
+  );
+  return stringifyHtmlAst(htmlAst);
+};
+
+const globalsInjectorOnJs = (content, globals, urlInfo) => {
+  const clientCode = generateClientCodeForGlobals(globals, {
+    isWebWorker:
+      urlInfo.subtype === "worker" ||
+      urlInfo.subtype === "service_worker" ||
+      urlInfo.subtype === "shared_worker",
+  });
+  const magicSource = createMagicSource(content);
+  magicSource.prepend(clientCode);
+  return magicSource.toContentAndSourcemap();
+};
+
+const generateClientCodeForGlobals = (globals, { isWebWorker = false }) => {
+  const globalName = isWebWorker ? "self" : "window";
+  return `Object.assign(${globalName}, ${JSON.stringify(
+    globals,
+    null,
+    "  ",
+  )});`;
+};

package/src/plugins/injections/jsenv_plugin_injections.js

@@ -0,0 +1,101 @@
+import { URL_META } from "@jsenv/url-meta";
+import { asUrlWithoutSearch } from "@jsenv/urls";
+import { createMagicSource } from "@jsenv/sourcemap";
+
+export const jsenvPluginInjections = (rawAssociations) => {
+  let resolvedAssociations;
+
+  return {
+    name: "jsenv:injections",
+    appliesDuring: "*",
+    init: (context) => {
+      resolvedAssociations = URL_META.resolveAssociations(
+        { injectionsGetter: rawAssociations },
+        context.rootDirectoryUrl,
+      );
+    },
+    transformUrlContent: async (urlInfo) => {
+      const { injectionsGetter } = URL_META.applyAssociations({
+        url: asUrlWithoutSearch(urlInfo.url),
+        associations: resolvedAssociations,
+      });
+      if (!injectionsGetter) {
+        return null;
+      }
+      if (typeof injectionsGetter !== "function") {
+        throw new TypeError("injectionsGetter must be a function");
+      }
+      const injections = await injectionsGetter(urlInfo);
+      if (!injections) {
+        return null;
+      }
+      const keys = Object.keys(injections);
+      if (keys.length === 0) {
+        return null;
+      }
+      return replacePlaceholders(urlInfo.content, injections, urlInfo);
+    },
+  };
+};
+
+const injectionSymbol = Symbol.for("jsenv_injection");
+export const INJECTIONS = {
+  optional: (value) => {
+    return { [injectionSymbol]: "optional", value };
+  },
+};
+
+// we export this because it is imported by jsenv_plugin_placeholder.js and unit test
+export const replacePlaceholders = (content, replacements, urlInfo) => {
+  const magicSource = createMagicSource(content);
+  for (const key of Object.keys(replacements)) {
+    let index = content.indexOf(key);
+    const replacement = replacements[key];
+    let isOptional;
+    let value;
+    if (replacement && replacement[injectionSymbol]) {
+      const valueBehindSymbol = replacement[injectionSymbol];
+      isOptional = valueBehindSymbol === "optional";
+      value = replacement.value;
+    } else {
+      value = replacement;
+    }
+    if (index === -1) {
+      if (!isOptional) {
+        urlInfo.context.logger.warn(
+          `placeholder "${key}" not found in ${urlInfo.url}.
+--- suggestion a ---
+Add "${key}" in that file.
+--- suggestion b ---
+Fix eventual typo in "${key}"?
+--- suggestion c ---
+Mark injection as optional using INJECTIONS.optional()
+
+import { INJECTIONS } from "@jsenv/core";
+
+return {
+  "${key}": INJECTIONS.optional(${JSON.stringify(value)}),
+}`,
+        );
+      }
+      continue;
+    }
+
+    while (index !== -1) {
+      const start = index;
+      const end = index + key.length;
+      magicSource.replace({
+        start,
+        end,
+        replacement:
+          urlInfo.type === "js_classic" ||
+          urlInfo.type === "js_module" ||
+          urlInfo.type === "html"
+            ? JSON.stringify(value, null, "  ")
+            : value,
+      });
+      index = content.indexOf(key, end);
+    }
+  }
+  return magicSource.toContentAndSourcemap();
+};

package/src/plugins/plugins.js

@@ -1,5 +1,4 @@
 import { jsenvPluginSupervisor } from "@jsenv/plugin-supervisor";
-import { jsenvPluginInjections } from "@jsenv/plugin-injections";
 import { jsenvPluginTranspilation } from "@jsenv/plugin-transpilation";
 
 import { jsenvPluginReferenceAnalysis } from "./reference_analysis/jsenv_plugin_reference_analysis.js";
@@ -9,6 +8,7 @@ import { jsenvPluginWebResolution } from "./resolution_web/jsenv_plugin_web_reso
 import { jsenvPluginVersionSearchParam } from "./version_search_param/jsenv_plugin_version_search_param.js";
 import { jsenvPluginProtocolFile } from "./protocol_file/jsenv_plugin_protocol_file.js";
 import { jsenvPluginProtocolHttp } from "./protocol_http/jsenv_plugin_protocol_http.js";
+import { jsenvPluginInjections } from "./injections/jsenv_plugin_injections.js";
 import { jsenvPluginInlining } from "./inlining/jsenv_plugin_inlining.js";
 import { jsenvPluginCommonJsGlobals } from "./commonjs_globals/jsenv_plugin_commonjs_globals.js";
 import { jsenvPluginImportMetaScenarios } from "./import_meta_scenarios/jsenv_plugin_import_meta_scenarios.js";