@codluv/versionguard 0.8.0 → 1.0.0

package/README.md

@@ -1,15 +1,15 @@
 # VersionGuard
 
-Strict version governance for TypeScript and Node.js projects.
+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 `package.json`, changelog entries, git tags, and configured version references in sync so humans and LLM agents stop shipping messy release state.
+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 and source files
-- changelog entries are forgotten
+- 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
@@ -18,58 +18,78 @@ VersionGuard turns those into enforceable checks with repair-oriented feedback.
 
 ## What it does
 
-- validates SemVer and CalVer formats strictly
-- keeps configured files synced from `package.json`
-- detects version mismatches in scanned files
-- validates Keep a Changelog structure and required release entries
-- installs git hooks for `pre-commit`, `pre-push`, and `post-tag`
+- 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
 
 ```bash
-npm install -D @codluv/versionguard
-npx versionguard init
-npx versionguard hooks 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 `package.json`
+- a repo-local version policy built around your manifest
 
 ## Quick start
 
 Run a basic version check:
 
 ```bash
-npx versionguard check
+vg check
 ```
 
-Run full repository validation:
+Run full repository validation (includes scan, guard, and publish checks by default):
 
 ```bash
-npx versionguard validate
+vg validate
 ```
 
 For CI or agent workflows:
 
 ```bash
-npx versionguard validate --json
+vg validate --json
 ```
 
-Sync configured files back to the package version:
+Sync configured files back to the manifest version:
 
 ```bash
-npx versionguard sync
+vg sync
 ```
 
 Repair common issues automatically:
 
 ```bash
-npx versionguard fix
+vg fix
 ```
 
 ## Example output
@@ -100,18 +120,20 @@ How to fix:
 
 ## Configuration
 
-VersionGuard uses a single YAML config file.
+VersionGuard uses a single YAML config file. Both `semver:` and `calver:` blocks are always present — change `type` to switch.
 
 Example:
 
 ```yaml
 versioning:
   type: semver
-
-  # Enable this block when using calver
-  # calver:
-  #   format: "YYYY.MM.PATCH"
-  #   preventFutureDates: true
+  semver:
+    allowVPrefix: false
+    allowBuildMetadata: true
+    requirePrerelease: false
+  calver:
+    format: "YYYY.MM.PATCH"
+    preventFutureDates: true
 
 sync:
   files:
@@ -128,6 +150,26 @@ changelog:
   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:
@@ -147,39 +189,55 @@ ignore:
 
 ### SemVer
 
-VersionGuard supports strict semantic version validation with:
+VersionGuard supports strict semantic version validation with configurable rules via the `semver:` block:
 
-- `MAJOR.MINOR.PATCH`
-- prerelease metadata such as `1.2.3-alpha.1`
-- build metadata such as `1.2.3+build.5`
+- `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
 
-Supported formats currently include:
+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`
 
-- `YYYY.MM.DD`
-- `YYYY.MM.PATCH`
-- `YY.M.PATCH`
-- `YYYY.0M.0D`
+CalVer validation can reject future-dated versions and enforce modifier allowlists.
 
-CalVer validation can reject future-dated versions when enabled.
+### 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 |
 | --- | --- |
-| `versionguard init` | Create `.versionguard.yml` in the current project |
-| `versionguard check` | Validate the current version with actionable feedback |
-| `versionguard validate` | Run version, sync, and changelog validation |
-| `versionguard doctor` | Report repository readiness in one pass |
-| `versionguard fix` | Apply deterministic fixes for common drift |
-| `versionguard sync` | Update configured files to match `package.json` |
-| `versionguard bump` | Suggest the next version and optionally apply it |
-| `versionguard tag [version]` | Create an annotated release tag safely |
-| `versionguard hooks install` | Install managed git hooks |
-| `versionguard hooks uninstall` | Remove managed git hooks |
-| `versionguard hooks status` | Check whether hooks are installed |
+| `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
 
@@ -196,13 +254,13 @@ When `git.enforceHooks` is enabled, release tagging also expects managed hooks t
 Use `doctor` when you want a one-pass readiness report before releasing:
 
 ```bash
-npx versionguard doctor
+vg doctor
 ```
 
 For CI or agent workflows:
 
 ```bash
-npx versionguard doctor --json
+vg doctor --json
 ```
 
 It reports:
@@ -219,7 +277,7 @@ It reports:
 Use `validate --json` when you need machine-readable validation output:
 
 ```bash
-npx versionguard validate --json
+vg validate --json
 ```
 
 The JSON payload includes:
@@ -229,6 +287,11 @@ The JSON payload includes:
 - `versionValid`
 - `syncValid`
 - `changelogValid`
+- `scanValid`
+- `guardValid`
+- `publishValid`
+- `publishCheck`
+- `guardReport`
 - `errors`
 - `hook`
 - `postTag`
@@ -247,31 +310,46 @@ It can refuse to proceed when:
 
 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:
+
+```yaml
+guard:
+  enabled: false
+scan:
+  enabled: false
+publish:
+  enabled: false
+```
+
 ## Typical workflows
 
 ### Validate before committing
 
 ```bash
-npx versionguard validate
+vg validate
 ```
 
 ### Repair drift after a manual version change
 
 ```bash
 npm version patch
-npx versionguard fix
+vg fix
 ```
 
 ### Suggest and apply the next version
 
 ```bash
-npx versionguard bump --apply
+vg bump --apply
 ```
 
 ### Create a release tag safely
 
 ```bash
-npx versionguard tag 1.2.3 -m "Release 1.2.3"
+vg tag 1.2.3 -m "Release 1.2.3"
 ```
 
 ## Using with Changesets
@@ -281,10 +359,12 @@ VersionGuard and [Changesets](https://github.com/changesets/changesets) are comp
 | Concern | Changesets | VersionGuard |
 | --- | --- | --- |
 | Decide the next version | Yes | No (validates, doesn't choose) |
-| Update `package.json` version | Yes | No (reads it as source of truth) |
+| 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) |
+| 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 |
 
@@ -300,7 +380,7 @@ npx changeset
 npx changeset version
 
 # 3. VersionGuard validates the new state
-npx versionguard validate
+vg validate
 
 # 4. Publish
 npx changeset publish
@@ -312,7 +392,7 @@ In GitHub Actions, both tools run in sequence. Changesets creates a "Version Pac
 
 ```yaml
 - run: npm run build
-- run: npx versionguard validate
+- run: vg validate
 - uses: changesets/action@v1
   with:
     publish: npx changeset publish --access public
@@ -368,6 +448,7 @@ npx vitest run src/__tests__/calver.test.ts -t "increments patch-based versions"
 
 - 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