@adhix11/shipguard

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