🚢 ShipGuard

Catch costly production mistakes before you ship.

A zero-config preflight scanner for JavaScript and TypeScript projects. Detect secrets, missing env docs, debug code, risky test flags, and basic package readiness before you ship.

Why?

Developers often forget small but critical things before pushing code:

| Pain | Example | |------|---------| | Secret leakage | AWS key, JWT secret, DB password inside code | | Missing env docs | Code uses process.env.DB_URL, but .env.example doesn't mention it | | Debug code | console.log, debugger, temporary test code left in | | Test mistakes | describe.only, it.only, skipped tests | | Risky package scripts | Suspicious postinstall, preinstall, shell commands | | Poor release readiness | No README, no LICENSE, missing package.json fields |

With AI-generated code accelerating development, the bottleneck has shifted from writing code to reviewing and validating it. ShipGuard helps you catch the things that slip through.

Quick Start

Run with zero setup:

npx @adhix11/shipguard

Or install globally:

npm install -g @adhix11/shipguard
shipguard

What It Scans

🔐 Secrets Risk

• AWS Access Keys & Secret Keys
• Private key blocks (-----BEGIN PRIVATE KEY-----)
• MongoDB connection URIs (mongodb+srv://...)
• Hardcoded passwords (password = "...")
• JWT secrets
• API keys & tokens (GitHub, OpenAI, Stripe, Slack)

📋 Missing Env Documentation

• Finds all process.env.XYZ and import.meta.env.XYZ in your code
• Cross-references with .env.example
• Reports any environment variables missing from documentation

🐛 Debug Code

• console.log, console.debug, console.warn
• debugger statements
• TODO, FIXME, HACK, XXX comments
• alert() calls

🧪 Test Risk

• describe.only(), it.only(), test.only() — focused tests
• describe.skip(), it.skip(), test.skip() — skipped tests
• fdescribe, fit, xit, xdescribe — Jasmine equivalents

📦 Package Health

• README.md exists
• LICENSE exists
• package.json has name, version, description
• Entry point (main, bin, module, or exports) is defined
• Risky lifecycle scripts (postinstall, preinstall) with suspicious commands

Example Output

🚢 ShipGuard Report
──────────────────────────────────────────────────

❌ Secrets Risk
  src/config/db.ts
  ✗ Possible MongoDB URI found (line 8)

⚠️ Missing Env Documentation
  .env.example
  ● .env.example is missing 3 variables:
  ● Missing: DB_URL
  ● Missing: JWT_SECRET
  ● Missing: AWS_REGION

⚠️ Debug Code Found
  src/app.ts
  ● console.log found (line 42)

❌ Test Risk
  src/__tests__/user.test.ts
  ✗ it.only found — other tests will be skipped (line 18)

──────────────────────────────────────────────────
Summary:
  2 critical issues
  4 warnings

✗ Run failed. Fix critical issues before shipping.

CLI Options

| Option | Description | |--------|-------------| | --strict | Treat warnings as errors (exit code 1 for any issue) | | --json | Output results as JSON for CI/CD integration | | --ignore <dirs> | Comma-separated directories to ignore | | --help, -h | Show help message | | --version, -v | Show version number |

Examples

# Basic scan
npx @adhix11/shipguard

# Strict mode — fail on any warning
npx @adhix11/shipguard --strict

# JSON output for CI pipelines
npx @adhix11/shipguard --json

# Ignore specific directories
npx @adhix11/shipguard --ignore "dist,build,coverage"

Default Ignores

ShipGuard automatically skips these directories:

node_modules, dist, build, .git, .next, .nuxt, coverage, .cache, .turbo, .output, out

And these files: *.min.js, *.min.css, *.map, package-lock.json, yarn.lock, pnpm-lock.yaml

CI/CD Integration

GitHub Actions

- name: ShipGuard Preflight Check
  run: npx @adhix11/shipguard --strict

Pre-commit Hook (with Husky)

npx husky add .husky/pre-commit "npx @adhix11/shipguard"

Exit Codes

| Code | Meaning | |------|---------| | 0 | All clear (or warnings only without --strict) | | 1 | Critical issues found (or warnings in --strict mode) | | 2 | ShipGuard internal error |

License

MIT © adhix11