npm package: @semicolonised/v-checker
Description: A lightweight CLI tool for checking package version compatibility in JavaScript environments. Install globally for best experience.
Author: Semicolonised
Latest version: 1.0.3

# v-checker - Version Compatibility Checker

A lightweight version compatibility checker for JavaScript environments. Check if packages are compatible with your current tech stack before installing or upgrading.

## Quick Start

```bash
# Install globally (recommended)
npm install -g @semicolonised/v-checker

# Use the tool
v-checker react
v-checker summary
```

## Features

- 🔍 **Package Compatibility Checking**: Check if a package's latest version is compatible with your tech stack
- 📊 **Project Analysis**: Get a comprehensive summary of all packages and their upgrade status
- 🛠️ **Tech Stack Detection**: Automatically detect Node.js, Angular, React, TypeScript, Docker, nginx versions
- 💡 **Smart Recommendations**: Get specific upgrade recommendations and compatible versions
- 🎨 **Beautiful Output**: Color-coded, formatted output for easy reading
- ⚡ **Lightweight**: Fast and efficient with minimal dependencies

## Installation

### Global Installation (Recommended) ⭐
For the best experience, install v-checker globally to use it from anywhere:
```bash
npm install -g @semicolonised/v-checker
```

### Local Installation
If you prefer to install locally, you'll need to use `npx` to run the command:
```bash
npm install @semicolonised/v-checker
# Then use with npx:
npx v-checker <package-name>
```

## Usage

> **Note**: If you installed locally, prefix all commands with `npx` (e.g., `npx v-checker react`)

### Check a Specific Package
```bash
# Basic package check
v-checker react

# Check with compatibility flag
v-checker @angular/core --check-compatible

# Verbose output
v-checker lodash --verbose
```

### Project Summary
```bash
# Show project-wide compatibility summary
v-checker summary

# Verbose summary with detailed package list
v-checker summary --verbose
```

### Other Commands
```bash
# Check if package exists in npm registry
v-checker exists my-package

# Show detected tech stack
v-checker tech-stack

# Show help
v-checker help
```

## Examples

### Example 1: Checking React Compatibility
```bash
# Global installation
$ v-checker react --check-compatible

# Local installation
$ npx v-checker react --check-compatible

🔧 Detected Tech Stack:
──────────────────────────────────────────────────
  node            18.17.0
  npm             9.6.7
  react           18.2.0

📦 react
──────────────────────────────────────────────────
  Current Version:  18.2.0
  Latest Version:   18.2.0
  Status:           ✅ Compatible

✅ react latest version is compatible with your tech stack
```

### Example 2: Project Summary
```bash
# Global installation
$ v-checker summary

# Local installation
$ npx v-checker summary

📊 Project Summary
════════════════════════════════════════════════════════════

🔧 Detected Tech Stack:
──────────────────────────────────────────────────
  node            18.17.0
  npm             9.6.7
  angular         16.0.0
  typescript      5.0.0

📦 Package Statistics:
──────────────────────────────────────────────────
  Total Packages:     15
  Upgradeable:        8
  Incompatible:       2

✅ Safe to Upgrade:
──────────────────────────────────────────────────
  lodash                   4.17.21 → 4.17.21
  axios                    1.4.0 → 1.6.0
  express                  4.18.2 → 4.18.2

⚠️  Compatibility Issues:
──────────────────────────────────────────────────
  @angular/core            16.0.0 → 16.2.0
  @angular/common          16.0.0 → 16.2.0

💡 Recommendations:
──────────────────────────────────────────────────
  • ✅ 8 packages can be safely upgraded
  • ⚠️  2 packages have compatibility issues
  • 📦 5 packages have newer versions available
```

## Supported Technologies

- **Node.js**: Version detection and compatibility checking
- **npm**: Package manager version detection
- **Angular**: Framework version detection and compatibility
- **React**: Framework version detection and compatibility
- **TypeScript**: Compiler version detection
- **Docker**: Container runtime version detection
- **nginx**: Web server version detection

## API Usage

You can also use v-check programmatically:

```typescript
import { CompatibilityChecker, VersionDetector, ProjectAnalyzer } from '@semicolonised/v-checker';

// Check package compatibility
const techStack = await VersionDetector.detectTechStack();
const result = await CompatibilityChecker.checkCompatibility('react', techStack);

// Analyze entire project
const summary = await ProjectAnalyzer.analyzeProject();
```

## Configuration

v-check automatically detects your tech stack from the current environment. No configuration file is required.

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/new-feature`
3. Commit your changes: `git commit -am 'Add new feature'`
4. Push to the branch: `git push origin feature/new-feature`
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Roadmap

- [ ] Support for more package managers (yarn, pnpm)
- [ ] Integration with security vulnerability databases
- [ ] CI/CD integration
- [ ] Configuration file support
- [ ] Plugin system for custom compatibility rules
- [ ] Web interface for large projects

## Troubleshooting

### Common Issues

1. **Package not found**: Make sure the package name is correct and exists in the npm registry
2. **Tech stack not detected**: Ensure the tools are installed and accessible in your PATH
3. **Permission errors**: Use `sudo` for global installation or install locally

### Getting Help

- Check the help: `v-checker help` (or `npx v-checker help` for local installation)
- Open an issue on GitHub
- Check the documentation

---

Made with ❤️ for the JavaScript community