@codluv/versionguard 0.1.0

package/dist/semver.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Semantic version parsing, validation, comparison, and increment helpers.
+ *
+ * @packageDocumentation
+ */
+import type { SemVer, ValidationResult } from './types';
+/**
+ * Parses a semantic version string.
+ *
+ * @remarks
+ * This helper enforces the standard SemVer structure and returns `null` when the input does not
+ * match. It preserves prerelease and build identifiers as ordered string segments.
+ *
+ * @param version - Version string to parse.
+ * @returns Parsed semantic version components, or `null` when the input is invalid.
+ *
+ * @example
+ * ```ts
+ * import { parse } from 'versionguard';
+ *
+ * parse('1.2.3-alpha.1+build.5')?.prerelease;
+ * // => ['alpha', '1']
+ * ```
+ *
+ * @public
+ * @since 0.1.0
+ */
+export declare function parse(version: string): SemVer | null;
+/**
+ * Validates that a string is a supported semantic version.
+ *
+ * @remarks
+ * When validation fails, the result includes targeted structural errors for common cases such as
+ * leading `v` prefixes and numeric segments with leading zeroes.
+ *
+ * @param version - Version string to validate.
+ * @returns A validation result containing any detected errors and the parsed version on success.
+ *
+ * @example
+ * ```ts
+ * import { validate } from 'versionguard';
+ *
+ * validate('1.2.3').valid;
+ * // => true
+ * ```
+ *
+ * @public
+ * @since 0.1.0
+ */
+export declare function validate(version: string): ValidationResult;
+/**
+ * Compares two semantic version strings.
+ *
+ * @remarks
+ * Comparison follows SemVer precedence rules, including special handling for prerelease
+ * identifiers and ignoring build metadata.
+ *
+ * @param a - Left-hand version string.
+ * @param b - Right-hand version string.
+ * @returns `1` when `a` is greater, `-1` when `b` is greater, or `0` when they are equal.
+ *
+ * @example
+ * ```ts
+ * import { compare } from 'versionguard';
+ *
+ * compare('1.2.3', '1.2.3-alpha.1');
+ * // => 1
+ * ```
+ *
+ * @public
+ * @since 0.1.0
+ */
+export declare function compare(a: string, b: string): number;
+/**
+ * Checks whether one semantic version is greater than another.
+ *
+ * @remarks
+ * This is a convenience wrapper around {@link compare} for callers that only need a boolean.
+ *
+ * @param a - Left-hand version string.
+ * @param b - Right-hand version string.
+ * @returns `true` when `a` has higher precedence than `b`.
+ *
+ * @example
+ * ```ts
+ * import { gt } from 'versionguard';
+ *
+ * gt('1.2.4', '1.2.3');
+ * // => true
+ * ```
+ *
+ * @see {@link compare} for full precedence ordering.
+ * @public
+ * @since 0.1.0
+ */
+export declare function gt(a: string, b: string): boolean;
+/**
+ * Checks whether one semantic version is less than another.
+ *
+ * @remarks
+ * This is a convenience wrapper around {@link compare} for callers that only need a boolean.
+ *
+ * @param a - Left-hand version string.
+ * @param b - Right-hand version string.
+ * @returns `true` when `a` has lower precedence than `b`.
+ *
+ * @example
+ * ```ts
+ * import { lt } from 'versionguard';
+ *
+ * lt('1.2.3-alpha.1', '1.2.3');
+ * // => true
+ * ```
+ *
+ * @see {@link compare} for full precedence ordering.
+ * @public
+ * @since 0.1.0
+ */
+export declare function lt(a: string, b: string): boolean;
+/**
+ * Checks whether two semantic versions are equal in precedence.
+ *
+ * @remarks
+ * This is a convenience wrapper around {@link compare}. Build metadata is ignored because
+ * precedence comparisons in SemVer do not consider it.
+ *
+ * @param a - Left-hand version string.
+ * @param b - Right-hand version string.
+ * @returns `true` when both versions compare as equal.
+ *
+ * @example
+ * ```ts
+ * import { eq } from 'versionguard';
+ *
+ * eq('1.2.3', '1.2.3');
+ * // => true
+ * ```
+ *
+ * @see {@link compare} for full precedence ordering.
+ * @public
+ * @since 0.1.0
+ */
+export declare function eq(a: string, b: string): boolean;
+/**
+ * Increments a semantic version string by release type.
+ *
+ * @remarks
+ * Incrementing `major` or `minor` resets lower-order numeric segments. When a prerelease label is
+ * provided, it is appended to the newly generated version.
+ *
+ * @param version - Current semantic version string.
+ * @param release - Segment to increment.
+ * @param prerelease - Optional prerelease suffix to append to the next version.
+ * @returns The incremented semantic version string.
+ *
+ * @example
+ * ```ts
+ * import { increment } from 'versionguard';
+ *
+ * increment('1.2.3', 'minor', 'beta.1');
+ * // => '1.3.0-beta.1'
+ * ```
+ *
+ * @public
+ * @since 0.1.0
+ */
+export declare function increment(version: string, release: 'major' | 'minor' | 'patch', prerelease?: string): string;
+/**
+ * Formats a parsed semantic version object.
+ *
+ * @remarks
+ * Prerelease and build metadata segments are only included when their arrays contain values.
+ *
+ * @param version - Parsed semantic version to serialize.
+ * @returns The normalized semantic version string.
+ *
+ * @example
+ * ```ts
+ * import { format } from 'versionguard';
+ *
+ * const version = { major: 1, minor: 2, patch: 3, prerelease: ['rc', '1'], build: ['build', '5'], raw: '1.2.3-rc.1+build.5' };
+ *
+ * format(version);
+ * // => '1.2.3-rc.1+build.5'
+ * ```
+ *
+ * @public
+ * @since 0.1.0
+ */
+export declare function format(version: SemVer): string;
+//# sourceMappingURL=semver.d.ts.map

package/dist/semver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semver.d.ts","sourceRoot":"","sources":["../src/semver.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAmB,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAKzE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAepD;AA6CD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAe1D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CA8DpD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,EACpC,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAgBR;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAY9C"}

package/dist/sync.d.ts

@@ -0,0 +1,71 @@
+import type { SyncConfig, SyncPattern, SyncResult, VersionMismatch } from './types';
+/**
+ * Synchronizes configured files to a single version string.
+ *
+ * @public
+ * @since 0.1.0
+ * @remarks
+ * File globs are resolved relative to `cwd`, then each matched file is updated
+ * with the configured replacement patterns.
+ *
+ * @param version - Version string to write into matching files.
+ * @param config - Sync configuration describing files and replacement patterns.
+ * @param cwd - Project directory used to resolve file globs.
+ * @returns A sync result for each resolved file.
+ * @example
+ * ```ts
+ * import { getDefaultConfig, syncVersion } from 'versionguard';
+ *
+ * const results = syncVersion('1.2.3', getDefaultConfig().sync, process.cwd());
+ * ```
+ */
+export declare function syncVersion(version: string, config: SyncConfig, cwd?: string): SyncResult[];
+/**
+ * Synchronizes a single file to a target version.
+ *
+ * @public
+ * @since 0.1.0
+ * @remarks
+ * Each configured regex is applied globally, and `{{version}}` placeholders in
+ * templates are replaced with the supplied version.
+ *
+ * @param filePath - Absolute or relative path to the file to update.
+ * @param version - Version string to write.
+ * @param patterns - Replacement patterns to apply.
+ * @returns A result describing whether the file changed and what changed.
+ * @example
+ * ```ts
+ * import { getDefaultConfig, syncFile } from 'versionguard';
+ *
+ * const result = syncFile('README.md', '1.2.3', getDefaultConfig().sync.patterns);
+ * ```
+ */
+export declare function syncFile(filePath: string, version: string, patterns: SyncPattern[]): SyncResult;
+/**
+ * Checks configured files for hardcoded version mismatches.
+ *
+ * @public
+ * @since 0.1.0
+ * @remarks
+ * Files matching the sync config are scanned without modification, and every
+ * captured version that differs from `expectedVersion` is returned.
+ *
+ * @param expectedVersion - Version all matching entries should use.
+ * @param config - Sync configuration describing files and replacement patterns.
+ * @param ignorePatterns - Glob patterns to exclude while scanning.
+ * @param cwd - Project directory used to resolve file globs.
+ * @returns A list of detected version mismatches.
+ * @example
+ * ```ts
+ * import { checkHardcodedVersions, getDefaultConfig } from 'versionguard';
+ *
+ * const mismatches = checkHardcodedVersions(
+ *   '1.2.3',
+ *   getDefaultConfig().sync,
+ *   getDefaultConfig().ignore,
+ *   process.cwd(),
+ * );
+ * ```
+ */
+export declare function checkHardcodedVersions(expectedVersion: string, config: SyncConfig, ignorePatterns: string[], cwd?: string): VersionMismatch[];
+//# sourceMappingURL=sync.d.ts.map

package/dist/sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AA8BpF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,UAAU,EAClB,GAAG,GAAE,MAAsB,GAC1B,UAAU,EAAE,CAId;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,UAAU,CAyC/F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,sBAAsB,CACpC,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,UAAU,EAClB,cAAc,EAAE,MAAM,EAAE,EACxB,GAAG,GAAE,MAAsB,GAC1B,eAAe,EAAE,CA0BnB"}

package/dist/tag/index.d.ts

@@ -0,0 +1,180 @@
+import type { VersionGuardConfig } from '../types';
+/**
+ * Tag management helpers for reading, validating, and creating release tags.
+ *
+ * @packageDocumentation
+ * @public
+ */
+/**
+ * Tag entry point exports for release-tag management helpers.
+ *
+ * @packageDocumentation
+ * @public
+ * @since 0.1.0
+ * @forgeIgnore E020
+ */
+export interface TagInfo {
+    /**
+     * Full git tag name, including any prefix such as `v`.
+     */
+    name: string;
+    /**
+     * Normalized version string derived from the tag name.
+     */
+    version: string;
+    /**
+     * Annotated tag message when one is available.
+     *
+     * @defaultValue `undefined`
+     */
+    message?: string;
+    /**
+     * Timestamp associated with the tag lookup result.
+     */
+    date: Date;
+}
+/**
+ * Returns the most recent reachable git tag for a repository.
+ *
+ * @public
+ * @since 0.1.0
+ * @remarks
+ * This helper reads the most recent annotated or lightweight tag that `git describe`
+ * can resolve from the current HEAD. It returns `null` when no tags are available
+ * or when git metadata cannot be read.
+ *
+ * @param cwd - Repository directory to inspect.
+ * @returns The latest tag details, or `null` when no tag can be resolved.
+ *
+ * @example
+ * ```typescript
+ * const latestTag = getLatestTag(process.cwd());
+ *
+ * if (latestTag) {
+ *   console.log(latestTag.version);
+ * }
+ * ```
+ */
+export declare function getLatestTag(cwd?: string): TagInfo | null;
+/**
+ * Lists all tags in a repository.
+ *
+ * @public
+ * @since 0.1.0
+ * @remarks
+ * This helper returns tag names in the order provided by `git tag --list`. The
+ * `date` field is populated with the current time because the implementation does
+ * not perform per-tag date lookups.
+ *
+ * @param cwd - Repository directory to inspect.
+ * @returns A list of discovered tags, or an empty array when tags cannot be read.
+ *
+ * @example
+ * ```typescript
+ * const tags = getAllTags(process.cwd());
+ * console.log(tags.map((tag) => tag.name));
+ * ```
+ */
+export declare function getAllTags(cwd?: string): TagInfo[];
+/**
+ * Creates a release tag and optionally fixes version state first.
+ *
+ * @public
+ * @since 0.1.0
+ * @remarks
+ * When `autoFix` is enabled, this helper updates versioned files, stages the
+ * changes, and creates a release commit before creating the annotated tag. It
+ * returns a structured result instead of throwing for most expected failures.
+ *
+ * @param version - Version to embed in the new tag name.
+ * @param message - Custom annotated tag message.
+ * @param autoFix - Whether to auto-fix version mismatches before tagging.
+ * @param config - Loaded VersionGuard configuration used for validation and fixes.
+ * @param cwd - Repository directory where git commands should run.
+ * @returns The tagging outcome and any actions performed along the way.
+ *
+ * @example
+ * ```typescript
+ * const result = createTag('1.2.3', 'Release 1.2.3', true, config, process.cwd());
+ *
+ * if (!result.success) {
+ *   console.error(result.message);
+ * }
+ * ```
+ */
+export declare function createTag(version: string, message?: string, autoFix?: boolean, config?: VersionGuardConfig, cwd?: string): {
+    success: boolean;
+    message: string;
+    actions: string[];
+};
+/**
+ * Runs post-tag validation and sync checks.
+ *
+ * @public
+ * @since 0.1.0
+ * @remarks
+ * This helper is intended for the `post-tag` git hook flow. It validates the
+ * latest tag against the configured versioning rules and reports any required
+ * follow-up actions without mutating git history.
+ *
+ * @param config - Loaded VersionGuard configuration used during validation.
+ * @param cwd - Repository directory where validation should run.
+ * @returns The post-tag workflow result and any follow-up actions.
+ *
+ * @example
+ * ```typescript
+ * const result = handlePostTag(config, process.cwd());
+ * console.log(result.success);
+ * ```
+ */
+export declare function handlePostTag(config: VersionGuardConfig, cwd?: string): {
+    success: boolean;
+    message: string;
+    actions: string[];
+};
+/**
+ * Validates that a local tag is safe to push to the default remote.
+ *
+ * @public
+ * @since 0.1.0
+ * @remarks
+ * This helper checks that the tag exists locally and, when the tag also exists on
+ * `origin`, verifies that both references point to the same commit.
+ *
+ * @param tagName - Name of the tag to validate.
+ * @param cwd - Repository directory where git commands should run.
+ * @returns A validation result with an optional suggested fix command.
+ *
+ * @example
+ * ```typescript
+ * const result = validateTagForPush('v1.2.3', process.cwd());
+ * console.log(result.valid);
+ * ```
+ */
+export declare function validateTagForPush(tagName: string, cwd?: string): {
+    valid: boolean;
+    message: string;
+    fix?: string;
+};
+/**
+ * Suggests an annotated tag message from changelog content.
+ *
+ * @public
+ * @since 0.1.0
+ * @remarks
+ * When a matching changelog entry exists, this helper uses the first bullet point
+ * as a concise release summary. It falls back to a generic `Release {version}`
+ * message when no changelog context is available.
+ *
+ * @param version - Version that the tag will represent.
+ * @param cwd - Repository directory containing the changelog file.
+ * @returns A suggested annotated tag message.
+ *
+ * @example
+ * ```typescript
+ * const message = suggestTagMessage('1.2.3', process.cwd());
+ * console.log(message);
+ * ```
+ */
+export declare function suggestTagMessage(version: string, cwd?: string): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/tag/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tag/index.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnD;;;;;GAKG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,OAAO;IACtB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,IAAI,EAAE,IAAI,CAAC;CACZ;AAcD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,GAAG,GAAE,MAAsB,GAAG,OAAO,GAAG,IAAI,CAoBxE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAsB,GAAG,OAAO,EAAE,CAgBjE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,EAChB,OAAO,GAAE,OAAc,EACvB,MAAM,CAAC,EAAE,kBAAkB,EAC3B,GAAG,GAAE,MAAsB,GAC1B;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CA0E1D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,kBAAkB,EAC1B,GAAG,GAAE,MAAsB,GAC1B;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAwD1D;AA6DD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,GAAG,GAAE,MAAsB,GAC1B;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CA6BnD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,MAAsB,GAAG,MAAM,CAwBtF"}