verscan

Zero-dependency CLI to verify that package.json, CHANGELOG.md, and your latest git tag all agree on the same version number — before you ship.

$ verscan

  ✓ package.json   1.3.0  (reference)
  ✓ CHANGELOG.md   1.3.0
  ✓ git tag        1.3.0

verscan: all sources match → 1.3.0

If they don't match, you hear about it before your users do:

  ✓ package.json   1.3.0  (reference)
  ✓ CHANGELOG.md   1.3.0
  ✓ git tag        1.2.9

  ✗ git tag is 1.2.9 — expected 1.3.0

verscan: version mismatch — git differ from 1.3.0

Install

# run once without installing
npx verscan

# or install globally
npm install -g verscan

No dependencies. Node.js ≥ 18 required.

Usage

verscan [options] [dir]

| Option | Description | |--------|-------------| | --no-git | Skip git tag check (useful before you've tagged) | | --no-changelog | Skip CHANGELOG.md check | | --manifest <file> | Custom manifest path (default: auto-detect package.json or pyproject.toml) | | --changelog <file> | Custom changelog path (default: CHANGELOG.md) | | --json | Output JSON (machine-readable) | | --version | Print verscan version | | --help | Show help |

Exit codes: 0 all match · 1 mismatch · 2 parse/read error

Examples

# Check the current directory (reads package.json + CHANGELOG.md + latest git tag)
verscan

# Check before tagging — only compare package.json vs CHANGELOG.md
verscan --no-git

# Check a sub-package in a monorepo
verscan ./packages/ui

# Check a Python project (auto-detects pyproject.toml)
verscan ./my-python-lib

# Use in CI — fail the build if versions don't align
verscan || exit 1

# Machine-readable
verscan --json | jq '.ok'

How it works

1. Reads the version from package.json (or pyproject.toml if no package.json is present)
2. Parses the first ## [x.y.z] heading in CHANGELOG.md (supports Keep a Changelog format, bare ## x.y.z, and ## vx.y.z)
3. Runs git describe --tags --abbrev=0 to get the latest tag (strips leading v)
4. Compares all three — exits 0 if they match, 1 if any differ

CI integration

# .github/workflows/release.yml
- name: Verify versions aligned
  run: npx verscan

# Pre-push hook: .git/hooks/pre-push
#!/bin/sh
npx verscan --no-git || exit 1

Python projects

verscan auto-detects pyproject.toml when package.json is absent:

verscan ./my-python-package   # reads [project] version from pyproject.toml

For the Python CLI counterpart, see verscan-py.

License

MIT