licenseguard-cli 2.0.0 → 2.1.1

package/CHANGELOG.md

@@ -0,0 +1,210 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.1.1] - 2025-11-25
+
+### Added
+- **Color-coded License Output** - Visual safety hierarchy for quick risk assessment
+  - Green (🟢): Permissive licenses (MIT, Apache-2.0, BSD-*, ISC)
+  - Yellow (⚠️): Weak copyleft (MPL-2.0, LGPL-*)
+  - Red (❌): Strong copyleft (GPL-*, AGPL-*)
+  - Gray (❔): Unknown licenses (requires manual review)
+  - Emojis as secondary indicators for accessibility (colorblind-friendly)
+  - Works in both light and dark terminal themes
+- **Update Notifier** - Automatic update notifications
+  - Checks npm registry once per 24 hours
+  - Displays banner when newer version available
+  - Non-blocking (doesn't slow down CLI startup)
+  - Fails silently if network unavailable
+  - Cache stored in OS temp directory
+
+### Changed
+- All license output now color-coded in `init` command
+- Conflict reports now show visual safety indicators
+
+## [2.1.0] - 2025-11-23
+
+### Added
+
+#### Multi-Ecosystem Dependency Scanning
+- **C/C++ (Conan) Support**
+  - Scans Conan 2.x and 1.x projects
+  - Auto-detects `conanfile.txt` and `conanfile.py`
+  - Tested with Facebook's folly library (23 dependencies, found 3 real GPL conflicts)
+  - Prevents GPL contamination in MIT/Apache projects
+- **Rust (Cargo) Support**
+  - Scans Cargo projects via `cargo metadata --format-version 1`
+  - Auto-detects `Cargo.toml`
+  - 100% test coverage
+- **Python (pip/pipenv/poetry) Support**
+  - **Native Python scanner** using `importlib.metadata` (IPC Bridge approach)
+  - **98.6% detection rate** (342/347 packages) vs 9.2% with pip show parsing
+  - Auto-detects `requirements.txt`, `Pipfile`, `pyproject.toml`
+  - Priority: poetry > pipenv > pip
+  - 37 license normalizations for Python ecosystem quirks
+  - Batch optimization (30x faster than individual calls)
+- **Go (modules) Support**
+  - Scans Go modules with streaming NDJSON for large projects
+  - Dynamic cache detection via `go env GOMODCACHE`
+  - Auto-detects `go.mod`
+  - Jaccard Index matching for LICENSE files (no package metadata fallback)
+
+- **Authoritative Source Citations (--explain)**
+  - Added `--explain` flag to `init` and `scan` commands
+  - Shows citations from FSF, OSI, and Mozilla for compatibility decisions
+  - Provides direct URLs to license text and compatibility matrices
+  - Helps developers verify "Why is this a conflict?" with legal backing
+
+#### Advanced License Detection
+- **Jaccard Index License Detector** (5-layer multi-strategy detection)
+  - Layer 1: SPDX-License-Identifier headers (fastest)
+  - Layer 2: License header/title detection (for full license texts)
+  - Layer 3: Dual-license pattern detection
+  - Layer 4: Key phrase patterns (distinctive phrases)
+  - Layer 5: Jaccard similarity matching (edge cases)
+  - Reduced Go scan warnings from 27 to 7
+  - Handles BSD-2-Clause vs BSD-3-Clause differentiation
+  - Universal detector usable across all ecosystems
+- **GPL Contamination Prevention**
+  - Detects copyleft licenses in transitive dependency trees
+  - Real-world validation: Found 3 GPL conflicts in folly's 23-dependency tree
+  - Business value: Prevents license violations before production
+
+### Changed
+
+#### Architecture
+- **Plugin Architecture** - Refactored from monolithic to pluggable ecosystem plugins
+  - `lib/scanner/plugins/node.js` - Node.js scanner (extracted from monolithic v2.0)
+  - `lib/scanner/plugins/cpp.js` - C/C++ Conan scanner
+  - `lib/scanner/plugins/rust.js` - Rust Cargo scanner
+  - `lib/scanner/plugins/python.js` - Python scanner with IPC bridge
+  - `lib/scanner/plugins/go.js` - Go modules scanner
+- **Auto-detection** - Scanner now auto-detects project type (Node > C++ > Rust > Python > Go priority)
+- **Node.js Scanner** - Backward compatible, all Epic 2 tests still passing
+
+### Technical
+
+#### New Files
+- `lib/scanner/plugins/cpp.js` - Conan plugin (87% coverage)
+- `lib/scanner/plugins/rust.js` - Cargo plugin (100% coverage)
+- `lib/scanner/plugins/python.js` - Python plugin with IPC bridge (98% coverage)
+- `lib/scanner/plugins/python-license-scanner.py` - Native Python scanner script
+- `lib/scanner/plugins/go.js` - Go modules plugin (92% coverage)
+- `lib/scanner/plugins/node.js` - Refactored Node.js scanner (100% coverage)
+- `lib/scanner/license-detector.js` - Jaccard Index multi-strategy detector (85% coverage)
+
+#### Test Growth
+- **635 tests** (was 132 in v2.0.0) - **+503 tests, +381% growth**
+- **19 test suites** (was ~10 in v2.0.0)
+- **0 regressions** - All Epic 2 tests passing
+- **Coverage:**
+  - Plugins: 94.37% (target: >80%)
+  - License detector: 85.41% (target: >80%)
+  - Overall: 84.46% statements, 75.95% branches
+
+#### Dependencies
+- No new npm dependencies added (uses child_process for ecosystem tools)
+
+#### Performance
+- Node.js: <1s for 1500 packages
+- Python: ~1-2s for 347 packages (IPC Bridge overhead)
+- C++: <1s for 23 packages (Conan metadata parsing)
+- Rust: <1s for typical project
+- Go: <1s for typical project
+
+### Breaking Changes
+None - Fully backward compatible with v2.0.0
+
+### Known Limitations
+- Mixed-language projects not yet supported (auto-detection picks first match)
+- Python requires Python 3.7+ installed
+- C++ requires Conan 1.x or 2.x installed
+- Rust requires Cargo installed
+- Go requires Go installed
+
+---
+
+**Epic 3 Completed:** Multi-Ecosystem Scanner Support
+**Stories Completed:** 3.0 (Plugin Architecture), 3.1 (C++), 3.2 (Rust), 3.3 (Python), 3.4 (Go), plus 2 hotfixes (compat-checker, license-detector)
+
+## [2.0.0] - 2025-11-18
+
+### BREAKING CHANGES
+
+#### CLI Architecture Migration
+- **Migrated from flag-based to subcommand-based routing**
+  - Old: `licenseguard --init` → New: `licenseguard init`
+  - Old: `licenseguard --ls` → New: `licenseguard ls`
+  - Old: `licenseguard --setup` → New: `licenseguard setup`
+- **Rationale:** Subcommands provide better CLI semantics and enable future extensibility
+- **Migration:** Update all scripts and documentation to use new syntax
+- **Backward compatibility:** Use `--noscan` flag for v1.x behavior without dependency scanning
+
+### Added
+
+#### License Compliance Guard 
+- **Dependency license scanning during init**
+  - Scans all npm dependencies for license conflicts
+  - Reads `package.json` and `node_modules/*/package.json`
+  - Displays scan summary with compatible/incompatible/unknown counts
+- **SPDX license compatibility checking**
+  - Uses `spdx-satisfies` for industry-standard compatibility rules
+  - Checks copyleft vs permissive conflicts (e.g., GPL-3.0 incompatible with MIT)
+  - Supports complex license expressions (e.g., "MIT OR Apache-2.0")
+- **Conflict detection with blocking**
+  - LICENSE creation blocked if incompatible licenses detected
+  - Exits with code 1 and error message
+  - Shows detailed conflict report with package names, licenses, and reasons
+- **scanResult persistence to .licenseguardrc**
+  - Optional field to save scan results for transparency
+  - Includes timestamp, counts, and issues array
+  - Acts as compliance badge (like CI or coverage badges)
+  - Prompt with smart defaults: YES for clean scans, NO for conflicts
+- **--force flag to override blocking**
+  - Creates LICENSE despite conflicts when user explicitly accepts risks
+  - Shows warnings but allows proceeding
+  - Useful for false positives or acceptable conflicts
+- **--noscan flag for v1.x compatibility**
+  - Skips dependency scanning entirely
+  - Maintains v1.x behavior for non-JavaScript projects
+  - No scanResult generated or saved
+
+### Changed
+
+- **Help text improved** - Now shows subcommands with descriptions
+- **Error messages enhanced** - More actionable feedback for common issues
+- **CLI routing refactored** - Cleaner subcommand architecture
+- **Init command enhanced** - Integrated scanning after license selection, before file creation
+- **Init-fast command enhanced** - Auto-saves clean scan results, skips saving on conflicts
+- **Configuration format extended** - `.licenseguardrc` now supports optional `scanResult` field
+
+### Technical
+
+#### New Dependencies
+- `spdx-satisfies@5.x` - SPDX license compatibility checking
+- `spdx-expression-parse@4.x` - Parse SPDX license expressions
+
+#### New Modules
+- `lib/scanner/index.js` - Dependency scanner with conflict detection
+- `lib/compat/rules.js` - License compatibility rules engine
+
+#### Test Coverage
+- Added scanner unit tests
+- Added file-ops scanResult handling tests
+- Maintained 86%+ coverage target
+
+## [1.1.0] - 2025-11-17
+
+### Added
+- Initial public release (Epic 1)
+- Interactive license setup (`init` command)
+- Fast mode for CI/CD (`init --fast`)
+- 6 embedded license templates (MIT, Apache 2.0, GPL 3.0, BSD 3-Clause, ISC, WTFPL)
+- Git hooks for license notifications (post-checkout, pre-commit)
+- Global hooks installation via npm postinstall
+- `.licenseguardrc` configuration file
+- Cross-platform support (Linux, macOS, Windows)

package/README.md

@@ -9,7 +9,7 @@ LicenseGuard helps you set up open source licenses and protects your project fro
 
 ## Key Features
 
-- **Dependency Scanning** - Scans npm dependencies for license conflicts during setup
+- **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
@@ -20,6 +20,20 @@ LicenseGuard helps you set up open source licenses and protects your project fro
 
 ---
 
+## 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)
@@ -175,9 +189,21 @@ 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
 
@@ -243,6 +269,72 @@ Reads existing `.licenseguardrc` and installs hooks. Used in npm prepare scripts
 
 ---
 
+## Color-coded Output
+
+LicenseGuard uses visual safety hierarchy with color-coding to help you quickly identify dangerous licenses:
+
+### Safety Level Legend
+
+| Color | Emoji | License Type | Examples |
+|-------|-------|--------------|----------|
+| 🟢 **Green** | Safe | Permissive licenses | MIT, Apache-2.0, BSD-*, ISC, 0BSD, Unlicense |
+| ⚠️ **Yellow** | Caution | Weak copyleft | MPL-2.0, LGPL-*, EPL-* |
+| ❌ **Red** | Dangerous | Strong copyleft | GPL-*, AGPL-* |
+| ❔ **Gray** | Unknown | Requires manual review | UNKNOWN, unrecognized licenses |
+
+### How It Works
+
+Licenses are automatically color-coded in all commands (`init`, `scan`) based on their safety level:
+
+- **Green licenses** (🟢) are permissive and safe to use - they allow you to do almost anything
+- **Yellow licenses** (⚠️) require caution - they have some copyleft restrictions
+- **Red licenses** (❌) are strong copyleft - they may require your project to use the same license
+- **Gray licenses** (❔) are unknown or unrecognized - manual review required
+
+**Example Output:**
+```bash
+licenseguard scan
+
+❌ 2 issue(s) found:
+
+❌ some-gpl-lib@2.0.0 (❌ GPL-3.0)
+   Conflict: Copyleft incompatible with MIT
+   Location: node_modules/some-gpl-lib/package.json
+
+⚠️  unknown-lib@1.0.0 (❔ UNKNOWN)
+   No license field found
+   Location: node_modules/unknown-lib/package.json
+```
+
+### Accessibility
+
+Colors work in both light and dark terminal themes, and emojis are used as secondary indicators for colorblind users:
+- Green = 🟢 (green circle)
+- Yellow = ⚠️ (warning triangle)
+- Red = ❌ (red X)
+- Gray = ❔ (question mark)
+
+---
+
+## Update Notifications
+
+LicenseGuard automatically checks for updates once per day (cached for 24 hours). When a new version is available, you'll see:
+
+```bash
+╔═══════════════════════════════════════════════╗
+║  Update available: 2.1.0 → 2.1.1              ║
+║  Run: npm install -g licenseguard-cli@latest  ║
+╚═══════════════════════════════════════════════╝
+```
+
+**Update check behavior:**
+- Checks npm registry once per 24 hours
+- Non-blocking (doesn't slow down CLI startup)
+- Fails silently if network unavailable
+- Result cached in OS temp directory
+
+---
+
 ## Supported Licenses
 
 | Key | Name | Description |
@@ -339,12 +431,20 @@ LicenseGuard works without git:
 
 ### What licenses are checked during scanning?
 
-Scans **npm dependencies only** (reads `package.json` and `node_modules`). It checks:
+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
+
+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
 
-For non-JavaScript projects, use `--noscan` flag.
+Mixed-language projects are not yet supported. Use `--noscan` flag if detection is incorrect.
 
 ### How does SPDX compatibility work?
 
@@ -378,12 +478,14 @@ This is useful for:
 
 ### Does this work for non-JavaScript projects?
 
-**Yes!** LicenseGuard works for any project:
-- Python projects
-- Rust/Cargo projects
-- Go modules
-- Ruby gems
-- Any language
+**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).
 

package/bin/licenseguard.js

@@ -6,7 +6,14 @@ const { version } = require('../package.json')
 const { runList } = require('../lib/commands/list')
 const { runInit } = require('../lib/commands/init')
 const { runInitFast } = require('../lib/commands/init-fast')
+const { runScan } = require('../lib/commands/scan')
 const { setupCommand } = require('../lib/commands/setup')
+const { checkForUpdates } = require('../lib/utils/update-notifier')
+
+// Check for updates (non-blocking, silent failure)
+checkForUpdates(version).catch(() => {
+  // Silent failure - don't block user
+})
 
 program
   .version(version)
@@ -18,6 +25,7 @@ program
   .description('Interactive license setup with dependency scanning')
   .option('--force', 'Create LICENSE despite conflicts')
   .option('--noscan', 'Skip dependency scanning')
+  .option('--explain', 'Show authoritative source citations for license compatibility decisions')
   .option('--fast', 'Non-interactive mode with auto-detection')
   .option('--license <type>', 'License type (for --fast mode)')
   .option('--owner <name>', 'Copyright owner name (for --fast mode)')
@@ -36,6 +44,24 @@ program
     }
   })
 
+// Scan command
+program
+  .command('scan')
+  .description('Scan dependencies for license conflicts')
+  .option('--license <type>', 'Specify project license (if not auto-detected)')
+  .option('--allow', 'Allow conflicts (exit 0 even if conflicts found)')
+  .option('--fail-on-unknown', 'Fail if unknown licenses detected')
+  .option('--explain', 'Show authoritative source citations for license compatibility decisions')
+  .option('--cwd <path>', 'Working directory to scan')
+  .action(async (options) => {
+    try {
+      await runScan(options)
+    } catch (error) {
+      console.error(chalk.red('✗ Error:'), error.message)
+      process.exit(1)
+    }
+  })
+
 // List command
 program
   .command('ls')

package/lib/commands/init-fast.js

@@ -6,6 +6,7 @@ const { generateLicense, LICENSE_TEMPLATES } = require('../templates')
 const { writeConfig } = require('../utils/file-ops')
 const { isGitRepo, installHooks } = require('../utils/git-helpers')
 const { scanDependencies, displayConflictReport } = require('../scanner')
+const { toSPDX } = require('../utils/license-mapper')
 
 function getGitConfig(key) {
   try {
@@ -67,16 +68,7 @@ async function runInitFast(options) {
     // Scanner integration (Story 2.3) - Fast mode
     let scanResult = null
     if (!options.noscan) {
-      // Convert internal license format to SPDX identifier
-      const licenseToSPDX = {
-        'mit': 'MIT',
-        'apache2_0': 'Apache-2.0',
-        'gpl3_0': 'GPL-3.0',
-        'bsd3clause': 'BSD-3-Clause',
-        'isc': 'ISC',
-        'wtfpl': 'WTFPL'
-      }
-      const spdxLicense = licenseToSPDX[flags.license] || flags.license.toUpperCase()
+      const spdxLicense = toSPDX(flags.license)
 
       try {
         console.log(chalk.blue('🔍 Scanning dependencies for license conflicts...\n'))

package/lib/commands/init.js

@@ -4,6 +4,7 @@ const { generateLicense } = require('../templates')
 const { writeLicenseFile, writeConfig } = require('../utils/file-ops')
 const { isGitRepo, initGitRepo, installHooks } = require('../utils/git-helpers')
 const { scanDependencies, displayConflictReport } = require('../scanner')
+const { toSPDX } = require('../utils/license-mapper')
 
 async function runInit(options = {}) {
   try {
@@ -52,22 +53,13 @@ async function runInit(options = {}) {
     // Scanner integration (Story 2.3)
     let scanResult = null
     if (!options.noscan) {
-      // Convert internal license format to SPDX identifier
-      const licenseToSPDX = {
-        'mit': 'MIT',
-        'apache2_0': 'Apache-2.0',
-        'gpl3_0': 'GPL-3.0',
-        'bsd3clause': 'BSD-3-Clause',
-        'isc': 'ISC',
-        'wtfpl': 'WTFPL'
-      }
-      const spdxLicense = licenseToSPDX[answers.license] || answers.license.toUpperCase()
+      const spdxLicense = toSPDX(answers.license)
 
       try {
         console.log(chalk.blue('\n🔍 Scanning dependencies for license conflicts...\n'))
 
         scanResult = await scanDependencies(spdxLicense)
-        const hasConflicts = displayConflictReport(scanResult, spdxLicense)
+        const hasConflicts = displayConflictReport(scanResult, spdxLicense, { explain: options.explain })
 
         if (hasConflicts && !options.force) {
           // Block LICENSE creation due to conflicts

package/lib/commands/scan.js

@@ -0,0 +1,122 @@
+/**
+ * Scan Command Handler
+ * Runs dependency scanning without modifying project files
+ */
+
+const chalk = require('chalk')
+const fs = require('fs')
+const { scanDependencies, displayConflictReport } = require('../scanner')
+const { detectLicenseFromText } = require('../scanner/license-detector')
+
+/**
+ * Try to detect project license from local files
+ * @returns {string|null} Detected license or null
+ */
+function detectProjectLicense() {
+  // 1. Try .licenseguardrc
+  if (fs.existsSync('.licenseguardrc')) {
+    try {
+      const config = JSON.parse(fs.readFileSync('.licenseguardrc', 'utf8'))
+      if (config.license) return config.license
+    } catch (e) {
+      // Ignore config error
+    }
+  }
+
+  // 2. Try LICENSE file
+  const licenseFiles = ['LICENSE', 'LICENSE.txt', 'LICENSE.md', 'COPYING']
+  for (const file of licenseFiles) {
+    if (fs.existsSync(file)) {
+      const content = fs.readFileSync(file, 'utf8')
+      const detected = detectLicenseFromText(content)
+      if (detected && detected !== 'UNKNOWN') {
+        return detected
+      }
+    }
+  }
+
+  // 3. Try package managers (basic check)
+  if (fs.existsSync('package.json')) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'))
+      if (pkg.license) return pkg.license
+    } catch (e) {
+      // Ignore malformed package.json
+    }
+  }
+
+  if (fs.existsSync('Cargo.toml')) {
+    // TODO: Parse Cargo.toml for license
+  }
+
+  return null
+}
+
+/**
+ * Run the scan command
+ * @param {Object} options - Command options
+ */
+async function runScan(options) {
+  // 1. Handle CWD
+  if (options.cwd) {
+    try {
+      process.chdir(options.cwd)
+    } catch (error) {
+      throw new Error(`Failed to change directory to ${options.cwd}: ${error.message}`)
+    }
+  }
+
+  console.log(chalk.blue(`📂 Scanning in: ${process.cwd()}`))
+
+  // 2. Determine Project License
+  let projectLicense = options.license
+
+  if (!projectLicense) {
+    projectLicense = detectProjectLicense()
+    if (projectLicense) {
+      console.log(chalk.blue(`ℹ️  Detected project license: ${projectLicense}`))
+    }
+  }
+
+  if (!projectLicense) {
+    throw new Error(
+      'Could not determine project license.\n' +
+      'Please create a LICENSE file, use "licenseguard init", or specify --license <type>'
+    )
+  }
+
+  // 3. Run Scan
+  console.log(chalk.gray('🔍 Scanning dependencies...'))
+  
+  try {
+    const results = await scanDependencies(projectLicense)
+
+    // 4. Display Report
+    const hasConflicts = displayConflictReport(results, projectLicense, {
+      explain: options.explain
+    })
+
+    // 5. Handle Exit Code
+    if (hasConflicts && !options.allow) {
+      console.log(chalk.red('\n❌ Scan failed: License conflicts detected.'))
+      process.exit(1)
+    } else if (hasConflicts && options.allow) {
+      console.log(chalk.yellow('\n⚠️  Scan passed (conflicts allowed via flag).'))
+    } 
+    
+    // Handle unknown licenses if fail-on-unknown flag is set
+    if (options.failOnUnknown && results.unknown > 0) {
+      console.log(chalk.red('\n❌ Scan failed: Unknown licenses detected (--fail-on-unknown).'))
+      process.exit(1)
+    }
+
+  } catch (error) {
+    // Check for specific plugin errors
+    if (error.message.includes('No supported package manager')) {
+      throw new Error('No supported package manager found (package.json, go.mod, Cargo.toml, etc.)')
+    }
+    throw error
+  }
+}
+
+module.exports = { runScan }

package/lib/scanner/color-mapper.js

@@ -0,0 +1,87 @@
+const chalk = require('chalk')
+
+// License color mapping based on safety level
+const LICENSE_COLORS = {
+  // Green: Permissive licenses
+  'MIT': 'green',
+  'Apache-2.0': 'green',
+  'BSD-2-Clause': 'green',
+  'BSD-3-Clause': 'green',
+  'ISC': 'green',
+  '0BSD': 'green',
+  'Unlicense': 'green',
+
+  // Yellow: Weak copyleft
+  'MPL-2.0': 'yellow',
+  'LGPL-2.1': 'yellow',
+  'LGPL-3.0': 'yellow',
+  'EPL-1.0': 'yellow',
+  'EPL-2.0': 'yellow',
+
+  // Red: Strong copyleft
+  'GPL-2.0': 'red',
+  'GPL-3.0': 'red',
+  'AGPL-3.0': 'red',
+
+  // Gray: Unknown
+  'UNKNOWN': 'gray'
+}
+
+// Emoji indicators for accessibility
+const EMOJI_INDICATORS = {
+  green: '🟢',
+  yellow: '⚠️',
+  red: '❌',
+  gray: '❔'
+}
+
+/**
+ * Get color for a given license
+ * @param {string} license - License identifier (e.g., "MIT", "GPL-3.0")
+ * @returns {string} - Color name (green/yellow/red/gray)
+ */
+function getColor(license) {
+  return LICENSE_COLORS[license] || 'gray'
+}
+
+/**
+ * Get emoji indicator for a given license
+ * @param {string} license - License identifier
+ * @returns {string} - Emoji indicator
+ */
+function getEmoji(license) {
+  const color = getColor(license)
+  return EMOJI_INDICATORS[color]
+}
+
+/**
+ * Colorize text based on license safety level
+ * @param {string} license - License identifier
+ * @param {string} text - Text to colorize
+ * @returns {string} - Colorized text with chalk
+ */
+function colorize(license, text) {
+  const color = getColor(license)
+  return chalk[color](text)
+}
+
+/**
+ * Colorize text with emoji indicator
+ * @param {string} license - License identifier
+ * @param {string} text - Text to colorize
+ * @returns {string} - Colorized text with emoji prefix
+ */
+function colorizeWithEmoji(license, text) {
+  const emoji = getEmoji(license)
+  const coloredText = colorize(license, text)
+  return `${emoji} ${coloredText}`
+}
+
+module.exports = {
+  getColor,
+  getEmoji,
+  colorize,
+  colorizeWithEmoji,
+  LICENSE_COLORS,
+  EMOJI_INDICATORS
+}