fix: external was removed as prefer of input usages

BREAKING CHANGE:
external parameter was removed
Migration plan propose to move all external resources to input usages
Motivation: packages has many inputs which describe in package.json
so that mean need each time to parse all package.json of exsternal resources to understand which etry point need to pick.
But it is base on guesses because entry point may could not contains a documentation and the best way to handle it manualy.

Author: anthony-redFox

__tests__/__snapshots__/test.js.snap

@@ -98,14 +98,6 @@ test('--shallow option', async function () {
   expect(data.length).toBe(0);
 });
 
-test('external modules option', async function () {
-  const data = await documentation([
-    'build fixture/external.input.js ' +
-      '--external=external --external=external/node_modules'
-  ]);
-  expect(data.length).toBe(2);
-});
-
 test('when a file is specified both in a glob and explicitly, it is only documented once', async function () {
   const data = await documentation([
     'build fixture/simple.input.js fixture/simple.input.*'

__tests__/bin.js

@@ -1,13 +1,6 @@
-import moduleFilters from '../../src/module_filters.js';
+import internalOnly from '../../src/module_filters.js';
 
 test('moduleFilters.internalOnly', function () {
-  expect(moduleFilters.internalOnly('./foo')).toEqual(true);
-  expect(moduleFilters.internalOnly('foo')).toEqual(false);
-});
-
-test('moduleFilters.externals', function () {
-  expect(moduleFilters.externals([], {})('./foo')).toEqual(true);
-  expect(
-    moduleFilters.externals([], { external: 'node_modules' })('./foo')
-  ).toEqual(true);
+  expect(internalOnly('./foo')).toEqual(true);
+  expect(internalOnly('foo')).toEqual(false);
 });

__tests__/lib/module_filters.js

@@ -59,19 +59,15 @@ test('document-exported error', async function () {
   }
 });
 
-test('external modules option', async function () {
-  const result = await documentation.build(
-    [path.join(__dirname, 'fixture', 'external.input.js')],
-    {
-      external: '(external|external/node_modules/*)'
-    }
-  );
+test('Check that external modules could parse as input', async function () {
+  const dir = path.join(__dirname, 'fixture');
+  const result = await documentation.build([
+    path.join(dir, 'node_modules', 'external', 'lib', 'main.js'),
+    path.join(dir, 'node_modules', 'external2', 'index.js'),
+    path.join(dir, 'external.input.js')
+  ]);
   normalize(result);
-  const outputfile = path.join(
-    __dirname,
-    'fixture',
-    '_external-deps-included.json'
-  );
+  const outputfile = path.join(dir, '_external-deps-included.json');
   expect(result).toMatchSnapshot();
 });
 

__tests__/test.js

@@ -40,15 +40,10 @@ Options:
   --no-package, --np         dont find and use package.json for project-
                              configuration option defaults
                                                       [boolean] [default: false]
-  --external                 a string / glob match pattern that defines which
-                             external modules will be whitelisted and included
-                             in the generated documentation.     [default: null]
   --require-extension, --re  additional extensions to include in require() and
                              import's search algorithm.For instance, adding .es5
                              would allow require("adder") to find "adder.es5"
   --parse-extension, --pe    additional extensions to parse as source code.
-  --private, -p              generate documentation tagged as private
-                                                      [boolean] [default: false]
   --access, -a               Include only comments with a given access level,
                              out of private, protected, public, undefined. By
                              default, public, protected, and undefined access

docs/USAGE.md

@@ -14,7 +14,6 @@
     "@babel/parser": "^7.15.4",
     "@babel/traverse": "^7.15.4",
     "@babel/types": "^7.14.1",
-    "babelify": "^10.0.0",
     "chalk": "^4.1.2",
     "chokidar": "^3.4.0",
     "concat-stream": "^2.0.0",
@@ -31,7 +30,6 @@
     "mdast-util-find-and-replace": "^2.1.0",
     "mdast-util-inject": "^1.1.0",
     "micromark-util-character": "^1.1.0",
-    "micromatch": "^4.0.4",
     "module-deps-sortable": "^5.0.3",
     "parse-filepath": "^1.0.2",
     "pify": "^5.0.0",

package-lock.json

@@ -1,16 +1,9 @@
 import mdeps from 'module-deps-sortable';
 import path from 'path';
-import babelify from 'babelify';
 import concat from 'concat-stream';
-import moduleFilters from '../module_filters.js';
-import { standardBabelParserPlugins } from '../parsers/parse_to_ast.js';
+import internalOnly from '../module_filters.js';
 import smartGlob from '../smart_glob.js';
 
-const STANDARD_BABEL_CONFIG = {
-  compact: false,
-  parserOpts: { plugins: [...standardBabelParserPlugins, 'flow', 'jsx'] }
-};
-
 /**
  * Returns a readable stream of dependencies, given an array of entry
  * points and an object of options to provide to module-deps.
@@ -23,22 +16,17 @@ const STANDARD_BABEL_CONFIG = {
  * @returns results
  */
 export default function dependencyStream(indexes, config) {
-  const babelConfig = config.babel
-    ? { configFile: path.resolve(__dirname, '../../../../', config.babel) }
-    : STANDARD_BABEL_CONFIG;
   const md = mdeps({
     /**
      * Determine whether a module should be included in documentation
      * @param {string} id path to a module
      * @returns {boolean} true if the module should be included.
      */
-    filter: id => !!config.external || moduleFilters.internalOnly(id),
+    filter: id => internalOnly(id),
     extensions: []
       .concat(config.requireExtension || [])
       .map(ext => '.' + ext.replace(/^\./, ''))
       .concat(['.mjs', '.js', '.json', '.es6', '.jsx']),
-    transform: [babelify.configure(babelConfig)],
-    postFilter: moduleFilters.externals(indexes, config),
     resolve:
       config.resolve === 'node' &&
       ((id, opts, cb) => {

package.json

@@ -1,6 +1,3 @@
-import path from 'path';
-import micromatch from 'micromatch';
-
 // Skip external modules. Based on http://git.io/pzPO.
 const internalModuleRegexp =
   process.platform === 'win32'
@@ -11,52 +8,4 @@ const internalModuleRegexp =
 /**
  * Module filters
  */
-export default {
-  internalOnly: internalModuleRegexp.test.bind(internalModuleRegexp),
-
-  /**
-   * Create a filter function for use with module-deps, allowing the specified
-   * external modules through.
-   *
-   * @param {Array<string>} indexes - the list of entry points that will be
-   * used by module-deps
-   * @param {Object} options - An options object with `external` being a
-   * micromatch-compatible glob. *NOTE:* the glob will be matched relative to
-   * the top-level node_modules directory for each entry point.
-   * @returns {function} - A function for use as the module-deps `postFilter`
-   * options.
-   */
-  externals: function externalModuleFilter(indexes, options) {
-    let externalFilters = false;
-    if (options.external) {
-      externalFilters = indexes.map(index => {
-        // grab the path of the top-level node_modules directory.
-        const topNodeModules = path.join(path.dirname(index), 'node_modules');
-        return function matchGlob(file, pkg) {
-          // if a module is not found, don't include it.
-          if (!file || !pkg) {
-            return false;
-          }
-          // if package.json specifies a 'main' script, strip that path off
-          // the file to get the module's directory.
-          // otherwise, just use the dirname of the file.
-          if (pkg.main) {
-            file = file.slice(0, -path.normalize(pkg.main).length);
-          } else {
-            file = path.dirname(file);
-          }
-          // test the path relative to the top node_modules dir.
-          const p = path.relative(topNodeModules, file);
-          return micromatch.any(p, options.external);
-        };
-      });
-    }
-
-    return function (id, file, pkg) {
-      const internal = internalModuleRegexp.test(id);
-      return (
-        internal || (externalFilters && externalFilters.some(f => f(file, pkg)))
-      );
-    };
-  }
-};
+export default id => internalModuleRegexp.test(id);