magic-comments-loader 1.5.1 → 1.6.0

package/README.md

@@ -3,7 +3,7 @@
 ![CI](https://github.com/morganney/magic-comments-loader/actions/workflows/ci.yml/badge.svg)
 [![codecov](https://codecov.io/gh/morganney/magic-comments-loader/branch/master/graph/badge.svg?token=1DWQL43B8V)](https://codecov.io/gh/morganney/magic-comments-loader)
 
-Keep your source code clean, add [magic coments](https://webpack.js.org/api/module-methods/#magic-comments) to your dynamic `import()` statements at build time.
+Keep your source code clean, add [magic comments](https://webpack.js.org/api/module-methods/#magic-comments) to your dynamic `import()` expressions at build time.
 
 ## Getting Started
 
@@ -19,7 +19,7 @@ Next add the loader to your `webpack.config.js` file:
 module: {
   rules: [
     {
-      test: /\.[jt]sx?$/,
+      test: /\.jsx?$/,
       use: ['magic-comments-loader']
     }
   ]
@@ -45,6 +45,7 @@ The `webpackChunkName` comment is added by default when registering the loader.
 Most loader options can be defined with a [`CommentConfig`](#commentconfig) object to support overrides and  suboptions ([`CommentOptions`](#commentoptions)). Options that support globs use [`micromatch`](https://github.com/micromatch/micromatch) for pattern matching.
 
 * [`verbose`](#verbose)
+* [`mode`](#mode)
 * [`match`](#match)
 * [`webpackChunkName`](#webpackchunkname)
 * [`webpackFetchPriority`](#webpackfetchpriority)
@@ -95,6 +96,15 @@ boolean
 
 Prints console statements of the module filepath and updated `import()` during the webpack build. Useful for debugging.
 
+### `mode`
+**type**
+```ts
+'parser' | 'regexp'
+```
+**default** `'parser'`
+
+Sets how the loader finds dynamic import expressions in your source code, either using an [ECMAScript parser](https://github.com/acornjs/acorn), or a regular expression. Your mileage may vary when using `'regexp'`.
+
 ### `match`
 **type**
 ```ts
@@ -525,7 +535,7 @@ When using a [`CommentConfig`](#commentconfig) object, you can override the conf
 }
 ```
 
-The `files` and `config` keys are both required, where the former is glob string, or array thereof, and the latter is the associated magic comment's [`CommentOptions`](#commentoptions).
+The `files` and `config` keys are both required, where the former is a glob string, or an array thereof, and the latter is the associated magic comment's [`CommentOptions`](#commentoptions).
 
 Here's a more complete example of how overrides can be applied:
 
@@ -581,3 +591,27 @@ import(/* webpackMode: "lazy" */ './folder/module.js')
 import(/* webpackMode: "eager" */ './eager/module.js')
 import(/* webpackChunkName: "locales-[request]", webpackMode: "lazy-once" */ `./locales/${lang}.json`)
 ```
+
+### TypeScript
+
+When using TypeScript or experimental ECMAScript features <= [stage 3](https://tc39.es/process-document/), i.e. non spec compliant, you must chain the appropriate loaders with `magic-comments-loader` coming after.
+
+For example, if your project source code is written in TypeScript, and you use `babel-loader` to transpile and remove type annotations via `@babel/preset-typescript`, while `tsc` is used for type-checking only, chain loaders like this:
+
+**config**
+```js
+module: {
+  rules: [
+    {
+      test: /\.[jt]sx?$/,
+      // Webpack loader chains are processed in reverse order, i.e. last comes first.
+      use: [
+        'magic-comments-loader',
+        'babel-loader'
+      ]
+    }
+  ]
+}
+```
+
+You would configure `ts-loader` similarly, or any other loader that transpiles your source code into spec compliant ECMAScript.

package/dist/cjs/comment.cjs

@@ -5,16 +5,17 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.getCommenter = void 0;
 var _strategy = require("./strategy.cjs");
+var _util = require("./util.cjs");
 const getCommenter = (filepath, options, logger) => (rgxMatch, capturedImportPath) => {
   const importPath = capturedImportPath.trim();
-  const bareImportPath = importPath.replace(/['"`]/g, '');
+  const bareImportPath = (0, _util.getBareImportSpecifier)(importPath);
   const {
     verbose,
     match,
-    ...magicCommentOptions
+    magicCommentOptions
   } = options;
   const magicComment = Object.keys(magicCommentOptions).map(key => _strategy.commentFor[key](filepath, bareImportPath, magicCommentOptions[key], match)).filter(Boolean);
-  const magicImport = rgxMatch.replace(capturedImportPath, magicComment.length > 0 ? `/* ${magicComment.join(', ')} */ ${importPath}` : `${importPath}`);
+  const magicImport = rgxMatch.replace(capturedImportPath, magicComment.length > 0 ? `/* ${magicComment.join(', ')} */ ${importPath}` : importPath);
   if (verbose) {
     logger.info(`${filepath} : ${magicImport}`);
   }

package/dist/cjs/formatter.cjs

@@ -0,0 +1,45 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.format = void 0;
+var _magicString = _interopRequireDefault(require("magic-string"));
+var _strategy = require("./strategy.cjs");
+var _util = require("./util.cjs");
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+const format = ({
+  match,
+  source,
+  filepath,
+  comments,
+  magicCommentOptions,
+  importExpressionNodes
+}) => {
+  const magicImports = [];
+  const step = 'import('.length;
+  const cmts = [...comments];
+  const src = new _magicString.default(source);
+  const hasComment = node => {
+    const idx = cmts.findIndex(cmt => cmt.start > node.start && cmt.end < node.end);
+    const wasFound = idx > -1;
+    if (wasFound) {
+      cmts.splice(idx, 1);
+    }
+    return wasFound;
+  };
+  for (const node of importExpressionNodes) {
+    if (!hasComment(node)) {
+      const specifier = source.substring(node.start + step, node.end - 1);
+      const bareImportPath = (0, _util.getBareImportSpecifier)(specifier);
+      const magic = Object.keys(magicCommentOptions).map(key => _strategy.commentFor[key](filepath, bareImportPath, magicCommentOptions[key], match)).filter(Boolean);
+      if (magic.length) {
+        const magicComment = `/* ${magic.join(', ')} */ `;
+        magicImports.push(src.snip(node.start, node.end).toString().replace(specifier, `${magicComment}${specifier}`));
+        src.appendRight(node.start + step, `${magicComment}`);
+      }
+    }
+  }
+  return [src.toString(), magicImports];
+};
+exports.format = format;

package/dist/cjs/loader.cjs

@@ -6,20 +6,44 @@ Object.defineProperty(exports, "__esModule", {
 exports.loader = void 0;
 var _schemaUtils = require("schema-utils");
 var _schema = require("./schema.cjs");
+var _parser = require("./parser.cjs");
+var _formatter = require("./formatter.cjs");
 var _comment = require("./comment.cjs");
 var _util = require("./util.cjs");
-const loader = function (source, map, meta) {
+const loader = function (source) {
   const options = this.getOptions();
-  const optionKeys = Object.keys(options);
   const logger = this.getLogger('MCL');
   (0, _schemaUtils.validate)(_schema.schema, options, {
     name: 'magic-comments-loader'
   });
-  const filepath = this.utils.contextify(this.rootContext, this.resourcePath);
-  const magicComments = (0, _comment.getCommenter)(filepath.replace(/^\.\/?/, ''), optionKeys.length > 0 ? options : {
-    match: 'module',
+  const {
+    mode = 'parser',
+    match = 'module',
+    verbose = false,
+    ...rest
+  } = options;
+  const magicCommentOptions = Object.keys(rest).length ? rest : {
     webpackChunkName: true
-  }, logger);
-  this.callback(null, source.replace(_util.dynamicImportsWithoutComments, magicComments), map, meta);
+  };
+  const filepath = this.utils.contextify(this.rootContext, this.resourcePath).replace(/^\.\/?/, '');
+  if (mode === 'parser') {
+    const [magicSource, magicImports] = (0, _formatter.format)({
+      ...(0, _parser.parse)(source),
+      match,
+      filepath,
+      magicCommentOptions
+    });
+    if (verbose) {
+      magicImports.forEach(magicImport => {
+        logger.info(`${filepath} : ${magicImport}`);
+      });
+    }
+    return magicSource;
+  }
+  return source.replace(_util.dynamicImportsWithoutComments, (0, _comment.getCommenter)(filepath, {
+    verbose,
+    match,
+    magicCommentOptions
+  }, logger));
 };
 exports.loader = loader;

package/dist/cjs/parser.cjs

@@ -0,0 +1,55 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.parse = void 0;
+var _acorn = require("acorn");
+var _acornWalk = require("acorn-walk");
+var _acornJsxWalk = require("acorn-jsx-walk");
+var _acornJsx = _interopRequireDefault(require("acorn-jsx"));
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+/**
+ * NOTE: Side-effect of importing this module's exports.
+ *
+ * Extend acorn-walk's base with missing JSX nodes.
+ * @see https://github.com/acornjs/acorn/issues/829
+ *
+ * Consider another parser that supports more syntaxes out-of-the-box.
+ * That would enable less requirements on loader chaining.
+ */
+(0, _acornJsxWalk.extend)(_acornWalk.base);
+const jsxParser = _acorn.Parser.extend((0, _acornJsx.default)());
+const parse = source => {
+  const comments = [];
+  const importExpressionNodes = [];
+  const ast = jsxParser.parse(source, {
+    locations: false,
+    ecmaVersion: 2023,
+    sourceType: 'module',
+    allowAwaitOutsideFunction: true,
+    allowReturnOutsideFunction: true,
+    allowImportExportEverywhere: true,
+    onComment: (isBlock, commentText, start, end) => {
+      if (isBlock) {
+        comments.push({
+          start,
+          end,
+          commentText
+        });
+      }
+    }
+  });
+  (0, _acornWalk.simple)(ast, {
+    ImportExpression(node) {
+      importExpressionNodes.push(node);
+    }
+  });
+  return {
+    ast,
+    comments,
+    importExpressionNodes,
+    source
+  };
+};
+exports.parse = parse;

package/dist/cjs/schema.cjs

@@ -19,6 +19,9 @@ const schema = {
     verbose: {
       type: 'boolean'
     },
+    mode: {
+      enum: ['parser', 'regexp']
+    },
     match: {
       enum: ['module', 'import']
     },

package/dist/cjs/util.cjs

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.pathIsMatch = exports.importPrefix = exports.getOverrideSchema = exports.getOverrideConfig = exports.dynamicImportsWithoutComments = void 0;
+exports.pathIsMatch = exports.importPrefix = exports.getOverrideSchema = exports.getOverrideConfig = exports.getBareImportSpecifier = exports.dynamicImportsWithoutComments = void 0;
 var _micromatch = _interopRequireDefault(require("micromatch"));
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 const pathIsMatch = (path, files) => {
@@ -56,6 +56,10 @@ const getOverrideConfig = (overrides, filepath, config) => {
   return config;
 };
 exports.getOverrideConfig = getOverrideConfig;
+const getBareImportSpecifier = specifier => {
+  return specifier.replace(/['"`]/g, '');
+};
+exports.getBareImportSpecifier = getBareImportSpecifier;
 const importPrefix = /^(?:(\.{1,2}\/)+)|^\/|^.+:\/\/\/?[.-\w]+\//;
 exports.importPrefix = importPrefix;
 const dynamicImportsWithoutComments = /(?<![\w.]|#!|(?:\/{2}.+\n?)+|\/\*[\s\w]*?|\*.+?|['"`][^)$,\n]*)import\s*\((?!\s*\/\*)(?<path>\s*?['"`][^)]+['"`]\s*)\)(?!\s*?\*\/)/gm;

package/dist/comment.js

@@ -1,14 +1,15 @@
 import { commentFor } from './strategy.js';
+import { getBareImportSpecifier } from './util.js';
 const getCommenter = (filepath, options, logger) => (rgxMatch, capturedImportPath) => {
   const importPath = capturedImportPath.trim();
-  const bareImportPath = importPath.replace(/['"`]/g, '');
+  const bareImportPath = getBareImportSpecifier(importPath);
   const {
     verbose,
     match,
-    ...magicCommentOptions
+    magicCommentOptions
   } = options;
   const magicComment = Object.keys(magicCommentOptions).map(key => commentFor[key](filepath, bareImportPath, magicCommentOptions[key], match)).filter(Boolean);
-  const magicImport = rgxMatch.replace(capturedImportPath, magicComment.length > 0 ? `/* ${magicComment.join(', ')} */ ${importPath}` : `${importPath}`);
+  const magicImport = rgxMatch.replace(capturedImportPath, magicComment.length > 0 ? `/* ${magicComment.join(', ')} */ ${importPath}` : importPath);
   if (verbose) {
     logger.info(`${filepath} : ${magicImport}`);
   }

package/dist/formatter.js

@@ -0,0 +1,38 @@
+import MagicString from 'magic-string';
+import { commentFor } from './strategy.js';
+import { getBareImportSpecifier } from './util.js';
+const format = ({
+  match,
+  source,
+  filepath,
+  comments,
+  magicCommentOptions,
+  importExpressionNodes
+}) => {
+  const magicImports = [];
+  const step = 'import('.length;
+  const cmts = [...comments];
+  const src = new MagicString(source);
+  const hasComment = node => {
+    const idx = cmts.findIndex(cmt => cmt.start > node.start && cmt.end < node.end);
+    const wasFound = idx > -1;
+    if (wasFound) {
+      cmts.splice(idx, 1);
+    }
+    return wasFound;
+  };
+  for (const node of importExpressionNodes) {
+    if (!hasComment(node)) {
+      const specifier = source.substring(node.start + step, node.end - 1);
+      const bareImportPath = getBareImportSpecifier(specifier);
+      const magic = Object.keys(magicCommentOptions).map(key => commentFor[key](filepath, bareImportPath, magicCommentOptions[key], match)).filter(Boolean);
+      if (magic.length) {
+        const magicComment = `/* ${magic.join(', ')} */ `;
+        magicImports.push(src.snip(node.start, node.end).toString().replace(specifier, `${magicComment}${specifier}`));
+        src.appendRight(node.start + step, `${magicComment}`);
+      }
+    }
+  }
+  return [src.toString(), magicImports];
+};
+export { format };

package/dist/loader.js

@@ -1,19 +1,43 @@
 import { validate } from 'schema-utils';
 import { schema } from './schema.js';
+import { parse } from './parser.js';
+import { format } from './formatter.js';
 import { getCommenter } from './comment.js';
 import { dynamicImportsWithoutComments } from './util.js';
-const loader = function (source, map, meta) {
+const loader = function (source) {
   const options = this.getOptions();
-  const optionKeys = Object.keys(options);
   const logger = this.getLogger('MCL');
   validate(schema, options, {
     name: 'magic-comments-loader'
   });
-  const filepath = this.utils.contextify(this.rootContext, this.resourcePath);
-  const magicComments = getCommenter(filepath.replace(/^\.\/?/, ''), optionKeys.length > 0 ? options : {
-    match: 'module',
+  const {
+    mode = 'parser',
+    match = 'module',
+    verbose = false,
+    ...rest
+  } = options;
+  const magicCommentOptions = Object.keys(rest).length ? rest : {
     webpackChunkName: true
-  }, logger);
-  this.callback(null, source.replace(dynamicImportsWithoutComments, magicComments), map, meta);
+  };
+  const filepath = this.utils.contextify(this.rootContext, this.resourcePath).replace(/^\.\/?/, '');
+  if (mode === 'parser') {
+    const [magicSource, magicImports] = format({
+      ...parse(source),
+      match,
+      filepath,
+      magicCommentOptions
+    });
+    if (verbose) {
+      magicImports.forEach(magicImport => {
+        logger.info(`${filepath} : ${magicImport}`);
+      });
+    }
+    return magicSource;
+  }
+  return source.replace(dynamicImportsWithoutComments, getCommenter(filepath, {
+    verbose,
+    match,
+    magicCommentOptions
+  }, logger));
 };
 export { loader };

package/dist/parser.js

@@ -0,0 +1,49 @@
+import { Parser } from 'acorn';
+import { simple, base } from 'acorn-walk';
+import { extend } from 'acorn-jsx-walk';
+import jsx from 'acorn-jsx';
+
+/**
+ * NOTE: Side-effect of importing this module's exports.
+ *
+ * Extend acorn-walk's base with missing JSX nodes.
+ * @see https://github.com/acornjs/acorn/issues/829
+ *
+ * Consider another parser that supports more syntaxes out-of-the-box.
+ * That would enable less requirements on loader chaining.
+ */
+extend(base);
+const jsxParser = Parser.extend(jsx());
+const parse = source => {
+  const comments = [];
+  const importExpressionNodes = [];
+  const ast = jsxParser.parse(source, {
+    locations: false,
+    ecmaVersion: 2023,
+    sourceType: 'module',
+    allowAwaitOutsideFunction: true,
+    allowReturnOutsideFunction: true,
+    allowImportExportEverywhere: true,
+    onComment: (isBlock, commentText, start, end) => {
+      if (isBlock) {
+        comments.push({
+          start,
+          end,
+          commentText
+        });
+      }
+    }
+  });
+  simple(ast, {
+    ImportExpression(node) {
+      importExpressionNodes.push(node);
+    }
+  });
+  return {
+    ast,
+    comments,
+    importExpressionNodes,
+    source
+  };
+};
+export { parse };

package/dist/schema.js

@@ -13,6 +13,9 @@ const schema = {
     verbose: {
       type: 'boolean'
     },
+    mode: {
+      enum: ['parser', 'regexp']
+    },
     match: {
       enum: ['module', 'import']
     },

package/dist/util.js

@@ -46,6 +46,9 @@ const getOverrideConfig = (overrides, filepath, config) => {
   }
   return config;
 };
+const getBareImportSpecifier = specifier => {
+  return specifier.replace(/['"`]/g, '');
+};
 const importPrefix = /^(?:(\.{1,2}\/)+)|^\/|^.+:\/\/\/?[.-\w]+\//;
 const dynamicImportsWithoutComments = /(?<![\w.]|#!|(?:\/{2}.+\n?)+|\/\*[\s\w]*?|\*.+?|['"`][^)$,\n]*)import\s*\((?!\s*\/\*)(?<path>\s*?['"`][^)]+['"`]\s*)\)(?!\s*?\*\/)/gm;
-export { getOverrideConfig, getOverrideSchema, pathIsMatch, importPrefix, dynamicImportsWithoutComments };
+export { getBareImportSpecifier, getOverrideConfig, getOverrideSchema, pathIsMatch, importPrefix, dynamicImportsWithoutComments };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "magic-comments-loader",
-  "version": "1.5.1",
-  "description": "Add webpack magic comments to your dynamic imports at build time",
+  "version": "1.6.0",
+  "description": "Add webpack magic comments to your dynamic imports at build time.",
   "main": "dist",
   "type": "module",
   "exports": {
@@ -64,7 +64,12 @@
     "webpack": "^5.87.0"
   },
   "dependencies": {
+    "acorn": "^8.9.0",
+    "acorn-jsx": "^5.3.2",
+    "acorn-jsx-walk": "^2.0.0",
+    "acorn-walk": "^8.2.0",
     "loader-utils": "^3.2.1",
+    "magic-string": "^0.30.0",
     "micromatch": "^4.0.4",
     "schema-utils": "^4.1.0"
   }