Shipcheck

Catch version, documentation, and release artifact drift before you ship.

Shipcheck is a local-first, deterministic command-line tool for checking whether a repository's version sources, release documentation, and packaged artifacts agree with each other. It reads project files only; it does not execute scanned project code, upload files, require an account, or send telemetry.

Why Shipcheck

A package manifest, browser-extension manifest, README, CHANGELOG, and release ZIP can each be valid while describing different releases. Those errors are easy to miss in manual review and often appear only after a user downloads the wrong artifact. Shipcheck turns that drift into repeatable local and CI checks.

Features

• Compare versions from package.json, Chrome Extension manifest.json, or any configured JSON path.
• Detect stale release versions in README installation commands, links, badges, and ZIP names.
• Validate CHANGELOG presence, current-version coverage, duplicate headings, parseable headings, and descending order.
• Verify artifact filenames and identify likely stale artifacts beside the current file.
• Inspect required JSON files inside ZIP archives, including archives with one wrapper directory.
• Reject unsafe ZIP paths, symbolic-link entries, encrypted entries, oversized entries, and configured forbidden content.
• Check required and forbidden repository files.
• Produce terminal, JSON, or Markdown reports from one result model.
• Use stable exit codes for shell scripts and CI.

Quick start

The npm package is not published yet. The following development installation has been verified:

git clone https://github.com/kodlbegiko/shipcheck.git
cd shipcheck
npm ci
npm install --global typescript@5.8.3
npm run build
node dist/cli.js init ../your-project
node dist/cli.js ../your-project

After an npm release, the intended commands are:

npx shipcheck
npx shipcheck .
npx shipcheck --config shipcheck.config.json
npx shipcheck --format json
npx shipcheck --format markdown --output shipcheck-report.md
npx shipcheck --ci
npx shipcheck init

shipcheck init never overwrites an existing configuration unless --force is supplied.

Configuration

{
  "$schema": "./schema/shipcheck.schema.json",
  "versionSources": [
    { "file": "package.json", "path": "version", "primary": true },
    { "file": "manifest.json", "path": "version" }
  ],
  "documents": {
    "readme": "README.md",
    "changelog": "CHANGELOG.md",
    "changelogRequired": true
  },
  "artifacts": [
    {
      "file": "dist/example-v{version}.zip",
      "versionPattern": "v?(?<version>\\d+\\.\\d+\\.\\d+)",
      "internalVersionSources": [
        { "file": "manifest.json", "path": "version" }
      ]
    }
  ],
  "requiredFiles": ["README.md", "LICENSE", "CHANGELOG.md"],
  "forbiddenFiles": [".env", ".DS_Store"]
}

Unknown configuration fields are rejected. Absolute paths and paths outside the project root are rejected. See configuration for the complete schema.

Example terminal output

Shipcheck 0.1.0 — FAIL
Project: /workspace/example
Version: 0.1.0

ERROR   VERSION_SOURCE_MISMATCH manifest.json: Version source does not match the primary version
         expected=0.1.0 actual=0.0.9
         fix: Update version to 0.1.0.

Summary: 1 error(s), 0 warning(s), 0 info

Supported checks

The rule catalogue, severities, and remediation guidance are documented in rules.

GitHub Actions

Until npm publication, use a checked-out copy of Shipcheck:

name: Shipcheck
on:
  pull_request:
  push:
    branches: [main]

jobs:
  release-consistency:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          path: project
      - uses: actions/checkout@v4
        with:
          repository: kodlbegiko/shipcheck
          ref: v0.1.0
          path: shipcheck
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
        working-directory: shipcheck
      - run: npm install --global typescript@5.8.3
      - run: npm run build
        working-directory: shipcheck
      - run: node ../shipcheck/dist/cli.js . --ci
        working-directory: project

Actions use major tags in this repository so trusted official actions receive compatible security fixes. Pin to full commit SHAs where organizational policy requires immutable references.

Exit codes

Code	Meaning
0	Checks completed with no blocking errors.
1	Checks completed and at least one blocking error was found.
2	Shipcheck could not run because of invalid configuration, invalid CLI usage, or an internal failure.

Warnings do not block by default. Use --warnings-as-errors or warningsAsErrors in configuration to make them blocking.

Limitations

Shipcheck intentionally supports JSON configuration only. README detection is contextual and may require documentation changes when a version-like token is intentionally historical. ZIP support is limited to standard single-disk archives using stored or DEFLATE entries; ZIP64 and encrypted archives are rejected. See limitations.

Security model

Shipcheck treats scanned repositories and ZIP files as untrusted data. It does not import project configuration, execute project scripts, extract ZIP content, follow symlinks, access paths outside the selected root, or make network requests. Resource limits reduce risk but do not make Shipcheck a general malware or supply-chain scanner. See SECURITY.md.

Development

npm ci
npm install --global typescript@5.8.3
npm run lint
npm run typecheck
npm test
npm run test:coverage
npm run build
npm pack
node scripts/package-smoke.mjs shipcheck-0.1.0.tgz
node dist/cli.js .
npm audit

The repository uses TypeScript with strict settings. Runtime code has no third-party dependencies. Tests use the Node.js test runner to keep package installation deterministic and offline after checkout.

Contributing

Read CONTRIBUTING.md before opening a pull request. Reports involving a vulnerability should follow SECURITY.md, not a public issue.

License

MIT