@codluv/versionguard 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,510 @@
+/**
+ * Shared public types for version parsing, validation, and configuration.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Supported versioning strategies.
+ *
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export type VersioningType = 'semver' | 'calver';
+/**
+ * Supported calendar version string layouts.
+ *
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export type CalVerFormat = 'YYYY.MM.DD' | 'YYYY.MM.PATCH' | 'YY.M.PATCH' | 'YYYY.0M.0D';
+/**
+ * Configures CalVer validation rules.
+ *
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export interface CalVerConfig {
+    /**
+     * Calendar format used when parsing and validating versions.
+     */
+    format: CalVerFormat;
+    /**
+     * Rejects versions that point to a future date.
+     *
+     * @defaultValue true
+     */
+    preventFutureDates: boolean;
+}
+/**
+ * Describes a search-and-replace pattern used during version synchronization.
+ *
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export interface SyncPattern {
+    /**
+     * Regular expression string used to locate a version value.
+     */
+    regex: string;
+    /**
+     * Replacement template applied when a match is updated.
+     */
+    template: string;
+}
+/**
+ * Configures files and patterns that should stay in sync with the canonical version.
+ *
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export interface SyncConfig {
+    /**
+     * File globs or paths that should be scanned for version updates.
+     */
+    files: string[];
+    /**
+     * Replacement patterns applied to matching files.
+     */
+    patterns: SyncPattern[];
+}
+/**
+ * Controls changelog validation behavior.
+ *
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export interface ChangelogConfig {
+    /**
+     * Enables changelog validation.
+     *
+     * @defaultValue false
+     */
+    enabled: boolean;
+    /**
+     * Path to the changelog file to inspect.
+     */
+    file: string;
+    /**
+     * Treats changelog problems as hard failures.
+     *
+     * @defaultValue false
+     */
+    strict: boolean;
+    /**
+     * Requires an entry for the current version.
+     *
+     * @defaultValue false
+     */
+    requireEntry: boolean;
+}
+/**
+ * Toggles each supported git hook integration.
+ *
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export interface GitHooksConfig {
+    /**
+     * Enables validation during the `pre-commit` hook.
+     *
+     * @defaultValue false
+     */
+    'pre-commit': boolean;
+    /**
+     * Enables validation during the `pre-push` hook.
+     *
+     * @defaultValue false
+     */
+    'pre-push': boolean;
+    /**
+     * Enables follow-up tasks after a tag is created.
+     *
+     * @defaultValue false
+     */
+    'post-tag': boolean;
+}
+/**
+ * Configures git-related enforcement.
+ *
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export interface GitConfig {
+    /**
+     * Hook toggles used by the CLI and validation workflow.
+     */
+    hooks: GitHooksConfig;
+    /**
+     * Fails validation when required hooks are missing.
+     *
+     * @defaultValue false
+     */
+    enforceHooks: boolean;
+}
+/**
+ * Configures the active versioning mode.
+ *
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export interface VersioningConfig {
+    /**
+     * Versioning strategy used for the project.
+     */
+    type: VersioningType;
+    /**
+     * CalVer-specific settings when `type` is `'calver'`.
+     *
+     * @defaultValue undefined
+     */
+    calver?: CalVerConfig;
+}
+/**
+ * Top-level configuration consumed by versionguard.
+ *
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export interface VersionGuardConfig {
+    /**
+     * Active versioning settings.
+     */
+    versioning: VersioningConfig;
+    /**
+     * Synchronization settings for mirrored version strings.
+     */
+    sync: SyncConfig;
+    /**
+     * Changelog validation settings.
+     */
+    changelog: ChangelogConfig;
+    /**
+     * Git enforcement settings.
+     */
+    git: GitConfig;
+    /**
+     * Files or patterns excluded from validation.
+     */
+    ignore: string[];
+}
+/**
+ * Parsed semantic version components.
+ *
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export interface SemVer {
+    /**
+     * Major version number.
+     */
+    major: number;
+    /**
+     * Minor version number.
+     */
+    minor: number;
+    /**
+     * Patch version number.
+     */
+    patch: number;
+    /**
+     * Ordered prerelease identifiers.
+     *
+     * @defaultValue []
+     */
+    prerelease: string[];
+    /**
+     * Ordered build metadata identifiers.
+     *
+     * @defaultValue []
+     */
+    build: string[];
+    /**
+     * Original version string.
+     */
+    raw: string;
+}
+/**
+ * Parsed calendar version components.
+ *
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export interface CalVer {
+    /**
+     * Four-digit year value.
+     */
+    year: number;
+    /**
+     * Month value from 1 through 12.
+     */
+    month: number;
+    /**
+     * Day-of-month value when the selected format includes a day token.
+     *
+     * @defaultValue undefined
+     */
+    day?: number;
+    /**
+     * Patch counter when the selected format includes a patch token.
+     *
+     * @defaultValue undefined
+     */
+    patch?: number;
+    /**
+     * Source format used to interpret the raw string.
+     */
+    format: CalVerFormat;
+    /**
+     * Original version string.
+     */
+    raw: string;
+}
+/**
+ * Parsed semantic version result wrapper.
+ *
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export interface ParsedSemVer {
+    /**
+     * Discriminator for semantic version results.
+     */
+    type: 'semver';
+    /**
+     * Parsed semantic version value.
+     */
+    version: SemVer;
+}
+/**
+ * Parsed calendar version result wrapper.
+ *
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export interface ParsedCalVer {
+    /**
+     * Discriminator for calendar version results.
+     */
+    type: 'calver';
+    /**
+     * Parsed calendar version value.
+     */
+    version: CalVer;
+}
+/**
+ * Union of supported parsed version payloads.
+ *
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export type ParsedVersion = ParsedSemVer | ParsedCalVer;
+/**
+ * Describes a single validation problem.
+ *
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export interface ValidationError {
+    /**
+     * Source file associated with the error when available.
+     *
+     * @defaultValue undefined
+     */
+    file?: string;
+    /**
+     * One-based source line associated with the error when available.
+     *
+     * @defaultValue undefined
+     */
+    line?: number;
+    /**
+     * Human-readable validation message.
+     */
+    message: string;
+    /**
+     * Severity of the reported problem.
+     */
+    severity: 'error' | 'warning';
+}
+/**
+ * Result returned by version parsing and validation helpers.
+ *
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export interface ValidationResult {
+    /**
+     * Indicates whether validation completed without errors.
+     */
+    valid: boolean;
+    /**
+     * Collected validation issues.
+     */
+    errors: ValidationError[];
+    /**
+     * Parsed version details when validation succeeds.
+     *
+     * @defaultValue undefined
+     */
+    version?: ParsedVersion;
+}
+/**
+ * Describes a single in-file version replacement.
+ *
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export interface SyncChange {
+    /**
+     * One-based line number where the replacement occurred.
+     */
+    line: number;
+    /**
+     * Previously matched value.
+     */
+    oldValue: string;
+    /**
+     * Replacement value written to the file.
+     */
+    newValue: string;
+}
+/**
+ * Reports the result of synchronizing a single file.
+ *
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export interface SyncResult {
+    /**
+     * File that was inspected or updated.
+     */
+    file: string;
+    /**
+     * Indicates whether the file content changed.
+     */
+    updated: boolean;
+    /**
+     * Detailed replacements applied within the file.
+     */
+    changes: SyncChange[];
+}
+/**
+ * Reports a discovered version mismatch.
+ *
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export interface VersionMismatch {
+    /**
+     * File containing the mismatched value.
+     */
+    file: string;
+    /**
+     * One-based line number of the mismatch.
+     */
+    line: number;
+    /**
+     * Version string found in the file.
+     */
+    found: string;
+}
+/**
+ * Combined result from a full project validation run.
+ *
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export interface FullValidationResult {
+    /**
+     * Indicates whether all checks passed.
+     */
+    valid: boolean;
+    /**
+     * Canonical version string used for validation.
+     */
+    version: string;
+    /**
+     * Indicates whether the root version string is valid.
+     */
+    versionValid: boolean;
+    /**
+     * Indicates whether synchronized files are in sync.
+     */
+    syncValid: boolean;
+    /**
+     * Indicates whether changelog checks passed.
+     */
+    changelogValid: boolean;
+    /**
+     * Human-readable validation failures collected during the run.
+     */
+    errors: string[];
+}
+/**
+ * Reports whether a project is ready to pass VersionGuard checks.
+ *
+ * @packageDocumentation
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export interface DoctorReport {
+    /**
+     * Indicates whether all doctor checks passed.
+     */
+    ready: boolean;
+    /**
+     * Package version resolved from `package.json`.
+     */
+    version: string;
+    /**
+     * Indicates whether the package version matches the configured scheme.
+     */
+    versionValid: boolean;
+    /**
+     * Indicates whether synced files match the package version.
+     */
+    syncValid: boolean;
+    /**
+     * Indicates whether changelog validation passed.
+     */
+    changelogValid: boolean;
+    /**
+     * Indicates whether the current working directory is inside a Git repository.
+     */
+    gitRepository: boolean;
+    /**
+     * Indicates whether VersionGuard-managed Git hooks are installed.
+     */
+    hooksInstalled: boolean;
+    /**
+     * Indicates whether `git status --porcelain` reports a clean worktree.
+     */
+    worktreeClean: boolean;
+    /**
+     * Human-readable validation and readiness errors.
+     */
+    errors: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,eAAe,GAAG,YAAY,GAAG,YAAY,CAAC;AAExF;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,MAAM,EAAE,YAAY,CAAC;IAErB;;;;OAIG;IACH,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAEhB;;OAEG;IACH,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;OAIG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;;;OAIG;IACH,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,YAAY,EAAE,OAAO,CAAC;IAEtB;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC;IAEpB;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB;;OAEG;IACH,KAAK,EAAE,cAAc,CAAC;IAEtB;;;;OAIG;IACH,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,IAAI,EAAE,cAAc,CAAC;IAErB;;;;OAIG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,UAAU,EAAE,gBAAgB,CAAC;IAE7B;;OAEG;IACH,IAAI,EAAE,UAAU,CAAC;IAEjB;;OAEG;IACH,SAAS,EAAE,eAAe,CAAC;IAE3B;;OAEG;IACH,GAAG,EAAE,SAAS,CAAC;IAEf;;OAEG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,MAAM;IACrB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,UAAU,EAAE,MAAM,EAAE,CAAC;IAErB;;;;OAIG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAEhB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;GAMG;AACH,MAAM,WAAW,MAAM;IACrB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,MAAM,EAAE,YAAY,CAAC;IAErB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,IAAI,EAAE,QAAQ,CAAC;IAEf;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,IAAI,EAAE,QAAQ,CAAC;IAEf;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,YAAY,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,KAAK,EAAE,OAAO,CAAC;IAEf;;OAEG;IACH,MAAM,EAAE,eAAe,EAAE,CAAC;IAE1B;;;;OAIG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,KAAK,EAAE,OAAO,CAAC;IAEf;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,YAAY,EAAE,OAAO,CAAC;IAEtB;;OAEG;IACH,SAAS,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,cAAc,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,KAAK,EAAE,OAAO,CAAC;IAEf;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,YAAY,EAAE,OAAO,CAAC;IAEtB;;OAEG;IACH,SAAS,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,cAAc,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,aAAa,EAAE,OAAO,CAAC;IAEvB;;OAEG;IACH,cAAc,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,aAAa,EAAE,OAAO,CAAC;IAEvB;;OAEG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB"}

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@codluv/versionguard",
+  "version": "0.1.0",
+  "description": "Strict versioning enforcement for SemVer and CalVer with git hooks, changelog validation, and file sync from package.json",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "versionguard": "dist/cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kryptobaseddev/versionguard.git"
+  },
+  "homepage": "https://github.com/kryptobaseddev/versionguard#readme",
+  "bugs": {
+    "url": "https://github.com/kryptobaseddev/versionguard/issues"
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "dev": "vite build --watch",
+    "typecheck": "tsc --noEmit",
+    "forge:check": "forge-ts check",
+    "forge:test": "forge-ts test",
+    "forge:build": "forge-ts build",
+    "forge:docs:init": "forge-ts init docs",
+    "forge:doctor": "forge-ts doctor",
+    "lint": "npm run lint:biome && npm run lint:eslint",
+    "lint:biome": "biome check .",
+    "lint:eslint": "eslint .",
+    "format": "biome format --write .",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest",
+    "prepare": "npm run build",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "npm run build && changeset publish"
+  },
+  "keywords": [
+    "semver",
+    "calver",
+    "versioning",
+    "git-hooks",
+    "changelog",
+    "version-sync",
+    "release",
+    "version-guard",
+    "package-version",
+    "keep-a-changelog"
+  ],
+  "author": "kryptobaseddev",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^12.0.0",
+    "glob": "^10.3.0",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.2.4",
+    "@changesets/changelog-github": "^0.6.0",
+    "@changesets/cli": "^2.30.0",
+    "@eslint/js": "^9.37.0",
+    "@forge-ts/cli": "0.19.4",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^24.6.0",
+    "@vitest/coverage-v8": "^4.0.7",
+    "eslint": "^9.37.0",
+    "husky": "^9.1.7",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.1",
+    "vite": "^7.1.7",
+    "vitest": "^4.0.7"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "dist/"
+  ]
+}