depshred 1.0.0 → 1.0.2

package/README.md

@@ -1,201 +1,238 @@
-<p align="center">
-  <img src="assets/depshred.webp" width="200" alt="depshred logo">
-</p>
-
-<h1 align="center">depshred</h1>
-
-<p align="center">
-  <em>Clean up your node_modules. Stop installing stuff Node already has.</em>
-</p>
-
-<p align="center">
-  <img src="https://img.shields.io/badge/run_with-npx_depshred-111111?style=flat-square" alt="Run with npx">
-  <img src="https://img.shields.io/badge/node.js-18%2B_%7C_20%2B_%7C_22%2B-111111?style=flat-square" alt="Node Support">
-  <img src="https://img.shields.io/badge/version-1.0.0-111111?style=flat-square" alt="version 1.0.0">
-  <img src="https://img.shields.io/badge/license-MIT-111111?style=flat-square" alt="MIT license">
-</p>
-
----
-
-Ever look at your `node_modules` folder and wonder why it takes up half your hard drive?
-
-When you follow tutorials or ask AI to write code, it is super easy to end up with 30 different packages installed for things modern Node can already do by itself. Stuff like `dotenv`, `uuid`, or `rimraf` do not need to be in your project anymore. Node already knows how to do all of that.
-
-`depshred` looks through your project, finds packages you do not actually need, and shows you how to swap them for simple code that comes with Node.
-
----
-
-## Quick start
-
-You do not even need to install anything first. Just open your terminal inside your project folder and run:
-
-```bash
-npx depshred
-```
-
-If your project lives in another folder, just tell it where:
-
-```bash
-npx depshred ./path/to/your-project
-```
-
-Using pnpm or bun instead of npm? That works too:
-
-```bash
-pnpm dlx depshred
-bunx depshred
-```
-
----
-
-## What it looks like
-
-Here is what you see when you run it in your terminal:
-
-<p align="center">
-  <img src="assets/view01.webp" width="100%" alt="depshred terminal interface">
-</p>
-
-You get an easy list you can move through with your arrow keys:
-
-```text
-+--------------------------------------------------------------------------+
-| depshred v1.0.0 (Node v20.12.0)                                          |
-| Target: ./my-project                                                     |
-+--------------------------------------------------------------------------+
-| Total Scanned: 24 dependencies                                           |
-|                                                                          |
-| [CRITICAL] 2 packages have native Node.js replacements (saves ~182 KB)   |
-| [UNUSED]   1 package has 0 imports (run: npm uninstall rimraf)           |
-| [WARN]     1 package is dormant >3y (0 sub-deps, self-contained)         |
-| [OK]       20 packages are lean and actively maintained                  |
-+--------------------------------------------------------------------------+
-
-Select a dependency to inspect (Use arrow keys, Enter to inspect):
-  > [CRITICAL] dotenv    Native Node.js built-in available (saves ~72 KB)
-    [CRITICAL] uuid      Native Node.js built-in available (saves ~110 KB)
-    [UNUSED]   rimraf    0 imports found in project source code
-    [WARN]     ms        Dormant >3 years | 0 sub-dependencies (self-contained)
-    [OK]       fastify   Active, schema-compiled and lean
-```
-
----
-
-## What it checks for
-
-When you run `depshred`, it checks three main things:
-
-1. **Stuff Node already has built in**
-Do you really need `dotenv` when Node can load `.env` files on its own? Do you need `uuid` when Node has `crypto.randomUUID()`? `depshred` finds every file and exact line number where you use these, and shows you the quick built-in way to replace them.
-
-2. **Packages you installed but never use**
-Ever ran `npm install` for a test or a guide, forgot about it, and left it sitting in your `package.json`? `depshred` scans your whole project. If you never imported it anywhere, it tells you straight up: `npm uninstall <package>`.
-
-3. **Old or abandoned packages**
-It checks npm to see how big each package is and whether anyone has touched it in the last 3 years. If a package is small, has zero other packages inside it, and just works, `depshred` lets you know so you do not have to worry.
-
-```text
-                    Your package.json
-                            |
-         +------------------+------------------+
-         |                  |                  |
-         v                  v                  v
- 1. Already in Node?   2. Used in code?   3. npm check
- (dotenv, uuid, etc.)  (0 imports found)  (file size, age)
-         |                  |                  |
-         v                  v                  v
- Use Node built-ins      Safe to delete    Good to know
- (saves disk space)     (npm uninstall)   (see how big it is)
-```
-
----
-
-## Extra options
-
-Need to run it inside a script or change how it works? Here are the flags you can use:
-
-| Flag | What it does |
-| :--- | :--- |
-| `--check` | Checks your project and stops with an error if it finds bad or useless packages. Great for GitHub Actions. |
-| `--strict` | Like `--check`, but also stops on small warnings. |
-| `--json` | Prints results as JSON so you can read them with code. |
-| `--no-interactive` | Skips the arrow-key menu and just prints a plain table. |
-| `--path <folder>` | Checks a different folder instead of where you are right now. |
-| `--dormant-years <num>` | How many years without updates before calling a package old (defaults to 3). |
-| `--ignore <names>` | Comma-separated names of packages you want to skip. |
-| `--init-skill [app]` | Adds instructions to your AI editor so it stops installing packages you do not need. |
-| `--help`, `-h` | Shows all available flags. |
-| `--version`, `-v` | Shows the version number. |
-
----
-
-## Teach your AI editor to stop installing junk
-
-If you use AI coding tools like Cursor, Claude, Windsurf, or GitHub Copilot, you have probably seen them run `npm install` for every single little thing. Most of the time, Node already has what they are trying to download.
-
-You can teach your AI helper to check first before installing:
-
-```bash
-# Pick your editor from a menu:
-npx depshred --init-skill
-
-# Or pick your editor directly:
-npx depshred --init-skill cursor       # For Cursor (.cursor/rules)
-npx depshred --init-skill copilot      # For GitHub Copilot (.github)
-npx depshred --init-skill windsurf     # For Windsurf (.windsurf/rules)
-npx depshred --init-skill claude       # For Claude Code (CLAUDE.md)
-npx depshred --init-skill cline        # For Cline (.clinerules)
-npx depshred --init-skill antigravity  # For Antigravity (.agents/skills)
-npx depshred --init-skill agents       # For general agents (AGENTS.md)
-npx depshred --init-skill all          # Sets up all of them at once
-```
-
-Want to see all the skill files and how they work? Check out [SKILLS.md](SKILLS.md).
-
----
-
-## Save your settings
-
-If there is a package you want `depshred` to leave alone, you can save your preferences right inside your `package.json`:
-
-```json
-{
-  "depshred": {
-    "ignore": ["fast-deep-equal"],
-    "dormantYears": 4
-  }
-}
-```
-
----
-
-## What projects work with it?
-
-Pretty much any modern Node.js project:
-
-- **Any framework:** Express, Fastify, Next.js, NestJS, Koa, or plain Node scripts.
-- **Any module style:** Both `import` (ES Modules) and `require` (CommonJS).
-- **JavaScript and TypeScript:** `.js`, `.ts`, `.jsx`, `.tsx`, `.mjs`, `.cjs`.
-- **Projects with multiple folders:** Works with monorepos using the `--path` flag.
-
----
-
-## Questions you might have
-
-**Does it change my code automatically?**  
-No. `depshred` never touches your code behind your back. It shows you the file, the line number, and the built-in Node replacement. You decide what to change and when.
-
-**Does it need a database or send my code to some server?**  
-No. Everything runs right on your computer. It only talks to the public npm website to check package sizes and update dates. It saves that info in your computer's temporary folder for a day so it stays fast.
-
-**What if an old package works fine and does not need updates?**  
-Not every old package is broken. Some small tools are simply finished and do not need changes. `depshred` checks if the package has zero sub-packages. If it is small and self-contained, it gives you a soft heads-up, not a red error. You can also add it to your ignore list.
-
-**Does it work with Python or Go?**  
-No, this is built only for Node.js and npm projects.
-
----
-
-## License
-
+<p align="center">
+  <img src="https://raw.githubusercontent.com/gozajpeg/depshred/master/assets/depshred.webp" width="200" alt="depshred logo">
+</p>
+
+<h1 align="center">depshred</h1>
+
+<p align="center">
+  <em>Clean up your node_modules. Stop installing stuff Node already has.</em>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/run_with-npx_depshred-111111?style=flat-square" alt="Run with npx">
+  <img src="https://img.shields.io/badge/node.js-18%2B_%7C_20%2B_%7C_22%2B-111111?style=flat-square" alt="Node Support">
+  <img src="https://img.shields.io/badge/version-1.0.2-111111?style=flat-square" alt="version 1.0.0">
+  <img src="https://img.shields.io/badge/license-MIT-111111?style=flat-square" alt="MIT license">
+</p>
+
+---
+
+Ever look at your `node_modules` folder and wonder why it takes up half your hard drive?
+
+When you follow tutorials or ask AI to write code, it is super easy to end up with 30 different packages installed for things modern Node can already do by itself. Stuff like `dotenv`, `uuid`, or `rimraf` do not need to be in your project anymore. Node already knows how to do all of that.
+
+`depshred` looks through your project, finds packages you do not actually need, and shows you how to swap them for simple code that comes with Node.
+
+---
+
+## Quick start
+
+You do not even need to install anything first. Just open your terminal inside your project folder and run:
+
+```bash
+npx depshred
+```
+
+If your project lives in another folder, just tell it where:
+
+```bash
+npx depshred ./path/to/your-project
+```
+
+Using pnpm or bun instead of npm? That works too:
+
+```bash
+pnpm dlx depshred
+bunx depshred
+```
+
+---
+
+## What it looks like
+
+Here is what you see when you run it in your terminal:
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/gozajpeg/depshred/master/assets/view01.webp" width="100%" alt="depshred terminal interface">
+</p>
+
+You get an easy list you can move through with your arrow keys:
+
+```text
++--------------------------------------------------------------------------+
+| depshred v1.0.2 (Node v20.12.0)                                          |
+| Target: ./my-project                                                     |
++--------------------------------------------------------------------------+
+| Total Scanned: 24 dependencies                                           |
+|                                                                          |
+| [CRITICAL] 2 packages have native Node.js replacements (saves ~182 KB)   |
+| [UNUSED]   1 package has 0 imports (run: npm uninstall rimraf)           |
+| [WARN]     1 package is dormant >3y (0 sub-deps, self-contained)         |
+| [OK]       20 packages are lean and actively maintained                  |
++--------------------------------------------------------------------------+
+
+Select a dependency to inspect (Use arrow keys, Enter to inspect):
+  > [CRITICAL] dotenv    Native Node.js built-in available (saves ~72 KB)
+    [CRITICAL] uuid      Native Node.js built-in available (saves ~110 KB)
+    [UNUSED]   rimraf    0 imports found in project source code
+    [WARN]     ms        Dormant >3 years | 0 sub-dependencies (self-contained)
+    [OK]       fastify   Active, schema-compiled and lean
+```
+
+---
+
+## What it checks for
+
+When you run `depshred`, it checks three main things:
+
+1. **Stuff Node already has built in**
+Do you really need `dotenv` when Node can load `.env` files on its own? Do you need `uuid` when Node has `crypto.randomUUID()`? `depshred` finds every file and exact line number where you use these, and shows you the quick built-in way to replace them.
+
+2. **Packages you installed but never use**
+Ever ran `npm install` for a test or a guide, forgot about it, and left it sitting in your `package.json`? `depshred` scans your whole project. If you never imported it anywhere, it tells you straight up: `npm uninstall <package>`.
+
+3. **Old or abandoned packages**
+It checks npm to see how big each package is and whether anyone has touched it in the last 3 years. If a package is small, has zero other packages inside it, and just works, `depshred` lets you know so you do not have to worry.
+
+```text
+                    Your package.json
+                            |
+         +------------------+------------------+
+         |                  |                  |
+         v                  v                  v
+ 1. Already in Node?   2. Used in code?   3. npm check
+ (dotenv, uuid, etc.)  (0 imports found)  (file size, age)
+         |                  |                  |
+         v                  v                  v
+ Use Node built-ins      Safe to delete    Good to know
+ (saves disk space)     (npm uninstall)   (see how big it is)
+```
+
+
+---
+
+## What packages can depshred replace?
+
+To be completely honest: no tool can replace every single package in the world. Node does not have a built-in 3D engine to replace `three.js` or a built-in database to replace `pg`.
+
+Instead, `depshred` targets the **most common sources of accidental bloat**: legacy packages that modern Node already includes for free, and heavy monolithic libraries with modern lightweight replacements.
+
+### 1. Modern Node.js built-ins (Zero packages needed)
+
+| Legacy Package | Built-in Node Feature | Supported in | What replaces it |
+| :--- | :--- | :--- | :--- |
+| **`dotenv`** | `--env-file` | Node 20.6+ | `node --env-file=.env app.js` |
+| **`uuid`** | `crypto.randomUUID()` | Node 14.17+ / 16.7+ | `crypto.randomUUID()` |
+| **`rimraf`** | `fs.rmSync()` / `fs.rm()` | Node 14.14+ | `fs.rmSync(path, { recursive: true, force: true })` |
+| **`mkdirp`** | `fs.mkdirSync()` / `fs.mkdir()` | Node 10.12+ | `fs.mkdirSync(path, { recursive: true })` |
+| **`nodemon`** | `node --watch` | Node 18.11+ | `node --watch app.js` |
+| **`axios`** | `fetch()` | Node 18+ | Native `fetch` and `AbortController` |
+| **`node-fetch`** | `fetch()` | Node 18+ | Native `fetch` and `AbortController` |
+| **`glob`** | `fs.glob()` | Node 22+ | Native file matching in `node:fs` |
+| **`querystring`** | `URLSearchParams` | Node 10+ | Built-in `URLSearchParams` |
+
+### 2. Lightweight modern alternatives
+
+| Heavy Package | Suggested Alternative | What you save |
+| :--- | :--- | :--- |
+| **`zod`** | `valibot` or `arktype` | Saves ~5.5 MB unpacked (~90% bundle size reduction) |
+| **`moment`** | `dayjs` or native `Intl` | Saves ~4 MB unpacked |
+| **`lodash`** | `es-toolkit` or modern JS | Saves ~1.5 MB unpacked |
+| **`chalk`** | `picocolors` | Saves ~100 KB and drops dependency chain |
+| **`classnames`** | `clsx` | Drop-in API, faster, zero dependencies |
+| **`bcrypt`** | `bcryptjs` or native `crypto` | Removes heavy C++ `node-gyp` build tools |
+| **`deep-equal`** | `fast-deep-equal` | Sub-1KB, faster comparisons |
+
+> *Everything else in your project is still scanned for 0-import unused packages, heavy sizes (>5MB), and unmaintained/abandoned code (>3 years old).*
+
+---
+
+## Extra options
+
+Need to run it inside a script or change how it works? Here are the flags you can use:
+
+| Flag | What it does |
+| :--- | :--- |
+| `--check` | Checks your project and stops with an error if it finds bad or useless packages. Great for GitHub Actions. |
+| `--strict` | Like `--check`, but also stops on small warnings. |
+| `--json` | Prints results as JSON so you can read them with code. |
+| `--no-interactive` | Skips the arrow-key menu and just prints a plain table. |
+| `--path <folder>` | Checks a different folder instead of where you are right now. |
+| `--dormant-years <num>` | How many years without updates before calling a package old (defaults to 3). |
+| `--ignore <names>` | Comma-separated names of packages you want to skip. |
+| `--init-skill [app]` | Adds instructions to your AI editor so it stops installing packages you do not need. |
+| `--help`, `-h` | Shows all available flags. |
+| `--version`, `-v` | Shows the version number. |
+
+---
+
+## Teach your AI editor to stop installing junk
+
+If you use AI coding tools like Cursor, Claude, Windsurf, or GitHub Copilot, you have probably seen them run `npm install` for every single little thing. Most of the time, Node already has what they are trying to download.
+
+You can teach your AI helper to check first before installing:
+
+```bash
+# Pick your editor from a menu:
+npx depshred --init-skill
+
+# Or pick your editor directly:
+npx depshred --init-skill cursor       # For Cursor (.cursor/rules)
+npx depshred --init-skill copilot      # For GitHub Copilot (.github)
+npx depshred --init-skill windsurf     # For Windsurf (.windsurf/rules)
+npx depshred --init-skill claude       # For Claude Code (CLAUDE.md)
+npx depshred --init-skill cline        # For Cline (.clinerules)
+npx depshred --init-skill antigravity  # For Antigravity (.agents/skills)
+npx depshred --init-skill agents       # For general agents (AGENTS.md)
+npx depshred --init-skill all          # Sets up all of them at once
+```
+
+Want to see all the skill files and how they work? Check out [SKILLS.md](SKILLS.md).
+
+---
+
+## Save your settings
+
+If there is a package you want `depshred` to leave alone, you can save your preferences right inside your `package.json`:
+
+```json
+{
+  "depshred": {
+    "ignore": ["fast-deep-equal"],
+    "dormantYears": 4
+  }
+}
+```
+
+---
+
+## What projects work with it?
+
+Pretty much any modern Node.js project:
+
+- **Any framework:** Express, Fastify, Next.js, NestJS, Koa, or plain Node scripts.
+- **Any module style:** Both `import` (ES Modules) and `require` (CommonJS).
+- **JavaScript and TypeScript:** `.js`, `.ts`, `.jsx`, `.tsx`, `.mjs`, `.cjs`.
+- **Projects with multiple folders:** Works with monorepos using the `--path` flag.
+
+---
+
+## Questions you might have
+
+**Does it change my code automatically?**  
+No. `depshred` never touches your code behind your back. It shows you the file, the line number, and the built-in Node replacement. You decide what to change and when.
+
+**Does it need a database or send my code to some server?**  
+No. Everything runs right on your computer. It only talks to the public npm website to check package sizes and update dates. It saves that info in your computer's temporary folder for a day so it stays fast.
+
+**What if an old package works fine and does not need updates?**  
+Not every old package is broken. Some small tools are simply finished and do not need changes. `depshred` checks if the package has zero sub-packages. If it is small and self-contained, it gives you a soft heads-up, not a red error. You can also add it to your ignore list.
+
+**Does it work with Python or Go?**  
+No, this is built only for Node.js and npm projects.
+
+---
+
+## License
+
 [MIT](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "depshred",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Shred dependency bloat. Embrace modern Node.",
   "type": "module",
   "main": "./src/cli.js",

package/src/cli.js

@@ -33,7 +33,7 @@ ${pc.bold('EXAMPLES:')}
   npx depshred
   npx depshred --check
   npx depshred --init-skill cursor
-  npx depshred ./packages/api --json
+  npx depshred ./path/to/your-project --json
 `;
 
 export async function run(rawArgs = []) {
@@ -77,7 +77,7 @@ export async function run(rawArgs = []) {
   }
 
   if (values.version) {
-    console.log('depshred v1.0.0');
+    console.log('depshred v1.0.2');
     return;
   }
 

package/src/interactive.js

@@ -29,7 +29,7 @@ export async function runInteractive(auditData) {
     process.stdout.write('\x1b[2J\x1b[3J\x1b[H');
 
     console.log(pc.bold(pc.white('+--------------------------------------------------------------------------+')));
-    console.log(pc.bold(pc.white(`| depshred v1.0.0 (Target Node: ${targetNode})`)));
+    console.log(pc.bold(pc.white(`| depshred v1.0.2 (Target Node: ${targetNode})`)));
     console.log(pc.bold(pc.white(`| Project: ${projectName} (${totalDependencies} dependencies scanned)`)));
     console.log(pc.bold(pc.white('+--------------------------------------------------------------------------+')));
     console.log(pc.red(`| [CRITICAL] ${summary.critical} native replacements (saves ~${formatBytes(totalSaveableBytes)})`));
@@ -41,27 +41,70 @@ export async function runInteractive(auditData) {
 
     if (inspecting) {
       const item = results[selectedIndex];
-      console.log(pc.bold(`=== INSPECTING: ${item.name} (${item.tier}) ===`));
-      console.log(`Details: ${item.details}`);
-      console.log(`Unpacked Size: ${formatBytes(item.size)}`);
-      console.log(`Sub-dependencies: ${item.dependenciesCount}`);
+      console.log(pc.bold(pc.white('+--------------------------------------------------------------------------+')));
+      console.log(pc.bold(pc.white(`| INSPECTING: ${item.name} (${item.tier})`)));
+      console.log(pc.bold(pc.white('+--------------------------------------------------------------------------+')));
+      console.log(`Summary: ${item.details}`);
+      console.log(`Unpacked Size: ${formatBytes(item.size)} | Sub-dependencies: ${item.dependenciesCount}`);
+      console.log(`Type: ${item.isDev ? 'Development dependency (devDependencies)' : 'Production dependency (dependencies)'}`);
       console.log('');
 
+      // Critical items: show Before/After diff and uninstall command
+      if (item.tier === 'CRITICAL') {
+        if (item.diff) {
+          console.log(pc.bold('Replacement Solution (Modern Node.js Built-in):'));
+          console.log(pc.green(item.diff));
+          console.log('');
+        }
+        console.log(pc.bold('Action:'));
+        console.log(pc.cyan(`  npm uninstall ${item.name}`));
+        console.log(pc.dim(`  Saves ~${formatBytes(item.size)} unpacked disk space.`));
+        console.log('');
+      }
 
+      // Unused items: show clear uninstall command and ignore instructions
+      if (item.tier === 'UNUSED') {
+        console.log(pc.bold('Recommended Action:'));
+        console.log(pc.cyan(`  npm uninstall ${item.name}`));
+        console.log(pc.dim(`  Zero imports or config references found in project.`));
+        console.log(pc.dim(`  To permanently ignore, add to package.json: "depshred": { "ignore": ["${item.name}"] }`));
+        console.log('');
+      }
 
-      if (item.imports && item.imports.length > 0) {
-        console.log(pc.bold(`Imports found (${item.imports.length}):`));
-        for (const imp of item.imports.slice(0, 5)) {
-          console.log(pc.dim(`  - ${imp.file}:${imp.line} -> ${imp.snippet}`));
+      // Warning items: show lighter alternatives or dormancy details
+      if (item.tier === 'WARN') {
+        if (item.altRule) {
+          console.log(pc.bold('Recommended Lighter Alternative:'));
+          console.log(`  Suggested: ${pc.cyan(item.altRule.lighter)}`);
+          console.log(`  Savings:   ${pc.green(item.altRule.savings)}`);
+          console.log(`  Details:   ${item.altRule.description}`);
+          console.log('');
+        } else if (item.size > 5 * 1024 * 1024) {
+          console.log(pc.bold('Size Optimization Note:'));
+          console.log(pc.yellow(`  Heavy package (${formatBytes(item.size)}). Check if dynamic import() or tree-shaking can reduce bundle weight.`));
+          console.log('');
         }
-        if (item.imports.length > 5) {
-          console.log(pc.dim(`  ... and ${item.imports.length - 5} more`));
+
+        if (item.yearsDormant && item.yearsDormant >= 3) {
+          console.log(pc.bold('Maintenance Assessment:'));
+          if (item.selfContained) {
+            console.log(pc.dim(`  Last update >${item.yearsDormant} years ago, but 0 sub-dependencies (self-contained and stable).`));
+          } else {
+            console.log(pc.yellow(`  Last update >${item.yearsDormant} years ago with ${item.dependenciesCount} sub-dependencies.`));
+          }
+          console.log('');
         }
-        console.log('');
       }
 
-      if (item.tier === 'UNUSED') {
-        console.log(pc.cyan(`Run: npm uninstall ${item.name}`));
+      // Show where imports or references were found
+      if (item.imports && item.imports.length > 0) {
+        console.log(pc.bold(`References in project (${item.imports.length}):`));
+        for (const imp of item.imports.slice(0, 8)) {
+          console.log(pc.dim(`  - ${imp.file}:${imp.line} -> ${imp.snippet}`));
+        }
+        if (item.imports.length > 8) {
+          console.log(pc.dim(`  ... and ${item.imports.length - 8} more references`));
+        }
         console.log('');
       }
 
@@ -136,4 +179,4 @@ export async function runInteractive(auditData) {
     process.stdin.resume();
     render();
   });
-}
+}

package/src/locator.js

@@ -1,7 +1,7 @@
 import { readdir, readFile, stat } from 'node:fs/promises';
-import { join, relative, extname } from 'node:path';
+import { join, relative, extname, basename } from 'node:path';
 
-const SUPPORTED_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx']);
+const SUPPORTED_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.vue', '.svelte']);
 const IGNORED_DIRECTORIES = new Set([
   'node_modules',
   '.git',
@@ -17,6 +17,25 @@ const IGNORED_DIRECTORIES = new Set([
   '.windsurf'
 ]);
 
+const CONFIG_FILE_PATTERNS = [
+  /^\.babelrc(\.json|\.js|\.cjs|\.mjs)?$/,
+  /^babel\.config(\.json|\.js|\.cjs|\.mjs)?$/,
+  /^\.eslintrc(\.json|\.js|\.cjs|\.yaml|\.yml)?$/,
+  /^eslint\.config(\.js|\.mjs|\.cjs)?$/,
+  /^\.prettierrc(\.json|\.js|\.cjs|\.yaml|\.yml)?$/,
+  /^prettier\.config(\.js|\.mjs|\.cjs)?$/,
+  /^tsconfig(\..+)?\.json$/,
+  /^jsconfig(\..+)?\.json$/,
+  /^postcss\.config(\.js|\.cjs|\.mjs|\.json)?$/,
+  /^tailwind\.config(\.js|\.cjs|\.mjs|\.ts)?$/,
+  /^vite\.config(\.js|\.ts|\.mjs)?$/,
+  /^webpack\.config(\.js|\.cjs|\.mjs|\.ts)?$/,
+  /^rollup\.config(\.js|\.mjs)?$/,
+  /^next\.config(\.js|\.mjs|\.ts)?$/,
+  /^jest\.config(\.js|\.ts|\.json)?$/,
+  /^vitest\.config(\.js|\.ts)?$/
+];
+
 /**
  * Normalizes an import specifier to its root npm package name.
  * e.g. "lodash/map" -> "lodash", "@scoped/pkg/deep" -> "@scoped/pkg"
@@ -80,10 +99,34 @@ async function getSourceFiles(dir) {
 }
 
 /**
- * Scan project source files to locate package imports and detect unused dependencies.
+ * Find root-level config files in a directory.
+ */
+async function getRootConfigFiles(dir) {
+  const configFiles = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return configFiles;
+  }
+
+  for (const entry of entries) {
+    if (entry.isFile()) {
+      const name = entry.name.toLowerCase();
+      if (CONFIG_FILE_PATTERNS.some((pat) => pat.test(name))) {
+        configFiles.push(entry.name);
+      }
+    }
+  }
+  return configFiles;
+}
+
+/**
+ * Scan project source files and config files to locate package imports and detect unused dependencies.
  *
  * @param {string} rootDir - Root directory of the project
  * @param {string[]} declaredDependencies - List of package names from package.json
+ * @param {object} scripts - package.json scripts object
  * @returns {Promise<{ importsMap: Map<string, Array<{file: string, line: number, snippet: string}>>, unusedPackages: string[], scannedFilesCount: number }>}
  */
 export async function locateImports(rootDir, declaredDependencies = [], scripts = {}) {
@@ -91,7 +134,142 @@ export async function locateImports(rootDir, declaredDependencies = [], scripts
   const importsMap = new Map();
   const importedSet = new Set();
 
-  // Scan package.json scripts for CLI tool references (e.g. nodemon, rimraf)
+  // Rule 1: Always ignore depshred itself (never flag depshred as unused within a project)
+  if (declaredDependencies.includes('depshred')) {
+    importedSet.add('depshred');
+    importsMap.set('depshred', [{
+      file: 'package.json',
+      line: 1,
+      snippet: 'depshred CLI dependency auditor'
+    }]);
+  }
+
+  // Rule 2: Ambient TypeScript definitions (@types/*) are used by compiler, never imported in source code
+  for (const pkg of declaredDependencies) {
+    if (pkg.startsWith('@types/')) {
+      importedSet.add(pkg);
+      if (!importsMap.has(pkg)) importsMap.set(pkg, []);
+      importsMap.get(pkg).push({
+        file: 'tsconfig.json',
+        line: 1,
+        snippet: 'TypeScript ambient type definition'
+      });
+    }
+  }
+
+  // Rule 3: Bundler, linter, and build configuration plugins
+  for (const pkg of declaredDependencies) {
+    if (
+      pkg.startsWith('@vitejs/plugin-') ||
+      pkg.startsWith('vite-plugin-') ||
+      pkg.startsWith('@rollup/plugin-') ||
+      pkg.startsWith('rollup-plugin-') ||
+      pkg.startsWith('@rolldown/plugin-') ||
+      pkg.endsWith('-webpack-plugin') ||
+      pkg.startsWith('eslint-config-') ||
+      pkg.startsWith('eslint-plugin-') ||
+      pkg.startsWith('@eslint/') ||
+      pkg.startsWith('prettier-plugin-')
+    ) {
+      importedSet.add(pkg);
+      if (!importsMap.has(pkg)) importsMap.set(pkg, []);
+      importsMap.get(pkg).push({
+        file: 'package.json',
+        line: 1,
+        snippet: 'Bundler or linter build plugin'
+      });
+    }
+  }
+
+  // Rule 4: Compiler engines and toolchain infrastructure
+  // Babel toolchain detection: @babel/core, plugins, presets, react-compiler
+  const hasBabelTool = declaredDependencies.some((p) =>
+    p.includes('babel') || p === '@vitejs/plugin-react' || p.includes('react-compiler')
+  );
+  if (hasBabelTool) {
+    for (const pkg of declaredDependencies) {
+      if (
+        pkg === '@babel/core' ||
+        pkg === '@babel/runtime' ||
+        pkg.startsWith('babel-plugin-') ||
+        pkg.startsWith('@babel/plugin-') ||
+        pkg.startsWith('babel-preset-') ||
+        pkg.startsWith('@babel/preset-') ||
+        pkg.includes('plugin-babel')
+      ) {
+        importedSet.add(pkg);
+        if (!importsMap.has(pkg)) importsMap.set(pkg, []);
+        importsMap.get(pkg).push({
+          file: 'package.json',
+          line: 1,
+          snippet: 'Babel compiler infrastructure / plugin'
+        });
+      }
+    }
+  }
+
+  // PostCSS toolchain detection: postcss, autoprefixer, tailwindcss
+  const hasPostcssTool = declaredDependencies.some((p) =>
+    p.includes('postcss') || p === 'tailwindcss' || p === 'autoprefixer'
+  );
+  if (hasPostcssTool) {
+    for (const pkg of declaredDependencies) {
+      if (pkg === 'postcss' || pkg.startsWith('postcss-')) {
+        importedSet.add(pkg);
+        if (!importsMap.has(pkg)) importsMap.set(pkg, []);
+        importsMap.get(pkg).push({
+          file: 'package.json',
+          line: 1,
+          snippet: 'PostCSS compiler infrastructure / plugin'
+        });
+      }
+    }
+  }
+
+  // Rule 5: Scan root configuration files for package names and plugin/preset references
+  const rootConfigFiles = await getRootConfigFiles(rootDir);
+  for (const configName of rootConfigFiles) {
+    let content;
+    try {
+      content = await readFile(join(rootDir, configName), 'utf8');
+    } catch {
+      continue;
+    }
+
+    for (const pkg of declaredDependencies) {
+      if (importedSet.has(pkg)) continue;
+
+      // Exact package match (quoted or word boundary)
+      const escaped = pkg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const directRegex = new RegExp(`['"]${escaped}['"]|\\b${escaped}\\b`);
+
+      // Shorthand matches for common config tools
+      let shorthandMatch = false;
+      if (configName.includes('eslint')) {
+        const eslintPlugin = pkg.replace(/^eslint-plugin-/, '');
+        const eslintConfig = pkg.replace(/^eslint-config-/, '');
+        if (eslintPlugin !== pkg && new RegExp(`['"]${eslintPlugin}['"]`).test(content)) shorthandMatch = true;
+        if (eslintConfig !== pkg && new RegExp(`['"]${eslintConfig}['"]`).test(content)) shorthandMatch = true;
+      } else if (configName.includes('babel')) {
+        const babelPreset = pkg.replace(/^(@babel\/preset-|babel-preset-)/, '');
+        const babelPlugin = pkg.replace(/^(@babel\/plugin-|babel-plugin-)/, '');
+        if (babelPreset !== pkg && new RegExp(`['"]${babelPreset}['"]`).test(content)) shorthandMatch = true;
+        if (babelPlugin !== pkg && new RegExp(`['"]${babelPlugin}['"]`).test(content)) shorthandMatch = true;
+      }
+
+      if (directRegex.test(content) || shorthandMatch) {
+        importedSet.add(pkg);
+        if (!importsMap.has(pkg)) importsMap.set(pkg, []);
+        importsMap.get(pkg).push({
+          file: configName,
+          line: 1,
+          snippet: `Config reference in ${configName}`
+        });
+      }
+    }
+  }
+
+  // Rule 6: Scan package.json scripts for CLI tool references (e.g. nodemon, rimraf, tsc, prettier)
   for (const [scriptName, scriptCmd] of Object.entries(scripts)) {
     if (typeof scriptCmd !== 'string') continue;
     for (const pkg of declaredDependencies) {
@@ -111,6 +289,7 @@ export async function locateImports(rootDir, declaredDependencies = [], scripts
     }
   }
 
+  // Rule 7: Scan project source files for import / require / export from
   for (const filePath of sourceFiles) {
     let content;
     try {
@@ -124,7 +303,6 @@ export async function locateImports(rootDir, declaredDependencies = [], scripts
 
     for (let i = 0; i < lines.length; i++) {
       const line = lines[i];
-      // Skip empty or comment-only lines
       const trimmed = line.trim();
       if (!trimmed || trimmed.startsWith('//') || trimmed.startsWith('/*') || trimmed.startsWith('*')) {
         continue;
@@ -152,7 +330,7 @@ export async function locateImports(rootDir, declaredDependencies = [], scripts
     }
   }
 
-  // Detect unused packages: declared in package.json but never imported in source code
+  // Detect unused packages: declared in package.json but never referenced anywhere
   const unusedPackages = declaredDependencies.filter((pkg) => !importedSet.has(pkg));
 
   return {
@@ -160,4 +338,4 @@ export async function locateImports(rootDir, declaredDependencies = [], scripts
     unusedPackages,
     scannedFilesCount: sourceFiles.length
   };
-}
+}

package/src/registry.js

@@ -1,4 +1,4 @@
-import { readFile, writeFile } from 'node:fs/promises';
+import { readFile, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
@@ -66,7 +66,7 @@ export async function fetchPackageMetadata(packageName, timeoutMs = 4000) {
       signal: controller.signal,
       headers: {
         Accept: 'application/json',
-        'User-Agent': 'depshred-audit/1.0.0'
+        'User-Agent': 'depshred-audit/1.0.2'
       }
     });
 

package/src/reporter.js

@@ -9,7 +9,7 @@ export function printScorecard(auditData, options = {}) {
 
   console.log('');
   console.log(pc.bold(pc.white('+--------------------------------------------------------------------------+')));
-  console.log(pc.bold(pc.white(`| depshred v1.0.0 (Target Node: ${targetNode})`)));
+  console.log(pc.bold(pc.white(`| depshred v1.0.2 (Target Node: ${targetNode})`)));
   console.log(pc.bold(pc.white(`| Project: ${projectName} (${totalDependencies} dependencies scanned)`)));
   console.log(pc.bold(pc.white('+--------------------------------------------------------------------------+')));
 

package/src/rules/alt-rules.js

@@ -1,8 +1,14 @@
-/**
+/**
  * Modern Lightweight Package Alternatives Catalog.
  * Objective replacements for heavy or legacy packages.
  */
 export const ALT_RULES = [
+  {
+    name: 'zod',
+    lighter: 'valibot',
+    description: 'Zod is ~5.9MB unpacked (~14KB gzipped). Replace with valibot (modular, sub-1KB per schema) or arktype for 10x smaller bundles.',
+    savings: '~5.5MB unpacked (~90% bundle reduction)'
+  },
   {
     name: 'moment',
     lighter: 'dayjs',
@@ -21,10 +27,22 @@ export const ALT_RULES = [
     description: 'Large dependency chain in v4/v5. Replace with picocolors (sub-7KB, 0 sub-dependencies).',
     savings: '~100KB'
   },
+  {
+    name: 'classnames',
+    lighter: 'clsx',
+    description: 'Legacy classnames utility. Replace with clsx (drop-in API, faster, zero dependencies).',
+    savings: '~50KB'
+  },
   {
     name: 'bcrypt',
     lighter: 'bcryptjs',
     description: 'Requires node-gyp C++ compilation toolchain. Replace with pure JS bcryptjs or native crypto.scrypt.',
     savings: 'Eliminates native build toolchain dependency'
+  },
+  {
+    name: 'deep-equal',
+    lighter: 'fast-deep-equal',
+    description: 'Legacy recursive comparison. Replace with fast-deep-equal (sub-1KB, faster) or native assert.deepStrictEqual.',
+    savings: '~80% faster and 0 sub-dependencies'
   }
-];
+];