Ship Parity

Deployment-readiness checks for projects that work locally or in preview but fail after release. Ship Parity detects framework/provider/package-manager drift, secret exposure patterns, runtime mismatch, missing environment names, private origins, debug leftovers, and contract violations without uploading the repository.

Position in the ecosystem

shipready is a broad AI-coded repository pre-flight scanner that also generates agent files. @decocms/parity compares two deployed URLs with browser, functional, SEO, network, and visual checks. Ship Parity is the local pre-deployment contract layer: it validates what the project declares and what the source tree references before a build or deployment is attempted.

Install

npm install --save-dev ship-parity
npx ship-parity --help

Node.js 20 or newer is required.

Run checks

# Local, offline, read-only report
npx ship-parity check .

# Machine-readable reports
npx ship-parity --json > ship-parity.json
npx ship-parity --markdown > ship-parity.md
npx ship-parity --sarif > ship-parity.sarif

# Make warnings block CI
npx ship-parity --strict

Example output:

Ship Parity - deployment readiness
  Framework: vite
  Package manager: pnpm
  Provider: vercel
  Integrations: supabase
  Findings: 1 errors, 1 warnings

  ERROR SHP001  Secret-looking environment name uses a public client prefix: VITE_SERVICE_ROLE_KEY
  WARNING SHP008  Debug statement remains in production-bound source.

What it checks

| Area | Current coverage | | --- | --- | | Framework | Next.js, Vite, Svelte, Astro, Remix, Nuxt | | Hosting | Vercel, Netlify, Cloudflare, Railway, Render | | Integrations | Supabase, Firebase, Clerk, Auth.js | | Configuration | npm/pnpm/Yarn/Bun locks, Node declarations, ship-parity.yml | | Exposure | public-prefix secrets, tracked .env, private/local origins | | Hygiene | debug statements, logs, dumps, temporary and coverage artifacts | | Reports | terminal, schema-versioned JSON, Markdown, SARIF |

Finding IDs include SHP001 public secret name, SHP002 missing contract environment name, SHP003 tracked environment file, SHP004 private origin, SHP006 runtime drift, SHP007 generated artifact, and SHP008 debugger/console debug statement.

Deployment contract

Generate a reviewable contract from the detected project:

npx ship-parity init

Edit ship-parity.yml to record names and expectations—not secret values:

expectedOrigin: "https://app.example.com"
nodeVersion: ">=20"
buildCommand: "pnpm build"
outputDirectory: "dist"
healthPath: "/health"
requiredEnv:
  - DATABASE_URL
  - VITE_PUBLIC_NAME
publicEnvPrefixes:
  - VITE_

init refuses to overwrite an existing contract unless --force is supplied. --build runs the project’s build script only with explicit --build --yes confirmation; normal checks never execute project code.

Privacy and limits

• offline and read-only by default;
• .env values, source values, and secret-shaped strings are never retained in reports;
• observations include source paths and line numbers so findings are actionable;
• static checks cannot prove cloud runtime behavior or replace a real staging smoke test.

Development

npm install
npm run lint
npm test
npm run test:cli
npm pack --dry-run

Issues and pull requests are welcome in the GitHub repository.

License

MIT © Debaditya Hait