node-modules-tools 0.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anthony Fu <https://github.com/antfu>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+# node-modules-tools
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![bundle][bundle-src]][bundle-href]
+[![JSDocs][jsdocs-src]][jsdocs-href]
+[![License][license-src]][license-href]
+
+## Sponsors
+
+<p align="center">
+  <a href="https://cdn.jsdelivr.net/gh/antfu/static/sponsors.svg">
+    <img src='https://cdn.jsdelivr.net/gh/antfu/static/sponsors.svg'/>
+  </a>
+</p>
+
+## License
+
+[MIT](./LICENSE) License © [Anthony Fu](https://github.com/antfu)
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/node-modules-tools?style=flat&colorA=080f12&colorB=1fa669
+[npm-version-href]: https://npmjs.com/package/node-modules-tools
+[npm-downloads-src]: https://img.shields.io/npm/dm/node-modules-tools?style=flat&colorA=080f12&colorB=1fa669
+[npm-downloads-href]: https://npmjs.com/package/node-modules-tools
+[bundle-src]: https://img.shields.io/bundlephobia/minzip/node-modules-tools?style=flat&colorA=080f12&colorB=1fa669&label=minzip
+[bundle-href]: https://bundlephobia.com/result?p=node-modules-tools
+[license-src]: https://img.shields.io/github/license/antfu/node-modules-tools.svg?style=flat&colorA=080f12&colorB=1fa669
+[license-href]: https://github.com/antfu/node-modules-tools/blob/main/LICENSE
+[jsdocs-src]: https://img.shields.io/badge/jsdocs-reference-080f12?style=flat&colorA=080f12&colorB=1fa669
+[jsdocs-href]: https://www.jsdocs.io/package/node-modules-tools

package/dist/chunks/pnpm.mjs

@@ -0,0 +1,81 @@
+import { x } from 'tinyexec';
+
+async function getDependenciesTree(options) {
+  const args = ["ls", "--json", "--no-optional", "--depth", String(options.depth)];
+  if (options.monorepo)
+    args.push("--recursive");
+  const raw = await x("pnpm", args, { throwOnError: true, nodeOptions: { cwd: options.cwd } });
+  const tree = JSON.parse(raw.stdout);
+  return tree;
+}
+async function listPackageDependencies(options) {
+  const tree = await getDependenciesTree(options);
+  const specs = /* @__PURE__ */ new Map();
+  const map = /* @__PURE__ */ new WeakMap();
+  function normalize(raw) {
+    let node = map.get(raw);
+    if (node)
+      return node;
+    node = {
+      spec: `${raw.from}@${raw.version}`,
+      name: raw.from,
+      version: raw.version,
+      path: raw.path,
+      dependencies: /* @__PURE__ */ new Set(),
+      dependents: /* @__PURE__ */ new Set(),
+      flatDependents: /* @__PURE__ */ new Set(),
+      flatDependencies: /* @__PURE__ */ new Set(),
+      nestedLevels: /* @__PURE__ */ new Set(),
+      dev: false,
+      prod: false,
+      optional: false
+    };
+    map.set(raw, node);
+    return node;
+  }
+  function traverse(_node, level, mode, directImporter, nestedImporter) {
+    if (_node.from.startsWith("@types"))
+      return;
+    const node = normalize(_node);
+    if (directImporter)
+      node.dependents.add(directImporter);
+    for (const im of nestedImporter)
+      node.flatDependents.add(im);
+    node.nestedLevels.add(level);
+    if (mode === "dev")
+      node.dev = true;
+    if (mode === "prod")
+      node.prod = true;
+    if (mode === "optional")
+      node.optional = true;
+    if (options.traverseFilter?.(node) === false)
+      return;
+    if (specs.has(node.spec))
+      return;
+    specs.set(node.spec, node);
+    for (const dep of Object.values(_node.dependencies || {})) {
+      traverse(dep, level + 1, mode, node.spec, [...nestedImporter, node.spec]);
+    }
+  }
+  for (const pkg of tree) {
+    for (const dep of Object.values(pkg.dependencies || {})) {
+      traverse(dep, 1, "prod", undefined, []);
+    }
+    for (const dep of Object.values(pkg.devDependencies || {})) {
+      traverse(dep, 1, "dev", undefined, []);
+    }
+  }
+  const packages = [...specs.values()].sort((a, b) => a.spec.localeCompare(b.spec));
+  for (const pkg of packages) {
+    for (const dep of pkg.flatDependents) {
+      const node = specs.get(dep);
+      if (node)
+        node.flatDependencies.add(pkg.spec);
+    }
+  }
+  return {
+    packages
+  };
+}
+
+export { listPackageDependencies };

package/dist/index.d.mts

@@ -0,0 +1,69 @@
+type PackageModuleTypeSimple = 'cjs' | 'esm';
+type PackageModuleType = 'cjs' | 'esm' | 'dual' | 'faux';
+interface ListPackageDependenciesOptions {
+    /**
+     * Current working directory
+     */
+    cwd: string;
+    /**
+     * Depeth of the dependency tree
+     */
+    depth: number;
+    /**
+     * Should it list dependencies of all packages in the monorepo
+     */
+    monorepo: boolean;
+    /**
+     * Filter if a package should be included and continue traversing
+     */
+    traverseFilter?: (node: PackageNode) => boolean;
+}
+interface ListPackageDependenciesResult {
+    packages: PackageNode[];
+}
+interface PackageNode {
+    /** Package Name */
+    name: string;
+    /** Version */
+    version: string;
+    /** Combined name and version using `@` */
+    spec: string;
+    /** Absolute file path of the package */
+    path: string;
+    /** Direct dependencies of this package */
+    dependencies: Set<string>;
+    /** Direct dependents of this package */
+    dependents: Set<string>;
+    /** All nested dependencies of this package */
+    flatDependencies: Set<string>;
+    /** All nested  dependents of this package */
+    flatDependents: Set<string>;
+    /** Nested levels of this package */
+    nestedLevels: Set<number>;
+    /** Is this package part of devDependencies */
+    dev: boolean;
+    /** Is this package part of dependencies */
+    prod: boolean;
+    /** Is this package part of optionalDependencies */
+    optional: boolean;
+}
+interface ResolvedPackageNode extends PackageNode {
+    module: PackageModuleType;
+}
+
+/**
+ * Analyze a package node, and return a resolved package node.
+ * This function mutates the input package node.
+ *
+ * - Set `module` to the resolved module type (cjs, esm, dual, faux).
+ */
+declare function analyzePackage(pkg: PackageNode): Promise<ResolvedPackageNode>;
+
+/**
+ * List dependencies of packages in the current project.
+ *
+ * This function will automatically detect the package manager in the current project, and list the dependencies of the packages.
+ */
+declare function listPackageDependencies(options: ListPackageDependenciesOptions): Promise<ListPackageDependenciesResult>;
+
+export { type ListPackageDependenciesOptions, type ListPackageDependenciesResult, type PackageModuleType, type PackageModuleTypeSimple, type PackageNode, type ResolvedPackageNode, analyzePackage, listPackageDependencies };

package/dist/index.d.ts

@@ -0,0 +1,69 @@
+type PackageModuleTypeSimple = 'cjs' | 'esm';
+type PackageModuleType = 'cjs' | 'esm' | 'dual' | 'faux';
+interface ListPackageDependenciesOptions {
+    /**
+     * Current working directory
+     */
+    cwd: string;
+    /**
+     * Depeth of the dependency tree
+     */
+    depth: number;
+    /**
+     * Should it list dependencies of all packages in the monorepo
+     */
+    monorepo: boolean;
+    /**
+     * Filter if a package should be included and continue traversing
+     */
+    traverseFilter?: (node: PackageNode) => boolean;
+}
+interface ListPackageDependenciesResult {
+    packages: PackageNode[];
+}
+interface PackageNode {
+    /** Package Name */
+    name: string;
+    /** Version */
+    version: string;
+    /** Combined name and version using `@` */
+    spec: string;
+    /** Absolute file path of the package */
+    path: string;
+    /** Direct dependencies of this package */
+    dependencies: Set<string>;
+    /** Direct dependents of this package */
+    dependents: Set<string>;
+    /** All nested dependencies of this package */
+    flatDependencies: Set<string>;
+    /** All nested  dependents of this package */
+    flatDependents: Set<string>;
+    /** Nested levels of this package */
+    nestedLevels: Set<number>;
+    /** Is this package part of devDependencies */
+    dev: boolean;
+    /** Is this package part of dependencies */
+    prod: boolean;
+    /** Is this package part of optionalDependencies */
+    optional: boolean;
+}
+interface ResolvedPackageNode extends PackageNode {
+    module: PackageModuleType;
+}
+
+/**
+ * Analyze a package node, and return a resolved package node.
+ * This function mutates the input package node.
+ *
+ * - Set `module` to the resolved module type (cjs, esm, dual, faux).
+ */
+declare function analyzePackage(pkg: PackageNode): Promise<ResolvedPackageNode>;
+
+/**
+ * List dependencies of packages in the current project.
+ *
+ * This function will automatically detect the package manager in the current project, and list the dependencies of the packages.
+ */
+declare function listPackageDependencies(options: ListPackageDependenciesOptions): Promise<ListPackageDependenciesResult>;
+
+export { type ListPackageDependenciesOptions, type ListPackageDependenciesResult, type PackageModuleType, type PackageModuleTypeSimple, type PackageNode, type ResolvedPackageNode, analyzePackage, listPackageDependencies };

package/dist/index.mjs

@@ -0,0 +1,125 @@
+import fs from 'node:fs/promises';
+import { join } from 'node:path';
+import { detect } from 'package-manager-detector';
+
+function analyzePackageJson(pkgJson) {
+  const { exports, main, type } = pkgJson;
+  let cjs;
+  let esm;
+  let fauxEsm;
+  if (pkgJson.module) {
+    fauxEsm = true;
+  }
+  if (exports && typeof exports === "object") {
+    for (const exportId in exports) {
+      if (Object.hasOwn(exports, exportId) && typeof exportId === "string") {
+        const value = (
+          /** @type {unknown} */
+          exports[exportId]
+        );
+        analyzeThing(value, `${pkgJson.name}#exports`);
+      }
+    }
+  }
+  if (esm && type === "commonjs") {
+    cjs = true;
+  }
+  if (cjs && type === "module") {
+    esm = true;
+  }
+  if (cjs === undefined && esm === undefined) {
+    if (type === "module" || main && /\.mjs$/.test(main)) {
+      esm = true;
+    } else {
+      cjs = true;
+    }
+  }
+  const style = esm && cjs ? "dual" : esm ? "esm" : fauxEsm ? "faux" : "cjs";
+  return style;
+  function analyzeThing(value, path) {
+    if (value && typeof value === "object") {
+      if (Array.isArray(value)) {
+        const values = (
+          /** @type {Array<unknown>} */
+          value
+        );
+        let index = -1;
+        while (++index < values.length) {
+          analyzeThing(values[index], `${path}[${index}]`);
+        }
+      } else {
+        const record = (
+          /** @type {Record<string, unknown>} */
+          value
+        );
+        let dots = false;
+        for (const [key, subvalue] of Object.entries(record)) {
+          if (key.charAt(0) !== ".")
+            break;
+          analyzeThing(subvalue, `${path}["${key}"]`);
+          dots = true;
+        }
+        if (dots)
+          return;
+        let explicit = false;
+        const conditionImport = Boolean("import" in record && record.import);
+        const conditionRequire = Boolean("require" in record && record.require);
+        const conditionDefault = Boolean("default" in record && record.default);
+        if (conditionImport || conditionRequire) {
+          explicit = true;
+        }
+        if (conditionImport || conditionRequire && conditionDefault) {
+          esm = true;
+        }
+        if (conditionRequire || conditionImport && conditionDefault) {
+          cjs = true;
+        }
+        const defaults = record.node || record.default;
+        if (typeof defaults === "string" && !explicit) {
+          if (/\.mjs$/.test(defaults))
+            esm = true;
+          if (/\.cjs$/.test(defaults))
+            cjs = true;
+        }
+      }
+    } else if (typeof value === "string") {
+      if (/\.mjs$/.test(value))
+        esm = true;
+      if (/\.cjs$/.test(value))
+        cjs = true;
+    } else if (value === null) ; else {
+      console.error("unknown:", [value], path);
+    }
+  }
+}
+
+function stripBomTag(content) {
+  if (content.charCodeAt(0) === 65279) {
+    return content.slice(1);
+  }
+  return content;
+}
+
+async function analyzePackage(pkg) {
+  const _pkg = pkg;
+  if (_pkg.module)
+    return _pkg;
+  const content = await fs.readFile(join(pkg.path, "package.json"), "utf-8");
+  const json = JSON.parse(stripBomTag(content));
+  _pkg.module = analyzePackageJson(json);
+  return _pkg;
+}
+
+async function listPackageDependencies(options) {
+  const manager = await detect({
+    cwd: options.cwd
+  });
+  if (!manager)
+    throw new Error("Cannot detect package manager in the current patch");
+  if (manager.name === "pnpm")
+    return await import('./chunks/pnpm.mjs').then((r) => r.listPackageDependencies(options));
+  else
+    throw new Error(`Package manager ${manager.name} is not yet supported`);
+}
+
+export { analyzePackage, listPackageDependencies };

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "node-modules-tools",
+  "type": "module",
+  "version": "0.0.0",
+  "description": "Tools for inspecting node_modules",
+  "author": "Anthony Fu <anthonyfu117@hotmail.com>",
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/antfu",
+  "homepage": "https://github.com/antfu/node-modules-inspector#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/antfu/node-modules-inspector.git",
+    "directory": "packages/node-modules-tools"
+  },
+  "bugs": "https://github.com/antfu/node-modules-inspector/issues",
+  "keywords": [],
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.mjs"
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./dist/*",
+        "./dist/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "package-manager-detector": "^0.2.8",
+    "tinyexec": "^0.3.2"
+  },
+  "devDependencies": {
+    "@pnpm/list": "^1000.0.5",
+    "@pnpm/types": "^1000.1.0",
+    "pkg-types": "^1.3.1",
+    "unbuild": "^3.3.1"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "dev": "unbuild --stub",
+    "start": "tsx src/index.ts",
+    "test": "vitest"
+  }
+}