licenseguard-cli 1.2.2 → 2.1.0

package/LICENSE

@@ -1,7 +1,7 @@
 MIT License
 
-Copyright (c) 2025 rfxlamia
-github.com/rfxlamia/licenseguard
+Copyright (c) 2025 v
+
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,66 +1,148 @@
 # LicenseGuard
 
-[![npm version](https://badge.fury.io/js/licenseguard-cli.svg)](https://badge.fury.io/js/licenseguard-cli)
-[![Build Status](https://github.com/your-username/licenseguard/workflows/Test/badge.svg)](https://github.com/your-username/licenseguard/actions)
-[![Coverage Status](https://codecov.io/gh/your-username/licenseguard/branch/main/graph/badge.svg)](https://codecov.io/gh/your-username/licenseguard)
+[![npm version](https://badge.fury.io/js/licenseguard-cli.svg)](https://www.npmjs.com/package/licenseguard-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**License setup & compliance helper for developers**
+> License setup & compliance guard for developers
 
-LicenseGuard is a CLI tool that helps you quickly set up open source licenses for your projects with automatic git hooks that notify your team about licensing requirements.
+LicenseGuard helps you set up open source licenses and protects your project from license conflicts. It scans your dependencies for incompatible licenses and automatically notifies developers about licensing requirements - works with any language (Node.js, Python, Rust, Go, etc.).
+
+## Key Features
+
+- **Multi-Ecosystem Scanning** - Scans dependencies across 5 ecosystems (Node.js, C++, Rust, Python, Go)
+- **Conflict Detection** - Detects incompatible licenses (e.g., GPL vs MIT) and blocks creation
+- **SPDX Compatibility** - Industry-standard license compatibility checking
+- **Scan Results** - Save scan results to `.licenseguardrc` for transparency
+- **Automatic Notifications** - See license info immediately after `git clone`
+- **Zero Effort** - Global hooks install once, work forever
+- **Language Agnostic** - Works for Python, Rust, Go, Ruby, any project
+- **Offline** - All license templates bundled, no internet required
+
+---
+
+## Supported Ecosystems
+
+LicenseGuard scans dependencies across multiple languages and package managers:
+
+- **Node.js** - npm packages (`package.json`)
+- **C/C++** - Conan packages (`conanfile.txt`, `conanfile.py`)
+- **Rust** - Cargo crates (`Cargo.toml`)
+- **Python** - pip/pipenv/poetry packages (`requirements.txt`, `Pipfile`, `pyproject.toml`)
+- **Go** - Go modules (`go.mod`)
+
+Each ecosystem uses optimized detection strategies for maximum accuracy.
+
+---
 
 ## Quick Start
 
+### For Developers (One-time Setup)
+
+```bash
+npm install -g licenseguard-cli
+```
+
+That's it! Now every time you clone a repo with `.licenseguardrc`, you'll see:
+
 ```bash
-# Step 1: Run the interactive setup
-npx licenseguard-cli --init
+git clone https://github.com/some/project
+# 📜 This project uses MIT License by ProjectOwner
+```
+
+### For Project Owners
+
+```bash
+cd your-project
+licenseguard init
+```
 
-# Step 2: Answer the prompts (license type, owner name, year)
+Follow the prompts, then commit:
 
-# Step 3: Done! Your LICENSE file and git hooks are ready
+```bash
+git add LICENSE .licenseguardrc
+git commit -m "Add license"
+git push
 ```
 
-That's it! Your project now has:
-- A properly formatted LICENSE file
-- A `.licenseguardrc` configuration file
-- Git hooks that display license reminders (optional)
+Anyone who has LicenseGuard installed globally will now see your license info when they clone.
+
+---
+
+## How It Works
+
+### Automatic Global Hooks
+
+When you install LicenseGuard globally, it automatically:
+
+1. Creates git template directory at `~/.git-templates/hooks/`
+2. Installs self-contained hooks (only needs Node.js, not LicenseGuard)
+3. Configures git: `git config --global init.templateDir ~/.git-templates`
 
-## Installation
+Now **every** `git clone` or `git init` copies these hooks automatically.
+
+The hooks check for `.licenseguardrc` and display license info if found:
 
-### Using npx (Recommended)
 ```bash
-npx licenseguard-cli --init
+git clone <any-repo>
+# If .licenseguardrc exists:
+# 📜 This project uses MIT License by OwnerName
+
+git checkout feature-branch
+# 📜 This project uses MIT License by OwnerName
+
+git commit -m "changes"
+# ℹ️  Reminder: This project is licensed under MIT
 ```
 
-### Global Installation
+---
+
+## Installation Options
+
+### Global (Recommended)
+
 ```bash
 npm install -g licenseguard-cli
-licenseguard --init
 ```
 
-### Local Installation
+Enables automatic license notifications for all git operations.
+
+### Using npx (No install)
+
 ```bash
-npm install --save-dev licenseguard-cli
-npx licenseguard-cli --init
+npx licenseguard-cli init
 ```
 
-## Usage
+One-time use without global install (no automatic notifications).
 
-### Interactive Setup (`--init`)
+### Local Development Dependency
 
 ```bash
-licenseguard --init
+npm install --save-dev licenseguard-cli
 ```
 
-This command guides you through:
-1. Selecting a license type
-2. Entering your copyright owner name
-3. Setting the copyright year (defaults to current year)
-4. Adding a project URL (optional)
-5. Optionally initializing git if not already a repo
-6. Installing git hooks for license notifications
+For use in npm scripts (see Advanced Usage).
+
+---
+
+## Commands
+
+### `init` - Interactive Setup
+
+```bash
+licenseguard init
+```
 
-**Example Output:**
+Guides you through:
+1. Selecting license type (MIT, Apache 2.0, GPL 3.0, etc.)
+2. Copyright owner name
+3. Copyright year (defaults to current)
+4. Project URL (optional)
+5. Dependency scanning for license conflicts
+6. Option to save scan results
+7. Git initialization (if needed)
+8. Git hooks installation
+
+Example (with clean dependencies):
 ```
 📜 LicenseGuard - Interactive License Setup
 
@@ -69,46 +151,103 @@ This command guides you through:
 ? Copyright year: 2025
 ? Project URL (optional): https://github.com/you/project
 
+🔍 Scanning dependencies for license conflicts...
+
+✓ Scan complete - 150 dependencies checked
+  ✓ 150 compatible
+  ✓ 0 incompatible
+  ✓ 0 unknown
+
+? Save scan results to .licenseguardrc? Yes
+
 ✓ LICENSE file created
+✓ Scan results saved to .licenseguardrc
 ✓ Configuration saved to .licenseguardrc
 ✓ Git hooks installed
 
 📄 Your project is now licensed under MIT
 ```
 
-### Fast Setup (`--init-fast`)
+Example (with conflicts):
+```
+🔍 Scanning dependencies for license conflicts...
+
+✗ Scan complete - 150 dependencies checked
+  ✓ 147 compatible
+  ❌ 2 incompatible
+  ⚠️ 1 unknown
+
+⚠️ CONFLICTS DETECTED:
+
+❌ some-gpl-lib@2.0.0 (GPL-3.0)
+   Conflict: Copyleft incompatible with MIT
+   Location: node_modules/some-gpl-lib/package.json
+
+✗ LICENSE NOT created due to license conflicts.
+
+Fix conflicts or use --force to proceed anyway:
+  licenseguard init --force
+```
+
+**With Explanation (`--explain`):**
+```bash
+licenseguard init --explain
+# ...
+# ❌ libdwarf@0.9.1 (LGPL-2.1-only)
+#    Conflict: Copyleft incompatible with MIT
+#    ────────────────────────
+#    📚 FSF: MIT license is permissive and GPL-compatible
+#    🔗 https://www.gnu.org/licenses/license-list.html#Expat
+```
+
+**Flags:**
+- `--force` - Create LICENSE despite conflicts (shows warnings)
+- `--noscan` - Skip dependency scanning
+- `--explain` - Show authoritative source citations (FSF/OSI links) for conflicts
+
+### `init --fast` - Non-Interactive Setup
 
 ```bash
-licenseguard --init-fast --license mit --owner "Your Name"
+licenseguard init --fast --license mit --owner "Your Name"
 ```
 
-Non-interactive setup with flags. Perfect for CI/CD or scripting.
+Perfect for CI/CD or scripting. Automatically scans dependencies and auto-saves clean results.
+
+**Flags:**
+- `--fast` - Enable non-interactive mode
+- `--license <type>` (required) - License type
+- `--owner <name>` (optional) - Auto-detects from git config
+- `--year <year>` (optional) - Defaults to current year
+- `--url <url>` (optional) - Auto-detects from git remote
+- `--force` - Create LICENSE despite conflicts
+- `--noscan` - Skip dependency scanning
 
-**Available Flags:**
-- `--license <type>` (required) - License type to use
-- `--owner <name>` (optional) - Copyright owner (auto-detects from git config)
-- `--year <year>` (optional) - Copyright year (defaults to current year)
-- `--url <url>` (optional) - Project URL (auto-detects from git remote)
+**Auto-save behavior in fast mode:**
+- Clean scan (no conflicts) → Automatically saves `scanResult`
+- Conflicts detected → Does not save `scanResult`
 
-**Examples:**
+Examples:
 ```bash
-# Minimal (auto-detects owner from git config)
-licenseguard --init-fast --license mit
+# Minimal
+licenseguard init --fast --license mit
 
-# Full specification
-licenseguard --init-fast --license apache2_0 --owner "Apache Corp" --year 2025 --url "https://apache.org"
+# Skip scanning
+licenseguard init --fast --license mit --noscan
+
+# Force creation despite conflicts
+licenseguard init --fast --license mit --force
 
-# GPL license
-licenseguard --init-fast --license gpl3_0 --owner "Free Software Foundation"
+# Full specification
+licenseguard init --fast --license apache2_0 --owner "Apache Corp" --year 2025
 ```
 
-### List Available Licenses (`--ls`)
+### `ls` - List Available Licenses
 
 ```bash
-licenseguard --ls
+licenseguard ls
 ```
 
-Displays all available license types:
+Output:
 ```
 Available License Templates:
 
@@ -120,23 +259,36 @@ Available License Templates:
 ✓ WTFPL - Do What The F*ck You Want To Public License (ultra-permissive)
 ```
 
-## Available Licenses
+### `setup` - Setup Hooks Only
+
+```bash
+licenseguard setup
+```
+
+Reads existing `.licenseguardrc` and installs hooks. Used in npm prepare scripts.
+
+---
+
+## Supported Licenses
 
-| License Key | Display Name | Description |
-|-------------|--------------|-------------|
-| `mit` | MIT | MIT License (permissive, widely used) |
-| `apache2_0` | Apache 2.0 | Apache License 2.0 (permissive with patent grant) |
-| `gpl3_0` | GPL 3.0 | GNU General Public License 3.0 (copyleft) |
-| `bsd3clause` | BSD 3-Clause | BSD 3-Clause License (permissive with attribution) |
-| `isc` | ISC | ISC License (simpler MIT alternative) |
-| `wtfpl` | WTFPL | Do What The F*ck You Want To Public License (ultra-permissive) |
+| Key | Name | Description |
+|-----|------|-------------|
+| `mit` | MIT | Permissive, widely used |
+| `apache2_0` | Apache 2.0 | Permissive with patent grant |
+| `gpl3_0` | GPL 3.0 | Copyleft |
+| `bsd3clause` | BSD 3-Clause | Permissive with attribution |
+| `isc` | ISC | Simpler MIT alternative |
+| `wtfpl` | WTFPL | Ultra-permissive |
 
-Not sure which license to choose? Visit [choosealicense.com](https://choosealicense.com) for guidance.
+Not sure which to choose? Visit [choosealicense.com](https://choosealicense.com).
+
+---
 
 ## Configuration
 
-LicenseGuard creates a `.licenseguardrc` file in your project root:
+LicenseGuard creates `.licenseguardrc` in your project root.
 
+**Basic format:**
 ```json
 {
   "license": "mit",
@@ -146,148 +298,194 @@ LicenseGuard creates a `.licenseguardrc` file in your project root:
 }
 ```
 
-This configuration is used by the git hooks to display license information.
-
-## Git Hooks
-
-LicenseGuard installs two informational git hooks:
-
-### Post-Checkout Hook
-Displays a notification after `git checkout` or branch switches:
-```
-📜 This project uses MIT License by Your Name
+**With scan results (optional):**
+```json
+{
+  "license": "mit",
+  "owner": "Your Name",
+  "year": "2025",
+  "url": "https://github.com/you/project",
+  "scanResult": {
+    "timestamp": "2025-11-18T10:30:00.000Z",
+    "totalDependencies": 150,
+    "compatible": 150,
+    "incompatible": 0,
+    "unknown": 0,
+    "issues": []
+  }
+}
 ```
 
-### Pre-Commit Hook
-Displays a reminder before each commit:
-```
-ℹ️ Reminder: This project is licensed under MIT
-```
+**Why save scan results?**
+- **Transparency badge** - Shows your project has validated license compliance
+- **Trust signal** - Like CI badges or test coverage badges
+- **Audit trail** - Documents when dependencies were last checked
+- **Open source best practice** - Demonstrates license awareness
+
+This file **must be committed** to your repository so others can see your license info.
 
-**Important:**
-- Hooks are **educational only** - they never block git operations
-- Hooks always exit with code 0 (success)
-- If `.licenseguardrc` is missing, hooks silently exit
+---
 
-### Auto-Setup on Clone (npm projects)
+## Advanced Usage
 
-Git hooks live in `.git/hooks/` which is **not tracked by git**. This means hooks are not copied when someone clones your repository.
+### For npm Projects (Alternative to Global Install)
 
-For npm projects, you can use the `prepare` script to automatically set up hooks when developers run `npm install`:
+If you can't rely on developers having LicenseGuard installed globally, use npm prepare script:
 
-**Add to your package.json:**
 ```json
 {
   "devDependencies": {
-    "licenseguard-cli": "^1.1.0"
+    "licenseguard-cli": "^2.0.0"
   },
   "scripts": {
-    "prepare": "licenseguard --setup || true"
+    "prepare": "licenseguard setup || true"
   }
 }
 ```
 
-**What happens when someone clones your project:**
-```bash
-git clone <your-repo>       # Gets code + .licenseguardrc
-npm install                 # AUTOMATICALLY:
-                           # 📜 "This project uses MIT License by Your Name"
-                           # ✓ Git hooks installed
-git checkout feature        # Notification appears (hooks active)
-git commit                  # Reminder appears (hooks active)
-```
+When developers run `npm install`, hooks are set up automatically.
 
-The `--setup` command:
-- Reads `.licenseguardrc` and displays license notification
-- Installs git hooks automatically
-- Always exits 0 (never breaks `npm install`)
-- Safe to run multiple times (idempotent)
+### Existing Git Hooks
 
-### Existing Hooks
+LicenseGuard **never overwrites** existing hooks. If conflicts exist:
 
-If you already have git hooks, LicenseGuard will NOT overwrite them. Instead, it creates variants:
-- `.git/hooks/licenseguard-pre-commit`
-- `.git/hooks/licenseguard-post-checkout`
+- Creates `licenseguard-post-checkout` and `licenseguard-pre-commit`
+- Shows warning with merge instructions
 
-You can manually merge these with your existing hooks if desired.
+### Non-Git Projects
 
-### Without Git
+LicenseGuard works without git:
+- `init` offers to run `git init`
+- `init --fast` creates LICENSE file only
+- Hooks are skipped with warning
 
-If your project is not a git repository:
-- Interactive mode (`--init`) will offer to run `git init`
-- Fast mode (`--init-fast`) will skip hooks and warn you
-- `--setup` command will skip hooks with a warning
-- LICENSE file is always created regardless of git status
+---
 
 ## FAQ
 
-### Does this work offline?
-Yes! LicenseGuard is completely offline. All license templates are bundled with the package.
-
-### Can I use custom licenses?
-Currently, LicenseGuard supports the 6 most common open source licenses. Custom license support may be added in future versions.
+### What licenses are checked during scanning?
 
-### Does it work on Windows?
-Yes! LicenseGuard is fully cross-platform and works on Linux, macOS, and Windows.
+LicenseGuard **auto-detects your project type** and scans the appropriate ecosystem:
+- **Node.js**: Reads `package.json` and `node_modules/*/package.json`
+- **C/C++**: Reads Conan metadata via `conan graph info`
+- **Rust**: Reads `cargo metadata` JSON output
+- **Python**: Uses native Python `importlib.metadata` (98.6% detection rate)
+- **Go**: Reads `go.mod` and scans `GOMODCACHE` with streaming NDJSON
 
-### What if I already have a LICENSE file?
-Interactive mode will ask if you want to overwrite it. Fast mode will overwrite without asking.
+All ecosystems check:
+- SPDX license identifiers (MIT, Apache-2.0, GPL-3.0, BSD-3-Clause, ISC, etc.)
+- License compatibility using industry-standard rules
+- Copyleft vs permissive conflicts (e.g., GPL incompatible with MIT)
+- Multi-strategy detection including Jaccard Index similarity matching
 
-### How do I update my license?
-Run `licenseguard --init` again and it will regenerate your LICENSE file.
+Mixed-language projects are not yet supported. Use `--noscan` flag if detection is incorrect.
 
-### Can I disable the git hooks?
-The hooks are informational only and don't block anything. If you don't want them, simply delete the hook files from `.git/hooks/`.
+### How does SPDX compatibility work?
 
-### What Node.js versions are supported?
-LicenseGuard requires Node.js 18.x or 20.x (LTS versions).
+LicenseGuard uses [spdx-satisfies](https://www.npmjs.com/package/spdx-satisfies) for compatibility checking:
+- **Permissive licenses** (MIT, Apache, BSD, ISC) - Compatible with most licenses
+- **Copyleft licenses** (GPL-3.0) - Incompatible with permissive project licenses
+- **Unknown licenses** - Generates warnings but doesn't block
+- **Custom rules** - Fallback for non-SPDX licenses (WTFPL, proprietary)
 
-## Contributing
+### What is the scanResult for?
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+`scanResult` is optional transparency data you can commit to show:
+1. Your project has validated license compliance
+2. When dependencies were last scanned
+3. What conflicts (if any) were detected
+4. Trust signal for users and contributors (like CI badges)
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+You choose whether to save it after each scan. Clean scans default to YES, conflicts default to NO.
 
-## Development
+### Can I skip dependency scanning?
 
+Yes! Use the `--noscan` flag:
 ```bash
-# Clone the repository
-git clone https://github.com/your-username/licenseguard.git
-cd licenseguard
+licenseguard init --noscan
+```
+
+This is useful for:
+- Non-JavaScript projects
+- Projects without dependencies
+- When you want manual license management
+
+### Does this work for non-JavaScript projects?
+
+**Yes!** LicenseGuard natively supports 5 ecosystems:
+- **Node.js** - Full dependency scanning
+- **C/C++** - Conan package scanning (requires Conan 2.x or 1.x installed)
+- **Rust** - Cargo crate scanning (requires Cargo installed)
+- **Python** - Native package scanning with 98.6% accuracy (requires Python 3.7+)
+- **Go** - Go module scanning (requires Go installed)
+
+For other languages (Ruby, PHP, etc.), the LICENSE file and git hooks still work, but dependency scanning is not yet available. Use `--noscan` flag for those projects.
+
+The hooks only need Node.js installed (which most developers have).
+
+### Do my contributors need to install LicenseGuard?
 
-# Install dependencies
-npm install
+For automatic notifications: **Yes**, they need `npm install -g licenseguard-cli` once.
 
-# Run tests
-npm test
+Alternative: Use npm prepare script (see Advanced Usage) - then only project owner installs.
 
-# Run tests with coverage
-npm run test:coverage
+### Does this work offline?
+
+Yes! All license templates are bundled. No internet required.
 
-# Lint code
-npm run lint
+### Can I disable notifications?
 
-# Format code
-npm run format
+Delete hooks from `.git/hooks/`:
+```bash
+rm .git/hooks/post-checkout .git/hooks/pre-commit
+```
 
-# Test locally
-npm link
-cd /tmp && mkdir test-project && cd test-project
-licenseguard --init
+Or remove global hooks:
+```bash
+rm -rf ~/.git-templates/hooks/
+git config --global --unset init.templateDir
 ```
 
+### What Node.js versions work?
+
+Node.js 18.x or 20.x (LTS versions).
+
+### Does it work on Windows?
+
+Yes! Fully cross-platform (Linux, macOS, Windows).
+
+---
+
+## Why LicenseGuard?
+
+- **Not enforcing** - Unlike license scanners, we inform and educate
+- **Zero friction** - One global install, automatic forever
+- **Universal** - Works with any language/framework
+- **Educational** - Raises awareness without blocking workflows
+- **Open source** - MIT licensed, free forever
+
+---
+
+## Contributing
+
+Contributions welcome!
+
+1. Fork the repository
+2. Create feature branch: `git checkout -b feature/amazing`
+3. Commit changes: `git commit -m 'Add feature'`
+4. Push: `git push origin feature/amazing`
+5. Open Pull Request
+
+---
+
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+MIT License - see [LICENSE](LICENSE) file.
 
 ---
 
-**Links:**
-- [Choose a License](https://choosealicense.com) - Help choosing the right license
-- [Open Source Initiative](https://opensource.org/licenses) - OSI-approved licenses
-- [GitHub Repository](https://github.com/your-username/licenseguard) - Source code
-- [npm Package](https://www.npmjs.com/package/licenseguard-cli) - npm registry
+## Links
+
+- [npm Package](https://www.npmjs.com/package/licenseguard-cli)
+- [Choose a License](https://choosealicense.com)
+- [Open Source Initiative](https://opensource.org/licenses)