@codluv/versionguard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kryptobaseddev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,357 @@
+# VersionGuard
+
+Strict version governance for TypeScript and Node.js projects.
+
+VersionGuard keeps `package.json`, 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
+- 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 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`
+- provides CLI commands for validation, sync, bumps, and tagging
+- refuses unsafe tagging when hooks are required or the worktree is dirty
+
+## Install
+
+```bash
+npm install -D @codluv/versionguard
+npx versionguard init
+npx versionguard hooks install
+```
+
+That gives you:
+
+- a `.versionguard.yml` config file
+- managed git hooks
+- a repo-local version policy built around `package.json`
+
+## Quick start
+
+Run a basic version check:
+
+```bash
+npx versionguard check
+```
+
+Run full repository validation:
+
+```bash
+npx versionguard validate
+```
+
+For CI or agent workflows:
+
+```bash
+npx versionguard validate --json
+```
+
+Sync configured files back to the package version:
+
+```bash
+npx versionguard sync
+```
+
+Repair common issues automatically:
+
+```bash
+npx versionguard fix
+```
+
+## Example output
+
+Valid version:
+
+```text
+Current version: 1.2.3
+Versioning type: semver
+
+✓ Version is valid
+```
+
+Invalid version with actionable guidance:
+
+```text
+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.
+
+Example:
+
+```yaml
+versioning:
+  type: semver
+
+  # Enable this block when using calver
+  # 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
+
+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:
+
+- `MAJOR.MINOR.PATCH`
+- prerelease metadata such as `1.2.3-alpha.1`
+- build metadata such as `1.2.3+build.5`
+- precedence comparison and increment helpers
+
+### CalVer
+
+Supported formats currently include:
+
+- `YYYY.MM.DD`
+- `YYYY.MM.PATCH`
+- `YY.M.PATCH`
+- `YYYY.0M.0D`
+
+CalVer validation can reject future-dated versions when enabled.
+
+## 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 |
+
+## 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:
+
+```bash
+npx versionguard doctor
+```
+
+For CI or agent workflows:
+
+```bash
+npx versionguard 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:
+
+```bash
+npx versionguard validate --json
+```
+
+The JSON payload includes:
+
+- `valid`
+- `version`
+- `versionValid`
+- `syncValid`
+- `changelogValid`
+- `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.
+
+## Typical workflows
+
+### Validate before committing
+
+```bash
+npx versionguard validate
+```
+
+### Repair drift after a manual version change
+
+```bash
+npm version patch
+npx versionguard fix
+```
+
+### Suggest and apply the next version
+
+```bash
+npx versionguard bump --apply
+```
+
+### Create a release tag safely
+
+```bash
+npx versionguard tag 1.2.3 -m "Release 1.2.3"
+```
+
+## 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:
+
+```bash
+npm run lint
+npm test
+npm run build
+```
+
+Forge commands:
+
+```bash
+npm run forge:check
+npm run forge:test
+npm run forge:build
+npm run forge:doctor
+```
+
+Initialize or refresh Forge scaffolding:
+
+```bash
+npm run forge:docs:init
+```
+
+Run a single test file:
+
+```bash
+npx vitest run src/__tests__/semver.test.ts
+```
+
+Run a single test by name:
+
+```bash
+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`
+- 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:
+
+```bash
+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:
+
+```bash
+npm run forge:check
+npm run forge:build
+```
+
+Then fix TSDoc issues in the order reported by Forge.
+
+## License
+
+MIT

package/dist/calver.d.ts

@@ -0,0 +1,245 @@
+/**
+ * Calendar version parsing, formatting, and comparison helpers.
+ *
+ * @packageDocumentation
+ */
+import type { CalVer, CalVerFormat, ValidationResult } from './types';
+/**
+ * Parsed token layout for a supported CalVer format string.
+ *
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export interface ParsedCalVerFormat {
+    /**
+     * Year token captured from the format string.
+     */
+    year: 'YYYY' | 'YY';
+    /**
+     * Month token captured from the format string.
+     */
+    month: 'MM' | 'M' | '0M';
+    /**
+     * Day token captured from the format string when present.
+     *
+     * @defaultValue undefined
+     */
+    day?: 'DD' | 'D' | '0D';
+    /**
+     * Patch token captured from the format string when present.
+     *
+     * @defaultValue undefined
+     */
+    patch?: 'PATCH';
+}
+/**
+ * Breaks a CalVer format string into its component tokens.
+ *
+ * @remarks
+ * This helper is used internally by parsing, formatting, and version generation helpers
+ * to decide which date parts or patch counters are present in a given CalVer layout.
+ *
+ * @param calverFormat - Format string to inspect.
+ * @returns The parsed token definition for the requested format.
+ *
+ * @example
+ * ```ts
+ * import { parseFormat } from 'versionguard';
+ *
+ * parseFormat('YYYY.MM.PATCH');
+ * // => { year: 'YYYY', month: 'MM', patch: 'PATCH' }
+ * ```
+ *
+ * @public
+ * @since 0.1.0
+ */
+export declare function parseFormat(calverFormat: CalVerFormat): ParsedCalVerFormat;
+/**
+ * Builds a regular expression that matches a supported CalVer format.
+ *
+ * @remarks
+ * The returned regular expression is anchored to the start and end of the string so it can
+ * be used directly for strict validation of a complete version value.
+ *
+ * @param calverFormat - Format string to convert into a regular expression.
+ * @returns A strict regular expression for the supplied CalVer format.
+ *
+ * @example
+ * ```ts
+ * import { getRegexForFormat } from 'versionguard';
+ *
+ * getRegexForFormat('YYYY.0M.0D').test('2026.03.21');
+ * // => true
+ * ```
+ *
+ * @public
+ * @since 0.1.0
+ */
+export declare function getRegexForFormat(calverFormat: CalVerFormat): RegExp;
+/**
+ * Parses a CalVer string using the supplied format.
+ *
+ * @remarks
+ * The parser returns `null` when the string does not structurally match the requested format.
+ * It does not enforce range rules such as future-date rejection; use {@link validate} for that.
+ *
+ * @param version - Version string to parse.
+ * @param calverFormat - Format expected for the version string.
+ * @returns Parsed CalVer components, or `null` when the string does not match the format.
+ *
+ * @example
+ * ```ts
+ * import { parse } from 'versionguard';
+ *
+ * parse('2026.03.21', 'YYYY.0M.0D')?.month;
+ * // => 3
+ * ```
+ *
+ * @see {@link validate} to apply date-range and future-date validation.
+ * @public
+ * @since 0.1.0
+ */
+export declare function parse(version: string, calverFormat: CalVerFormat): CalVer | null;
+/**
+ * Validates a CalVer string against formatting and date rules.
+ *
+ * @remarks
+ * Validation checks the requested CalVer format, month and day ranges, and optionally rejects
+ * future dates relative to the current system date.
+ *
+ * @param version - Version string to validate.
+ * @param calverFormat - Format expected for the version string.
+ * @param preventFutureDates - Whether future dates should be reported as errors.
+ * @returns A validation result containing any discovered errors and the parsed version on success.
+ *
+ * @example
+ * ```ts
+ * import { validate } from 'versionguard';
+ *
+ * validate('2026.03.21', 'YYYY.0M.0D', false).valid;
+ * // => true
+ * ```
+ *
+ * @public
+ * @since 0.1.0
+ */
+export declare function validate(version: string, calverFormat: CalVerFormat, preventFutureDates?: boolean): ValidationResult;
+/**
+ * Formats a parsed CalVer object back into a version string.
+ *
+ * @remarks
+ * Missing `day` and `patch` values fall back to `1` and `0` respectively when the selected
+ * format requires those tokens.
+ *
+ * @param version - Parsed CalVer value to serialize.
+ * @returns The formatted CalVer string.
+ *
+ * @example
+ * ```ts
+ * import { format } from 'versionguard';
+ *
+ * const version = { year: 2026, month: 3, day: 21, format: 'YYYY.0M.0D', raw: '2026.03.21' };
+ *
+ * format(version);
+ * // => '2026.03.21'
+ * ```
+ *
+ * @public
+ * @since 0.1.0
+ */
+export declare function format(version: CalVer): string;
+/**
+ * Creates the current CalVer string for a format.
+ *
+ * @remarks
+ * This helper derives its values from the provided date and initializes any patch token to `0`.
+ * It is useful for generating a same-day baseline before incrementing patch-based formats.
+ *
+ * @param calverFormat - Format to generate.
+ * @param now - Date used as the source for year, month, and day values.
+ * @returns The current version string for the requested format.
+ *
+ * @example
+ * ```ts
+ * import { getCurrentVersion } from 'versionguard';
+ *
+ * getCurrentVersion('YYYY.MM.PATCH', new Date('2026-03-21T00:00:00Z'));
+ * // => '2026.3.0'
+ * ```
+ *
+ * @public
+ * @since 0.1.0
+ */
+export declare function getCurrentVersion(calverFormat: CalVerFormat, now?: Date): string;
+/**
+ * Compares two CalVer strings using a shared format.
+ *
+ * @remarks
+ * Comparison is performed component-by-component in year, month, day, then patch order.
+ * Missing day and patch values are treated as `0` during comparison.
+ *
+ * @param a - Left-hand version string.
+ * @param b - Right-hand version string.
+ * @param calverFormat - Format used to parse both versions.
+ * @returns `1` when `a` is greater, `-1` when `b` is greater, or `0` when they are equal.
+ *
+ * @example
+ * ```ts
+ * import { compare } from 'versionguard';
+ *
+ * compare('2026.03.2', '2026.03.1', 'YYYY.MM.PATCH');
+ * // => 1
+ * ```
+ *
+ * @public
+ * @since 0.1.0
+ */
+export declare function compare(a: string, b: string, calverFormat: CalVerFormat): number;
+/**
+ * Increments a CalVer string.
+ *
+ * @remarks
+ * Patch-based formats increment the existing patch number. Formats without a patch token are
+ * promoted to a patch-based output by appending `.PATCH` semantics with an initial value of `0`.
+ *
+ * @param version - Current version string.
+ * @param calverFormat - Format used to parse the current version.
+ * @returns The next version string.
+ *
+ * @example
+ * ```ts
+ * import { increment } from 'versionguard';
+ *
+ * increment('2026.03.1', 'YYYY.MM.PATCH');
+ * // => '2026.3.2'
+ * ```
+ *
+ * @public
+ * @since 0.1.0
+ */
+export declare function increment(version: string, calverFormat: CalVerFormat): string;
+/**
+ * Returns the most likely next CalVer candidates.
+ *
+ * @remarks
+ * The first candidate is the version derived from the current date. The second candidate is the
+ * incremented form of the supplied current version.
+ *
+ * @param currentVersion - Existing project version.
+ * @param calverFormat - Format used to generate both candidates.
+ * @returns Two candidate version strings ordered as current-date then incremented version.
+ *
+ * @example
+ * ```ts
+ * import { getNextVersions } from 'versionguard';
+ *
+ * getNextVersions('2026.03.1', 'YYYY.MM.PATCH').length;
+ * // => 2
+ * ```
+ *
+ * @public
+ * @since 0.1.0
+ */
+export declare function getNextVersions(currentVersion: string, calverFormat: CalVerFormat): string[];
+//# sourceMappingURL=calver.d.ts.map

package/dist/calver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calver.d.ts","sourceRoot":"","sources":["../src/calver.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAmB,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEvF;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAEpB;;OAEG;IACH,KAAK,EAAE,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC;IAEzB;;;;OAIG;IACH,GAAG,CAAC,EAAE,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC;IAExB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,YAAY,GAAG,kBAAkB,CAkB1E;AAuBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,YAAY,GAAG,MAAM,CAIpE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAmChF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,YAAY,EAC1B,kBAAkB,GAAE,OAAc,GACjC,gBAAgB,CA0ElB;AAcD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAa9C;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,YAAY,EAAE,GAAG,GAAE,IAAiB,GAAG,MAAM,CAkB5F;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,CAiBhF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,CAsB7E;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAAC,cAAc,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,EAAE,CAE5F"}

package/dist/changelog.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Describes the outcome of validating a changelog file.
+ *
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export interface ChangelogValidationResult {
+    /**
+     * Indicates whether the changelog satisfies all requested checks.
+     */
+    valid: boolean;
+    /**
+     * Human-readable validation errors.
+     */
+    errors: string[];
+    /**
+     * Indicates whether the changelog contains an entry for the requested version.
+     */
+    hasEntryForVersion: boolean;
+}
+/**
+ * Validates a changelog file for release readiness.
+ *
+ * @public
+ * @since 0.1.0
+ * @remarks
+ * The validator checks for a top-level changelog heading, an `[Unreleased]`
+ * section, and optionally a dated entry for the requested version.
+ *
+ * @param changelogPath - Path to the changelog file.
+ * @param version - Version that must be present in the changelog.
+ * @param strict - Whether to require compare links and dated release headings.
+ * @param requireEntry - Whether the requested version must already have an entry.
+ * @returns The result of validating the changelog file.
+ * @example
+ * ```ts
+ * import { validateChangelog } from 'versionguard';
+ *
+ * const result = validateChangelog('CHANGELOG.md', '1.2.0', true, true);
+ * ```
+ */
+export declare function validateChangelog(changelogPath: string, version: string, strict?: boolean, requireEntry?: boolean): ChangelogValidationResult;
+/**
+ * Gets the most recent released version from a changelog.
+ *
+ * @public
+ * @since 0.1.0
+ * @remarks
+ * The `[Unreleased]` section is skipped so the first concrete version heading is
+ * treated as the latest release.
+ *
+ * @param changelogPath - Path to the changelog file.
+ * @returns The latest released version, or `null` when no release entry exists.
+ * @example
+ * ```ts
+ * import { getLatestVersion } from 'versionguard';
+ *
+ * const latest = getLatestVersion('CHANGELOG.md');
+ * ```
+ */
+export declare function getLatestVersion(changelogPath: string): string | null;
+/**
+ * Inserts a new version entry beneath the `[Unreleased]` section.
+ *
+ * @public
+ * @since 0.1.0
+ * @remarks
+ * If the changelog already contains the requested version, no changes are made.
+ * The inserted entry includes a starter `Added` subsection for follow-up edits.
+ *
+ * @param changelogPath - Path to the changelog file.
+ * @param version - Version to add.
+ * @param date - Release date to write in `YYYY-MM-DD` format.
+ * @example
+ * ```ts
+ * import { addVersionEntry } from 'versionguard';
+ *
+ * addVersionEntry('CHANGELOG.md', '1.2.0', '2026-03-21');
+ * ```
+ */
+export declare function addVersionEntry(changelogPath: string, version: string, date?: string): void;
+//# sourceMappingURL=changelog.d.ts.map

package/dist/changelog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changelog.d.ts","sourceRoot":"","sources":["../src/changelog.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC;;OAEG;IACH,KAAK,EAAE,OAAO,CAAC;IACf;;OAEG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;;OAEG;IACH,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,OAAc,EACtB,YAAY,GAAE,OAAc,GAC3B,yBAAyB,CAgD3B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQrE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,MAA8C,GACnD,IAAI,CAmBN"}