reqscan 1.0.0

package/README.md

@@ -0,0 +1,238 @@
+# reqscan — Dependency Manager for Node.js
+
+**reqscan** is a powerful CLI tool that scans your Node.js project, detects missing dependencies, and helps you manage them with simple commands. Zero external dependencies.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/node/v/reqscan.svg)](https://nodejs.org)
+
+---
+
+## ✨ Features
+
+- 🔍 **Check** — Find imported packages missing from `package.json`
+- 📦 **Install** — Install all missing packages at once
+- 🧹 **Clean** — Remove unused/undeclared packages
+- 🔧 **Fix** — Install missing + clean unused in one shot
+- 🎯 **Audit** — Full dependency health report with score
+- 📋 **List** — Show every dependency with its status
+- 🚫 **Smart filtering** — Ignores built-ins, `node_modules`, relative imports
+- 📁 **Multi-language** — Supports `.js`, `.ts`, `.jsx`, `.tsx`, `.mjs`, `.cjs`
+- 🎨 **Beautiful output** — Color-coded terminal UI
+- ⚡ **Zero dependencies** — Lightweight and fast
+- 🔧 **Programmatic API** — Use it in your own tools
+
+---
+
+## 📦 Installation
+
+### Global Installation (Recommended)
+
+```bash
+npm install -g reqscan
+```
+
+### Run without installing (npx)
+
+```bash
+npx reqscan check
+npx reqscan install
+```
+
+### Local Installation (for CI/CD)
+
+```bash
+npm install --save-dev reqscan
+```
+
+Then add to your `package.json` scripts:
+```json
+{
+  "scripts": {
+    "deps:check": "reqscan check",
+    "deps:fix":   "reqscan fix"
+  }
+}
+```
+
+---
+
+## 🚀 Usage
+
+```bash
+# Scan current directory
+reqscan check
+
+# Scan specific project
+reqscan check /path/to/project
+
+# Install all missing dependencies
+reqscan install
+
+# Remove unused dependencies
+reqscan clean
+
+# Fix everything (install missing + remove unused)
+reqscan fix
+
+# Show full project health report
+reqscan audit
+
+# Show all packages with their status
+reqscan list
+```
+
+---
+
+## 📋 Command Reference
+
+| Command | Description |
+|---------|-------------|
+| `check [dir]` | List missing, present, and unused packages |
+| `install` | Install all missing packages found by `check` |
+| `clean` | Remove packages declared but never imported |
+| `fix` | Run `install` + `clean` in one command |
+| `audit` | Full dependency health report with score |
+| `list` | Show all dependencies with status |
+
+---
+
+## 📤 Example Outputs
+
+### `reqscan check`
+
+```
+📦 Project: my-app
+──────────────────────────────────────────────────
+Summary
+  Total imports found   : 9
+  Declared in pkg.json  : 4
+  Already installed     : 3
+  Missing (not declared): 2
+
+❌ Missing Packages (not in package.json)
+──────────────────────────────────────────────────
+  ✗ axios
+  ✗ uuid
+
+💡 Run this to install all missing packages:
+   npm install axios uuid
+
+✅ Already Declared Packages
+──────────────────────────────────────────────────
+  ✓ express    ^4.18.0
+  ✓ mongoose   ^7.0.0
+  ✓ dotenv     ^16.0.0
+
+⚠️  Declared but NOT imported in source (possibly unused)
+──────────────────────────────────────────────────
+  ~ jest
+```
+
+### `reqscan audit`
+
+```
+🏥 Dependency Health Report
+──────────────────────────────────────────────────
+  Health Score        : 75%
+  Files Scanned       : 12
+  Total Imports       : 8
+  Declared            : 6
+  ✓ Present           : 6
+  ✗ Missing           : 2
+  ~ Unused declared   : 1
+
+📋 package.json Breakdown
+──────────────────────────────────────────────────
+  dependencies         : 4
+  devDependencies      : 2
+  peerDependencies     : 0
+  optionalDependencies : 0
+
+💡 Recommendations
+──────────────────────────────────────────────────
+  → Run reqscan install to install 2 missing package(s).
+  → Run reqscan clean   to remove 1 unused package(s).
+```
+
+### `reqscan list`
+
+```
+📋 All Dependencies with Status
+──────────────────────────────────────────────────
+  ✓ axios                          ^1.6.0       present
+  ✗ date-fns                                    missing
+  ✓ express                        ^4.18.0      present
+  ~ jest                           ^29.0.0      unused
+
+Legend: ✓ present  ✗ missing  ~ declared but unused
+```
+
+---
+
+## 🛠️ How It Works
+
+1. **Scans** all `.js/.ts/.jsx/.tsx/.mjs/.cjs` files (skips `node_modules`, `dist`, `.next`, etc.)
+2. **Extracts** package names from all import styles:
+   - `require('pkg')`
+   - `import x from 'pkg'`
+   - `import('pkg')`
+   - `require.resolve('pkg')`
+   - `export { x } from 'pkg'`
+3. **Filters out** Node.js built-ins (`fs`, `path`, `http`, `node:*`, etc.)
+4. **Compares** against `package.json` (all dependency types)
+5. **Reports** and optionally acts on findings
+
+---
+
+## 🔧 Programmatic API
+
+```javascript
+const { scanProject } = require('reqscan');
+
+const result = await scanProject('/path/to/project');
+
+console.log(result.missing);      // ['axios', 'uuid']
+console.log(result.present);      // ['express', 'mongoose']
+console.log(result.unused);       // ['jest']
+console.log(result.allImports);   // all detected package names
+console.log(result.scannedFiles); // list of files scanned
+```
+
+### Return Value
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `projectName` | `string` | Name from package.json |
+| `allImports` | `string[]` | All unique packages found in source |
+| `declared` | `string[]` | All packages in package.json |
+| `missing` | `string[]` | Imported but not declared |
+| `present` | `string[]` | Imported AND declared |
+| `unused` | `string[]` | Declared but never imported |
+| `scannedFiles` | `string[]` | All files that were scanned |
+| `packageJson` | `object\|null` | Parsed package.json content |
+
+---
+
+## 🧪 Running Tests
+
+```bash
+node test/test.js
+```
+
+---
+
+## 🗺️ Roadmap
+
+- [ ] `reqscan outdated` — Check for newer package versions
+- [ ] `reqscan upgrade` — Update all outdated packages
+- [ ] `--save-dev` flag for install command
+- [ ] `--dry-run` flag for previewing changes
+- [ ] Configuration file (`.reqscanrc`)
+- [ ] Monorepo/workspace support
+- [ ] JSON output mode (`--json` flag)
+
+---
+
+## 📄 License
+
+MIT

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "reqscan",
+  "version": "1.0.0",
+  "description": "Dependency Manager for Node.js — scan, install, clean, and audit your project dependencies",
+  "main": "src/scanner.js",
+  "bin": {
+    "depm": "./src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node test/test.js"
+  },
+  "keywords": [
+    "npm",
+    "dependencies",
+    "missing",
+    "packages",
+    "audit",
+    "scanner",
+    "cli",
+    "depm"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}

package/src/colors.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const c = {
+  reset  : '\x1b[0m',
+  bold   : '\x1b[1m',
+  dim    : '\x1b[2m',
+  red    : '\x1b[31m',
+  green  : '\x1b[32m',
+  yellow : '\x1b[33m',
+  cyan   : '\x1b[36m',
+  white  : '\x1b[37m',
+};
+
+const paint = (color, text) => `${color}${text}${c.reset}`;
+
+module.exports = {
+  ...c,
+  bold   : (t) => paint(c.bold,   t),
+  dim    : (t) => paint(c.dim,    t),
+  red    : (t) => paint(c.red,    t),
+  green  : (t) => paint(c.green,  t),
+  yellow : (t) => paint(c.yellow, t),
+  cyan   : (t) => paint(c.cyan,   t),
+  white  : (t) => paint(c.white,  t),
+  boldCyan   : (t) => `${c.bold}${c.cyan}${t}${c.reset}`,
+  boldGreen  : (t) => `${c.bold}${c.green}${t}${c.reset}`,
+  boldRed    : (t) => `${c.bold}${c.red}${t}${c.reset}`,
+  boldYellow : (t) => `${c.bold}${c.yellow}${t}${c.reset}`,
+  LINE : '─'.repeat(50),
+};

package/src/commands.js

@@ -0,0 +1,290 @@
+'use strict';
+
+const { execSync }   = require('child_process');
+const readline       = require('readline');
+const { scanProject} = require('./scanner');
+const col            = require('./colors');
+
+// ─── Shared helpers ───────────────────────────────────────────────────────────
+
+function header(projectName) {
+  console.log();
+  console.log(col.boldCyan(`📦 Project: ${projectName}`));
+  console.log(col.dim(col.LINE));
+}
+
+function prompt(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (ans) => { rl.close(); resolve(ans.trim()); });
+  });
+}
+
+function runNpm(args, cwd) {
+  try {
+    execSync(`npm ${args}`, { cwd, stdio: 'inherit' });
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+// ─── check ────────────────────────────────────────────────────────────────────
+
+async function cmdCheck(targetDir) {
+  const r = await scanProject(targetDir);
+  header(r.projectName);
+
+  // Summary
+  console.log(col.bold('Summary'));
+  console.log(`  Total imports found   : ${col.bold(String(r.allImports.length))}`);
+  console.log(`  Declared in pkg.json  : ${col.bold(String(r.declared.length))}`);
+  console.log(`  Already installed     : ${col.boldGreen(String(r.present.length))}`);
+  console.log(`  Missing (not declared): ${r.missing.length > 0 ? col.boldRed(String(r.missing.length)) : col.boldGreen('0')}`);
+  console.log();
+
+  // Missing
+  if (r.missing.length > 0) {
+    console.log(col.boldRed('❌ Missing Packages (not in package.json)'));
+    console.log(col.dim(col.LINE));
+    r.missing.forEach(p => console.log(`  ${col.red('✗')} ${p}`));
+    console.log();
+    console.log(col.boldYellow('💡 Run this to install all missing packages:'));
+    console.log(col.boldCyan(`   npm install ${r.missing.join(' ')}`));
+    console.log();
+    if (r.missing.length > 1) {
+      console.log(col.dim('Or install one by one:'));
+      r.missing.forEach(p => console.log(col.dim(`  npm install ${p}`)));
+      console.log();
+    }
+  } else {
+    console.log(col.boldGreen('✅ All imported packages are declared in package.json!'));
+    console.log();
+  }
+
+  // Present
+  if (r.present.length > 0) {
+    console.log(col.boldGreen('✅ Already Declared Packages'));
+    console.log(col.dim(col.LINE));
+    r.present.forEach(p => {
+      const ver =
+        r.packageJson?.dependencies?.[p] ||
+        r.packageJson?.devDependencies?.[p] ||
+        r.packageJson?.peerDependencies?.[p] ||
+        r.packageJson?.optionalDependencies?.[p] || '';
+      console.log(`  ${col.green('✓')} ${p} ${col.dim(ver)}`);
+    });
+    console.log();
+  }
+
+  // Unused
+  if (r.unused.length > 0) {
+    console.log(col.boldYellow('⚠️  Declared but NOT imported in source (possibly unused)'));
+    console.log(col.dim(col.LINE));
+    r.unused.forEach(p => console.log(`  ${col.yellow('~')} ${p}`));
+    console.log();
+    console.log(col.dim('Tip: Run `deptrack clean` to remove unused packages.'));
+    console.log();
+  }
+
+  console.log(col.dim(col.LINE));
+  console.log(col.dim('Scan complete.'));
+  console.log();
+
+  return r;
+}
+
+// ─── install ──────────────────────────────────────────────────────────────────
+
+async function cmdInstall(targetDir) {
+  console.log();
+  console.log(col.boldCyan('📦 Installing missing dependencies...'));
+  console.log();
+
+  const r = await scanProject(targetDir);
+
+  if (r.missing.length === 0) {
+    console.log(col.boldGreen('✅ No missing packages found. Everything is already declared!'));
+    console.log();
+    return;
+  }
+
+  console.log(`Found ${col.boldRed(String(r.missing.length))} missing package(s):`);
+  r.missing.forEach(p => console.log(`  • ${p}`));
+  console.log();
+  console.log('Installing... ⚙️');
+  console.log();
+
+  const ok = runNpm(`install ${r.missing.join(' ')}`, targetDir);
+
+  if (ok) {
+    console.log();
+    console.log(col.boldGreen('✔ Successfully installed:'));
+    r.missing.forEach(p => console.log(`  • ${col.green(p)}`));
+    console.log();
+    console.log(col.dim('💡 Run `deptrack check` again to verify all packages are declared.'));
+  } else {
+    console.log(col.boldRed('❌ Installation failed. Please check your npm setup and try again.'));
+  }
+  console.log();
+}
+
+// ─── clean ────────────────────────────────────────────────────────────────────
+
+async function cmdClean(targetDir, { force = false } = {}) {
+  console.log();
+  console.log(col.boldCyan('🧹 Scanning for unused dependencies...'));
+  console.log();
+
+  const r = await scanProject(targetDir);
+
+  if (r.unused.length === 0) {
+    console.log(col.boldGreen('✅ No unused packages found. Your package.json is clean!'));
+    console.log();
+    return;
+  }
+
+  console.log(`Found ${col.boldYellow(String(r.unused.length))} unused package(s):`);
+  r.unused.forEach(p => {
+    const inDev = r.packageJson?.devDependencies?.[p];
+    const kind  = inDev ? 'devDependencies' : 'dependencies';
+    console.log(`  • ${p} ${col.dim(`(${kind})`)}`);
+  });
+  console.log();
+
+  let confirm = 'y';
+  if (!force) {
+    confirm = await prompt('Remove these packages? [Y/n] ');
+  }
+
+  if (confirm === '' || confirm.toLowerCase() === 'y') {
+    const depsBefore    = Object.keys(r.packageJson?.dependencies    || {}).length;
+    const devDepsBefore = Object.keys(r.packageJson?.devDependencies || {}).length;
+
+    console.log();
+    const ok = runNpm(`uninstall ${r.unused.join(' ')}`, targetDir);
+
+    if (ok) {
+      // Re-read to get updated counts
+      const { readPackageJson } = require('./scanner');
+      const updated = readPackageJson(targetDir);
+      const depsAfter    = Object.keys(updated?.dependencies    || {}).length;
+      const devDepsAfter = Object.keys(updated?.devDependencies || {}).length;
+
+      console.log();
+      console.log(col.boldGreen(`✔ Successfully removed ${r.unused.length} package(s)`));
+      console.log();
+      console.log(col.bold('📊 After cleanup:'));
+      console.log(`  Dependencies    : ${depsBefore} → ${depsAfter}`);
+      console.log(`  devDependencies : ${devDepsBefore} → ${devDepsAfter}`);
+    } else {
+      console.log(col.boldRed('❌ Removal failed. Please check your npm setup.'));
+    }
+  } else {
+    console.log(col.dim('Aborted. No changes made.'));
+  }
+  console.log();
+}
+
+// ─── fix ──────────────────────────────────────────────────────────────────────
+
+async function cmdFix(targetDir) {
+  console.log();
+  console.log(col.boldCyan('🔧 Running deptrack fix (install missing + clean unused)...'));
+  console.log(col.dim(col.LINE));
+  await cmdInstall(targetDir);
+  console.log(col.dim(col.LINE));
+  await cmdClean(targetDir, { force: false });
+}
+
+// ─── audit ────────────────────────────────────────────────────────────────────
+
+async function cmdAudit(targetDir) {
+  const r = await scanProject(targetDir);
+  header(r.projectName);
+
+  // Health score
+  const total   = r.allImports.length || 1;
+  const score   = Math.round((r.present.length / total) * 100);
+  const scoreColor = score === 100 ? col.boldGreen : score >= 70 ? col.boldYellow : col.boldRed;
+
+  console.log(col.bold('🏥 Dependency Health Report'));
+  console.log(col.dim(col.LINE));
+  console.log(`  Health Score        : ${scoreColor(`${score}%`)}`);
+  console.log(`  Files Scanned       : ${col.bold(String(r.scannedFiles.length))}`);
+  console.log(`  Total Imports       : ${col.bold(String(r.allImports.length))}`);
+  console.log(`  Declared            : ${col.bold(String(r.declared.length))}`);
+  console.log(`  ✓ Present           : ${col.boldGreen(String(r.present.length))}`);
+  console.log(`  ✗ Missing           : ${r.missing.length > 0 ? col.boldRed(String(r.missing.length)) : col.boldGreen('0')}`);
+  console.log(`  ~ Unused declared   : ${r.unused.length  > 0 ? col.boldYellow(String(r.unused.length)) : col.boldGreen('0')}`);
+  console.log();
+
+  // Dependency breakdown
+  const deps    = r.packageJson?.dependencies        || {};
+  const devDeps = r.packageJson?.devDependencies     || {};
+  const peer    = r.packageJson?.peerDependencies    || {};
+  const opt     = r.packageJson?.optionalDependencies|| {};
+
+  console.log(col.bold('📋 package.json Breakdown'));
+  console.log(col.dim(col.LINE));
+  console.log(`  dependencies         : ${Object.keys(deps).length}`);
+  console.log(`  devDependencies      : ${Object.keys(devDeps).length}`);
+  console.log(`  peerDependencies     : ${Object.keys(peer).length}`);
+  console.log(`  optionalDependencies : ${Object.keys(opt).length}`);
+  console.log();
+
+  // Recommendations
+  const recs = [];
+  if (r.missing.length > 0) recs.push(`Run ${col.cyan('deptrack install')} to install ${r.missing.length} missing package(s).`);
+  if (r.unused.length  > 0) recs.push(`Run ${col.cyan('deptrack clean')}   to remove ${r.unused.length} unused package(s).`);
+  if (recs.length === 0)    recs.push(col.green('Your project dependencies look great!'));
+
+  console.log(col.bold('💡 Recommendations'));
+  console.log(col.dim(col.LINE));
+  recs.forEach(r => console.log(`  → ${r}`));
+  console.log();
+  console.log(col.dim(col.LINE));
+  console.log(col.dim('Audit complete.'));
+  console.log();
+
+  return r;
+}
+
+// ─── list ─────────────────────────────────────────────────────────────────────
+
+async function cmdList(targetDir) {
+  const r = await scanProject(targetDir);
+  header(r.projectName);
+
+  console.log(col.bold('📋 All Dependencies with Status'));
+  console.log(col.dim(col.LINE));
+
+  const all = new Set([...r.allImports, ...r.declared]);
+  const sorted = [...all].sort();
+
+  sorted.forEach(pkg => {
+    const imported  = r.allImports.includes(pkg);
+    const declared  = r.declared.includes(pkg);
+    const ver =
+      r.packageJson?.dependencies?.[pkg] ||
+      r.packageJson?.devDependencies?.[pkg] ||
+      r.packageJson?.peerDependencies?.[pkg] ||
+      r.packageJson?.optionalDependencies?.[pkg] || '';
+
+    let status, icon;
+    if (imported && declared)  { icon = col.green('✓');  status = col.dim('present');  }
+    else if (imported)         { icon = col.red('✗');    status = col.red('missing');   }
+    else                       { icon = col.yellow('~'); status = col.yellow('unused'); }
+
+    console.log(`  ${icon} ${pkg.padEnd(30)} ${col.dim(ver.padEnd(12))} ${status}`);
+  });
+
+  console.log();
+  console.log(col.dim(`Legend: ${col.green('✓')} present  ${col.red('✗')} missing  ${col.yellow('~')} declared but unused`));
+  console.log();
+  console.log(col.dim(col.LINE));
+  console.log(col.dim('List complete.'));
+  console.log();
+}
+
+module.exports = { cmdCheck, cmdInstall, cmdClean, cmdFix, cmdAudit, cmdList };

package/src/index.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const fs   = require('fs');
+const col  = require('./colors');
+const { cmdCheck, cmdInstall, cmdClean, cmdFix, cmdAudit, cmdList } = require('./commands');
+
+// ─── Parse args ───────────────────────────────────────────────────────────────
+const args    = process.argv.slice(2);
+const command = args[0];
+const dirArg  = args[1];
+
+// ─── Help text ────────────────────────────────────────────────────────────────
+function printHelp() {
+  console.log();
+  console.log(col.boldCyan('reqscan') + col.bold(' — Dependency Manager for Node.js'));
+  console.log();
+  console.log(col.bold('Usage:'));
+  console.log('  reqscan <command> [project-dir]');
+  console.log();
+  console.log(col.bold('Commands:'));
+  const cmds = [
+    ['check [dir]',   'List missing, present, and unused packages'],
+    ['install',       'Install all missing packages found by check'],
+    ['clean',         'Remove packages declared but never imported'],
+    ['fix',           'Run install + clean in one command'],
+    ['audit',         'Full dependency health report'],
+    ['list',          'Show all dependencies with status'],
+  ];
+  cmds.forEach(([cmd, desc]) => {
+    console.log(`  ${col.cyan(cmd.padEnd(20))} ${desc}`);
+  });
+  console.log();
+  console.log(col.bold('Examples:'));
+  console.log(`  ${col.dim('reqscan check')}                   # scan current directory`);
+  console.log(`  ${col.dim('reqscan check ./my-app')}          # scan specific folder`);
+  console.log(`  ${col.dim('reqscan install')}                 # install all missing`);
+  console.log(`  ${col.dim('reqscan clean')}                   # remove unused`);
+  console.log(`  ${col.dim('reqscan fix')}                     # install missing + clean unused`);
+  console.log(`  ${col.dim('reqscan audit')}                   # full health report`);
+  console.log(`  ${col.dim('reqscan list')}                    # show all with status`);
+  console.log();
+}
+
+// ─── Resolve target directory ─────────────────────────────────────────────────
+function resolveDir(dirArg) {
+  const target = dirArg ? path.resolve(dirArg) : process.cwd();
+  if (!fs.existsSync(target)) {
+    console.error(col.boldRed(`❌ Directory not found: ${target}`));
+    process.exit(1);
+  }
+  if (!fs.existsSync(path.join(target, 'package.json'))) {
+    console.warn(col.boldYellow(`⚠️  No package.json found in: ${target}`));
+    console.warn(col.dim('   Results may be incomplete.\n'));
+  }
+  return target;
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+(async () => {
+  const validCmds = ['check','install','clean','fix','audit','list','help','--help','-h'];
+
+  if (!command || command === 'help' || command === '--help' || command === '-h') {
+    printHelp();
+    return;
+  }
+
+  if (!validCmds.includes(command)) {
+    console.error(col.boldRed(`❌ Unknown command: "${command}"`));
+    printHelp();
+    process.exit(1);
+  }
+
+  const targetDir = resolveDir(command === 'check' ? dirArg : (dirArg || undefined));
+
+  console.log(col.dim(`\n🔍 Scanning project at: ${targetDir}`));
+
+  try {
+    switch (command) {
+      case 'check'  : await cmdCheck(targetDir);   break;
+      case 'install': await cmdInstall(targetDir); break;
+      case 'clean'  : await cmdClean(targetDir);   break;
+      case 'fix'    : await cmdFix(targetDir);     break;
+      case 'audit'  : await cmdAudit(targetDir);   break;
+      case 'list'   : await cmdList(targetDir);    break;
+    }
+  } catch (err) {
+    console.error(col.boldRed(`\n❌ Error: ${err.message}`));
+    process.exit(1);
+  }
+})();

package/src/scanner.js

@@ -0,0 +1,140 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+// ─── Node.js built-in modules ───────────────────────────────────────────────
+const BUILTIN_MODULES = new Set([
+  'assert','async_hooks','buffer','child_process','cluster','console',
+  'constants','crypto','dgram','diagnostics_channel','dns','domain',
+  'events','fs','fs/promises','http','http2','https','inspector',
+  'module','net','os','path','path/posix','path/win32','perf_hooks',
+  'process','punycode','querystring','readline','repl','stream',
+  'stream/consumers','stream/promises','stream/web','string_decoder',
+  'sys','timers','timers/promises','tls','trace_events','tty','url',
+  'util','util/types','v8','vm','wasi','worker_threads','zlib',
+  // node: prefix variants
+  'node:assert','node:buffer','node:child_process','node:cluster',
+  'node:crypto','node:dgram','node:dns','node:domain','node:events',
+  'node:fs','node:http','node:http2','node:https','node:inspector',
+  'node:module','node:net','node:os','node:path','node:perf_hooks',
+  'node:process','node:readline','node:repl','node:stream','node:string_decoder',
+  'node:timers','node:tls','node:tty','node:url','node:util','node:v8',
+  'node:vm','node:worker_threads','node:zlib'
+]);
+
+// ─── Directories to skip ─────────────────────────────────────────────────────
+const IGNORE_DIRS = new Set([
+  'node_modules','.git','.next','.nuxt','dist','build',
+  'coverage','.cache','.turbo','out','.svelte-kit','.vercel',
+  '.output','public','static','assets'
+]);
+
+// ─── File extensions to scan ─────────────────────────────────────────────────
+const JS_EXTENSIONS = new Set(['.js','.jsx','.mjs','.cjs','.ts','.tsx','.mts','.cts']);
+
+// ─── Import/require patterns ─────────────────────────────────────────────────
+const IMPORT_PATTERNS = [
+  /require\s*\(\s*['"`]([^'"`\s]+)['"`]\s*\)/g,
+  /import\s+(?:[\w*{}\s,]+\s+from\s+)?['"`]([^'"`\s]+)['"`]/g,
+  /import\s*\(\s*['"`]([^'"`\s]+)['"`]\s*\)/g,
+  /require\.resolve\s*\(\s*['"`]([^'"`\s]+)['"`]\s*\)/g,
+  /(?:export\s+(?:[\w*{}\s,]+\s+)?from\s+)['"`]([^'"`\s]+)['"`]/g,
+];
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function extractPackageName(raw) {
+  if (!raw) return null;
+  // Skip relative, absolute, URL imports
+  if (raw.startsWith('.') || raw.startsWith('/') || /^https?:\/\//.test(raw) || raw.startsWith('data:')) return null;
+  // Scoped: @scope/pkg
+  if (raw.startsWith('@')) {
+    const parts = raw.split('/');
+    return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : null;
+  }
+  // Regular: pkg or pkg/subpath → pkg
+  return raw.split('/')[0];
+}
+
+function extractImportsFromFile(filePath) {
+  const found = new Set();
+  try {
+    const src = fs.readFileSync(filePath, 'utf8');
+    for (const re of IMPORT_PATTERNS) {
+      re.lastIndex = 0;
+      let m;
+      while ((m = re.exec(src)) !== null) {
+        const pkg = extractPackageName(m[1]);
+        if (pkg && !BUILTIN_MODULES.has(pkg)) found.add(pkg);
+      }
+    }
+  } catch (_) { /* skip unreadable */ }
+  return found;
+}
+
+function walkDir(dir, allImports = new Set(), scannedFiles = []) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch (_) { return { allImports, scannedFiles }; }
+
+  for (const e of entries) {
+    if (IGNORE_DIRS.has(e.name)) continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      walkDir(full, allImports, scannedFiles);
+    } else if (e.isFile() && JS_EXTENSIONS.has(path.extname(e.name))) {
+      scannedFiles.push(full);
+      for (const pkg of extractImportsFromFile(full)) allImports.add(pkg);
+    }
+  }
+  return { allImports, scannedFiles };
+}
+
+function readPackageJson(dir) {
+  const p = path.join(dir, 'package.json');
+  if (!fs.existsSync(p)) return null;
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
+  catch (_) { return null; }
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+async function scanProject(targetDir) {
+  const pkgJson = readPackageJson(targetDir);
+  const { allImports, scannedFiles } = walkDir(targetDir);
+
+  const declared = new Set([
+    ...Object.keys(pkgJson?.dependencies        || {}),
+    ...Object.keys(pkgJson?.devDependencies     || {}),
+    ...Object.keys(pkgJson?.peerDependencies    || {}),
+    ...Object.keys(pkgJson?.optionalDependencies|| {}),
+  ]);
+
+  const missing = [];
+  const present = [];
+  const unused  = [];
+
+  for (const pkg of [...allImports].sort()) {
+    if (declared.has(pkg)) present.push(pkg);
+    else                   missing.push(pkg);
+  }
+
+  for (const pkg of [...declared].sort()) {
+    if (!allImports.has(pkg)) unused.push(pkg);
+  }
+
+  return {
+    projectName : pkgJson?.name || path.basename(targetDir),
+    packageJson : pkgJson,
+    allImports  : [...allImports].sort(),
+    declared    : [...declared].sort(),
+    missing,
+    present,
+    unused,
+    scannedFiles,
+    targetDir,
+  };
+}
+
+module.exports = { scanProject, readPackageJson };

package/test/test.js

@@ -0,0 +1,152 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+const { scanProject } = require('../src/scanner');
+const { cmdCheck, cmdAudit, cmdList } = require('../src/commands');
+
+// ─── Test helpers ─────────────────────────────────────────────────────────────
+let passed = 0;
+let failed = 0;
+
+function assert(condition, label) {
+  if (condition) {
+    console.log(`  \x1b[32m✓\x1b[0m ${label}`);
+    passed++;
+  } else {
+    console.error(`  \x1b[31m✗\x1b[0m ${label}`);
+    failed++;
+  }
+}
+
+function section(title) {
+  console.log(`\n\x1b[1m\x1b[36m${title}\x1b[0m`);
+  console.log('─'.repeat(40));
+}
+
+// ─── Build mock project ───────────────────────────────────────────────────────
+function buildMockProject() {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'depm-test-'));
+
+  // package.json — express declared, jest declared (but never imported)
+  fs.writeFileSync(path.join(tmpDir, 'package.json'), JSON.stringify({
+    name: 'mock-project',
+    version: '1.0.0',
+    dependencies: {
+      express: '^4.18.0',
+      mongoose: '^7.0.0',
+    },
+    devDependencies: {
+      jest: '^29.0.0',
+    },
+  }, null, 2));
+
+  // index.js — requires express (declared), axios (missing), uuid (missing)
+  fs.writeFileSync(path.join(tmpDir, 'index.js'), `
+const express = require('express');
+const axios = require('axios');
+const path = require('path');         // built-in
+const fs = require('fs');             // built-in
+import something from 'lodash';
+  `);
+
+  // utils/db.js — subdir, scoped pkg, subpath import
+  fs.mkdirSync(path.join(tmpDir, 'utils'));
+  fs.writeFileSync(path.join(tmpDir, 'utils', 'db.js'), `
+const mongoose = require('mongoose');   // declared
+const { v4 } = require('uuid');          // missing
+import { format } from 'date-fns';       // missing
+import core from '@babel/core';          // missing scoped
+  `);
+
+  // lib/helpers.ts — TypeScript file
+  fs.mkdirSync(path.join(tmpDir, 'lib'));
+  fs.writeFileSync(path.join(tmpDir, 'lib', 'helpers.ts'), `
+import { useState } from 'react';        // missing
+export { something } from 'lodash';      // missing (already found, de-duped)
+  `);
+
+  // node_modules — should be skipped entirely
+  fs.mkdirSync(path.join(tmpDir, 'node_modules', 'express'), { recursive: true });
+  fs.writeFileSync(path.join(tmpDir, 'node_modules', 'express', 'index.js'), `
+require('some-internal-dep');            // should NOT be counted
+  `);
+
+  return tmpDir;
+}
+
+// ─── Run tests ────────────────────────────────────────────────────────────────
+async function run() {
+  console.log('\n\x1b[1mdepm — Test Suite\x1b[0m');
+
+  const tmpDir = buildMockProject();
+
+  // ── Scanner tests ────────────────────────────────────────────────────────
+  section('Scanner: extracting imports');
+  const r = await scanProject(tmpDir);
+
+  assert(r.projectName === 'mock-project',           'project name read from package.json');
+  assert(r.scannedFiles.length >= 3,                  'scanned js/ts files (not node_modules)');
+  assert(!r.allImports.includes('path'),              'built-in "path" excluded');
+  assert(!r.allImports.includes('fs'),                'built-in "fs" excluded');
+  assert(!r.allImports.includes('some-internal-dep'), 'node_modules skipped');
+
+  section('Scanner: detected packages');
+  assert(r.allImports.includes('express'),   'express detected');
+  assert(r.allImports.includes('axios'),     'axios detected');
+  assert(r.allImports.includes('lodash'),    'lodash detected (import default)');
+  assert(r.allImports.includes('mongoose'),  'mongoose detected');
+  assert(r.allImports.includes('uuid'),      'uuid detected');
+  assert(r.allImports.includes('date-fns'),  'date-fns detected');
+  assert(r.allImports.includes('@babel/core'),'scoped @babel/core detected');
+  assert(r.allImports.includes('react'),     'react detected from .ts file');
+
+  section('Scanner: missing vs present');
+  assert(r.present.includes('express'),      'express in present (declared)');
+  assert(r.present.includes('mongoose'),     'mongoose in present (declared)');
+  assert(r.missing.includes('axios'),        'axios in missing');
+  assert(r.missing.includes('uuid'),         'uuid in missing');
+  assert(r.missing.includes('date-fns'),     'date-fns in missing');
+  assert(r.missing.includes('@babel/core'),  '@babel/core in missing');
+  assert(r.missing.includes('react'),        'react in missing');
+  assert(!r.missing.includes('express'),     'express NOT in missing');
+  assert(!r.missing.includes('mongoose'),    'mongoose NOT in missing');
+
+  section('Scanner: unused (declared but not imported)');
+  assert(r.unused.includes('jest'),          'jest in unused (declared, never imported)');
+  assert(!r.unused.includes('express'),      'express NOT in unused (it is imported)');
+  assert(!r.unused.includes('mongoose'),     'mongoose NOT in unused (it is imported)');
+
+  section('Commands: check (output only)');
+  console.log('\n--- depm check output ---');
+  await cmdCheck(tmpDir);
+  assert(true, 'cmdCheck ran without error');
+
+  section('Commands: audit (output only)');
+  console.log('\n--- depm audit output ---');
+  await cmdAudit(tmpDir);
+  assert(true, 'cmdAudit ran without error');
+
+  section('Commands: list (output only)');
+  console.log('\n--- depm list output ---');
+  await cmdList(tmpDir);
+  assert(true, 'cmdList ran without error');
+
+  // Cleanup
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+
+  // ── Results ──────────────────────────────────────────────────────────────
+  console.log('\n' + '─'.repeat(40));
+  if (failed === 0) {
+    console.log(`\x1b[32m\x1b[1m✅ All ${passed} tests passed.\x1b[0m\n`);
+  } else {
+    console.error(`\x1b[31m\x1b[1m❌ ${failed} test(s) failed. ${passed} passed.\x1b[0m\n`);
+    process.exit(1);
+  }
+}
+
+run().catch(err => {
+  console.error('Unexpected error:', err);
+  process.exit(1);
+});