preship 2.0.8 → 2.0.10

package/README.md

@@ -1,144 +1,535 @@
-# PreShip
+<p align="center">
+  <h1 align="center">PreShip</h1>
+  <p align="center"><strong>Pre-ship verification for modern dev teams.</strong></p>
+  <p align="center">License compliance + Security vulnerabilities + Secret detection — all in one command.</p>
+</p>
 
-**License compliance for modern dev teams.** Detect GPL, AGPL, EUPL, and other
-problematic licenses in your dependencies before you ship.
+<p align="center">
+  <a href="https://www.npmjs.com/package/preship"><img src="https://img.shields.io/npm/v/preship.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/preship"><img src="https://img.shields.io/npm/dm/preship.svg" alt="npm downloads"></a>
+  <a href="https://github.com/dipen-code/preship/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="License"></a>
+  <a href="https://badge.socket.dev/npm/package/preship"><img src="https://badge.socket.dev/npm/package/preship" alt="Socket Badge"></a>
+  <a href="https://github.com/dipen-code/preship"><img src="https://img.shields.io/github/stars/dipen-code/preship?style=social" alt="GitHub Stars"></a>
+</p>
 
-Zero config. Fully offline. Completely free.
+---
 
-Works with: npm, yarn, pnpm (Node.js, React, Next.js, and more)
+## What is PreShip?
 
-Created by [Cyfox Inc.](https://www.cyfox.tech)
+PreShip is a **free, open-source CLI tool** that runs three critical checks on your project before you ship:
+
+| Check | What it catches | How |
+|-------|----------------|-----|
+| **License Compliance** | GPL, AGPL, EUPL, SSPL and other problematic licenses in your dependency tree | Parses lockfile, resolves licenses via npm registry / GitHub / local |
+| **Security Vulnerabilities** | Known CVEs + deprecated, outdated, and unmaintained packages | Queries [OSV.dev](https://osv.dev) + npm registry health data |
+| **Secret Detection** | Leaked API keys, tokens, private keys, database URLs in source code | 38 regex rules + Shannon entropy analysis |
+
+**Zero config. No signup. No API keys. Works offline.**
+
+---
 
 ## Quick Start
 
-**Run once (no install):**
+### Run instantly (no install needed)
+
 ```bash
 npx preship scan
 ```
 
-**Add to your project:**
+That's it. PreShip detects your package manager, parses your lockfile, and runs all three checks.
+
+### Install in your project
+
 ```bash
 npm install --save-dev preship
+```
+
+Then add it to your `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "preshipcheck": "preship scan",
+    "prebuild": "preship scan"
+  }
+}
+```
+
+Now every `npm run build` automatically verifies your project before building.
+
+### Set up config and build hooks
+
+```bash
 npx preship init
 ```
 
-No signup. No cloud. No API keys. Just answers.
+This creates a `preship-config.yml` and optionally adds pre-build hooks to your project.
+
+---
+
+## How It Works
+
+```
+npx preship scan
+        |
+        v
+  [1] Detect project
+      - Reads package.json
+      - Finds lockfile (npm / yarn / pnpm)
+      - Detects framework (React, Next.js, Vue, Nuxt, Angular, Svelte, Express...)
+        |
+        v
+  [2] Parse dependencies
+      - Extracts all packages + versions from lockfile
+      - Separates direct vs transitive, dev vs production
+        |
+        v
+  [3] Run scan modules (in parallel)
+      |
+      ├── License:   Resolve license for each package → Apply policy
+      ├── Security:  Query OSV.dev for CVEs → Check npm for deprecated/outdated
+      └── Secrets:   Walk source files → Match 38 rules + entropy check
+        |
+        v
+  [4] Output results
+      - Summary table with pass/fail per module
+      - Grouped failures (critical + high)
+      - Grouped warnings (medium + low)
+      - Exit code 1 if any module fails
+```
+
+---
+
+## Sample Output
+
+```
+🔍 PreShip: Pre-ship verification
+   Project: my-app (nextjs)
+   Lock file: package-lock.json (npm)
+   Policy: commercial-safe  |  Mode: auto
+   Modules: license, security, secrets
+
+📊 Scan Summary                                Total time: 6.9s
+┌────────────┬────────────┬─────────┬─────────┬──────────┬─────────┬────────┐
+│ Module     │ Scanned    │ Passed  │ Issues  │ Warnings │ Status  │ Time   │
+├────────────┼────────────┼─────────┼─────────┼──────────┼─────────┼────────┤
+│ License    │ 534 pkgs   │ 533     │ 0       │ 1        │ PASS    │ 0.1s   │
+│ Security   │ 534 pkgs   │ --      │ 6       │ 4        │ FAIL    │ 6.9s   │
+│ Secrets    │ 166 files  │ --      │ 0       │ 0        │ PASS    │ 0.0s   │
+└────────────┴────────────┴─────────┴─────────┴──────────┴─────────┴────────┘
+
+📜 License Compliance — ✅ 533 passed, 1 warning
+🔑 Secret Detection — ✅ No issues found
+
+❌ Failures
+   🛡️  Security Vulnerabilities — 6 high
+   Health Issues:
+      ├── [HIGH] glob@10.3.10 — package is deprecated
+      └── ... and 4 more
+
+⚠️  Warnings
+   📜 License Compliance — 1 weak copyleft
+      └── axe-core@4.11.1 — MPL-2.0
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+❌ RESULT: 1 of 3 checks failed
+💡 To fix:
+   • Update packages with known vulnerabilities
+   • Replace deprecated or unmaintained packages
+```
+
+---
+
+## Supported Frameworks & Package Managers
+
+### Package Managers
+
+| Manager | Lockfile | Versions |
+|---------|----------|----------|
+| **npm** | `package-lock.json` | v1, v2, v3 |
+| **Yarn** | `yarn.lock` | v1, v2+ |
+| **pnpm** | `pnpm-lock.yaml` | v5, v6, v9+ |
 
-## What It Does
+### Frameworks (auto-detected)
 
-Every npm package you install comes with a license. Some licenses (like GPL
-and AGPL) require you to open-source your entire codebase if you distribute
-your software. PreShip catches these before they become a legal problem.
+React, Next.js, Vue.js, Nuxt.js, Angular, Svelte, SvelteKit, Express, Fastify, NestJS
 
-**One command. Three seconds. Done.**
+Framework detection is automatic — PreShip reads your `package.json` and identifies the framework for display. **All frameworks scan identically** — detection is informational only.
 
-## Commands
+---
+
+## All CLI Commands
+
+### `preship scan` — Run all checks
+
+```bash
+npx preship scan                          # Full scan (all 3 modules)
+npx preship scan --no-security            # Skip security scanning
+npx preship scan --no-secrets             # Skip secret detection
+npx preship scan --no-license             # Skip license checking
+npx preship scan --license-only           # Legacy: license scan only
+npx preship scan --strict                 # Fail on any warnings
+npx preship scan --dev                    # Include devDependencies
+npx preship scan --format json            # JSON output (for CI/CD)
+npx preship scan --format csv             # CSV output
+npx preship scan --mode local             # Offline mode (zero network calls)
+npx preship scan --silent                 # No output, exit code only
+npx preship scan --scan-timeout 120000    # Custom timeout (ms)
+npx preship scan --no-cache               # Skip encrypted cache
+```
+
+**Security-specific flags:**
+
+```bash
+npx preship scan --security-severity strict    # strict | default | lenient
+npx preship scan --security-fail-on critical   # critical | high | medium | low
+npx preship scan --no-deprecated               # Ignore deprecated packages
+npx preship scan --no-outdated                 # Ignore outdated packages
+npx preship scan --no-unmaintained             # Ignore unmaintained packages
+```
+
+### `preship init` — Set up config
+
+```bash
+npx preship init                    # Interactive setup
+npx preship init --policy strict    # Use strict policy
+npx preship init --skip-hooks       # Don't add build hooks
+```
+
+### `preship list` — Show findings
 
 ```bash
-preship scan                    # Scan for license violations
-preship scan --strict           # Fail on warnings too
-preship scan --dev              # Include devDependencies
-preship scan --format json      # JSON output for CI/CD
-preship scan --mode local       # Fully offline, zero network
+npx preship list                    # All module findings
+npx preship list --license-only     # License info only
+npx preship list --filter GPL-3.0   # Filter by license
+npx preship list --format csv       # CSV output
+```
+
+### `preship report` — Generate reports
 
-preship init                    # Set up config and build hooks
-preship list                    # Show all deps and their licenses
-preship report                  # Generate NOTICE/attribution file
-preship allow <pkg> --reason "" # Add a package exception
+```bash
+npx preship report                                    # Full compliance report
+npx preship report --license-only                     # License NOTICE file
+npx preship report --out compliance.json --format json # JSON export
+```
+
+### `preship allow <package>` — Add exceptions
+
+```bash
+npx preship allow readline-sync --reason "Internal CLI only, not distributed"
 ```
 
-## Features
+---
 
-- **Zero config** -- works out of the box with commercial-safe defaults
-- **Build gate** -- blocks builds when violations are found (exit code 1)
-- **Fast** -- scans 200+ packages in under 3 seconds
-- **Fully offline** -- `--mode local` requires zero network access
-- **Air-gap safe** -- your code and dependency data never leave your machine
-- **Encrypted cache** -- AES-256-CBC encrypted, project-level
-- **Multiple formats** -- terminal, JSON, CSV output
-- **3 resolution modes** -- auto (default), online, local
-- **Configurable** -- custom policies, exceptions, overrides
+## Features in Detail
 
-## Policy Templates
+### License Compliance
+
+PreShip resolves the license for every package in your dependency tree using a multi-source resolution chain:
+
+```
+1. Encrypted cache (instant, no network)
+2. npm registry API (most reliable)
+3. GitHub API (fallback for uncommon packages)
+4. Local node_modules/ (air-gap environments)
+5. UNKNOWN (if all sources fail)
+```
+
+Each resolved license is then evaluated against your chosen policy. Results are categorized as **allowed**, **warned**, **rejected**, or **unknown**.
+
+**5 built-in policy templates:**
 
 | Policy | Rejects | Warns | Best For |
 |--------|---------|-------|----------|
 | **commercial-safe** (default) | GPL, AGPL, EUPL, SSPL | LGPL, MPL | SaaS, commercial apps |
-| **strict** | All copyleft (GPL + LGPL + MPL) | Nothing | Distributed/embedded software |
-| **permissive-only** | Everything not explicitly allowed | Nothing | Maximum legal safety |
+| **saas-safe** | AGPL, SSPL | LGPL, MPL | SaaS applications |
+| **distribution-safe** | All copyleft risky for distribution | MPL-2.0 | Desktop apps, binaries |
+| **strict** | All copyleft (GPL + LGPL + MPL) | — | Embedded/distributed software |
+| **permissive-only** | Everything not explicitly allowed | — | Maximum legal safety |
+
+### Security Vulnerability Scanning
+
+PreShip checks your dependencies against two sources:
+
+**Vulnerability database ([OSV.dev](https://osv.dev)):**
+- Covers CVEs, GHSAs, and ecosystem-specific advisories
+- Batch queries for performance (one API call for all packages)
+- No API key required, completely free
+
+**Package health checks (npm registry):**
+- **Deprecated** — Package author marked it as deprecated (HIGH severity)
+- **Outdated** — Major version behind latest (MEDIUM severity)
+- **Unmaintained** — No updates in 2+ years (MEDIUM severity)
+
+**Severity → Action mapping:**
+
+| Severity | Classification | Default Behavior |
+|----------|---------------|-----------------|
+| Critical | Issue | Fails scan |
+| High | Issue | Fails scan |
+| Medium | Warning | Reported, doesn't fail |
+| Low | Warning | Reported, doesn't fail |
+
+### Secret Detection
+
+PreShip scans your source code for accidentally committed credentials:
+
+**38 detection rules covering:**
+- Cloud providers: AWS, GCP, Azure access keys and secrets
+- API services: GitHub, GitLab, Stripe, Slack, Twilio, SendGrid, Mailgun
+- Databases: MongoDB, PostgreSQL, MySQL, Redis connection strings
+- Auth: JWTs, OAuth tokens, bearer tokens, private keys (RSA/EC/PGP)
+- Generic: passwords, API keys, high-entropy hex/base64 strings
+
+**Smart exclusions (never scanned):**
+- `node_modules/`, `.git/`, `dist/`, build output
+- `.env` and `.env.*` files (expected to contain secrets)
+- Binary files (images, fonts, etc.)
+- Lockfiles (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`)
+- Minified files and files larger than 1MB
+
+**Shannon entropy analysis** catches secrets that don't match any rule pattern but have suspiciously high randomness (hex strings > 3.5 bits/char, base64 > 4.0 bits/char).
+
+---
 
 ## Configuration
 
-Create `preship-config.yml` in your project root (or run `preship init`):
+Create `preship-config.yml` in your project root (or run `npx preship init`):
 
 ```yaml
-# Policy template: commercial-safe | strict | permissive-only
-policy: commercial-safe
+# Policy template
+policy: commercial-safe    # commercial-safe | saas-safe | distribution-safe | strict | permissive-only
 
-# Scan devDependencies?
-scanDevDependencies: false
+# Module toggles (all enabled by default)
+modules:
+  license: true
+  security: true
+  secrets: true
 
-# Flag packages with no detectable license?
+# Resolution mode
+mode: auto                 # auto | online | local
+
+# License settings
+scanDevDependencies: false
 flagUnknown: true
 
-# Package exceptions:
+# Custom license overrides
+# reject:
+#   - CUSTOM-LICENSE
+# allow:
+#   - BSD-3-Clause-No-Nuclear-License
 # exceptions:
-#   - package: some-package
-#     reason: "Used internally only"
+#   - package: some-internal-package
+#     reason: "Used internally only, not distributed"
 #     approvedBy: your-name
-#     date: 2026-02-12
+#     date: 2025-01-15
+
+# Security settings
+# security:
+#   severity: default          # default | strict | lenient
+#   failOn: high               # critical | high | medium | low
+#   checkOutdated: true
+#   checkDeprecated: true
+#   checkUnmaintained: true
+
+# Secrets settings
+# secrets:
+#   allowPaths: []             # Glob paths to skip
+#   allowRules: []             # Rule IDs to disable (e.g., generic-password)
 ```
 
+---
+
+## Resolution Modes
+
+| Mode | What it does | Network | Cache | Best for |
+|------|-------------|---------|-------|----------|
+| **auto** (default) | Cache → npm registry → GitHub API → local node_modules | Yes | Yes | Daily development |
+| **online** | Cache → npm registry → GitHub API (no local fallback) | Yes | Yes | CI/CD without node_modules |
+| **local** | Local node_modules only | None | No | Air-gapped / offline environments |
+
+```bash
+npx preship scan --mode auto      # Default
+npx preship scan --mode online    # Registry only
+npx preship scan --mode local     # Zero network calls
+```
+
+---
+
 ## CI/CD Integration
 
+### GitHub Actions
+
 ```yaml
-# GitHub Actions
-- name: License check
-  run: npx preship scan --format json
+name: PreShip Check
+on: [push, pull_request]
+
+jobs:
+  preship:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - run: npx preship scan
+```
+
+### As a pre-commit hook
 
-# GitLab CI
-license-check:
-  script:
-    - npx preship scan --strict
+```bash
+npx preship init    # Adds hooks automatically
 ```
 
-PreShip exits with code 1 on violations, so it naturally gates your pipeline.
+Or manually in `package.json`:
+
+```json
+{
+  "scripts": {
+    "precommit": "preship scan --silent",
+    "prebuild": "preship scan"
+  }
+}
+```
+
+### JSON output for pipelines
+
+```bash
+npx preship scan --format json > preship-report.json
+```
+
+---
 
 ## Programmatic API
 
+PreShip can be used as a library in your own tools:
+
 ```typescript
-import { scan } from 'preship';
+import { scan, unifiedScan } from 'preship';
+import type { ScanResult, UnifiedScanResult } from 'preship';
+
+// Full unified scan (all modules)
+const result: UnifiedScanResult = await unifiedScan({
+  projectPath: './my-project',
+});
+
+console.log(result.passed);                     // true if ALL modules pass
+console.log(result.modules.license?.rejected);   // License violations
+console.log(result.modules.security?.findings);  // Security findings
+console.log(result.modules.secrets?.findings);   // Secret findings
+
+// Configure specific modules
+const secOnly = await unifiedScan({
+  config: {
+    modules: { license: false, security: true, secrets: false },
+    security: { failOn: 'critical' },
+  },
+});
+
+// Offline scan
+const offline = await unifiedScan({
+  config: { mode: 'local' },
+});
+
+// Legacy: license-only scan
+const licenseResult: ScanResult = await scan({
+  projectPath: './my-project',
+});
+```
 
-const result = await scan({ projectPath: './my-project' });
+Individual packages are also available:
 
-console.log(result.passed);        // true/false
-console.log(result.rejected);      // PolicyResult[]
-console.log(result.totalPackages); // number
+```bash
+npm install @preship/license     # License scanning API
+npm install @preship/security    # Vulnerability checking API
+npm install @preship/secrets     # Secret detection API
 ```
 
+---
+
+## Performance
+
+| Feature | Detail |
+|---------|--------|
+| **Parallel scanning** | All 3 modules run concurrently via `Promise.all()` |
+| **Encrypted cache** | AES-256-CBC encrypted, 7-day TTL, instant license lookups on repeat scans |
+| **Adaptive rate limiting** | Reads `X-RateLimit-*` headers, backs off proportionally |
+| **Scan timeout** | 60s default (configurable, 0 = disabled), AbortController-based |
+| **Batch vulnerability queries** | One API call to OSV.dev for all packages |
+| **Keyword prefiltering** | Secrets scanner skips files with no keyword matches |
+
+Typical scan: **500+ packages in under 10 seconds** (with cache).
+
+---
+
 ## License Cheat Sheet
 
-| License | Risk | PreShip Verdict |
-|---------|------|-----------------|
-| MIT, BSD, ISC | None | Allowed |
-| Apache-2.0 | None (+ patent grant) | Allowed |
-| LGPL-2.1/3.0 | Moderate (linking rules) | Warning |
-| MPL-2.0 | Low (file-level copyleft) | Warning |
-| GPL-2.0/3.0 | High (viral copyleft) | Rejected |
-| AGPL-3.0 | Very High (SaaS killer) | Rejected |
-| SSPL-1.0 | Very High (AGPL on steroids) | Rejected |
-| UNKNOWN | Unknown | Flagged |
+| License | What it means | Default verdict |
+|---------|---------------|-----------------|
+| MIT, BSD, ISC | Do whatever you want, keep the copyright | Allowed |
+| Apache-2.0 | Same + patent grant | Allowed |
+| LGPL-2.1/3.0 | OK if dynamically linked, risky if static | Warning |
+| MPL-2.0 | Must share modifications to MPL files only | Warning |
+| GPL-2.0/3.0 | Must open-source your entire codebase | Rejected |
+| AGPL-3.0 | GPL + network use triggers it (SaaS killer) | Rejected |
+| EUPL-1.2 | European GPL equivalent | Rejected |
+| SSPL-1.0 | AGPL on steroids (MongoDB license) | Rejected |
+| UNKNOWN | No license detected | Flagged |
+
+---
+
+## Use Cases
+
+- **Startups** — Clean up before investor due diligence
+- **Agencies** — Scan client projects before delivery
+- **Enterprise** — Gate CI/CD pipelines without paying $20K+/year for Snyk/FOSSA
+- **Open source maintainers** — Keep your dependency tree clean
+- **Regulated industries** — Finance, healthcare, defense — air-gapped scanning with `--mode local`
+- **Security teams** — Catch leaked secrets before they hit production
 
-## Coming Soon
+---
+
+## Architecture
+
+PreShip is a monorepo with feature-based packages:
+
+```
+preship/
+  packages/
+    core/       @preship/core      Config, parsers, cache, rate limiter, types
+    license/    @preship/license   License compliance scanning
+    security/   @preship/security  Vulnerability + health scanning
+    secrets/    @preship/secrets   Secret/credential detection
+  apps/
+    cli/        preship            Unified CLI
+```
+
+---
+
+## Requirements
+
+- **Node.js 18+** (uses native `fetch` — no HTTP library dependency)
+- A lockfile (`package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml`)
+
+---
+
+## Contributing
+
+Contributions are welcome! PreShip is Apache-2.0 licensed.
+
+```bash
+git clone https://github.com/dipen-code/preship.git
+cd preship
+npm install
+npm run build
+npm test        # 613 tests across 21 test files
+```
 
-- **Security scanning** -- vulnerability detection via OSV.dev + GitHub Advisory
-- **Secret detection** -- catch leaked API keys, tokens, credentials
-- **PreShip Enterprise** -- dashboard, team policies, audit trail, SBOM export
+---
 
-## Links
+## License
 
-- **GitHub**: [github.com/dipen-code/preship](https://github.com/dipen-code/preship)
-- **Issues**: [github.com/dipen-code/preship/issues](https://github.com/dipen-code/preship/issues)
-- **License**: Apache 2.0
+**Apache-2.0** — fully open source, free for commercial use.
 
-Made with care by [Cyfox Inc.](https://www.cyfox.tech) in Chicago, IL.
+Created by [Cyfox Inc.](https://www.cyfox.tech) (Chicago, IL)

package/dist/cli.js

@@ -4018,7 +4018,7 @@ function registerAllowCommand(program2) {
 
 // src/cli.ts
 var program = new import_commander.Command();
-program.name("preship").description("Pre-ship verification: license compliance, security scanning, and secret detection \u2014 all before you ship.").version("2.0.8");
+program.name("preship").description("Pre-ship verification: license compliance, security scanning, and secret detection \u2014 all before you ship.").version("2.0.10");
 registerScanCommand(program);
 registerInitCommand(program);
 registerListCommand(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "preship",
-  "version": "2.0.8",
+  "version": "2.0.10",
   "description": "Pre-ship verification for modern dev teams. License compliance, security vulnerability scanning, and secret detection — all in one CLI. Zero config. Fully offline. Free forever.",
   "keywords": [
     "license",