magic-comments-loader 1.5.0 → 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/booleanComment.js

@@ -0,0 +1,90 @@
+import { getOverrideSchema, pathIsMatch, importPrefix } from './util.js';
+const defaultSchema = {
+  type: 'object',
+  properties: {
+    active: {
+      oneOf: [{
+        type: 'boolean'
+      }, {
+        instanceof: 'Function'
+      }]
+    }
+  },
+  additionalProperties: false
+};
+const getSchema = (commentSchema = defaultSchema) => ({
+  oneOf: [{
+    type: 'boolean'
+  }, {
+    type: 'string'
+  }, {
+    type: 'array',
+    items: {
+      type: 'string'
+    }
+  }, {
+    instanceof: 'Function'
+  }, {
+    type: 'object',
+    properties: {
+      config: commentSchema,
+      overrides: getOverrideSchema(commentSchema)
+    },
+    required: ['config'],
+    additionalProperties: false
+  }]
+});
+const getConfig = (value, match, filepath, importPath, defaultConfig = {
+  active: true
+}) => {
+  const path = match === 'import' ? importPath.replace(importPrefix, '') : filepath;
+  if (value === true) {
+    return defaultConfig;
+  }
+  if (value === false) {
+    return {
+      ...defaultConfig,
+      active: false
+    };
+  }
+  if (Array.isArray(value) || typeof value === 'string') {
+    return {
+      ...defaultConfig,
+      active: pathIsMatch(path, value)
+    };
+  }
+  if (typeof value === 'function') {
+    const configValue = value(filepath, importPath);
+    if (configValue) {
+      return {
+        ...defaultConfig,
+        active: true,
+        dynamic: configValue
+      };
+    }
+    return {
+      ...defaultConfig,
+      active: false
+    };
+  }
+  let config = {
+    ...defaultConfig,
+    ...value.config
+  };
+  if (Array.isArray(value.overrides)) {
+    const {
+      overrides
+    } = value;
+    const length = overrides.length;
+    for (let i = 0; i < length; i++) {
+      if (pathIsMatch(path, overrides[i].files)) {
+        return {
+          ...config,
+          ...overrides[i].config
+        };
+      }
+    }
+  }
+  return config;
+};
+export { getSchema, getConfig };

package/dist/cjs/booleanComment.cjs

@@ -0,0 +1,97 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getSchema = exports.getConfig = void 0;
+var _util = require("./util.cjs");
+const defaultSchema = {
+  type: 'object',
+  properties: {
+    active: {
+      oneOf: [{
+        type: 'boolean'
+      }, {
+        instanceof: 'Function'
+      }]
+    }
+  },
+  additionalProperties: false
+};
+const getSchema = (commentSchema = defaultSchema) => ({
+  oneOf: [{
+    type: 'boolean'
+  }, {
+    type: 'string'
+  }, {
+    type: 'array',
+    items: {
+      type: 'string'
+    }
+  }, {
+    instanceof: 'Function'
+  }, {
+    type: 'object',
+    properties: {
+      config: commentSchema,
+      overrides: (0, _util.getOverrideSchema)(commentSchema)
+    },
+    required: ['config'],
+    additionalProperties: false
+  }]
+});
+exports.getSchema = getSchema;
+const getConfig = (value, match, filepath, importPath, defaultConfig = {
+  active: true
+}) => {
+  const path = match === 'import' ? importPath.replace(_util.importPrefix, '') : filepath;
+  if (value === true) {
+    return defaultConfig;
+  }
+  if (value === false) {
+    return {
+      ...defaultConfig,
+      active: false
+    };
+  }
+  if (Array.isArray(value) || typeof value === 'string') {
+    return {
+      ...defaultConfig,
+      active: (0, _util.pathIsMatch)(path, value)
+    };
+  }
+  if (typeof value === 'function') {
+    const configValue = value(filepath, importPath);
+    if (configValue) {
+      return {
+        ...defaultConfig,
+        active: true,
+        dynamic: configValue
+      };
+    }
+    return {
+      ...defaultConfig,
+      active: false
+    };
+  }
+  let config = {
+    ...defaultConfig,
+    ...value.config
+  };
+  if (Array.isArray(value.overrides)) {
+    const {
+      overrides
+    } = value;
+    const length = overrides.length;
+    for (let i = 0; i < length; i++) {
+      if ((0, _util.pathIsMatch)(path, overrides[i].files)) {
+        return {
+          ...config,
+          ...overrides[i].config
+        };
+      }
+    }
+  }
+  return config;
+};
+exports.getConfig = getConfig;

package/dist/cjs/comment.cjs

@@ -0,0 +1,24 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+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 = (0, _util.getBareImportSpecifier)(importPath);
+  const {
+    verbose,
+    match,
+    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);
+  if (verbose) {
+    logger.info(`${filepath} : ${magicImport}`);
+  }
+  return magicImport;
+};
+exports.getCommenter = getCommenter;

package/dist/cjs/enumComment.cjs

@@ -0,0 +1,99 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getEnumComment = void 0;
+var _util = require("./util.cjs");
+const getEnumComment = (name, enums, defaultValue) => {
+  const configSchema = {
+    type: 'object',
+    properties: {
+      active: {
+        oneOf: [{
+          type: 'boolean'
+        }, {
+          instanceof: 'Function'
+        }]
+      },
+      [name]: {
+        oneOf: [{
+          enum: enums
+        }, {
+          instanceof: 'Function'
+        }]
+      }
+    },
+    additionalProperties: false
+  };
+  const schema = {
+    oneOf: [{
+      type: 'boolean'
+    }, {
+      type: 'string'
+    }, {
+      instanceof: 'Function'
+    }, {
+      type: 'object',
+      properties: {
+        config: configSchema,
+        overrides: (0, _util.getOverrideSchema)(configSchema)
+      },
+      required: ['config'],
+      additionalProperties: false
+    }]
+  };
+  const defaultConfig = {
+    active: true,
+    [name]: defaultValue
+  };
+  const getConfig = (value, filepath) => {
+    if (value === true) {
+      return defaultConfig;
+    }
+    if (value === false) {
+      return {
+        ...defaultConfig,
+        active: false
+      };
+    }
+    if (typeof value === 'string' || typeof value === 'function') {
+      return {
+        ...defaultConfig,
+        [name]: value
+      };
+    }
+    let config = {
+      ...defaultConfig,
+      ...value.config
+    };
+    if (Array.isArray(value.overrides)) {
+      config = (0, _util.getOverrideConfig)(value.overrides, filepath, config);
+    }
+    return config;
+  };
+  const comment = (filepath, importPath, value) => {
+    let enumValue = '';
+    const commentSuffix = `${name[0].toUpperCase()}${name.slice(1)}`;
+    const config = getConfig(value, filepath);
+    const isActive = typeof config.active === 'function' ? config.active(filepath, importPath) : config.active;
+    if (!isActive) {
+      return '';
+    }
+    if (typeof config[name] === 'function') {
+      enumValue = config[name](filepath, importPath);
+    }
+    if (typeof config[name] === 'string') {
+      enumValue = config[name];
+    }
+    if (!enums.includes(enumValue)) {
+      return '';
+    }
+    return `webpack${commentSuffix}: "${enumValue}"`;
+  };
+  return {
+    comment,
+    schema
+  };
+};
+exports.getEnumComment = getEnumComment;

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/index.cjs

@@ -0,0 +1,12 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "default", {
+  enumerable: true,
+  get: function () {
+    return _loader.loader;
+  }
+});
+var _loader = require("./loader.cjs");

package/dist/cjs/loader.cjs

@@ -0,0 +1,49 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+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) {
+  const options = this.getOptions();
+  const logger = this.getLogger('MCL');
+  (0, _schemaUtils.validate)(_schema.schema, options, {
+    name: 'magic-comments-loader'
+  });
+  const {
+    mode = 'parser',
+    match = 'module',
+    verbose = false,
+    ...rest
+  } = options;
+  const magicCommentOptions = Object.keys(rest).length ? rest : {
+    webpackChunkName: true
+  };
+  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/regexComment.cjs

@@ -0,0 +1,101 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getRegexComment = void 0;
+var _util = require("./util.cjs");
+const getRegexComment = type => {
+  const configSchema = {
+    type: 'object',
+    properties: {
+      active: {
+        oneOf: [{
+          type: 'boolean'
+        }, {
+          instanceof: 'Function'
+        }]
+      },
+      include: {
+        oneOf: [{
+          instanceof: 'Function'
+        }, {
+          instanceof: 'RegExp'
+        }]
+      },
+      exclude: {
+        oneOf: [{
+          instanceof: 'Function'
+        }, {
+          instanceof: 'RegExp'
+        }]
+      }
+    },
+    additionalProperties: false
+  };
+  const schema = {
+    oneOf: [{
+      instanceof: 'Function'
+    }, {
+      instanceof: 'RegExp'
+    }, {
+      type: 'object',
+      properties: {
+        config: configSchema,
+        overrides: (0, _util.getOverrideSchema)(configSchema)
+      },
+      required: ['config'],
+      additionalProperties: false
+    }]
+  };
+  const getConfig = (value, filepath) => {
+    if (typeof value === 'function' || value instanceof RegExp) {
+      return {
+        active: true,
+        [type]: value
+      };
+    }
+    let config = {
+      active: true,
+      ...value.config
+    };
+    if (Array.isArray(value.overrides)) {
+      config = (0, _util.getOverrideConfig)(value.overrides, filepath, config);
+    }
+    return config;
+  };
+  const comment = (filepath, importPath, value) => {
+    const config = getConfig(value, filepath);
+    const isActive = typeof config.active === 'function' ? config.active(filepath, importPath) : config.active;
+    let regex = null;
+    if (!isActive) {
+      return '';
+    }
+    if (typeof config[type] === 'function') {
+      regex = config[type](filepath, importPath);
+    }
+    if (config[type] instanceof RegExp) {
+      regex = config[type];
+    }
+    if (!(regex instanceof RegExp)) {
+      return '';
+    }
+    const source = regex.source;
+    const typeName = `${type[0].toUpperCase()}${type.slice(1)}`;
+    /**
+     * Check if the provided RegExp ends in one or more '*'
+     * and if so be sure to escape the ending '/' in the
+     * comments regular expression so as not to break the
+     * comment and cause a SyntaxError.
+     */
+    if (/(\*+)$/.test(source)) {
+      return `webpack${typeName}: /${source}\\/${regex.flags}`;
+    }
+    return `webpack${typeName}: /${source}/${regex.flags}`;
+  };
+  return {
+    comment,
+    schema
+  };
+};
+exports.getRegexComment = getRegexComment;

package/dist/cjs/schema.cjs

@@ -0,0 +1,40 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.schema = void 0;
+var _webpackChunkName = require("./webpackChunkName.cjs");
+var _webpackFetchPriority = require("./webpackFetchPriority.cjs");
+var _webpackMode = require("./webpackMode.cjs");
+var _webpackIgnore = require("./webpackIgnore.cjs");
+var _webpackPrefetch = require("./webpackPrefetch.cjs");
+var _webpackPreload = require("./webpackPreload.cjs");
+var _webpackExports = require("./webpackExports.cjs");
+var _webpackInclude = require("./webpackInclude.cjs");
+var _webpackExclude = require("./webpackExclude.cjs");
+const schema = {
+  type: 'object',
+  properties: {
+    verbose: {
+      type: 'boolean'
+    },
+    mode: {
+      enum: ['parser', 'regexp']
+    },
+    match: {
+      enum: ['module', 'import']
+    },
+    webpackChunkName: _webpackChunkName.schema,
+    webpackFetchPriority: _webpackFetchPriority.schema,
+    webpackMode: _webpackMode.schema,
+    webpackIgnore: _webpackIgnore.schema,
+    webpackPrefetch: _webpackPrefetch.schema,
+    webpackPreload: _webpackPreload.schema,
+    webpackExports: _webpackExports.schema,
+    webpackInclude: _webpackInclude.schema,
+    webpackExclude: _webpackExclude.schema
+  },
+  additionalProperties: false
+};
+exports.schema = schema;