licenseguard-cli 2.1.1 → 2.3.0

package/CHANGELOG.md

@@ -5,6 +5,95 @@ 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.3.0] - 2026-02-21
+
+### Added
+
+- **ESM (ECMAScript Module) Support** - Git hooks now work in ESM projects
+  - Auto-detects ESM projects via `package.json` `"type": "module"`
+  - Generates ESM-compatible git hooks using `import` syntax for ESM projects
+  - Generates CommonJS hooks using `require` syntax for CJS projects
+  - `isEsmProject()` utility function for ESM detection
+  - ESM hook generators: `generatePostCheckoutScriptEsm()`, `generatePreCommitScriptEsm()`
+  - ESM global hooks in `postinstall.js` for `npm install -g` compatibility
+  - Full test coverage: 23 unit tests + 5 integration tests
+  - Backward compatible - existing CJS projects unaffected
+
+## [2.2.0] - 2025-11-25
+
+### Added
+
+- **Friction-Free Adoption (Dual-Mode Init)** - `scan` command now adapts to environment
+  - **Interactive Mode**: Prompts user to initialize configuration when missing (TTY)
+  - **CI/CD Mode**: Auto-detects project license from package manager files (no TTY or CI env)
+  - **Multi-Ecosystem Auto-Detection**: Supports Node.js, Rust, Python, Go, and C++
+  - **Graceful Fallback**: Clear error messages with setup instructions when auto-detect fails
+  - License auto-detection functions: `autoDetectLicense()`, `detectNodeLicense()`, `detectRustLicense()`, `detectPythonLicense()`, `detectGoLicense()`, `detectCppLicense()`
+  - `isInteractive()` helper to detect TTY vs CI/CD environments
+  - `isValidLicense()` validator to check for valid license strings (excludes UNLICENSED and empty)
+
+- **Deep Scan Engine** - Complete dependency visibility for Node.js projects
+  - Parses `package-lock.json` to find ALL packages including transitive dependencies
+  - Supports lockfile v1 (npm 5-6), v2 (npm 7-8), v3 (npm 9+)
+  - Automatically detects lockfile version and uses appropriate parser
+  - Graceful fallback to flat scan when lockfile missing or corrupt
+  - **30x improvement** in package discovery: Typical React project goes from 50 packages (flat) → 1500+ packages (deep)
+  - **~99% coverage** with deep scan vs ~15% with flat scan
+  - Zero configuration required - works automatically when lockfile present
+
+- **Dependency Path Visualization** - Shows exact dependency chains for license conflicts
+  - Automatically traces paths for GPL conflicts: "app → @facebook/folly → liburing"
+  - Uses npm's built-in `npm explain` command (npm 7+ required)
+  - Lazy evaluation: Only traces paths when conflicts detected (performance optimized)
+  - Caching to avoid duplicate subprocess calls (5 second timeout per package)
+  - Graceful fallback: Displays conflicts without paths when npm explain unavailable
+  - Answers the key question: "Where did this GPL package come from?"
+  - Enables instant decision-making: Remove direct dependency or find alternative
+
+- **Coverage Report** - Automatic scan transparency for trust building
+  - Shows "X/Y packages identified (Z%)" after every scan
+  - Visual indicators: ✅ (90%+ excellent), ⚠️ (70-89% good), ❌ (<70% needs attention)
+  - Percentage formatted to 1 decimal place for precision
+  - Always displayed by default (no flag needed)
+  - Educational tip shown when coverage < 80%: "💡 Tip: Some packages may need manual LICENSE file inspection"
+  - Displays BEFORE conflict report in `init` command
+  - Displays at end of output in `scan` command
+  - Builds user trust through transparency about scan completeness
+
+- **HTML Attribution Generator** - Mobile-ready CREDITS.html for App Store compliance
+  - New `--format html` flag on `scan` command generates attribution file
+  - Mobile-optimized responsive design (max-width 800px desktop, full-width mobile)
+  - System fonts for instant loading: `-apple-system, BlinkMacSystemFont, Segoe UI, Roboto`
+  - Touch-friendly: 44px minimum touch targets (iOS accessibility guideline)
+  - Dark mode support: Automatic light/dark theme adaptation
+  - Expandable license text: Click "Show license text" to view full license
+  - Alphabetical sorting: Packages sorted by name for easy navigation
+  - XSS safe: All user content properly escaped (prevents script injection)
+  - Single file: Inline CSS and JavaScript (no external dependencies)
+  - Ready to bundle: Works with iOS (Xcode + WKWebView) and Android (assets + WebView)
+  - Meets App Store requirements: iOS App Store and Google Play Store attribution compliance
+  - Zero configuration: `licenseguard scan --format html` generates `CREDITS.html`
+
+### Changed
+- **`scan` command behavior**: Now checks for `.licenseguardrc` before requiring license specification
+  - Interactive mode offers to run `init` instead of throwing error
+  - CI/CD mode attempts auto-detection before erroring out
+  - Scan command continues seamlessly after interactive init completes
+- Node.js scanner now uses deep scan (lockfile parsing) by default when lockfile available
+- Flat scan preserved as fallback for projects without lockfiles
+- Scan output now includes coverage statistics by default
+- Coverage report appears in both `init` and `scan` commands automatically
+- Significantly improved dependency discovery accuracy for Node.js projects
+
+### Technical Details
+- New module: `lib/scanner/deep-scan.js` - Lockfile parser (v1/v2/v3 support)
+- New module: `lib/scanner/path-tracer.js` - npm explain adapter for dependency paths
+- Modified: `lib/scanner/plugins/node.js` - Integrated deep scan with fallback logic
+- Modified: `lib/scanner/index.js` - displayConflictReport now async, traces paths for conflicts
+- Modified: `lib/commands/scan.js` - Awaits displayConflictReport for path tracing
+- Test coverage: 100% for deep-scan.js and path-tracer.js modules
+- All 762 tests passing with zero regressions
+
 ## [2.1.1] - 2025-11-25
 
 ### Added

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,43 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## The "No Elitism" Clause
+
+LicenseGuard was built by a solo developer learning the ropes. We value **grit** and **learning** over certificates and titles.
+
+*   **No Gatekeeping:** Do not belittle contributors for "bad code" or "being junior." Teach, don't preach.
+*   **Practicality over Purity:** We prefer code that works and is readable over "clever" one-liners that no one understands.
+*   **Respect the Craft:** Take pride in what you ship. Code is communication.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+*   Demonstrating empathy and kindness toward other people
+*   Being respectful of differing opinions, viewpoints, and experiences
+*   Giving and gracefully accepting constructive feedback
+*   Accepting responsibility and apologizing to those affected by our mistakes
+*   Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+*   The use of sexualized language or imagery, and sexual attention or advances of any kind
+*   Trolling, insulting or derogatory comments, and personal or political attacks
+*   Public or private harassment
+*   Publishing others' private information, such as a physical or email address, without their explicit permission
+*   Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org

package/CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing to LicenseGuard
+
+First off, thank you for considering contributing to LicenseGuard. This project is built on the belief that license compliance should be **fast, free, and accessible** to every developer.
+
+## The LicenseGuard Philosophy
+
+Before you write a single line of code, please understand the core values that built this tool:
+
+1.  **Zero Bloat Policy** 🚀
+    *   We prefer native Node.js APIs (`fs`, `child_process`, `path`) over adding heavy dependencies.
+    *   Current dependencies are minimal (chalk, commander, inquirer). Keep it that way.
+    *   If you can write it in 20 lines of utility code, don't install a 5MB library.
+
+2.  **Ecosystem Native** 🧠
+    *   Don't force one logic on all languages.
+    *   **Node.js** uses file parsing (`package.json`) because it's fast.
+    *   **Python** uses IPC bridge (`python-license-scanner.py`) because pip is chaotic.
+    *   **Go/Rust** uses CLI tools (`go list`, `cargo metadata`) because they are authoritative.
+    *   *Rule:* Research the ecosystem's standard first. Don't guess.
+
+3.  **Fail-Safe Architecture** 🛡️
+    *   This is a polyglot tool. If the user doesn't have `conan` installed, the C++ scanner should fail silently with a warning. It MUST NOT crash the Node.js scan.
+    *   Always wrap plugin execution in `try-catch`.
+
+4.  **"Feel Code"** ✍️
+    *   Understand what you are parsing. Don't just regex blindly.
+    *   Read the lockfiles. Understand the graph.
+
+## Development Setup
+
+1.  **Clone and Install:**
+    ```bash
+    git clone https://github.com/rfxlamia/licenseguard.git
+    cd licenseguard
+    npm install
+    ```
+
+2.  **Run Tests:**
+    We take testing seriously.
+    ```bash
+    npm test
+    ```
+    *Current Benchmark:* 635+ tests passing in ~3 seconds. Do not make it slower.
+
+3.  **Manual Testing:**
+    Automated tests are not enough. Verify your changes against real projects.
+    See `manual-test/` directory for reference projects (Node, C++, Python).
+
+## Pull Request Guidelines
+
+*   **Branch Naming:** `feat/feature-name` or `fix/bug-name`.
+*   **Commit Messages:** Follow [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `feat: add ruby support`, `fix: handle corrupt lockfile`).
+*   **Tests:** Every PR **MUST** include unit tests. Code coverage should not drop below 90%.
+*   **Documentation:** Update `README.md` if you add a new feature or flag.
+
+## Adding a New Ecosystem Plugin
+
+Want to add support for Ruby, PHP, or Java?
+1.  Create `lib/scanner/plugins/language.js`.
+2.  Implement the standard interface:
+    *   `detect()`: Boolean
+    *   `scanDependencies(projectLicense)`: Promise<Result>
+3.  Register it in `lib/scanner/index.js`.
+4.  Add comprehensive unit tests in `tests/unit/scanner-language.test.js`.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under its MIT License.

package/README.md

@@ -5,7 +5,7 @@
 
 > License setup & compliance guard for developers
 
-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.).
+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 across ecosystems (Node.js, Python, Rust, Go, C++).
 
 ## Key Features
 
@@ -15,7 +15,6 @@ LicenseGuard helps you set up open source licenses and protects your project fro
 - **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
 
 ---
@@ -189,7 +188,7 @@ Fix conflicts or use --force to proceed anyway:
   licenseguard init --force
 ```
 
-**With Explanation (`--explain`):**
+### `init --explain` - With Explanation
 ```bash
 licenseguard init --explain
 # ...
@@ -269,73 +268,8 @@ Reads existing `.licenseguardrc` and installs hooks. Used in npm prepare scripts
 
 ---
 
-## Color-coded Output
+## Supported License Setup
 
-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 |
 |-----|------|-------------|
@@ -535,12 +469,46 @@ Yes! Fully cross-platform (Linux, macOS, Windows).
 ## Contributing
 
 Contributions welcome!
+**We need your help to make LicenseGuard better.**
+
+---
+
+### How to Contribute
+
+1. Read [CONTRIBUTING.md](CONTRIBUTING.md) - Philosophy and guidelines
+2. Check [GitHub Issues](https://github.com/rfxlamia/licenseguard-development/issues) for "good first issue" label
+3. Fork repository
+4. Create branch: `git checkout -b feat/license-mpl2`
+5. Write tests (90%+ coverage required)
+6. Submit Pull Request
+
+**Philosophy:**
+- **Zero Bloat** - Prefer native APIs over dependencies
+- **Ecosystem Native** - Research the right tool, don't guess
+- **Fail-Safe** - Plugins fail gracefully, never crash
+- **Feel Code** - Understand what you parse
 
-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
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.
+
+---
+
+## Code of Conduct
+
+We're committed to an inclusive community. Read our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+**Key principles:**
+- **No Elitism** - Grit and learning > credentials
+- **No Gatekeeping** - Teach, don't preach
+- **Practicality > Purity** - Readable > clever
+- **Respect the Craft** - Code is communication
+
+---
+
+## Documentation
+
+- **[QUICK-USE.md](QUICK-USE.md)** - Complete command reference and examples
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** - How to contribute
+- **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** - Community standards
 
 ---
 
@@ -553,5 +521,9 @@ MIT License - see [LICENSE](LICENSE) file.
 ## Links
 
 - [npm Package](https://www.npmjs.com/package/licenseguard-cli)
+- [GitHub Repository](https://github.com/rfxlamia/licenseguard)
+- [Quick Use Guide](QUICK-USE.md)
+- [Contributing Guide](CONTRIBUTING.md)
 - [Choose a License](https://choosealicense.com)
-- [Open Source Initiative](https://opensource.org/licenses)
+- [SPDX License List](https://spdx.org/licenses/)
+

package/bin/licenseguard.js

@@ -52,6 +52,7 @@ program
   .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('--format <type>', 'Output format (html) - generates CREDITS.html for mobile apps')
   .option('--cwd <path>', 'Working directory to scan')
   .action(async (options) => {
     try {

package/lib/commands/init-fast.js

@@ -74,7 +74,7 @@ async function runInitFast(options) {
         console.log(chalk.blue('🔍 Scanning dependencies for license conflicts...\n'))
 
         scanResult = await scanDependencies(spdxLicense)
-        const hasConflicts = displayConflictReport(scanResult, spdxLicense)
+        const hasConflicts = await displayConflictReport(scanResult, spdxLicense)
 
         if (hasConflicts && !options.force) {
           // Block LICENSE creation due to conflicts

package/lib/commands/init.js

@@ -5,6 +5,7 @@ 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')
+const { calculateCoverage, displayCoverage } = require('../scanner/coverage-reporter')
 
 async function runInit(options = {}) {
   try {
@@ -59,7 +60,12 @@ async function runInit(options = {}) {
         console.log(chalk.blue('\n🔍 Scanning dependencies for license conflicts...\n'))
 
         scanResult = await scanDependencies(spdxLicense)
-        const hasConflicts = displayConflictReport(scanResult, spdxLicense, { explain: options.explain })
+
+        // Display coverage BEFORE conflict report (AC #3)
+        const coverage = calculateCoverage(scanResult)
+        displayCoverage(coverage)
+
+        const hasConflicts = await displayConflictReport(scanResult, spdxLicense, { explain: options.explain })
 
         if (hasConflicts && !options.force) {
           // Block LICENSE creation due to conflicts