@codluv/versionguard

v1.2.0

Published

8 days ago

Strict versioning enforcement for SemVer and CalVer — language-agnostic manifest support, git hooks, changelog validation, and file sync

0High
0Medium
0Low

kryptobaseddev

semver calver versioning git-hooks changelog version-sync release version-guard package-version keep-a-changelog

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:

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.
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.
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

| Command | Description | | --- | --- | | vg init | Create .versionguard.yml (interactive wizard or headless) | | vg check | Validate the current version with actionable feedback | | vg validate | Run all checks: version, sync, changelog, scan, guard, publish | | vg doctor | Report repository readiness in one pass | | vg fix | Apply deterministic fixes for common drift | | vg fix-changelog | Fix Changesets-mangled changelogs to Keep a Changelog format | | vg sync | Update configured files to match manifest version | | vg bump | Suggest the next version and optionally apply it | | vg tag [version] | Create an annotated release tag safely | | vg hooks install | Install managed git hooks | | vg hooks uninstall | Remove managed git hooks | | vg hooks status | Check whether hooks are installed | | vg ckm [topic] | Codebase Knowledge Manifest — auto-generated help | | vg ckm [topic] --json | Machine-readable CKM for LLM agents |

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.

| Concern | Changesets | VersionGuard | | --- | --- | --- | | Decide the next version | Yes | No (validates, doesn't choose) | | Update manifest version | Yes | No (reads it as source of truth) | | Validate version format | No | Yes (SemVer/CalVer strictness) | | Sync version across files | No | Yes (regex-based sync) | | Validate changelog structure | No | Yes (Keep a Changelog + section enforcement) | | Scan repo for stale versions | No | Yes | | Verify publish status on registry | No | Yes (fail-open) | | Git hooks enforcement | No | Yes | | Publish to npm | Yes | No |

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.