VersionGuard

Strict version governance for any project — SemVer and CalVer enforcement, language-agnostic manifest support, git hooks, changelog validation, file sync, and repo-wide version scanning.

VersionGuard keeps your manifest, changelog entries, git tags, and configured version references in sync so humans and LLM agents stop shipping messy release state.

Why it exists

Versioning breaks in the same places over and over:

• versions get hardcoded across docs, CI configs, and Dockerfiles
• changelog entries are forgotten or use wrong section names
• tags drift from the package version
• SemVer and CalVer rules get bent under pressure
• agents take shortcuts and leave the repo in an invalid release state

VersionGuard turns those into enforceable checks with repair-oriented feedback.

What it does

• validates SemVer and CalVer formats with configurable rules
• keeps configured files synced from your manifest (package.json, Cargo.toml, pyproject.toml, etc.)
• scans the entire repo for stale version literals (enabled by default)
• verifies publish status against your package registry (npm, crates.io, PyPI, etc.)
• validates Keep a Changelog structure with section enforcement
• installs cooperative git hooks for pre-commit, pre-push, and post-tag
• provides CLI commands for validation, sync, bumps, and tagging
• refuses unsafe tagging when hooks are required or the worktree is dirty
• built-in CKM help system for humans and LLM agents (vg ckm)

Where it runs

VersionGuard enforces at three points in the development lifecycle:

1. Local dev (git hooks): pre-commit and pre-push hooks run vg validate automatically. This catches version drift, changelog issues, and sync mismatches before code leaves the developer's machine. This is the primary enforcement point.

2. CI (GitHub Actions): vg validate runs as a build gate in CI. This catches anything the hooks missed (hooks can be skipped with --no-verify), validates on every PR, and ensures Dependabot PRs don't break version consistency.

3. CLI (developer workflow): vg check, vg fix, vg sync, vg tag, vg doctor — manual commands that developers and agents use during the release flow.

Who needs it

• Any project that ships versioned software and wants to stop version-related drift: stale install commands in docs, missing changelog entries, hardcoded version strings in CI configs or Dockerfiles, tag/manifest mismatches
• Teams using AI agents that modify code — VG is the guardrail that catches when agents skip versioning steps
• Polyglot projects that need consistent version governance across npm, Rust, Python, Dart, PHP, Java, and more

Install

npm install -D @codluv/versionguard@latest
vg init
vg hooks install

vg is a shorthand alias for versionguard. Both work identically.

That gives you:

• a .versionguard.yml config file
• managed git hooks
• a repo-local version policy built around your manifest

Quick start

Run a basic version check:

vg check

Run full repository validation (includes scan, guard, and publish checks by default):

vg validate

For CI or agent workflows:

vg validate --json

Sync configured files back to the manifest version:

vg sync

Repair common issues automatically:

vg fix

Example output

Valid version:

Current version: 1.2.3
Versioning type: semver

✓ Version is valid

Invalid version with actionable guidance:

Current version: v1.0.0
Versioning type: semver

✗ Version has issues:

  ✗ Version should not start with 'v': v1.0.0

How to fix:
  → Remove the 'v' prefix
    Run: npm version 1.0.0

Configuration

VersionGuard uses a single YAML config file. Both semver: and calver: blocks are always present — change type to switch.

Example:

versioning:
  type: semver
  semver:
    allowVPrefix: false
    allowBuildMetadata: true
    requirePrerelease: false
  calver:
    format: "YYYY.MM.PATCH"
    preventFutureDates: true

sync:
  files:
    - "README.md"
    - "CHANGELOG.md"
  patterns:
    - regex: '(version\s*[=:]\s*["'])(.+?)(["'])'
      template: '$1{{version}}$3'
    - regex: '(##\s*\[)(.+?)(\])'
      template: '$1{{version}}$3'

changelog:
  enabled: true
  file: "CHANGELOG.md"
  strict: true
  requireEntry: true
  enforceStructure: false
  sections:
    - Added
    - Changed
    - Deprecated
    - Removed
    - Fixed
    - Security

# All checks below are enabled by default — opt OUT via config
guard:
  enabled: true          # hook bypass detection

publish:
  enabled: true          # registry publish status verification
  timeout: 5000          # ms, fail-open on timeout

scan:
  enabled: true          # repo-wide stale version detection
  allowlist: []

git:
  hooks:
    pre-commit: true
    pre-push: true
    post-tag: true
  enforceHooks: true

ignore:
  - "node_modules/**"
  - "dist/**"
  - ".git/**"
  - "*.lock"

Supported versioning modes

SemVer

VersionGuard supports strict semantic version validation with configurable rules via the semver: block:

• MAJOR.MINOR.PATCH with prerelease (1.2.3-alpha.1) and build metadata (1.2.3+build.5)
• allowVPrefix — tolerate v1.2.3 format (stripped before parsing)
• allowBuildMetadata — permit or reject +build metadata suffix
• requirePrerelease — require prerelease labels on every version
• schemeRules.allowedModifiers — whitelist prerelease tags (e.g., alpha, beta, rc)
• precedence comparison and increment helpers

CalVer

Composable token-based format strings supporting all calver.org tokens:

• Year: YYYY, YY, 0Y
• Month: MM, M, 0M
• Week: WW, 0W
• Day: DD, D, 0D
• Counter: MICRO, PATCH

CalVer validation can reject future-dated versions and enforce modifier allowlists.

Language-agnostic manifests

VersionGuard reads versions from any supported manifest:

• package.json (Node.js), Cargo.toml (Rust), pyproject.toml (Python)
• pubspec.yaml (Dart/Flutter), composer.json (PHP), pom.xml (Java/Maven)
• VERSION (plain text), Git tags (Go/Swift), Custom regex patterns

Set manifest.source: auto for automatic detection.

Commands

Git hook behavior

VersionGuard can install these hooks:

• pre-commit
• pre-push
• post-tag

When git.enforceHooks is enabled, release tagging also expects managed hooks to be present.

Doctor command

Use doctor when you want a one-pass readiness report before releasing:

vg doctor

For CI or agent workflows:

vg doctor --json

It reports:

• current package version
• version validity
• sync status
• changelog readiness
• hook installation state
• worktree cleanliness

Validate JSON output

Use validate --json when you need machine-readable validation output:

vg validate --json

The JSON payload includes:

• valid
• version
• versionValid
• syncValid
• changelogValid
• scanValid
• guardValid
• publishValid
• publishCheck
• guardReport
• errors
• hook
• postTag

Tagging behavior

versionguard tag is intentionally strict.

It can refuse to proceed when:

• hooks are required but not installed
• the working tree is dirty
• the requested tag already exists
• the package version or changelog state is invalid
• synced files are out of date

That keeps release tags from becoming a bypass around normal validation.

Stability Policy

1.x maintains backward compatibility for all CLI commands and configuration formats. Breaking changes only occur in 2.0+.

Deprecated flags (--strict, --scan) continue to work in 1.x and print a warning. Their behavior is now the default. To opt out of specific checks, use config:

guard:
  enabled: false
scan:
  enabled: false
publish:
  enabled: false

Typical workflows

Validate before committing

vg validate

Repair drift after a manual version change

npm version patch
vg fix

Suggest and apply the next version

vg bump --apply

Create a release tag safely

vg tag 1.2.3 -m "Release 1.2.3"

Using with Changesets

VersionGuard and Changesets are complementary tools that handle different parts of the release lifecycle.

Changesets decides what version comes next. VersionGuard validates that the result is correct.

Recommended workflow

# 1. Add a changeset when making changes
npx changeset

# 2. When ready to release, version the packages
npx changeset version

# 3. VersionGuard validates the new state
vg validate

# 4. Publish
npx changeset publish

CI integration

In GitHub Actions, both tools run in sequence. Changesets creates a "Version Packages" PR when changesets are pending. VersionGuard validates the result before publishing:

- run: npm run build
- run: vg validate
- uses: changesets/action@v1
  with:
    publish: npx changeset publish --access public

VersionGuard does not replace Changesets and does not conflict with it. Use Changesets for release automation. Use VersionGuard for release correctness.

Development

This repository uses a modern ESM toolchain:

• Vite for builds
• Vitest for tests
• Biome for formatting and baseline linting
• ESLint for semantic TypeScript linting

Useful commands:

npm run lint
npm test
npm run build

Forge commands:

npm run forge:check
npm run forge:test
npm run forge:build
npm run forge:doctor

Initialize or refresh Forge scaffolding:

npm run forge:docs:init

Run a single test file:

npx vitest run src/__tests__/semver.test.ts

Run a single test by name:

npx vitest run src/__tests__/calver.test.ts -t "increments patch-based versions"

Docs

• Product vision: docs/VISION.md
• Verified feature ledger and roadmap: docs/FEATURES.md
• CKM module documentation: src/ckm/README-CKM.md
• Agent guidance for contributors: AGENTS.md

Forge

This repo is set up with @forge-ts/cli and a project config in forge-ts.config.ts.

Useful commands:

npm run forge:check
npm run forge:test
npm run forge:build
npm run forge:doctor

Current status:

• Forge is installed and initialized
• forge-ts check currently reports significant TSDoc debt
• generated documentation artifacts are written into docs/

Recommended workflow:

npm run forge:check
npm run forge:build

Then fix TSDoc issues in the order reported by Forge.

License

MIT