depopsy 1.0.0

package/src/analyze/grouper.js

@@ -0,0 +1,298 @@
+// Packages that are well-known low-level utilities — never actionable as root causes
+const LEAF_BLACKLIST = new Set([
+  // Terminal styling
+  'chalk', 'ansi-styles', 'ansi-regex', 'strip-ansi', 'wrap-ansi', 'string-width',
+  'color-convert', 'color-name', 'supports-color', 'has-flag', 'kleur', 'picocolors',
+  // Character / string utilities
+  'is-fullwidth-code-point', 'emoji-regex', 'escape-string-regexp', 'string-length',
+  'widest-line', 'wrap-ansi-cjs',
+  // Core Node.js polyfills / util
+  'inherits', 'safe-buffer', 'once', 'wrappy', 'inflight', 'ee-first', 'depd',
+  'ms', 'debug', 'signal-exit',
+  // Glob / file matching
+  'minimatch', 'glob', 'brace-expansion', 'balanced-match', 'concat-map',
+  'path-is-absolute', 'path-type', 'picomatch', 'micromatch', 'fast-glob',
+  'glob-parent', 'is-glob', 'is-extglob', 'fill-range', 'to-regex-range',
+  // Version / semver
+  'semver', 'semver-compare', 'compare-versions',
+  // MIME
+  'mime', 'mime-types', 'mime-db',
+  // Collection / iteration utilities
+  'lru-cache', 'yallist', 'minipass',
+  // Argument parsing
+  'camelcase', 'decamelize', 'minimist', 'yargs-parser',
+  // Config / rc
+  'ini', 'js-ini', 'strip-json-comments',
+  // Process
+  'cross-spawn', 'execa', 'which', 'shebang-command', 'shebang-regex', 'isexe',
+  // Misc
+  'p-limit', 'p-locate', 'locate-path', 'path-exists', 'yocto-queue',
+  'queue-microtask', 'run-parallel', 'reusify', 'fastq',
+]);
+
+// Regex-based matcher for families not enumerated above
+function isLeafPackage(name) {
+  if (LEAF_BLACKLIST.has(name)) return true;
+  if (/^(ansi|color|strip|wrap|supports|is-|has-|get-|set-)/.test(name)) return true;
+  if (/(-regex|-styles|-utils|-compat|-ify|-cjs)$/.test(name)) return true;
+  return false;
+}
+
+// Same predicate exported for the formatter
+export function isLowLevelPackage(name) {
+  if (!name || name.startsWith('⚠️')) return true;
+  const bare = name.startsWith('@') ? name.split('/').slice(1).join('/') : name;
+  if (isLeafPackage(bare)) return true;
+  return /(ansi|regex|string|width|wrap|strip|minimatch|semver|color|glob)/i.test(bare);
+}
+
+/**
+ * Extract the bare package name from a "name@version" string.
+ * Handles scoped packages like "@babel/core@7.0.0" correctly.
+ */
+function pkgName(nameAtVersion) {
+  if (!nameAtVersion) return '';
+  if (nameAtVersion.startsWith('@')) {
+    const second = nameAtVersion.indexOf('@', 1);
+    return second > 0 ? nameAtVersion.substring(0, second) : nameAtVersion;
+  }
+  const at = nameAtVersion.indexOf('@');
+  return at > 0 ? nameAtVersion.substring(0, at) : nameAtVersion;
+}
+
+/**
+ * SOURCE PRIORITY — The single source of truth for which packages to
+ * attribute a duplicate to.
+ *
+ * Priority (highest → lowest):
+ *   1. roots[]   — pre-computed top-level introducers (pnpm ownership DFS
+ *                  or npm graph traversal root nodes). Always the preferred
+ *                  attribution because they represent INTENTIONAL dependencies.
+ *   2. parents[] — immediate dependents. Closer to the signal than the full
+ *                  ancestor chain, and avoids "ancestor soup" dilution.
+ *   3. ancestors — full flattened chain. Last resort; very noisy because it
+ *                  includes every transitive dependency, making low-level
+ *                  packages appear highly frequent.
+ *
+ * NEVER use ancestors first — on large graphs (Next.js) the ancestor list
+ * is hundreds of entries long and low-level packages like `semver` appear
+ * in almost every chain, making them look like root causes.
+ */
+function getSources(detail) {
+  if (detail.roots && detail.roots.length > 0) return detail.roots;
+  if (detail.parents && detail.parents.length > 0) return detail.parents;
+  // Canonical ancestors field (detector maps inst.allParents → ancestors)
+  const anc = detail.ancestors || detail.allParents || [];
+  return anc;
+}
+
+function computeFixLikelihood(safeties) {
+  const safeCount = safeties.filter(s => s === 'SAFE').length;
+  const totalCount = safeties.length;
+  if (totalCount === 0) return 'LOW';
+  if (safeCount === totalCount) return 'HIGH';
+  if (safeCount / totalCount >= 0.5) return 'MEDIUM';
+  return 'LOW';
+}
+
+/**
+ * Compute confidence based on per-package version spread.
+ *
+ * Rather than pooling ALL version strings together (which always yields
+ * 3+ majors for large groups like lerna→164 packages), we score each
+ * affected package individually:
+ *   - singleMajor: the package's duplicate versions share 1 major → easy fix
+ *   - twoMajors:   2 distinct majors            → likely fixable
+ *   - manyMajors:  3+ distinct majors           → hard / risky
+ *
+ * Confidence is then determined by what fraction of affected packages
+ * fall into each bucket:
+ *   HIGH   → >60% are singleMajor
+ *   MEDIUM → >30% are singleMajor  (or >50% are singleMajor+twoMajors)
+ *   LOW    → everything else
+ */
+function computeConfidence(group, scoredDuplicates) {
+  if (!group.affectedPackages || group.affectedPackages.length === 0) {
+    return computeFixLikelihood(group.safeties || []);
+  }
+
+  let singleMajor = 0;
+  let twoMajors   = 0;
+  let manyMajors  = 0;
+  let noData      = 0;
+
+  for (const pkgName of group.affectedPackages) {
+    const dup = scoredDuplicates.find(d => d.name === pkgName);
+    if (!dup || !dup.versions || dup.versions.length === 0) {
+      noData++;
+      continue;
+    }
+    const majors = new Set(
+      dup.versions
+        .map(v => (v || '').split('.')[0].replace(/[^0-9]/g, ''))
+        .filter(Boolean)
+    );
+    if (majors.size <= 1)      singleMajor++;
+    else if (majors.size <= 2) twoMajors++;
+    else                       manyMajors++;
+  }
+
+  const total = singleMajor + twoMajors + manyMajors;
+  if (total === 0) return computeFixLikelihood(group.safeties || []);
+
+  const pctSingle   = singleMajor / total;
+  const pctEasy     = (singleMajor + twoMajors) / total;
+
+  if (pctSingle > 0.6)  return 'HIGH';
+  if (pctSingle > 0.3 || pctEasy > 0.5) return 'MEDIUM';
+  return 'LOW';
+}
+
+/**
+ * Build an introducer attribution map.
+ * filterFn(pkgName) → true means this name is an acceptable introducer.
+ * Each duplicate is counted once per introducer (deduped via seenForDup).
+ */
+function buildIntroducerMap(scoredDuplicates, filterFn) {
+  const introducerMap = {};
+
+  for (const dup of scoredDuplicates) {
+    const seenForDup = new Set();
+
+    for (const detail of dup.details) {
+      const sources = getSources(detail);
+
+      for (const p of sources) {
+        const name = pkgName(p);
+        if (!name || !filterFn(name)) continue;
+        if (seenForDup.has(name)) continue;
+        seenForDup.add(name);
+
+        if (!introducerMap[name]) {
+          introducerMap[name] = { name, affectedPackages: [], count: 0, safeties: [] };
+        }
+        introducerMap[name].count += dup.totalInstances;
+        if (!introducerMap[name].affectedPackages.includes(dup.name)) {
+          introducerMap[name].affectedPackages.push(dup.name);
+        }
+        introducerMap[name].safeties.push(dup.safety);
+      }
+    }
+  }
+
+  return introducerMap;
+}
+
+function formatGroups(map, limit = 8, scoredDuplicates = []) {
+  const groups = Object.values(map);
+
+  // Degradation guard: silently continue — each root maps to 1 package is a valid
+  // (though non-ideal) state that the formatter handles with the low-level fallback.
+
+  return groups
+    .sort((a, b) =>
+      b.affectedPackages.length - a.affectedPackages.length ||
+      b.count - a.count
+    )
+    .slice(0, limit)
+    .map(g => {
+      const fixLikelihood = computeFixLikelihood(g.safeties);
+      const confidence    = computeConfidence(g, scoredDuplicates);
+      return {
+        name: g.name,
+        affectedPackages: g.affectedPackages,
+        count: g.count,
+        fixLikelihood,
+        confidence
+      };
+    });
+}
+
+/**
+ * Build a coverage map: pkgName → Set<dupName>
+ * Tells us how many distinct duplicate packages each candidate name covers.
+ * Uses getSources() priority so roots are always preferred over ancestors.
+ */
+function buildCoverageMap(scoredDuplicates) {
+  const coverageMap = {};
+
+  for (const dup of scoredDuplicates) {
+    const seenNames = new Set();
+
+    for (const detail of dup.details) {
+      const sources = getSources(detail);
+
+      for (const p of sources) {
+        const name = pkgName(p);
+        if (!name) continue;
+        if (seenNames.has(name)) continue;
+
+        seenNames.add(name);
+
+        // soft penalty for low-level packages instead of removing them
+        const penalty = isLeafPackage(name) ? 0.3 : 1.0;
+
+        if (!coverageMap[name]) {
+          coverageMap[name] = {
+            dups: new Set(),
+            weight: 0
+          };
+        }
+
+        coverageMap[name].dups.add(dup.name);
+        coverageMap[name].weight += penalty;
+      }
+    }
+  }
+
+  return coverageMap;
+}
+
+export function groupRootCauses(scoredDuplicates, topLevelDeps = new Set()) {
+  // ── LAYER 1: Explicit top-level matching (pnpm importers) ──────────────────
+  // When topLevelDeps is provided, only names from that set qualify.
+  // getSources() ensures we read roots[] first, so pnpm ownership DFS results
+  // are used directly without going through the noisy ancestor chain.
+  if (topLevelDeps && topLevelDeps.size > 0) {
+    const map = buildIntroducerMap(scoredDuplicates, name => topLevelDeps.has(name));
+    if (Object.keys(map).length > 0) {
+      return formatGroups(map, 8, scoredDuplicates);
+    }
+  }
+
+  // ── LAYER 2: Coverage-based grouping (npm / yarn / pnpm without importers) ─
+  // Build coverageMap using getSources() priority (roots > parents > ancestors).
+  // Candidates with highest coverage (most distinct dups) win.
+  const coverageMap = buildCoverageMap(scoredDuplicates);
+
+  const candidates = Object.entries(coverageMap)
+    .sort((a, b) =>
+      b[1].weight - a[1].weight ||
+      b[1].dups.size - a[1].dups.size
+    );
+
+  // Try strict threshold first (≥2 dups covered)
+  const strict = candidates.filter(([, data]) => data.dups.size >= 2);
+  if (strict.length > 0) {
+    const topNames = new Set(strict.slice(0, 10).map(([n]) => n));
+    const map = buildIntroducerMap(scoredDuplicates, name => topNames.has(name));
+    if (Object.keys(map).length > 0) return formatGroups(map, 8, scoredDuplicates);
+  }
+
+  // Drop to threshold=1 if nothing met ≥2
+  if (candidates.length > 0) {
+    const topNames = new Set(candidates.slice(0, 10).map(([n]) => n));
+    const map = buildIntroducerMap(scoredDuplicates, name => topNames.has(name));
+    if (Object.keys(map).length > 0) return formatGroups(map, 8, scoredDuplicates);
+  }
+
+  // candidates.length === 0 falls through to the MISC bucket below
+  // ── LAYER 3: Misc fallback (truly no graph data) ────────────────────────────
+  const MISC = '⚠️ Misc / Low-level dependencies';
+  return [{
+    name: MISC,
+    affectedPackages: scoredDuplicates.map(d => d.name),
+    count: scoredDuplicates.reduce((s, d) => s + d.totalInstances, 0),
+    fixLikelihood: 'LOW'
+  }];
+}

package/src/analyze/scorer.js

@@ -0,0 +1,40 @@
+import semver from 'semver';
+
+/**
+ * Calculates a severity score and confidence level for fixing the duplicate.
+ * @param {Array} duplicates The raw duplicate analysis
+ * @returns {Array} Duplicates with embedded severity/confidence scores
+ */
+export function scoreDuplicates(duplicates) {
+  const scored = duplicates.map(dup => {
+    let severity = 'LOW';
+    // Update severity based on counts based on user prompt (e.g. 4+ -> HIGH)
+    if (dup.totalInstances >= 4 || dup.wastedBytes > 200 * 1024) {
+      severity = 'HIGH';
+    } else if (dup.totalInstances >= 2 || dup.wastedBytes > 50 * 1024) {
+      severity = 'MEDIUM';
+    }
+
+    let confidence = 'LOW';
+    if (dup.safety === 'SAFE') {
+      confidence = 'HIGH';
+    } else if (dup.details && dup.details.length > 0 && dup.details[0].count >= dup.totalInstances * 0.8) {
+      confidence = 'MEDIUM';
+    }
+
+    let severityWeight = 10;
+    if (severity === 'HIGH') severityWeight = 100;
+    else if (severity === 'MEDIUM') severityWeight = 50;
+    
+    const score = (dup.totalInstances * 10) + severityWeight;
+
+    return {
+      ...dup,
+      severity,
+      confidence,
+      score
+    };
+  });
+
+  return scored.sort((a, b) => b.score - a.score);
+}

package/src/cli/analyze-command.js

@@ -0,0 +1,57 @@
+import chalk from 'chalk';
+import { parseLockfile } from '../parser/index.js';
+import { buildDependencyGraph } from '../graph/builder.js';
+import { detectDuplicates } from '../analyze/detector.js';
+import { scoreDuplicates } from '../analyze/scorer.js';
+import { groupRootCauses } from '../analyze/grouper.js';
+import { printTextReport, printJsonReport, printCiReport } from '../report/formatter.js';
+import { detectWorkspaces } from '../utils/workspace.js';
+import fs from 'fs/promises';
+import path from 'path';
+
+export async function commandAnalyze(options) {
+  const projectDir = process.cwd();
+
+  try {
+    if (!options.json && !options.ci) {
+      console.log(chalk.dim('Analyzing large dependency graph...'));
+    }
+
+    // Try reading package.json for workspaces
+    let pkg = null;
+    try {
+      const pkgStr = await fs.readFile(path.join(projectDir, 'package.json'), 'utf-8');
+      pkg = JSON.parse(pkgStr);
+    } catch(e) {}
+    
+    // We can use the workspace config eventually to refine ignored internal packages
+    await detectWorkspaces(projectDir, pkg);
+
+    const { type, map: rawPackagesMap, topLevelDeps = new Set() } = await parseLockfile(projectDir);
+    const cleanMap = buildDependencyGraph(rawPackagesMap);
+    const duplicates = await detectDuplicates(cleanMap, projectDir);
+    const scoredDuplicates = scoreDuplicates(duplicates);
+    const rootCauses = groupRootCauses(scoredDuplicates, topLevelDeps);
+
+    if (options.ci) {
+      printCiReport(scoredDuplicates);
+      process.exit(scoredDuplicates.length > 0 ? 1 : 0);
+    } else if (options.json) {
+      printJsonReport(scoredDuplicates, rootCauses);
+      process.exit(scoredDuplicates.length > 0 ? 1 : 0);
+    } else {
+      if (type === 'npm') console.log(chalk.dim('Detected Package Manager: npm'));
+      if (type === 'yarn') console.log(chalk.dim('Detected Package Manager: yarn'));
+      if (type === 'pnpm') console.log(chalk.dim('Detected Package Manager: pnpm'));
+      printTextReport(scoredDuplicates, rootCauses, options);
+      process.exit(scoredDuplicates.length > 0 ? 1 : 0);
+    }
+  } catch (error) {
+    if (options.json || options.ci) {
+      console.log(JSON.stringify({ error: error.message }));
+    } else {
+      console.error(chalk.red(`❌ Error: ${error.message}`));
+    }
+    process.exit(2);
+  }
+}

package/src/cli/fix-command.js

@@ -0,0 +1,37 @@
+import chalk from 'chalk';
+import { parseLockfile } from '../parser/index.js';
+import { buildDependencyGraph } from '../graph/builder.js';
+import { detectDuplicates } from '../analyze/detector.js';
+import { scoreDuplicates } from '../analyze/scorer.js';
+import { applyFixes } from '../fix/fixer.js';
+import { detectWorkspaces } from '../utils/workspace.js';
+import fs from 'fs/promises';
+import path from 'path';
+
+export async function commandFix(options) {
+  const projectDir = process.cwd();
+  const isDryRun = !options.yes;
+
+  try {
+    console.log(chalk.dim('Analyzing dependencies to prepare fix plan...'));
+    
+    let pkg = null;
+    try {
+      const pkgStr = await fs.readFile(path.join(projectDir, 'package.json'), 'utf-8');
+      pkg = JSON.parse(pkgStr);
+    } catch(e) {}
+    
+    await detectWorkspaces(projectDir, pkg);
+
+    const { type, map: rawPackagesMap } = await parseLockfile(projectDir);
+    const cleanMap = buildDependencyGraph(rawPackagesMap);
+    const duplicates = await detectDuplicates(cleanMap, projectDir);
+    const scoredDuplicates = scoreDuplicates(duplicates);
+
+    await applyFixes(scoredDuplicates, projectDir, isDryRun, type);
+
+  } catch (error) {
+    console.error(chalk.red(`❌ Error: ${error.message}`));
+    process.exit(1);
+  }
+}

package/src/cli/index.js

@@ -0,0 +1,27 @@
+import { commandAnalyze } from './analyze-command.js';
+import { commandFix } from './fix-command.js';
+import { commandTrace } from './trace-command.js';
+
+export function setupCommands(program) {
+  // Add default behavior when no command is passed to run 'analyze'
+  program
+    .command('analyze', { isDefault: true })
+    .description('Analyze the lockfile and output a duplicate dependencies report')
+    .option('--json', 'Output report as JSON')
+    .option('--ci', 'Run in CI mode (minimal JSON, correct exit codes, no formatting)')
+    .option('--verbose', 'Show full breakdown of all root causes and packages')
+    .option('--simple', 'Show only top 3 root causes — great for a quick overview')
+    .option('--top <number>', 'Limit results to top N root cause groups (default 5)', parseInt)
+    .action(commandAnalyze);
+
+  program
+    .command('fix')
+    .description('Safely automatically consolidate duplicate dependencies via package.json overrides')
+    .option('--yes', 'Confirm to actually write the changes (defaults to dry-run)')
+    .action(commandFix);
+
+  program
+    .command('trace <package>')
+    .description('Trace which top-level dependencies introduce a given package')
+    .action(commandTrace);
+}

package/src/cli/trace-command.js

@@ -0,0 +1,104 @@
+import chalk from 'chalk';
+import { parseLockfile } from '../parser/index.js';
+import { buildDependencyGraph } from '../graph/builder.js';
+import { detectDuplicates } from '../analyze/detector.js';
+import { scoreDuplicates } from '../analyze/scorer.js';
+
+export async function commandTrace(pkgArg, options) {
+  const projectDir = process.cwd();
+  const targetName = pkgArg.replace(/@.*/, ''); // strip version if accidentally passed
+
+  try {
+    console.log(chalk.dim(`\nTracing "${targetName}" through dependency graph...\n`));
+
+    const { map: rawPackagesMap } = await parseLockfile(projectDir);
+    const cleanMap = buildDependencyGraph(rawPackagesMap);
+    const duplicates = await detectDuplicates(cleanMap, projectDir);
+    const scored = scoreDuplicates(duplicates);
+
+    // Find the target duplicate (if any)
+    const target = scored.find(d => d.name === targetName);
+
+    if (!target) {
+      console.log(chalk.yellow(`  ⚠ "${targetName}" is not in the duplicate list.`));
+      console.log(chalk.dim(`  It might exist at a single version (no conflict) or not be installed.\n`));
+      return;
+    }
+
+    // Collect all root introducers across all instances
+    const rootSet = new Map(); // rootName → versions[]
+    for (const detail of target.details) {
+      for (const r of (detail.roots || [])) {
+        if (!rootSet.has(r)) rootSet.set(r, new Set());
+      }
+      for (const p of (detail.parents || [])) {
+        // Group immediate parents as secondary info
+        if (!rootSet.has(p)) rootSet.set(p, new Set());
+      }
+    }
+
+    // Collect all allParents for chain display
+    const allAncestors = new Set();
+    for (const detail of target.details) {
+      for (const a of (detail.ancestors || detail.allParents || detail.roots || [])) {
+        allAncestors.add(a);
+      }
+    }
+
+    console.log(chalk.bold.white(`🔍 Trace: ${chalk.cyan(targetName)}`));
+    console.log(chalk.dim('─'.repeat(50)));
+    console.log('');
+
+    // Show versions found
+    console.log(`  ${chalk.bold('Versions found:')} ${target.versions.map(v => chalk.yellow(v)).join(', ')}`);
+    console.log(`  ${chalk.bold('Safety:')} ${target.safety === 'SAFE' ? chalk.green('SAFE') : chalk.red('RISKY')}`);
+    console.log('');
+
+    // Show which top-level deps introduce this
+    const roots = [...new Set(target.details.flatMap(d => d.roots || []))].filter(Boolean);
+    if (roots.length > 0) {
+      console.log(chalk.bold.white(`  ${targetName} is introduced by:`));
+      for (const r of roots) {
+        console.log(`    ${chalk.dim('▶')} ${chalk.cyan(r)}`);
+      }
+    } else if (allAncestors.size > 0) {
+      console.log(chalk.bold.white(`  ${targetName} appears via these ancestors:`));
+      const ancestors = [...allAncestors].slice(0, 15);
+      for (const a of ancestors) {
+        console.log(`    ${chalk.dim('→')} ${a}`);
+      }
+      if (allAncestors.size > 15) {
+        console.log(chalk.dim(`    (+ ${allAncestors.size - 15} more)`));
+      }
+    } else {
+      console.log(chalk.yellow(`  No parent chain found.`));
+      console.log(chalk.dim(`  "${targetName}" may be a direct project dependency.\n`));
+    }
+
+    // Show immediate parents per version
+    console.log('');
+    console.log(chalk.bold.white('  Per-version breakdown:'));
+    for (const detail of target.details) {
+      const immediateParents = (detail.parents || []).slice(0, 5);
+      const more = (detail.parents || []).length - immediateParents.length;
+      console.log(`    ${chalk.yellow(detail.version)} — required by: ${
+        immediateParents.length > 0
+          ? immediateParents.join(', ') + (more > 0 ? chalk.dim(` (+${more} more)`) : '')
+          : chalk.dim('(unknown)')
+      }`);
+    }
+
+    console.log('');
+    console.log(chalk.dim('─'.repeat(50)));
+    if (target.suggestedVersion) {
+      console.log(`  💡 Suggested fix: align all to ${chalk.green(target.suggestedVersion)}`);
+      console.log(chalk.dim(`     Run: npx depopsy fix\n`));
+    } else {
+      console.log(chalk.dim(`  ⚠  No auto-fix available — versions span multiple majors.\n`));
+    }
+
+  } catch (err) {
+    console.error(chalk.red(`❌ Error: ${err.message}`));
+    process.exit(2);
+  }
+}

package/src/fix/fixer.js

@@ -0,0 +1,90 @@
+import fs from 'fs/promises';
+import path from 'path';
+import chalk from 'chalk';
+
+export async function applyFixes(scoredDuplicates, projectDir, isDryRun, packageManagerType) {
+  const packageJsonPath = path.join(projectDir, 'package.json');
+  
+  let pkgContent;
+  try {
+    pkgContent = await fs.readFile(packageJsonPath, 'utf-8');
+  } catch (e) {
+    throw new Error('Could not read package.json');
+  }
+
+  const pkg = JSON.parse(pkgContent);
+
+  // Filter for safe duplicates to fix automatically
+  const targets = scoredDuplicates.filter(dup => dup.safety === 'SAFE' && dup.suggestedVersion !== null);
+  const riskyTargets = scoredDuplicates.filter(dup => dup.safety === 'RISKY');
+
+  if (targets.length === 0) {
+    console.log(chalk.green('✅ No auto-fixes available. Semver-compatible SAFE duplicates not found.'));
+    return;
+  }
+
+  // Build the overrides object
+  const newOverrides = {};
+  for (const target of targets) {
+    newOverrides[target.name] = target.suggestedVersion;
+  }
+
+  console.log(chalk.bold.underline(`\n🛠️  Deduplication Fix Plan (${packageManagerType}):`));
+  console.log(chalk.dim('Applying SAFE fixes only...'));
+
+  for (const target of targets) {
+    console.log(`  ✔ ${chalk.cyan(target.name)} (SAFE) -> aligns to ${chalk.green(target.suggestedVersion)}`);
+  }
+
+  if (riskyTargets.length > 0) {
+    for (const target of riskyTargets) {
+      console.log(`  ⚠️ skipped ${chalk.cyan(target.name)} (RISKY)`);
+    }
+  }
+
+  if (isDryRun) {
+    console.log(chalk.yellow('\n⚠️  This is a DRY RUN. No files have been modified.'));
+    console.log(`To apply these changes and update your package.json, run:\n  ${chalk.cyan('npx depopsy fix --yes')}\n`);
+    return;
+  }
+
+  // Determine property to update based on package manager
+  let propToUpdate = 'overrides';
+  if (packageManagerType === 'yarn') {
+    propToUpdate = 'resolutions';
+  } else if (packageManagerType === 'pnpm') {
+    if (!pkg.pnpm) pkg.pnpm = {};
+    propToUpdate = 'pnpm.overrides';
+  }
+
+  // Apply fixes
+  if (packageManagerType === 'pnpm') {
+    if (!pkg.pnpm.overrides) pkg.pnpm.overrides = {};
+    Object.assign(pkg.pnpm.overrides, newOverrides);
+  } else {
+    if (!pkg[propToUpdate]) pkg[propToUpdate] = {};
+    Object.assign(pkg[propToUpdate], newOverrides);
+  }
+
+  // Backup files
+  try {
+    const backupDir = path.join(projectDir, '.depopsy-backup');
+    await fs.mkdir(backupDir, { recursive: true });
+    await fs.writeFile(path.join(backupDir, 'package.json.bak'), pkgContent);
+    console.log(chalk.dim(`\nBacked up package.json to ${backupDir}`));
+  } catch (e) {
+    console.log(chalk.dim(`Warning: Failed to create backups.`));
+  }
+
+  // Write new package.json
+  await fs.writeFile(packageJsonPath, JSON.stringify(pkg, null, 2) + '\n');
+  console.log(chalk.green(`\n✅ Successfully updated package.json "${propToUpdate}".`));
+  
+  if (packageManagerType === 'npm') {
+    console.log(chalk.bold(`You MUST now run ${chalk.cyan('npm install')} to apply the deduplication to your lockfile!\n`));
+  } else if (packageManagerType === 'yarn') {
+    console.log(chalk.bold(`You MUST now run ${chalk.cyan('yarn install')} to apply the deduplication to your lockfile!\n`));
+  } else if (packageManagerType === 'pnpm') {
+    console.log(chalk.bold(`You MUST now run ${chalk.cyan('pnpm install')} to apply the deduplication to your lockfile!\n`));
+  }
+}

package/src/graph/builder.js

@@ -0,0 +1,30 @@
+import { isLocalVersion } from '../utils/workspace.js';
+
+export function buildDependencyGraph(rawPackagesMap) {
+  // In the future, this can stitch together full traversal trees.
+  // For duplicate bloat detection, we just need to ensure the raw map is clean
+  // of local/workspace internal packages, which we filter out here.
+  
+  const cleanMap = new Map();
+
+  for (const [name, data] of rawPackagesMap.entries()) {
+    const validVersions = new Set();
+    const validInstances = [];
+
+    for (const instance of data.instances) {
+      if (!isLocalVersion(instance.version)) {
+        validVersions.add(instance.version);
+        validInstances.push(instance);
+      }
+    }
+
+    if (validVersions.size > 0) {
+      cleanMap.set(name, {
+        versions: validVersions,
+        instances: validInstances
+      });
+    }
+  }
+
+  return cleanMap;
+}