licenseguard-cli 2.1.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

@@ -269,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 |

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)
@@ -37,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/scan.js

@@ -5,7 +5,6 @@
 
 const chalk = require('chalk')
 const fs = require('fs')
-const path = require('path')
 const { scanDependencies, displayConflictReport } = require('../scanner')
 const { detectLicenseFromText } = require('../scanner/license-detector')
 
@@ -41,7 +40,9 @@ function detectProjectLicense() {
     try {
       const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'))
       if (pkg.license) return pkg.license
-    } catch (e) {}
+    } catch (e) {
+      // Ignore malformed package.json
+    }
   }
 
   if (fs.existsSync('Cargo.toml')) {

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
+}

package/lib/scanner/index.js

@@ -8,6 +8,9 @@ const chalk = require('chalk')
 // Import explainCompatibility for --explain flag support
 const { explainCompatibility } = require('./compat-checker')
 
+// Import color mapper for license color-coding
+const { colorizeWithEmoji } = require('./color-mapper')
+
 // Import ecosystem plugins
 const nodePlugin = require('./plugins/node')
 const cppPlugin = require('./plugins/cpp')
@@ -83,10 +86,13 @@ function displayConflictReport(scanResult, projectLicense, options = {}) {
   }
 
   for (const issue of scanResult.issues) {
+    // Color-code the license based on safety level
+    const coloredLicense = colorizeWithEmoji(issue.license, issue.license)
+
     if (issue.type === 'conflict') {
-      console.log(chalk.red(`❌ ${issue.package} (${issue.license})`))
+      console.log(chalk.red(`❌ ${issue.package} (${coloredLicense})`))
     } else {
-      console.log(chalk.yellow(`⚠️  ${issue.package} (${issue.license})`))
+      console.log(chalk.yellow(`⚠️  ${issue.package} (${coloredLicense})`))
     }
     console.log(chalk.gray(`   ${issue.reason}`))
     console.log(chalk.gray(`   Location: ${issue.location}`))

package/lib/scanner/license-detector.js

@@ -42,7 +42,7 @@ const LICENSE_HEADER_PATTERNS = {
     /\(mit\)/i
   ],
   'BSD-3-Clause': [
-    /bsd\s+3[- ]clause\s+(license|\"new\")/i,
+    /bsd\s+3[- ]clause\s+(license|"new")/i,
     /\b3[- ]clause\s+bsd\b/i
   ],
   'BSD-2-Clause': [

package/lib/scanner/plugins/go.js

@@ -192,7 +192,6 @@ function getGoModulesSync() {
 
     // Parse NDJSON (newline-delimited JSON)
     const modules = []
-    let buffer = ''
     let braceCount = 0
     let startIdx = 0
     let inString = false

package/lib/scanner/plugins/python.js

@@ -167,7 +167,7 @@ function parsePyprojectToml() {
  * @param {string} manager - Package manager (for error messages)
  * @returns {Object} Map of { packageName: licenseString }
  */
-function getLicensesBatch(packageNames, manager) {
+function getLicensesBatch(packageNames, _manager) {
   if (packageNames.length === 0) return {}
 
   const CHUNK_SIZE = 100  // Process in chunks to avoid stdin size limits

package/lib/utils/update-notifier.js

@@ -0,0 +1,141 @@
+const https = require('https')
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const chalk = require('chalk')
+
+const CACHE_FILE = path.join(os.tmpdir(), 'licenseguard-update-check')
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000 // 24 hours
+const FETCH_TIMEOUT_MS = 5000 // 5 seconds
+
+/**
+ * Fetch package version info from npm registry
+ * @param {string} packageName - Package name to check
+ * @returns {Promise<Object>} - Package metadata from npm registry
+ */
+function fetchNpmVersion(packageName) {
+  return new Promise((resolve, reject) => {
+    const options = {
+      hostname: 'registry.npmjs.org',
+      path: `/${packageName}`,
+      method: 'GET',
+      timeout: FETCH_TIMEOUT_MS
+    }
+
+    const req = https.request(options, (res) => {
+      let data = ''
+
+      res.on('data', (chunk) => {
+        data += chunk
+      })
+
+      res.on('end', () => {
+        try {
+          const parsed = JSON.parse(data)
+          resolve(parsed)
+        } catch (error) {
+          reject(new Error('Failed to parse npm registry response'))
+        }
+      })
+    })
+
+    req.on('error', (error) => {
+      reject(error)
+    })
+
+    req.on('timeout', () => {
+      req.destroy()
+      reject(new Error('npm registry request timeout'))
+    })
+
+    req.end()
+  })
+}
+
+/**
+ * Check if cached result is still valid
+ * @returns {boolean} - True if cache exists and is fresh
+ */
+function isCacheValid() {
+  if (!fs.existsSync(CACHE_FILE)) {
+    return false
+  }
+
+  try {
+    const stat = fs.statSync(CACHE_FILE)
+    const age = Date.now() - stat.mtimeMs
+    return age < CACHE_TTL_MS
+  } catch (error) {
+    return false
+  }
+}
+
+/**
+ * Compare two semantic version strings
+ * @param {string} current - Current version (e.g., "2.1.0")
+ * @param {string} latest - Latest version (e.g., "2.2.0")
+ * @returns {boolean} - True if latest is newer than current
+ */
+function isNewerVersion(current, latest) {
+  const currentParts = current.split('.').map(Number)
+  const latestParts = latest.split('.').map(Number)
+
+  for (let i = 0; i < 3; i++) {
+    if (latestParts[i] > currentParts[i]) return true
+    if (latestParts[i] < currentParts[i]) return false
+  }
+
+  return false // Versions are equal
+}
+
+/**
+ * Display update banner in terminal
+ * @param {string} current - Current version
+ * @param {string} latest - Latest available version
+ */
+function displayUpdateBanner(current, latest) {
+  console.log(chalk.yellow('\n╔═══════════════════════════════════════════════╗'))
+  console.log(chalk.yellow(`║  Update available: ${current} → ${latest}              ║`))
+  console.log(chalk.yellow('║  Run: npm install -g licenseguard-cli@latest  ║'))
+  console.log(chalk.yellow('╚═══════════════════════════════════════════════╝\n'))
+}
+
+/**
+ * Check for updates from npm registry (with caching)
+ * Non-blocking, silent failure on errors
+ * @param {string} currentVersion - Current version from package.json
+ * @returns {Promise<void>}
+ */
+async function checkForUpdates(currentVersion) {
+  try {
+    // Check cache validity
+    if (isCacheValid()) {
+      return // Skip check - cache is fresh
+    }
+
+    // Fetch latest version from npm registry
+    const data = await fetchNpmVersion('licenseguard-cli')
+    const latestVersion = data['dist-tags'].latest
+
+    // Cache result
+    fs.writeFileSync(CACHE_FILE, latestVersion, 'utf8')
+
+    // Compare versions and display banner if update available
+    if (isNewerVersion(currentVersion, latestVersion)) {
+      displayUpdateBanner(currentVersion, latestVersion)
+    }
+  } catch (error) {
+    // Silent failure - don't block user or pollute output
+    // Network issues, timeouts, parsing errors all handled gracefully
+  }
+}
+
+module.exports = {
+  checkForUpdates,
+  displayUpdateBanner,
+  isNewerVersion,
+  fetchNpmVersion,
+  isCacheValid,
+  CACHE_FILE,
+  CACHE_TTL_MS
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "licenseguard-cli",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "License setup & compliance guard for developers",
   "bin": {
     "licenseguard": "bin/licenseguard.js"