helpforbegs 0.0.0-stage → 1.0.0

package/src/messages.js

@@ -0,0 +1,82 @@
+// src/messages.js
+// WHY: Keeping all human-facing text in one place makes it easy to maintain,
+// translate, review tone, and switch cleanly between friendly mode and roast mode.
+
+const NORMAL_MESSAGES = {
+  scanHeader: (filesCount) => `🔍 Scanning your project... (${filesCount} files read)`,
+  monorepoNotice: (count) => `📦 Monorepo detected: merged dependencies across ${count} workspace folders.`,
+  missingNodeModulesNotice: '💡 Tip: node_modules is missing. Run `npm install` for accurate folder sizes and script binary checks.',
+  largeFileSkipped: (file, sizeMb) => `ℹ️  Skipped ${file} (${sizeMb} MB) because it exceeds the 1 MB safety limit.`,
+  parseWarning: (warning) => `⚠️  ${warning} (fell back to regex scanning).`,
+
+  unusedHeader: (count) => `❌ Installed but never used (${count})`,
+  probablyHeader: (count) => `🤔 Probably unused (${count})`,
+  missingHeader: (count) => `⚠️  Used but not installed (${count})`,
+  usedHeader: (count) => `✅ ${count} package${count === 1 ? ' is' : 's are'} used correctly`,
+
+  unusedItem: (pkg, reason) => `You installed ${pkg} but never used it.`,
+  probablyItem: (pkg, reason) => `${reason || 'Detected as tooling with no direct script references; double check before removing.'}`,
+  missingItem: (pkg, firstLoc) => `Used in ${firstLoc.file}:${firstLoc.line} but missing from package.json.`,
+
+  scoreLabel: (score, grade, comment) => `📊 Health score: ${score}/100 (${grade}) "${comment}"`,
+  spaceSaved: (sizeStr) => `💾 You could free about ${sizeStr}.`,
+  cleanAllGood: '🎉 Congratulations! Your project dependencies are squeaky clean!',
+  runRemoveTip: '💡 Run `npx helpforbegs remove` to clean up safely.',
+  runDryRunTip: '💡 Run `npx helpforbegs remove --dry-run` to preview cleanup.',
+
+  gradeComments: {
+    'A+': 'Spotless! Everything installed has a clear purpose.',
+    'A': 'Excellent! Clean, lean, and very well-organized.',
+    'B': 'Pretty tidy, a few dusty corners.',
+    'C': 'Getting cluttered; time for a quick spring cleaning.',
+    'D': 'Heavy bag of unused packages slowing you down.',
+    'F': 'Critical issues found! Missing packages could break your app at runtime.',
+  },
+};
+
+const ROAST_MESSAGES = {
+  scanHeader: (filesCount) => `🔍 Inspecting the crime scene... (${filesCount} files judged)`,
+  monorepoNotice: (count) => `📦 Monorepo alert: you brought ${count} workspaces into this mess.`,
+  missingNodeModulesNotice: '💡 Even node_modules refused to show up. Run `npm install` so we can see the full damage.',
+  largeFileSkipped: (file, sizeMb) => `🐘 Skipped ${file} (${sizeMb} MB). Did you accidentally commit a movie?`,
+  parseWarning: (warning) => `⚠️  ${warning}. Your syntax confused our parser, so we squinted at it with regex.`,
+
+  unusedHeader: (count) => `❌ Digital hoarders club (${count} ghost dependencies)`,
+  probablyHeader: (count) => `🤔 Living on borrowed time (${count} mystery packages)`,
+  missingHeader: (count) => `⚠️  Playing with fire: imported but not installed (${count})`,
+  usedHeader: (count) => `✅ ${count} package${count === 1 ? '' : 's'} actually paying rent in your code`,
+
+  unusedItem: (pkg) => {
+    const jokes = [
+      `You installed ${pkg} months ago and never spoke to it again.`,
+      `${pkg} is just taking up disk space and emotional energy.`,
+      `Did you follow a 2017 tutorial and forget you installed ${pkg}?`,
+      `${pkg} has been ghosted harder than a bad first date.`,
+    ];
+    // Return a consistent joke based on string hash
+    const index = Math.abs(pkg.split('').reduce((acc, c) => acc + c.charCodeAt(0), 0)) % jokes.length;
+    return jokes[index];
+  },
+  probablyItem: (pkg, reason) => `We saw ${pkg} lurking in the shadows. Check if you still need it before deleting.`,
+  missingItem: (pkg, firstLoc) => `You imported ${pkg} in ${firstLoc.file}:${firstLoc.line} on pure faith without installing it!`,
+
+  scoreLabel: (score, grade, comment) => `📊 Health roast: ${score}/100 (${grade}) "${comment}"`,
+  spaceSaved: (sizeStr) => `💾 Removing these dead weights would free ${sizeStr} of sweet disk space.`,
+  cleanAllGood: '🎉 Wow, not a single wasted byte. Are you sure you are a beginner?',
+  runRemoveTip: '💡 Take out the trash with `npx helpforbegs remove`.',
+  runDryRunTip: '💡 Too scared? Try `npx helpforbegs remove --dry-run` first.',
+
+  gradeComments: {
+    'A+': 'Suspiciously perfect. Did you write this in a cleanroom?',
+    'A': 'Solid work! Marie Kondo would approve of this repo.',
+    'B': 'Not bad, but a few neglected packages are crying for attention.',
+    'C': 'Your package.json looks like an unfinished garage sale.',
+    'D': 'More unused weight than a gym membership in March.',
+    'F': 'An absolute danger zone! Your app will crash if you deploy this.',
+  },
+};
+
+module.exports = {
+  NORMAL_MESSAGES,
+  ROAST_MESSAGES,
+};

package/src/remover.js

@@ -0,0 +1,184 @@
+// src/remover.js
+// WHY: Deleting dependencies can be scary for beginners.
+// This module provides triple safety:
+// 1. Shows you the exact list before touching anything.
+// 2. Creates a timestamped backup of your package.json first.
+// 3. Detects your exact package manager (npm, yarn, pnpm, or bun) so your lockfile stays valid.
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { spawn } = require('child_process');
+const { analyzeProject } = require('./analyzer');
+const { calculateScoreAndSavings } = require('./scorer');
+const { createStyler } = require('./reporter');
+
+/**
+ * Detects which package manager the project uses by looking for lockfiles.
+ *
+ * @param {string} projectDir
+ * @returns {{ name: string, uninstallCmd: string[] }}
+ */
+function detectPackageManager(projectDir) {
+  if (fs.existsSync(path.join(projectDir, 'pnpm-lock.yaml'))) {
+    return { name: 'pnpm', uninstallCmd: ['remove'] };
+  }
+  if (fs.existsSync(path.join(projectDir, 'yarn.lock'))) {
+    return { name: 'yarn', uninstallCmd: ['remove'] };
+  }
+  if (fs.existsSync(path.join(projectDir, 'bun.lockb')) || fs.existsSync(path.join(projectDir, 'bun.lock'))) {
+    return { name: 'bun', uninstallCmd: ['remove'] };
+  }
+  // Default to npm
+  return { name: 'npm', uninstallCmd: ['uninstall'] };
+}
+
+/**
+ * Prompts the user with a y/N question in the terminal.
+ *
+ * @param {string} question
+ * @returns {Promise<boolean>}
+ */
+function askConfirmation(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      const trimmed = answer.trim().toLowerCase();
+      resolve(trimmed === 'y' || trimmed === 'yes');
+    });
+  });
+}
+
+/**
+ * Executes the safe package removal process.
+ *
+ * @param {string} projectDir
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun=false]
+ * @param {boolean} [options.yes=false]
+ * @param {boolean} [options.isInteractive=true]
+ * @param {boolean} [options.noColor=false]
+ * @returns {Promise<number>} Exit code (0 = success, 1 = aborted or failed)
+ */
+async function removeUnused(projectDir, options = {}) {
+  const styler = createStyler(options.noColor);
+  const pkgJsonPath = path.join(projectDir, 'package.json');
+
+  if (!fs.existsSync(pkgJsonPath)) {
+    console.log(styler.red(`❌ No package.json found in ${projectDir}`));
+    return 1;
+  }
+
+  const analysis = analyzeProject(projectDir);
+  const { sizedUnused } = calculateScoreAndSavings(analysis);
+
+  if (sizedUnused.length === 0) {
+    console.log();
+    console.log(styler.green('✨ No unused packages found! Your project is already tidy.'));
+    console.log();
+    return 0;
+  }
+
+  console.log();
+  console.log(styler.bold(`Found ${sizedUnused.length} unused package${sizedUnused.length === 1 ? '' : 's'} ready for removal:`));
+  console.log();
+
+  for (const item of sizedUnused) {
+    const sizeStr = item.bytes > 0 ? styler.gray(`(${item.formattedSize})`) : '';
+    console.log(`  • ${styler.red(item.name)} ${sizeStr}`);
+  }
+  console.log();
+
+  const pm = detectPackageManager(projectDir);
+  const pkgsToRemove = sizedUnused.map((u) => u.name);
+  const timestamp = Date.now();
+  const backupFileName = `package.json.helpforbegs.${timestamp}.bak`;
+  const backupFilePath = path.join(projectDir, backupFileName);
+
+  // Dry-run mode: explain what would happen without altering files
+  if (options.dryRun) {
+    console.log(styler.cyan(styler.bold('🔎 [DRY RUN] Simulation mode active. No changes will be made:')));
+    console.log(`   1. Would create backup at: ${backupFileName}`);
+    console.log(`   2. Would run: ${pm.name} ${pm.uninstallCmd.join(' ')} ${pkgsToRemove.join(' ')}`);
+    console.log();
+    return 0;
+  }
+
+  // Non-interactive or CI environments without --yes: refuse to run
+  if (!options.isInteractive && !options.yes) {
+    console.log(styler.yellow('⚠️  Interactive confirmation is disabled in non-interactive / CI environments.'));
+    console.log(styler.dim('   Run again with `--yes` to confirm removal automatically:'));
+    console.log(`   npx helpforbegs remove --yes`);
+    console.log();
+    return 1;
+  }
+
+  // Prompt user for confirmation unless --yes was passed
+  if (!options.yes) {
+    const confirmed = await askConfirmation(
+      styler.bold(`Are you sure you want to uninstall these ${pkgsToRemove.length} packages? (y/N): `)
+    );
+
+    if (!confirmed) {
+      console.log();
+      console.log(styler.gray('Cleanup cancelled. No changes were made.'));
+      console.log();
+      return 0;
+    }
+  }
+
+  // 1. Create timestamped backup of package.json
+  try {
+    fs.copyFileSync(pkgJsonPath, backupFilePath);
+    console.log();
+    console.log(styler.green(`🛡️  Created backup: ${backupFileName}`));
+  } catch (err) {
+    console.log(styler.red(`❌ Failed to create backup file: ${err.message}`));
+    return 1;
+  }
+
+  // 2. Run the package manager uninstall command
+  console.log(styler.cyan(`🚀 Running \`${pm.name} ${pm.uninstallCmd.join(' ')} ${pkgsToRemove.join(' ')}\`...`));
+  console.log();
+
+  return new Promise((resolve) => {
+    const child = spawn(pm.name, [...pm.uninstallCmd, ...pkgsToRemove], {
+      cwd: projectDir,
+      stdio: 'inherit',
+      shell: process.platform === 'win32', // Use shell on Windows for resolving npm.cmd
+    });
+
+    child.on('error', (err) => {
+      console.log();
+      console.log(styler.red(`❌ Failed to execute ${pm.name}: ${err.message}`));
+      console.log(styler.yellow(`   Your package.json backup is saved at: ${backupFileName}`));
+      resolve(1);
+    });
+
+    child.on('close', (code) => {
+      console.log();
+      if (code === 0) {
+        console.log(styler.green('🎉 Successfully uninstalled unused packages!'));
+        console.log(styler.dim(`   (Backup kept at ${backupFileName} just in case you ever want it back)`));
+        console.log();
+        resolve(0);
+      } else {
+        console.log(styler.red(`⚠️  ${pm.name} exited with status code ${code}.`));
+        console.log(styler.yellow(`   You can restore your original package.json from: ${backupFileName}`));
+        console.log();
+        resolve(1);
+      }
+    });
+  });
+}
+
+module.exports = {
+  removeUnused,
+  detectPackageManager,
+  askConfirmation,
+};

package/src/reporter.js

@@ -0,0 +1,186 @@
+// src/reporter.js
+// WHY: A good CLI should feel friendly, readable, and encouraging.
+// We format findings with clean indentation, gentle colors, and clear emojis.
+// When piped or run in CI, colors are stripped automatically so logs stay crisp.
+
+const chalk = require('chalk');
+const { NORMAL_MESSAGES, ROAST_MESSAGES } = require('./messages');
+
+/**
+ * Creates a color wrapper that respects the user's --no-color setting and environment.
+ *
+ * @param {boolean} noColor
+ */
+function createStyler(noColor) {
+  if (noColor) {
+    const identity = (str) => String(str);
+    return {
+      bold: identity,
+      dim: identity,
+      red: identity,
+      yellow: identity,
+      green: identity,
+      cyan: identity,
+      gray: identity,
+    };
+  }
+  return chalk;
+}
+
+/**
+ * Formats and prints the complete CLI report to stdout.
+ *
+ * @param {object} analysis - Result from analyzer.analyzeProject
+ * @param {object} scoreData - Result from scorer.calculateScoreAndSavings
+ * @param {object} [options]
+ * @param {boolean} [options.roast=false]
+ * @param {boolean} [options.noColor=false]
+ * @param {boolean} [options.json=false]
+ * @param {boolean} [options.scoreOnly=false]
+ * @returns {number} The recommended process exit code (0 = clean, 1 = issues found)
+ */
+function reportResults(analysis, scoreData, options = {}) {
+  const isRoast = Boolean(options.roast);
+  const msgBundle = isRoast ? ROAST_MESSAGES : NORMAL_MESSAGES;
+  const styler = createStyler(options.noColor);
+
+  // 1. JSON mode: output raw structured data for scripts and tools
+  if (options.json) {
+    const output = {
+      project: analysis.rootPkgJson.name || 'unnamed-project',
+      version: analysis.rootPkgJson.version || '1.0.0',
+      filesScanned: analysis.filesReadCount,
+      isMonorepo: analysis.isMonorepo,
+      workspacesCount: analysis.workspacesCount,
+      missingNodeModules: analysis.missingNodeModules,
+      health: {
+        score: scoreData.score,
+        letterGrade: scoreData.letterGrade,
+        comment: scoreData.comment,
+        potentialSavingsBytes: scoreData.totalBytesSaved,
+        potentialSavingsFormatted: scoreData.formattedSpaceSaved,
+      },
+      unused: scoreData.sizedUnused.map((u) => ({
+        name: u.name,
+        isDev: u.isDev,
+        sizeBytes: u.bytes,
+        formattedSize: u.formattedSize,
+        reason: u.reason,
+      })),
+      probablyUnused: analysis.probablyUnused,
+      missing: analysis.missing,
+      usedCount: analysis.used.size,
+      skippedLargeFiles: analysis.skippedLargeFiles,
+      parseWarnings: analysis.parseWarnings,
+    };
+
+    console.log(JSON.stringify(output, null, 2));
+    const hasIssues = scoreData.sizedUnused.length > 0 || analysis.missing.length > 0 || analysis.probablyUnused.length > 0;
+    return hasIssues ? 1 : 0;
+  }
+
+  // 2. Score-only mode: `helpforbegs score`
+  if (options.scoreOnly) {
+    console.log(
+      styler.bold(
+        msgBundle.scoreLabel(scoreData.score, scoreData.letterGrade, scoreData.comment)
+      )
+    );
+    const hasIssues = scoreData.sizedUnused.length > 0 || analysis.missing.length > 0 || analysis.probablyUnused.length > 0;
+    return hasIssues ? 1 : 0;
+  }
+
+  // 3. Full human-friendly report:
+  console.log();
+  console.log(styler.cyan(msgBundle.scanHeader(analysis.filesReadCount)));
+
+  // Monorepo notice
+  if (analysis.isMonorepo) {
+    console.log(styler.dim(`  ${msgBundle.monorepoNotice(analysis.workspacesCount)}`));
+  }
+
+  // Missing node_modules warning
+  if (analysis.missingNodeModules) {
+    console.log(styler.yellow(`  ${msgBundle.missingNodeModulesNotice}`));
+  }
+
+  // Skipped large files
+  for (const skipped of analysis.skippedLargeFiles) {
+    const sizeMb = (skipped.size / (1024 * 1024)).toFixed(1);
+    console.log(styler.gray(`  ${msgBundle.largeFileSkipped(skipped.relativePath, sizeMb)}`));
+  }
+
+  // Parse warnings
+  for (const warning of analysis.parseWarnings) {
+    console.log(styler.gray(`  ${msgBundle.parseWarning(warning)}`));
+  }
+
+  console.log();
+
+  // Section: Unused packages
+  if (scoreData.sizedUnused.length > 0) {
+    console.log(styler.red(styler.bold(msgBundle.unusedHeader(scoreData.sizedUnused.length))));
+    for (const item of scoreData.sizedUnused) {
+      const sizeTag = item.bytes > 0 ? styler.gray(`(${item.formattedSize})`.padEnd(10)) : ''.padEnd(10);
+      const pkgFormatted = styler.bold(item.name.padEnd(14));
+      const message = msgBundle.unusedItem(item.name, item.reason);
+      console.log(`   • ${pkgFormatted} ${sizeTag}  ${message}`);
+    }
+    console.log();
+  }
+
+  // Section: Probably unused
+  if (analysis.probablyUnused.length > 0) {
+    console.log(styler.yellow(styler.bold(msgBundle.probablyHeader(analysis.probablyUnused.length))));
+    for (const item of analysis.probablyUnused) {
+      const pkgFormatted = styler.bold(item.name.padEnd(14));
+      const message = msgBundle.probablyItem(item.name, item.reason);
+      console.log(`   • ${pkgFormatted}  ${message}`);
+    }
+    console.log();
+  }
+
+  // Section: Missing packages
+  if (analysis.missing.length > 0) {
+    console.log(styler.red(styler.bold(msgBundle.missingHeader(analysis.missing.length))));
+    for (const item of analysis.missing) {
+      const pkgFormatted = styler.bold(item.name.padEnd(14));
+      const firstLoc = item.locations[0] || { file: 'unknown', line: 1 };
+      const message = msgBundle.missingItem(item.name, firstLoc);
+      console.log(`   • ${pkgFormatted}  ${message}`);
+    }
+    console.log();
+  }
+
+  // Section: Used packages count
+  if (analysis.used.size > 0) {
+    console.log(styler.green(msgBundle.usedHeader(analysis.used.size)));
+    console.log();
+  }
+
+  // Section: Health Score & Potential Disk Space Saved
+  console.log(styler.bold(msgBundle.scoreLabel(scoreData.score, scoreData.letterGrade, scoreData.comment)));
+  if (scoreData.totalBytesSaved > 0) {
+    console.log(styler.cyan(msgBundle.spaceSaved(scoreData.formattedSpaceSaved)));
+  }
+
+  console.log();
+
+  // Recommendations
+  if (scoreData.sizedUnused.length > 0) {
+    console.log(styler.dim(msgBundle.runRemoveTip));
+  } else if (analysis.missing.length === 0 && analysis.probablyUnused.length === 0) {
+    console.log(styler.green(msgBundle.cleanAllGood));
+  }
+
+  console.log();
+
+  // Exit code: 0 if clean, 1 if any unused, missing, or probablyUnused items exist
+  const hasIssues = scoreData.sizedUnused.length > 0 || analysis.missing.length > 0 || analysis.probablyUnused.length > 0;
+  return hasIssues ? 1 : 0;
+}
+
+module.exports = {
+  reportResults,
+  createStyler,
+};

package/src/safeList.js

@@ -0,0 +1,91 @@
+// src/safeList.js
+// WHY: Many essential development packages are run directly from the command line,
+// loaded via CLI hooks, or invoked by build systems, so they never appear in `require()` or `import`
+// inside source code. Flagging them as "unused" would confuse beginners and break their builds.
+// Keeping this list in a dedicated, clean file makes it easy to maintain and expand.
+
+/**
+ * Built-in safe-list of popular development tools, linters, transpilers,
+ * test frameworks, and CLI helpers.
+ */
+const SAFE_LIST = new Set([
+  // Compilers & Language Tools
+  'typescript',
+  'ts-node',
+  'tsx',
+  'tslib',
+  '@babel/core',
+  '@babel/cli',
+  '@babel/preset-env',
+  '@babel/preset-react',
+  '@babel/preset-typescript',
+
+  // Linters & Formatters
+  'eslint',
+  'prettier',
+  'lint-staged',
+  'husky',
+  'commitlint',
+  '@commitlint/cli',
+  '@commitlint/config-conventional',
+
+  // Bundlers & Build Tools
+  'webpack',
+  'webpack-cli',
+  'webpack-dev-server',
+  'vite',
+  'esbuild',
+  'rollup',
+  'parcel',
+  'turbo',
+
+  // Testing Frameworks & Runners
+  'jest',
+  'vitest',
+  'mocha',
+  'chai',
+  'supertest',
+  'c8',
+  'nyc',
+  'cypress',
+  'playwright',
+
+  // CLI Utilities & Task Runners
+  'nodemon',
+  'pm2',
+  'rimraf',
+  'concurrently',
+  'npm-run-all',
+  'cross-env',
+  'shx',
+  'dotenv-cli',
+  'wait-on',
+  'serve',
+
+  // Styling & CSS Processors (invoked by PostCSS/Tailwind CLI or build tools)
+  'postcss',
+  'postcss-cli',
+  'autoprefixer',
+  'tailwindcss',
+
+  // Documentation & Deployment
+  'typedoc',
+  'jsdoc',
+  'gh-pages',
+]);
+
+/**
+ * Checks if a given package name is in our built-in tooling safe-list.
+ *
+ * @param {string} packageName
+ * @returns {boolean}
+ */
+function isSafeListed(packageName) {
+  if (!packageName) return false;
+  return SAFE_LIST.has(packageName.toLowerCase());
+}
+
+module.exports = {
+  SAFE_LIST,
+  isSafeListed,
+};

package/src/scorer.js

@@ -0,0 +1,150 @@
+// src/scorer.js
+// WHY: Numbers and grades give beginners immediate, intuitive feedback.
+// Showing how much disk space can be saved (e.g. "Free about 5.6 MB")
+// turns abstract dependency cleanup into a tangible, rewarding achievement.
+
+const fs = require('fs');
+const path = require('path');
+const { NORMAL_MESSAGES, ROAST_MESSAGES } = require('./messages');
+
+/**
+ * Recursively calculates the byte size of a folder on disk.
+ *
+ * @param {string} dirPath
+ * @returns {number} Size in bytes
+ */
+function getDirectorySize(dirPath) {
+  let totalBytes = 0;
+
+  if (!fs.existsSync(dirPath)) {
+    return 0;
+  }
+
+  try {
+    const stats = fs.statSync(dirPath);
+    if (!stats.isDirectory()) {
+      return stats.size;
+    }
+
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dirPath, entry.name);
+      try {
+        if (entry.isDirectory()) {
+          totalBytes += getDirectorySize(fullPath);
+        } else if (entry.isFile()) {
+          const fileStat = fs.statSync(fullPath);
+          totalBytes += fileStat.size;
+        }
+      } catch {
+        // Skip unreadable files or broken symlinks
+      }
+    }
+  } catch {
+    return 0;
+  }
+
+  return totalBytes;
+}
+
+/**
+ * Formats a byte number into a clean, human-readable string (KB or MB).
+ *
+ * @param {number} bytes
+ * @returns {string} e.g. "1.4 MB" or "320 KB"
+ */
+function formatBytes(bytes) {
+  if (bytes <= 0) return '0 KB';
+  const kb = bytes / 1024;
+  if (kb < 1000) {
+    return `${Math.round(kb)} KB`;
+  }
+  const mb = kb / 1024;
+  return `${mb.toFixed(1)} MB`;
+}
+
+/**
+ * Measures the install size of a package inside node_modules.
+ *
+ * @param {string} projectDir
+ * @param {string} pkgName
+ * @returns {number}
+ */
+function getPackageInstallSize(projectDir, pkgName) {
+  const pkgPath = path.join(projectDir, 'node_modules', ...pkgName.split('/'));
+  return getDirectorySize(pkgPath);
+}
+
+/**
+ * Calculates health score, letter grade, and disk savings for an analyzed project.
+ *
+ * @param {object} analysis - Result from analyzer.analyzeProject
+ * @param {object} [options]
+ * @param {boolean} [options.roast=false]
+ * @returns {object} Score and savings breakdown
+ */
+function calculateScoreAndSavings(analysis, options = {}) {
+  const isRoast = Boolean(options.roast);
+  const msgBundle = isRoast ? ROAST_MESSAGES : NORMAL_MESSAGES;
+
+  const unusedCount = analysis.unused.length;
+  const missingCount = analysis.missing.length;
+  const probablyCount = analysis.probablyUnused.length;
+
+  // Score deductions:
+  // - Missing package: -15 (severe: app will crash at runtime)
+  // - Unused package: -10 (wasted bloat and install time)
+  // - Probably unused: -5 (minor uncertainty)
+  let rawScore = 100 - (missingCount * 15) - (unusedCount * 10) - (probablyCount * 5);
+  if (rawScore < 0) rawScore = 0;
+  if (rawScore > 100) rawScore = 100;
+
+  // Letter grades
+  let letterGrade = 'A+';
+  if (rawScore === 100) {
+    letterGrade = 'A+';
+  } else if (rawScore >= 90) {
+    letterGrade = 'A';
+  } else if (rawScore >= 80) {
+    letterGrade = 'B';
+  } else if (rawScore >= 70) {
+    letterGrade = 'C';
+  } else if (rawScore >= 60) {
+    letterGrade = 'D';
+  } else {
+    letterGrade = 'F';
+  }
+
+  const comment = msgBundle.gradeComments[letterGrade];
+
+  // Calculate size for each unused package
+  let totalBytesSaved = 0;
+  const sizedUnused = analysis.unused.map((item) => {
+    const bytes = getPackageInstallSize(analysis.projectDir, item.name);
+    totalBytesSaved += bytes;
+    return {
+      ...item,
+      bytes,
+      formattedSize: formatBytes(bytes),
+    };
+  });
+
+  // Sort unused packages by weight, biggest first!
+  sizedUnused.sort((a, b) => b.bytes - a.bytes);
+
+  return {
+    score: rawScore,
+    letterGrade,
+    comment,
+    totalBytesSaved,
+    formattedSpaceSaved: formatBytes(totalBytesSaved),
+    sizedUnused,
+  };
+}
+
+module.exports = {
+  calculateScoreAndSavings,
+  getDirectorySize,
+  formatBytes,
+  getPackageInstallSize,
+};