depopsy 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dep-optimizer contributors
+
+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,309 @@
+<div align="center">
+
+# Depopsy 🚀
+
+### The npm doctor for dependency chaos.
+
+**Understand *why* your dependencies are bloated — and fix them safely.**
+
+[![npm version](https://img.shields.io/npm/v/depopsy?color=crimson&label=npm&logo=npm)](https://www.npmjs.com/package/depopsy)
+[![npm downloads](https://img.shields.io/npm/dm/depopsy?color=blue&logo=npm)](https://www.npmjs.com/package/depopsy)
+[![Node.js >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen?logo=node.js)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](./LICENSE)
+![Supports npm · yarn · pnpm](https://img.shields.io/badge/supports-npm%20%C2%B7%20yarn%20%C2%B7%20pnpm-8A2BE2)
+
+</div>
+
+---
+
+## The Problem
+
+Modern JavaScript projects silently accumulate **multiple versions of the same package**. After a few months of adding dependencies, you might have `lodash@4.17.19` *and* `lodash@4.17.21` installed simultaneously — pulled in by different tools like `eslint`, `jest`, or `next`.
+
+This leads to:
+
+- 🐢 **Slower installs** — `npm install` / CI pipelines download and extract duplicate packages
+- 📦 **Larger bundles** — your end users download the bloat too
+- 🐛 **Subtle runtime bugs** — packages that check `instanceof` silently break when two versions exist
+
+`npm dedupe` tells you *what* is duplicated. `depopsy` tells you ***why*** — and fixes it safely.
+
+---
+
+## Quick Start
+
+Zero install required. Run it at the root of **any** npm, yarn, or pnpm project:
+
+```bash
+npx depopsy
+```
+
+For a quick 3-line summary:
+
+```bash
+npx depopsy --simple
+```
+
+---
+
+## Example Output
+
+```
+Analyzing large dependency graph...
+Detected Package Manager: npm
+
+📦 Dependency Health Report
+──────────────────────────────────────────────────
+
+🚨 Problem:
+   You have 19 duplicate dependencies
+   → ~1.89 MB wasted on disk
+   → Slower installs, larger bundles, subtle runtime bugs
+
+🔥 Top Root Causes  (you can act on)
+   These are the packages pulling in most duplicate dependencies.
+
+  1. jest  → 19 duplicate packages
+
+   ➔ These top root causes account for ~89% of your duplication.
+
+🎯 Why this matters
+  · Multiple versions of the same package increase bundle size
+  · Slows npm install / pnpm install / CI pipelines
+  · Can cause subtle runtime bugs when packages check instanceof
+
+🧠 What you should do
+
+  ▶ jest
+  Confidence: LOW — manual review required
+  Introduces: ansi-styles, chalk, ansi-regex, semver (+15 more)
+  → Test tooling often bundles its own utility versions.
+  → Upgrade jest to latest — may resolve 19 duplicate chains.
+
+⚡ Quick Fix
+   Run:  npx depopsy fix
+   (applies 0 SAFE fixes automatically — no breaking changes)
+
+📊 Summary
+──────────────────────────────────────────────────
+  ✔ SAFE issues:  0  (auto-fixable)
+  ✖ RISKY issues: 19  (manual review)
+
+──────────────────────────────────────────────────
+💡 Tip: Even well-maintained projects have duplicates.
+   This tool explains *why* — not just what.
+```
+
+---
+
+## CLI Reference
+
+| Command | Description |
+|---|---|
+| `npx depopsy` | Full dependency health report |
+| `npx depopsy --simple` | Top 3 root causes only |
+| `npx depopsy --verbose` | Full breakdown of every group |
+| `npx depopsy --top <n>` | Limit root cause output to top N groups |
+| `npx depopsy --json` | JSON output for CI/CD pipelines |
+| `npx depopsy --ci` | Minimal JSON with correct exit codes |
+| `npx depopsy fix` | Dry-run: preview safe deduplication fixes |
+| `npx depopsy fix --yes` | Apply fixes directly to `package.json` |
+| `npx depopsy trace <pkg>` | Trace which top-level dep introduces `<pkg>` |
+
+### Exit Codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success — no duplicates found |
+| `1` | Duplicates found |
+| `2` | Fatal error (no lockfile, parse failure, etc.) |
+
+---
+
+## How It Works
+
+```
+1. Parses your lockfile  →  package-lock.json, yarn.lock, or pnpm-lock.yaml
+2. Builds a dependency graph  →  maps every package to its introducers
+3. Detects duplicates  →  packages installed at multiple versions
+4. Identifies root causes  →  which top-level dep (eslint, jest, next) is responsible
+5. Suggests safe fixes  →  only semver-compatible consolidations
+```
+
+### Root Cause Attribution
+
+The attribution engine uses a 3-layer priority system to find the most actionable signal:
+
+1. **`roots[]`** — Pre-computed top-level introducers via graph traversal (most accurate)
+2. **`parents[]`** — Immediate dependents (closer signal than full ancestor chain)
+3. **`ancestors[]`** — Full flattened chain (last resort, only when no better signal exists)
+
+Low-level utility packages (`chalk`, `semver`, `minimatch`, `glob`, etc.) are automatically suppressed from root cause output — they are always *indirect* symptoms, never *causes*.
+
+---
+
+## Features
+
+| Feature | Detail |
+|---|---|
+| ✅ Multi-lockfile | npm (`package-lock.json`), yarn (`yarn.lock`), pnpm (`pnpm-lock.yaml`) |
+| ✅ Root cause analysis | Identifies *which* top-level dep pulls in each duplicate |
+| ✅ Safe fixes only | Backs up `package.json` before writing; never touches RISKY diffs |
+| ✅ CI/CD ready | `--json` and `--ci` flags with correct exit codes |
+| ✅ Zero config | Works instantly in any project root — no setup required |
+| ✅ Monorepo aware | Skips internal workspace packages (`link:`, `workspace:`, `file:`) |
+| ✅ Disk waste measurement | Actual on-disk byte measurement of duplicate package directories |
+| ✅ Package manager detection | Auto-detects npm / yarn / pnpm from lockfile presence |
+| ✅ Yarn v1 + v2+ | Handles both classic and modern Yarn lockfile formats |
+| ✅ pnpm v5–v9 | Handles all pnpm lockfile versions including v9 snapshots |
+
+---
+
+## The `fix` Command
+
+`depopsy fix` only touches **SAFE** duplicates — packages where all versions share the same major version (semver-compatible).
+
+```bash
+# Preview what would change (no files modified)
+npx depopsy fix
+
+# Apply changes to package.json
+npx depopsy fix --yes
+```
+
+After running `fix --yes`, you **must** reinstall to apply the overrides to your lockfile:
+
+```bash
+npm install    # or yarn install / pnpm install
+```
+
+### What it writes
+
+| Package manager | What gets written |
+|---|---|
+| npm | `"overrides"` in `package.json` |
+| yarn | `"resolutions"` in `package.json` |
+| pnpm | `"pnpm.overrides"` in `package.json` |
+
+A backup of your original `package.json` is saved to `.depopsy-backup/` before any write.
+
+---
+
+## The `trace` Command
+
+Trace exactly which top-level dependencies are responsible for pulling in a given package:
+
+```bash
+npx depopsy trace semver
+```
+
+```
+Tracing "semver" through dependency graph...
+
+🔍 Trace: semver
+──────────────────────────────────────────────────
+
+  Versions found: 5.7.2, 7.5.4, 7.6.0
+  Safety: RISKY
+
+  semver is introduced by:
+    ▶ jest
+    ▶ eslint
+    ▶ @babel/core
+
+  Per-version breakdown:
+    5.7.2 — required by: node-semver, validate-npm-package-version
+    7.5.4 — required by: jest-runner, jest-resolve
+    7.6.0 — required by: eslint, @babel/core
+
+──────────────────────────────────────────────────
+  ⚠  No auto-fix available — versions span multiple majors.
+```
+
+---
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+- name: Check for duplicate dependencies
+  run: npx depopsy --ci
+  # Exits 1 if duplicates found, 0 if clean
+```
+
+### JSON output for custom scripting
+
+```bash
+npx depopsy --json > dep-report.json
+```
+
+```json
+{
+  "summary": {
+    "total": 19,
+    "safe": 4,
+    "risky": 15,
+    "wasteKB": "1934.22"
+  },
+  "rootCauses": [...],
+  "duplicates": [...],
+  "suggestions": [...]
+}
+```
+
+---
+
+## FAQ
+
+**Q: How is this different from `npm dedupe`?**
+
+`npm dedupe` reorganizes `node_modules` at install time but doesn't prevent the problem from recurring. `depopsy` analyzes your *lockfile* to explain the root cause and writes `overrides`/`resolutions` to your `package.json` — so the deduplication survives a fresh `npm install`.
+
+**Q: Is it safe to run on production projects?**
+
+Yes. The `analyze` and `trace` commands are fully **read-only**. The `fix` command defaults to a dry-run — you must explicitly pass `--yes` to make changes, and it always creates a backup first.
+
+**Q: Does it work with workspaces / monorepos?**
+
+Yes. It automatically detects workspace packages and excludes them from root cause attribution (they use `link:`, `workspace:`, or `file:` version strings in lockfiles).
+
+**Q: Why does it show "RISKY" for some duplicates?**
+
+RISKY means the duplicate versions span **multiple major versions** (e.g., `react@17` and `react@18`). These cannot be safely auto-aligned because major version bumps can include breaking changes. Use `depopsy trace <pkg>` to understand which dependency is causing it.
+
+**Q: Why don't I see `semver` or `chalk` as root causes?**
+
+These are *leaf* utility packages — they are always pulled in transitively, never directly causing bloat. `depopsy` suppresses them from root cause output to keep results actionable. Use `--verbose` or `trace` to inspect them.
+
+---
+
+## Requirements
+
+- **Node.js** `>= 18.0.0`
+- A project with at least one lockfile: `package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml`
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/depopsy/depopsy
+cd depopsy
+npm install
+npm test
+```
+
+Please open an issue before submitting a pull request for significant changes.
+
+---
+
+## License
+
+[MIT](./LICENSE) © 2026 depopsy contributors
+
+---
+
+<div align="center">
+Built with ❤️ for the open-source JavaScript ecosystem.
+</div>

package/bin/cli.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import { setupCommands } from '../src/cli/index.js';
+import { fileURLToPath } from 'url';
+import path from 'path';
+import fs from 'fs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Resolve version from this package's own package.json.
+// Works correctly whether invoked via: node bin/cli.js, npm link, npm install -g, or npx.
+let version = '1.0.0';
+try {
+  const pkgPath = path.join(__dirname, '..', 'package.json');
+  version = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version;
+} catch {
+  // Silently fall back — the CLI is still fully functional without a version string.
+}
+
+program
+  .name('depopsy')
+  .description('NPM doctor for dependency bloat. Detects and resolves duplicated dependencies in your lockfile.')
+  .version(version, '-v, --version', 'Output the current version')
+  .addHelpText('after', `
+Examples:
+  $ depopsy                   Full dependency health report
+  $ depopsy --simple          Top 3 root causes only
+  $ depopsy --verbose         Full breakdown of every group
+  $ depopsy --json            JSON output for CI/CD pipelines
+  $ depopsy --ci              Minimal JSON + exit codes for CI
+  $ depopsy fix               Dry-run safe deduplication fixes
+  $ depopsy fix --yes         Apply fixes to package.json
+  $ depopsy trace <pkg>       Trace a package to its root cause
+`);
+
+setupCommands(program);
+
+async function runCLI() {
+  await program.parseAsync(process.argv);
+}
+
+try {
+  await runCLI();
+} catch (err) {
+  console.error("❌ Error:", err.message);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "depopsy",
+  "version": "1.0.0",
+  "description": "Understand why your dependencies are bloated — detect and fix duplicated packages in your lockfile.",
+  "bin": {
+    "depopsy": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "dependencies",
+    "duplicates",
+    "npm",
+    "pnpm",
+    "yarn",
+    "optimization",
+    "cli",
+    "lockfile",
+    "deduplication",
+    "bloat",
+    "bundle",
+    "monorepo",
+    "root-cause",
+    "package-manager"
+  ],
+  "author": "depopsy contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/depopsy/depopsy"
+  },
+  "homepage": "https://github.com/depopsy/depopsy#readme",
+  "bugs": {
+    "url": "https://github.com/depopsy/depopsy/issues"
+  },
+  "dependencies": {
+    "@yarnpkg/lockfile": "^1.1.0",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "js-yaml": "^4.1.1",
+    "semver": "^7.7.4"
+  }
+}

package/src/analyze/detector.js

@@ -0,0 +1,144 @@
+import fs from 'fs/promises';
+import path from 'path';
+import semver from 'semver';
+
+/**
+ * Super fast directory size calculator.
+ * Silently fails and returns 0 if directory doesn't exist or there's a permission error.
+ */
+async function getDirectorySize(dirPath) {
+  let size = 0;
+  try {
+    const files = await fs.readdir(dirPath, { withFileTypes: true });
+    for (const file of files) {
+      const fullPath = path.join(dirPath, file.name);
+      if (file.isDirectory()) {
+        size += await getDirectorySize(fullPath);
+      } else {
+        const stats = await fs.stat(fullPath);
+        size += stats.size;
+      }
+    }
+  } catch (error) {
+    // Ignore errors (e.g., ENOENT if not installed)
+    return 0;
+  }
+  return size;
+}
+
+/**
+ * Analyzes the parsed packages map and returns a list of duplicated packages.
+ * @param {Map<string, { instances: string[], versions: Set<string> }>} packagesMap 
+ * @param {string} projectDir 
+ * @returns {Promise<Array>} List of duplicates, sorted by severity/instances
+ */
+export async function detectDuplicates(packagesMap, projectDir) {
+  const duplicates = [];
+
+  for (const [name, data] of packagesMap.entries()) {
+    if (data.versions.size > 1) {
+      let totalWastedBytes = 0;
+      let approxSize = false;
+
+      // Group instances by version
+      const instancesByVersion = new Map();
+      for (const instance of data.instances) {
+        if (!instancesByVersion.has(instance.version)) {
+          instancesByVersion.set(instance.version, []);
+        }
+        instancesByVersion.get(instance.version).push(instance);
+      }
+
+      // Evaluate safety using semver
+      const validVersions = Array.from(data.versions).filter(v => semver.valid(semver.coerce(v)));
+      const coercedVersions = validVersions.map(v => semver.coerce(v));
+      const majors = new Set(coercedVersions.map(v => v.major));
+      
+      const safety = majors.size === 1 ? 'SAFE' : 'RISKY';
+      let suggestedVersion = null;
+
+      // Calculate instances counts
+      const counts = Array.from(instancesByVersion.entries()).map(([v, instances]) => ({
+        version: v,
+        count: instances.length
+      })).sort((a, b) => b.count - a.count);
+
+      const mostFrequent = counts[0];
+
+      if (safety === 'SAFE') {
+        const sortedOriginals = [...validVersions].sort((a, b) => {
+          return semver.rcompare(semver.coerce(a), semver.coerce(b));
+        });
+        
+        // Popularity heuristic: if one version is overwhelmingly popular (>= 80% usage), prefer it
+        if (mostFrequent && mostFrequent.count >= data.instances.length * 0.8) {
+          suggestedVersion = mostFrequent.version;
+        } else {
+          // Otherwise, highest version
+          suggestedVersion = sortedOriginals[0];
+        }
+      } else {
+         // RISKY: optionally suggest highest version as a direction, but we keep it null to avoid auto-fix
+         suggestedVersion = null;
+      }
+
+      const duplicateVersionsInfo = [];
+
+      // Calculate sizes for non-canonical versions (wasted sizes)
+      for (const [version, instances] of instancesByVersion.entries()) {
+        let versionBytes = 0;
+        const allParents = new Set();
+        const allAncestors = new Set();
+        const allRoots = new Set();
+        
+        // Calculate size on disk if available (only for this version's instances)
+        for (const inst of instances) {
+            const absolutePath = path.join(projectDir, inst.path);
+            const size = await getDirectorySize(absolutePath);
+            versionBytes += size;
+            
+            if (inst.parents) inst.parents.forEach(p => allParents.add(p));
+            if (inst.allParents) inst.allParents.forEach(a => allAncestors.add(a));
+            if (inst.roots) inst.roots.forEach(r => allRoots.add(r));
+        }
+
+        duplicateVersionsInfo.push({
+            version,
+            count: instances.length,
+            instances,
+            parents: Array.from(allParents),
+            ancestors: Array.from(allAncestors),
+            roots: Array.from(allRoots),
+            sizeBytes: versionBytes
+        });
+
+        // Any version that isn't the primary selected version is considered "waste" (optimistic assumption)
+        if (safety === 'SAFE' && version !== suggestedVersion) {
+            totalWastedBytes += versionBytes;
+        } else if (safety === 'RISKY' && version !== mostFrequent.version) {
+            totalWastedBytes += versionBytes;
+        }
+      }
+
+      duplicates.push({
+        name,
+        versions: Array.from(data.versions),
+        totalInstances: data.instances.length,
+        wastedBytes: totalWastedBytes,
+        suggestedVersion,
+        safety,
+        details: duplicateVersionsInfo.sort((a, b) => b.count - a.count)
+      });
+    }
+  }
+
+  // Sort by wasted bytes (if available) then by total instances
+  duplicates.sort((a, b) => {
+    if (b.wastedBytes !== a.wastedBytes) {
+      return b.wastedBytes - a.wastedBytes;
+    }
+    return b.totalInstances - a.totalInstances;
+  });
+
+  return duplicates;
+}