devcompass 1.0.0 → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ajay Thorat
+
+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,41 +1,211 @@
-# DevCompass 🧭
+# 🧭 DevCompass
 
-> Health check for your JavaScript project
+**Dependency health checker for JavaScript/TypeScript projects**
 
-Find unused dependencies, outdated packages, and calculate your project's health score in seconds.
+[![npm version](https://img.shields.io/npm/v/devcompass.svg)](https://www.npmjs.com/package/devcompass)
+[![npm downloads](https://img.shields.io/npm/dm/devcompass.svg)](https://www.npmjs.com/package/devcompass)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## 🚀 Quick Start
-```bash
-npx devcompass analyze
-```
+Analyze your JavaScript projects to find unused dependencies, outdated packages, and get a health score.
 
 ## ✨ Features
 
-- 🔍 Find unused dependencies
-- 📦 Check for outdated packages
-- 📊 Calculate health score (0-10)
-- 💡 Get actionable recommendations
-- ⚡ Fast analysis (2-3 seconds)
+- 🔍 **Detect unused dependencies** - Find packages you're not actually using
+- 📦 **Check for outdated packages** - See what needs updating
+- 📊 **Project health score** - Get a 0-10 rating for your dependencies
+- 🎨 **Beautiful terminal UI** - Colored output with clear sections
+- ⚡ **Fast analysis** - Scans projects in seconds
+- 🔧 **Framework-aware** - Handles React, Next.js, Angular, NestJS, PostCSS, Tailwind
+
+## 🚀 Installation
 
-## 📦 Installation
+**Global installation (recommended):**
+```bash
+npm install -g devcompass
+```
 
-### Option 1: npx (Recommended)
+**Local installation:**
+```bash
+npm install --save-dev devcompass
+```
+
+**One-time use (no installation):**
 ```bash
 npx devcompass analyze
 ```
 
-### Option 2: Global Installation
+## 📖 Usage
+
+Navigate to your project directory and run:
 ```bash
-npm install -g devcompass
 devcompass analyze
 ```
 
+### Example Output
+```
+🔍 DevCompass v1.0.1 - Analyzing your project...
+✔ Scanned 15 dependencies in project
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🔴 UNUSED DEPENDENCIES (2)
+  ● lodash
+  ● moment
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🟡 OUTDATED PACKAGES (3)
+  react          18.2.0 → ^19.0.0  (major update)
+  axios          1.4.0 → ^1.6.0   (minor update)
+  express        4.18.0 → ^4.19.0  (patch update)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📊 PROJECT HEALTH
+  Overall Score:       6.5/10
+  Total Dependencies:  15
+  Unused:              2
+  Outdated:            3
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+💡 QUICK WIN
+  Clean up unused dependencies:
+  npm uninstall lodash moment
+
+  Expected impact:
+  ✓ Remove 2 unused packages
+  ✓ Reduce node_modules size
+  ✓ Improve health score → 7.5/10
+```
+
+## 🎯 What It Detects
+
+### Unused Dependencies
+- Uses AST parsing via [depcheck](https://github.com/depcheck/depcheck)
+- Scans all `.js`, `.jsx`, `.ts`, `.tsx` files
+- Excludes `node_modules`, `dist`, `build` folders
+- Framework-aware (automatically ignores framework core packages)
+
+### Automatically Ignored Packages
+DevCompass won't flag these as unused (they're typically used in config files):
+- **Frameworks:** React, Next.js, Angular, NestJS
+- **Build tools:** Webpack, Vite, Rollup, ESBuild
+- **Testing:** Jest, Vitest, Mocha, Testing Library
+- **CSS/PostCSS:** PostCSS, Autoprefixer, Tailwind CSS, cssnano
+- **Linting/Formatting:** ESLint, Prettier, ESLint plugins/configs
+- **TypeScript:** TypeScript, @types/* packages
+
+### Outdated Packages
+- Checks against npm registry
+- Shows current vs latest versions
+- Indicates update type (major/minor/patch)
+
+### Health Score
+- Calculated from 0-10 based on:
+  - Percentage of unused dependencies (-4 points per 100%)
+  - Percentage of outdated packages (-3 points per 100%)
+- Higher score = healthier project
+
+## ⚙️ Options
+```bash
+# Analyze current directory
+devcompass analyze
+
+# Analyze specific directory
+devcompass analyze --path /path/to/project
+
+# Show version
+devcompass --version
+
+# Show help
+devcompass --help
+```
+
+## ⚠️ Known Issues & Best Practices
+
+### Installation
+- **Recommended:** Install globally with `npm install -g devcompass`
+- If installed locally, DevCompass may appear in the unused dependencies list (this is expected)
+- You'll see a warning if running from local installation
+
+### Dependency Warnings
+Some deprecation warnings may appear during installation. These come from third-party dependencies (depcheck, npm-check-updates) and don't affect functionality.
+
+### False Positives
+DevCompass is smart about config-based dependencies, but occasionally may flag packages that are only used in:
+- Config files (webpack.config.js, next.config.js, etc.)
+- Build scripts
+- Type definitions
+
+If you encounter a false positive, please [report it](https://github.com/AjayBThorat-20/devcompass/issues)!
+
 ## 🛠️ Requirements
 
-- Node.js >= 16.0.0
-- npm >= 7.0.0
-- A project with `package.json`
+- Node.js >= 14.0.0
+- npm or yarn
+
+## 💡 Tips
+
+1. **Run regularly** - Add to your CI/CD pipeline or git hooks
+2. **Check before updates** - See what's outdated before updating
+3. **Clean up first** - Remove unused deps before adding new ones
+4. **Verify before uninstalling** - DevCompass helps identify candidates, but always verify before removing
+
+## 🤝 Contributing
+
+Contributions are welcome! Feel free to:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Development
+```bash
+# Clone the repo
+git clone https://github.com/AjayBThorat-20/devcompass.git
+cd devcompass
+
+# Install dependencies
+npm install
+
+# Test locally
+node bin/devcompass.js analyze
+
+# Run on test projects
+cd examples/test-project
+node ../../bin/devcompass.js analyze
+```
 
 ## 📝 License
 
-MIT
+MIT © [Ajay Thorat](https://github.com/AjayBThorat-20)
+
+## 🔗 Links
+
+- [npm Package](https://www.npmjs.com/package/devcompass)
+- [GitHub Repository](https://github.com/AjayBThorat-20/devcompass)
+- [Report Issues](https://github.com/AjayBThorat-20/devcompass/issues)
+- [Changelog](https://github.com/AjayBThorat-20/devcompass/blob/main/CHANGELOG.md)
+
+## 🙏 Acknowledgments
+
+Built with:
+- [depcheck](https://github.com/depcheck/depcheck) - Dependency checker
+- [npm-check-updates](https://github.com/raineorshine/npm-check-updates) - Package updater
+- [chalk](https://github.com/chalk/chalk) - Terminal colors
+- [ora](https://github.com/sindresorhus/ora) - Spinners
+- [commander](https://github.com/tj/commander.js) - CLI framework
+
+## 📈 Stats
+
+Check out DevCompass stats:
+- [npm trends](https://npmtrends.com/devcompass)
+- [npm-stat](https://npm-stat.com/charts.html?package=devcompass)
+
+---
+
+**Made with ❤️ by [Ajay Thorat](https://github.com/AjayBThorat-20)**
+
+*DevCompass - Keep your dependencies healthy!* 🧭

package/bin/devcompass.js

@@ -2,9 +2,18 @@
 
 const { Command } = require('commander');
 const chalk = require('chalk');
+const path = require('path');
 const { analyze } = require('../src/commands/analyze');
 const packageJson = require('../package.json');
 
+// Check if running from local node_modules
+const isLocalInstall = __dirname.includes('node_modules');
+if (isLocalInstall && process.argv.includes('analyze')) {
+  console.log(chalk.yellow('\n⚠️  DevCompass is installed locally as a dependency.'));
+  console.log(chalk.yellow('   For best results, install globally:'));
+  console.log(chalk.cyan('   npm install -g devcompass\n'));
+}
+
 const program = new Command();
 
 program

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devcompass",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Analyze your JavaScript projects for unused dependencies and outdated packages",
   "main": "src/index.js",
   "bin": {

package/src/analyzers/unused-deps.js

@@ -14,6 +14,7 @@ async function findUnusedDeps(projectPath, dependencies) {
       '*.min.js'
     ],
     ignoreMatches: [
+      // Framework core packages
       'react',
       'react-dom',
       'react-native',
@@ -26,14 +27,34 @@ async function findUnusedDeps(projectPath, dependencies) {
       '@nestjs/platform-express',
       'typescript',
       '@types/*',
+      
+      // Build tools
       'webpack',
       'vite',
       'rollup',
       'esbuild',
+      
+      // Testing
       'jest',
       'vitest',
       'mocha',
-      '@testing-library/*'
+      '@testing-library/*',
+      
+      // CSS/PostCSS (used in config files)
+      'postcss',
+      'autoprefixer',
+      'tailwindcss',
+      'cssnano',
+      
+      // Linting/Formatting (used in config files)
+      'prettier',
+      'eslint',
+      'eslint-config-*',
+      '@eslint/*',
+      'eslint-plugin-*',
+      
+      // Self-reference (don't flag devcompass as unused)
+      'devcompass'
     ]
     // REMOVED parsers - let depcheck use defaults
   };