dependency-tree 11.4.3 → 11.5.0

package/README.md

@@ -10,18 +10,17 @@
 npm install dependency-tree
 ```
 
-* Works for JS (AMD, CommonJS, ES6 modules), TypeScript, and CSS preprocessors (CSS (PostCSS), Sass, Stylus, and Less); basically, any module type supported by [precinct](https://github.com/dependents/node-precinct).
-  - For CommonJS modules, 3rd party dependencies (npm installed dependencies) are included in the tree by default
-  - Dependency path resolutions are handled by [filing-cabinet](https://github.com/dependents/node-filing-cabinet)
-  - Supports RequireJS and Webpack loaders
-* All core Node modules (assert, path, fs, etc) are removed from the dependency list by default
+* Supports JS (AMD, CommonJS, ES6), TypeScript, and CSS preprocessors (PostCSS, Sass, Stylus, Less) - any type handled by [precinct](https://github.com/dependents/node-precinct)
+  - CommonJS: third-party (npm) dependencies are included by default
+  - Path resolution is handled by [filing-cabinet](https://github.com/dependents/node-filing-cabinet); RequireJS and webpack loaders are supported
+* Core Node built-ins (assert, path, fs, etc.) are excluded by default
 
 ## Usage
 
 ```js
 const dependencyTree = require('dependency-tree');
 
-// Returns a dependency tree object for the given file
+// Returns a nested dependency tree object for the given file
 const tree = dependencyTree({
   filename: 'path/to/a/file',
   directory: 'path/to/all/files',
@@ -31,14 +30,13 @@ const tree = dependencyTree({
   nodeModulesConfig: {
     entry: 'module'
   }, // optional
-  filter: path => path.indexOf('node_modules') === -1, // optional
+  filter: path => !path.includes('node_modules'), // optional
   nonExistent: [], // optional
   noTypeDefinitions: false // optional
 });
 
-// Returns a post-order traversal (list form) of the tree with duplicate sub-trees pruned.
-// This is useful for bundling source files, because the list gives the concatenation order.
-// Note: you can pass the same arguments as you would to dependencyTree()
+// Returns a post-order flat list of absolute paths (dependencies before dependents).
+// Useful as a concatenation order for bundling.
 const list = dependencyTree.toList({
   filename: 'path/to/a/file',
   directory: 'path/to/all/files'
@@ -47,78 +45,68 @@ const list = dependencyTree.toList({
 
 ### Options
 
-* `requireConfig`: path to a requirejs config for AMD modules (allows for the result of aliased module paths)
-* `webpackConfig`: path to a webpack config for aliased modules
-* `tsConfig`: path to a typescript config (or a preloaded object representing the typescript config)
-* `tsConfigPath`: a (virtual) path to typescript config file when `tsConfig` option is given as an object, not a string. Needed to calculate [Path Mapping](https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping). If not given when `tsConfig` is an object, **Path Mapping** is ignored. This is not needed when `tsConfig` is given as a path string.
-* `nodeModulesConfig`: config for resolving entry file for node_modules
-* `visited`: object used for avoiding redundant subtree generations via memoization.
-* `nonExistent`: array used for storing the list of partial paths that do not exist
-* `filter`: a function used to determine if a module (and its subtree) should be included in the dependency tree
- - The first argument given to the filter is an absolute filepath to the dependency and the second is the filepath to the currently traversed file. Should return a `Boolean`. If it returns `true`, the module is included in the resulting tree.
-* `detective`: object with configuration specific to detectives used to find dependencies of a file
-  - for example `detective.amd.skipLazyLoaded: true` tells the AMD detective to omit inner requires
-  - See [precinct's usage docs](https://github.com/dependents/node-precinct#usage) for the list of module types you can pass options to.
-* `noTypeDefinitions`: For TypeScript imports, whether to resolve to `*.js` instead of `*.d.ts`.
-
-### Format Details
-
-The object form is a mapping of the dependency tree to the filesystem –
-where every key is an absolute filepath and the value is another object/subtree.
-
-Example:
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `filename` | `string` | - | **Required.** Absolute path to the entry file |
+| `directory` | `string` | - | **Required.** Root directory used to resolve relative paths |
+| `requireConfig` | `string` | `undefined` | Path to a RequireJS config for AMD modules (resolves aliased paths) |
+| `webpackConfig` | `string` | `undefined` | Path to a webpack config for aliased modules |
+| `tsConfig` | `string \| object` | `undefined` | Path to a TypeScript config file, or a preloaded config object |
+| `tsConfigPath` | `string` | `undefined` | Virtual path for the TypeScript config when `tsConfig` is an object. Required for [Path Mapping](https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping); ignored when `tsConfig` is a string path |
+| `nodeModulesConfig` | `object` | `undefined` | Config for resolving `node_modules` entry files (e.g. `{ entry: 'module' }`) |
+| `visited` | `object` | `{}` | Memoization cache (`filename → subtree`) to skip already-processed files |
+| `nonExistent` | `string[]` | `[]` | Array populated with partial paths that could not be resolved |
+| `filter` | `(depPath, parentPath) => boolean` | `undefined` | Return `true` to include a dependency (and its subtree) in the tree |
+| `detective` | `object` | `undefined` | Detector options passed to [precinct](https://github.com/dependents/node-precinct#usage) - e.g. `{ amd: { skipLazyLoaded: true } }` |
+| `noTypeDefinitions` | `boolean` | `false` | Resolve TypeScript imports to `*.js` instead of `*.d.ts` |
+
+### Output format
+
+The default output is a nested object where every key is an absolute file path and the value is its own subtree:
 
 ```js
 {
-  '/Users/mrjoelkemp/Documents/node-dependency-tree/test/example/extended/a.js': {
-    '/Users/mrjoelkemp/Documents/node-dependency-tree/test/example/extended/b.js': {
-      '/Users/mrjoelkemp/Documents/node-dependency-tree/test/example/extended/d.js': {},
-      '/Users/mrjoelkemp/Documents/node-dependency-tree/test/example/extended/e.js': {}
+  '/path/to/a.js': {
+    '/path/to/b.js': {
+      '/path/to/d.js': {},
+      '/path/to/e.js': {}
     },
-    '/Users/mrjoelkemp/Documents/node-dependency-tree/test/example/extended/c.js': {
-      '/Users/mrjoelkemp/Documents/node-dependency-tree/test/example/extended/f.js': {},
-      '/Users/mrjoelkemp/Documents/node-dependency-tree/test/example/extended/g.js': {}
+    '/path/to/c.js': {
+      '/path/to/f.js': {},
+      '/path/to/g.js': {}
     }
   }
 }
 ```
 
-This structure was chosen to serve as a visual representation of the dependency tree
-for use in the [Dependents](https://github.com/mrjoelkemp/sublime-dependents) plugin.
+This format was designed for visual representation in the [Dependents](https://github.com/mrjoelkemp/sublime-dependents) plugin.
 
-### CLI version
+### CLI
 
-* Assumes a global install: `npm install -g dependency-tree`
+Requires a global install: `npm install -g dependency-tree`
 
 ```
-dependency-tree --directory=path/to/all/supported/files [--list-form] [-c path/to/require/config] [-w path/to/webpack/config] filename
+dependency-tree --directory=path/to/files [--list-form] [--es6-mixed-imports] [-c path/to/require/config] [-w path/to/webpack/config] filename
 ```
 
-Prints the dependency tree of the given filename as stringified json (by default).
-
-* You can alternatively print out the list form one element per line using the `--list-form` option.
-
-## How does this work?
+Prints the dependency tree as JSON. Use `--list-form` to print one path per line instead.
 
-Dependency tree takes in a starting file, extracts its declared dependencies via [precinct](https://github.com/dependents/node-precinct/), resolves each of those dependencies to a file on the filesystem via [filing-cabinet](https://github.com/dependents/node-filing-cabinet), then recursively performs those steps until there are no more dependencies to process.
+## How it works
 
-In more detail, the starting file is passed to precinct to extract dependencies. Dependency-tree doesn't care about how to extract dependencies, so it delegates that work to precinct: which is a multi-language dependency extractor; we'll focus on JavaScript tree generation for this example. To do the extraction, precinct delegates the abstract-syntax-tree (AST) generation to the default parser for [node-source-walk](https://github.com/dependents/node-source-walk). Precinct uses the AST to determine what type of JS module the file is (Commonjs, AMD, or ES6) and then delegates to the "detective" that's appropriate for that module type. The "detective" contains the logic for how to extract dependencies based on the module syntax format; i.e., the way dependencies are declared in commonjs is different than in AMD (which has 4 ways of doing that, for example).
+dependency-tree passes the entry file to [precinct](https://github.com/dependents/node-precinct/) to extract raw dependency strings, then passes each to [filing-cabinet](https://github.com/dependents/node-filing-cabinet) to resolve them to real filesystem paths, and recurses until the full tree is built.
 
-After using the detective to get the (raw, like './foobar') dependency strings, precinct passes that back to dependency-tree. Of course, in order to find the dependencies in './foobar', we need to resolve that dependency to a real file on the filesystem. To do this, dependency-tree delegates that task to filing-cabinet: which is a multi-language dependency resolver.
+Precinct generates an AST via [node-source-walk](https://github.com/dependents/node-source-walk), detects the module format (CommonJS, AMD, or ES6), and delegates to the appropriate detective to extract dependency declarations.
 
-Filing-cabinet reuses (for performance) the AST that precinct made node-source-walk generate. It then does a similar check on the AST to see which module type (commonjs, amd, or es6) is being used in the file (again, we're assuming a regular JS file for this example) and then delegates to the appropriate resolver for that module type. We need different resolvers because a dependency name in AMD could be aliased via a requirejs config. Similarly, commonjs has its own algorithm for resolving dependencies.
-
-So after the appropriate resolver finds the file on the filesystem, filing-cabinet has successfully mapped a raw dependency name to a file on the filesystem. Now, dependency-tree has a file that it can also traverse (repeating exactly what was done for the starting file).
-
-At the end of traversing every file (in a depth-first fashion), we have a fully populated dependency tree. :dancers:
+Filing-cabinet reuses that AST to detect the module format again, then delegates to the right resolver - necessary because AMD supports path aliasing via a RequireJS config, while CommonJS has its own resolution algorithm. The resolver returns an absolute path, which dependency-tree then recurses into.
 
 ## FAQ
 
-### Why aren't some some dependencies being detected?
+### Why aren't some dependencies being detected?
+
+Bugs in [precinct](https://github.com/dependents/node-precinct) or an incomplete `requireConfig`/`webpackConfig`/`tsConfig` are the most common causes. Any path that could not be resolved is appended to the array passed as `nonExistent`.
 
-If there are bugs in [precinct](https://github.com/dependents/node-precinct) or if the `requireConfig`/`webpackConfig`/`tsConfig` options are incomplete,
-some dependencies may not be resolved. The optional array passed to the `nonExistent` option will be populated with paths
-that could not be resolved. You can check this array to see where problems might exist.
+For detailed resolution logs, set `NODE_DEBUG=*` when using the CLI:
 
-You can also use the `NODE_DEBUG=*` env variable along with the cli version to see debugging information explaining where resolution went wrong.
-Example: `NODE_DEBUG=* dependency-tree -w path/to/webpack.config.json path/to/a/file`
+```sh
+NODE_DEBUG=* dependency-tree -w path/to/webpack.config.json path/to/a/file
+```

package/bin/cli.js

@@ -2,7 +2,9 @@
 
 'use strict';
 
+const process = require('node:process');
 const { program } = require('commander');
+const { stringifyChunked } = require('@discoveryjs/json-ext');
 const dependencyTree = require('../index.js');
 const { name, description, version } = require('../package.json');
 
@@ -16,6 +18,7 @@ program
   .option('-c, --require-config <path>', 'path to a requirejs config')
   .option('-w, --webpack-config <path>', 'path to a webpack config')
   .option('-t, --ts-config <path>', 'path to a typescript config')
+  .option('--es6-mixed-imports', 'detect dependencies from files that mix ES6 imports and CJS require() calls')
   .option('--list-form', 'output the list form of the tree (one element per line)')
   .showHelpAfterError()
   .parse();
@@ -26,7 +29,12 @@ const options = {
   root: cliOptions.directory,
   config: cliOptions.requireConfig,
   webpackConfig: cliOptions.webpackConfig,
-  tsConfig: cliOptions.tsConfig
+  tsConfig: cliOptions.tsConfig,
+  detective: {
+    es6: {
+      mixedImports: Boolean(cliOptions.es6MixedImports)
+    }
+  }
 };
 
 if (cliOptions.listForm) {
@@ -38,5 +46,9 @@ if (cliOptions.listForm) {
 } else {
   const tree = dependencyTree(options);
 
-  console.log(JSON.stringify(tree));
+  for (const chunk of stringifyChunked(tree)) {
+    process.stdout.write(chunk);
+  }
+
+  process.stdout.write('\n');
 }

package/index.js

@@ -10,22 +10,21 @@ const Config = require('./lib/config.js');
 const debug = debuglog('tree');
 
 /**
- * Recursively find all dependencies (avoiding circular) traversing the entire dependency tree
- * and returns a flat list of all unique, visited nodes
+ * Returns the dependency tree of a module as a nested object
  *
  * @param {Object} options
- * @param {String} options.filename - The path of the module whose tree to traverse
- * @param {String} options.directory - The directory containing all JS files
- * @param {String} [options.requireConfig] - The path to a requirejs config
- * @param {String} [options.webpackConfig] - The path to a webpack config
- * @param {String} [options.nodeModulesConfig] - config for resolving entry file for node_modules
- * @param {Object} [options.visited] - Cache of visited, absolutely pathed files that should not be reprocessed.
- *                                     Format is a filename -> tree as list lookup table
- * @param {Array} [options.nonExistent] - List of partials that do not exist
- * @param {Boolean} [options.isListForm=false]
- * @param {String|Object} [options.tsConfig] Path to a typescript config (or a preloaded one).
- * @param {Boolean} [options.noTypeDefinitions] For TypeScript imports, whether to resolve to `*.js` instead of `*.d.ts`.
- * @return {Object}
+ * @param {string} options.filename - Entry module path
+ * @param {string} options.directory - Root directory containing all files
+ * @param {string} [options.requireConfig] - Path to a RequireJS config
+ * @param {string} [options.webpackConfig] - Path to a webpack config
+ * @param {string} [options.nodeModulesConfig] - Config for resolving node_modules entry files
+ * @param {Object} [options.visited] - Memoization cache: filename ? subtree
+ * @param {Array}  [options.nonExistent] - Accumulator for unresolvable partials
+ * @param {boolean} [options.isListForm=false] - Return a flat list instead of a tree
+ * @param {string|Object} [options.tsConfig] - Path to (or preloaded) TypeScript config
+ * @param {string} [options.tsConfigPath] - (Virtual) path to tsconfig when tsConfig is an object; needed for Path Mapping
+ * @param {boolean} [options.noTypeDefinitions] - Resolve TS imports to `*.js` instead of `*.d.ts`
+ * @returns {Object}
  */
 module.exports = function(options = {}) {
   const config = new Config(options);
@@ -56,30 +55,23 @@ module.exports = function(options = {}) {
 };
 
 /**
- * Executes a post-order depth first search on the dependency tree and returns a
- * list of absolute file paths. The order of files in the list will be the
- * proper concatenation order for bundling.
+ * Returns a post-order flat list of absolute file paths (dependencies before dependents).
+ * Every file's dependencies appear at lower indices, so the root entry point is last.
+ * The list contains no duplicates. Accepts the same options as the default export.
  *
- * In other words, for any file in the list, all of that file's dependencies (direct or indirect) will appear at
- * lower indices in the list. The root (entry point) file will therefore appear last.
- *
- * The list will not contain duplicates.
- *
- * Params are those of module.exports
+ * @param {Object} options - Same as the default export
+ * @returns {Array<string>}
  */
 module.exports.toList = function(options = {}) {
-  options.isListForm = true;
-
-  return module.exports(options);
+  return module.exports({ ...options, isListForm: true });
 };
 
 /**
- * Returns the list of dependencies for the given filename
- *
- * Protected for testing
+ * Returns resolved dependency paths for the file described by `config`.
+ * Exposed for testing.
  *
- * @param  {Config} config
- * @return {Array}
+ * @param {Config} config
+ * @returns {Array<string>}
  */
 module.exports._getDependencies = function(config = {}) {
   const precinctOptions = config.detectiveConfig;
@@ -132,8 +124,8 @@ module.exports._getDependencies = function(config = {}) {
 };
 
 /**
- * @param  {Config} config
- * @return {Object|Set}
+ * @param {Config} config
+ * @returns {Object|Set}
  */
 function traverse(config = {}) {
   const subTree = config.isListForm ? new Set() : {};
@@ -148,8 +140,7 @@ function traverse(config = {}) {
   let dependencies = module.exports._getDependencies(config);
 
   debug('cabinet-resolved all dependencies: ', dependencies);
-  // Prevents cycles by eagerly marking the current file as read
-  // so that any dependent dependencies exit
+  // Eagerly mark the current file before recursing so any re-entrant visit exits early
   config.visited[config.filename] = config.isListForm ? [] : {};
 
   if (config.filter) {
@@ -163,7 +154,7 @@ function traverse(config = {}) {
   for (const dependency of dependencies) {
     const localConfig = config.clone();
     localConfig.filename = dependency;
-    localConfig.directory = getDirectory(localConfig);
+    localConfig.directory = getLocalConfigDirectory(localConfig);
 
     if (localConfig.isListForm) {
       for (const item of traverse(localConfig)) {
@@ -184,7 +175,7 @@ function traverse(config = {}) {
   return subTree;
 }
 
-// Mutate the list input to do a dereferenced modification of the user-supplied list
+// Dedupe in-place so the caller's array reference stays valid
 function dedupeNonExistent(nonExistent) {
   const deduped = new Set(nonExistent);
   nonExistent.length = deduped.size;
@@ -196,24 +187,35 @@ function dedupeNonExistent(nonExistent) {
   }
 }
 
-// If the file is in a node module, use the root directory of the module
-function getDirectory(localConfig) {
-  if (!localConfig.filename.includes('node_modules')) {
-    return localConfig.directory;
+// If the file is in a node_modules directory, we want to resolve the root of the package,
+// not the file itself, since the file may be buried in a subdirectory and not contain all
+// of the package's dependencies
+function getLocalConfigDirectory(localConfig) {
+  const { filename, directory } = localConfig;
+
+  if (!filename.includes('node_modules')) {
+    return directory;
   }
 
-  return getProjectPath(path.dirname(localConfig.filename)) || localConfig.directory;
-}
+  const dir = path.dirname(filename);
+  const parts = dir.split('node_modules');
 
-function getProjectPath(filename) {
-  try {
-    const nodeModuleParts = filename.split('node_modules');
-    const packageSubPathPath = nodeModuleParts.pop().split(path.sep).filter(Boolean);
-    const packageName = packageSubPathPath[0].startsWith('@') ? `${packageSubPathPath[0]}${path.sep}${packageSubPathPath[1]}` : packageSubPathPath[0];
-
-    return path.normalize([...nodeModuleParts, `${path.sep}${packageName}`].join('node_modules'));
-  } catch {
-    debug(`Could not determine the root directory of package file ${filename}. Using default`);
-    return null;
+  if (parts.length < 2) {
+    return directory;
   }
+
+  const afterNodeModules = parts.pop();
+  if (!afterNodeModules) {
+    return directory;
+  }
+
+  const segments = afterNodeModules.split(path.sep).filter(Boolean);
+  if (segments.length === 0) {
+    return directory;
+  }
+
+  const packageName = segments[0].startsWith('@') ? `${segments[0]}${path.sep}${segments[1]}` : segments[0];
+  const projectPath = path.normalize(`${parts.join('node_modules')}node_modules${path.sep}${packageName}`);
+
+  return projectPath;
 }

package/lib/config.js

@@ -27,6 +27,7 @@ module.exports = class Config {
     if (this.filter && typeof this.filter !== 'function') throw new Error('filter must be a function');
 
     if (typeof this.tsConfig === 'string') {
+      // Pre-parse once so all recursive clones share the object form
       debug('preparsing the ts config into an object for performance');
       const ts = require('typescript');
       const tsParsedConfig = ts.readJsonConfigFile(this.tsConfig, ts.sys.readFile);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dependency-tree",
-  "version": "11.4.3",
+  "version": "11.5.0",
   "description": "Get the dependency tree of a module",
   "main": "index.js",
   "types": "index.d.ts",
@@ -49,9 +49,10 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@discoveryjs/json-ext": "^1.1.0",
     "commander": "^12.1.0",
-    "filing-cabinet": "^5.3.0",
-    "precinct": "^12.3.1",
+    "filing-cabinet": "^5.5.1",
+    "precinct": "^12.3.2",
     "typescript": "^5.9.3"
   },
   "devDependencies": {