node-module-license-output 0.3.0 → 1.0.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 myooken
-
-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.
+MIT License
+
+Copyright (c) 2025 myooken
+
+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

@@ -1,133 +1,150 @@
-# Third-Party License Output for node_modules
-
-[![npm version](https://img.shields.io/npm/v/@myooken/license-output.svg)](https://www.npmjs.com/package/@myooken/license-output)
-[![npm downloads](https://img.shields.io/npm/dm/@myooken/license-output.svg)](https://www.npmjs.com/package/@myooken/license-output)
-[![node](https://img.shields.io/node/v/@myooken/license-output.svg)](https://www.npmjs.com/package/@myooken/license-output)
-
-https://www.npmjs.com/package/@myooken/license-output
-
-### What is this?
-
-A tool to scan `node_modules` and **output third-party licenses in Markdown**.  
-It generates two files: `THIRD-PARTY-LICENSE.md` (main content) and `THIRD-PARTY-LICENSE-REVIEW.md` (review checklist).
-
-### Highlights
-
-- **ESM / Node.js 18+**, zero dependencies
-- **Outputs full license texts** from LICENSE/NOTICE/COPYRIGHT/THIRD-PARTY-NOTICES/THIRD-PARTY-LICENSES/ThirdPartyNoticeText/ThirdPartyText/COPYING files
-- **Review file** flags missing Source / license / license files
-- `--fail-on-missing` supports CI enforcement
-
-CLI command: `third-party-license`
-
-### Usage
-
-#### Run without installing (recommended)
-
-```bash
-npx --package=@myooken/license-output -- third-party-license
-```
-
-#### Run via npm exec
-
-```bash
-npm exec --package=@myooken/license-output -- third-party-license
-```
-
-#### Install globally
-
-```bash
-npm i -g @myooken/license-output
-third-party-license
-```
-
-### Options
-
-| Option                 | Description                                                                 | Default                         |
-| ---------------------- | --------------------------------------------------------------------------- | ------------------------------- |
-| `--node-modules <dir>` | Path to `node_modules`                                                      | `node_modules`                  |
-| `--review [file]`      | Write review file only; optional filename                                   | `THIRD-PARTY-LICENSE-REVIEW.md` |
-| `--license [file]`     | Write main file only; optional filename                                     | `THIRD-PARTY-LICENSE.md`        |
-| `--recreate`           | Regenerate files from current `node_modules` only (drops removed packages)  | `true` (default)                |
-| `--update`             | Merge with existing outputs, keep removed packages, and mark their presence | `false`                        |
-| `--fail-on-missing`    | Exit with code 1 if LICENSE/NOTICE/COPYRIGHT/THIRD-PARTY-NOTICES/THIRD-PARTY-LICENSES/ThirdPartyNoticeText/ThirdPartyText/COPYING are missing  | `false`                         |
-| `-h`, `--help`         | Show help                                                                   | -                               |
-
-> If neither `--review` nor `--license` is specified, **both files are generated**.
-> Packages in both files are sorted by name@version; `--update` keeps entries for packages no longer in `node_modules` and annotates their usage status.
-
-### Examples
-
-```bash
-# Default (both files)
-third-party-license
-
-# Update existing files without dropping removed packages
-third-party-license --update
-
-# Custom node_modules path
-third-party-license --node-modules ./path/to/node_modules
-
-# Review-only output (optional filename)
-third-party-license --review
-third-party-license --review ./out/THIRD-PARTY-LICENSE-REVIEW.md
-
-# Main-only output (optional filename)
-third-party-license --license
-third-party-license --license ./out/THIRD-PARTY-LICENSE.md
-
-# Exit with code 1 when something is missing (with --fail-on-missing)
-third-party-license --fail-on-missing
-```
-
-### Programmatic API
-
-```js
-import { collectThirdPartyLicenses } from "@myooken/license-output";
-
-const result = await collectThirdPartyLicenses({
-  nodeModules: "./node_modules",
-  outFile: "./THIRD-PARTY-LICENSE.md",
-  reviewFile: "./THIRD-PARTY-LICENSE-REVIEW.md",
-  failOnMissing: false,
-  // mode: "update", // keep packages missing from node_modules when updating files
-});
-
-console.log(result.mainContent);
-console.log(result.reviewContent);
-```
-
-Outputs are sorted by package key. Use `mode: "update"` to merge with existing files and keep packages that are no longer in `node_modules`, with their usage shown in both outputs.
-
-### Output overview
-
-- **THIRD-PARTY-LICENSE.md**
-  - List of packages
-  - Source / License info
-  - Full LICENSE/NOTICE/COPYRIGHT/THIRD-PARTY-NOTICES/THIRD-PARTY-LICENSES/ThirdPartyNoticeText/ThirdPartyText/COPYING texts
-  - Usage line shows whether the package is present in the current `node_modules`
-- **THIRD-PARTY-LICENSE-REVIEW.md**
-  - Review-oriented checklist
-  - Usage-aware status (present / not found) for each package
-  - **Missing summary** section
-
-### How it differs from typical npm license tools (general view)
-
-> Examples: `license-checker`, `license-report`, `license-finder`
-
-- **Focused on bundling full license texts into a single Markdown file**
-  - Many existing tools emphasize JSON/CSV reports; this tool emphasizes **ready-to-share license documents**.
-- **Separate review file** to track missing metadata
-  - Easier to integrate into audit workflows.
-- **ESM / Node.js 18+ with no dependencies**
-  - Simple runtime requirements.
-
-### Notes
-
-- Scans all packages under `node_modules` (including nested dependencies); license files are searched only in each package root directory.
-- Recognizes LICENSE, NOTICE, COPYRIGHT, THIRD-PARTY-NOTICES, THIRD-PARTY-LICENSES, ThirdPartyNoticeText/ThirdPartyText, and COPYING files (e.g., TypeScript's `ThirdPartyNoticeText.txt`).
-- Exit code 0: success.
-- Exit code 1: missing license files when `--fail-on-missing` is set, or `node_modules` not found.
-- Throws an error if `node_modules` does not exist.
-- Missing `license` or `repository` fields are flagged in the review file.
-- Paths printed in outputs/logs are shown relative to the current working directory.
+# Third-Party License Output for node_modules
+
+Package name: node-module-license-output
+
+https://www.npmjs.com/package/node-module-license-output
+
+### What is this?
+
+A tool to scan `node_modules` and **output third-party licenses in Markdown**.  
+It generates two files: `THIRD-PARTY-LICENSE.md` (main content) and `THIRD-PARTY-LICENSE-REVIEW.md` (review checklist).
+
+### Highlights
+
+- **ESM / Node.js 18+**, zero dependencies
+- **Outputs full license texts** from LICENSE/NOTICE/COPYRIGHT/THIRD-PARTY-NOTICES/THIRD-PARTY-LICENSES/ThirdPartyNoticeText/ThirdPartyText/COPYING files
+- **Review file** flags missing Source / license / license files
+- `--fail-on-missing` supports CI enforcement
+- Requires a `package.json` next to the target `node_modules` when using `--dependencies-only`
+- Intended for npm/pnpm usage (node_modules layout)
+
+CLI command: `third-party-license`
+
+### Usage
+
+#### Run without installing (recommended)
+
+```bash
+npx --package=node-module-license-output -- third-party-license
+```
+
+#### Run via npm exec
+
+```bash
+npm exec --package=node-module-license-output -- third-party-license
+```
+
+#### Install globally
+
+```bash
+npm i -g node-module-license-output
+third-party-license
+```
+
+### Options
+
+| Option                 | Description                                                                                                                                   | Default                         |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| `--node-modules <dir>` | Path to `node_modules`                                                                                                                        | `node_modules`                  |
+| `--review [file]`      | Write review file only; optional filename                                                                                                     | `THIRD-PARTY-LICENSE-REVIEW.md` |
+| `--license [file]`     | Write main file only; optional filename                                                                                                       | `THIRD-PARTY-LICENSE.md`        |
+| `--recreate`           | Regenerate files from current `node_modules` only (drops removed packages)                                                                    | `true` (default)                |
+| `--update`             | Merge with existing outputs, keep removed packages, and mark their presence                                                                   | `false`                         |
+| `--fail-on-missing`    | Exit with code 1 if LICENSE/NOTICE/COPYRIGHT/THIRD-PARTY-NOTICES/THIRD-PARTY-LICENSES/ThirdPartyNoticeText/ThirdPartyText/COPYING are missing | `false`                         |
+| `--dependencies-only`  | Limit output to dependency tree rooted at `dependencies` (and `optionalDependencies`) in the project `package.json`                          | `true` (default)                |
+| `--dependencies-all`   | Scan all packages under `node_modules`                                                                                                       | `false`                         |
+| `-h`, `--help`         | Show help                                                                                                                                     | -                               |
+
+> If neither `--review` nor `--license` is specified, **both files are generated**.
+> Packages in both files are sorted by name@version; `--update` keeps entries for packages no longer in `node_modules` and annotates their usage status.
+> `--dependencies-only` reads the `package.json` next to the target `node_modules` and limits output to the dependency tree rooted at `dependencies` and `optionalDependencies` (not `devDependencies` or `peerDependencies`); it throws if that `package.json` is not found.
+> Operationally, the default (`--dependencies-only`) is intended for day-to-day use, while `--dependencies-all` is intended for SBOM-like, exhaustive reporting.
+> When duplicates are disambiguated by path, `--update` may treat path-changed entries as new.
+
+### Examples
+
+```bash
+# Default (both files)
+third-party-license
+
+# Update existing files without dropping removed packages
+third-party-license --update
+
+# Custom node_modules path
+third-party-license --node-modules ./path/to/node_modules
+
+# Review-only output (optional filename)
+third-party-license --review
+third-party-license --review ./out/THIRD-PARTY-LICENSE-REVIEW.md
+
+# Main-only output (optional filename)
+third-party-license --license
+third-party-license --license ./out/THIRD-PARTY-LICENSE.md
+
+# Exit with code 1 when something is missing (with --fail-on-missing)
+third-party-license --fail-on-missing
+
+# Day-to-day (dependencies only)
+third-party-license --dependencies-only
+
+# Audit / SBOM-like (scan all packages under node_modules)
+third-party-license --dependencies-all
+third-party-license --dependencies-all --license ./out/THIRD-PARTY-LICENSE.md --review ./out/THIRD-PARTY-LICENSE-REVIEW.md
+```
+
+### Programmatic API
+
+```js
+import { collectThirdPartyLicenses } from "node-module-license-output";
+
+const result = await collectThirdPartyLicenses({
+  nodeModules: "./node_modules",
+  outFile: "./THIRD-PARTY-LICENSE.md",
+  reviewFile: "./THIRD-PARTY-LICENSE-REVIEW.md",
+  failOnMissing: false,
+  dependenciesOnly: true,
+  // mode: "update", // keep packages missing from node_modules when updating files
+});
+
+console.log(result.mainContent);
+console.log(result.reviewContent);
+```
+
+Outputs are sorted by package key. Use `mode: "update"` to merge with existing files and keep packages that are no longer in `node_modules`, with their usage shown in both outputs.
+
+### Output overview
+
+- **THIRD-PARTY-LICENSE.md**
+  - List of packages (default: only those reachable from `dependencies`/`optionalDependencies`)
+  - Source / License info
+  - Full LICENSE/NOTICE/COPYRIGHT/THIRD-PARTY-NOTICES/THIRD-PARTY-LICENSES/ThirdPartyNoticeText/ThirdPartyText/COPYING texts
+  - Usage line shows whether the package is present in the current `node_modules` (or kept from previous output with `--update`)
+- **THIRD-PARTY-LICENSE-REVIEW.md**
+  - Review-oriented checklist
+  - Usage-aware status (present / not found) for each package
+  - **Missing summary** section
+
+### How it differs from typical npm license tools (general view)
+
+> Examples: `license-checker`, `license-report`, `license-finder`
+
+- **Focused on bundling full license texts into a single Markdown file**
+  - Many existing tools emphasize JSON/CSV reports; this tool emphasizes **ready-to-share license documents**.
+- **Separate review file** to track missing metadata
+  - Easier to integrate into audit workflows.
+- **ESM / Node.js 18+ with no dependencies**
+  - Simple runtime requirements.
+
+### Notes
+
+- Default output is restricted to the dependency tree from `dependencies` and `optionalDependencies`.
+- Use `--dependencies-all` to scan all packages under `node_modules` (including nested dependencies).
+- License files are searched only in each package root directory.
+- If multiple copies of the same name@version exist, dependency-only output disambiguates them by path.
+- pnpm installs may be resolved via `.pnpm` directories under `node_modules`; this tool follows resolved package paths rather than only direct `node_modules/<pkg>` locations.
+- Recognizes LICENSE, NOTICE, COPYRIGHT, THIRD-PARTY-NOTICES, THIRD-PARTY-LICENSES, ThirdPartyNoticeText/ThirdPartyText, and COPYING files (e.g., TypeScript's `ThirdPartyNoticeText.txt`).
+- Exit code 0: success.
+- Exit code 1: missing license files when `--fail-on-missing` is set, or `node_modules` not found.
+- Throws an error if `node_modules` does not exist.
+- Missing `license` or `repository` fields are flagged in the review file.
+- Paths printed in outputs/logs are shown relative to the current working directory.

package/package.json

@@ -1,38 +1,38 @@
-{
-  "name": "node-module-license-output",
-  "version": "0.3.0",
-  "description": "Generate third-party-license markdown by scanning licenses in node_modules.",
-  "license": "MIT",
-  "type": "module",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/myooken/collect-node-modules-licenses.git"
-  },
-  "homepage": "https://github.com/myooken/collect-node-modules-licenses#readme",
-  "bugs": {
-    "url": "https://github.com/myooken/collect-node-modules-licenses/issues"
-  },
-  "keywords": [
-    "license",
-    "third-party",
-    "notices",
-    "node_modules",
-    "oss",
-    "compliance",
-    "cli"
-  ],
-  "exports": {
-    ".": "./src/core.js"
-  },
-  "bin": {
-    "third-party-license": "./src/cli.js"
-  },
-  "files": [
-    "src",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=18"
-  }
-}
+{
+  "name": "node-module-license-output",
+  "version": "1.0.0",
+  "description": "Generate third-party-license markdown by scanning licenses in node_modules.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/myooken/collect-node-modules-licenses.git"
+  },
+  "homepage": "https://github.com/myooken/collect-node-modules-licenses#readme",
+  "bugs": {
+    "url": "https://github.com/myooken/collect-node-modules-licenses/issues"
+  },
+  "keywords": [
+    "license",
+    "third-party",
+    "notices",
+    "node_modules",
+    "oss",
+    "compliance",
+    "cli"
+  ],
+  "exports": {
+    ".": "./src/core.js"
+  },
+  "bin": {
+    "third-party-license": "./src/cli.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/cli.js

@@ -39,6 +39,10 @@ function parseArgs(argv) {
       args.mode = "update";
     } else if (a === "--fail-on-missing") {
       args.failOnMissing = true;
+    } else if (a === "--dependencies-only") {
+      args.dependenciesOnly = true;
+    } else if (a === "--dependencies-all") {
+      args.dependenciesOnly = false;
     } else if (a === "-h" || a === "--help") {
       showHelp();
       process.exit(0);
@@ -71,7 +75,7 @@ function applyOutputMode(mode, args) {
 
 function showHelp() {
   console.log(`Usage:
-  third-party-license [--node-modules <dir>] [--review [file]] [--license [file]] [--recreate|--update] [--fail-on-missing]
+  third-party-license [--node-modules <dir>] [--review [file]] [--license [file]] [--recreate|--update] [--fail-on-missing] [--dependencies-only|--dependencies-all]
 `);
 }
 

package/src/constants.js

@@ -5,6 +5,7 @@ export const DEFAULT_OPTIONS = {
   reviewFile: "THIRD-PARTY-LICENSE-REVIEW.md",
   failOnMissing: false,
   mode: "recreate", // "recreate" | "update"
+  dependenciesOnly: true,
 };
 
 // ライセンスらしいファイル名を検出する正規表現

package/src/core.js

@@ -73,6 +73,9 @@ function normalizeOptions(options) {
     failOnMissing: Boolean(
       options.failOnMissing ?? DEFAULT_OPTIONS.failOnMissing
     ),
+    dependenciesOnly: Boolean(
+      options.dependenciesOnly ?? DEFAULT_OPTIONS.dependenciesOnly
+    ),
     writeMain: options.writeMain ?? true,
     writeReview: options.writeReview ?? true,
     warn: options.onWarn ?? defaultWarn,

package/src/dependency-tree.js

@@ -0,0 +1,123 @@
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { readPackageJson, uniqSorted } from "./fs-utils.js";
+// Cache realpath resolutions to keep dependency traversal fast.
+const realpathCache = new Map();
+// dependencies/optionalDependencies から到達可能なパッケージのディレクトリを収集
+export async function collectDependencyDirs(opts) {
+  const nodeModulesReal = await toRealPath(opts.nodeModules);
+  const projectDir = path.dirname(path.resolve(opts.nodeModules));
+  const projectRootBoundary = projectDir;
+  const projectPackageJson = path.join(projectDir, "package.json");
+  const rootPkg = await readPackageJson(projectPackageJson);
+  if (!rootPkg) {
+    throw new Error(`package.json not found: ${projectPackageJson}`);
+  }
+  const rootDeps = collectDependencyNames(rootPkg);
+  if (rootDeps.length === 0) {
+    opts.warn("No dependencies found in package.json; output will be empty.");
+    return new Set();
+  }
+  const allowed = new Set();
+  const visitedDirs = new Set();
+  const stack = [];
+  for (const depName of rootDeps) {
+    const depDir = await resolvePackageDir(
+      projectDir,
+      depName,
+      nodeModulesReal,
+      projectRootBoundary
+    );
+    if (!depDir) {
+      opts.warn(`Dependency not found in node_modules: ${depName}`);
+      continue;
+    }
+    stack.push(depDir);
+  }
+  while (stack.length > 0) {
+    const pkgDir = stack.pop();
+    if (!pkgDir || visitedDirs.has(pkgDir)) continue;
+    visitedDirs.add(pkgDir);
+    const pkg = await readPackageJson(path.join(pkgDir, "package.json"));
+    if (!pkg) continue;
+    const name =
+      typeof pkg.name === "string" && pkg.name.trim().length > 0
+        ? pkg.name.trim()
+        : "";
+    const version =
+      typeof pkg.version === "string" && pkg.version.trim().length > 0
+        ? pkg.version.trim()
+        : "";
+    if (!name || !version) continue;
+    allowed.add(pkgDir);
+    for (const depName of collectDependencyNames(pkg)) {
+      const depDir = await resolvePackageDir(
+        pkgDir,
+        depName,
+        nodeModulesReal,
+        projectRootBoundary
+      );
+      if (!depDir) {
+        opts.warn(
+          `Dependency not found in node_modules: ${depName} (required by ${name}@${version})`
+        );
+        continue;
+      }
+      stack.push(depDir);
+    }
+  }
+  return allowed;
+}
+// node_modules からの相対パスで同名同バージョンの区別をつける
+export function makePackagePathLabel(pkgDir, nodeModulesRoot) {
+  const rel = path.relative(nodeModulesRoot, pkgDir).replace(/\\/g, "/");
+  return rel || path.basename(pkgDir);
+}
+function collectDependencyNames(pkg) {
+  const deps =
+    pkg?.dependencies && typeof pkg.dependencies === "object"
+      ? Object.keys(pkg.dependencies)
+      : [];
+  const optionalDeps =
+    pkg?.optionalDependencies && typeof pkg.optionalDependencies === "object"
+      ? Object.keys(pkg.optionalDependencies)
+      : [];
+  return uniqSorted([...deps, ...optionalDeps]);
+}
+async function resolvePackageDir(
+  fromDir,
+  depName,
+  nodeModulesRoot,
+  projectRootBoundary
+) {
+  const rootParent = path.dirname(nodeModulesRoot);
+  const boundary = path.resolve(projectRootBoundary);
+  let dir = fromDir;
+  while (true) {
+    const nmDir = path.join(dir, "node_modules");
+    const candidateDir = path.join(nmDir, depName);
+    const candidatePkg = path.join(candidateDir, "package.json");
+    const stat = await fsp.stat(candidatePkg).catch(() => null);
+    if (stat && stat.isFile()) return toRealPath(candidateDir);
+    if (dir === rootParent) break;
+    if (path.resolve(dir) === boundary) break;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+async function toRealPath(targetPath) {
+  const cached = realpathCache.get(targetPath);
+  if (cached) return cached;
+  try {
+    const resolved = await fsp.realpath(targetPath);
+    realpathCache.set(targetPath, resolved);
+    return resolved;
+  } catch {
+    const resolved = path.resolve(targetPath);
+    realpathCache.set(targetPath, resolved);
+    return resolved;
+  }
+}

package/src/fs-utils.js

@@ -1,114 +1,114 @@
-import fsp from "node:fs/promises";
-import path from "node:path";
-import { LICENSE_LIKE_RE } from "./constants.js";
-
-// 文字コードを判定しつつ文字列へデコードする
-export function decodeSmart(buf) {
-  if (buf.length >= 2) {
-    const b0 = buf[0];
-    const b1 = buf[1];
-    if (b0 === 0xff && b1 === 0xfe) {
-      return new TextDecoder("utf-16le").decode(buf.subarray(2));
-    }
-    if (b0 === 0xfe && b1 === 0xff) {
-      const be = buf.subarray(2);
-      const swapped = Buffer.allocUnsafe(be.length);
-      for (let i = 0; i + 1 < be.length; i += 2) {
-        swapped[i] = be[i + 1];
-        swapped[i + 1] = be[i];
-      }
-      return new TextDecoder("utf-16le").decode(swapped);
-    }
-  }
-  if (
-    buf.length >= 3 &&
-    buf[0] === 0xef &&
-    buf[1] === 0xbb &&
-    buf[2] === 0xbf
-  ) {
-    return new TextDecoder("utf-8").decode(buf.subarray(3));
-  }
-
-  try {
-    return new TextDecoder("utf-8", { fatal: true }).decode(buf);
-  } catch {
-    return new TextDecoder("latin1").decode(buf);
-  }
-}
-
-// LICENSE/NOTICE などのライセンス系ファイルを探す
-export async function getLicenseLikeFilesInFolderRoot(pkgDir) {
-  try {
-    const ents = await fsp.readdir(pkgDir, { withFileTypes: true });
-    return ents
-      .filter((e) => e.isFile() && LICENSE_LIKE_RE.test(e.name))
-      .map((e) => path.join(pkgDir, e.name))
-      .sort((a, b) => path.basename(a).localeCompare(path.basename(b)));
-  } catch {
-    return [];
-  }
-}
-
-// package.json を深さ優先で探す（node_modules/.bin は除外）
-export async function* walkForPackageJson(rootDir) {
-  const stack = [rootDir];
-
-  while (stack.length) {
-    const dir = stack.pop();
-    if (!dir) continue;
-
-    let ents;
-    try {
-      ents = await fsp.readdir(dir, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-
-    for (const e of ents) {
-      const full = path.join(dir, e.name);
-      if (e.isDirectory()) {
-        if (e.name === ".bin") continue;
-        stack.push(full);
-        continue;
-      }
-      if (e.isFile() && e.name === "package.json") {
-        if (full.includes(`${path.sep}.bin${path.sep}`)) continue;
-        yield full;
-      }
-    }
-  }
-}
-
-export async function readPackageJson(pjPath) {
-  try {
-    const txt = await fsp.readFile(pjPath, "utf8");
-    return JSON.parse(txt);
-  } catch {
-    return null;
-  }
-}
-
-// BOM や UTF-16 を考慮してテキストを読み込む
-export async function readTextFileSmart(filePath) {
-  const buf = await fsp.readFile(filePath);
-  return decodeSmart(buf);
-}
-
-export function mdSafeText(s) {
-  return String(s).replace(/```/g, "``\u200b`");
-}
-
-export function uniqSorted(arr) {
-  return [...new Set(arr)].sort();
-}
-
-// アンカー用の安全な ID を作る
-export function makeAnchorId(key) {
-  return (
-    "pkg-" +
-    String(key)
-      .toLowerCase()
-      .replace(/[^a-z0-9]+/g, "-")
-      .replace(/^-+|-+$/g, "")
-  );
-}
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { LICENSE_LIKE_RE } from "./constants.js";
+
+// 文字コードを判定しつつ文字列へデコードする
+export function decodeSmart(buf) {
+  if (buf.length >= 2) {
+    const b0 = buf[0];
+    const b1 = buf[1];
+    if (b0 === 0xff && b1 === 0xfe) {
+      return new TextDecoder("utf-16le").decode(buf.subarray(2));
+    }
+    if (b0 === 0xfe && b1 === 0xff) {
+      const be = buf.subarray(2);
+      const swapped = Buffer.allocUnsafe(be.length);
+      for (let i = 0; i + 1 < be.length; i += 2) {
+        swapped[i] = be[i + 1];
+        swapped[i + 1] = be[i];
+      }
+      return new TextDecoder("utf-16le").decode(swapped);
+    }
+  }
+  if (
+    buf.length >= 3 &&
+    buf[0] === 0xef &&
+    buf[1] === 0xbb &&
+    buf[2] === 0xbf
+  ) {
+    return new TextDecoder("utf-8").decode(buf.subarray(3));
+  }
+
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(buf);
+  } catch {
+    return new TextDecoder("latin1").decode(buf);
+  }
+}
+
+// LICENSE/NOTICE などのライセンス系ファイルを探す
+export async function getLicenseLikeFilesInFolderRoot(pkgDir) {
+  try {
+    const ents = await fsp.readdir(pkgDir, { withFileTypes: true });
+    return ents
+      .filter((e) => e.isFile() && LICENSE_LIKE_RE.test(e.name))
+      .map((e) => path.join(pkgDir, e.name))
+      .sort((a, b) => path.basename(a).localeCompare(path.basename(b)));
+  } catch {
+    return [];
+  }
+}
+
+// package.json を深さ優先で探す（node_modules/.bin は除外）
+export async function* walkForPackageJson(rootDir) {
+  const stack = [rootDir];
+
+  while (stack.length) {
+    const dir = stack.pop();
+    if (!dir) continue;
+
+    let ents;
+    try {
+      ents = await fsp.readdir(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const e of ents) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (e.name === ".bin") continue;
+        stack.push(full);
+        continue;
+      }
+      if (e.isFile() && e.name === "package.json") {
+        if (full.includes(`${path.sep}.bin${path.sep}`)) continue;
+        yield full;
+      }
+    }
+  }
+}
+
+export async function readPackageJson(pjPath) {
+  try {
+    const txt = await fsp.readFile(pjPath, "utf8");
+    return JSON.parse(txt);
+  } catch {
+    return null;
+  }
+}
+
+// BOM や UTF-16 を考慮してテキストを読み込む
+export async function readTextFileSmart(filePath) {
+  const buf = await fsp.readFile(filePath);
+  return decodeSmart(buf);
+}
+
+export function mdSafeText(s) {
+  return String(s).replace(/```/g, "``\u200b`");
+}
+
+export function uniqSorted(arr) {
+  return [...new Set(arr)].sort();
+}
+
+// アンカー用の安全な ID を作る
+export function makeAnchorId(key) {
+  return (
+    "pkg-" +
+    String(key)
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+  );
+}

package/src/license-utils.js

@@ -0,0 +1,40 @@
+// license フィールドを人間可読にまとめる（文字列/オブジェクト/配列に対応）
+export function formatLicense(raw) {
+  const parts = [];
+
+  const pushMaybe = (v) => {
+    if (typeof v === "string" && v.trim()) parts.push(v.trim());
+  };
+
+  const handleObj = (licObj) => {
+    if (!licObj || typeof licObj !== "object") return;
+    const type =
+      typeof licObj.type === "string" && licObj.type.trim()
+        ? licObj.type.trim()
+        : "";
+    const url =
+      typeof licObj.url === "string" && licObj.url.trim()
+        ? licObj.url.trim()
+        : "";
+    if (type && url) {
+      parts.push(`${type} (${url})`);
+    } else {
+      pushMaybe(type);
+      pushMaybe(url);
+    }
+  };
+
+  if (typeof raw === "string") {
+    pushMaybe(raw);
+  } else if (Array.isArray(raw)) {
+    for (const lic of raw) {
+      if (typeof lic === "string") pushMaybe(lic);
+      else handleObj(lic);
+    }
+  } else {
+    handleObj(raw);
+  }
+
+  if (parts.length === 0) return null;
+  return [...new Set(parts)].join(" | ");
+}

package/src/package-entry.js

@@ -0,0 +1,68 @@
+import path from "node:path";
+import {
+  getLicenseLikeFilesInFolderRoot,
+  readTextFileSmart,
+} from "./fs-utils.js";
+import { getRepositoryUrl } from "./url.js";
+import { LICENSE_FILES_LABEL } from "./constants.js";
+import { formatLicense } from "./license-utils.js";
+
+// ライセンス情報と警告フラグをまとめてエントリ化する
+export async function buildPackageEntry({
+  pkg,
+  pkgDir,
+  key,
+  baseKey,
+}) {
+  const source = getRepositoryUrl(pkg);
+  const license = formatLicense(pkg.license);
+  const flags = [];
+  const missing = {
+    source: false,
+    licenseField: false,
+    licenseFiles: false,
+  };
+
+  if (!source) {
+    missing.source = true;
+    flags.push("Missing Source");
+  }
+  if (!license) {
+    missing.licenseField = true;
+    flags.push("Missing package.json license");
+  }
+
+  const licFiles = await getLicenseLikeFilesInFolderRoot(pkgDir);
+  const fileNames = licFiles.map((f) => path.basename(f));
+
+  if (licFiles.length === 0) {
+    missing.licenseFiles = true;
+    const missingMsg = `Missing ${LICENSE_FILES_LABEL} files`;
+    flags.push(missingMsg);
+  }
+
+  const licenseTexts =
+    licFiles.length > 0
+      ? await Promise.all(
+          licFiles.map(async (filePath) => ({
+            name: path.basename(filePath),
+            text: await readTextFileSmart(filePath),
+          }))
+        )
+      : [];
+
+  return {
+    entry: {
+      key,
+      baseKey: baseKey ?? key,
+      source,
+      license,
+      fileNames,
+      flags,
+      licenseTexts,
+      dir: pkgDir,
+      missing,
+    },
+    missing,
+  };
+}

package/src/scan.js

@@ -1,89 +1,71 @@
+import fsp from "node:fs/promises";
 import path from "node:path";
 import {
-  getLicenseLikeFilesInFolderRoot,
   makeAnchorId,
   readPackageJson,
-  readTextFileSmart,
   uniqSorted,
   walkForPackageJson,
 } from "./fs-utils.js";
-import { getRepositoryUrl } from "./url.js";
+import {
+  collectDependencyDirs,
+  makePackagePathLabel,
+} from "./dependency-tree.js";
+import { buildPackageEntry } from "./package-entry.js";
 import { LICENSE_FILES_LABEL } from "./constants.js";
-
+// Cache realpath resolutions to avoid repeated fs calls during large scans.
+const realpathCache = new Map();
 // node_modules を走査してパッケージ情報を集約する
 export async function gatherPackages(opts) {
-  const missingFiles = [];
-  const missingSource = [];
-  const missingLicenseField = [];
+  const nodeModulesReal = await toRealPath(opts.nodeModules);
+  const allowedDirs = opts.dependenciesOnly
+    ? await collectDependencyDirs(opts)
+    : null;
   const packages = [];
   const seen = new Set();
-
   for await (const pj of walkForPackageJson(opts.nodeModules)) {
-    const pkgDir = path.dirname(pj);
+    const pkgDir = await toRealPath(path.dirname(pj));
+    if (allowedDirs && !allowedDirs.has(pkgDir)) continue;
     const pkg = await readPackageJson(pj);
     if (!pkg) continue;
+    const ident = getPackageIdentity(pkg);
+    if (!ident) continue;
+    const baseKey = `${ident.name}@${ident.version}`;
+    const seenKey = pkgDir;
+    if (seen.has(seenKey)) continue;
+    seen.add(seenKey);
+    const key = baseKey;
+    const { entry } = await buildPackageEntry({
+      pkg,
+      pkgDir,
+      key,
+      baseKey,
+    });
+    packages.push(entry);
+  }
 
-    const name =
-      typeof pkg.name === "string" && pkg.name.trim().length > 0
-        ? pkg.name.trim()
-        : "";
-    const version =
-      typeof pkg.version === "string" && pkg.version.trim().length > 0
-        ? pkg.version.trim()
-        : "";
-    if (!name || !version) continue;
-
-    const key = `${name}@${version}`;
-    if (seen.has(key)) continue;
-    seen.add(key);
-
-    const anchor = makeAnchorId(key);
-    const source = getRepositoryUrl(pkg);
-    const license = formatLicense(pkg.license); // 文字列/オブジェクト/配列すべてを受け付ける
-
-    const flags = [];
-    if (!source) {
-      missingSource.push(key);
-      flags.push("Missing Source");
-      opts.warn(`Unknown source: ${key}`);
+  // 同名同バージョンが複数ある場合はパスで区別する
+  disambiguateDuplicateKeys(packages, nodeModulesReal);
+  for (const pkg of packages) {
+    pkg.anchor = makeAnchorId(pkg.key);
+  }
+  ensureUniqueAnchors(packages, nodeModulesReal);
+  const missingFiles = [];
+  const missingSource = [];
+  const missingLicenseField = [];
+  for (const pkg of packages) {
+    if (pkg.missing?.licenseFiles) {
+      missingFiles.push(pkg.key);
+      opts.warn(`Missing ${LICENSE_FILES_LABEL} in ${pkg.dir} (${pkg.key})`);
     }
-    if (!license) {
-      missingLicenseField.push(key);
-      flags.push("Missing package.json license");
-      opts.warn(`Missing license in package.json: ${key}`);
+    if (pkg.missing?.source) {
+      missingSource.push(pkg.key);
+      opts.warn(`Unknown source: ${pkg.key}`);
     }
-
-    const licFiles = await getLicenseLikeFilesInFolderRoot(pkgDir);
-    const fileNames = licFiles.map((f) => path.basename(f));
-
-    if (licFiles.length === 0) {
-      missingFiles.push(key);
-      const missingMsg = `Missing ${LICENSE_FILES_LABEL} files`;
-      flags.push(missingMsg);
-      opts.warn(`Missing ${LICENSE_FILES_LABEL} in ${pkgDir} (${key})`);
+    if (pkg.missing?.licenseField) {
+      missingLicenseField.push(pkg.key);
+      opts.warn(`Missing license in package.json: ${pkg.key}`);
     }
-
-    const licenseTexts =
-      licFiles.length > 0
-        ? await Promise.all(
-            licFiles.map(async (filePath) => ({
-              name: path.basename(filePath),
-              text: await readTextFileSmart(filePath),
-            }))
-          )
-        : [];
-
-    packages.push({
-      key,
-      anchor,
-      source,
-      license,
-      fileNames,
-      flags,
-      licenseTexts,
-    });
   }
-
   return {
     packages,
     missingFiles: uniqSorted(missingFiles),
@@ -92,44 +74,72 @@ export async function gatherPackages(opts) {
     seenCount: seen.size,
   };
 }
+function getPackageIdentity(pkg) {
+  const name =
+    typeof pkg.name === "string" && pkg.name.trim().length > 0
+      ? pkg.name.trim()
+      : "";
+  const version =
+    typeof pkg.version === "string" && pkg.version.trim().length > 0
+      ? pkg.version.trim()
+      : "";
+  if (!name || !version) return null;
+  return { name, version };
+}
 
-// license フィールドを人間可読にまとめる（文字列/オブジェクト/配列に対応）
-function formatLicense(raw) {
-  const parts = [];
-
-  const pushMaybe = (v) => {
-    if (typeof v === "string" && v.trim()) parts.push(v.trim());
-  };
+function disambiguateDuplicateKeys(packages, nodeModulesRoot) {
+  const groups = new Map();
+  for (const pkg of packages) {
+    const list = groups.get(pkg.baseKey) ?? [];
+    list.push(pkg);
+    groups.set(pkg.baseKey, list);
+  }
 
-  const handleObj = (licObj) => {
-    if (!licObj || typeof licObj !== "object") return;
-    const type =
-      typeof licObj.type === "string" && licObj.type.trim()
-        ? licObj.type.trim()
-        : "";
-    const url =
-      typeof licObj.url === "string" && licObj.url.trim()
-        ? licObj.url.trim()
-        : "";
-    if (type && url) {
-      parts.push(`${type} (${url})`);
-    } else {
-      pushMaybe(type);
-      pushMaybe(url);
+  for (const list of groups.values()) {
+    if (list.length < 2) continue;
+    for (const pkg of list) {
+      const label = makePackagePathLabel(pkg.dir, nodeModulesRoot);
+      const key = `${pkg.baseKey} (${label})`;
+      pkg.key = key;
     }
-  };
+  }
+}
+
+function hashStableSuffix(value) {
+  let hash = 5381;
+  for (let i = 0; i < value.length; i += 1) {
+    hash = (hash * 33) ^ value.charCodeAt(i);
+  }
+  return (hash >>> 0).toString(36);
+}
 
-  if (typeof raw === "string") {
-    pushMaybe(raw);
-  } else if (Array.isArray(raw)) {
-    for (const lic of raw) {
-      if (typeof lic === "string") pushMaybe(lic);
-      else handleObj(lic);
+function ensureUniqueAnchors(packages, nodeModulesRoot) {
+  const groups = new Map();
+  for (const pkg of packages) {
+    const list = groups.get(pkg.anchor) ?? [];
+    list.push(pkg);
+    groups.set(pkg.anchor, list);
+  }
+
+  for (const list of groups.values()) {
+    if (list.length < 2) continue;
+    for (const pkg of list) {
+      const label = makePackagePathLabel(pkg.dir, nodeModulesRoot);
+      pkg.anchor = `${pkg.anchor}-${hashStableSuffix(label)}`;
     }
-  } else {
-    handleObj(raw);
   }
+}
 
-  if (parts.length === 0) return null;
-  return [...new Set(parts)].join(" | ");
+async function toRealPath(targetPath) {
+  const cached = realpathCache.get(targetPath);
+  if (cached) return cached;
+  try {
+    const resolved = await fsp.realpath(targetPath);
+    realpathCache.set(targetPath, resolved);
+    return resolved;
+  } catch {
+    const resolved = path.resolve(targetPath);
+    realpathCache.set(targetPath, resolved);
+    return resolved;
+  }
 }

package/src/url.js

@@ -1,8 +1,8 @@
-// package.jsonのrepositoryからURLを取り出す
-export function getRepositoryUrl(pkg) {
-  const repo = pkg?.repository;
-  if (!repo) return null;
-  if (typeof repo === "string") return repo;
-  if (typeof repo === "object" && typeof repo.url === "string") return repo.url;
-  return null;
-}
+// package.jsonのrepositoryからURLを取り出す
+export function getRepositoryUrl(pkg) {
+  const repo = pkg?.repository;
+  if (!repo) return null;
+  if (typeof repo === "string") return repo;
+  if (typeof repo === "object" && typeof repo.url === "string") return repo.url;
+  return null;
+}