helpforbegs 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 helpforbegs 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

@@ -1,3 +1,147 @@
-# Temporary Holding Version
+# helpforbegs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Dependency help for beginners. No jargon, just plain English.**
+
+A gentle, accurate command-line assistant that scans your Node.js project and tells you:
+- Which packages you installed but never use.
+- Which packages you use in your code but forgot to install.
+- How much lighter and cleaner your project will be after cleaning up.
+
+Zero build steps. Zero TypeScript compilation needed. Safe by default.
+
+---
+
+## 📸 Demo Output
+
+```text
+🔍 Scanning your project... (42 files read)
+
+❌ Installed but never used (2)
+   • lodash   (1.4 MB)  You installed lodash but never used it.
+   • moment   (4.2 MB)  You installed moment but never used it.
+
+🤔 Probably unused (1)
+   • cors     Known development tool, but no active script or config reference was detected
+
+⚠️  Used but not installed (1)
+   • axios    Used in src/api.js:3 but missing from package.json.
+
+✅ 9 packages are used correctly
+
+📊 Health score: 78/100 (B) "Pretty tidy, a few dusty corners."
+💾 You could free about 5.6 MB.
+
+💡 Run `npx helpforbegs remove` to clean up safely.
+```
+
+---
+
+## ⚡ Quick Start
+
+You don't even need to install it permanently! Just run `npx` inside any Node.js project:
+
+```bash
+npx helpforbegs
+```
+
+Or install it globally if you want to use it anytime:
+
+```bash
+npm install -g helpforbegs
+helpforbegs
+```
+
+---
+
+## 🛠️ Commands
+
+| Command | What it does |
+|---|---|
+| `helpforbegs` or `helpforbegs scan` | Runs a complete project scan and prints the friendly health report. |
+| `helpforbegs remove` | Displays unused packages, prompts for confirmation (`y/N`), creates a timestamped backup of `package.json`, and safely uninstalls them. |
+| `helpforbegs why <package>` | Explains in plain English with exact file paths and line numbers where a package is used, or why it is considered unused. |
+| `helpforbegs score` | Prints only the project health score, letter grade, and summary comment (great for CI or quick checks). |
+
+---
+
+## 🚩 Flags & Options
+
+- `--path <dir>`: Scan another folder instead of the current directory (e.g. `npx helpforbegs --path ../my-express-app`).
+- `--dry-run`: Test `helpforbegs remove` safely without touching or deleting any files.
+- `--yes` or `-y`: Automatically confirm uninstallation in `remove` mode (required in CI or non-interactive terminals).
+- `--roast`: Enable humorous, playfully sarcastic feedback on your dependency habits.
+- `--json`: Output raw JSON data for CI pipelines, scripts, or custom dashboards.
+- `--no-color`: Disable all ANSI terminal colors (automatically respected if `NO_COLOR` is set or when output is redirected to a file).
+- `--help` (`-h`): Display the CLI help screen.
+- `--version` (`-v`): Show the installed version.
+- `--debug`: Display full technical stack traces on unexpected errors.
+
+---
+
+## 🧠 How Detection Works (In Plain English)
+
+Many tools use simple text searches or regular expressions to find package names, which often leads to mistakes. `helpforbegs` works differently:
+
+1. **Real AST Code Parsing**: We parse your JavaScript and TypeScript files using `@babel/parser`. This means we inspect the actual syntax tree of your code. We recognize:
+   - CommonJS `require('pkg')` and `require.resolve('pkg')`
+   - ES Module `import ... from 'pkg'`, `import 'pkg'`, and `export ... from 'pkg'`
+   - Dynamic `import('pkg')`
+   - TypeScript `import type { ... } from 'pkg'`
+2. **Package Name Normalization**: We strip subpaths (`lodash/fp` $\rightarrow$ `lodash`, `@babel/parser/lib` $\rightarrow$ `@babel/parser`), ignore relative paths (`./utils`), and filter out Node.js built-ins (`fs`, `path`, `node:test`, `crypto`).
+3. **Path Alias Intelligence**: We read path aliases in `tsconfig.json`, `jsconfig.json` (`compilerOptions.paths`), and `package.json` (`imports`). Imports like `@/components/Button` or `~/helpers` are recognized as internal aliases and are never flagged as missing npm packages.
+4. **Script Execution (`bin` commands)**: When you install CLI packages like `nodemon` or `rimraf`, you don't `require` them in code—you run them in `package.json` scripts. We read the `bin` field of packages in `node_modules` and match them against your script commands.
+5. **Config Files**: We check ESLint configs, Prettier plugins, Babel presets, Tailwind, PostCSS, and `tsconfig.json` compiler types.
+6. **Peer Dependencies**: If another installed package requires a dependency as a `peerDependency`, we will never mark it as unused.
+7. **Safe-List for Dev Tools**: Common development tools (`typescript`, `eslint`, `prettier`, `jest`, `nodemon`, `husky`, etc.) are recognized so you aren't pressured to delete your build pipeline.
+8. **Special Dotenv Rule**: `dotenv` is only flagged as unused if it is neither imported in code nor passed as a `-r dotenv/config` flag in scripts.
+
+---
+
+## 🛡️ Why You Can Trust the Results
+
+False positives are dangerous: telling a beginner to uninstall a required package could break their project.
+
+`helpforbegs` follows strict safety rules:
+1. **Never guess when unsure**: When confidence is not 100%, packages are marked `"Probably unused"` with an explanation to double-check, and `helpforbegs remove` will never delete them automatically.
+2. **Timestamped backups**: Before modifying `package.json`, a backup named `package.json.helpforbegs.<timestamp>.bak` is created.
+3. **Respects your package manager**: Automatically detects whether you use `npm`, `yarn`, `pnpm`, or `bun` by checking lockfiles, so your lockfile stays consistent.
+4. **Large files protection**: Skips files larger than 1 MB to prevent memory bloat, and informs you in the report.
+5. **Graceful syntax recovery**: If a file contains syntax errors that fail AST parsing, it falls back to a regex scanner and notes: `"Could not fully read src/x.js"`.
+
+---
+
+## 🙈 Ignoring Packages (`.helpforbegsignore`)
+
+If you have a package that is used in a way automated tools cannot see, create a `.helpforbegsignore` file in your project root:
+
+```text
+# .helpforbegsignore
+# Packages listed here will never be flagged as unused
+
+cors
+dotenv
+```
+
+---
+
+## ⚠️ Known Limitations
+
+1. **Dynamic require variables**: Expressions like `require(myVariableName)` cannot be statically analyzed because their value is only known while your app is running.
+2. **Shell scripts outside package.json**: Tools invoked exclusively inside custom `.sh` or `.bat` files outside `package.json` scripts won't be seen unless listed in `.helpforbegsignore`.
+3. **Code generated at runtime**: Dynamically evaluated code (e.g. `eval()` or code fetched over a network) cannot be scanned statically.
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome!
+1. Fork the repository.
+2. Clone your fork and run `npm install`.
+3. Run tests with `npm test`.
+4. Submit a Pull Request.
+
+---
+
+## 📄 License
+
+MIT © helpforbegs contributors

package/bin/cli.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+
+// bin/cli.js
+// WHY: This is the executable entry point when someone runs `helpforbegs`
+// or `npx helpforbegs` in their terminal.
+// It coordinates argument parsing, routing to commands, and clean exit codes.
+
+const path = require('path');
+const { parseArgs } = require('../src/args');
+const { analyzeProject } = require('../src/analyzer');
+const { calculateScoreAndSavings } = require('../src/scorer');
+const { reportResults } = require('../src/reporter');
+const { explainPackage } = require('../src/why');
+const { removeUnused } = require('../src/remover');
+const pkgInfo = require('../package.json');
+
+/**
+ * Prints user-friendly help documentation.
+ */
+function printHelp() {
+  console.log(`
+helpforbegs - ${pkgInfo.description}
+
+USAGE:
+  $ npx helpforbegs [command] [options]
+
+COMMANDS:
+  scan               (default) Scans your project and prints the health report
+  remove             Safely uninstalls unused packages after confirmation
+  why <package>      Explains exactly where a package is used, or why it is unused
+  score              Prints only the health score and letter grade
+
+FLAGS:
+  --path <dir>       Scan another directory (default: current directory)
+  --dry-run          Preview what \`remove\` would uninstall without changing files
+  --yes, -y          Confirm \`remove\` automatically (required in CI / non-TTY)
+  --roast            Funny, gently sarcastic commentary
+  --json             Output raw JSON data for scripts and CI
+  --no-color         Disable ANSI terminal colors
+  --help, -h         Show this help screen
+  --version, -v      Show the version of helpforbegs
+  --debug            Show technical stack traces on unexpected errors
+
+EXAMPLES:
+  $ npx helpforbegs
+  $ npx helpforbegs --roast
+  $ npx helpforbegs why lodash
+  $ npx helpforbegs remove --dry-run
+  $ npx helpforbegs --path ./my-app
+`);
+}
+
+async function main() {
+  const { command, targetPkg, flags } = parseArgs(process.argv.slice(2));
+
+  // 1. --help / -h
+  if (flags.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  // 2. --version / -v
+  if (flags.version) {
+    console.log(pkgInfo.version);
+    process.exit(0);
+  }
+
+  const targetDir = flags.targetDir;
+
+  try {
+    if (command === 'why') {
+      const exitCode = explainPackage(targetDir, targetPkg, flags);
+      process.exit(exitCode);
+    }
+
+    if (command === 'remove') {
+      const exitCode = await removeUnused(targetDir, flags);
+      process.exit(exitCode);
+    }
+
+    // Default: 'scan' or 'score'
+    const analysis = analyzeProject(targetDir);
+    const scoreData = calculateScoreAndSavings(analysis, { roast: flags.roast });
+
+    const exitCode = reportResults(analysis, scoreData, {
+      ...flags,
+      scoreOnly: command === 'score',
+    });
+
+    process.exit(exitCode);
+  } catch (err) {
+    // Exit code 2 for internal/input errors (no package.json, invalid JSON, etc.)
+    if (err.code === 'NO_PKG_JSON' || err.code === 'INVALID_PKG_JSON') {
+      console.error(`\n❌ ${err.message}\n`);
+      process.exit(2);
+    }
+
+    console.error(`\n❌ An unexpected error occurred: ${err.message}`);
+    if (flags.debug) {
+      console.error(err.stack);
+    } else {
+      console.error('   Run with `--debug` to view the full technical stack trace.\n');
+    }
+    process.exit(2);
+  }
+}
+
+main();

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "helpforbegs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Dependency help for beginners. No jargon, just plain English.",
+  "main": "src/analyzer.js",
+  "bin": {
+    "helpforbegs": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "test": "jest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/your-username/helpforbegs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/your-username/helpforbegs/issues"
+  },
+  "homepage": "https://github.com/your-username/helpforbegs#readme",
+  "keywords": [
+    "dependencies",
+    "unused",
+    "cleanup",
+    "depcheck",
+    "beginner",
+    "cli",
+    "package-json"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "Shriyan Kogta",
+  "license": "MIT",
+  "dependencies": {
+    "@babel/parser": "^7.24.0",
+    "chalk": "^4.1.2"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  }
+}

package/src/analyzer.js

@@ -0,0 +1,348 @@
+// src/analyzer.js
+// WHY: This is the brain of helpforbegs. It collects findings from all our scanners
+// (AST parser, config reader, scripts, bin mapper, peer dependencies, and safe-list)
+// and sorts every package into one of four clear verdict buckets:
+// 1. Used
+// 2. Unused (high confidence)
+// 3. Probably unused (tooling with uncertainty)
+// 4. Missing (imported in code but forgotten in package.json)
+
+const fs = require('fs');
+const path = require('path');
+const { findFiles } = require('./fileFinder');
+const { parseImports } = require('./astParser');
+const {
+  extractPathAliases,
+  readIgnoreFile,
+  collectPeerDependencies,
+  scanConfigFiles,
+  checkDotenvInScripts,
+} = require('./configReader');
+const { mapInstalledBins, findBinUsageInScripts } = require('./binMapper');
+const { isSafeListed } = require('./safeList');
+
+/**
+ * Resolves monorepo workspace directories if "workspaces" is defined in package.json.
+ *
+ * @param {string} projectDir
+ * @param {string[]|object} workspacesConfig
+ * @returns {string[]} List of absolute paths to workspace packages
+ */
+function resolveWorkspaces(projectDir, workspacesConfig) {
+  const patterns = Array.isArray(workspacesConfig)
+    ? workspacesConfig
+    : (workspacesConfig && Array.isArray(workspacesConfig.packages) ? workspacesConfig.packages : []);
+
+  const workspaceDirs = [];
+
+  for (const pattern of patterns) {
+    if (pattern.endsWith('/*')) {
+      // e.g. "packages/*"
+      const parentDir = path.join(projectDir, pattern.slice(0, -2));
+      if (fs.existsSync(parentDir)) {
+        try {
+          const entries = fs.readdirSync(parentDir, { withFileTypes: true });
+          for (const entry of entries) {
+            if (entry.isDirectory()) {
+              const subDir = path.join(parentDir, entry.name);
+              if (fs.existsSync(path.join(subDir, 'package.json'))) {
+                workspaceDirs.push(subDir);
+              }
+            }
+          }
+        } catch {
+          // Ignore directory read errors
+        }
+      }
+    } else {
+      // Direct directory path, e.g. "apps/web"
+      const directDir = path.join(projectDir, pattern);
+      if (fs.existsSync(path.join(directDir, 'package.json'))) {
+        workspaceDirs.push(directDir);
+      }
+    }
+  }
+
+  return workspaceDirs;
+}
+
+/**
+ * Main analysis function that scans a project folder and categorizes all dependencies.
+ *
+ * @param {string} projectDir - Absolute path to the project root
+ * @param {object} [options]
+ * @returns {object} Full analysis results
+ */
+function analyzeProject(projectDir, options = {}) {
+  const pkgJsonPath = path.join(projectDir, 'package.json');
+
+  // Verify that package.json exists
+  if (!fs.existsSync(pkgJsonPath)) {
+    const error = new Error(`No package.json found in ${projectDir}. Make sure you are in a Node.js project folder.`);
+    error.code = 'NO_PKG_JSON';
+    throw error;
+  }
+
+  // Parse package.json
+  let rootPkgJson;
+  try {
+    const content = fs.readFileSync(pkgJsonPath, 'utf8');
+    rootPkgJson = JSON.parse(content);
+  } catch (err) {
+    const error = new Error(`Could not read package.json in ${projectDir}. It contains invalid JSON syntax.`);
+    error.code = 'INVALID_PKG_JSON';
+    throw error;
+  }
+
+  // Check for monorepo workspaces
+  const workspaceDirs = rootPkgJson.workspaces ? resolveWorkspaces(projectDir, rootPkgJson.workspaces) : [];
+  const isMonorepo = workspaceDirs.length > 0;
+
+  // Aggregate all declared dependencies across root and workspaces
+  const declaredDeps = new Map(); // pkgName -> { isDev: boolean, definedIn: string }
+  const workspacePkgNames = new Set();
+
+  function registerDeps(pkgData, sourcePath) {
+    if (pkgData.name) {
+      workspacePkgNames.add(pkgData.name);
+    }
+    const regularDeps = pkgData.dependencies || {};
+    const devDeps = pkgData.devDependencies || {};
+
+    for (const dep of Object.keys(regularDeps)) {
+      if (!declaredDeps.has(dep)) {
+        declaredDeps.set(dep, { isDev: false, definedIn: sourcePath });
+      }
+    }
+    for (const dep of Object.keys(devDeps)) {
+      // If already in dependencies, regular dependency takes precedence
+      if (!declaredDeps.has(dep)) {
+        declaredDeps.set(dep, { isDev: true, definedIn: sourcePath });
+      }
+    }
+  }
+
+  registerDeps(rootPkgJson, 'package.json');
+
+  for (const wsDir of workspaceDirs) {
+    try {
+      const wsPkgJson = JSON.parse(fs.readFileSync(path.join(wsDir, 'package.json'), 'utf8'));
+      registerDeps(wsPkgJson, path.relative(projectDir, wsDir));
+    } catch {
+      // Ignore unparseable workspace package.json
+    }
+  }
+
+  // Discover files to scan
+  const { files, skippedLargeFiles } = findFiles(projectDir);
+  const knownAliases = extractPathAliases(projectDir, rootPkgJson);
+  const userIgnored = readIgnoreFile(projectDir);
+  const peerDeps = collectPeerDependencies(projectDir);
+  const { usedPackages: configPackages, hasTsConfig } = scanConfigFiles(projectDir);
+  const { binToPkg, missingNodeModules } = mapInstalledBins(projectDir);
+
+  // Collect scripts from root and workspaces
+  const allScripts = { ...(rootPkgJson.scripts || {}) };
+  for (const wsDir of workspaceDirs) {
+    try {
+      const wsPkg = JSON.parse(fs.readFileSync(path.join(wsDir, 'package.json'), 'utf8'));
+      Object.assign(allScripts, wsPkg.scripts || {});
+    } catch {
+      // Ignore
+    }
+  }
+
+  const binUsageInScripts = findBinUsageInScripts(allScripts, binToPkg);
+  const dotenvInScripts = checkDotenvInScripts(allScripts);
+
+  // Track code imports: pkgName -> Array<{ file: string, line: number, isTypeOnly: boolean }>
+  const codeImports = new Map();
+  const parseWarnings = [];
+  let hasTypeScriptFiles = false;
+
+  for (const fileObj of files) {
+    if (fileObj.ext === '.ts' || fileObj.ext === '.tsx') {
+      hasTypeScriptFiles = true;
+    }
+
+    try {
+      const content = fs.readFileSync(fileObj.fullPath, 'utf8');
+      const { imports, warning } = parseImports(content, fileObj.fullPath, { knownAliases });
+
+      if (warning) {
+        parseWarnings.push(warning);
+      }
+
+      for (const item of imports) {
+        if (!codeImports.has(item.packageName)) {
+          codeImports.set(item.packageName, []);
+        }
+        codeImports.get(item.packageName).push({
+          file: fileObj.relativePath,
+          line: item.line,
+          isTypeOnly: item.isTypeOnly,
+        });
+      }
+    } catch {
+      parseWarnings.push(`Could not read file: ${fileObj.relativePath}`);
+    }
+  }
+
+  // Build verdicts:
+  const used = new Map(); // pkgName -> { locations: [], reasons: [] }
+  const unused = [];
+  const probablyUnused = [];
+  const missing = [];
+
+  // Helper to mark a package as used with a specific reason
+  function markUsed(pkgName, reason, locations = []) {
+    if (!used.has(pkgName)) {
+      used.set(pkgName, { locations: [], reasons: [] });
+    }
+    const entry = used.get(pkgName);
+    if (reason && !entry.reasons.includes(reason)) {
+      entry.reasons.push(reason);
+    }
+    if (locations && locations.length > 0) {
+      entry.locations.push(...locations);
+    }
+  }
+
+  // 1. Evaluate all declared packages
+  for (const [pkgName, meta] of declaredDeps.entries()) {
+    let isFound = false;
+
+    // a) Found in user .helpforbegsignore
+    if (userIgnored.has(pkgName)) {
+      markUsed(pkgName, 'Listed in .helpforbegsignore');
+      continue;
+    }
+
+    // b) Found in source code imports
+    if (codeImports.has(pkgName)) {
+      markUsed(pkgName, 'Imported in source code', codeImports.get(pkgName));
+      isFound = true;
+    }
+
+    // c) Found in package.json scripts (directly or via bin name)
+    if (binUsageInScripts.has(pkgName)) {
+      const uses = binUsageInScripts.get(pkgName);
+      const scriptsList = uses.map((u) => `"${u.scriptName}"`).join(', ');
+      markUsed(pkgName, `Executed in package.json scripts: ${scriptsList}`);
+      isFound = true;
+    } else {
+      // Also check if the raw package name itself appears as a command in scripts
+      const escaped = pkgName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const scriptRegex = new RegExp(`(^|[;&|\\s])${escaped}(\\s|$|[;&|])`);
+      for (const [sName, sCmd] of Object.entries(allScripts)) {
+        if (typeof sCmd === 'string' && scriptRegex.test(sCmd)) {
+          markUsed(pkgName, `Referenced in script "${sName}"`);
+          isFound = true;
+          break;
+        }
+      }
+    }
+
+    // d) Found in config files (ESLint, Prettier, Babel, tsconfig)
+    if (configPackages.has(pkgName)) {
+      markUsed(pkgName, 'Referenced in project configuration files');
+      isFound = true;
+    }
+
+    // e) Declared as a peerDependency by an installed package
+    if (peerDeps.has(pkgName)) {
+      markUsed(pkgName, 'Required as a peer dependency by another installed package');
+      isFound = true;
+    }
+
+    // f) Handling @types/xyz packages
+    if (pkgName.startsWith('@types/')) {
+      const basePkg = pkgName.slice('@types/'.length);
+
+      // If the base package is used in code or declared
+      if (codeImports.has(basePkg) || declaredDeps.has(basePkg)) {
+        markUsed(pkgName, `TypeScript definitions for used package "${basePkg}"`);
+        isFound = true;
+      }
+      // Special rule: @types/node is used if project has any TS files or tsconfig.json
+      else if (basePkg === 'node' && (hasTypeScriptFiles || hasTsConfig)) {
+        markUsed(pkgName, 'TypeScript type definitions for Node.js runtime');
+        isFound = true;
+      }
+    }
+
+    // g) Special dotenv check:
+    if (pkgName === 'dotenv') {
+      if (isFound || dotenvInScripts) {
+        markUsed(pkgName, dotenvInScripts ? 'Loaded via -r dotenv/config in scripts' : 'Imported in source code');
+        continue;
+      } else {
+        unused.push({
+          name: pkgName,
+          isDev: meta.isDev,
+          reason: 'Neither imported in code nor referenced with -r dotenv/config in scripts',
+        });
+        continue;
+      }
+    }
+
+    // If already confirmed as used, we're done with this package
+    if (isFound) {
+      continue;
+    }
+
+    // h) Built-in safe-list check:
+    // If a package is in the safe-list but wasn't found in scripts or configs,
+    // we mark it as "probably unused" so the user is encouraged to double check
+    // rather than accidentally breaking their tooling.
+    if (isSafeListed(pkgName)) {
+      probablyUnused.push({
+        name: pkgName,
+        isDev: meta.isDev,
+        reason: 'Known development tool, but no active script or config reference was detected',
+      });
+      continue;
+    }
+
+    // Otherwise, high confidence UNUSED
+    unused.push({
+      name: pkgName,
+      isDev: meta.isDev,
+      reason: `Installed in ${meta.isDev ? 'devDependencies' : 'dependencies'} but never imported or referenced`,
+    });
+  }
+
+  // 2. Detect missing packages (imported in code but not in package.json)
+  for (const [pkgName, locations] of codeImports.entries()) {
+    if (
+      !declaredDeps.has(pkgName) &&
+      !workspacePkgNames.has(pkgName) &&
+      !userIgnored.has(pkgName)
+    ) {
+      missing.push({
+        name: pkgName,
+        locations,
+      });
+    }
+  }
+
+  return {
+    projectDir,
+    rootPkgJson,
+    isMonorepo,
+    workspacesCount: workspaceDirs.length,
+    missingNodeModules,
+    filesReadCount: files.length,
+    skippedLargeFiles,
+    parseWarnings,
+    used,
+    unused,
+    probablyUnused,
+    missing,
+  };
+}
+
+module.exports = {
+  analyzeProject,
+  resolveWorkspaces,
+};